From 8a8af25e517c37e0270c46c9028e140b04aba288 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sat, 19 Sep 2026 00:51:52 +0800 Subject: [PATCH 1/6] feat(email): align platform email with authoritative gateway design --- docs/guide/email.md | 134 +- docs/guide/platform-administration.md | 10 +- docs/guide/self-hosted-platform.md | 24 +- docs/reference/cli.md | 20 +- packages/deploy-core/src/index.ts | 2 + packages/deploy-core/src/validate.ts | 3 + .../deploy-core/test/unit/validate.test.ts | 11 + packages/platform/README.md | 2 +- packages/platform/package.json | 4 + packages/platform/scripts/build-runtime.mjs | 10 +- packages/platform/src/email-protocol.ts | 462 ++ packages/platform/src/installer.ts | 27 +- packages/platform/src/manifest.ts | 29 +- packages/platform/src/worker-config.ts | 43 +- .../platform/test/unit/email-protocol.test.ts | 106 + .../platform/test/unit/worker-config.test.ts | 65 +- packages/platform/vite.config.ts | 2 +- packages/void/package.json | 5 + packages/void/skills/void/SKILL.md | 2 + packages/void/src/cli/client.ts | 82 +- packages/void/src/cli/deploy.ts | 2 + packages/void/src/cli/email-args.ts | 13 +- packages/void/src/cli/email.ts | 326 +- packages/void/src/cli/help.ts | 28 +- packages/void/src/cli/package.ts | 4 + packages/void/src/cli/platform-installer.ts | 73 +- packages/void/src/cli/platform-lifecycle.ts | 9 + packages/void/src/cli/platform-management.ts | 14 + packages/void/src/cli/platform-plan.ts | 45 +- packages/void/src/router/compile.ts | 36 +- packages/void/src/runtime/email-protocol.ts | 7 + packages/void/src/runtime/email.ts | 111 +- packages/void/src/runtime/email/inbound.ts | 37 +- packages/void/src/runtime/email/mime.ts | 16 +- packages/void/src/runtime/email/types.ts | 41 +- packages/void/test/unit/cli-help.test.ts | 5 +- .../void/test/unit/email-cli-disallow.test.ts | 4 +- .../void/test/unit/email-cli-domain.test.ts | 1335 +---- .../void/test/unit/email-dev-inbox.test.ts | 25 +- .../void/test/unit/email-domain-args.test.ts | 4 +- packages/void/test/unit/email-inbound.test.ts | 59 +- packages/void/test/unit/email-mime.test.ts | 114 +- packages/void/test/unit/email-send.test.ts | 96 +- packages/void/test/unit/package.test.ts | 12 + .../void/test/unit/platform-installer.test.ts | 410 +- packages/void/test/unit/platform-plan.test.ts | 59 +- .../void/test/unit/platform-recovery.test.ts | 7 + .../void/test/unit/platform-rollback.test.ts | 50 + .../void/test/unit/platform-runtime.test.ts | 11 + packages/void/vite.config.ts | 1 + platform/README.md | 43 +- .../meta/design-docs/0078-email-cf-native.md | 1426 ++--- platform/meta/design-docs/README.md | 2 +- platform/meta/operations.md | 33 +- platform/package.json | 6 +- .../api/drizzle/0047_email_gateway.sql | 208 + .../packages/api/drizzle/compatibility.json | 4 + .../api/drizzle/meta/0047_snapshot.json | 5220 +++++++++++++++++ .../packages/api/drizzle/meta/_journal.json | 7 + .../api/src/admin/platform-workers.ts | 15 +- .../packages/api/src/admin/routes/email.tsx | 474 +- platform/packages/api/src/auth/profile.ts | 2 + platform/packages/api/src/db.ts | 82 +- .../api/src/email/admission-schema.ts | 125 + platform/packages/api/src/email/admission.ts | 911 +++ .../packages/api/src/email/cf-customer.ts | 105 +- .../api/src/email/connection-schema.ts | 231 + .../api/src/email/connection-service.ts | 2107 +++++++ .../packages/api/src/email/domain-service.ts | 2232 +------ .../api/src/email/ingress-resolution.ts | 311 + .../packages/api/src/email/internal-body.ts | 66 + .../packages/api/src/email/relay-worker.ts | 74 +- platform/packages/api/src/email/settings.ts | 142 +- platform/packages/api/src/env.ts | 4 + platform/packages/api/src/index.ts | 33 + .../packages/api/src/operator/email-routes.ts | 132 +- .../packages/api/src/provisioning/cleanup.ts | 64 +- .../api/src/provisioning/provision.ts | 12 + .../packages/api/src/reserved-bindings.ts | 1 + platform/packages/api/src/routes/deploy.ts | 1 + platform/packages/api/src/routes/email.ts | 232 +- .../api/src/routes/internal-email-actions.ts | 268 + .../packages/api/src/routes/internal-email.ts | 208 +- platform/packages/api/src/schema.ts | 4 + .../api/test/integration/admin-email.test.ts | 906 +-- .../api/test/integration/api-delete.test.ts | 70 +- .../integration/api-email-domains.test.ts | 3195 +--------- .../api/test/integration/api-email.test.ts | 282 +- .../test/integration/email-admission.test.ts | 340 ++ .../integration/email-connections.test.ts | 644 ++ .../test/integration/email-domain-cf-stub.ts | 100 + .../packages/api/test/integration/helpers.ts | 16 + .../test/integration/operator-audit.test.ts | 3 + .../operator-email-domains.test.ts | 722 +-- .../test/integration/operator-email.test.ts | 140 +- .../integration/operator-operations.test.ts | 5 +- .../api/test/unit/email-cf-customer.test.ts | 6 +- .../api/test/unit/email-migration.test.ts | 70 + .../api/test/unit/email-relay-engine.test.ts | 14 + .../api/test/unit/email-relay-worker.test.ts | 124 +- .../unit/platform-deployment-manifest.test.ts | 1 + .../test/unit/platform-worker-config.test.ts | 6 + .../api/test/unit/reserved-bindings.test.ts | 34 + platform/packages/email-gateway/package.json | 21 + platform/packages/email-gateway/src/index.ts | 516 ++ .../email-gateway/src/tenant-dispatch.ts | 77 + .../email-gateway/test/unit/gateway.test.ts | 286 + platform/packages/email-gateway/tsconfig.json | 14 + .../packages/email-gateway/wrangler.jsonc | 32 + platform/packages/proxy/package.json | 1 + .../packages/proxy/src/email-admission.ts | 249 + platform/packages/proxy/src/email-lease.ts | 52 +- platform/packages/proxy/src/email-router.ts | 762 ++- platform/packages/proxy/src/email.ts | 711 ++- platform/packages/proxy/src/index.ts | 205 +- .../test/unit/email-admission-send.test.ts | 152 + .../proxy/test/unit/email-admission.test.ts | 97 + .../test/unit/email-custom-domain.test.ts | 239 +- .../proxy/test/unit/email-relay.test.ts | 878 +-- .../proxy/test/unit/email-router.test.ts | 1453 +---- .../packages/proxy/test/unit/email.test.ts | 1136 +--- pnpm-lock.yaml | 48 +- 122 files changed, 17897 insertions(+), 14492 deletions(-) create mode 100644 packages/platform/src/email-protocol.ts create mode 100644 packages/platform/test/unit/email-protocol.test.ts create mode 100644 packages/void/src/runtime/email-protocol.ts create mode 100644 platform/packages/api/drizzle/0047_email_gateway.sql create mode 100644 platform/packages/api/drizzle/meta/0047_snapshot.json create mode 100644 platform/packages/api/src/email/admission-schema.ts create mode 100644 platform/packages/api/src/email/admission.ts create mode 100644 platform/packages/api/src/email/connection-schema.ts create mode 100644 platform/packages/api/src/email/connection-service.ts create mode 100644 platform/packages/api/src/email/ingress-resolution.ts create mode 100644 platform/packages/api/src/email/internal-body.ts create mode 100644 platform/packages/api/src/routes/internal-email-actions.ts create mode 100644 platform/packages/api/test/integration/email-admission.test.ts create mode 100644 platform/packages/api/test/integration/email-connections.test.ts create mode 100644 platform/packages/api/test/unit/email-migration.test.ts create mode 100644 platform/packages/email-gateway/package.json create mode 100644 platform/packages/email-gateway/src/index.ts create mode 100644 platform/packages/email-gateway/src/tenant-dispatch.ts create mode 100644 platform/packages/email-gateway/test/unit/gateway.test.ts create mode 100644 platform/packages/email-gateway/tsconfig.json create mode 100644 platform/packages/email-gateway/wrangler.jsonc create mode 100644 platform/packages/proxy/src/email-admission.ts create mode 100644 platform/packages/proxy/test/unit/email-admission-send.test.ts create mode 100644 platform/packages/proxy/test/unit/email-admission.test.ts diff --git a/docs/guide/email.md b/docs/guide/email.md index 2993f97b5..3d78361b4 100644 --- a/docs/guide/email.md +++ b/docs/guide/email.md @@ -77,46 +77,40 @@ The shared sender lives on the platform's `mail.void.cloud` zone. To send — an void email domain add acme.com ``` -`add` needs one credential for the zone and offers two ways to grant it. The default opens Cloudflare's hosted consent page for an OAuth grant — one Allow click; the page names Wrangler, whose OAuth client Void borrows for it. Pressing Enter at any point, or any failure of the consent flow, switches to the fallback: a three-click template link that creates a scoped API token, which the CLI watches for on the clipboard or takes as a masked paste. Either credential is POSTed to the platform once and stored there, encrypted for the project — nothing is kept on your machine. +`add` opens a Cloudflare API-token template. Restrict the token to the selected account and mail zone before creating it; Workers Scripts permission applies across that account. The CLI accepts a masked paste or a newly copied token and asks you to confirm those restrictions. The platform encrypts the credential for the zone connection, so projects sharing that zone do not need separate ingress Workers. -**Where the mail lives.** Void never enables routing over live mail: when `acme.com` already carries MX records, the CLI proposes `mail.acme.com` (`[change with --subdomain]`); the apex is used only when it carries no MX records. `--subdomain ` overrides the proposal outright. +When an apex already receives mail, the CLI proposes `mail.`. Use `--subdomain ` to choose another mail subdomain. Void refuses to replace a foreign enabled catch-all. A domain belongs to one project; multiple exact domains can share a zone, and a project can register more than one domain. -**The pending state.** Enabling Email Routing on a subdomain is the one step with no API path, so when it is the step that remains, `add` prints it — Cloudflare dashboard → Email Routing → acme.com → Settings → Subdomains → add the subdomain — and the row sits at `pending`. Poll with: +Setup returns an operation ID. If your connection drops, the platform keeps the recorded operation and the CLI checks that operation's status. An uncertain Cloudflare write stops conflicting changes until its outcome can be established. -```sh -void email domain status acme.com -``` - -Once public MX on the domain names Cloudflare, the row flips itself to `active` — no second command. `status` also re-probes the stored credential and the relay worker on every call, so it doubles as the drift report. - -**When a row is not active.** `failed` names the step that failed; fix it and re-run `void email domain add acme.com` — adding again replaces the credential and retries, and the routing rules stay. `token_revoked` / `token_expired` mean the stored credential died at Cloudflare; re-run `add` with a fresh grant or token — rules and the relay stay. - -Two upkeep verbs: +`void email domain status ` reports three independent results: -- `void email domain sync acme.com` redeploys the relay at the current version and rotates its secret — the answer when `status` reports the relay missing or drifted. -- `void email domain remove acme.com` deletes the platform row, the stored credential, and the relay secret. Cloudflare-side cleanup is best-effort; anything that could not be finished is named so you can delete it by hand. +- **Inbound**: whether mail can reach the project's handlers. +- **Outbound**: whether sending is ready, restricted to verified destinations, pending, or blocked. +- **Management**: whether the stored Cloudflare credential can manage the connection. -Two rules bound registrations: one live email domain per Cloudflare zone (a second `add` on the same zone is refused until you `remove` the first), and one project per domain (a domain registered to another project is refused). +Use `void email domain sync ` to reconcile setup and refresh readiness. Sync does not rotate the connection secret. Use `void email domain rotate-secret ` for an explicit rotation; it applies to all domains sharing that zone connection and verifies the deployed secret before completing. If a dashboard or credential step is required, the status names it. Removing a domain disables its assignment; zone resources used by another domain remain in place, and unfinished cleanup stays recorded for reconciliation. -Sends from a registered domain skip the verified-recipient allowlist — the domain's own Email Sending onboarding replaces it — while platform quota and abuse controls still apply. Inbound needs nothing further: once the domain is `active`, mail to any address on it reaches your `email/` handlers. +Once inbound is ready, mail to any address on that domain reaches your `email/` handlers. Sending to arbitrary recipients also needs outbound readiness; a domain limited to verified destinations still requires recipient verification. Platform quotas and suspension apply to both shared and custom senders. -**On a platform your administrator runs.** Some platforms register email domains for their projects centrally — typically a company installation whose users have no Cloudflare account. There, `void email domain add` opens no consent page; it prints the command to ask your administrator for and stops — unless your project registered that domain itself before the switch, which `add` still renews as before. `void email domain list` and `status` work as usual on such a domain; `status` names the administrator's command for any step you cannot take, and `sync` and `remove` point you at the administrator too. The administrator may also have widened who the shared sender reaches, so `void email allow` can be unnecessary for colleagues; `void email destinations` still lists what your project verified itself. +On an administrator-managed platform, `add` prints the administrator command for new domains. Existing owner-managed connections remain available to their owner. Your administrator may permit shared-sender mail to specific recipient domains or any recipient; destinations on the platform's shared mail domain still require explicit verification. ## Options -| Option | Type | Notes | -| ------------- | ---------------------------- | ---------------------------------------------------------------- | -| `from` | `string \| { email, name? }` | Optional. Pinned to the project sender — see below. | -| `to` | `Address \| Address[]` | Required. One or more recipients. | -| `subject` | `string` | Required. UTF-8 supported (encoded as RFC 2047). | -| `text` | `string` | At least one of `text` / `html` is required. | -| `html` | `string` | Sent as `multipart/alternative` if both are provided. | -| `replyTo` | `Address` | Optional `Reply-To` header. | -| `cc`, `bcc` | `Address \| Address[]` | Optional. Each recipient is sent its own message envelope. | -| `headers` | `Record` | Custom headers; reserved headers (From, Date, etc.) are ignored. | -| `attachments` | `Attachment[]` | See [Attachments](#attachments). | - -At most 100 recipients across `to`, `cc` and `bcc` per call. Each address is checked with [`email-validator`](https://www.npmjs.com/package/email-validator): an ASCII dot-atom local part (before the `@`) of at most 64 characters — no whitespace, control character or RFC 5322 special, no leading, trailing or doubled dot, and no quoted local part — and a dotted domain of ASCII labels (at most 63 characters each) whose TLD starts with a letter and is at least 2 characters, so `user@localhost` is refused and an IDN domain must be given as punycode (`xn--…`); at most 254 characters in total (RFC 5321: a 256-octet forward-path `` and a 64-octet local part are the longest every receiver must accept). The address itself carries no display-name syntax; a display name goes around it (`"Name "` or `{ email, name }`). All of these are checked before anything is built and return `INVALID_TO` (`INVALID_FROM` for `from`; `MIME_ERROR` for `cc`, `bcc` and `replyTo`). The platform's inbound router applies the same package to `forward()` and `reply()` addresses, so nothing a handler records is dropped there for its shape. Custom header names must be RFC 5322 field names (printable ASCII, no colon); a name too long to fit a 998-octet line — a field name cannot be folded — is rejected with `MIME_ERROR` before anything is built. +| Option | Type | Notes | +| ---------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `from` | `string \| { email, name? }` | Optional. Pinned to the project sender — see below. | +| `to` | `Address \| Address[]` | Required. One or more recipients. | +| `subject` | `string` | Required. UTF-8 supported (encoded as RFC 2047). | +| `text` | `string` | At least one of `text` / `html` is required. | +| `html` | `string` | Sent as `multipart/alternative` if both are provided. | +| `replyTo` | `Address` | Optional `Reply-To` header. | +| `cc`, `bcc` | `Address \| Address[]` | Optional. Each recipient is sent its own message envelope. | +| `headers` | `Record` | Custom headers; reserved headers (From, Date, etc.) are ignored. | +| `attachments` | `Attachment[]` | See [Attachments](#attachments). | +| `idempotencyKey` | `string` | Optional on the Void Platform: 1–128 printable, non-space ASCII characters. Reuse for retries of the same send. | + +At most 50 recipients across `to`, `cc` and `bcc` per call. Each address is checked with [`email-validator`](https://www.npmjs.com/package/email-validator): an ASCII dot-atom local part (before the `@`) of at most 64 characters — no whitespace, control character or RFC 5322 special, no leading, trailing or doubled dot, and no quoted local part — and a dotted domain of ASCII labels (at most 63 characters each) whose TLD starts with a letter and is at least 2 characters, so `user@localhost` is refused and an IDN domain must be given as punycode (`xn--…`); at most 254 characters in total (RFC 5321: a 256-octet forward-path `` and a 64-octet local part are the longest every receiver must accept). The address itself carries no display-name syntax; a display name goes around it (`"Name "` or `{ email, name }`). All of these are checked before anything is built and return `INVALID_TO` (`INVALID_FROM` for `from`; `MIME_ERROR` for `cc`, `bcc` and `replyTo`). The platform's inbound router applies the same package to `forward()` and `reply()` addresses, so nothing a handler records is dropped there for its shape. Custom header names must be RFC 5322 field names (printable ASCII, no colon); a name too long to fit a 998-octet line — a field name cannot be folded — is rejected with `MIME_ERROR` before anything is built. `Address` accepts either a string (`"hello@acme.dev"` or `"Name "`) or an object (`{ email, name? }`). Display names with non-ASCII characters are RFC 2047 encoded automatically. @@ -162,66 +156,50 @@ await sendEmail({ }); ``` -`contentType` is inferred from the filename extension when omitted; when given, it must be a valid media type (`type/subtype`, optionally followed by `; attribute=value` parameters — no `name`, which is set from `filename`), or `sendEmail` returns `MIME_ERROR`. `contentId` is the identifier the HTML references as `cid:`: letters, digits, the RFC 5322 `atext` symbols and dots, optionally with an `@domain` part and optionally in one pair of angle brackets (`logo`, `logo@acme.dev` and `` all render as `Content-ID: <…>`); anything else — whitespace, quotes, parentheses, a stray `<` or `>`, or an empty string — returns `MIME_ERROR`. Total message size (after base64 expansion) is capped at 10 MB to match Cloudflare's limit; oversize payloads return `MIME_ERROR` instead of failing upstream. +`contentType` is inferred from the filename extension when omitted; when given, it must be a valid media type (`type/subtype`, optionally followed by `; attribute=value` parameters — no `name`, which is set from `filename`), or `sendEmail` returns `MIME_ERROR`. `contentId` is the identifier the HTML references as `cid:`: letters, digits, the RFC 5322 `atext` symbols and dots, optionally with an `@domain` part and optionally in one pair of angle brackets (`logo`, `logo@acme.dev` and `` all render as `Content-ID: <…>`); anything else — whitespace, quotes, parentheses, a stray `<` or `>`, or an empty string — returns `MIME_ERROR`. Total encoded message size is capped at 5 MiB, and custom headers at 16 KiB; oversize payloads return `MIME_ERROR` instead of failing upstream. ## Result and errors -`sendEmail` returns a discriminated union — there are no thrown errors: +`sendEmail` returns a result instead of throwing. A successful result means the provider accepted the send; it does not confirm delivery to the recipient's mailbox. -```ts -interface SendEmailDelivery { - recipient: string; // the envelope `To` used for this CF send - messageId: string; -} +`ok: true` carries `ids`, one per unique recipient. Addresses are compared case-insensitively across `to`, `cc`, and `bcc`. A custom-domain provider batch can report the same provider reference for several recipients. -type SendEmailRecipientResult = - | { recipient: string; ok: true; messageId: string } - | { recipient: string; ok: false; error: SendEmailError }; - -type SendEmailResult = - | { ok: true; ids: SendEmailDelivery[] } - | { ok: false; error: SendEmailError } // pre-flight failure - | { ok: false; deliveries: SendEmailRecipientResult[] }; // mid-batch failure -``` +`ok: false` carries either a top-level `error` or a complete per-recipient `deliveries` list. Platform results include an `operationId` when available, and per-recipient `state` distinguishes rejection, reservation, submission, provider acceptance, failure, cancellation, and an unknown outcome. -`ids` carries one entry per envelope send. Because the CF `EmailMessage` envelope is single-recipient, multi-recipient calls (`to`/`cc`/`bcc`) fan out into one CF send per unique address, each with its own messageId. Addresses are matched case-insensitively across the three fields and `recipient` is the lowercased address; a capture under `void dev` or the test harness reports the same list. - -There are three discriminated cases: - -- **All success** (`ok: true`) — every recipient delivered. -- **Pre-flight failure** (`ok: false`, has `error`) — validation / MIME / missing binding rejected the call before any sends were attempted. Retrying the whole call is safe. -- **Mid-batch failure** (`ok: false`, has `deliveries`) — sends were attempted and some failed. Each recipient has its own per-recipient outcome (`ok: true` with `messageId`, or `ok: false` with `error`). Retry only recipients with `ok: false` — re-sending to ones with `ok: true` will deliver duplicates. The list always names every recipient of the call; an incomplete or malformed list from the platform proxy is reported as a top-level `UPSTREAM_ERROR` (`result.error`), never as a partial `deliveries`. +Use an idempotency key for sends you may retry: ```ts -const result = await sendEmail({ to: ['a@x.dev', 'b@x.dev', 'c@x.dev'], ... }); +const result = await sendEmail({ + to: 'user@example.com', + subject: 'Invoice ready', + text: 'Your invoice is available in your account.', + idempotencyKey: 'invoice:42:ready', +}); + if (result.ok) { - // every recipient delivered -} else if ('error' in result) { - // pre-flight failure — retry the whole call + console.log('Accepted by the provider', result.operationId); } else { - // mid-batch failure — retry only the failed recipients - const toRetry = result.deliveries.filter((d) => !d.ok).map((d) => d.recipient); + console.log('Inspect the outcome before retrying', result.operationId, result); } ``` -Error codes: - -| Code | Meaning | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `BINDING_MISSING` | No email transport: neither the worker's own `SEND_EMAIL` binding (an own-account deploy without `email.from`) nor the platform proxy is available, or a Class B/C dev server. | -| `INVALID_FROM` | `from` was missing, malformed, not the project sender (platform), or a sender Cloudflare would not accept (own account). | -| `INVALID_TO` | `to` was empty, contained an invalid or over-long address, or the call had more than 100 recipients. | -| `UNVERIFIED_DESTINATION` | Cloudflare rejected the recipient as unverified. | -| `MIME_ERROR` | Failed to build the MIME message (oversize attachments, malformed input). | -| `QUOTA_EXCEEDED` | Platform quota for outbound email reached (retry next billing period), or Cloudflare's own rate or daily limit on the sending account — the platform's, or your own. | -| `UPSTREAM_ERROR` | Other binding failure; the original error is attached as `error.cause`. | - -Which branch carries the code depends on when the send failed. -`BINDING_MISSING`, `INVALID_FROM`, `INVALID_TO` and `MIME_ERROR` are pre-flight, -so they arrive as a top-level `result.error`. `UNVERIFIED_DESTINATION` is always -per-recipient and therefore only ever appears inside `result.deliveries` — -never as `result.error`. `QUOTA_EXCEEDED` and `UPSTREAM_ERROR` can arrive either -way. Narrow with `'error' in result` rather than assuming. +For 30 days, repeating a key with the same payload returns its recorded outcome without another provider submission. Reusing it with a different payload returns `IDEMPOTENCY_CONFLICT`. A lost response or interrupted provider request can return `OUTCOME_UNKNOWN`; check `void email logs` or repeat the same key. A new key creates a new send and can produce a duplicate. Native Cloudflare binding sends do not support platform idempotency keys. + +| Code | Meaning | +| ------------------------ | -------------------------------------------------------------- | +| `BINDING_MISSING` | No email transport is configured. | +| `INVALID_FROM` | The sender is invalid or not authorized for the project. | +| `INVALID_TO` | The recipient list is invalid or exceeds 50 recipients. | +| `UNVERIFIED_DESTINATION` | The recipient needs verification under the active policy. | +| `MIME_ERROR` | The message is invalid or exceeds a size limit. | +| `QUOTA_EXCEEDED` | A platform or provider quota has been reached. | +| `IDEMPOTENCY_CONFLICT` | The key was already used for another payload. | +| `OUTCOME_UNKNOWN` | The send may have reached the provider; do not blindly resend. | +| `UPSTREAM_ERROR` | The provider or platform refused the request. | + +The default platform allowance is 200 recipient submissions per UTC calendar month and 10 in a rolling 60-second window. Reserved submissions count toward the limits. Once an attempt starts, it stays charged even if the provider fails or the outcome is unknown. Administrators can change these limits. + +`void email usage` shows the current allowance. `void email logs --limit 50` shows up to 100 recent metadata entries retained for 30 days: operation, recipient, direction, state, provider reference, and error code. It does not store subjects, bodies, or attachments. Receiving a message and sending a reply are separate events. ## Local development @@ -484,7 +462,7 @@ describe('email handlers', () => { }); ``` -The harness uses the same precedence rules as the production dispatcher. Reserved key `_default` mirrors `email/_default.ts`. It also applies the platform's inbound admission limits before your handler runs: a message over 10 MiB, or carrying more than 1024 distinct headers, is recorded in `rejects` and the handler is not called — exactly what the platform does before dispatch. With `slug: null` there is no platform router in front of the worker, so neither limit applies. +The harness uses the same precedence rules as the production dispatcher. Reserved key `_default` mirrors `email/_default.ts`. It also applies the platform's inbound admission limits before your handler runs: a message over 10 MiB, or carrying more than 1024 headers or 128 KiB of header data, is recorded in `rejects` and the handler is not called — exactly what the platform does before dispatch. With `slug: null` there is no platform router in front of the worker, so neither limit applies. ## Your own Cloudflare account diff --git a/docs/guide/platform-administration.md b/docs/guide/platform-administration.md index c943cf114..94e6a2df8 100644 --- a/docs/guide/platform-administration.md +++ b/docs/guide/platform-administration.md @@ -217,11 +217,11 @@ void platform email policy-set any void platform email policy-set verified ``` -`domains` lets every project mail any address on the listed domains in addition to its verified recipients; `any` lifts the check. Cloudflare still refuses a recipient it has not verified until your mail domain is onboarded for Email Sending, which needs Workers Paid on the platform's account. Until then such sends come back as `UNVERIFIED_DESTINATION` for that recipient, whatever the policy says. Two things the policy never changes: sends from a project's own custom domain, and mail to any address on the platform's own mail domain — those stay verified-recipient-only, so no project reaches another project's inbox without its consent. A tightening takes effect everywhere within a minute. The same setting is on the admin UI's **Email** page. +`domains` lets every project mail any address on the listed domains in addition to its verified recipients; `any` lifts the check. Cloudflare still refuses a recipient it has not verified until your mail domain is onboarded for Email Sending, which needs Workers Paid on the platform's account. Until then such sends come back as `UNVERIFIED_DESTINATION` for that recipient, whatever the policy says. Two things the policy never changes: sends from a project's own custom domain, and mail to any address on the platform's own mail domain — those stay verified-recipient-only, so no project reaches another project's inbox without its consent. A tightening applies to new send admissions as soon as it commits; previously admitted attempts may finish. The same setting is on the admin UI's **Email** page. ### Project caps -Each project may send 200 messages a month and 10 a minute by default. Raise or lower a project's caps by id or slug: +Each project has 200 recipient submissions per UTC calendar month and 10 in a rolling 60-second window by default. An attempt stays charged once it starts, including a failed or uncertain outcome. Raise or lower a project's caps by id or slug: ```sh void platform email limit hr-portal --monthly 2000 --burst 30 @@ -231,7 +231,7 @@ The project's page in the admin UI shows the current values and clears an overri ### Registering email domains for projects -Your users may hold no Cloudflare account. Tell the platform that administrators register email domains, so `void email domain add` prints the command to ask you for instead of opening a Cloudflare consent: +Your users may hold no Cloudflare account. Tell the platform that administrators register email domains, so `void email domain add` prints the command to ask you for instead of opening a token-creation page: ```sh void platform email settings-set --domains admin @@ -245,7 +245,7 @@ void platform email domain-status mail.example.com void platform email domains ``` -Name the exact mail domain: a subdomain such as `mail.example.com` when the apex already receives mail, otherwise the apex itself. Enabling Email Routing on a subdomain is a one-time step in the Cloudflare dashboard; `domain-status` names it and reports the domain active once the MX records appear. Email Sending onboarding needs Workers Paid; after upgrading, `domain-sync` re-attempts it. For a zone in another Cloudflare account, pipe an API token for that account on standard input: +Name the exact mail domain: a subdomain such as `mail.example.com` when the apex already receives mail, otherwise the apex itself. `domain-status` reports inbound, outbound, and management readiness separately. Follow any required DNS or Cloudflare dashboard step, then use `domain-sync` to reconcile. Email Sending onboarding needs Workers Paid; after upgrading, `domain-sync` re-attempts it. For a zone in another Cloudflare account, pipe an API token for that account on standard input: ```sh void platform email domain-add mail.other.example --project hr-portal --token-stdin --yes < token.txt @@ -344,3 +344,5 @@ unset VOID_OPERATOR_TOKEN Disable shell tracing for the exchange and do not write either token to logs or plaintext files. A full API login session expires after 30 days and can be revoked sooner; renew it through the normal authenticated login flow and update the protected CI secret. A job that runs longer than one hour must repeat the exchange while its full API session is still valid. An expired operator token cannot refresh itself, and Void does not issue permanent service tokens for administrator automation. `auth login --token-stdin` performs the same elevation and saves the one-hour operator token in the system keychain for interactive use. See [operator authentication](../reference/cli.md#operator-authentication) for the full command syntax. + +An email zone has one connection and ingress Worker shared by its exact domain assignments. Removing one assignment preserves resources used by the others. The Email administration page can explicitly rotate that connection secret; ordinary synchronization does not rotate it. Setup and cleanup outcomes include operation IDs, and uncertain provider writes remain recorded until reconciled. diff --git a/docs/guide/self-hosted-platform.md b/docs/guide/self-hosted-platform.md index b501640c6..7d666b89e 100644 --- a/docs/guide/self-hosted-platform.md +++ b/docs/guide/self-hosted-platform.md @@ -136,6 +136,8 @@ The management token also needs **Zone Edit** with authority to create zones if A custom runtime that enables email lets administrators [register email domains for projects](./platform-administration.md#registering-email-domains-for-projects) on the runtime token. That needs **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail, and **Email Sending: Edit** on the account; the token link preselects them when the runtime enables email. Email Sending onboarding itself needs Workers Paid on the account. +For an email-enabled runtime, set `VOID_EMAIL_SENDER_DOMAIN` to the shared sender domain and `VOID_EMAIL_SHARED_ZONE_ID` to its Cloudflare zone ID when installing or upgrading. Void records both values for later upgrades and rejects attempts to replace them during an ordinary upgrade. The mail zone can differ from the application zone; without an explicit mail-zone identity, shared inbound delivery stays unavailable. The dedicated email gateway is deployed in the platform account. Each customer zone uses its own ingress Worker to forward mail to that gateway. + Void checks access before provisioning. If it reports a missing permission, update the token's permissions for the selected account or zone and retry. ::: @@ -460,17 +462,17 @@ The management token needs **SSL and Certificates: Read** (or Edit) on that zone Resources use a `void---*` prefix where Cloudflare allows names. This keeps installations recognizable and avoids predictable Worker names colliding during setup. -| Resource | Count | Purpose | -| ----------------------------------------- | ------------------------------------: | ------------------------------------------------------------------------------ | -| Workers | 4, plus one per app using workers.dev | API/control plane, proxy, tail ingestion, dispatch, and test-origin forwarders | -| KV namespaces | 3 | Routing, ISR cache, and static asset storage | -| R2 buckets | 1 | Static and deployment assets | -| Queues | 2 | Usage events and cron firing | -| Workers for Platforms dispatch namespaces | 1 | User application Workers | -| Hyperdrive configurations | 1 | External platform PostgreSQL | -| AI Gateways | 1 | Installation-isolated AI routing and metering | -| Proxied wildcard DNS records | 0 or 1 | Created only when an application domain is configured | -| Zones | 0 or 1 | Created only when the requested application zone is absent | +| Resource | Count | Purpose | +| ----------------------------------------- | ------------------------------------: | --------------------------------------------------------------------------------------------- | +| Workers | 5, plus one per app using workers.dev | API/control plane, proxy, tail ingestion, dispatch, email gateway, and test-origin forwarders | +| KV namespaces | 3 | Routing, ISR cache, and static asset storage | +| R2 buckets | 1 | Static and deployment assets | +| Queues | 2 | Usage events and cron firing | +| Workers for Platforms dispatch namespaces | 1 | User application Workers | +| Hyperdrive configurations | 1 | External platform PostgreSQL | +| AI Gateways | 1 | Installation-isolated AI routing and metering | +| Proxied wildcard DNS records | 0 or 1 | Created only when an application domain is configured | +| Zones | 0 or 1 | Created only when the requested application zone is absent | The API Worker uses four Durable Object classes for usage, cron scheduling, error monitoring, and concurrency. Worker bindings create the request and log datasets in Analytics Engine. The core installation doesn't create Container applications, a GitHub App, a dashboard Worker, or build Workers. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 3ad71edda..d55c38f7c 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1452,7 +1452,7 @@ Show the current month's outbound and inbound counts, the monthly outbound limit void email logs [--limit ] [--project ] ``` -Show recent email activity — timestamp, direction, sender, recipient, status, and subject. `--limit` takes a positive integer. Email activity logs are not available yet on the platform; the command says so. Console output from your email handler appears in `void project logs`, like any other invocation of your worker. +Show recent email operation metadata retained for 30 days: timestamp, direction, operation ID, recipient, and state. `--limit` accepts 1–100. Subjects, bodies, and attachments are not stored. Provider acceptance does not confirm mailbox delivery; inspect unknown outcomes before retrying. ### `void email destinations` @@ -1478,7 +1478,7 @@ The project owner's email is added automatically when the project is created, so void email disallow
[--project ] ``` -Remove one recipient from the project's destination list. Sends to that address are refused within about a minute: the platform updates the project's allowlist as part of the command, and the proxy re-reads it every 60 seconds. No deploy is involved. +Remove one recipient from the project's destination list. Sends to that address are refused for new sends immediately; previously admitted attempts may finish: the platform updates the project's allowlist as part of the command, and the proxy re-reads it every 60 seconds. No deploy is involved. ### `void email domain` @@ -1494,7 +1494,7 @@ Send and receive at your own domain on a Cloudflare zone you own, registered to void email domain add [--subdomain ] [--project ] ``` -Register the domain with the project. One credential is required, granted two ways: an OAuth grant from Cloudflare's hosted consent page (the page names Wrangler — Void borrows its OAuth client), or, as the fallback Enter switches to at any point, a scoped API token created from a three-click template link and picked up from the clipboard or a masked paste. The credential is POSTed once and stored on the platform, encrypted for the project — nothing is kept locally. Needs an interactive terminal. The CLI proposes `mail.` when the apex already carries MX records and allows the apex only when it carries none; `--subdomain` overrides the proposal. One live email domain per zone and one project per domain are enforced — a conflict is refused with a 409. Re-running `add` on a `failed`, `token_revoked`, or `token_expired` row replaces the credential and retries; the routing rules stay. +Register an exact domain with the project using a scoped Cloudflare API token. The CLI opens a token template, accepts a masked paste or newly copied token, and asks you to confirm account and zone restrictions. Credentials are encrypted for the zone connection. The CLI proposes `mail.` when the apex already has MX records; `--subdomain` overrides that proposal. Several domains can share a zone connection, but each domain belongs to one project. Setup returns an operation ID so an interrupted request can be checked without restarting the operation. #### `void email domain status` @@ -1502,7 +1502,7 @@ Register the domain with the project. One credential is required, granted two wa void email domain status [--project ] ``` -Show one registered domain. The platform re-probes the stored credential and the relay worker on every call, so this doubles as the drift report. A `pending` row whose only remaining step is the dashboard's subdomain form (printed by `add`) self-clears to `active` once public MX on the domain names Cloudflare — which makes this command the poll for that one human step. +Show the recorded inbound, outbound, and management readiness, observation times, and latest operation. Use `sync` to reconcile setup and refresh readiness. #### `void email domain list` @@ -1518,7 +1518,15 @@ List the project's registered email domains with their status and mode. void email domain sync [--project ] ``` -Redeploy the domain's relay worker at the current version and rotate its secret — the fix when `status` reports the relay missing or drifted. +Reconcile the domain connection and refresh readiness. Sync does not rotate its secret. A blocked or uncertain operation exits unsuccessfully and names the operation to inspect. + +#### `void email domain rotate-secret` + +```sh +void email domain rotate-secret [--project ] +``` + +Rotate the ingress secret for the zone connection shared by this domain and its siblings. The platform accepts the staged secret before updating the Worker and promotes it only after verifying the deployed generation. An uncertain update stays recorded for reconciliation. #### `void email domain remove` @@ -1526,7 +1534,7 @@ Redeploy the domain's relay worker at the current version and rotate its secret void email domain remove [--project ] ``` -Delete the registration: the platform row, the stored credential, and the relay secret. Cloudflare-side cleanup is best-effort; any step that fails is named (`failed_steps`) so you can finish it in the Cloudflare dashboard. +Disable the domain assignment and record cleanup. Zone resources used by another domain remain available. Unfinished or uncertain cleanup remains recorded until it can be reconciled safely. ### `void email status` diff --git a/packages/deploy-core/src/index.ts b/packages/deploy-core/src/index.ts index 31968b247..d0bea5c65 100644 --- a/packages/deploy-core/src/index.ts +++ b/packages/deploy-core/src/index.ts @@ -221,6 +221,8 @@ export type LiveManifestMeta = { export type DeployManifest = { version: number; assetManifestVersion?: 1 | 2; + /** Authenticated framed HTTP delivery for managed inbound email. */ + emailProtocolVersion?: 1; auth?: boolean; bindings: { d1?: Array; diff --git a/packages/deploy-core/src/validate.ts b/packages/deploy-core/src/validate.ts index 7481e6b22..238f31171 100644 --- a/packages/deploy-core/src/validate.ts +++ b/packages/deploy-core/src/validate.ts @@ -60,6 +60,9 @@ export function validateManifestShape(parsed: unknown): string | null { return 'invalid manifest shape: expected a JSON object'; } const manifest = parsed as Record; + if (manifest.emailProtocolVersion !== undefined && manifest.emailProtocolVersion !== 1) { + return 'invalid manifest shape: emailProtocolVersion must be 1'; + } if ( manifest.bindings == null || diff --git a/packages/deploy-core/test/unit/validate.test.ts b/packages/deploy-core/test/unit/validate.test.ts index 77b2ebbeb..ab86933a2 100644 --- a/packages/deploy-core/test/unit/validate.test.ts +++ b/packages/deploy-core/test/unit/validate.test.ts @@ -43,3 +43,14 @@ describe('WebSocket deployment manifest validation', () => { ).toContain('deletedClasses must be an array of strings'); }); }); + +describe('managed email protocol', () => { + it('accepts version 1 and rejects unknown versions before deployment', () => { + expect(validateManifestShape({ version: 3, bindings: {}, emailProtocolVersion: 1 })).toBeNull(); + for (const emailProtocolVersion of [0, 2, '1', null, {}]) { + expect(validateManifestShape({ version: 3, bindings: {}, emailProtocolVersion })).toContain( + 'emailProtocolVersion must be 1', + ); + } + }); +}); diff --git a/packages/platform/README.md b/packages/platform/README.md index 25fbc75ef..d615e0983 100644 --- a/packages/platform/README.md +++ b/packages/platform/README.md @@ -28,7 +28,7 @@ The package contains: - versioned deployment and installation manifests - deterministic resource naming and application-route generation - discovery-document and capability contracts -- Cloudflare Worker configuration generation for the core API, proxy, tail, and dispatch Workers +- Cloudflare Worker configuration generation for the API, proxy, tail, dispatch, and email gateway Workers - A shared installation-owned traffic-disable protocol used by lifecycle-safe retained Workers - integrity-checked, deployable Worker bundles plus a schema-versioned PostgreSQL migration and rollback-compatibility manifest under the `./installer` export diff --git a/packages/platform/package.json b/packages/platform/package.json index 599b24ae4..165ee7e86 100644 --- a/packages/platform/package.json +++ b/packages/platform/package.json @@ -18,6 +18,10 @@ "./installer": { "types": "./dist/installer.d.mts", "import": "./dist/installer.mjs" + }, + "./email-protocol": { + "types": "./dist/email-protocol.d.mts", + "import": "./dist/email-protocol.mjs" } }, "publishConfig": { diff --git a/packages/platform/scripts/build-runtime.mjs b/packages/platform/scripts/build-runtime.mjs index 15d2cf945..f905037d9 100644 --- a/packages/platform/scripts/build-runtime.mjs +++ b/packages/platform/scripts/build-runtime.mjs @@ -22,6 +22,10 @@ const { PLATFORM_USAGE_PROTOCOL_VERSION } = await import( const workers = [ ['api', join(repositoryRoot, 'platform', 'packages', 'api', 'src', 'worker', 'index.ts')], ['proxy', join(repositoryRoot, 'platform', 'packages', 'proxy', 'src', 'index.ts')], + [ + 'emailGateway', + join(repositoryRoot, 'platform', 'packages', 'email-gateway', 'src', 'index.ts'), + ], ['tail', join(repositoryRoot, 'platform', 'packages', 'tail', 'src', 'index.ts')], ['dispatch', join(repositoryRoot, 'platform', 'packages', 'dispatch', 'src', 'index.ts')], ]; @@ -43,11 +47,12 @@ try { writeFileSync( configPath, JSON.stringify({ - name: `void-runtime-build-${name}`, + name: `void-runtime-build-${name === 'emailGateway' ? 'email-gateway' : name}`, main: entrypoint, alias: sourceAliases, compatibility_date: '2026-02-24', - compatibility_flags: name === 'api' || name === 'proxy' ? ['nodejs_compat'] : [], + compatibility_flags: + name === 'api' || name === 'proxy' || name === 'emailGateway' ? ['nodejs_compat'] : [], }), ); const result = spawnSync( @@ -81,6 +86,7 @@ try { artifacts, applicationRoutingVersion: 1, authenticationProtocolVersion: 1, + emailProtocolVersion: 1, database, platformVersion: packageJson.version, safetyProtocols: { sandboxDrain: 2 }, diff --git a/packages/platform/src/email-protocol.ts b/packages/platform/src/email-protocol.ts new file mode 100644 index 000000000..a7650da61 --- /dev/null +++ b/packages/platform/src/email-protocol.ts @@ -0,0 +1,462 @@ +/** Worker-safe wire contract shared by the platform gateway and tenant entry. */ +export const EMAIL_PROTOCOL_VERSION = 1; +export const EMAIL_RECEIPT_PATH = '/__void/email/receipt/v1'; +export const EMAIL_MAX_ACTIONS: number = 100; +export const EMAIL_MAX_METADATA_BYTES: number = 8 * 1024; +export const EMAIL_MAX_RESPONSE_BYTES: number = 8 * 1024 * 1024; +export const EMAIL_MAX_REPLY_BYTES: number = 5 * 1024 * 1024; +export const EMAIL_MAX_INBOUND_BYTES: number = 10 * 1024 * 1024; +export const EMAIL_MAX_INBOUND_HEADERS: number = 1024; +export const EMAIL_MAX_INBOUND_HEADER_BYTES: number = 128 * 1024; + +export type EmailWireAction = + | { type: 'reject'; reason: string } + | { type: 'forward'; to: string; headers?: Record } + | { type: 'reply'; from: string; to: string; raw: Uint8Array }; + +export type EmailReceiptClaims = { + version: 1; + receiptId: string; + projectId: string; + deploymentId: string; + recipient: string; + expiresAt: number; +}; + +const encoder = new TextEncoder(); +const decoder = new TextDecoder('utf-8', { fatal: true }); + +function assertFlatJson(bytes: Uint8Array, maxDepth: number, maxFields: number): void { + let depth = 0; + let fields = 0; + let quoted = false; + let escaped = false; + for (const byte of bytes) { + if (quoted) { + if (escaped) { + escaped = false; + } else if (byte === 92) { + escaped = true; + } else if (byte === 34) { + quoted = false; + } + } else if (byte === 34) { + quoted = true; + } else if (byte === 123 || byte === 91) { + if (++depth > maxDepth) { + throw new Error('email metadata too deep'); + } + } else if (byte === 125 || byte === 93) { + if (--depth < 0) { + throw new Error('invalid email metadata'); + } + } else if (byte === 58 && ++fields > maxFields) { + throw new Error('too many email metadata fields'); + } + } + if (quoted || depth !== 0) { + throw new Error('invalid email metadata'); + } +} + +export type EmailWireEnvelope = { + from: string; + to: string; + headers: Record; + raw: Uint8Array; + rawSize: number; + viaDomain?: string; +}; + +export function encodeEmailEnvelope(envelope: EmailWireEnvelope): Uint8Array { + const metadata = encoder.encode( + JSON.stringify({ + from: envelope.from, + to: envelope.to, + headers: envelope.headers, + rawSize: envelope.rawSize, + ...(envelope.viaDomain ? { viaDomain: envelope.viaDomain } : {}), + }), + ); + if ( + metadata.byteLength > EMAIL_MAX_INBOUND_HEADER_BYTES || + envelope.raw.byteLength > EMAIL_MAX_INBOUND_BYTES + ) { + throw new Error('email envelope too large'); + } + const bytes = new Uint8Array(4 + metadata.byteLength + envelope.raw.byteLength); + new DataView(bytes.buffer).setUint32(0, metadata.byteLength); + bytes.set(metadata, 4); + bytes.set(envelope.raw, 4 + metadata.byteLength); + return bytes; +} + +export async function readEmailEnvelope( + stream: ReadableStream | null, + deadlineMs = 15_000, +): Promise { + if (!stream) { + throw new Error('missing email envelope'); + } + const reader = stream.getReader(); + const bytes = new Uint8Array(4 + EMAIL_MAX_INBOUND_HEADER_BYTES + EMAIL_MAX_INBOUND_BYTES); + let total = 0; + const deadline = Date.now() + deadlineMs; + try { + for (;;) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('email envelope timeout'); + } + let timer: ReturnType | undefined; + const chunk = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('email envelope timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (chunk.done) { + break; + } + total += chunk.value.byteLength; + if (total > bytes.byteLength) { + throw new Error('email envelope too large'); + } + bytes.set(chunk.value, total - chunk.value.byteLength); + } + } catch (error) { + await reader.cancel().catch(() => {}); + throw error; + } finally { + reader.releaseLock(); + } + if (total < 4) { + throw new Error('truncated email envelope'); + } + const metadataLength = new DataView(bytes.buffer).getUint32(0); + if (metadataLength > EMAIL_MAX_INBOUND_HEADER_BYTES || total < 4 + metadataLength) { + throw new Error('invalid email envelope'); + } + const metadataBytes = bytes.subarray(4, 4 + metadataLength); + assertFlatJson(metadataBytes, 2, EMAIL_MAX_INBOUND_HEADERS + 8); + const metadata: unknown = JSON.parse(decoder.decode(metadataBytes)); + if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) { + throw new Error('invalid email envelope'); + } + const value = metadata as Record; + const raw = bytes.subarray(4 + metadataLength, total); + if ( + typeof value.from !== 'string' || + value.from.length > 320 || + typeof value.to !== 'string' || + value.to.length > 320 || + typeof value.rawSize !== 'number' || + value.rawSize !== raw.byteLength || + !value.headers || + typeof value.headers !== 'object' || + Array.isArray(value.headers) || + Object.keys(value.headers).length > EMAIL_MAX_INBOUND_HEADERS || + Object.values(value.headers).some((header) => typeof header !== 'string') || + (value.viaDomain !== undefined && + (typeof value.viaDomain !== 'string' || value.viaDomain.length > 253)) + ) { + throw new Error('invalid email envelope'); + } + return { + from: value.from, + to: value.to, + headers: value.headers as Record, + raw, + rawSize: raw.byteLength, + ...(value.viaDomain ? { viaDomain: value.viaDomain as string } : {}), + }; +} + +function base64url(bytes: Uint8Array): string { + let binary = ''; + for (const byte of bytes) { + binary += String.fromCharCode(byte); + } + return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', ''); +} + +function unbase64url(value: string): Uint8Array { + if (!/^[A-Za-z0-9_-]+$/.test(value) || value.length > 1024) { + throw new Error('invalid receipt'); + } + const binary = atob( + value.replaceAll('-', '+').replaceAll('_', '/') + '='.repeat((4 - (value.length % 4)) % 4), + ); + return Uint8Array.from(binary, (char) => char.charCodeAt(0)); +} + +async function receiptKey(secret: string, usage: 'sign' | 'verify'): Promise { + return crypto.subtle.importKey( + 'raw', + encoder.encode(secret), + { name: 'HMAC', hash: 'SHA-256' }, + false, + [usage], + ); +} + +export async function signEmailReceipt( + claims: EmailReceiptClaims, + projectToken: string, +): Promise { + const payload = encoder.encode(JSON.stringify(claims)); + const signature = new Uint8Array( + await crypto.subtle.sign('HMAC', await receiptKey(projectToken, 'sign'), payload), + ); + return `${base64url(payload)}.${base64url(signature)}`; +} + +export async function verifyEmailReceipt( + token: string, + projectToken: string, + expected: Pick, + now: number = Date.now(), +): Promise { + try { + if (token.length > 1536) { + return null; + } + const parts = token.split('.'); + if (parts.length !== 2) { + return null; + } + const payload = unbase64url(parts[0]); + const signature = unbase64url(parts[1]); + if (payload.byteLength > 768 || signature.byteLength !== 32) { + return null; + } + if ( + !(await crypto.subtle.verify( + 'HMAC', + await receiptKey(projectToken, 'verify'), + Uint8Array.from(signature), + Uint8Array.from(payload), + )) + ) { + return null; + } + const claims: unknown = JSON.parse(decoder.decode(payload)); + if (typeof claims !== 'object' || claims === null) { + return null; + } + const value = claims as Partial; + if ( + value.version !== EMAIL_PROTOCOL_VERSION || + typeof value.receiptId !== 'string' || + !/^[a-f0-9-]{16,64}$/.test(value.receiptId) || + value.projectId !== expected.projectId || + value.deploymentId !== expected.deploymentId || + value.recipient !== expected.recipient || + typeof value.expiresAt !== 'number' || + !Number.isSafeInteger(value.expiresAt) || + value.expiresAt < now || + value.expiresAt > now + 60_000 + ) { + return null; + } + return value as EmailReceiptClaims; + } catch { + return null; + } +} + +function frame(kind: number, payload: Uint8Array): Uint8Array { + const bytes = new Uint8Array(5 + payload.byteLength); + new DataView(bytes.buffer).setUint32(0, payload.byteLength); + bytes[4] = kind; + bytes.set(payload, 5); + return bytes; +} + +export function encodeEmailActions( + actions: ReadonlyArray, +): ReadableStream { + if (actions.length > EMAIL_MAX_ACTIONS) { + throw new Error('too many email actions'); + } + let index = 0; + let pending: Uint8Array | null = null; + let total = 0; + return new ReadableStream({ + pull(controller) { + if (pending) { + controller.enqueue(pending); + pending = null; + return; + } + if (index === actions.length) { + controller.enqueue(frame(0, new Uint8Array())); + controller.close(); + return; + } + const action = actions[index++]; + const metadata = encoder.encode( + JSON.stringify( + action.type === 'reply' + ? { type: action.type, from: action.from, to: action.to } + : action, + ), + ); + if (metadata.byteLength > EMAIL_MAX_METADATA_BYTES) { + throw new Error('email action metadata too large'); + } + if (action.type === 'reply') { + if (action.raw.byteLength > EMAIL_MAX_REPLY_BYTES) { + throw new Error('email reply too large'); + } + pending = frame(2, action.raw); + } + total += 5 + metadata.byteLength + (pending?.byteLength ?? 0); + if (total > EMAIL_MAX_RESPONSE_BYTES) { + throw new Error('email actions too large'); + } + controller.enqueue(frame(1, metadata)); + }, + }); +} + +/** Read each frame with fixed ceilings before parsing metadata or allocating a reply. */ +export async function readEmailActions( + stream: ReadableStream, + deadlineMs = 15_000, +): Promise> { + const reader = stream.getReader(); + const actions: Array = []; + let stash: Uint8Array = new Uint8Array(0); + let total = 0; + const deadline = Date.now() + deadlineMs; + async function readChunk() { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('email response timeout'); + } + let timer: ReturnType | undefined; + return Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('email response timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + } + async function exact(length: number): Promise { + const result = new Uint8Array(length); + let offset = 0; + while (offset < length) { + if (stash.byteLength === 0) { + const chunk = await readChunk(); + if (chunk.done) { + throw new Error('truncated email response'); + } + total += chunk.value.byteLength; + if (total > EMAIL_MAX_RESPONSE_BYTES) { + throw new Error('email response too large'); + } + stash = chunk.value; + } + const used = Math.min(stash.byteLength, length - offset); + result.set(stash.subarray(0, used), offset); + stash = stash.subarray(used); + offset += used; + } + return result; + } + try { + for (;;) { + const head = await exact(5); + const length = new DataView(head.buffer).getUint32(0); + const kind = head[4]; + if (kind === 0) { + if (length !== 0 || stash.byteLength !== 0) { + throw new Error('invalid email response tail'); + } + const last = await readChunk(); + if (!last.done) { + throw new Error('invalid email response tail'); + } + if (actions.some((action) => action.type === 'reject') && actions.length !== 1) { + throw new Error('email reject cannot accompany delivery actions'); + } + return actions; + } + if (kind !== 1 || length > EMAIL_MAX_METADATA_BYTES || actions.length >= EMAIL_MAX_ACTIONS) { + throw new Error('invalid email action frame'); + } + const metadataBytes = await exact(length); + assertFlatJson(metadataBytes, 2, 40); + const value: unknown = JSON.parse(decoder.decode(metadataBytes)); + if (!value || typeof value !== 'object' || Array.isArray(value)) { + throw new Error('invalid email action'); + } + const action = value as Record; + if (action.type === 'reply') { + if ( + typeof action.from !== 'string' || + typeof action.to !== 'string' || + Object.keys(action).length !== 3 + ) { + throw new Error('invalid email reply'); + } + const rawHead = await exact(5); + const rawLength = new DataView(rawHead.buffer).getUint32(0); + if (rawHead[4] !== 2 || rawLength > EMAIL_MAX_REPLY_BYTES) { + throw new Error('invalid email reply frame'); + } + actions.push({ + type: 'reply', + from: action.from, + to: action.to, + raw: await exact(rawLength), + }); + } else if (action.type === 'forward') { + if ( + typeof action.to !== 'string' || + Object.keys(action).length > 3 || + (action.headers !== undefined && + (typeof action.headers !== 'object' || + action.headers === null || + Array.isArray(action.headers))) + ) { + throw new Error('invalid email forward'); + } + const headers = action.headers as Record | undefined; + if ( + headers && + (Object.keys(headers).length > 32 || + Object.values(headers).some((v) => typeof v !== 'string')) + ) { + throw new Error('invalid email headers'); + } + actions.push({ + type: 'forward', + to: action.to, + ...(headers ? { headers: headers as Record } : {}), + }); + } else if (action.type === 'reject') { + if (typeof action.reason !== 'string' || Object.keys(action).length !== 2) { + throw new Error('invalid email reject'); + } + actions.push({ type: 'reject', reason: action.reason }); + } else { + throw new Error('unknown email action'); + } + } + } catch (error) { + await reader.cancel().catch(() => {}); + throw error; + } finally { + reader.releaseLock(); + } +} diff --git a/packages/platform/src/installer.ts b/packages/platform/src/installer.ts index 40ed1e34b..fbb543af6 100644 --- a/packages/platform/src/installer.ts +++ b/packages/platform/src/installer.ts @@ -33,7 +33,11 @@ export type PlatformRuntimeDatabaseManifest = Readonly<{ export type PlatformRuntimeManifest = Readonly<{ authenticationProtocolVersion?: 1; applicationRoutingVersion?: 1; - artifacts: Readonly>; + artifacts: Readonly< + Record<'api' | 'dispatch' | 'proxy' | 'tail', PlatformRuntimeArtifact> & + Partial> + >; + emailProtocolVersion?: 1; database: PlatformRuntimeDatabaseManifest; platformVersion: string; safetyProtocols: Readonly<{ sandboxDrain: 0 | 1 | 2 }>; @@ -83,13 +87,23 @@ export function parsePlatformRuntimeManifest(value: unknown): PlatformRuntimeMan ) { throw new Error('Unsupported authentication protocol version.'); } + if (root.emailProtocolVersion !== undefined && root.emailProtocolVersion !== 1) { + throw new Error('Unsupported email protocol version.'); + } const artifactsValue = record(root.artifacts, 'runtime manifest artifacts'); + if (root.emailProtocolVersion === 1 && artifactsValue.emailGateway === undefined) { + throw new Error('Email protocol version 1 requires an emailGateway runtime artifact.'); + } + const artifactNames = [ + 'api', + 'dispatch', + 'proxy', + 'tail', + ...(artifactsValue.emailGateway === undefined ? [] : ['emailGateway']), + ] as const; const artifacts = Object.fromEntries( - (['api', 'dispatch', 'proxy', 'tail'] as const).map((name) => [ - name, - parseArtifact(artifactsValue[name], name), - ]), - ) as Record<'api' | 'dispatch' | 'proxy' | 'tail', PlatformRuntimeArtifact>; + artifactNames.map((name) => [name, parseArtifact(artifactsValue[name], name)]), + ) as PlatformRuntimeManifest['artifacts']; const databaseValue = record(root.database, 'runtime manifest database'); if (databaseValue.protocolVersion !== 1) { throw new Error('runtime manifest database protocolVersion must be 1'); @@ -162,6 +176,7 @@ export function parsePlatformRuntimeManifest(value: unknown): PlatformRuntimeMan ...(root.authenticationProtocolVersion === 1 ? { authenticationProtocolVersion: 1 as const } : {}), + ...(root.emailProtocolVersion === 1 ? { emailProtocolVersion: 1 as const } : {}), ...(root.applicationRoutingVersion === 1 ? { applicationRoutingVersion: 1 as const } : {}), database: { journalSha256: sha256(databaseValue.journalSha256, 'database journal digest'), diff --git a/packages/platform/src/manifest.ts b/packages/platform/src/manifest.ts index dc5d31793..11d9018d6 100644 --- a/packages/platform/src/manifest.ts +++ b/packages/platform/src/manifest.ts @@ -28,6 +28,7 @@ export type PlatformResourceNames = Readonly<{ dashboardWorker: string; dispatchNamespace: string; dispatchWorker: string; + emailGatewayWorker: string; hyperdrive: string; isrCacheKv: string; legacyAssetsKv: string; @@ -41,6 +42,10 @@ export type PlatformResourceNames = Readonly<{ export type PlatformDeploymentManifest = Readonly<{ application: PlatformApplication; + /** Zone that owns the installation's shared sender mail domain. */ + emailSharedZoneId?: string; + /** Shared sender domain registered for managed email. */ + emailSenderDomain?: string; authentication: Readonly<{ providers: ReadonlyArray; configurable?: true; @@ -62,6 +67,8 @@ export type PlatformDeploymentManifestInput = Readonly<{ workersDev?: PlatformApplication['workersDev']; zoneId?: string; }>; + emailSharedZoneId?: string; + emailSenderDomain?: string; authentication?: Readonly<{ providers?: ReadonlyArray; configurable?: true; @@ -152,6 +159,7 @@ export function createPlatformResourceNames(installationSlug: string): PlatformR dashboardWorker: `${prefix}-dashboard`, dispatchNamespace: `${prefix}-users`, dispatchWorker: `${prefix}-dispatch`, + emailGatewayWorker: `${prefix}-email-gateway`, hyperdrive: `${prefix}-database`, isrCacheKv: `${prefix}-isr-cache`, legacyAssetsKv: `${prefix}-legacy-assets`, @@ -252,6 +260,12 @@ export function createPlatformDeploymentManifest( ...(input.authentication?.accessProtection ? { accessProtection: true } : {}), }, capabilities, + ...(input.emailSharedZoneId !== undefined + ? { emailSharedZoneId: requiredString(input.emailSharedZoneId, 'emailSharedZoneId') } + : {}), + ...(input.emailSenderDomain !== undefined + ? { emailSenderDomain: normalizeApplicationDomain(input.emailSenderDomain) } + : {}), controlPlane: { ...CONTROL_PLANE_DEFAULTS, ...input.controlPlane }, displayName: requiredString(input.displayName, 'displayName').trim(), installationSlug, @@ -344,7 +358,10 @@ export function parsePlatformDeploymentManifest(value: unknown): PlatformDeploym ); const resources: Partial> = {}; for (const key of Object.keys(resourceDefaults) as Array) { - resources[key] = requiredString(rawResources[key], `resources.${key}`); + resources[key] = requiredString( + rawResources[key] ?? (key === 'emailGatewayWorker' ? resourceDefaults[key] : undefined), + `resources.${key}`, + ); } const readHostname = (key: keyof PlatformControlPlane): string | null => { const hostname = controlPlane[key]; @@ -367,6 +384,16 @@ export function parsePlatformDeploymentManifest(value: unknown): PlatformDeploym ...(authentication.accessProtection === true ? { accessProtection: true } : {}), }, capabilities, + ...(value.emailSharedZoneId !== undefined + ? { emailSharedZoneId: requiredString(value.emailSharedZoneId, 'emailSharedZoneId') } + : {}), + ...(value.emailSenderDomain !== undefined + ? { + emailSenderDomain: normalizeApplicationDomain( + requiredString(value.emailSenderDomain, 'emailSenderDomain'), + ), + } + : {}), controlPlane: { apiHostname: readHostname('apiHostname'), dashboardHostname: readHostname('dashboardHostname'), diff --git a/packages/platform/src/worker-config.ts b/packages/platform/src/worker-config.ts index edbf6091a..8b72ff158 100644 --- a/packages/platform/src/worker-config.ts +++ b/packages/platform/src/worker-config.ts @@ -10,7 +10,7 @@ export type PlatformProvisionedResourceIds = Readonly<{ }>; export type PlatformWorkerConfigSet = Readonly< - Record<'api' | 'dispatch' | 'proxy' | 'tail', Record> + Record<'api' | 'dispatch' | 'proxy' | 'tail' | 'emailGateway', Record> >; export function createPlatformWorkerConfigs(input: { @@ -24,8 +24,11 @@ export function createPlatformWorkerConfigs(input: { platformVersion: string; publicEndpoints?: boolean; proxyUrl: string; + emailGatewayUrl: string; resources: PlatformProvisionedResourceIds; - runtimeEntrypoints: Readonly>; + runtimeEntrypoints: Readonly< + Record<'api' | 'dispatch' | 'proxy' | 'tail' | 'emailGateway', string> + >; trafficState?: 'enabled' | 'sandbox-drain' | 'staging'; }): PlatformWorkerConfigSet { const { @@ -37,12 +40,23 @@ export function createPlatformWorkerConfigs(input: { ownershipNonce, platformVersion, proxyUrl, + emailGatewayUrl, resources, runtimeEntrypoints, } = input; const publicEndpoints = input.publicEndpoints ?? true; const trafficState = input.trafficState ?? 'enabled'; const names = deployment.resources; + const sharedEmailIngress = deployment.emailSharedZoneId + ? { + EMAIL_SHARED_ACCOUNT_ID: accountId, + EMAIL_SHARED_ZONE_ID: deployment.emailSharedZoneId, + EMAIL_SHARED_INGRESS_NAME: names.emailGatewayWorker, + } + : {}; + const senderDomain = deployment.emailSenderDomain + ? { EMAIL_SENDER_DOMAIN: deployment.emailSenderDomain } + : {}; const ownershipVars = (resourceKey: string, resourceName: string) => ({ PLATFORM_OWNERSHIP_MARKER: JSON.stringify( createPlatformResourceOwnershipMarker({ @@ -136,6 +150,9 @@ export function createPlatformWorkerConfigs(input: { ...ownershipVars('api-worker', names.apiWorker), PLATFORM_VERSION: platformVersion, PROXY_URL: proxyUrl, + EMAIL_GATEWAY_ORIGIN: emailGatewayUrl, + ...sharedEmailIngress, + ...senderDomain, R2_STATIC_ASSETS_BUCKET: names.assetsBucket, REQUESTS_DATASET: names.requestsDataset, SITE_DOMAIN: deployment.application.baseDomain, @@ -170,6 +187,7 @@ export function createPlatformWorkerConfigs(input: { PLATFORM_HEALTH_PROBE_TOKEN: healthProbeToken, PLATFORM_INSTALLATION_ID: installationId, PLATFORM_TRAFFIC_STATE: trafficState, + ...senderDomain, ...ownershipVars('proxy-worker', names.proxyWorker), }, }; @@ -180,6 +198,27 @@ export function createPlatformWorkerConfigs(input: { return { api, proxy, + emailGateway: { + ...common, + workers_dev: publicEndpoints, + preview_urls: false, + name: names.emailGatewayWorker, + main: runtimeEntrypoints.emailGateway, + no_bundle: true, + compatibility_flags: ['nodejs_compat'], + kv_namespaces: [{ binding: 'ROUTING', id: resources.routingKv }], + services: [{ binding: 'API', service: names.apiWorker }], + dispatch_namespaces: dispatchNamespace, + ...(deployment.capabilities.email ? { send_email: [{ name: 'SEND_EMAIL' }] } : {}), + vars: { + PLATFORM_CAPABILITIES: JSON.stringify(deployment.capabilities), + PLATFORM_INSTALLATION_ID: installationId, + PLATFORM_TRAFFIC_STATE: trafficState, + ...sharedEmailIngress, + ...senderDomain, + ...ownershipVars('email-gateway-worker', names.emailGatewayWorker), + }, + }, tail: { ...common, name: names.tailWorker, diff --git a/packages/platform/test/unit/email-protocol.test.ts b/packages/platform/test/unit/email-protocol.test.ts new file mode 100644 index 000000000..1b0a018ff --- /dev/null +++ b/packages/platform/test/unit/email-protocol.test.ts @@ -0,0 +1,106 @@ +import { describe, expect, it } from 'vite-plus/test'; +import { + encodeEmailActions, + readEmailEnvelope, + readEmailActions, + signEmailReceipt, + verifyEmailReceipt, +} from '../../src/email-protocol.ts'; + +const claims = { + version: 1 as const, + receiptId: 'a16b6d96-7097-45f6-b88e-5677072628ef', + projectId: 'project-1', + deploymentId: 'deployment-1', + recipient: 'support@example.com', + expiresAt: Date.now() + 20_000, +}; + +describe('bounded email receipt protocol', () => { + it('binds a short-lived receipt to project, deployment and SMTP recipient', async () => { + const token = await signEmailReceipt(claims, 'platform-only-secret'); + expect(await verifyEmailReceipt(token, 'platform-only-secret', claims)).toMatchObject(claims); + expect(await verifyEmailReceipt(token, 'tenant-known-token', claims)).toBeNull(); + expect( + await verifyEmailReceipt(token, 'platform-only-secret', { + ...claims, + recipient: 'other@example.com', + }), + ).toBeNull(); + expect( + await verifyEmailReceipt(token, 'platform-only-secret', claims, claims.expiresAt + 1), + ).toBeNull(); + }); + + it('reads a complete framed batch before returning actions', async () => { + const stream = encodeEmailActions([ + { type: 'forward', to: 'user@example.com' }, + { + type: 'reply', + from: 'support@example.com', + to: 'sender@example.com', + raw: new Uint8Array([0, 255, 17]), + }, + ]); + expect(await readEmailActions(stream)).toEqual([ + { type: 'forward', to: 'user@example.com' }, + { + type: 'reply', + from: 'support@example.com', + to: 'sender@example.com', + raw: new Uint8Array([0, 255, 17]), + }, + ]); + }); + + it('rejects a truncated tail instead of returning a partial action batch', async () => { + const encoded = encodeEmailActions([{ type: 'forward', to: 'user@example.com' }]); + const reader = encoded.getReader(); + const first = await reader.read(); + const truncated = new ReadableStream({ + start(controller) { + controller.enqueue(first.value!); + controller.close(); + }, + }); + await expect(readEmailActions(truncated)).rejects.toThrow('truncated email response'); + }); + + it('rejects oversized metadata before JSON parsing', async () => { + const head = new Uint8Array(5); + new DataView(head.buffer).setUint32(0, 8193); + head[4] = 1; + await expect( + readEmailActions( + new ReadableStream({ + start(controller) { + controller.enqueue(head); + controller.close(); + }, + }), + ), + ).rejects.toThrow('invalid email action frame'); + }); + + it('rejects an oversized tenant response before retaining its chunk', async () => { + const oversized = new Uint8Array(8 * 1024 * 1024 + 1); + await expect( + readEmailActions( + new ReadableStream({ + start(controller) { + controller.enqueue(oversized); + controller.close(); + }, + }), + ), + ).rejects.toThrow('email response too large'); + }); + + it('bounds stalled tenant and envelope streams by deadline', async () => { + await expect(readEmailActions(new ReadableStream(), 5)).rejects.toThrow( + 'email response timeout', + ); + const envelope = new ReadableStream(); + await expect(readEmailEnvelope(envelope, 5)).rejects.toThrow('email envelope timeout'); + }); +}); diff --git a/packages/platform/test/unit/worker-config.test.ts b/packages/platform/test/unit/worker-config.test.ts index f91ac7f5f..c815d48bc 100644 --- a/packages/platform/test/unit/worker-config.test.ts +++ b/packages/platform/test/unit/worker-config.test.ts @@ -3,6 +3,57 @@ import { createPlatformDeploymentManifest } from '../../src/manifest.ts'; import { createPlatformWorkerConfigs } from '../../src/worker-config.ts'; describe('platform usage queue bindings', () => { + it('routes shared mail through its configured zone, independent of the application zone', () => { + const deployment = createPlatformDeploymentManifest({ + application: { baseDomain: 'apps.example.com', zoneName: 'example.com' }, + emailSharedZoneId: 'mail-zone-id', + emailSenderDomain: 'mail.example.org', + capabilities: { email: true }, + displayName: 'Example', + installationSlug: 'example', + }); + const configs = createPlatformWorkerConfigs({ + accountId: 'account', + apiUrl: 'https://api.example.com', + proxyUrl: 'https://proxy.example.com', + emailGatewayUrl: 'https://email-gateway.account.workers.dev', + deployment, + healthProbeToken: 'probe', + installationId: 'installation', + ownershipNonce: 'ownership', + platformVersion: '1.0.0', + resources: { + hyperdrive: 'db', + isrCacheKv: 'isr', + legacyAssetsKv: 'assets', + routingKv: 'routing', + zone: 'app-zone-id', + }, + runtimeEntrypoints: { + api: 'api.mjs', + proxy: 'proxy.mjs', + emailGateway: 'email-gateway.mjs', + tail: 'tail.mjs', + dispatch: 'dispatch.mjs', + }, + }); + const expected = { + EMAIL_SHARED_ACCOUNT_ID: 'account', + EMAIL_SHARED_ZONE_ID: 'mail-zone-id', + EMAIL_SHARED_INGRESS_NAME: deployment.resources.emailGatewayWorker, + }; + expect(configs.api.vars).toMatchObject(expected); + expect(configs.emailGateway.vars).toMatchObject(expected); + expect(configs.api.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); + expect(configs.proxy.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); + expect(configs.emailGateway.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); + expect(configs.emailGateway).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]); + expect(configs.api.vars).toHaveProperty( + 'EMAIL_GATEWAY_ORIGIN', + 'https://email-gateway.account.workers.dev', + ); + }); + it.each([ { apiUrl: 'https://api.example.com', @@ -46,6 +97,7 @@ describe('platform usage queue bindings', () => { accountId: 'account', apiUrl, proxyUrl, + emailGatewayUrl: 'https://email-gateway.account.workers.dev', deployment, healthProbeToken: 'probe', installationId: 'example-123456abcdef', @@ -61,6 +113,7 @@ describe('platform usage queue bindings', () => { runtimeEntrypoints: { api: 'api.mjs', proxy: 'proxy.mjs', + emailGateway: 'email-gateway.mjs', dispatch: 'dispatch.mjs', tail: 'tail.mjs', }, @@ -74,7 +127,13 @@ describe('platform usage queue bindings', () => { expect(configs.proxy.services).toEqual([ { binding: 'API', service: deployment.resources.apiWorker }, ]); - expect(Object.keys(configs).sort()).toEqual(['api', 'dispatch', 'proxy', 'tail']); + expect(Object.keys(configs).sort()).toEqual([ + 'api', + 'dispatch', + 'emailGateway', + 'proxy', + 'tail', + ]); }, ); @@ -93,6 +152,7 @@ describe('platform usage queue bindings', () => { ownershipNonce: 'ownership', platformVersion: '1.0.0', proxyUrl: 'https://proxy.example.com', + emailGatewayUrl: 'https://email-gateway.account.workers.dev', resources: { hyperdrive: 'hyperdrive-id', isrCacheKv: 'isr-id', @@ -104,6 +164,7 @@ describe('platform usage queue bindings', () => { api: 'api.mjs', dispatch: 'dispatch.mjs', proxy: 'proxy.mjs', + emailGateway: 'email-gateway.mjs', tail: 'tail.mjs', }, }); @@ -135,6 +196,7 @@ describe('platform usage queue bindings', () => { ownershipNonce: 'ownership', platformVersion: '1.0.0', proxyUrl: 'https://proxy.example.com', + emailGatewayUrl: 'https://email-gateway.account.workers.dev', resources: { hyperdrive: 'hyperdrive-id', isrCacheKv: 'isr-id', @@ -146,6 +208,7 @@ describe('platform usage queue bindings', () => { api: 'api.mjs', dispatch: 'dispatch.mjs', proxy: 'proxy.mjs', + emailGateway: 'email-gateway.mjs', tail: 'tail.mjs', }, }); diff --git a/packages/platform/vite.config.ts b/packages/platform/vite.config.ts index 12a09e07d..b482a33d3 100644 --- a/packages/platform/vite.config.ts +++ b/packages/platform/vite.config.ts @@ -2,7 +2,7 @@ import { defineConfig } from 'vite-plus'; export default defineConfig({ pack: { - entry: ['src/index.ts', 'src/installer.ts'], + entry: ['src/index.ts', 'src/installer.ts', 'src/email-protocol.ts'], format: 'esm', dts: true, clean: true, diff --git a/packages/void/package.json b/packages/void/package.json index 932e4a55f..e66fc483d 100644 --- a/packages/void/package.json +++ b/packages/void/package.json @@ -218,6 +218,11 @@ "import": "./dist/runtime/email.mjs", "require": "./dist/runtime/email.mjs" }, + "./_email-protocol": { + "types": "./dist/runtime/email-protocol.d.mts", + "import": "./dist/runtime/email-protocol.mjs", + "require": "./dist/runtime/email-protocol.mjs" + }, "./email/testing": { "types": "./dist/runtime/email/testing.d.mts", "import": "./dist/runtime/email/testing.mjs", diff --git a/packages/void/skills/void/SKILL.md b/packages/void/skills/void/SKILL.md index 1c535a1e8..312750115 100644 --- a/packages/void/skills/void/SKILL.md +++ b/packages/void/skills/void/SKILL.md @@ -158,3 +158,5 @@ Then ask what to do next. - If docs and memory differ, follow docs. - For Void-managed auth, `void db generate` automatically includes the production Better Auth schema in the generated migration, including configured model/field renames and plugin tables. Keep those migrations under `db/migrations/`; do not duplicate generated auth tables in the application Drizzle schema. - **Env vars:** When the project has `env.ts`, the canonical access pattern is `import { env } from "void/env"`. Declare every env key in `env.ts` via `defineEnv({...})` so values are typed and validated. Do not introduce ad-hoc `process.env.X` or untyped `c.env.X` access in new code — add the key to `env.ts` first. + +For platform email domains, use `void email domain add` with an account- and zone-scoped Cloudflare API token. Read inbound, outbound, and management readiness separately; `domain sync` reconciles without rotating secrets. Use a stable `sendEmail({ idempotencyKey })` for retryable sends and inspect `void email logs` when the result is `OUTCOME_UNKNOWN`; never retry an uncertain send with a new key. Native Cloudflare email setup remains `void email setup --platform cloudflare` and does not support platform idempotency keys. diff --git a/packages/void/src/cli/client.ts b/packages/void/src/cli/client.ts index 3d403f00c..1c85b181c 100644 --- a/packages/void/src/cli/client.ts +++ b/packages/void/src/cli/client.ts @@ -236,10 +236,15 @@ export type EmailUsageResponse = { export type EmailLogEntry = { timestamp: number; direction: 'sent' | 'received'; - from: string; - to: string; - subject?: string; + operationId: string; + receiptId?: string | null; + actionId?: string; + recipient?: string | null; status: string; + transport?: string; + providerReference?: string | null; + errorCode?: string | null; + policyVersion?: number | null; }; export type EmailLogsResponse = { @@ -290,7 +295,15 @@ export type EmailDomainResponse = { id: string; domain: string; mode: 'apex' | 'subdomain' | null; - status: 'pending' | 'active' | 'token_revoked' | 'token_expired' | 'failed'; + status: + | 'pending' + | 'ready' + | 'disabled' + | 'drifted' + | 'active' + | 'token_revoked' + | 'token_expired' + | 'failed'; /** `platform` rows run on the platform's own credential — an administrator's row. */ credential_kind: 'oauth_grant' | 'api_token' | 'platform'; /** Who registered the row; owners may read an `admin` row but not sync or remove it. */ @@ -307,6 +320,9 @@ export type EmailDomainResponse = { * reconcile tells that apart from a stamped null. */ attemptId?: string | null; + operationId?: string; + operationStatus?: EmailOperationResponse['status']; + readiness?: EmailReadiness; setup_state: { /** Orchestration step that left the row 'failed'. */ failed_step?: string; @@ -323,6 +339,34 @@ export type EmailDomainResponse = { updated_at: string; }; +export type EmailReadiness = { + inbound: { + status: 'pending' | 'ready' | 'disabled' | 'drifted'; + reason?: string | null; + observedAt?: string | null; + }; + outbound: { + status: 'pending' | 'verified_only' | 'ready' | 'blocked'; + reason?: string | null; + observedAt?: string | null; + }; + management: { + status: 'healthy' | 'expired' | 'revoked' | 'refresh_unknown' | 'probe_failed'; + reason?: string | null; + observedAt?: string | null; + }; +}; + +export type EmailOperationResponse = { + operationId: string; + attemptId: string; + status: 'pending' | 'running' | 'blocked' | 'unknown' | 'completed'; + domain: string; + readiness: EmailReadiness; + failedStep?: string; + error?: string; +}; + /** The zone catch-all outcome of a sync — absent when the row has no zone_id. */ export type EmailDomainSyncCatchAll = | 'ensured' @@ -351,6 +395,9 @@ export type EmailDomainStatusResponse = EmailDomainResponse & { export type RemoveEmailDomainFailedStep = 'catch_all' | 'delete_relay' | 'revoke_grant'; export type RemoveEmailDomainResponse = { + operationId?: string; + operationStatus?: EmailOperationResponse['status']; + error?: string; ok: boolean; /** * false = the row was KEPT for retry: a Cloudflare-side step failed and @@ -1605,6 +1652,17 @@ export class PlatformClient { return res.json(); } + async getEmailOperation(projectId: string, operationId: string): Promise { + const res = await this.request( + `${this.baseUrl}/projects/${encodeURIComponent(projectId)}/email/operations/${encodeURIComponent(operationId)}`, + { headers: { ...this.authHeaders } }, + ); + if (!res.ok) { + await throwPlatformApiError('Failed to fetch email operation', res); + } + return res.json(); + } + async listEmailDestinations(projectId: string): Promise> { const res = await this.request(`${this.baseUrl}/projects/${projectId}/email/destinations`, { headers: { @@ -1713,7 +1771,7 @@ export class PlatformClient { */ async addEmailDomain( projectId: string, - input: { domain: string; refreshToken?: string; apiToken?: string; attemptId?: string }, + input: { domain: string; apiToken?: string; attemptId?: string }, ): Promise { const res = await this.request(`${this.baseUrl}/projects/${projectId}/email/domains`, { method: 'POST', @@ -1723,7 +1781,6 @@ export class PlatformClient { }, body: JSON.stringify({ domain: input.domain, - ...(input.refreshToken !== undefined ? { refreshToken: input.refreshToken } : {}), ...(input.apiToken !== undefined ? { apiToken: input.apiToken } : {}), ...(input.attemptId !== undefined ? { attemptId: input.attemptId } : {}), }), @@ -1753,7 +1810,18 @@ export class PlatformClient { return res.json(); } - /** Redeploys the relay at the current version and rotates its secret (0078, `sync`). */ + /** Reconciles the shared zone connection without rotating its secret. */ + async rotateEmailDomainSecret(projectId: string, domain: string): Promise { + const res = await this.request( + `${this.baseUrl}/projects/${projectId}/email/domains/${encodeURIComponent(domain)}/rotate-secret`, + { method: 'POST', headers: { ...this.authHeaders } }, + ); + if (!res.ok) { + await throwPlatformApiError('Failed to rotate email connection secret', res); + } + return res.json(); + } + async syncEmailDomain(projectId: string, domain: string): Promise { const res = await this.request( `${this.baseUrl}/projects/${projectId}/email/domains/${encodeURIComponent(domain)}/sync`, diff --git a/packages/void/src/cli/deploy.ts b/packages/void/src/cli/deploy.ts index e12cf28d7..cd201dfd9 100644 --- a/packages/void/src/cli/deploy.ts +++ b/packages/void/src/cli/deploy.ts @@ -8117,6 +8117,8 @@ async function runFullDeploy( isFrameworkMode, { bindings: liveConfig ? { ...effectiveBindings, needsLive: true } : effectiveBindings, + hasEmailHandlers: + !isFrameworkMode && routeScan.email !== undefined && hasEmailHandlers(routeScan.email), migrations: validatedMigrations, schedules, ssr: isSsr || hasRoutes || hasMiddleware || hasWebSockets || authEnabled, diff --git a/packages/void/src/cli/email-args.ts b/packages/void/src/cli/email-args.ts index d403670b3..fe7a8ae7a 100644 --- a/packages/void/src/cli/email-args.ts +++ b/packages/void/src/cli/email-args.ts @@ -17,7 +17,7 @@ export const emailSubcommands: Array = [ // errors naming the missing , the same as a typed invocation. { name: 'domain', - arg: '', + arg: '', description: 'Send and receive at your own domain on a Cloudflare zone', }, { @@ -43,7 +43,14 @@ const EMAIL_SUBCOMMANDS = [ 'setup', ] as const; -export const EMAIL_DOMAIN_VERBS = ['add', 'status', 'list', 'sync', 'remove'] as const; +export const EMAIL_DOMAIN_VERBS = [ + 'add', + 'status', + 'list', + 'sync', + 'rotate-secret', + 'remove', +] as const; export type EmailDomainVerb = (typeof EMAIL_DOMAIN_VERBS)[number]; export interface EmailArgs { @@ -305,7 +312,7 @@ function parseEmailDomainArgs( const verb = positional[0]; if (!verb || !(EMAIL_DOMAIN_VERBS as ReadonlyArray).includes(verb)) { throw new Error( - 'email: Usage: void email domain [] [--project ].', + 'email: Usage: void email domain [] [--project ].', ); } if (flags.subdomain !== undefined && verb !== 'add') { diff --git a/packages/void/src/cli/email.ts b/packages/void/src/cli/email.ts index 89b6e9569..0079704bc 100644 --- a/packages/void/src/cli/email.ts +++ b/packages/void/src/cli/email.ts @@ -5,7 +5,6 @@ import { readConfig } from '../config.ts'; import { readProjectPaths } from '../project-paths.ts'; import { scanEmailHandlersSync } from '../router/email.ts'; import { getToken, openBrowser } from './auth.ts'; -import { revokeCfOauthGrant, runCfOauthGrant, type CfOauthGrant } from './cf-oauth.ts'; import { PlatformApiError, PlatformClient, @@ -198,7 +197,9 @@ export async function emailDisallow( process.exit(1); } await client.removeEmailDestination(projectId, dest.id); - log.success(`Removed ${dest.address}. Sends to it are refused within about a minute.`); + log.success( + `Removed ${dest.address}. New sends to it are refused immediately; already admitted attempts may finish.`, + ); } /** @@ -210,10 +211,6 @@ export async function emailLogs( projectId: string, limit?: number, ): Promise { - // The API currently ignores `limit`; server-side wiring is pending the - // Analytics Engine integration. Forwarding it now keeps the CLI - // forward-compatible — once persistent storage lands, no client change is - // needed. const result = await client.getEmailLogs(projectId, limit); if (result.pending) { log.info(result.note ?? 'Persistent log storage is not yet wired up.'); @@ -234,8 +231,7 @@ export async function emailLogs( const lines = result.logs.map((entry) => { const ts = new Date(entry.timestamp).toISOString(); const dir = entry.direction === 'sent' ? '→' : '←'; - const subject = entry.subject ? ` "${entry.subject}"` : ''; - return `${ts} ${dir} ${entry.from} → ${entry.to} ${entry.status}${subject}`; + return `${ts} ${dir} ${entry.operationId} ${entry.recipient ?? '—'} ${entry.status}${entry.errorCode ? ` (${entry.errorCode})` : ''}`; }); note(lines.join('\n'), 'Email Logs'); } @@ -244,9 +240,9 @@ export async function emailLogs( // // `void email domain add|status|list|sync|remove`. The api owns the // orchestration (contract 7); the CLI owns the MX-decision render, the -// credential grant (the OAuth flow in cf-oauth.ts, the template link + +// scoped API token (the template link + // clipboard watch below as the permanent fallback), and the result render. -// The credential — grant refresh token or pasted API token — is held in +// The pasted API token is held in // memory, POSTed once, and never printed, logged, or persisted locally. /** @@ -263,7 +259,7 @@ const CF_TOKEN_TEMPLATE_PERMISSION_GROUPS = [ { key: 'zone_settings', type: 'edit' }, ] as const; -/** The three-click template link — the fallback grant path (0078, "Creating the token in three clicks"). */ +/** The three-click template link — the scoped token path (0078, "Creating the token in three clicks"). */ export function buildCfApiTokenTemplateUrl(domain: string): string { const url = new URL('https://dash.cloudflare.com/profile/api-tokens'); url.searchParams.set('permissionGroupKeys', JSON.stringify(CF_TOKEN_TEMPLATE_PERMISSION_GROUPS)); @@ -475,11 +471,6 @@ function createEnterRace(waitForEnter?: () => Promise): EnterRace { /** Seams for {@link emailDomainAdd} — every browser, clipboard, DNS, and stdin touch is injectable. */ export interface EmailDomainAddDeps { dns?: Pick; - /** The OAuth grant (default: the real PKCE flow in cf-oauth.ts). */ - runGrant?: (options: { - onUrl?: (url: string) => void; - signal?: AbortSignal; - }) => Promise; /** Browser open for the template link (default: auth.ts's openBrowser). */ openUrl?: (url: string) => void; /** Clipboard read; null means no clipboard tool — the paste prompt is the path. */ @@ -489,6 +480,8 @@ export interface EmailDomainAddDeps { verifyToken?: (token: string) => Promise; /** The masked paste prompt; null means the user cancelled (Esc). */ pasteToken?: () => Promise; + /** Confirms the account/zone resource restriction shown in the token form. */ + confirmScope?: (domain: string) => Promise; /** The Enter keypress that switches paths (default: one stdin line). */ waitForEnter?: () => Promise; watchIntervalMs?: number; @@ -512,9 +505,7 @@ async function defaultPasteToken(): Promise { return result; } -type EmailDomainCredential = - | { kind: 'oauth_grant'; refreshToken: string } - | { kind: 'api_token'; apiToken: string }; +type EmailDomainCredential = { kind: 'api_token'; apiToken: string }; /** * Lost-answer reconcile bounds for `domain add`: attempt-count bounded (not @@ -530,7 +521,7 @@ const ADD_RECONCILE_INTERVAL_MS = 1000; * `void email domain add ` — exported for the unit test; the command * entry resolves the client and project first. * - * The flow (0078, "The flow"): render the MX decision → the OAuth grant → + * The flow: render the MX decision → scoped API token → * the template-link + clipboard fallback (Enter switches to the masked paste * at any point) → POST the credential once → render the resulting row. A * failed add leaves the platform row 'failed' and re-running add replaces @@ -541,7 +532,11 @@ const ADD_RECONCILE_INTERVAL_MS = 1000; export async function emailDomainAdd( client: Pick< PlatformClient, - 'addEmailDomain' | 'getEmailDomain' | 'getEmailSettings' | 'listEmailDomains' + | 'addEmailDomain' + | 'getEmailDomain' + | 'getEmailOperation' + | 'getEmailSettings' + | 'listEmailDomains' >, projectId: string, rawDomain: string, @@ -646,60 +641,19 @@ export async function emailDomainAdd( await decideTarget(); } - // Both grant paths need a human: a browser, a clipboard, or a paste prompt. + // Token creation needs a browser or a masked paste prompt. const interactive = deps.isInteractive ?? !isWranglerNonInteractiveOrCI(); if (!interactive) { return fail( - 'email: `void email domain add` needs an interactive terminal (the grant opens a browser; the fallback reads the clipboard or a paste). Run it locally.', + 'email: `void email domain add` needs an interactive terminal to create or paste a scoped Cloudflare API token. Run it locally.', ); } - // 1. The OAuth grant on wrangler's client (cf-oauth.ts). Enter switches to - // the template-link path mid-wait; any failure falls through to it too — - // the borrowed client id is not ours, so the fallback is permanent. - let credential: EmailDomainCredential | undefined; - const runGrant = deps.runGrant ?? ((options) => runCfOauthGrant(options)); - const grantSpinner = createSpinner(); - grantSpinner.start("Opening Cloudflare's consent page…"); - const controller = new AbortController(); - const enterDuringGrant = createEnterRace(deps.waitForEnter); - const grantOutcome = await Promise.race([ - runGrant({ - signal: controller.signal, - onUrl: (url) => - grantSpinner.message( - `Waiting for the Cloudflare grant — click Allow. If the browser didn't open, visit:\n${pc.cyan(url)}\n(Enter switches to the API-token path.)`, - ), - }).then( - (grant) => ({ type: 'grant' as const, grant }), - (error: unknown) => ({ - type: 'error' as const, - error: error instanceof Error ? error : new Error(String(error)), - }), - ), - enterDuringGrant.promise.then(() => ({ type: 'enter' as const })), - ]); - enterDuringGrant.stop(); - if (grantOutcome.type === 'grant') { - grantSpinner.stop('Grant received.'); - credential = { kind: 'oauth_grant', refreshToken: grantOutcome.grant.refreshToken }; - } else { - controller.abort(); - grantSpinner.stop( - grantOutcome.type === 'enter' - ? 'Switched to the API-token path.' - : 'The consent flow did not complete — using the API-token path.', + let credential: EmailDomainCredential; + { + log.info( + `Create a Cloudflare API token restricted to the account and DNS zone containing ${target.emailDomain}. In the resource selectors, replace All accounts and All zones with those exact resources. Workers Scripts Write still applies to every Worker in the selected account.`, ); - if (grantOutcome.type === 'error') { - log.warn(grantOutcome.error.message); - } - } - - // 2. The template link + clipboard watch (0078, "Creating the token in - // three clicks"). The clipboard is read only between opening the link - // and getting a token, only a NEW value shaped like a CF token is - // accepted, and the clipboard is cleared once it arrives. - if (credential === undefined) { const url = buildCfApiTokenTemplateUrl(target.emailDomain); const readClip = deps.readClipboard ?? readClipboard; const clearClip = deps.clearClipboard ?? clearClipboard; @@ -821,132 +775,85 @@ export async function emailDomainAdd( } } - // 3. The one call that carries the credential. Everything after it - // (status, sync, remove) addresses the row by domain. The attempt id - // is stamped on the row by the api, so a reconcile after a lost answer - // can tell this attempt's committed row apart from a pre-existing one. + const scopeConfirmed = await ( + deps.confirmScope ?? + (async (domain: string) => { + const answer = await confirm({ + message: `Is this token restricted to the Cloudflare account and DNS zone containing ${domain}?`, + initialValue: false, + }); + return !isCancel(answer) && answer === true; + }) + )(target.emailDomain); + if (!scopeConfirmed) { + return fail( + 'email: restrict the token to the selected account and zone before adding the domain. Nothing was submitted to the platform.', + ); + } + const attemptId = crypto.randomUUID(); + log.info(`Setup operation: ${attemptId}`); let row: EmailDomainResponse; try { row = await client.addEmailDomain(projectId, { domain: target.emailDomain, - ...(credential.kind === 'oauth_grant' - ? { refreshToken: credential.refreshToken } - : { apiToken: credential.apiToken }), + apiToken: credential.apiToken, attemptId, }); - } catch (err) { - if ( - err instanceof PlatformApiError && - (err.status === 400 || err.status === 404 || err.status === 409) - ) { - // Only the add route's deliberate rejections rethrow: it revokes a - // posted grant server-side before answering any of these, and the - // error names the reason. 403 is NOT in this set — the platform's - // middleware answers 403 pre-route (a suspended account, a - // deploy-token scope refusal) without ever parsing the body, so a - // 403 proves nothing about the grant and reconciles like any other - // ambiguous answer. - throw err; + } catch (error) { + if (error instanceof PlatformApiError && [400, 403, 404, 409].includes(error.status)) { + throw error; } - // A transport failure (DNS, a connection reset, a lost answer) OR an - // ambiguous answer (403, 5xx, or a 401/413/426/429 from middleware or - // the edge) leaves the add's outcome unknown: the request may never - // have reached the route, it may have failed before the grant was - // stored or revoked, or it COMMITTED and only the outcome was lost. - // The CLI holds the only copy of a freshly minted grant, so reconcile - // before anything irreversible — a committed row is the grant's - // revocation handle, and only a definitive "not on the row" makes a - // CLI-side revoke safe (revoking a stored-and-unrotated grant would - // brick the row it belongs to). const sleep = deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms))); - // The last informative read picks the deadline branch: a row carrying a - // DIFFERENT attempt id means the platform kept the row's existing - // credential; a 404 means nothing persisted (yet). - let lastRead: 'foreign' | 'missing' | undefined; for (let attempt = 0; attempt < ADD_RECONCILE_ATTEMPTS; attempt++) { if (attempt > 0) { await sleep(ADD_RECONCILE_INTERVAL_MS); } - let existing: EmailDomainStatusResponse; + let operation; try { - existing = await client.getEmailDomain(projectId, target.emailDomain); - } catch (statusErr) { - if (statusErr instanceof PlatformApiError && statusErr.status === 404) { - lastRead = 'missing'; - } - // Any other error is no read at all — keep polling. - continue; - } - if ('attemptId' in existing) { - if (existing.attemptId === attemptId) { - // My POST committed. NEVER revoke — the row is the grant's handle. - log.warn( - "The add's answer was lost (network or platform error), but the platform has the row.", - ); - printEmailDomainOutcome(existing); - return; - } - // Not mine (yet) — my in-flight POST could still commit a replace - // stamping this id, so keep polling to the deadline. - lastRead = 'foreign'; + operation = await client.getEmailOperation(projectId, attemptId); + } catch { continue; } - // An api without attempt identity (the key is absent): this could be - // my add committed there, indistinguishable from a pre-existing row. - // Trust the row like the pre-attempt flow did — NEVER revoke. - log.warn( - "The add's answer was lost (network or platform error), but the platform has the row.", + note( + [ + `Operation: ${operation.operationId}`, + `Status: ${operation.status}`, + `Inbound: ${operation.readiness.inbound.status}`, + `Outbound: ${operation.readiness.outbound.status}`, + `Credential: ${operation.readiness.management.status}`, + ].join('\n'), + 'Email Setup', ); - printEmailDomainOutcome(existing); - return; - } - if (lastRead === 'foreign') { - // The row settled on another attempt id (or none), so this attempt's - // credential was never stored — a committed mine would have stamped - // my id. The revoke cannot brick the row. - if (credential.kind === 'oauth_grant') { - const revoked = await revokeCfOauthGrant(credential.refreshToken); - return fail( - revoked - ? `email: the add did not complete, and ${target.emailDomain} kept the row's existing credential; the OAuth grant minted for this attempt was revoked — re-run to retry the replace.` - : `email: the add did not complete, and ${target.emailDomain} kept the row's existing credential; the OAuth grant minted for this attempt could not be revoked — revoke it in the Cloudflare dashboard, then re-run to retry the replace.`, - ); + if (operation.error) { + log.error(operation.error); } - return fail( - `email: the add did not complete, and ${target.emailDomain} kept the row's existing credential. The token was not stored anywhere; delete it in the Cloudflare dashboard if you are not retrying.`, - ); - } - if (lastRead === 'missing') { - // 404 at every poll — provably nothing persisted. The minted grant's - // only copy is in this process: revoke it rather than strand it live - // (an api_token has no revoke primitive — the customer deletes it - // themselves). - if (credential.kind === 'oauth_grant') { - const revoked = await revokeCfOauthGrant(credential.refreshToken); - return fail( - revoked - ? `email: the add did not complete — ${target.emailDomain} was not registered, and the OAuth grant minted for this attempt was revoked.` - : `email: the add did not complete — ${target.emailDomain} was not registered; the OAuth grant minted for this attempt could not be revoked — revoke it in the Cloudflare dashboard before retrying.`, - ); + log.info(`Run \`void email domain status ${target.emailDomain}\` to inspect setup.`); + if (operation.status === 'completed') { + return; } return fail( - `email: the add did not complete — ${target.emailDomain} was not registered. The token was not stored anywhere; delete it in the Cloudflare dashboard if you are not retrying.`, + `email: setup is ${operation.status}; operation ${operation.operationId} retains its confirmed progress on the platform.`, ); } - // No poll produced any read — the add's state is unknown, and a blind - // revoke could brick a committed row: report, don't revoke. return fail( - `email: the add did not complete, and the follow-up check failed too — the add's state is unknown, so nothing was revoked. A grant minted for this attempt may still be live: once connectivity is back, run \`void email domain status ${target.emailDomain}\`; if it shows no row, revoke the grant in the Cloudflare dashboard before retrying.`, + `email: setup outcome is unknown (operation ${attemptId}). Nothing was revoked. Check \`void email domain status ${target.emailDomain}\` before starting another setup.`, ); } log.success( - credential.kind === 'oauth_grant' - ? 'Grant stored on the platform, encrypted for this project — nothing is kept on this machine.' - : 'Token stored on the platform, encrypted for this project — nothing is kept on this machine.', + 'Token stored encrypted on the platform for this zone connection — nothing is kept on this machine.', ); printEmailDomainOutcome(row); + if ( + row.status === 'failed' || + row.status === 'token_revoked' || + row.status === 'token_expired' || + row.operationStatus === 'blocked' || + row.operationStatus === 'unknown' + ) { + return exit(1); + } } /** An administrator's row runs on the platform's own credential; the owner never held one. */ @@ -961,7 +868,7 @@ function emailCredentialLabel(row: Pick + `${name.padEnd(12)} ${value.status}${value.reason ? ' — ' + value.reason : ''}${value.observedAt ? ' (' + value.observedAt + ')' : ''}`, + ), + ]; + if (row.operationId) { + lines.push( + `Operation: ${row.operationId}${row.operationStatus ? ' · ' + row.operationStatus : ''}`, + ); + } + note(lines.join('\n'), 'Email Domain'); + if (row.error) { + log.error(row.error); + } + if (row.readiness.inbound.status !== 'ready') { + log.info(`Run void email domain sync ${row.domain} to reconcile setup.`); + } + return; + } if (row.status === 'failed') { const step = row.setup_state?.failed_step; log.error( @@ -1025,7 +954,7 @@ function printEmailDomainOutcome(row: EmailDomainResponse): void { } if (row.status === 'token_revoked' || row.status === 'token_expired') { log.warn( - `The stored credential was ${row.status === 'token_revoked' ? 'revoked at Cloudflare' : 'left to expire'} — re-run \`void email domain add ${row.domain}\` with a fresh grant or token. Rules and the relay stay.`, + `The stored credential was ${row.status === 'token_revoked' ? 'revoked at Cloudflare' : 'left to expire'} — re-run \`void email domain add ${row.domain}\` with a fresh API token. Rules and the relay stay.`, ); return; } @@ -1051,6 +980,10 @@ export async function emailDomainStatus( ): Promise { const domain = normalizeEmailDomainInput(rawDomain); const row: EmailDomainStatusResponse = await client.getEmailDomain(projectId, domain); + if (row.readiness) { + printEmailDomainOutcome(row); + return; + } const adminRow = row.managed_by === 'admin'; const lines = [ @@ -1130,7 +1063,7 @@ export async function emailDomainStatus( ); } else { log.warn( - `Re-run \`void email domain add ${row.domain}\` with a fresh grant or token — adding again replaces the credential, rules stay.`, + `Re-run \`void email domain add ${row.domain}\` with a fresh scoped API token — adding again replaces the credential, rules stay.`, ); } } @@ -1164,20 +1097,39 @@ export async function emailDomainSync( ): Promise { const domain = normalizeEmailDomainInput(rawDomain); const row = await client.syncEmailDomain(projectId, domain); - if (row.status !== 'failed') { - log.success( - `Relay redeployed${row.relay_version !== null ? ` at v${row.relay_version}` : ''} with a rotated secret.`, + if (row.catch_all === 'foreign_conflict') { + log.warn( + "Catch-all: the zone's catch-all points at a different worker and was not overwritten.", ); - // catch_all is absent when the row carries no zone_id. - if (row.catch_all === 'foreign_conflict') { - log.warn( - "Catch-all: the zone's catch-all points at a different worker and was NOT overwritten — change it in the zone's Email Routing settings if inbound mail should reach this relay.", - ); - } else if (row.catch_all !== undefined) { - log.info(`Catch-all: ${row.catch_all.replaceAll('_', ' ')}`); - } + } else if (row.catch_all) { + log.info(`Catch-all: ${row.catch_all.replaceAll('_', ' ')}`); } printEmailDomainOutcome(row); + if ( + row.status === 'failed' || + row.operationStatus === 'blocked' || + row.operationStatus === 'unknown' + ) { + throw new Error( + `email: reconciliation ${row.operationStatus ?? row.status}; inspect operation ${row.operationId ?? row.domain}`, + ); + } +} + +/** Rotation applies to every domain sharing this zone connection. */ +export async function emailDomainRotateSecret( + client: Pick, + projectId: string, + rawDomain: string, +): Promise { + const row = await client.rotateEmailDomainSecret(projectId, normalizeEmailDomainInput(rawDomain)); + printEmailDomainOutcome(row); + if (row.operationStatus !== 'completed') { + throw new Error( + `email: secret rotation ${row.operationStatus ?? 'pending'}; inspect operation ${row.operationId ?? row.domain}`, + ); + } + log.success('Zone ingress secret rotated and verified on the deployed Worker.'); } /** `void email domain remove ` — exported for the unit test. */ @@ -1190,6 +1142,18 @@ export async function emailDomainRemove( const domain = normalizeEmailDomainInput(rawDomain); const result = await client.removeEmailDomain(projectId, domain, options.force); + if (result.operationId) { + log.info(`Operation: ${result.operationId} · ${result.operationStatus ?? 'pending'}`); + if (!result.removed) { + log.error( + result.error ?? + 'Email cleanup is not complete. Its operation and resources remain recorded for reconciliation.', + ); + (options.exit ?? ((code: number): never => process.exit(code)))(1); + } + log.success(`Removed ${domain}. Zone resources still used by other domains were retained.`); + return; + } if (!result.removed) { // Kept for retry: a Cloudflare-side step failed without --force, so the // row (and the stored credential the retry needs) stays. @@ -1234,6 +1198,8 @@ async function runEmailDomainCommand( return emailDomainList(client, projectId); case 'sync': return emailDomainSync(client, projectId, args.domain!); + case 'rotate-secret': + return emailDomainRotateSecret(client, projectId, args.domain!); case 'remove': return emailDomainRemove(client, projectId, args.domain!, { force: args.force }); } diff --git a/packages/void/src/cli/help.ts b/packages/void/src/cli/help.ts index c1c03d9ff..f3b2d25f7 100644 --- a/packages/void/src/cli/help.ts +++ b/packages/void/src/cli/help.ts @@ -612,7 +612,7 @@ const HELP_TREE: HelpTree = { { command: 'allow
', description: 'Add a recipient and trigger CF verification' }, { command: 'disallow
', description: 'Remove a recipient from the allowlist' }, { - command: 'domain ', + command: 'domain ', description: 'Send and receive at your own domain on a Cloudflare zone', }, { @@ -655,7 +655,7 @@ const HELP_TREE: HelpTree = { 'Remove a recipient from the verified allowlist.', 'void email disallow
[options]', ), - // The one nested group: verbs parse in email-args.ts (`domain `). + // The one nested group: verbs parse in email-args.ts (`domain `). // Void-platform-only, so `--project` is global here; `--subdomain` is `add`-only. domain: { summary: 'Send and receive at your own domain on a Cloudflare zone.', @@ -663,20 +663,24 @@ const HELP_TREE: HelpTree = { commands: [ { command: 'add ', - description: 'Register the domain (OAuth grant, or a scoped API token)', + description: 'Register the domain with a scoped Cloudflare API token', }, { command: 'status ', - description: 'Show state; re-probes the credential and relay, polls a pending row', + description: 'Show inbound, outbound, management, and operation readiness', }, { command: 'list', description: 'List registered email domains' }, + { + command: 'rotate-secret ', + description: 'Rotate the shared zone ingress secret with a deployment probe', + }, { command: 'sync ', - description: 'Redeploy the relay at the current version and rotate its secret', + description: 'Reconcile the zone connection and refresh readiness', }, { command: 'remove ', - description: 'Delete the registration, stored credential, and relay secret', + description: 'Disable the domain assignment and reconcile shared resources', }, ], options: [ @@ -700,26 +704,30 @@ const HELP_TREE: HelpTree = { ], }, status: withProjectOption( - 'Show a registered domain, re-probing its credential and relay.', + 'Show a registered domain and its recorded readiness.', 'void email domain status [options]', ), list: withProjectOption( 'List registered email domains.', 'void email domain list [options]', ), + 'rotate-secret': withProjectOption( + 'Rotate the shared zone ingress secret and verify the deployed generation.', + 'void email domain rotate-secret [options]', + ), sync: withProjectOption( - 'Redeploy the relay at the current version and rotate its secret.', + 'Reconcile the zone connection and refresh readiness.', 'void email domain sync [options]', ), // Not `withProjectOption`: `remove` has a flag of its own (`--force`), // same shape as the `email logs` page above. remove: { - summary: 'Delete the registration, stored credential, and relay secret.', + summary: 'Disable the domain assignment and reconcile shared resources.', usage: ['void email domain remove [options]'], options: [ { command: '--force', - description: 'Drop the row even when Cloudflare-side cleanup fails', + description: 'Retain cleanup intent when provider work cannot be completed', }, { command: '--project ', description: 'Project name override' }, ], diff --git a/packages/void/src/cli/package.ts b/packages/void/src/cli/package.ts index 8747eedb4..f3bbc7fde 100644 --- a/packages/void/src/cli/package.ts +++ b/packages/void/src/cli/package.ts @@ -506,6 +506,7 @@ export function detectNonSpaFallbackWarning( */ export function buildVoidManifest(opts: { bindings: InferredBindings; + hasEmailHandlers?: boolean; migrations?: Array; schedules?: Array; ssr?: boolean; @@ -549,6 +550,9 @@ export function buildVoidManifest(opts: { const resolvedDialect = dialect ?? 'sqlite'; const manifest: DeployManifest = { version: 3, assetManifestVersion: 2, bindings: {} }; + if (opts.hasEmailHandlers) { + manifest.emailProtocolVersion = 1; + } if (bindings.needsAuth) { manifest.auth = true; } diff --git a/packages/void/src/cli/platform-installer.ts b/packages/void/src/cli/platform-installer.ts index eb97bab93..f68243dd0 100644 --- a/packages/void/src/cli/platform-installer.ts +++ b/packages/void/src/cli/platform-installer.ts @@ -772,6 +772,25 @@ export async function installPlatform( const resolvedRuntime = dependencies.runtime ?? resolvePlatformRuntime(); const runtimeDirectory = resolvedRuntime.directory; const runtime = resolvedRuntime.manifest; + const hasEmailGatewayArtifact = runtime.artifacts.emailGateway !== undefined; + if (runtime.emailProtocolVersion !== 1 && plan.deployment.capabilities.email) { + throw new Error( + 'platform: This runtime cannot serve enabled platform email without email protocol version 1.', + ); + } + if ( + runtime.emailProtocolVersion !== 1 && + existing?.resources.some( + (resource) => resource.key === 'email-gateway-worker' && resource.state === 'ready', + ) + ) { + throw new Error( + 'platform: This runtime cannot replace an installed email gateway Worker. Use a runtime with email protocol version 1.', + ); + } + const workerKeys: ReadonlyArray = hasEmailGatewayArtifact + ? ['api', 'proxy', 'emailGateway', 'tail', 'dispatch'] + : ['api', 'proxy', 'tail', 'dispatch']; if (plan.deployment.authentication.configurable && runtime.authenticationProtocolVersion !== 1) { throw new Error( 'platform: This runtime does not support configurable authentication. Upgrade Void or use a compatible runtime.', @@ -1406,7 +1425,8 @@ export async function installPlatform( key, join(runtimeDirectory, artifact.path), ]), - ) as Record<'api' | 'dispatch' | 'proxy' | 'tail', string>; + ) as Record<'api' | 'dispatch' | 'proxy' | 'tail', string> & + Partial>; let interruptedCutover = interruptedWorkerCutover(manifest); if (interruptedCutover && authenticationProtocolTransition && authenticationEnforcementActive) { manifest = recordWorkerCutoverResolution( @@ -1422,7 +1442,10 @@ export async function installPlatform( } const recoveringUnsafeTraffic = (interruptedCutover?.unsafeTraffic.size ?? 0) > 0; const createsWorker = plan.actions.some( - (action) => action.kind === 'worker' && action.action === 'create', + (action) => + action.kind === 'worker' && + action.action === 'create' && + (hasEmailGatewayArtifact || action.key !== 'email-gateway-worker'), ); const recoveringCreatedWorker = interruptedCutover !== null && @@ -1472,6 +1495,7 @@ export async function installPlatform( ownershipNonce: manifest.ownershipNonce, platformVersion: version, proxyUrl: plan.proxyUrl, + emailGatewayUrl: `https://${plan.deployment.resources.emailGatewayWorker}.${plan.workersSubdomain}.workers.dev`, resources: { hyperdrive: requireId(ids, 'hyperdrive'), isrCacheKv: requireId(ids, 'isr-cache-kv'), @@ -1479,7 +1503,7 @@ export async function installPlatform( routingKv: requireId(ids, 'routing-kv'), zone: zoneId, }, - runtimeEntrypoints: entrypoints, + runtimeEntrypoints: entrypoints as Record, }; const requiresStagedCommit = !preserveDisabled && requiresTrafficGuard; const enabledConfigs = createPlatformWorkerConfigs({ @@ -1501,7 +1525,9 @@ export async function installPlatform( }); const managedRoutes = platformManagedWorkerTraffic(plan.deployment).routes; let workerActions: ReadonlyArray = plan.actions.filter( - (action) => action.kind === 'worker', + (action) => + action.kind === 'worker' && + (hasEmailGatewayArtifact || action.key !== 'email-gateway-worker'), ); if (interruptedCutover) { for (const key of [...interruptedCutover.staged.keys()].reverse()) { @@ -1618,7 +1644,7 @@ export async function installPlatform( plan, manifest, await dependencies.replanWorkers(manifest), - ); + ).filter((action) => hasEmailGatewayArtifact || action.key !== 'email-gateway-worker'); } } workerCutoverGeneration = nextWorkerCutoverGeneration(manifest); @@ -1641,9 +1667,12 @@ export async function installPlatform( secretCheckpoint(secrets, workerSecretUpdateIntent), ); } - for (const key of ['api', 'proxy', 'tail', 'dispatch'] as const) { + for (const key of workerKeys) { dependencies.onProgress?.(`Deploying the ${key} service`); - const action = workerActions.find((entry) => entry.key === `${key}-worker`)!; + const action = workerActions.find( + (entry) => + entry.key === (key === 'emailGateway' ? 'email-gateway-worker' : `${key}-worker`), + )!; const workerSecrets = platformWorkerSecretPayload( key, workerDeploymentSecrets, @@ -1892,6 +1921,7 @@ export async function installPlatform( workers: [ plan.deployment.resources.apiWorker, plan.deployment.resources.proxyWorker, + ...(hasEmailGatewayArtifact ? [plan.deployment.resources.emailGatewayWorker] : []), plan.deployment.resources.dispatchWorker, ], resumeCommand: dependencies.healthCheckResumeCommand, @@ -1986,9 +2016,12 @@ export async function installPlatform( secretCheckpoint(secrets, workerSecretUpdateIntent), ); } - for (const key of ['api', 'proxy', 'tail', 'dispatch'] as const) { + for (const key of workerKeys) { dependencies.onProgress?.(`Enabling the ${key} service`); - const action = workerActions.find((entry) => entry.key === `${key}-worker`)!; + const action = workerActions.find( + (entry) => + entry.key === (key === 'emailGateway' ? 'email-gateway-worker' : `${key}-worker`), + )!; const workerSecrets = platformWorkerSecretPayload( key, workerDeploymentSecrets, @@ -2125,6 +2158,7 @@ export async function installPlatform( enabledConfigs, plan.account.id, runPinnedPlatformWrangler, + workerKeys, ); } }; @@ -2767,13 +2801,13 @@ export function apiWorkerSecrets( /** Existing Workers inherit live secrets, including complete encryption keyrings. */ export function platformWorkerSecretPayload( - worker: 'api' | 'proxy' | 'tail' | 'dispatch', + worker: 'api' | 'proxy' | 'emailGateway' | 'tail' | 'dispatch', secrets: PlatformInstallationSecrets, accountId: string, zoneId: string, existingWorker: boolean, ): Record | null { - if (worker !== 'api' && worker !== 'proxy') { + if (worker !== 'api' && worker !== 'proxy' && worker !== 'emailGateway') { return null; } if (!existingWorker) { @@ -2902,7 +2936,9 @@ export function assertRequiredPlatformSecrets( if ( plan.actions.some( (action) => - action.key === 'proxy-worker' && action.kind === 'worker' && action.action === 'create', + (action.key === 'proxy-worker' || action.key === 'email-gateway-worker') && + action.kind === 'worker' && + action.action === 'create', ) ) { requireSecret(secrets.cloudflareApiToken, 'VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN'); @@ -4921,7 +4957,7 @@ function nextTrafficGeneration(manifest: PlatformInstallationManifest): number { ); } -type PlatformWorkerKey = 'api' | 'proxy' | 'tail' | 'dispatch'; +type PlatformWorkerKey = 'api' | 'proxy' | 'emailGateway' | 'tail' | 'dispatch'; type PlatformWorkerCutoverSnapshot = Readonly<{ previousVersionId: string | null; @@ -5141,16 +5177,23 @@ export async function verifyPlatformWorkerCutoverVersions( configs: Record>, accountId: string, runner: typeof runPlatformWrangler = runPlatformWrangler, + workerKeys: ReadonlyArray = [ + 'api', + 'proxy', + 'emailGateway', + 'tail', + 'dispatch', + ], ): Promise { const cutover = interruptedWorkerCutover(manifest); - if (cutover?.generation !== generation || cutover.staged.size !== 4) { + if (cutover?.generation !== generation || cutover.staged.size !== workerKeys.length) { throw new Error( `platform: Worker cutover generation ${generation} is missing a complete immutable-version checkpoint.`, ); } const directory = mkdtempSync(join(tmpdir(), 'void-platform-cutover-verify-')); try { - for (const key of ['api', 'proxy', 'tail', 'dispatch'] as const) { + for (const key of workerKeys) { const snapshot = cutover.staged.get(key); if (!snapshot) { throw new Error( diff --git a/packages/void/src/cli/platform-lifecycle.ts b/packages/void/src/cli/platform-lifecycle.ts index e34e22415..440d633d4 100644 --- a/packages/void/src/cli/platform-lifecycle.ts +++ b/packages/void/src/cli/platform-lifecycle.ts @@ -433,6 +433,12 @@ export async function runPlatformLifecycleCommand(args: PlatformArgs): Promise action.kind === 'worker'), revalidateBeforeWorkerDeploy: (manifest, action) => @@ -873,6 +881,7 @@ export async function verifyPlatformAiGatewayPlan( try { verified = await createPlatformInstallPlan(client, input, existing, { authoritativeProvisionIntents, + includeEmailGateway: preview.actions.some((entry) => entry.key === 'email-gateway-worker'), }); } catch (error) { if ( diff --git a/packages/void/src/cli/platform-management.ts b/packages/void/src/cli/platform-management.ts index 86a68b514..eb7a1253a 100644 --- a/packages/void/src/cli/platform-management.ts +++ b/packages/void/src/cli/platform-management.ts @@ -241,6 +241,7 @@ export async function runInstalledPlatformCommand(args: PlatformArgs): Promise action.kind === 'worker'), revalidateBeforeWorkerDeploy: (manifest, action) => @@ -481,6 +483,17 @@ export function assertPlatformRollbackCompatibility( target: ReturnType, source: ReturnType, ): void { + if ( + target.manifest.emailProtocolVersion !== 1 && + (installation.deployment.capabilities.email || + installation.resources.some( + (resource) => resource.key === 'email-gateway-worker' && resource.state === 'ready', + )) + ) { + throw new Error( + 'platform: The rollback target predates the email gateway and cannot safely replace this installation. Use a runtime with email protocol version 1.', + ); + } if (!installation.runtime) { throw new Error( 'platform: The installed runtime has no artifact provenance, so post-success rollback cannot identify its compatibility manifest.', @@ -936,6 +949,7 @@ export async function recoverDurablyMarkedProvisionIntents( const candidates = [ ['api-worker', 'worker', manifest.deployment.resources.apiWorker], ['proxy-worker', 'worker', manifest.deployment.resources.proxyWorker], + ['email-gateway-worker', 'worker', manifest.deployment.resources.emailGatewayWorker], ['tail-worker', 'worker', manifest.deployment.resources.tailWorker], ['dispatch-worker', 'worker', manifest.deployment.resources.dispatchWorker], ['assets-bucket', 'r2-bucket', manifest.deployment.resources.assetsBucket], diff --git a/packages/void/src/cli/platform-plan.ts b/packages/void/src/cli/platform-plan.ts index f134c1c5b..f699af78c 100644 --- a/packages/void/src/cli/platform-plan.ts +++ b/packages/void/src/cli/platform-plan.ts @@ -50,6 +50,8 @@ export type PlatformInstallPlanInput = Readonly<{ controlPlaneDomain: string; dedicatedZone: boolean; displayName: string; + emailSharedZoneId?: string; + emailSenderDomain?: string; installationSlug: string; zoneName: string; workersDev?: boolean; @@ -85,6 +87,7 @@ export async function createPlatformInstallPlan( authoritativeProvisionIntents?: boolean; repairMissing?: boolean; allowUnverifiedAiGateway?: boolean; + includeEmailGateway?: boolean; }, ): Promise { const accounts = await client.listAccounts(); @@ -94,6 +97,15 @@ export async function createPlatformInstallPlan( `platform: Refusing to resume installation ${existing.id} in a different Cloudflare account.`, ); } + if ( + existing?.deployment.emailSenderDomain && + input.emailSenderDomain && + existing.deployment.emailSenderDomain !== input.emailSenderDomain.trim().toLowerCase() + ) { + throw new Error( + 'platform: The shared email sender domain is already recorded for this installation.', + ); + } const installationSlug = normalizeInstallationSlug(input.installationSlug); const installationId = existing?.id ?? @@ -147,10 +159,31 @@ export async function createPlatformInstallPlan( proxyHostname: null, }, displayName: input.displayName, + ...(existing?.deployment.emailSharedZoneId || input.emailSharedZoneId + ? { emailSharedZoneId: existing?.deployment.emailSharedZoneId ?? input.emailSharedZoneId } + : {}), + ...(existing?.deployment.emailSenderDomain || input.emailSenderDomain + ? { emailSenderDomain: existing?.deployment.emailSenderDomain ?? input.emailSenderDomain } + : {}), installationSlug, resources: existing?.deployment.resources ?? createPlatformResourceNames(installationSlug), }); - if (existing && JSON.stringify(existing.deployment) !== JSON.stringify(deployment)) { + const { + emailSharedZoneId: configuredEmailZone, + emailSenderDomain: configuredSenderDomain, + ...deploymentWithoutEmailZone + } = deployment; + const { + emailSharedZoneId: recordedEmailZone, + emailSenderDomain: recordedSenderDomain, + ...existingWithoutEmailZone + } = existing?.deployment ?? deployment; + if ( + existing && + (JSON.stringify(existingWithoutEmailZone) !== JSON.stringify(deploymentWithoutEmailZone) || + (recordedEmailZone !== undefined && recordedEmailZone !== configuredEmailZone) || + (recordedSenderDomain !== undefined && recordedSenderDomain !== configuredSenderDomain)) + ) { throw new Error( `platform: --resume inputs do not match installation ${existing.id}. Use its recorded configuration.`, ); @@ -266,6 +299,7 @@ export async function createPlatformInstallPlan( for (const [key, name] of [ ['api-worker', names.apiWorker], ['proxy-worker', names.proxyWorker], + ['email-gateway-worker', names.emailGatewayWorker], ['tail-worker', names.tailWorker], ['dispatch-worker', names.dispatchWorker], ] as const) { @@ -495,6 +529,9 @@ export async function createPlatformInstallPlan( for (const [key, name] of [ ['api-worker', names.apiWorker], ['proxy-worker', names.proxyWorker], + ...(options?.includeEmailGateway === false + ? [] + : ([['email-gateway-worker', names.emailGatewayWorker]] as const)), ['tail-worker', names.tailWorker], ['dispatch-worker', names.dispatchWorker], ] as const) { @@ -561,7 +598,10 @@ export async function revalidatePlatformInstallAction( zoneName: deployment.application.zoneName, }, manifest, - options, + { + ...options, + includeEmailGateway: original.actions.some((entry) => entry.key === 'email-gateway-worker'), + }, ); const current = refreshed.actions.find((entry) => entry.key === action.key); if ( @@ -942,6 +982,7 @@ const RESOURCE_NAME_KEY_BY_ACTION: Readonly< 'isr-cache-kv': 'isrCacheKv', 'legacy-assets-kv': 'legacyAssetsKv', 'proxy-worker': 'proxyWorker', + 'email-gateway-worker': 'emailGatewayWorker', 'routing-kv': 'routingKv', 'tail-worker': 'tailWorker', 'usage-queue': 'usageQueue', diff --git a/packages/void/src/router/compile.ts b/packages/void/src/router/compile.ts index 5647b3630..698398354 100644 --- a/packages/void/src/router/compile.ts +++ b/packages/void/src/router/compile.ts @@ -2853,6 +2853,7 @@ ${renderBlock} const internalRouteHelper = `async function __handleInternal(request, env, ctx) { const url = new URL(request.url); + ${hasEmail ? `if (url.pathname === "/__void/email/receipt/v1") return __handleEmailReceipt(request, env, ctx);` : ''} // Readiness probe — platform polls this to confirm the worker is live after WfP upload. // Handled here (before app.fetch) so user middleware cannot block it. if (request.method === "GET" && url.pathname === "/__void/ready") { @@ -2897,7 +2898,7 @@ ${envValidateCall}${isrDeploymentStamp} const userEnv = __filterInternalBinding const emailImport = hasEmail ? ', __emailHandler' : ''; const emailRuntimePath = runtimeEmailPath ?? deriveEmailRuntimePath(runtimeEnvPath); const emailProxyImport = hasEmail - ? `import { createMessageProxy as __createMessageProxy, enactEmailActions as __enactEmailActions, isForwardableEmailMessage as __isForwardableEmailMessage } from ${JSON.stringify(emailRuntimePath)};\n` + ? `import { createMessageProxy as __createMessageProxy, enactEmailActions as __enactEmailActions, isForwardableEmailMessage as __isForwardableEmailMessage } from ${JSON.stringify(emailRuntimePath)};\nimport { EMAIL_PROTOCOL_VERSION as __EMAIL_PROTOCOL_VERSION, encodeEmailActions as __encodeEmailActions, readEmailEnvelope as __readEmailEnvelope } from "void/_email-protocol";\n` : ''; // `__VOID_PROJECT_SLUG` is the same binding the outbound `sendEmail` reads to // default `from`. It is passed to `createMessageProxy` so the user-visible @@ -2938,6 +2939,37 @@ ${envValidateCall} const userEnv = __filterInternalBindings(env); }` : ''; + const emailReceiptHandler = hasEmail + ? `async function __handleEmailReceipt(request, env, ctx) { + if (request.method !== "POST" || request.headers.get("content-encoding")) return new Response(null, { status: 404 }); + const __token = request.headers.get("x-void-email-receipt"); + const __recipient = request.headers.get("x-void-email-recipient"); + if (!__token || __token.length > 1536 || !__recipient || __recipient.length > 320 || + !env.__VOID_PROXY_TOKEN || !env.__PROJECT_ID || !env.__VOID_EMAIL_DEPLOYMENT_ID || !env.__VOID_PROXY) { + return new Response(null, { status: 404 }); + } + const __verificationBody = JSON.stringify({ receipt: __token, projectId: env.__PROJECT_ID, + deploymentId: env.__VOID_EMAIL_DEPLOYMENT_ID, recipient: __recipient }); + const __verification = await env.__VOID_PROXY.fetch("https://proxy/email/verify-receipt", { + method: "POST", + headers: { "content-type": "application/json", "x-void-internal": env.__VOID_PROXY_TOKEN }, + body: __verificationBody, + }); + if (!__verification.ok) return new Response(null, { status: 404 }); + const __verified = await __verification.json(); + if (__verified?.valid !== true) return new Response(null, { status: 404 }); + let __envelope; + try { __envelope = await __readEmailEnvelope(request.body); } + catch { return new Response(null, { status: 400 }); } + if (__envelope.to !== __recipient) return new Response(null, { status: 400 }); + const __actions = await handleEmail(__envelope, env, ctx); + return new Response(__encodeEmailActions(__actions), { + headers: { "content-type": "application/vnd.void.email-actions; version=" + __EMAIL_PROTOCOL_VERSION, + "cache-control": "no-store" }, + }); +}` + : ''; + // The default export is a `WorkerEntrypoint` subclass. A plain default object // only exposes `.fetch()` through a Workers-for-Platforms dispatch stub, so // `email()` would be unreachable; class methods on a `WorkerEntrypoint` @@ -2963,6 +2995,7 @@ ${internalRouteHelper} ${fetchDeclaration} ${scheduledHandler} ${emailHandler} +${emailReceiptHandler} async function __voidQueue(batch, env, ctx) { ${envValidateCall}${remotePath ? ` if (env.__VOID_REMOTE === "1") env = ${createRemoteEnvCall};\n` : ''}${isrDeploymentStamp} const userEnv = __filterInternalBindings(env); const messages = [...batch.messages].map(m => ({ @@ -2996,6 +3029,7 @@ ${internalRouteHelper} ${fetchDeclaration} ${scheduledHandler} ${emailHandler} +${emailReceiptHandler} ${webSocketClasses.map((name) => `export { ${name} };`).join('\n')} ${liveExport} ${sandboxExport} diff --git a/packages/void/src/runtime/email-protocol.ts b/packages/void/src/runtime/email-protocol.ts new file mode 100644 index 000000000..d57c00109 --- /dev/null +++ b/packages/void/src/runtime/email-protocol.ts @@ -0,0 +1,7 @@ +// Generated email handlers import the wire protocol through Void so consumer +// projects do not need a direct dependency on @void/platform. +export { + EMAIL_PROTOCOL_VERSION, + encodeEmailActions, + readEmailEnvelope, +} from '@void/platform/email-protocol'; diff --git a/packages/void/src/runtime/email.ts b/packages/void/src/runtime/email.ts index d6fdac4d3..a16b0a0a0 100644 --- a/packages/void/src/runtime/email.ts +++ b/packages/void/src/runtime/email.ts @@ -2,10 +2,8 @@ // // On the managed platform, user worker code never holds a `send_email` // binding directly. The framework builds MIME locally, then POSTs to -// `__VOID_PROXY/email/send`. The proxy worker holds the platform-level -// `send_email` binding and enforces per-project quotas, suspend kill-switch, -// and verified-destinations allowlist (mirrored from `email_destinations` -// into KV by the API on every CRUD). +// `__VOID_PROXY/email/send`. The platform gateway enforces authoritative +// project policy and quotas and records each provider submission's outcome. // // On the developer's own Cloudflare account (`void deploy --platform // cloudflare`) there is no proxy: the deploy provisions a `send_email` @@ -34,6 +32,7 @@ import { } from './email/dev-inbox.ts'; import { buildMime, MimeError, normalizeEmail } from './email/mime.ts'; import type { + EmailDeliveryState, NormalizedEmail, SendEmailDelivery, SendEmailErrorCode, @@ -47,6 +46,7 @@ import { getRawRuntimeEnv } from './env-raw.ts'; export type { Address, Attachment, + EmailDeliveryState, NormalizedEmail, SendEmailDelivery, SendEmailError, @@ -371,19 +371,23 @@ interface ProxySendBody { mimeBase64: string; byteSize: number; requestId: string; + idempotencyKey?: string; fromDomain: string; } interface ProxyOkResponse { ok: true; ids: Array; + operationId?: string; } interface ProxyPreflightFailure { ok: false; error: { code: SendEmailErrorCode | string; message: string }; + operationId?: string; } interface ProxyMidBatchFailure { ok: false; + operationId?: string; deliveries: Array<{ recipient: string; ok: boolean; @@ -401,6 +405,8 @@ function coerceErrorCode(code: unknown): SendEmailErrorCode { 'UNVERIFIED_DESTINATION', 'MIME_ERROR', 'QUOTA_EXCEEDED', + 'IDEMPOTENCY_CONFLICT', + 'OUTCOME_UNKNOWN', 'UPSTREAM_ERROR', ]; return known.includes(code as SendEmailErrorCode) @@ -530,7 +536,11 @@ function readDeliveryList( '{ recipient: string, messageId: string }', (entry, recipient) => typeof entry.messageId === 'string' - ? { recipient, messageId: entry.messageId || fallbackId } + ? { + recipient, + messageId: entry.messageId || fallbackId, + ...(entry.state === 'provider_accepted' ? { state: 'provider_accepted' as const } : {}), + } : undefined, ); } @@ -557,13 +567,25 @@ function readFailureDeliveries( (entry, recipient) => { if (entry.ok === true) { return typeof entry.messageId === 'string' - ? { recipient, ok: true, messageId: entry.messageId || fallbackId } + ? { + recipient, + ok: true, + messageId: entry.messageId || fallbackId, + ...(entry.state === 'provider_accepted' + ? { state: 'provider_accepted' as const } + : {}), + } : undefined; } if (entry.ok === false) { const error = entry.error as { code?: unknown; message?: unknown } | null | undefined; return typeof error === 'object' && error !== null && typeof error.message === 'string' - ? { recipient, ok: false, error: makeError(coerceErrorCode(error.code), error.message) } + ? { + recipient, + ok: false, + error: makeError(coerceErrorCode(error.code), error.message), + ...(readDeliveryState(entry.state) ? { state: readDeliveryState(entry.state) } : {}), + } : undefined; } return undefined; @@ -571,6 +593,19 @@ function readFailureDeliveries( ); } +function readDeliveryState(value: unknown): EmailDeliveryState | undefined { + const states: ReadonlyArray = [ + 'rejected', + 'reserved', + 'attempt_started', + 'provider_accepted', + 'failed', + 'outcome_unknown', + 'cancelled', + ]; + return states.find((state) => state === value); +} + async function readResponseAsResult( res: Response, recipients: ReadonlyArray, @@ -581,7 +616,10 @@ async function readResponseAsResult( try { body = await res.json(); } catch { - return err('UPSTREAM_ERROR', `email: proxy returned ${res.status} with non-JSON body`); + return err( + 'OUTCOME_UNKNOWN', + `email: could not establish the send outcome (status ${res.status}); check email logs or repeat the same idempotency key`, + ); } if (!isValidProxyResponse(body)) { // The proxy's own middleware — auth, platform lifecycle, capability @@ -597,7 +635,7 @@ async function readResponseAsResult( return err('UPSTREAM_ERROR', `email: proxy returned ${res.status}: ${refusal}`, body); } return err( - 'UPSTREAM_ERROR', + 'OUTCOME_UNKNOWN', `email: proxy returned malformed response (status ${res.status})`, body, ); @@ -606,21 +644,38 @@ async function readResponseAsResult( // recipients this send asked for (`ids` / `deliveries` are `unknown[]` // from the typeguard's perspective). const malformedList = (reason: string): SendEmailResult => - err('UPSTREAM_ERROR', `email: proxy returned a malformed delivery list (${reason})`, body); + err( + 'OUTCOME_UNKNOWN', + `email: proxy returned a malformed delivery list (${reason}); do not retry with a new idempotency key`, + body, + ); + const operation = + typeof body.operationId === 'string' && body.operationId.length <= 128 + ? { operationId: body.operationId } + : {}; if (body.ok === true) { const list = readDeliveryList(body.ids as Array, recipients, fallbackId); - return list.ok ? { ok: true, ids: list.entries } : malformedList(list.reason); + return list.ok ? { ok: true, ids: list.entries, ...operation } : malformedList(list.reason); } // Treat the body as a flat record from here — the discriminated // union narrowing fights the `unknown`-derived branches and adds // little value once we've validated the shape via isValidProxyResponse. const failure = body as unknown as Record; + if (Array.isArray(failure.deliveries)) { + const list = readFailureDeliveries(failure.deliveries, recipients, fallbackId); + return list.ok + ? { ok: false, deliveries: list.entries, ...operation } + : malformedList(list.reason); + } if ('error' in failure && failure.error) { const e = failure.error as { code?: unknown; message?: unknown }; - return err( - coerceErrorCode(e.code), - typeof e.message === 'string' ? e.message : 'email: upstream send failed', - ); + return { + ...err( + coerceErrorCode(e.code), + typeof e.message === 'string' ? e.message : 'email: upstream send failed', + ), + ...operation, + }; } // Mid-batch — per-recipient outcomes, one per requested recipient, so // the caller can retry exactly the failed ones. @@ -629,13 +684,15 @@ async function readResponseAsResult( recipients, fallbackId, ); - return list.ok ? { ok: false, deliveries: list.entries } : malformedList(list.reason); + return list.ok + ? { ok: false, deliveries: list.entries, ...operation } + : malformedList(list.reason); } catch (e) { // Defense-in-depth: any unexpected error parsing the proxy response // becomes a clean UPSTREAM_ERROR rather than escaping `sendEmail` as // an unhandled rejection. return err( - 'UPSTREAM_ERROR', + 'OUTCOME_UNKNOWN', `email: failed to parse proxy response (status ${res.status}): ${e instanceof Error ? e.message : String(e)}`, e, ); @@ -820,6 +877,15 @@ function capturedResult(normalized: NormalizedEmail, captureId: string): SendEma * override for a single call. */ export async function sendEmail(opts: SendEmailOptions): Promise { + if ( + opts.idempotencyKey !== undefined && + (typeof opts.idempotencyKey !== 'string' || !/^[\x21-\x7e]{1,128}$/.test(opts.idempotencyKey)) + ) { + return err( + 'MIME_ERROR', + 'email: idempotencyKey must contain 1–128 printable non-space ASCII characters.', + ); + } const resolvedOpts = resolveDefaultFrom(opts); if (resolvedOpts.from === undefined) { return err( @@ -892,6 +958,12 @@ export async function sendEmail(opts: SendEmailOptions): Promise { - if (message.rawSize > MAX_MESSAGE_BYTES) { + if (message.rawSize > MAX_INBOUND_BYTES) { throw new ParseEmailError( 'INBOUND_TOO_LARGE', - `parseEmail: message size ${message.rawSize} bytes exceeds maximum of ${MAX_MESSAGE_BYTES} bytes.`, + `parseEmail: message size ${message.rawSize} bytes exceeds maximum of ${MAX_INBOUND_BYTES} bytes.`, ); } const { default: PostalMime } = await import('postal-mime'); @@ -309,7 +305,7 @@ function stripSlugFromAddress(address: string, slug: string | undefined): string function replyTooLarge(size: number): MimeError { return new MimeError( 'MIME_ERROR', - `reply: message size ${size} bytes exceeds Cloudflare limit of ${MAX_MESSAGE_BYTES} bytes.`, + `reply: message size ${size} bytes exceeds Void's sending limit of ${MAX_REPLY_BYTES} bytes.`, ); } @@ -660,7 +656,18 @@ export function createMessageProxy( if (headersObj) { assertForwardHeadersWithinBounds(headersObj); } - actions.push({ type: 'forward', to, ...(headersObj ? { headers: headersObj } : {}) }); + const action = { + type: 'forward' as const, + to, + ...(headersObj ? { headers: headersObj } : {}), + }; + if (new TextEncoder().encode(JSON.stringify(action)).byteLength > MAX_ACTION_METADATA_BYTES) { + throw new MimeError( + 'MIME_ERROR', + `forward: action metadata exceeds ${MAX_ACTION_METADATA_BYTES} bytes.`, + ); + } + actions.push(action); }, async reply(reply: { from: string; to: string; raw: ReadableStream | Uint8Array }) { if (rejected) { @@ -690,7 +697,7 @@ export function createMessageProxy( const remaining = MAX_REPLY_BYTES_TOTAL - replyBytesUsed; let rawBytes: Uint8Array; if (reply.raw instanceof Uint8Array) { - if (reply.raw.byteLength > MAX_MESSAGE_BYTES) { + if (reply.raw.byteLength > MAX_REPLY_BYTES) { throw replyTooLarge(reply.raw.byteLength); } if (reply.raw.byteLength > remaining) { @@ -719,9 +726,9 @@ export function createMessageProxy( // already spent part of it, and the stream must stop where the budget // does. Whichever bound is lower is the one that fires, so the // callback names the one that actually bound this read. - const limit = Math.min(MAX_MESSAGE_BYTES, remaining); + const limit = Math.min(MAX_REPLY_BYTES, remaining); rawBytes = await readStreamToBytes(reply.raw, limit, (total) => - limit === MAX_MESSAGE_BYTES + limit === MAX_REPLY_BYTES ? replyTooLarge(total) : replyBudgetExhausted(replyBytesUsed + total), ); diff --git a/packages/void/src/runtime/email/mime.ts b/packages/void/src/runtime/email/mime.ts index 02a617df9..340169c38 100644 --- a/packages/void/src/runtime/email/mime.ts +++ b/packages/void/src/runtime/email/mime.ts @@ -9,8 +9,8 @@ import { validate as isValidEmailSyntax } from 'email-validator'; import type { Address, Attachment, NormalizedAttachment, NormalizedEmail } from './types.ts'; -/** Cloudflare Email Workers reject messages larger than ~10 MB after base64 expansion. */ -export const MAX_MESSAGE_BYTES: number = 10 * 1024 * 1024; +/** Encoded outbound MIME ceiling, separate from the 10 MiB inbound limit. */ +export const MAX_MESSAGE_BYTES: number = 5 * 1024 * 1024; /** * Upper bound on the TOTAL attachment bytes `normalizeEmail` will materialize. @@ -43,7 +43,7 @@ const MAX_ATTACHMENT_BYTES_TOTAL: number = Math.floor((MAX_MESSAGE_BYTES * 3) / * Cap on the recipient count across `to`, `cc` and `bcc`, checked against * the RAW input before a single address is parsed. * - * The platform proxy refuses more than 100 recipients (`MAX_RECIPIENTS` in + * The platform proxy refuses more than 50 recipients (`MAX_RECIPIENTS` in * `proxy/src/email.ts`, counted on the deduplicated list this module * produces), so on the platform a larger list is always rejected — but only * after the tenant has parsed every address and rendered the whole `To:` @@ -64,7 +64,7 @@ const MAX_ATTACHMENT_BYTES_TOTAL: number = Math.floor((MAX_MESSAGE_BYTES * 3) / * this bound exists to skip, so a list of 150 entries with 100 unique * addresses is refused here where the proxy would have accepted it. */ -export const MAX_RECIPIENTS: number = 100; +export const MAX_RECIPIENTS: number = 50; /** * Pre-parse cap on one parsed address, in characters. RFC 5321 §4.5.3.1 @@ -749,6 +749,7 @@ export async function normalizeEmail(opts: { rejectCRLF('subject', opts.subject); } if (opts.headers) { + let headerBytes = 0; for (const [name, value] of Object.entries(opts.headers)) { if (!HEADER_NAME.test(name)) { throw new MimeError( @@ -774,6 +775,13 @@ export async function normalizeEmail(opts: { `so its line would exceed the ${MAX_LINE_OCTETS}-octet limit in RFC 5322 §2.1.1. Shorten the name.`, ); } + if (headerBytes + name.length + value.length + 4 > 16 * 1024) { + throw new MimeError('MIME_ERROR', 'email: custom headers exceed the 16 KiB limit.'); + } + headerBytes += name.length + new TextEncoder().encode(value).byteLength + 4; + if (headerBytes > 16 * 1024) { + throw new MimeError('MIME_ERROR', 'email: custom headers exceed the 16 KiB limit.'); + } rejectCRLF(`header '${name}'`, value); } } diff --git a/packages/void/src/runtime/email/types.ts b/packages/void/src/runtime/email/types.ts index bda176538..334d82b95 100644 --- a/packages/void/src/runtime/email/types.ts +++ b/packages/void/src/runtime/email/types.ts @@ -34,6 +34,12 @@ export interface SendEmailOptions { bcc?: Address | Array
; headers?: Record; attachments?: Array; + /** + * Deduplicates a platform send for 30 days. Reuse the same key and message + * when checking an uncertain attempt; a changed message is a conflict. + * Native Cloudflare bindings do not provide this guarantee. + */ + idempotencyKey?: string; /** * Per-call escape hatch for local development. When true, bypasses the * `void dev` in-memory inbox for this one send. @@ -58,6 +64,8 @@ export type SendEmailErrorCode = | 'UNVERIFIED_DESTINATION' | 'MIME_ERROR' | 'QUOTA_EXCEEDED' + | 'IDEMPOTENCY_CONFLICT' + | 'OUTCOME_UNKNOWN' | 'UPSTREAM_ERROR'; export interface SendEmailError { @@ -74,16 +82,26 @@ export interface SendEmailError { export interface SendEmailDelivery { recipient: string; messageId: string; + state?: 'provider_accepted'; } +export type EmailDeliveryState = + | 'rejected' + | 'reserved' + | 'attempt_started' + | 'provider_accepted' + | 'failed' + | 'outcome_unknown' + | 'cancelled'; + /** * Per-recipient outcome for a multi-recipient send. `ok: true` carries the * CF-issued messageId; `ok: false` carries the error for that specific * recipient (e.g. one address is unverified while others succeed). */ export type SendEmailRecipientResult = - | { recipient: string; ok: true; messageId: string } - | { recipient: string; ok: false; error: SendEmailError }; + | { recipient: string; ok: true; messageId: string; state?: 'provider_accepted' } + | { recipient: string; ok: false; error: SendEmailError; state?: EmailDeliveryState }; /** * Result of `sendEmail`. @@ -93,20 +111,19 @@ export type SendEmailRecipientResult = * `'deliveries' in result` (per-recipient failure, some may have succeeded): * * - `{ ok: true, ids }` — every envelope succeeded. - * - `{ ok: false, error }` — pre-flight failure (validation, MIME, - * missing binding); no envelopes attempted. + * - `{ ok: false, error }` — validation or transport failure. An + * OUTCOME_UNKNOWN may have been submitted; + * never retry it with a new idempotency key. * - `{ ok: false, deliveries }` — sends were attempted; at least one failed. * `deliveries` carries the per-recipient - * outcome so callers can safely retry only - * the failed ones. There is no aggregate - * top-level error — distinct recipients can - * fail with distinct errors, and picking one - * would be arbitrary. + * outcome. Provider acceptance does not + * establish mailbox delivery. Unknown + * outcomes must not be blindly retried. */ export type SendEmailResult = - | { ok: true; ids: Array } - | { ok: false; error: SendEmailError } - | { ok: false; deliveries: Array }; + | { ok: true; ids: Array; operationId?: string } + | { ok: false; error: SendEmailError; operationId?: string } + | { ok: false; deliveries: Array; operationId?: string }; /** * Normalized representation produced by validation, consumed by both the diff --git a/packages/void/test/unit/cli-help.test.ts b/packages/void/test/unit/cli-help.test.ts index 2849939fd..d19380a43 100644 --- a/packages/void/test/unit/cli-help.test.ts +++ b/packages/void/test/unit/cli-help.test.ts @@ -176,7 +176,7 @@ describe('rendered help advertises the flags the parser honours', () => { }); const group = render(['email']); - expect(group).toContain('domain '); + expect(group).toContain('domain '); expect(hasHelpPage(['email', 'domain'])).toBe(true); expect(getHelpPath(['email', 'domain', '--help'])).toEqual(['email', 'domain']); @@ -186,6 +186,7 @@ describe('rendered help advertises the flags the parser honours', () => { 'status ', 'list', 'sync ', + 'rotate-secret ', 'remove ', ]) { expect(page).toContain(verb); @@ -193,7 +194,7 @@ describe('rendered help advertises the flags the parser honours', () => { expect(page).toContain('--subdomain '); expect(page).toContain('--project '); - for (const verb of ['add', 'status', 'list', 'sync', 'remove']) { + for (const verb of ['add', 'status', 'list', 'sync', 'rotate-secret', 'remove']) { expect(hasHelpPage(['email', 'domain', verb])).toBe(true); } expect(render(['email', 'domain', 'add'])).toContain( diff --git a/packages/void/test/unit/email-cli-disallow.test.ts b/packages/void/test/unit/email-cli-disallow.test.ts index 97a34e539..216f761dd 100644 --- a/packages/void/test/unit/email-cli-disallow.test.ts +++ b/packages/void/test/unit/email-cli-disallow.test.ts @@ -61,7 +61,9 @@ describe('void email disallow', () => { expect(c.removeEmailDestination).toHaveBeenCalledWith('prj_1', 'edst_1'); const text = printed(successSpy); - expect(text).toBe(`Removed ${ADDRESS}. Sends to it are refused within about a minute.`); + expect(text).toBe( + `Removed ${ADDRESS}. New sends to it are refused immediately; already admitted attempts may finish.`, + ); // The api tightens the KV allowlist in the DELETE and the proxy's // cacheTtl bounds convergence; nothing about a revoke waits for a deploy. expect(text).not.toMatch(/deploy/); diff --git a/packages/void/test/unit/email-cli-domain.test.ts b/packages/void/test/unit/email-cli-domain.test.ts index 4e5933b32..000bc4498 100644 --- a/packages/void/test/unit/email-cli-domain.test.ts +++ b/packages/void/test/unit/email-cli-domain.test.ts @@ -15,10 +15,10 @@ import { emailDomainRemove, emailDomainStatus, emailDomainSync, + emailDomainRotateSecret, isValidEmailDomainInput, normalizeEmailDomainInput, resolveEmailDomainTarget, - type CfTokenVerification, type EmailDomainAddDeps, } from '../../src/cli/email.ts'; @@ -35,9 +35,10 @@ vi.mock('@clack/prompts', async (importOriginal) => { const LEGACY_TOKEN = `Lgcy-${'a1'.repeat(17)}B`; // 40 chars, [A-Za-z0-9_-] const CFUT_TOKEN = `cfut_${'c0'.repeat(20)}${'deed'.repeat(2)}`; // 40-char core + checksum tail -const GRANT_SENTINEL = 'grant-refresh-token-placeholder'; /** The default platform: owners register their own domains. */ -const selfServeSettings = async () => ({ domains: { management: 'self-serve' as const } }); +const selfServeSettings = async (): Promise<{ + domains: { management: 'self-serve' | 'admin' }; +}> => ({ domains: { management: 'self-serve' } }); const noEmailDomains = async (): Promise> => []; type LogSpy = ReturnType; @@ -237,1224 +238,255 @@ describe('PlatformClient.getEmailSettings', () => { }); describe('emailDomainAdd', () => { - // The fixed per-invocation attempt id the randomUUID spy returns. const ATTEMPT_ID = '11111111-2222-4333-8444-555555555555'; - function addDeps(overrides: Partial = {}): EmailDomainAddDeps { return { dns: { resolveMx: vi.fn(async () => []) }, - runGrant: vi.fn(async () => ({ refreshToken: GRANT_SENTINEL })), isInteractive: true, + openUrl: vi.fn(), + readClipboard: () => null, + clearClipboard: vi.fn(), + pasteToken: vi.fn(async () => LEGACY_TOKEN), + confirmScope: vi.fn(async () => true), + verifyToken: vi.fn(async () => 'active' as const), waitForEnter: neverEnter, watchIntervalMs: 1, - watchTimeoutMs: 50, - // Instant reconcile polls — the loop is bounded by attempt count. + watchTimeoutMs: 40, sleep: vi.fn(async () => {}), exit: exitSpy(), ...overrides, }; } - - /** Pins the per-invocation attempt id (restored by the outer afterEach). */ - function mockAttemptId(id: string = ATTEMPT_ID): void { - vi.spyOn(crypto, 'randomUUID').mockReturnValue(id as ReturnType); + function client() { + return { + addEmailDomain: vi.fn(async () => domainRow({ credential_kind: 'api_token' })), + getEmailDomain: vi.fn(async () => statusRow()), + getEmailOperation: vi.fn(async () => ({ + operationId: 'op_1', + attemptId: ATTEMPT_ID, + status: 'completed' as const, + domain: 'acme.com', + readiness: { + inbound: { status: 'ready' as const }, + outbound: { status: 'ready' as const }, + management: { status: 'healthy' as const }, + }, + })), + getEmailSettings: vi.fn(selfServeSettings), + listEmailDomains: vi.fn(noEmailDomains), + }; } - it('runs the grant and POSTs the refresh token for an MX-empty apex', async () => { - const addEmailDomain = vi.fn(async () => domainRow({ domain: 'acme.com', mode: 'apex' })); + it('uses scoped API-token setup and submits no OAuth grant', async () => { + const api = client(); const deps = addDeps(); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - deps, - ); - - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'acme.com', - refreshToken: GRANT_SENTINEL, - attemptId: expect.any(String), - }); - expect(printed(infoSpy)).toContain('acme.com has no MX records → using the apex'); - expect(printed(successSpy)).toContain( - 'Grant stored on the platform, encrypted for this project — nothing is kept on this machine.', - ); - expect(notedBlocks()).toContain('Domain: acme.com'); - expect(notedBlocks()).toContain('Mode: apex'); - // The credential never reaches an output. - expect(printed(infoSpy) + printed(successSpy) + notedBlocks()).not.toContain(GRANT_SENTINEL); - }); - - it('prints the administrator command and stops on an admin-managed platform', async () => { - const addEmailDomain = vi.fn(); - const runGrant = vi.fn(); - const resolveMx = vi.fn(async () => []); - const exit = exitSpy(); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - }), - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ runGrant, dns: { resolveMx }, exit }), - ), - ).rejects.toThrow('exit 0'); - - expect(printed(infoSpy)).toContain( - 'Email domains on this platform are managed by its administrator.', - ); - expect(printed(infoSpy)).toContain( - 'void platform email domain-add acme.com --project hr-portal', - ); - // The target was decided, but no browser or POST ran — and exit was clean. - expect(resolveMx).toHaveBeenCalledWith('acme.com'); - expect(runGrant).not.toHaveBeenCalled(); - expect(addEmailDomain).not.toHaveBeenCalled(); - expect(exit).toHaveBeenCalledWith(0); - }); - - it('prints the mail subdomain for an admin-managed apex that already receives mail', async () => { - const addEmailDomain = vi.fn(); - const runGrant = vi.fn(); - const resolveMx = vi.fn(async (name: string) => - name === 'acme.com' ? [{ exchange: 'aspmx.l.google.com.', priority: 1 }] : [], - ); - const exit = exitSpy(); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - }), - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ runGrant, dns: { resolveMx }, exit }), - ), - ).rejects.toThrow('exit 0'); - - expect(printed(infoSpy)).toContain('acme.com carries MX for aspmx.l.google.com'); - expect(printed(infoSpy)).toContain( - 'void platform email domain-add mail.acme.com --project hr-portal', - ); - expect(runGrant).not.toHaveBeenCalled(); - expect(addEmailDomain).not.toHaveBeenCalled(); - expect(exit).toHaveBeenCalledWith(0); - }); - - it('keeps a forced admin-managed subdomain in the printed command and warns on its MX', async () => { - const addEmailDomain = vi.fn(); - const runGrant = vi.fn(); - const resolveMx = vi.fn(async () => [{ exchange: 'aspmx.l.google.com.', priority: 1 }]); - const exit = exitSpy(); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - }), - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - 'mx', - addDeps({ runGrant, dns: { resolveMx }, exit }), - ), - ).rejects.toThrow('exit 0'); - - expect(resolveMx).toHaveBeenCalledWith('mx.acme.com'); - expect(printed(warnSpy)).toContain('mx.acme.com already carries MX'); - expect(printed(warnSpy)).toContain('may refuse it'); - expect(printed(infoSpy)).toContain( - 'void platform email domain-add mx.acme.com --project hr-portal', - ); - expect(runGrant).not.toHaveBeenCalled(); - expect(addEmailDomain).not.toHaveBeenCalled(); - }); - - it('prints the administrator command when the target is already an administrator row', async () => { - const addEmailDomain = vi.fn(); - const runGrant = vi.fn(); - const resolveMx = vi.fn(async () => []); - const exit = exitSpy(); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - }), - listEmailDomains: async () => [domainRow({ managed_by: 'admin' })], - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ runGrant, dns: { resolveMx }, exit }), - ), - ).rejects.toThrow('exit 0'); - - expect(printed(infoSpy)).toContain( - 'void platform email domain-add acme.com --project hr-portal', - ); - expect(resolveMx).toHaveBeenCalledWith('acme.com'); - expect(runGrant).not.toHaveBeenCalled(); - expect(addEmailDomain).not.toHaveBeenCalled(); - }); - - it.each([ - ['an explicit owner row', 'owner' as const], - ['a row from an older api without managed_by', undefined], - ])( - 'continues the renewal flow for %s on an admin-managed platform', - async (_label, managedBy) => { - const addEmailDomain = vi.fn(async () => - domainRow({ domain: 'mail.acme.com', mode: 'subdomain', managed_by: managedBy }), - ); - const runGrant = vi.fn(async () => ({ refreshToken: GRANT_SENTINEL })); - const resolveMx = vi.fn(async () => [{ exchange: 'aspmx.l.google.com.', priority: 1 }]); - const exit = exitSpy(); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - }), - listEmailDomains: async () => [ - domainRow({ domain: 'mail.acme.com', managed_by: managedBy }), - ], - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ runGrant, dns: { resolveMx }, exit }), - ); - - expect(resolveMx).not.toHaveBeenCalled(); - expect(printed(infoSpy)).toContain( - 'Renewing mail.acme.com — the stored credential is replaced; rules and the relay stay.', - ); - expect(runGrant).toHaveBeenCalled(); - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'mail.acme.com', - refreshToken: GRANT_SENTINEL, - attemptId: expect.any(String), - }); - expect(exit).not.toHaveBeenCalledWith(0); - }, - ); - - it.each([ - ['an apex row', 'acme.com'], - ['an already-prefixed mail row', 'mail.acme.com'], - ])('renews %s without re-running the MX decision', async (_label, existingDomain) => { - const addEmailDomain = vi.fn(async () => domainRow({ domain: existingDomain })); - const runGrant = vi.fn(async () => ({ refreshToken: GRANT_SENTINEL })); - const resolveMx = vi.fn(async () => [{ exchange: 'route1.mx.cloudflare.net.', priority: 10 }]); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - }), - listEmailDomains: async () => [domainRow({ domain: existingDomain, managed_by: 'owner' })], - }, - 'prj_1', - existingDomain, - undefined, - addDeps({ runGrant, dns: { resolveMx } }), - ); - - expect(resolveMx).not.toHaveBeenCalled(); - expect(printed(infoSpy)).toContain(`Renewing ${existingDomain}`); - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: existingDomain, - refreshToken: GRANT_SENTINEL, - attemptId: expect.any(String), - }); - }); - - it('proposes mail. when the apex carries MX, and says so', async () => { - const addEmailDomain = vi.fn(async () => - domainRow({ domain: 'mail.acme.com', mode: 'subdomain' }), - ); - const resolveMx = vi.fn(async (name: string) => - name === 'acme.com' ? [{ exchange: 'aspmx.l.google.com.', priority: 1 }] : [], - ); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ dns: { resolveMx } }), - ); - - expect(printed(infoSpy)).toContain( - 'acme.com carries MX for aspmx.l.google.com → apex is off limits', - ); - expect(printed(infoSpy)).toContain('using mail.acme.com [change with --subdomain]'); - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'mail.acme.com', - refreshToken: GRANT_SENTINEL, - attemptId: expect.any(String), - }); - }); - - it('honours an explicit --subdomain and normalizes the positional domain', async () => { - const addEmailDomain = vi.fn(async () => - domainRow({ domain: 'mx.acme.com', mode: 'subdomain' }), - ); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - ' ACME.com. ', - 'mx', - addDeps(), - ); - - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'mx.acme.com', - refreshToken: GRANT_SENTINEL, - attemptId: expect.any(String), - }); - }); - - it('refuses an invalid domain or a foreign --subdomain before any grant', async () => { - const runGrant = vi.fn(); - const addEmailDomain = vi.fn(); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'not a domain', - undefined, - addDeps({ runGrant }), - ), - ).rejects.toThrow('exit 1'); - expect(printed(errorSpy)).toContain("email: invalid domain 'not a domain'."); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - 'other.com', - addDeps({ runGrant }), - ), - ).rejects.toThrow('exit 1'); - expect(printed(errorSpy)).toContain('--subdomain must name a subdomain of acme.com'); - expect(runGrant).not.toHaveBeenCalled(); - expect(addEmailDomain).not.toHaveBeenCalled(); - }); - - it('refuses to run non-interactively (both grant paths need a human)', async () => { - const runGrant = vi.fn(); - await expect( - emailDomainAdd( - { - addEmailDomain: vi.fn(), - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ runGrant, isInteractive: false }), - ), - ).rejects.toThrow('exit 1'); - expect(printed(errorSpy)).toContain('needs an interactive terminal'); - expect(runGrant).not.toHaveBeenCalled(); - }); - - it('falls back to the template link + clipboard watch when the grant fails', async () => { - const token = CFUT_TOKEN; - const clipboard = ['clipboard-before', token]; - let reads = 0; - const readClipboard = vi.fn(() => clipboard[Math.min(reads++, clipboard.length - 1)]!); - const clearClipboard = vi.fn(); - const verifyToken = vi.fn(async (): Promise => 'active'); - const openUrl = vi.fn(); - const addEmailDomain = vi.fn(async () => - domainRow({ credential_kind: 'api_token', domain: 'acme.com' }), - ); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ - runGrant: vi.fn(async () => { - throw new Error('cf-oauth: could not start the local callback server on port 8976.'); - }), - readClipboard, - clearClipboard, - verifyToken, - openUrl, - }), - ); - - // The failure is named, the link opened, and only the token-shaped NEW - // clipboard value was verified and POSTed. - expect(printed(warnSpy)).toContain('could not start the local callback server'); - expect(openUrl).toHaveBeenCalledWith(buildCfApiTokenTemplateUrl('acme.com')); - expect(verifyToken).toHaveBeenCalledTimes(1); - expect(clearClipboard).toHaveBeenCalledTimes(1); - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'acme.com', - apiToken: token, - attemptId: expect.any(String), - }); - expect(printed(successSpy)).toContain( - 'Token stored on the platform, encrypted for this project — nothing is kept on this machine.', - ); - expect(printed(infoSpy) + printed(successSpy) + notedBlocks()).not.toContain(token); - }); - - it('keeps watching past wrong-shape clipboard values without a network call', async () => { - const values = ['snapshot', 'ghp_' + 'a'.repeat(36), 'not a token', LEGACY_TOKEN]; - let reads = 0; - const readClipboard = vi.fn(() => values[Math.min(reads++, values.length - 1)]!); - const verifyToken = vi.fn(async (): Promise => 'active'); - const addEmailDomain = vi.fn(async () => domainRow({ credential_kind: 'api_token' })); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ - runGrant: vi.fn(async () => { - throw new Error('cf-oauth: cancelled.'); - }), - readClipboard, - clearClipboard: vi.fn(), - verifyToken, - openUrl: vi.fn(), - }), - ); - - // One verify — for the only value that passed the shape check. - expect(verifyToken).toHaveBeenCalledTimes(1); - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'acme.com', - apiToken: LEGACY_TOKEN, - attemptId: expect.any(String), - }); - }); - - it('switches to the masked paste on Enter; a cancel stores nothing', async () => { - const addEmailDomain = vi.fn(async () => domainRow({ credential_kind: 'api_token' })); - const pasteToken = vi.fn(async () => ` ${LEGACY_TOKEN}\n`); - const verifyToken = vi.fn(async (): Promise => 'active'); - // The grant hangs (it waits on a browser for minutes); Enter resolves at - // once, so the race deterministically switches paths. - const pendingGrant = vi.fn(() => new Promise(() => {})); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ - runGrant: pendingGrant, - waitForEnter: vi.fn(async () => {}), - readClipboard: vi.fn(() => 'clipboard-before'), - verifyToken, - pasteToken, - openUrl: vi.fn(), - clearClipboard: vi.fn(), - }), - ); - - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { + vi.spyOn(crypto, 'randomUUID').mockReturnValue(ATTEMPT_ID); + await emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps); + expect(api.addEmailDomain).toHaveBeenCalledWith('prj_1', { domain: 'acme.com', apiToken: LEGACY_TOKEN, - attemptId: expect.any(String), + attemptId: ATTEMPT_ID, }); - - // Esc at the paste prompt: nothing is POSTed, nothing is stored. - const addEmailDomain2 = vi.fn(); - await emailDomainAdd( - { - addEmailDomain: addEmailDomain2, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ - runGrant: pendingGrant, - waitForEnter: vi.fn(async () => {}), - readClipboard: vi.fn(() => null), - pasteToken: vi.fn(async () => null), - openUrl: vi.fn(), - }), + expect(deps.openUrl).toHaveBeenCalledWith(expect.stringContaining('/profile/api-tokens?')); + expect(deps.confirmScope).toHaveBeenCalledWith('acme.com'); + expect(printed(infoSpy)).toContain('replace All accounts and All zones'); + expect(printed(successSpy)).toContain('zone connection'); + expect([printed(infoSpy), printed(successSpy), notedBlocks()].join('')).not.toContain( + LEGACY_TOKEN, ); - expect(addEmailDomain2).not.toHaveBeenCalled(); - expect(printed(infoSpy)).toContain('Cancelled — nothing was stored anywhere.'); }); - it('stops the clipboard watch once Enter wins — no orphaned poll loop', async () => { - const addEmailDomain = vi.fn(async () => domainRow({ credential_kind: 'api_token' })); - // A constant non-token value: the poll loop keeps watching without verifying. - const readClipboard = vi.fn(() => 'clipboard-before'); - const verifyToken = vi.fn(async (): Promise => 'active'); - let resolveEnter!: () => void; - const enterPressed = new Promise((resolve) => { - resolveEnter = resolve; - }); - - const run = emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ - runGrant: vi.fn(async () => { - throw new Error('cf-oauth: cancelled.'); - }), - // The first waitForEnter arms the grant race and never fires (the - // grant's failure ends that race); the second arms the watch race and - // is fired below, once the poll loop is observably running. - waitForEnter: vi - .fn() - .mockImplementationOnce(neverEnter) - .mockImplementationOnce(() => enterPressed), - readClipboard, - clearClipboard: vi.fn(), - verifyToken, - pasteToken: vi.fn(async () => LEGACY_TOKEN), - openUrl: vi.fn(), - // Far past the observation window below, so a still-running loop - // would keep polling through it. - watchTimeoutMs: 10_000, - }), - ); - - // The watch is running: the snapshot read plus at least one interval poll. - await vi.waitFor(() => { - expect(readClipboard.mock.calls.length).toBeGreaterThanOrEqual(2); - }); - resolveEnter(); - await run; - - // Enter switched to the paste path, which POSTed the pasted token. - expect(addEmailDomain).toHaveBeenCalledWith('prj_1', { - domain: 'acme.com', - apiToken: LEGACY_TOKEN, - attemptId: expect.any(String), - }); - // The settled race stopped the poll loop: no further clipboard reads (so - // no timer chain and no stray verify from the watch) past this point. - const readsAtSettle = readClipboard.mock.calls.length; - await new Promise((resolve) => setTimeout(resolve, 30)); // ~30 watch intervals - expect(readClipboard.mock.calls.length).toBe(readsAtSettle); - expect(verifyToken).toHaveBeenCalledTimes(1); // the pasted token's check - }); - - it('refuses a pasted token shaped like another vendor’s, without a network call', async () => { - const verifyToken = vi.fn(); - const addEmailDomain = vi.fn(); - + it('does not submit a token whose scope was not confirmed', async () => { + const api = client(); await expect( emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps({ - runGrant: vi.fn(() => new Promise(() => {})), - waitForEnter: vi.fn(async () => {}), - readClipboard: vi.fn(() => null), - pasteToken: vi.fn(async () => `ghp_${'a'.repeat(36)}`), - verifyToken, - openUrl: vi.fn(), - }), - ), - ).rejects.toThrow('exit 1'); - expect(printed(errorSpy)).toContain('that looks like a different kind of token'); - expect(verifyToken).not.toHaveBeenCalled(); - expect(addEmailDomain).not.toHaveBeenCalled(); - }); - - it('refuses a pasted token Cloudflare says is not active', async () => { - const addEmailDomain = vi.fn(); - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + api, 'prj_1', 'acme.com', undefined, - addDeps({ - runGrant: vi.fn(() => new Promise(() => {})), - waitForEnter: vi.fn(async () => {}), - readClipboard: vi.fn(() => null), - pasteToken: vi.fn(async () => LEGACY_TOKEN), - verifyToken: vi.fn(async (): Promise => 'inactive'), - openUrl: vi.fn(), - }), + addDeps({ confirmScope: async () => false }), ), ).rejects.toThrow('exit 1'); - expect(printed(errorSpy)).toContain('that is not an active Cloudflare token'); - expect(addEmailDomain).not.toHaveBeenCalled(); + expect(api.addEmailDomain).not.toHaveBeenCalled(); }); - it('renders a failed row with the failed step and the retry hint', async () => { - const addEmailDomain = vi.fn(async () => - domainRow({ - status: 'failed', - setup_state: { failed_step: 'zone_lookup' }, - error: 'no Cloudflare zone found for acme.com in an account this credential can see', - }), + it('chooses a mail subdomain when the apex already receives mail', async () => { + const api = client(); + const resolveMx = vi.fn(async (name: string) => + name === 'acme.com' ? [{ exchange: 'mx.example.net', priority: 10 }] : [], ); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + await emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps({ dns: { resolveMx } })); + expect(api.addEmailDomain).toHaveBeenCalledWith( 'prj_1', - 'acme.com', - undefined, - addDeps(), + expect.objectContaining({ domain: 'mail.acme.com' }), ); - - expect(printed(errorSpy)).toContain('failed at zone lookup'); - expect(printed(errorSpy)).toContain('no Cloudflare zone found for acme.com'); - expect(printed(infoSpy)).toContain('re-run `void email domain add acme.com`'); }); - it('renders the pending row with the routing-subdomain dashboard step', async () => { - const addEmailDomain = vi.fn(async () => - domainRow({ - domain: 'mail.acme.com', - mode: 'subdomain', - status: 'pending', - setup_state: { remaining_steps: ['routing_subdomain'] }, - }), - ); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + it('honors an explicitly selected mail subdomain', async () => { + const api = client(); + await emailDomainAdd(api, 'prj_1', 'acme.com', 'notifications', addDeps()); + expect(api.addEmailDomain).toHaveBeenCalledWith( 'prj_1', - 'acme.com', - undefined, - addDeps(), + expect.objectContaining({ domain: 'notifications.acme.com' }), ); - - expect(notedBlocks()).toContain('Domain: mail.acme.com'); - expect(printed(warnSpy)).toContain('Email Routing → acme.com → Settings → Subdomains'); - expect(printed(infoSpy)).toContain('void email domain status mail.acme.com'); }); - it('renders the Workers Free hint when sending onboarding is still pending on a live row', async () => { - const addEmailDomain = vi.fn(async () => - domainRow({ - status: 'active', - setup_state: { remaining_steps: ['sending_onboarding'] }, - }), - ); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain: vi.fn(), - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), + it('rejects invalid domains before opening a browser', async () => { + const api = client(); + const deps = addDeps(); + await expect(emailDomainAdd(api, 'prj_1', 'https://acme.com', undefined, deps)).rejects.toThrow( + 'exit 1', ); - - expect(printed(infoSpy)).toContain('Workers Paid'); - expect(printed(infoSpy)).toContain('void email domain sync acme.com'); - // The row is live — the success line still prints. - expect(printed(successSpy)).toContain('acme.com is live'); + expect(deps.openUrl).not.toHaveBeenCalled(); + expect(api.addEmailDomain).not.toHaveBeenCalled(); }); - it('rethrows an API rejection without reconciling — the server already revoked the grant', async () => { - const addEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to add email domain', - 409, - '{"error":"domain is registered to another project"}', - ); - }); - const getEmailDomain = vi.fn(); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow(PlatformApiError); - // No reconciliation, no CLI-side revoke: the API's rejection owns both. - expect(getEmailDomain).not.toHaveBeenCalled(); - expect(fetchSpy).not.toHaveBeenCalled(); + it('hands new administrator-managed domains to the operator without a token flow', async () => { + const api = client(); + const deps = addDeps(); + api.getEmailSettings.mockResolvedValue({ domains: { management: 'admin' } }); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps)).rejects.toThrow( + 'exit 0', + ); + expect(deps.openUrl).not.toHaveBeenCalled(); + expect(deps.pasteToken).not.toHaveBeenCalled(); + expect(printed(infoSpy)).toContain('void platform email domain-add acme.com --project prj_1'); }); - it('routes a 500 answer through the attempt-id reconcile — the row committed', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new PlatformApiError('Failed to add email domain', 500, '{"error":"internal error"}'); - }); - // A 500 is ambiguous — the add may have committed before the error. The - // reconcile proves it did: the row carries this attempt's id. - const getEmailDomain = vi.fn(async () => statusRow({ attemptId: ATTEMPT_ID })); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + it('lets an owner renew their earlier assignment after the administrator mode switch', async () => { + const api = client(); + const deps = addDeps(); + api.getEmailSettings.mockResolvedValue({ domains: { management: 'admin' } }); + api.listEmailDomains.mockResolvedValue([domainRow({ managed_by: 'owner' })]); + await emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps); + expect(api.addEmailDomain).toHaveBeenCalledWith( 'prj_1', - 'acme.com', - undefined, - addDeps(), + expect.objectContaining({ domain: 'acme.com', apiToken: LEGACY_TOKEN }), ); - - expect(getEmailDomain).toHaveBeenCalledTimes(1); - expect(printed(warnSpy)).toContain('answer was lost'); - expect(notedBlocks()).toContain('Domain: acme.com'); - expect(fetchSpy).not.toHaveBeenCalled(); + expect(deps.dns?.resolveMx).not.toHaveBeenCalled(); }); - it('routes a 500 answer through the attempt-id reconcile — nothing persisted, the grant is revoked', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new PlatformApiError('Failed to add email domain', 500, '{"error":"internal error"}'); - }); - const getEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to fetch email domain status', - 404, - '{"error":"email domain not found"}', - ); - }); - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(null, { status: 200 }), + it('fails non-interactive setup without opening a browser', async () => { + const api = client(); + const deps = addDeps({ isInteractive: false }); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps)).rejects.toThrow( + 'exit 1', ); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - // The 500 did not prove a server-side revoke, so the CLI kills the grant - // it still holds once the polls prove nothing persisted. - expect(getEmailDomain).toHaveBeenCalledTimes(15); - expect(fetchSpy).toHaveBeenCalledTimes(1); - expect(String(fetchSpy.mock.calls[0]![0])).toBe('https://dash.cloudflare.com/oauth2/revoke'); - expect(printed(errorSpy)).toContain('was not registered'); - expect(printed(errorSpy)).toContain('was revoked'); + expect(deps.openUrl).not.toHaveBeenCalled(); }); - it('reconciles a 403 answer — a suspended account never reached the route, nothing persisted', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to add email domain', - 403, - '{"error":"account suspended"}', - ); - }); - // A 403 may come from the middleware pre-route (no parse, no revoke), so - // it reconciles like any other ambiguous answer — here the polls prove - // nothing persisted and the held grant is revoked. - const getEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to fetch email domain status', - 404, - '{"error":"email domain not found"}', - ); - }); - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(null, { status: 200 }), - ); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - expect(getEmailDomain).toHaveBeenCalledTimes(15); - expect(fetchSpy).toHaveBeenCalledTimes(1); - expect(String(fetchSpy.mock.calls[0]![0])).toBe('https://dash.cloudflare.com/oauth2/revoke'); - expect(printed(errorSpy)).toContain('was not registered'); + it('cancels masked paste without storing a credential', async () => { + const api = client(); + const deps = addDeps({ pasteToken: async () => null }); + await emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps); + expect(api.addEmailDomain).not.toHaveBeenCalled(); + expect(deps.confirmScope).not.toHaveBeenCalled(); }); - it('reconciles a 403 answer — every poll 403s too, so the state stays unknown and nothing is revoked', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to add email domain', - 403, - '{"error":"account suspended"}', + it.each(['ghp_not-a-cloudflare-token', 'not-a-token'])( + 'rejects foreign or malformed credential %s locally', + async (token) => { + const api = client(); + const deps = addDeps({ pasteToken: async () => token }); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps)).rejects.toThrow( + 'exit 1', ); - }); - const getEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to fetch email domain status', - 403, - '{"error":"account suspended"}', - ); - }); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - // No poll produced a read — the grant may be live, and a blind revoke - // could brick a committed row: report, don't revoke. - expect(getEmailDomain).toHaveBeenCalledTimes(15); - expect(printed(errorSpy)).toContain('state is unknown'); - expect(fetchSpy).not.toHaveBeenCalled(); - }); - - it('reports a failed revocation instead of claiming it — the grant may still be live', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const getEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to fetch email domain status', - 404, - '{"error":"email domain not found"}', - ); - }); - // Cloudflare answers the revoke with a 500: fetch resolves, and a helper - // that ignored the status would let the CLI claim a revocation that - // never happened. - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => - new Response('nope', { status: 500 }), - ); - vi.stubGlobal('fetch', fetchSpy); + expect(deps.verifyToken).not.toHaveBeenCalled(); + expect(api.addEmailDomain).not.toHaveBeenCalled(); + }, + ); + it('refuses an inactive token', async () => { + const api = client(); await expect( emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + api, 'prj_1', 'acme.com', undefined, - addDeps(), + addDeps({ verifyToken: async () => 'inactive' }), ), ).rejects.toThrow('exit 1'); - - expect(fetchSpy).toHaveBeenCalledTimes(1); - expect(printed(errorSpy)).toContain('could not be revoked'); - expect(printed(errorSpy)).toContain('revoke it in the Cloudflare dashboard'); - expect(printed(errorSpy)).not.toContain('was revoked'); + expect(api.addEmailDomain).not.toHaveBeenCalled(); }); - it('reconciles a lost answer: the row carries this attempt id, nothing is revoked', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const getEmailDomain = vi.fn(async () => statusRow({ attemptId: ATTEMPT_ID })); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - + it('leaves authoritative verification to the API if the local token probe is unavailable', async () => { + const api = client(); await emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + api, 'prj_1', 'acme.com', undefined, - addDeps(), + addDeps({ verifyToken: async () => 'unknown' }), ); - - // One read settles it: the stamped attempt id proves this attempt's - // POST committed, so the platform holds the credential and the row - // renders like any other add. - expect(getEmailDomain).toHaveBeenCalledTimes(1); - expect(getEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com'); - expect(printed(warnSpy)).toContain('answer was lost'); - expect(notedBlocks()).toContain('Domain: acme.com'); - expect(fetchSpy).not.toHaveBeenCalled(); + expect(api.addEmailDomain).toHaveBeenCalled(); }); - it('reconciles a lost answer: a 404 then the row with this attempt id — the insert was still in flight', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const getEmailDomain = vi + it('accepts only a new Cloudflare-shaped clipboard value and clears it after use', async () => { + const api = client(); + const readClipboard = vi .fn() - .mockRejectedValueOnce( - new PlatformApiError( - 'Failed to fetch email domain status', - 404, - '{"error":"email domain not found"}', - ), - ) - .mockResolvedValueOnce(statusRow({ attemptId: ATTEMPT_ID })); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, + .mockReturnValueOnce('old clipboard') + .mockReturnValueOnce('ghp_ignored') + .mockReturnValue(CFUT_TOKEN); + const deps = addDeps({ readClipboard }); + await emailDomainAdd(api, 'prj_1', 'acme.com', undefined, deps); + expect(deps.verifyToken).toHaveBeenCalledTimes(1); + expect(deps.verifyToken).toHaveBeenCalledWith(CFUT_TOKEN); + expect(deps.clearClipboard).toHaveBeenCalledTimes(1); + expect(api.addEmailDomain).toHaveBeenCalledWith( 'prj_1', - 'acme.com', - undefined, - addDeps(), + expect.objectContaining({ apiToken: CFUT_TOKEN }), ); - - // The lost answer did not stop the API worker: the row committed - // between polls, and the stamped attempt id proves the credential is - // this attempt's — revoking here would brick the row. - expect(getEmailDomain).toHaveBeenCalledTimes(2); - expect(printed(warnSpy)).toContain('answer was lost'); - expect(notedBlocks()).toContain('Domain: acme.com'); - expect(fetchSpy).not.toHaveBeenCalled(); }); - it('reconciles a lost answer against an api without attempt identity: the row exists, nothing is revoked', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - // No attemptId key in the parsed row at all (statusRow carries none): - // an old api, where this could be my committed add — indistinguishable - // from a pre-existing row, so trust it and never revoke. - const getEmailDomain = vi.fn(async () => statusRow({ status: 'pending' })); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - - await emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ); - - expect(getEmailDomain).toHaveBeenCalledTimes(1); - expect(getEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com'); - expect(printed(warnSpy)).toContain('answer was lost'); - expect(notedBlocks()).toContain('Domain: acme.com'); - expect(fetchSpy).not.toHaveBeenCalled(); + it('recovers a lost submission response by exact operation key', async () => { + const api = client(); + vi.spyOn(crypto, 'randomUUID').mockReturnValue(ATTEMPT_ID); + api.addEmailDomain.mockRejectedValue(new Error('connection reset')); + await emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps()); + expect(api.getEmailOperation).toHaveBeenCalledWith('prj_1', ATTEMPT_ID); + expect(api.getEmailDomain).not.toHaveBeenCalled(); + expect(notedBlocks()).toContain('Operation: op_1'); + expect(notedBlocks()).toContain('Inbound: ready'); + expect(notedBlocks()).not.toContain('[object Object]'); }); - it('revokes the minted grant when the row keeps a different attempt id through the deadline', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - // The pre-existing row, stamped by an earlier attempt: this attempt's - // replace POST never landed, and a committed mine would carry my id. - const getEmailDomain = vi.fn(async () => - statusRow({ attemptId: '99999999-9999-4999-8999-999999999999' }), - ); - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(null, { status: 200 }), + it('never treats missing operation reads as proof that nothing committed', async () => { + const api = client(); + api.addEmailDomain.mockRejectedValue(new Error('connection reset')); + api.getEmailOperation.mockRejectedValue(new PlatformApiError('not found', 404, '{}')); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps())).rejects.toThrow( + 'exit 1', ); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - expect(getEmailDomain).toHaveBeenCalledTimes(15); - // Exactly one call: the RFC 7009 revoke of the grant this process held. - expect(fetchSpy).toHaveBeenCalledTimes(1); - const [url, init] = fetchSpy.mock.calls[0]!; - expect(String(url)).toBe('https://dash.cloudflare.com/oauth2/revoke'); - const form = new URLSearchParams(String(init?.body)); - expect(form.get('token')).toBe(GRANT_SENTINEL); - expect(form.get('token_type_hint')).toBe('refresh_token'); - expect(printed(errorSpy)).toContain("kept the row's existing credential"); - expect(printed(errorSpy)).toContain('revoked'); - // The token itself never reaches an output line. - expect(printed(errorSpy) + printed(infoSpy) + printed(warnSpy)).not.toContain(GRANT_SENTINEL); + expect(api.getEmailOperation).toHaveBeenCalledTimes(15); + expect(printed(errorSpy)).toContain('outcome is unknown'); + expect(printed(errorSpy)).toContain('Nothing was revoked'); }); - it('treats a stamped null attempt id as foreign — a row an older CLI wrote', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const getEmailDomain = vi.fn(async () => statusRow({ attemptId: null })); - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(null, { status: 200 }), + it('does not poll after a definitive validation refusal', async () => { + const api = client(); + api.addEmailDomain.mockRejectedValue(new PlatformApiError('invalid domain', 400, '{}')); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps())).rejects.toThrow( + 'invalid domain', ); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - // The key is present (new api) but null — not this attempt, so the - // posted grant was never stored and the revoke is safe. - expect(getEmailDomain).toHaveBeenCalledTimes(15); - expect(fetchSpy).toHaveBeenCalledTimes(1); - expect(printed(errorSpy)).toContain("kept the row's existing credential"); + expect(api.getEmailOperation).not.toHaveBeenCalled(); }); - it('revokes the minted grant when a transport failure provably never persisted it', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const getEmailDomain = vi.fn(async () => { - throw new PlatformApiError( - 'Failed to fetch email domain status', - 404, - '{"error":"email domain not found"}', - ); - }); - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(null, { status: 200 }), + it('returns failure for setup needing intervention, even if a row exists', async () => { + const api = client(); + api.addEmailDomain.mockResolvedValue( + domainRow({ + status: 'failed', + operationId: 'op_1', + operationStatus: 'blocked', + error: 'catch-all conflict', + }), ); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - // 404 at every one of the 15 polls — provably nothing persisted. - expect(getEmailDomain).toHaveBeenCalledTimes(15); - // Exactly one call: the RFC 7009 revoke of the grant this process held. - expect(fetchSpy).toHaveBeenCalledTimes(1); - const [url, init] = fetchSpy.mock.calls[0]!; - expect(String(url)).toBe('https://dash.cloudflare.com/oauth2/revoke'); - const form = new URLSearchParams(String(init?.body)); - expect(form.get('token')).toBe(GRANT_SENTINEL); - expect(form.get('token_type_hint')).toBe('refresh_token'); - expect(printed(errorSpy)).toContain('was not registered'); - expect(printed(errorSpy)).toContain('revoked'); - // The token itself never reaches an output line. - expect(printed(errorSpy) + printed(infoSpy) + printed(warnSpy)).not.toContain(GRANT_SENTINEL); - }); - - it('never revokes on an indeterminate reconcile — the grant may be the row’s credential', async () => { - mockAttemptId(); - const addEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const getEmailDomain = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - const fetchSpy = vi.fn(); - vi.stubGlobal('fetch', fetchSpy); - - await expect( - emailDomainAdd( - { - addEmailDomain, - getEmailDomain, - getEmailSettings: selfServeSettings, - listEmailDomains: noEmailDomains, - }, - 'prj_1', - 'acme.com', - undefined, - addDeps(), - ), - ).rejects.toThrow('exit 1'); - - // No poll produced any read: a blind revoke could brick a committed - // row — report, don't revoke. - expect(getEmailDomain).toHaveBeenCalledTimes(15); - expect(fetchSpy).not.toHaveBeenCalled(); - expect(printed(errorSpy)).toContain('state is unknown'); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps())).rejects.toThrow( + 'exit 1', + ); + expect(printed(errorSpy)).toContain('catch-all conflict'); }); }); @@ -1685,10 +717,11 @@ describe('emailDomainList', () => { }); describe('emailDomainSync', () => { - it('renders the redeploy + rotation on success', async () => { + it('renders reconciliation without claiming automatic secret rotation', async () => { const syncEmailDomain = vi.fn(async () => domainRow({ relay_version: 2 })); await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); - expect(printed(successSpy)).toContain('Relay redeployed at v2 with a rotated secret.'); + expect(printed(successSpy)).not.toContain('rotated secret'); + expect(notedBlocks()).toContain('acme.com'); expect(syncEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com'); }); @@ -1701,7 +734,9 @@ describe('emailDomainSync', () => { error: 'PUT script failed', }), ); - await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); + await expect(emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com')).rejects.toThrow( + 'reconciliation', + ); expect(printed(errorSpy)).toContain('failed at deploy relay'); expect(printed(errorSpy)).toContain('PUT script failed'); expect(printed(successSpy)).not.toContain('Relay redeployed'); @@ -1721,7 +756,7 @@ describe('emailDomainSync', () => { })); await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); expect(printed(warnSpy)).toContain("the zone's catch-all points at a different worker"); - expect(printed(warnSpy)).toContain('NOT overwritten'); + expect(printed(warnSpy)).toContain('not overwritten'); expect(printed(infoSpy)).not.toContain('Catch-all:'); }); @@ -1836,3 +871,23 @@ describe('PlatformClient.removeEmailDomain', () => { expect(forceInit?.method).toBe('DELETE'); }); }); + +describe('emailDomainRotateSecret', () => { + it('prints completion only after the deployed generation is confirmed', async () => { + const rotateEmailDomainSecret = vi.fn(async () => + domainRow({ operationId: 'eop_rotate', operationStatus: 'completed' }), + ); + await emailDomainRotateSecret({ rotateEmailDomainSecret }, 'prj_1', 'acme.com'); + expect(rotateEmailDomainSecret).toHaveBeenCalledWith('prj_1', 'acme.com'); + expect(printed(successSpy)).toContain('verified on the deployed Worker'); + }); + it('surfaces an uncertain rotation instead of reporting success', async () => { + const rotateEmailDomainSecret = vi.fn(async () => + domainRow({ operationId: 'eop_rotate', operationStatus: 'unknown' }), + ); + await expect( + emailDomainRotateSecret({ rotateEmailDomainSecret }, 'prj_1', 'acme.com'), + ).rejects.toThrow('eop_rotate'); + expect(printed(successSpy)).not.toContain('secret rotated'); + }); +}); diff --git a/packages/void/test/unit/email-dev-inbox.test.ts b/packages/void/test/unit/email-dev-inbox.test.ts index 57ae970ad..0f6f289e2 100644 --- a/packages/void/test/unit/email-dev-inbox.test.ts +++ b/packages/void/test/unit/email-dev-inbox.test.ts @@ -246,15 +246,11 @@ async function serializedSizeOf( } describe('dev inbox capture cap (sized for the serialized capture)', () => { - // 3.31M x \x01. Quoted-printable renders each as `=01` plus a soft break - // every 25, so the MIME is 10.3 MB — under MAX_MESSAGE_BYTES, so production - // sends it — while the capture renders each as `\u0001` (19.9 MB) next to - // the base64 of that MIME (13.8 MB): 33.6 MB, over the 32 MiB the cap used - // to be. The dev server answered 413 and `sendEmail` reported the legal - // message as UPSTREAM_ERROR. The smallest such body is 3,303,000 characters; - // the margin keeps the test off the edge of the old cap. - it('captures a legal message whose serialized capture exceeds 32 MiB', async () => { - const text = '\x01'.repeat(3_310_000); + // Quoted-printable expands each control byte to `=01` plus soft breaks. + // The capture also carries JSON-escaped text and base64 MIME, so even a + // message below the 5 MiB sending limit exceeds three times that budget. + it('captures a legal message whose serialized capture exceeds three MIME budgets', async () => { + const text = '\x01'.repeat(Math.floor(MAX_MESSAGE_BYTES / 3.15)); const server = createFakeViteServer(); const assets = fakeAssetsBinding(server); const result = await withRuntimeEnv(devEnv(assets), () => @@ -266,8 +262,8 @@ describe('dev inbox capture cap (sized for the serialized capture)', () => { expect(message.raw.byteLength).toBeLessThanOrEqual(MAX_MESSAGE_BYTES); expect(message.text).toBe(text); // What crossed the wire: the same JSON the worker POSTed (ASCII, so its - // length is its byte size), and it is over the former cap. - expect(serializeCapturedMessage(message).length).toBeGreaterThan(32 * 1024 * 1024); + // length is its byte size), including both expanded representations. + expect(serializeCapturedMessage(message).length).toBeGreaterThan(3 * MAX_MESSAGE_BYTES); }); // The bound behind the constant: base64 raw (4/3) plus every caller string @@ -293,7 +289,10 @@ describe('dev inbox capture cap (sized for the serialized capture)', () => { // encoded-word header: base64 plus framing (1.6) in the MIME, 6 in JSON — 3.75x ['control subject', { ...base, subject: control, text: 't' }], ['control display name', { ...base, to: [{ email: 'b@y.dev', name: control }], text: 't' }], - ['control custom header value', { ...base, headers: { 'X-Note': control }, text: 't' }], + [ + 'control custom header value', + { ...base, headers: { 'X-Note': control.slice(0, 8_192) }, text: 't' }, + ], ]; const shapes: Array<[string, Parameters[0]]> = [ // body: `=01` (3) in the MIME, `\u0001` (6) in JSON — 2x @@ -309,7 +308,7 @@ describe('dev inbox capture cap (sized for the serialized capture)', () => { ...base, text: 't', headers: Object.fromEntries( - Array.from({ length: 50 }, (_, i) => [`${'"'.repeat(900)}${i}`, 'v']), + Array.from({ length: 12 }, (_, i) => [`${'"'.repeat(900)}${i}`, 'v']), ), }, ], diff --git a/packages/void/test/unit/email-domain-args.test.ts b/packages/void/test/unit/email-domain-args.test.ts index 7b1f0ff91..66d97bc9c 100644 --- a/packages/void/test/unit/email-domain-args.test.ts +++ b/packages/void/test/unit/email-domain-args.test.ts @@ -63,7 +63,7 @@ describe('parseEmailArgs — domain group', () => { it('errors on a missing or unknown domain verb', () => { expect(() => parseEmailArgs(['domain'])).toThrow( - 'email: Usage: void email domain [] [--project ].', + 'email: Usage: void email domain [] [--project ].', ); expect(() => parseEmailArgs(['domain', 'frobnicate', 'acme.com'])).toThrow( /Usage: void email domain/, @@ -71,7 +71,7 @@ describe('parseEmailArgs — domain group', () => { }); it('errors when a domain verb is missing its domain', () => { - for (const verb of ['add', 'status', 'sync', 'remove']) { + for (const verb of ['add', 'status', 'sync', 'rotate-secret', 'remove']) { expect(() => parseEmailArgs(['domain', verb])).toThrow( `email: Usage: void email domain ${verb} [--project ].`, ); diff --git a/packages/void/test/unit/email-inbound.test.ts b/packages/void/test/unit/email-inbound.test.ts index 2a502b910..ae8cdc837 100644 --- a/packages/void/test/unit/email-inbound.test.ts +++ b/packages/void/test/unit/email-inbound.test.ts @@ -897,6 +897,8 @@ describe('compileWorkerEntry (email)', () => { 'async email(envelope) { return handleEmail(envelope, this.env, this.ctx); }', ); expect(code).toContain('async function handleEmail'); + expect(code).toContain('from "void/_email-protocol"'); + expect(code).not.toContain('from "@void/platform/email-protocol"'); }); it('omits the email export when hasEmail is false', () => { @@ -1403,7 +1405,7 @@ describe('harness enforces the proxy action bounds, like production', () => { }); await harness.deliver(DELIVERY); expect(thrown).toBeInstanceOf(MimeError); - expect((thrown as MimeError).message).toMatch(/exceeds Cloudflare limit/); + expect((thrown as MimeError).message).toMatch(/exceeds Void's sending limit/); expect(harness.replies).toEqual([]); }); @@ -3063,7 +3065,7 @@ describe('end-to-end: envelope → handler → action queue', () => { } as unknown as Parameters[0]); }); await expect(dispatchToHandler(makeEnvelope(), handler)).rejects.toThrow( - /exceeds Cloudflare limit/, + /exceeds Void's sending limit/, ); }); @@ -3089,11 +3091,11 @@ describe('end-to-end: envelope → handler → action queue', () => { } as unknown as Parameters[0]); }); await expect(dispatchToHandler(makeEnvelope(), handler)).rejects.toThrow( - /exceeds Cloudflare limit/, + /exceeds Void's sending limit/, ); expect(cancelled).toBe(true); - // 10 MiB limit + the chunk that crosses it + the stream's own read-ahead. - expect(pulls).toBeLessThanOrEqual(12); + // 5 MiB limit + the chunk that crosses it + the stream's own read-ahead. + expect(pulls).toBeLessThanOrEqual(7); }); it('refuses the 101st queued action and leaves the queue at 100', async () => { @@ -3119,10 +3121,7 @@ describe('end-to-end: envelope → handler → action queue', () => { }); it('refuses a third reply once the cumulative reply budget is spent', async () => { - // This is what the per-reply cap does NOT catch: each of the first two - // replies is exactly at MAX_MESSAGE_BYTES and legal on its own, and the - // third is a single byte — but 2 x MAX_MESSAGE_BYTES is the whole budget - // for one delivery, so the byte is refused. + // The first two replies spend the 8 MiB response budget exactly. let thrown: unknown; const handler = defineEmail(async (message) => { const send = (raw: Uint8Array) => @@ -3131,8 +3130,8 @@ describe('end-to-end: envelope → handler → action queue', () => { to: 'sender@example.com', raw, } as unknown as Parameters[0]); - await send(new Uint8Array(MAX_MESSAGE_BYTES)); - await send(new Uint8Array(MAX_MESSAGE_BYTES)); + await send(new Uint8Array(5 * 1024 * 1024)); + await send(new Uint8Array(3 * 1024 * 1024)); try { await send(new Uint8Array(1)); } catch (e) { @@ -3140,21 +3139,20 @@ describe('end-to-end: envelope → handler → action queue', () => { } }); const actions = await dispatchToHandler(makeEnvelope(), handler); - // Both full-size replies are legal and queued; only the third is refused. + // Both in-budget replies are queued; only the third is refused. expect(actions).toHaveLength(2); expect(thrown).toBeInstanceOf(MimeError); expect((thrown as MimeError).message).toMatch(/cumulative reply size/); }); it('cancels a stream reply at the REMAINING budget, not the per-reply cap', async () => { - // 15 MiB already spent out of the 20 MiB budget, so 5 MiB is left. A - // stream bounded by the per-reply cap would keep pulling to 10 MiB and + // 7 MiB already spent out of the 8 MiB budget, so 1 MiB is left. A + // stream bounded by the per-reply cap would keep pulling to 5 MiB and // report the wrong limit; the pull count and the message both pin that // the remaining budget is what stopped it. // // Two prior replies, not one: after a single full-size reply the - // remaining budget is exactly MAX_MESSAGE_BYTES, which cannot be told - // apart from the per-reply cap. + // remaining budget is still below the per-reply cap, but this pins a tighter boundary. let pulls = 0; let cancelled = false; const chunk = new Uint8Array(1024 * 1024); @@ -3175,8 +3173,8 @@ describe('end-to-end: envelope → handler → action queue', () => { to: 'sender@example.com', raw: body, } as unknown as Parameters[0]); - await send(new Uint8Array(MAX_MESSAGE_BYTES)); await send(new Uint8Array(5 * 1024 * 1024)); + await send(new Uint8Array(2 * 1024 * 1024)); try { await send(raw); } catch (e) { @@ -3186,9 +3184,8 @@ describe('end-to-end: envelope → handler → action queue', () => { const actions = await dispatchToHandler(makeEnvelope(), handler); expect(actions).toHaveLength(2); expect(cancelled).toBe(true); - // 5 MiB of remaining budget + the chunk that crosses it + read-ahead — - // NOT the ~11 a 10 MiB per-reply cap would have allowed. - expect(pulls).toBeLessThanOrEqual(7); + // 1 MiB of remaining budget + the chunk that crosses it + read-ahead. + expect(pulls).toBeLessThanOrEqual(3); expect(thrown).toBeInstanceOf(MimeError); expect((thrown as MimeError).message).toMatch(/cumulative reply size/); }); @@ -3299,12 +3296,10 @@ describe('end-to-end: envelope → handler → action queue', () => { }, ); - it("records a forward header bag exactly at the router's bounds", async () => { - // 32 headers, every name and value 1024 characters: the largest bag the - // managed router enacts. The bound is `>` on both sides, not `>=`. + it('records 32 forward headers within the wire metadata budget', async () => { const bag: Record = {}; for (let i = 0; i < 32; i++) { - bag[`X-${'a'.repeat(1020)}${String(i).padStart(2, '0')}`] = 'v'.repeat(1024); + bag[`X-${'a'.repeat(95)}${String(i).padStart(2, '0')}`] = 'v'.repeat(100); } const { message, getActions } = createMessageProxy(makeEnvelope()); await message.forward('archive@example.com', bag as unknown as Headers); @@ -3313,11 +3308,23 @@ describe('end-to-end: envelope → handler → action queue', () => { const recorded = (actions[0] as { headers?: Record }).headers ?? {}; expect(Object.keys(recorded)).toHaveLength(32); for (const [name, value] of Object.entries(recorded)) { - expect(name).toHaveLength(1024); - expect(value).toHaveLength(1024); + expect(name).toHaveLength(99); + expect(value).toHaveLength(100); } }); + it('rejects an aggregate forward header bag over the wire metadata budget', async () => { + const bag: Record = {}; + for (let i = 0; i < 32; i++) { + bag[`X-${i}`] = 'v'.repeat(1024); + } + const { message, getActions } = createMessageProxy(makeEnvelope()); + await expect(message.forward('archive@example.com', bag as unknown as Headers)).rejects.toThrow( + 'action metadata exceeds 8192 bytes', + ); + expect(getActions()).toEqual([]); + }); + it('normalizes the reject reason as the router does: slice to 1000, then strip controls', () => { // The router's own fixture (`email-router.test.ts`): 300 x "line\r\n" is // 1800 characters; the first 1000 code units are 166 full lines plus diff --git a/packages/void/test/unit/email-mime.test.ts b/packages/void/test/unit/email-mime.test.ts index d44d411d2..bd4b79827 100644 --- a/packages/void/test/unit/email-mime.test.ts +++ b/packages/void/test/unit/email-mime.test.ts @@ -503,7 +503,7 @@ describe('normalizeEmail', () => { it('is derived from the per-part floor and the message cap', () => { expect(MAX_ATTACHMENTS).toBe(Math.floor(MAX_MESSAGE_BYTES / PART_MIN_OCTETS)); - expect(MAX_ATTACHMENTS).toBe(88_115); + expect(MAX_ATTACHMENTS).toBe(44_057); }); it('refuses one over MAX_ATTACHMENTS before normalizing any of them', async () => { @@ -2440,7 +2440,7 @@ describe('buildMime body size projection', () => { it('counts text and html together', async () => { // Each alone projects under the limit; together they cannot fit. - const half = '漢'.repeat(Math.ceil((1.8 * 1024 * 1024) / 3)); + const half = '漢'.repeat(Math.ceil((0.9 * 1024 * 1024) / 3)); await expect( build({ from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: half }), ).resolves.toBeTruthy(); @@ -2455,7 +2455,7 @@ describe('buildMime body size projection', () => { // The projection must let it through; the post-render check must reject // it. One full ~10 MB render, so it carries its own timeout (0.4 s here, // several times that on a loaded CI runner). - const nearly = '漢'.repeat(Math.ceil((3.3 * 1024 * 1024) / 3)); + const nearly = '漢'.repeat(Math.ceil((1.65 * 1024 * 1024) / 3)); const email = await normalizeEmail({ from: 'a@x.dev', to: 'b@y.dev', @@ -2517,81 +2517,21 @@ describe('buildMime header size projection', () => { }); }); - it('counts a custom header, and not a reserved one that is never rendered', async () => { - const big = 'x'.repeat(11 * 1024 * 1024); - await expectProjected({ - from: 'a@x.dev', - to: 'b@y.dev', - subject: 's', - text: 'hi', - headers: { 'X-Note': big }, - }); - // `Subject` in the custom map is dropped by `buildMime`, so charging it - // would reject a message that fits. - const { text } = await build({ - from: 'a@x.dev', - to: 'b@y.dev', - subject: 's', - text: 'hi', - headers: { Subject: big }, - }); - expect(text).toContain('Subject: s\r\n'); - }); - - // A custom header's NAME is rendered verbatim too, and `normalizeEmail` - // bounds one name at under a kilobyte — not the sum, nor the count. With - // empty values the names and the `: ` CRLF around each are the whole - // message, and none of it was charged: 60k empty headers with - // 500-character names — a 30 MB message — projected to zero, rendered in - // full and peaked at 121 MB of a 128 MB isolate (measured, 240 ms); 100k - // of them went to 169 MB. Every name and its framing is charged now, so - // the same set is refused before a line is built (98 ms, 67 MB peak). - it('counts every custom header name and the framing around it', async () => { - const names = (count: number, len: number) => - Object.fromEntries(Array.from({ length: count }, (_, i) => [`X${i}`.padEnd(len, 'a'), ''])); - const started = performance.now(); - // 22k names of 500 characters: 11 MB of names, nothing else. - await expectProjected({ - from: 'a@x.dev', - to: 'b@y.dev', - subject: 's', - text: 't', - headers: names(22_000, 500), - }); - // 31 ms measured; the bound leaves room for a loaded CI runner. - expect(performance.now() - started).toBeLessThan(2000); - // The bound is exact for a header with an empty value: 10,485 names of - // 996 characters project 745 octets under the cap and render 548 under - // it, so they build. One more 600-character name projects 141 under - // and renders 57 over, so the post-render check — not the projection — - // must be the one to refuse it. One more 996-character name is over - // by projection alone. - const fits = names(10_485, 996); - const { raw } = await build({ - from: 'a@x.dev', - to: 'b@y.dev', - subject: 's', - text: 't', - headers: fits, - }); - expect(raw.byteLength).toBeLessThanOrEqual(MAX_MESSAGE_BYTES); + it('bounds aggregate custom headers before rendering, including names and UTF-8 bytes', async () => { + const base = { from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 'hi' }; await expect( - build({ - from: 'a@x.dev', - to: 'b@y.dev', - subject: 's', - text: 't', - headers: { ...fits, ['Y'.padEnd(600, 'a')]: '' }, - }), - ).rejects.toThrow(/message size \d+ bytes exceeds Cloudflare limit/); - await expectProjected({ - from: 'a@x.dev', - to: 'b@y.dev', - subject: 's', - text: 't', - headers: names(10_486, 996), - }); - }, 30_000); + normalizeEmail({ ...base, headers: { 'X-Note': 'x'.repeat(16 * 1024) } }), + ).rejects.toThrow('16 KiB'); + await expect( + normalizeEmail({ ...base, headers: { 'X-Note': '漢'.repeat(6000) } }), + ).rejects.toThrow('16 KiB'); + const names = Object.fromEntries( + Array.from({ length: 40 }, (_, i) => [`X${i}`.padEnd(500, 'a'), '']), + ); + await expect(normalizeEmail({ ...base, headers: names })).rejects.toThrow('16 KiB'); + const { text } = await build({ ...base, headers: { 'X-Note': 'short note' } }); + expect(text).toContain('X-Note: short note'); + }); // The runner's own heap is not capped, so the pin runs the projection in // a child with the isolate's cap. 60k empty headers with 996-character @@ -2609,9 +2549,8 @@ describe('buildMime header size projection', () => { const headers = {}; for (let i = 0; i < 60_000; i++) headers['X' + i + 'a'.repeat(996 - 1 - String(i).length)] = ''; const t0 = performance.now(); - const email = await normalizeEmail({ from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 't', headers }); let error; - try { buildMime(email); } catch (e) { error = e; } + try { const email = await normalizeEmail({ from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 't', headers }); buildMime(email); } catch (e) { error = e; } console.log(JSON.stringify({ code: error?.code, message: error?.message, ms: performance.now() - t0 })); `; const stdout = execFileSync( @@ -2625,7 +2564,7 @@ describe('buildMime header size projection', () => { ms: number; }; expect(result.code).toBe('MIME_ERROR'); - expect(result.message).toMatch(PROJECTION); + expect(result.message).toContain('16 KiB'); // 173 ms measured locally; the bound leaves room for CI's slower runner // (about 6x), where the old shape did not finish at all. expect(result.ms).toBeLessThan(5000); @@ -2718,13 +2657,13 @@ describe('buildMime header size projection', () => { to: 'b@y.dev', subject: 's', text: 't', - attachments: parts(50_000), + attachments: parts(25_000), }); // The bound is exact for a part with no content: 5,012 parts project to // 640 octets under the cap and render to 10.66 MB, so the post-render // check — not the projection — must be the one to refuse them. await expect( - build({ from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 't', attachments: parts(5_012) }), + build({ from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 't', attachments: parts(2_506) }), ).rejects.toThrow(/message size \d+ bytes exceeds Cloudflare limit/); // And 4,900 parts, a 10.42 MB message, build. const { raw } = await build({ @@ -2732,7 +2671,7 @@ describe('buildMime header size projection', () => { to: 'b@y.dev', subject: 's', text: 't', - attachments: parts(4_900), + attachments: parts(2_450), }); expect(raw.byteLength).toBeLessThanOrEqual(MAX_MESSAGE_BYTES); }); @@ -2741,7 +2680,10 @@ describe('buildMime header size projection', () => { // A 5 MB chain of short ids is a legal message: it folds at its spaces // into 76-column lines and renders under the cap. const id = ''; - const chain = Array.from({ length: Math.floor((5 * 1024 * 1024) / (id.length + 1)) }, () => id); + const chain = Array.from( + { length: Math.floor((2.5 * 1024 * 1024) / (id.length + 1)) }, + () => id, + ); const { raw, text } = await build({ from: 'a@x.dev', to: 'b@y.dev', @@ -2771,7 +2713,7 @@ describe('buildMime header size projection', () => { // reject it. This is the one case that needs a full ~10 MB render (the // property is AT the boundary), so it carries its own timeout: 0.8 s // here, 5.4 s on a loaded 4-vCPU CI runner. - const nearly = '漢'.repeat(2_150_000); + const nearly = '漢'.repeat(1_075_000); const email = await normalizeEmail({ from: 'a@x.dev', to: 'b@y.dev', @@ -2825,7 +2767,7 @@ describe('body line scan memory', () => { // runner's heap is not the isolate's; this pins the rendered shape and // that the scans stay linear. it('builds a legal message of millions of short lines in text and html', async () => { - const lines = 1_500_000; + const lines = 750_000; const started = performance.now(); const { raw, text } = await build({ from: 'a@x.dev', diff --git a/packages/void/test/unit/email-send.test.ts b/packages/void/test/unit/email-send.test.ts index d184956ea..b4d03688a 100644 --- a/packages/void/test/unit/email-send.test.ts +++ b/packages/void/test/unit/email-send.test.ts @@ -248,14 +248,14 @@ describe('sendEmail (error mapping)', () => { try { const result = await sendEmail({ from: 'a@x.dev', - to: Array.from({ length: 101 }, (_, i) => `u${i}@example.com`), + to: Array.from({ length: 51 }, (_, i) => `u${i}@example.com`), subject: 's', text: 't', }); expect(result.ok).toBe(false); if (!result.ok && 'error' in result) { expect(result.error.code).toBe('INVALID_TO'); - expect(result.error.message).toMatch(/too many recipients \(max 100, got 101\)/); + expect(result.error.message).toMatch(/too many recipients \(max 50, got 51\)/); } expect(harness.messages).toHaveLength(0); } finally { @@ -625,7 +625,7 @@ describe('sendEmail (proxy round trip)', () => { } }); - it('returns UPSTREAM_ERROR on proxy fetch failure', async () => { + it('returns OUTCOME_UNKNOWN on proxy fetch failure', async () => { const proxy = { async fetch() { throw new Error('network unreachable'); @@ -642,7 +642,7 @@ describe('sendEmail (proxy round trip)', () => { ); expect(result.ok).toBe(false); if (!result.ok && 'error' in result) { - expect(result.error.code).toBe('UPSTREAM_ERROR'); + expect(result.error.code).toBe('OUTCOME_UNKNOWN'); } }); @@ -711,7 +711,7 @@ describe('sendEmail (proxy round trip)', () => { ['ok:false with neither error nor deliveries', { ok: false }], ['primitive number body', 42], ['primitive array body', []], - ])('returns UPSTREAM_ERROR (no throw) for malformed proxy response: %s', async (_, payload) => { + ])('returns OUTCOME_UNKNOWN (no throw) for malformed proxy response: %s', async (_, payload) => { const { proxy } = fakeProxy(() => ({ status: 200, body: payload })); const result = await withRuntimeEnv({ __VOID_PROXY: proxy, ...PROXY_ENV_KEYS }, () => sendEmail({ @@ -724,7 +724,7 @@ describe('sendEmail (proxy round trip)', () => { ); expect(result.ok).toBe(false); if (!result.ok && 'error' in result) { - expect(result.error.code).toBe('UPSTREAM_ERROR'); + expect(result.error.code).toBe('OUTCOME_UNKNOWN'); } }); @@ -781,12 +781,12 @@ describe('sendEmail (proxy round trip)', () => { ); expect(result.ok).toBe(false); if (!result.ok && 'error' in result) { - expect(result.error.code).toBe('UPSTREAM_ERROR'); + expect(result.error.code).toBe('OUTCOME_UNKNOWN'); expect(result.error.message).toBe('email: proxy returned malformed response (status 200)'); } }); - it('returns UPSTREAM_ERROR when proxy responds with non-JSON', async () => { + it('returns OUTCOME_UNKNOWN when proxy responds with non-JSON', async () => { const proxy = { async fetch() { return new Response('not json', { @@ -806,7 +806,7 @@ describe('sendEmail (proxy round trip)', () => { ); expect(result.ok).toBe(false); if (!result.ok && 'error' in result) { - expect(result.error.code).toBe('UPSTREAM_ERROR'); + expect(result.error.code).toBe('OUTCOME_UNKNOWN'); } }); @@ -911,15 +911,15 @@ describe('sendEmail (proxy delivery list)', () => { 'entry 0 names a recipient that was not requested', ], ])( - 'returns UPSTREAM_ERROR for an ok:true response carrying %s', + 'returns OUTCOME_UNKNOWN for an ok:true response carrying %s', async (_, to, payload, reason) => { const { proxy } = fakeProxy(() => ({ status: 200, body: payload })); const result = await send(proxy, to); expect(result).toEqual({ ok: false, error: { - code: 'UPSTREAM_ERROR', - message: `email: proxy returned a malformed delivery list (${reason})`, + code: 'OUTCOME_UNKNOWN', + message: `email: proxy returned a malformed delivery list (${reason}); do not retry with a new idempotency key`, cause: payload, }, }); @@ -1118,15 +1118,15 @@ describe('sendEmail (proxy mid-batch delivery list)', () => { `entry 1 is not ${SHAPE}`, ], ])( - 'returns a top-level UPSTREAM_ERROR for a mid-batch response carrying %s', + 'returns a top-level OUTCOME_UNKNOWN for a mid-batch response carrying %s', async (_, to, payload, reason) => { const { proxy } = fakeProxy(() => ({ status: 200, body: payload })); const result = await send(proxy, to); expect(result).toEqual({ ok: false, error: { - code: 'UPSTREAM_ERROR', - message: `email: proxy returned a malformed delivery list (${reason})`, + code: 'OUTCOME_UNKNOWN', + message: `email: proxy returned a malformed delivery list (${reason}); do not retry with a new idempotency key`, cause: payload, }, }); @@ -1268,3 +1268,69 @@ describe('sendEmail (sendInDev escape hatch)', () => { } }); }); + +describe('sendEmail platform idempotency', () => { + const options = { from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 't', sendInDev: true }; + it('carries the key and preserves the operation and provider acceptance state', async () => { + const { proxy, calls } = fakeProxy(() => ({ + status: 200, + body: { + ok: true, + operationId: 'emailact_1', + ids: [{ recipient: 'b@y.dev', messageId: 'cf-1', state: 'provider_accepted' }], + }, + })); + const result = await withRuntimeEnv({ __VOID_PROXY: proxy, ...PROXY_ENV_KEYS }, () => + sendEmail({ ...options, idempotencyKey: 'invoice:42' }), + ); + expect(calls[0]?.body).toMatchObject({ idempotencyKey: 'invoice:42' }); + expect(result).toMatchObject({ + ok: true, + operationId: 'emailact_1', + ids: [{ state: 'provider_accepted' }], + }); + }); + it('keeps partial outcomes when the response also carries an overall error', async () => { + const { proxy } = fakeProxy(() => ({ + status: 200, + body: { + ok: false, + operationId: 'emailact_2', + error: { code: 'OUTCOME_UNKNOWN', message: 'unknown' }, + deliveries: [ + { + recipient: 'b@y.dev', + ok: false, + state: 'outcome_unknown', + error: { code: 'OUTCOME_UNKNOWN', message: 'unknown' }, + }, + ], + }, + })); + const result = await withRuntimeEnv({ __VOID_PROXY: proxy, ...PROXY_ENV_KEYS }, () => + sendEmail(options), + ); + expect(result).toMatchObject({ + ok: false, + operationId: 'emailact_2', + deliveries: [{ state: 'outcome_unknown', error: { code: 'OUTCOME_UNKNOWN' } }], + }); + }); + it('refuses an invalid key before transport and rejects unsupported native deduplication', async () => { + const send = vi.fn(); + for (const idempotencyKey of ['', 'a b', 'x'.repeat(129)]) { + const result = await withRuntimeEnv({ SEND_EMAIL: { send } }, () => + sendEmail({ ...options, idempotencyKey }), + ); + expect(result).toMatchObject({ ok: false, error: { code: 'MIME_ERROR' } }); + } + const result = await withRuntimeEnv({ SEND_EMAIL: { send } }, () => + sendEmail({ ...options, idempotencyKey: 'invoice:42' }), + ); + expect(result).toMatchObject({ + ok: false, + error: { code: 'MIME_ERROR', message: expect.stringContaining('native Cloudflare') }, + }); + expect(send).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/void/test/unit/package.test.ts b/packages/void/test/unit/package.test.ts index 037df5ee3..bdf2e3bba 100644 --- a/packages/void/test/unit/package.test.ts +++ b/packages/void/test/unit/package.test.ts @@ -99,6 +99,18 @@ describe('buildVoidManifest — self-host non-regression', () => { return (revalidate === undefined ? {} : { routing: { revalidate } }) as VoidConfig; } + it('advertises authenticated email protocol only for a managed inbound handler', () => { + expect( + buildVoidManifest({ bindings: makeBindings(), hasEmailHandlers: true }).emailProtocolVersion, + ).toBe(1); + expect( + buildVoidManifest({ bindings: makeBindings({ needsEmail: true }) }).emailProtocolVersion, + ).toBeUndefined(); + const noEmail = buildVoidManifest({ bindings: makeBindings() }); + expect(noEmail.emailProtocolVersion).toBeUndefined(); + expect(noEmail.bindings).toEqual({}); + }); + it('sets bindings.ai === true when the app needs Workers AI', () => { const manifest = buildVoidManifest({ bindings: makeBindings({ needsAI: true }) }); expect(manifest.bindings.ai).toBe(true); diff --git a/packages/void/test/unit/platform-installer.test.ts b/packages/void/test/unit/platform-installer.test.ts index d10152dcb..8eabf1e09 100644 --- a/packages/void/test/unit/platform-installer.test.ts +++ b/packages/void/test/unit/platform-installer.test.ts @@ -518,7 +518,7 @@ describe('platform installer', () => { }, deployWorker: async (config) => { expect(progress.at(-1)).toMatch( - /^(Deploying|Enabling) the (api|proxy|tail|dispatch) service/, + /^(Deploying|Enabling) the (api|proxy|emailGateway|tail|dispatch) service/, ); configs.push(config); }, @@ -546,6 +546,7 @@ describe('platform installer', () => { workers: [ plan.deployment.resources.apiWorker, plan.deployment.resources.proxyWorker, + plan.deployment.resources.emailGatewayWorker, plan.deployment.resources.dispatchWorker, ], resumeCommand: undefined, @@ -558,7 +559,7 @@ describe('platform installer', () => { (resource) => resource.kind === 'zone' || resource.kind === 'dns-record', ), ).toBe(false); - expect(new Set(configs.map((config) => config.name)).size).toBe(4); + expect(new Set(configs.map((config) => config.name)).size).toBe(5); expect( configs.every((config) => !config.routes || (config.routes as Array).length === 0), ).toBe(true); @@ -2886,171 +2887,194 @@ describe('platform installer', () => { expect(released).toBe(true); }); - it('checkpoints every resource and removes pending secrets only after verification', async () => { - const directory = mkdtempSync(join(tmpdir(), 'void-platform-installer-test-')); - directories.push(directory); - process.env.VOID_PLATFORM_REGISTRY_DIR = directory; - const plan = await createPlatformInstallPlan( - planningClient(), - { - accountId: 'account', - applicationDomain: 'apps.example.com', - controlPlaneDomain: '', - dedicatedZone: false, - displayName: 'Example', - installationSlug: 'example', - zoneName: 'example.com', - }, - null, - ); - let resourceIndex = 0; - const created = async (_account: string, name: string) => ({ - id: `resource-${resourceIndex++}`, - name, - }); - const deployed: Array = []; - const deployedTrafficStates: Array = []; - let apiSecrets: Record | null = null; - let r2OwnershipMarker = ''; - const routingValues = new Map(); - const lifecycleEvents: Array = []; - let remoteManifest = ''; - const databaseClaims: Array<[string, string]> = []; - const result = await installPlatform( - plan, - createPlatformInstallationSecrets({ - bootstrapGitHubId: '583231', - bootstrapGitHubLogin: 'octocat', - cloudflareApiToken: 'cf-token', - databaseUrl: 'postgres://user:password@db.example.com/void', - githubClientId: 'github-id', - githubClientSecret: 'github-secret', - jwtSecret: TEST_PLATFORM_JWT_SECRET, - projectSecretKey: TEST_PLATFORM_PROJECT_SECRET_KEY, - r2AccessKeyId: 'r2-id', - r2SecretAccessKey: 'r2-secret', - }), - null, - { - acquireDatabaseLifecycleLock, - claimDatabase: async (_url, installationId, ownershipNonce) => { - databaseClaims.push([installationId, ownershipNonce]); + it.each([false, true])( + 'checkpoints every resource and removes pending secrets only after verification (legacy runtime: %s)', + async (legacyRuntime) => { + const directory = mkdtempSync(join(tmpdir(), 'void-platform-installer-test-')); + directories.push(directory); + process.env.VOID_PLATFORM_REGISTRY_DIR = directory; + const plan = await createPlatformInstallPlan( + planningClient(), + { + accountId: 'account', + applicationDomain: 'apps.example.com', + controlPlaneDomain: '', + dedicatedZone: false, + displayName: 'Example', + installationSlug: 'example', + zoneName: 'example.com', }, - client: { - createAiGateway: created, - createDnsRecord: async (_zone, name) => ({ - content: '100::', - id: `resource-${resourceIndex++}`, - name, - proxied: true, - type: 'AAAA', - }), - createZone: async () => { - throw new Error('existing zone must not be created'); + null, + { includeEmailGateway: !legacyRuntime }, + ); + const packagedRuntime = resolvePlatformRuntime(getPlatformRuntimeDirectory()); + const { emailGateway: _legacyGateway, ...legacyArtifacts } = + packagedRuntime.manifest.artifacts; + const { emailProtocolVersion: _legacyProtocol, ...legacyManifest } = packagedRuntime.manifest; + const selectedRuntime = legacyRuntime + ? { + ...packagedRuntime, + manifest: { ...legacyManifest, artifacts: legacyArtifacts }, + } + : packagedRuntime; + if (legacyRuntime) { + expect(plan.actions.some((action) => action.key === 'email-gateway-worker')).toBe(false); + } + let resourceIndex = 0; + const created = async (_account: string, name: string) => ({ + id: `resource-${resourceIndex++}`, + name, + }); + const deployed: Array = []; + const deployedTrafficStates: Array = []; + let apiSecrets: Record | null = null; + let r2OwnershipMarker = ''; + const routingValues = new Map(); + const lifecycleEvents: Array = []; + let remoteManifest = ''; + const databaseClaims: Array<[string, string]> = []; + const result = await installPlatform( + plan, + createPlatformInstallationSecrets({ + bootstrapGitHubId: '583231', + bootstrapGitHubLogin: 'octocat', + cloudflareApiToken: 'cf-token', + databaseUrl: 'postgres://user:password@db.example.com/void', + githubClientId: 'github-id', + githubClientSecret: 'github-secret', + jwtSecret: TEST_PLATFORM_JWT_SECRET, + projectSecretKey: TEST_PLATFORM_PROJECT_SECRET_KEY, + r2AccessKeyId: 'r2-id', + r2SecretAccessKey: 'r2-secret', + }), + null, + { + runtime: selectedRuntime, + acquireDatabaseLifecycleLock, + claimDatabase: async (_url, installationId, ownershipNonce) => { + databaseClaims.push([installationId, ownershipNonce]); }, - createKvNamespace: created, - createR2Bucket: created, - createQueue: created, - createDispatchNamespace: created, - createHyperdrive: async (account, name) => created(account, name), - deleteKvValue: async (_account, _namespace, key) => { - lifecycleEvents.push(`delete:${key}`); - routingValues.delete(key); + client: { + createAiGateway: created, + createDnsRecord: async (_zone, name) => ({ + content: '100::', + id: `resource-${resourceIndex++}`, + name, + proxied: true, + type: 'AAAA', + }), + createZone: async () => { + throw new Error('existing zone must not be created'); + }, + createKvNamespace: created, + createR2Bucket: created, + createQueue: created, + createDispatchNamespace: created, + createHyperdrive: async (account, name) => created(account, name), + deleteKvValue: async (_account, _namespace, key) => { + lifecycleEvents.push(`delete:${key}`); + routingValues.delete(key); + }, + putKvValue: async (_account, _namespace, key, value) => { + routingValues.set(key, value); + if (key === PLATFORM_DISABLED_KEY) { + lifecycleEvents.push(`put:${key}`); + } + if (key === '__void/platform/installation/v1') { + remoteManifest = value; + } + }, + putR2Object: async (_account, _bucket, _key, value) => { + r2OwnershipMarker = value; + }, }, - putKvValue: async (_account, _namespace, key, value) => { - routingValues.set(key, value); - if (key === PLATFORM_DISABLED_KEY) { - lifecycleEvents.push(`put:${key}`); - } - if (key === '__void/platform/installation/v1') { - remoteManifest = value; + deployWorker: async (config, secrets) => { + expect(routingValues.get(PLATFORM_DISABLED_KEY)).toBe(PLATFORM_DISABLED_VALUE); + expect(JSON.parse(routingValues.get(PLATFORM_SANDBOX_DRAIN_KEY)!)).toMatchObject({ + state: 'complete', + version: 1, + }); + lifecycleEvents.push(`deploy:${String(config.name)}`); + deployed.push(String(config.name)); + deployedTrafficStates.push( + (config.vars as Record).PLATFORM_TRAFFIC_STATE, + ); + if (String(config.name).endsWith('-api')) { + apiSecrets = secrets; } }, - putR2Object: async (_account, _bucket, _key, value) => { - r2OwnershipMarker = value; + migrateDatabase: async () => {}, + prepareSandboxDrain: async () => sandboxDrainPreparation('complete'), + revalidateBeforeWorkerDeploy: async () => {}, + verifyHealth: async () => { + expect(routingValues.get(PLATFORM_DISABLED_KEY)).toBe( + lifecycleEvents.includes('verify') ? undefined : PLATFORM_DISABLED_VALUE, + ); + lifecycleEvents.push('verify'); + }, + verifySandboxDrain: async () => { + throw new Error('an empty fresh installation must not require a manual drain'); }, }, - deployWorker: async (config, secrets) => { - expect(routingValues.get(PLATFORM_DISABLED_KEY)).toBe(PLATFORM_DISABLED_VALUE); - expect(JSON.parse(routingValues.get(PLATFORM_SANDBOX_DRAIN_KEY)!)).toMatchObject({ - state: 'complete', - version: 1, - }); - lifecycleEvents.push(`deploy:${String(config.name)}`); - deployed.push(String(config.name)); - deployedTrafficStates.push( - (config.vars as Record).PLATFORM_TRAFFIC_STATE, - ); - if (String(config.name).endsWith('-api')) { - apiSecrets = secrets; - } - }, - migrateDatabase: async () => {}, - prepareSandboxDrain: async () => sandboxDrainPreparation('complete'), - revalidateBeforeWorkerDeploy: async () => {}, - verifyHealth: async () => { - expect(routingValues.get(PLATFORM_DISABLED_KEY)).toBe( - lifecycleEvents.includes('verify') ? undefined : PLATFORM_DISABLED_VALUE, - ); - lifecycleEvents.push('verify'); - }, - verifySandboxDrain: async () => { - throw new Error('an empty fresh installation must not require a manual drain'); - }, - }, - ); + ); - expect(result.manifest.status).toBe('installed'); - expect(result.manifest.steps.some((step) => step.key === 'adoption-intent:zone')).toBe(true); - expect(databaseClaims).toEqual([[result.manifest.id, result.manifest.ownershipNonce]]); - expect(result.manifest.resources).toHaveLength(15); - expect(deployed).toEqual([ - result.manifest.deployment.resources.apiWorker, - result.manifest.deployment.resources.proxyWorker, - result.manifest.deployment.resources.tailWorker, - result.manifest.deployment.resources.dispatchWorker, - result.manifest.deployment.resources.apiWorker, - result.manifest.deployment.resources.proxyWorker, - result.manifest.deployment.resources.tailWorker, - result.manifest.deployment.resources.dispatchWorker, - ]); - expect(deployedTrafficStates).toEqual([ - 'staging', - 'staging', - undefined, - 'staging', - 'enabled', - 'enabled', - undefined, - 'enabled', - ]); - expect(apiSecrets).toMatchObject({ PLATFORM_BOOTSTRAP_GITHUB_ID: '583231' }); - expect(JSON.parse(r2OwnershipMarker)).toMatchObject({ - accountId: 'account', - installationId: result.manifest.id, - ownershipNonce: result.manifest.ownershipNonce, - resourceKey: 'assets-bucket', - }); - expect(JSON.parse(remoteManifest)).toMatchObject({ - id: result.manifest.id, - status: 'installed', - }); - expect(routingValues.get('signup:enabled')).toBe('true'); - expect(JSON.parse(routingValues.get('signup:allowlist')!)).toEqual([]); - expect(routingValues.has(PLATFORM_DISABLED_KEY)).toBe(false); - expect(lifecycleEvents[0]).toBe(`put:${PLATFORM_DISABLED_KEY}`); - expect(lifecycleEvents.filter((event) => event === 'verify')).toHaveLength(2); - expect(lifecycleEvents.indexOf('verify')).toBeLessThan( - lifecycleEvents.lastIndexOf(`deploy:${result.manifest.deployment.resources.dispatchWorker}`), - ); - expect(lifecycleEvents.indexOf(`delete:${PLATFORM_DISABLED_KEY}`)).toBeLessThan( - lifecycleEvents.lastIndexOf('verify'), - ); - expect(listInstallationManifests(directory)).toHaveLength(1); - expect(readdirSync(join(directory, 'account')).some((name) => name.endsWith('.secrets'))).toBe( - false, - ); - }); + expect(result.manifest.status).toBe('installed'); + expect(result.manifest.steps.some((step) => step.key === 'adoption-intent:zone')).toBe(true); + expect(databaseClaims).toEqual([[result.manifest.id, result.manifest.ownershipNonce]]); + expect(result.manifest.resources).toHaveLength(legacyRuntime ? 15 : 16); + const workerOrder = [ + result.manifest.deployment.resources.apiWorker, + result.manifest.deployment.resources.proxyWorker, + ...(!legacyRuntime ? [result.manifest.deployment.resources.emailGatewayWorker] : []), + result.manifest.deployment.resources.tailWorker, + result.manifest.deployment.resources.dispatchWorker, + ]; + expect(deployed).toEqual([...workerOrder, ...workerOrder]); + const trafficStates = legacyRuntime + ? ['staging', 'staging', undefined, 'staging', 'enabled', 'enabled', undefined, 'enabled'] + : [ + 'staging', + 'staging', + 'staging', + undefined, + 'staging', + 'enabled', + 'enabled', + 'enabled', + undefined, + 'enabled', + ]; + expect(deployedTrafficStates).toEqual(trafficStates); + expect(apiSecrets).toMatchObject({ PLATFORM_BOOTSTRAP_GITHUB_ID: '583231' }); + expect(JSON.parse(r2OwnershipMarker)).toMatchObject({ + accountId: 'account', + installationId: result.manifest.id, + ownershipNonce: result.manifest.ownershipNonce, + resourceKey: 'assets-bucket', + }); + expect(JSON.parse(remoteManifest)).toMatchObject({ + id: result.manifest.id, + status: 'installed', + }); + expect(routingValues.get('signup:enabled')).toBe('true'); + expect(JSON.parse(routingValues.get('signup:allowlist')!)).toEqual([]); + expect(routingValues.has(PLATFORM_DISABLED_KEY)).toBe(false); + expect(lifecycleEvents[0]).toBe(`put:${PLATFORM_DISABLED_KEY}`); + expect(lifecycleEvents.filter((event) => event === 'verify')).toHaveLength(2); + expect(lifecycleEvents.indexOf('verify')).toBeLessThan( + lifecycleEvents.lastIndexOf( + `deploy:${result.manifest.deployment.resources.dispatchWorker}`, + ), + ); + expect(lifecycleEvents.indexOf(`delete:${PLATFORM_DISABLED_KEY}`)).toBeLessThan( + lifecycleEvents.lastIndexOf('verify'), + ); + expect(listInstallationManifests(directory)).toHaveLength(1); + expect( + readdirSync(join(directory, 'account')).some((name) => name.endsWith('.secrets')), + ).toBe(false); + }, + ); it('closes the routing gate before an ambiguous fresh Worker upload', async () => { const directory = mkdtempSync(join(tmpdir(), 'void-platform-worker-ambiguity-test-')); @@ -3473,6 +3497,7 @@ describe('platform installer', () => { listWorkerNames: async () => [ deployment.resources.apiWorker, deployment.resources.proxyWorker, + deployment.resources.emailGatewayWorker, deployment.resources.tailWorker, deployment.resources.dispatchWorker, ], @@ -3665,7 +3690,7 @@ describe('platform installer', () => { authentication: { configurable: true, providers: ['google', 'oidc'] }, capabilities: { githubOAuth: false, googleOAuth: true }, }); - expect(emptyCoreUpgradeConfigs).toHaveLength(8); + expect(emptyCoreUpgradeConfigs).toHaveLength(10); expect(resumedSecretPayloads.slice(0, 2)).toEqual([ resumedUpdates, { CF_API_TOKEN: 'retry-cf-token' }, @@ -3673,12 +3698,12 @@ describe('platform installer', () => { expect( readInstallationRecoverySecrets(emptyCoreUpgrade.manifest)?.workerSecretUpdatesJson, ).toBe(undefined); - for (const index of [0, 1, 3]) { + for (const index of [0, 1, 2, 4]) { expect( (emptyCoreUpgradeConfigs[index]!.vars as Record).PLATFORM_TRAFFIC_STATE, ).toBe('staging'); } - for (const index of [4, 5, 7]) { + for (const index of [5, 6, 7, 9]) { expect( (emptyCoreUpgradeConfigs[index]!.vars as Record).PLATFORM_TRAFFIC_STATE, ).toBe('enabled'); @@ -3776,10 +3801,12 @@ describe('platform installer', () => { expect(sandboxDrainDeployments).toEqual([ deployment.resources.apiWorker, deployment.resources.proxyWorker, + deployment.resources.emailGatewayWorker, deployment.resources.tailWorker, deployment.resources.dispatchWorker, ]); expect(sandboxDrainTrafficStates).toEqual([ + 'sandbox-drain', 'sandbox-drain', 'sandbox-drain', undefined, @@ -3835,16 +3862,18 @@ describe('platform installer', () => { safetyProtocols: { sandboxDrain: 2 }, status: 'installed', }); - expect(resumedDrainDeployments).toHaveLength(8); - expect(resumedDrainDeployments.slice(0, 4)).toEqual([ + expect(resumedDrainDeployments).toHaveLength(10); + expect(resumedDrainDeployments.slice(0, 5)).toEqual([ `${deployment.resources.apiWorker}:sandbox-drain`, `${deployment.resources.proxyWorker}:sandbox-drain`, + `${deployment.resources.emailGatewayWorker}:sandbox-drain`, `${deployment.resources.tailWorker}:undefined`, `${deployment.resources.dispatchWorker}:sandbox-drain`, ]); - expect(resumedDrainDeployments.slice(4)).toEqual([ + expect(resumedDrainDeployments.slice(5)).toEqual([ `${deployment.resources.apiWorker}:enabled`, `${deployment.resources.proxyWorker}:enabled`, + `${deployment.resources.emailGatewayWorker}:enabled`, `${deployment.resources.tailWorker}:undefined`, `${deployment.resources.dispatchWorker}:enabled`, ]); @@ -3895,10 +3924,12 @@ describe('platform installer', () => { expect(deployed).toEqual([ deployment.resources.apiWorker, deployment.resources.proxyWorker, + deployment.resources.emailGatewayWorker, deployment.resources.tailWorker, deployment.resources.dispatchWorker, deployment.resources.apiWorker, deployment.resources.proxyWorker, + deployment.resources.emailGatewayWorker, deployment.resources.tailWorker, deployment.resources.dispatchWorker, ]); @@ -3916,7 +3947,7 @@ describe('platform installer', () => { manifestSha256: expect.stringMatching(/^[0-9a-f]{64}$/), source: 'custom', }); - expect(upgraded.manifest.resources).toHaveLength(15); + expect(upgraded.manifest.resources).toHaveLength(16); const currentRuntime = resolvePlatformRuntime(getPlatformRuntimeDirectory()); const earlierDatabase = migrationSubset(currentRuntime.manifest.database.migrations.length - 1); @@ -4051,7 +4082,7 @@ describe('platform installer', () => { }, }); expect(downgradeEvents[0]).toBe('gate:closed'); - expect(downgradeEvents.filter((event) => event.startsWith('deploy:'))).toHaveLength(8); + expect(downgradeEvents.filter((event) => event.startsWith('deploy:'))).toHaveLength(10); expect(downgradeEvents.indexOf('gate:open')).toBeGreaterThan( downgradeEvents.lastIndexOf(`deploy:${deployment.resources.dispatchWorker}`), ); @@ -4115,13 +4146,13 @@ describe('platform installer', () => { ...repairEvents.flatMap((event, index) => (event.startsWith('deploy:') ? [index] : [])), ), ); - expect(repairedWorkerConfigs).toHaveLength(8); - for (const index of [0, 1, 3]) { + expect(repairedWorkerConfigs).toHaveLength(10); + for (const index of [0, 1, 2, 4]) { expect( (repairedWorkerConfigs[index]!.vars as Record).PLATFORM_TRAFFIC_STATE, ).toBe('staging'); expect( - (repairedWorkerConfigs[index + 4]!.vars as Record).PLATFORM_TRAFFIC_STATE, + (repairedWorkerConfigs[index + 5]!.vars as Record).PLATFORM_TRAFFIC_STATE, ).toBe('enabled'); } @@ -4179,8 +4210,8 @@ describe('platform installer', () => { ); expect(legacyEnableResult.waitingForSandboxDrain).toBe(true); expect(legacyEnableGateOpened).toBe(false); - expect(legacyEnableConfigs).toHaveLength(4); - for (const index of [0, 1, 3]) { + expect(legacyEnableConfigs).toHaveLength(5); + for (const index of [0, 1, 2, 4]) { expect( (legacyEnableConfigs[index]!.vars as Record).PLATFORM_TRAFFIC_STATE, ).toBe('sandbox-drain'); @@ -4213,7 +4244,7 @@ describe('platform installer', () => { ); expect(disabledUpgrade.manifest.status).toBe('disabled'); expect(disabledHealthChecks).toBe(0); - expect(disabledConfigs).toHaveLength(4); + expect(disabledConfigs).toHaveLength(5); for (const config of disabledConfigs) { expect(config.workers_dev).toBe(false); expect(config.preview_urls).toBe(false); @@ -4256,7 +4287,7 @@ describe('platform installer', () => { }, ); expect(resumedDisabledUpgrade.manifest.status).toBe('disabled'); - expect(resumedConfigs).toHaveLength(4); + expect(resumedConfigs).toHaveLength(5); for (const config of resumedConfigs) { expect(config.workers_dev).toBe(false); expect(config.preview_urls).toBe(false); @@ -4325,12 +4356,12 @@ describe('platform installer', () => { deployWorker: async (config) => { const deploymentIndex = ++failedEnableDeploys; failedEnableEvents.push(`deploy:${deploymentIndex}:${String(config.name)}`); - if (deploymentIndex === 6) { + if (deploymentIndex === 7) { throw new Error('generation 2 deployment failed'); } return async () => { failedEnableEvents.push(`rollback:${deploymentIndex}:${String(config.name)}`); - if (deploymentIndex === 5) { + if (deploymentIndex === 6) { throw new Error('generation 2 rollback failed'); } }; @@ -4344,7 +4375,7 @@ describe('platform installer', () => { 'generation 2 deployment failed Automatic Worker rollback was incomplete: generation 2 rollback failed', ); expect(failedEnableEvents.filter((event) => event.startsWith('rollback:'))).toEqual([ - `rollback:5:${deployment.resources.apiWorker}`, + `rollback:6:${deployment.resources.apiWorker}`, ]); const failedEnableManifest = listInstallationManifests(directory)[0]!; @@ -4361,14 +4392,14 @@ describe('platform installer', () => { verifyHealth: async () => {}, }); expect(retriedEnable.manifest.status).toBe('installed'); - expect(retryPreviousConfigs).toHaveLength(8); - expect(retryPreviousConfigs.slice(0, 4).every((config) => config.workers_dev === false)).toBe( + expect(retryPreviousConfigs).toHaveLength(10); + expect(retryPreviousConfigs.slice(0, 5).every((config) => config.workers_dev === false)).toBe( true, ); - expect(retryPreviousConfigs.slice(4).every((config) => config.workers_dev === true)).toBe(true); + expect(retryPreviousConfigs.slice(5).every((config) => config.workers_dev === true)).toBe(true); expect( retryPreviousConfigs - .slice(4) + .slice(5) .filter((config) => !String(config.name).endsWith('-tail')) .every( (config) => (config.vars as Record).PLATFORM_TRAFFIC_STATE === 'staging', @@ -4404,19 +4435,19 @@ describe('platform installer', () => { expect(enabledUpgrade.manifest.deployment.authentication.configurable).toBe(true); expect(enabledHealthChecks).toBe(2); expect(deletedKvValues).toContain('__void/platform/disabled/v1'); - expect(enabledConfigs).toHaveLength(8); - for (const config of enabledConfigs.slice(0, 4)) { + expect(enabledConfigs).toHaveLength(10); + for (const config of enabledConfigs.slice(0, 5)) { expect((config.vars as Record).PLATFORM_TRAFFIC_STATE).not.toBe('enabled'); } - for (const config of enabledConfigs.slice(4)) { + for (const config of enabledConfigs.slice(5)) { expect(config.workers_dev).toBe(true); - expect(config.preview_urls).toBe(true); + expect(config.preview_urls).toBe(config.name !== deployment.resources.emailGatewayWorker); if (!String(config.name).endsWith('-tail')) { expect((config.vars as Record).PLATFORM_TRAFFIC_STATE).toBe('enabled'); } } expect( - enabledConfigs.slice(4).find((config) => config.name === deployment.resources.dispatchWorker), + enabledConfigs.slice(5).find((config) => config.name === deployment.resources.dispatchWorker), ).toHaveProperty('routes'); const disabledRollbackStates: Array = []; @@ -4494,7 +4525,7 @@ describe('platform installer', () => { expect(partialEvents).toEqual([ `deploy:${deployment.resources.apiWorker}`, `deploy:${deployment.resources.proxyWorker}`, - `deploy:${deployment.resources.tailWorker}`, + `deploy:${deployment.resources.emailGatewayWorker}`, `rollback:${deployment.resources.proxyWorker}`, `rollback:${deployment.resources.apiWorker}`, ]); @@ -4519,9 +4550,10 @@ describe('platform installer', () => { }, }), ).rejects.toThrow('health check failed'); - expect(healthEvents.slice(-4)).toEqual([ + expect(healthEvents.slice(-5)).toEqual([ `rollback:${deployment.resources.dispatchWorker}`, `rollback:${deployment.resources.tailWorker}`, + `rollback:${deployment.resources.emailGatewayWorker}`, `rollback:${deployment.resources.proxyWorker}`, `rollback:${deployment.resources.apiWorker}`, ]); @@ -4547,7 +4579,7 @@ describe('platform installer', () => { ).rejects.toThrow( 'health check failed Automatic Worker rollback was incomplete: rollback unavailable', ); - expect(rollbackIndex).toBe(4); + expect(rollbackIndex).toBe(5); const interruptedCutover = { ...enabledUpgrade.manifest, diff --git a/packages/void/test/unit/platform-plan.test.ts b/packages/void/test/unit/platform-plan.test.ts index d1d1b98cb..3adf718b0 100644 --- a/packages/void/test/unit/platform-plan.test.ts +++ b/packages/void/test/unit/platform-plan.test.ts @@ -80,6 +80,61 @@ function legacyInstallation(suffix = '0123456789ab') { } describe('platform installation planning', () => { + it('persists the shared email zone separately from the application zone on resume', async () => { + const configured = await createPlatformInstallPlan( + client(), + { ...input, emailSharedZoneId: 'mail-zone-id', emailSenderDomain: 'mail.example.org' }, + null, + ); + expect(configured.deployment.emailSharedZoneId).toBe('mail-zone-id'); + expect(configured.deployment.emailSenderDomain).toBe('mail.example.org'); + const manifest = createPlatformInstallationManifest({ + account: configured.account, + deployment: configured.deployment, + id: configured.installationId, + ownershipNonce: '0123456789abcdef0123456789abcdef', + platformVersion: '1.0.0', + createdAt: '2026-09-17T00:00:00.000Z', + }); + const resumed = await createPlatformInstallPlan(client(), input, manifest); + expect(resumed.deployment.emailSharedZoneId).toBe('mail-zone-id'); + expect(resumed.deployment.emailSenderDomain).toBe('mail.example.org'); + expect(resumed.zone?.id).not.toBe('mail-zone-id'); + }); + + it('adds a configured shared email zone to a previously unconfigured installation', async () => { + const initial = await createPlatformInstallPlan(client(), input, null); + const manifest = createPlatformInstallationManifest({ + account: initial.account, + deployment: initial.deployment, + id: initial.installationId, + ownershipNonce: '0123456789abcdef0123456789abcdef', + platformVersion: '1.0.0', + createdAt: '2026-09-17T00:00:00.000Z', + }); + const upgraded = await createPlatformInstallPlan( + client(), + { ...input, emailSharedZoneId: 'mail-zone-id', emailSenderDomain: 'mail.example.org' }, + manifest, + ); + expect(upgraded.deployment.emailSharedZoneId).toBe('mail-zone-id'); + expect(upgraded.deployment.emailSenderDomain).toBe('mail.example.org'); + await expect( + createPlatformInstallPlan( + client(), + { ...input, emailSenderDomain: 'other.example.org' }, + createPlatformInstallationManifest({ + account: upgraded.account, + deployment: upgraded.deployment, + id: upgraded.installationId, + ownershipNonce: '0123456789abcdef0123456789abcdef', + platformVersion: '1.0.0', + createdAt: '2026-09-17T00:00:00.000Z', + }), + ), + ).rejects.toThrow('already recorded'); + }); + it('resumes the recorded namespaces using the real unfiltered KV API response', async () => { const initial = await createPlatformInstallPlan(client(), input, null); let manifest = createPlatformInstallationManifest({ @@ -253,7 +308,7 @@ describe('platform installation planning', () => { zoneName: '', workersDev: { subdomain: 'example' }, }); - expect(plan.actions.filter((action) => action.kind === 'worker')).toHaveLength(4); + expect(plan.actions.filter((action) => action.kind === 'worker')).toHaveLength(5); }); it('rejects an uncovered nested application domain before resource inventory', async () => { let inventoried = false; @@ -378,7 +433,7 @@ describe('platform installation planning', () => { const plan = await createPlatformInstallPlan(fake, input, null); expect(plan.apiUrl).toBe(`https://${plan.deployment.resources.apiWorker}.example.workers.dev`); expect(plan.deployment.resources.apiWorker).toBe('void-example-api'); - expect(plan.actions).toHaveLength(15); + expect(plan.actions).toHaveLength(16); expect(plan.actions.every((action) => action.action === 'create')).toBe(true); expect(Object.keys(fake)).not.toContain('createZone'); }); diff --git a/packages/void/test/unit/platform-recovery.test.ts b/packages/void/test/unit/platform-recovery.test.ts index 3b47d75af..eb2885443 100644 --- a/packages/void/test/unit/platform-recovery.test.ts +++ b/packages/void/test/unit/platform-recovery.test.ts @@ -81,6 +81,12 @@ function remoteManifest() { ['hyperdrive', 'hyperdrive', 'hyperdrive-id', deployment.resources.hyperdrive], ['api-worker', 'worker', deployment.resources.apiWorker, deployment.resources.apiWorker], ['proxy-worker', 'worker', deployment.resources.proxyWorker, deployment.resources.proxyWorker], + [ + 'email-gateway-worker', + 'worker', + deployment.resources.emailGatewayWorker, + deployment.resources.emailGatewayWorker, + ], ['tail-worker', 'worker', deployment.resources.tailWorker, deployment.resources.tailWorker], [ 'dispatch-worker', @@ -242,6 +248,7 @@ function client(manifest = remoteManifest()) { listWorkerNames: async () => [ manifest.deployment.resources.apiWorker, manifest.deployment.resources.proxyWorker, + manifest.deployment.resources.emailGatewayWorker, manifest.deployment.resources.tailWorker, manifest.deployment.resources.dispatchWorker, ], diff --git a/packages/void/test/unit/platform-rollback.test.ts b/packages/void/test/unit/platform-rollback.test.ts index b665297dc..32878ff0e 100644 --- a/packages/void/test/unit/platform-rollback.test.ts +++ b/packages/void/test/unit/platform-rollback.test.ts @@ -77,6 +77,56 @@ function installed(source: PlatformRuntime) { } describe('platform post-success rollback', () => { + it('blocks rollback to a four-Worker runtime after the email gateway was installed', () => { + const target = runtime({ + digest: 'a'.repeat(64), + migrations: [firstMigration], + platformVersion: '1.0.0', + schemaDigest: 'c'.repeat(64), + }); + const source = runtime({ + digest: 'b'.repeat(64), + migrations: [firstMigration, secondMigration], + platformVersion: '1.1.0', + schemaDigest: 'd'.repeat(64), + rollbackSafeFrom: [{ platformVersion: '1.0.0', schemaDigest: 'c'.repeat(64) }], + }); + const installation = installed(source); + expect(() => + assertPlatformRollbackCompatibility( + { + ...installation, + resources: [ + ...installation.resources, + { + configHash: '', + key: 'email-gateway-worker', + kind: 'worker', + id: installation.deployment.resources.emailGatewayWorker, + name: installation.deployment.resources.emailGatewayWorker, + ownership: 'created', + state: 'ready', + }, + ], + }, + target, + source, + ), + ).toThrow('predates the email gateway'); + expect(() => + assertPlatformRollbackCompatibility( + { + ...installation, + deployment: { + ...installation.deployment, + capabilities: { ...installation.deployment.capabilities, email: true }, + }, + }, + target, + source, + ), + ).toThrow('predates the email gateway'); + }); it('blocks a runtime without human-session revocation even when its database rollback is declared safe', () => { const target = runtime({ digest: 'a'.repeat(64), diff --git a/packages/void/test/unit/platform-runtime.test.ts b/packages/void/test/unit/platform-runtime.test.ts index 2e597b12f..7b6fe79e4 100644 --- a/packages/void/test/unit/platform-runtime.test.ts +++ b/packages/void/test/unit/platform-runtime.test.ts @@ -110,6 +110,17 @@ describe('platform runtime manifest', () => { expect(parsePlatformRuntimeManifest(legacy).usageProtocolVersion).toBe(0); const { safetyProtocols: _safetyProtocols, ...legacySafety } = manifest; expect(parsePlatformRuntimeManifest(legacySafety).safetyProtocols).toEqual({ sandboxDrain: 0 }); + const { emailGateway: _gateway, ...fourArtifacts } = manifest.artifacts; + const { emailProtocolVersion: _emailProtocolVersion, ...preEmailRuntime } = manifest; + expect( + parsePlatformRuntimeManifest({ + ...preEmailRuntime, + artifacts: fourArtifacts, + }).artifacts.emailGateway, + ).toBeUndefined(); + expect(() => parsePlatformRuntimeManifest({ ...manifest, artifacts: fourArtifacts })).toThrow( + 'Email protocol version 1 requires an emailGateway runtime artifact', + ); }); it('resolves packaged and explicit runtime directories with provenance', () => { diff --git a/packages/void/vite.config.ts b/packages/void/vite.config.ts index 5dc273f75..ea2b38c69 100644 --- a/packages/void/vite.config.ts +++ b/packages/void/vite.config.ts @@ -121,6 +121,7 @@ export default defineConfig({ 'src/runtime/log.ts', 'src/runtime/ai.ts', 'src/runtime/email.ts', + 'src/runtime/email-protocol.ts', 'src/runtime/email/testing.ts', 'src/runtime/sandbox.ts', 'src/runtime/remote/index.ts', diff --git a/platform/README.md b/platform/README.md index 09946988c..647016cb8 100644 --- a/platform/README.md +++ b/platform/README.md @@ -4,7 +4,7 @@ The Void platform runs in your Cloudflare account and lets developers deploy applications through the Void CLI. This repository contains its control plane, routing, proxy, log ingestion, and optional dashboard and build services. -The core API, dispatch, proxy, and tail Workers are packaged into +The API, dispatch, proxy, tail, and email gateway Workers are packaged into [`@void/platform`](../packages/platform/README.md). A released or source-built runtime can be installed and upgraded with `void platform`. The installer tracks resource ownership, applies compatible migrations, and preserves credentials @@ -163,6 +163,7 @@ Void is one repository with an explicit dependency boundary: | [`packages/api`](./packages/api/README.md) | Control plane API, deploy pipeline, provisioning, administrator UI | | [`packages/dashboard`](./packages/dashboard/README.md) | User-facing dashboard app | | [`packages/dispatch`](./packages/dispatch/README.md) | Edge router for installation app domains and custom domains | +| `packages/email-gateway` | Email ingress, bounded tenant delivery, and validated email actions | | [`packages/proxy`](./packages/proxy/README.md) | AI proxy, remote D1/KV/R2 proxy, ISR revalidation bridge | | [`packages/tail`](./packages/tail/README.md) | Runtime log ingestion into Analytics Engine | | [`../packages/void`](../packages/void/AGENTS.md) | Main `void` package: Vite plugin, CLI, runtime, codegen, deploy packaging | @@ -175,26 +176,26 @@ Void is one repository with an explicit dependency boundary: ### Where Code for X Lives -| Feature | Primary code paths | -| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Vite plugin and local runtime | `../packages/void/src/index.ts`, `plugin-*`, `runtime/*` | -| CLI commands | `../packages/void/src/cli/*` | -| File-based API routing | `../packages/void/src/router/*`, `runtime/handler.ts` | -| Pages routing, loaders, actions, named actions, deferred props | `../packages/void/src/pages/*`, adapter runtimes in `../packages/{vue,react,svelte,solid}/src/runtime/*` | -| Typed route/page/action codegen | `../packages/void/src/codegen/*`, `routes-stub.ts` | -| Binding inference | `../packages/void/src/plugin-inference.ts`, `../packages/void/src/inference/*` | -| Drizzle integration and migrations | `../packages/void/src/drizzle/*`, `../packages/void/src/migrations/*` | -| Framework detection and deploy presets | `../packages/void/src/plugin-inference.ts`, `../packages/void/src/cli/preset.ts` | -| Platform auth and project APIs | `packages/api/src/routes/*`, `packages/api/src/auth/*`, `packages/api/src/middleware/*` | -| Administrator UI | `packages/api/src/admin/*` | -| Deploy pipeline | `../packages/void/src/cli/deploy.ts`, `packages/api/src/routes/deploy.ts`, `packages/api/src/assets.ts`, `packages/api/src/provisioning/*` | -| Deploy on GitHub (App connect, webhooks, OIDC, build containers) | `packages/api/src/routes/{github,webhooks,auth-oidc}.ts`, `packages/api/src/github/*`, `packages/api/src/build-scheduler.ts`, `packages/api/src/build-manager.ts`, `packages/api/container/*`, `packages/api/src/auth/deploy-token.ts` | -| Hostname routing, static serving, ISR, redirects, rewrites, headers, metering | `packages/dispatch/src/*` | -| AI metering, BYOK AI gateway, remote D1/KV/R2 access, revalidation bridge | `packages/proxy/src/*` | -| Email (shared sender, custom domains, recipient policy, admin-managed domains) | `packages/proxy/src/email*.ts`, `packages/api/src/routes/email.ts`, `packages/api/src/email/*`, `packages/api/src/operator/email-routes.ts`, `packages/api/src/admin/routes/email.tsx`, `../packages/void/src/cli/email*.ts`, `../packages/void/src/runtime/email*` | -| Runtime logs and live tailing | `packages/tail/src/index.ts`, `packages/api/src/admin/routes/deployments.tsx` | -| User-facing dashboard | `packages/dashboard/pages/*`, `packages/dashboard/middleware/01.auth.ts`, `packages/dashboard/lib/api.ts` | -| Dashboard styling | `packages/dashboard/ui/styles/base.css`, `packages/dashboard/ui/styles/tokens.css` | +| Feature | Primary code paths | +| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Vite plugin and local runtime | `../packages/void/src/index.ts`, `plugin-*`, `runtime/*` | +| CLI commands | `../packages/void/src/cli/*` | +| File-based API routing | `../packages/void/src/router/*`, `runtime/handler.ts` | +| Pages routing, loaders, actions, named actions, deferred props | `../packages/void/src/pages/*`, adapter runtimes in `../packages/{vue,react,svelte,solid}/src/runtime/*` | +| Typed route/page/action codegen | `../packages/void/src/codegen/*`, `routes-stub.ts` | +| Binding inference | `../packages/void/src/plugin-inference.ts`, `../packages/void/src/inference/*` | +| Drizzle integration and migrations | `../packages/void/src/drizzle/*`, `../packages/void/src/migrations/*` | +| Framework detection and deploy presets | `../packages/void/src/plugin-inference.ts`, `../packages/void/src/cli/preset.ts` | +| Platform auth and project APIs | `packages/api/src/routes/*`, `packages/api/src/auth/*`, `packages/api/src/middleware/*` | +| Administrator UI | `packages/api/src/admin/*` | +| Deploy pipeline | `../packages/void/src/cli/deploy.ts`, `packages/api/src/routes/deploy.ts`, `packages/api/src/assets.ts`, `packages/api/src/provisioning/*` | +| Deploy on GitHub (App connect, webhooks, OIDC, build containers) | `packages/api/src/routes/{github,webhooks,auth-oidc}.ts`, `packages/api/src/github/*`, `packages/api/src/build-scheduler.ts`, `packages/api/src/build-manager.ts`, `packages/api/container/*`, `packages/api/src/auth/deploy-token.ts` | +| Hostname routing, static serving, ISR, redirects, rewrites, headers, metering | `packages/dispatch/src/*` | +| AI metering, BYOK AI gateway, remote D1/KV/R2 access, revalidation bridge | `packages/proxy/src/*` | +| Email (shared sender, custom domains, recipient policy, admin-managed domains) | `packages/email-gateway/src/*`, `packages/proxy/src/email*.ts`, `packages/api/src/routes/email.ts`, `packages/api/src/email/*`, `packages/api/src/operator/email-routes.ts`, `packages/api/src/admin/routes/email.tsx`, `../packages/void/src/cli/email*.ts`, `../packages/void/src/runtime/email*` | +| Runtime logs and live tailing | `packages/tail/src/index.ts`, `packages/api/src/admin/routes/deployments.tsx` | +| User-facing dashboard | `packages/dashboard/pages/*`, `packages/dashboard/middleware/01.auth.ts`, `packages/dashboard/lib/api.ts` | +| Dashboard styling | `packages/dashboard/ui/styles/base.css`, `packages/dashboard/ui/styles/tokens.css` | The dashboard depends on `void` and `@void/react` through normal `workspace:*` dependencies. Those packages export only their `dist/` output, so run `vp run build` before `vp run --filter @voidcloud/platform deploy` on a fresh checkout. The platform workflows do this; the task graph does not. diff --git a/platform/meta/design-docs/0078-email-cf-native.md b/platform/meta/design-docs/0078-email-cf-native.md index a72cb2b8e..500ae05ea 100644 --- a/platform/meta/design-docs/0078-email-cf-native.md +++ b/platform/meta/design-docs/0078-email-cf-native.md @@ -1,123 +1,61 @@ --- title: Cloudflare-Native Email Design -status: implemented +status: draft created: 2026-04-24 updated: 2026-09-18 --- # Cloudflare-native email design -The [email guide](../../../docs/guide/email.md) and the -[administration guide](../../../docs/guide/platform-administration.md#managing-email) -describe the supported API and setup. This record holds the trust boundaries, -lifecycle rules and accepted limitations behind them. - -## Hosting modes - -### Mode A — managed platform - -The platform proxy owns the account-level `send_email` binding. Tenant -Workers receive only the authenticated `__VOID_PROXY` interface; a raw send -binding would bypass destination consent, suspension and quota policy. - -The mail domain is configured per environment as `EMAIL_SENDER_DOMAIN` and -injected as `__VOID_EMAIL_DOMAIN`. Missing configuration fails closed. The -project-slug binding is `__VOID_PROJECT_SLUG`; senders must belong to that -project's namespace on the configured mail domain. - -#### Verified destinations - -Cloudflare's account-level verification does not establish consent for every -project on the account. `email_destinations.verification_source` keeps the -distinction: +Email has not been released to production. This document defines the target +for the first production release, including routing, setup, credential lifecycle, +delivery policy and observable outcomes. The implementation already provides the +`void/email` programming model; the remaining architecture and verification work +below must be completed before release. -- **Owner inheritance** — an already verified address matching the current - project owner's email inherits that owner's consent. The owner email is - rechecked inside the transaction that writes or promotes the destination; - an owner-email change revokes inherited consent and tightens the allowlist - without silently committing a failed tighten. -- **Platform confirmation** — an address verified for another project stays - pending until the recipient follows this project's signed confirmation - link. A Cloudflare refresh cannot bypass this gate. -- A newly registered Cloudflare destination is promoted only when the - verified tag matches the project's registration; an unrelated recreation of - the same address proves nothing. - -The proxy reads `email-allowlist:` from routing KV. Destination -listing repairs a missing or inconsistent mirror from the authoritative -verified rows; an absent mirror fails closed. A verified platform row is not -revoked by an out-of-band Cloudflare deletion; Cloudflare refuses the actual -send until its destination is verified again. - -#### Recipient policy - -One installation-wide setting decides whether the per-project allowlist gates -shared-sender recipients: - -``` - mode shared-sender recipient passes when … default - ───────── ──────────────────────────────────────────────────── ─────── - verified it is on the project's allowlist yes - domains its domain is in the policy list, OR it is allowlisted - any always -``` - -The policy does not fake delivery: Cloudflare's `send_email` binding still -refuses an unverified destination unless the platform mail domain is onboarded -for Email Sending (Workers Paid on the operator's account). Under `domains` or -`any` that refusal still arrives as a per-recipient `UNVERIFIED_DESTINATION`; -the admin UI and the operator preview say so next to the policy. - -Scope: shared-sender sends and the inbound forward/reply gate -(`recipientAllowed` in the proxy's `email-policy.ts`, one gate for both). -Custom-domain sends are unchanged. Burst cap, monthly cap, the -`email-suspended:` kill switch and the reply-sender pin do not move. The -policy never widens delivery to an address on the platform's own mail domains -— `EMAIL_SENDER_DOMAIN` and, on inbound, the domain Cloudflare accepted the -message on, so an unset binding or a second routed domain opens nothing: -another tenant's `+tag@` inbox is reached only through that project's -verified-destination consent, whatever the mode — so `any` cannot turn two -auto-replying handlers into a loop or one tenant into another's spam source. -A tightening reaches every colo within the mirror's 60-second read cache. - -Storage: authoritative in the `platform_settings` table (key/value jsonb — -the installation's runtime-changeable settings), mirrored to routing KV as -`email-recipient-policy` for the proxy's hot path (`cacheTtl: 60`, like the -allowlist). An absent or unreadable mirror means `verified` — `any` included -when its shape is not the api's. A publish is ONE KV write — Workers KV -refuses a second write to a key within a second, so the mirror is never -cleared and re-put — ordered so the mirror never authorizes a recipient the -database has not committed: a tightening (a lower mode, or a list that only -shrinks) puts the mirror before the database commits — a refused put leaves -the saved policy unchanged, a failed commit leaves the proxy stricter until -the next read republishes; a widening (a higher mode, or a list that gains -any domain, even one that also drops others) commits first and puts after — -a failed put leaves the previous policy in force, the operator told so, -until a retry or the next read republishes. The one residual is that -previous policy: for a list edited both ways, its removed domains stay -reachable until the republish, exactly as they were a moment earlier. -Publisher and -repair serialize on a transaction-scoped advisory lock because KV has no -compare-and-set, and every read surface (operator, owner settings, admin -page) repairs a drifted mirror. Surface: the admin UI's **Email** page and -`void platform email policy` / `policy-set [--domains a,b]`, recorded -in `operator_events`. - -#### Quotas and visibility - -Outbound sends and inbound forward/reply actions share destination, -suspension, burst and monthly checks. Burst and monthly caps apply to every -send through the proxy, custom domain included, and are -administrator-controlled per project. The counters are KV read-modify-write -and best-effort under concurrency, not strict admission limits. - -Destination listing picks up pending Cloudflare verification; Cloudflare does -not push that event. Persistent project delivery logs are not implemented: -`void email logs` reports pending support. A handled inbound message can still -have a forward or reply refused by its outbound gate; a handled receipt is not -proof of delivery. - -### Mode B — the developer's own Cloudflare account +The [email guide](../../../docs/guide/email.md) and +[administration guide](../../../docs/guide/platform-administration.md#managing-email) +will be aligned with the completed implementation. The control-flow diagrams in +this document describe the intended behavior, not a claim that every path is +already implemented. + +## Decisions + +| Concern | Design decision | +| ----------------- | -------------------------------------------------------------------------------- | +| Routing ownership | One zone ingress, many explicitly registered mail domains | +| Company setup | Shared sender and project subdomains share the zone ingress | +| Provisioning | Durable operation steps, provider read-back and resumable reconciliation | +| Credentials | Scoped API token by default; operator credential for administrator-managed zones | +| Tenant response | Byte-bounded HTTP response with a constrained action format | +| Admission | Authoritative policy, suspension and quota reservation in PostgreSQL | +| Outcomes | Durable, queryable action outcomes, including uncertainty | +| Readiness | Separate inbound, outbound and management readiness | + +The platform already depends on PostgreSQL. Use that authority for the first +version instead of adding another state store. This adds latency and makes email +admission depend on database availability; it is an explicit correctness tradeoff. +Measure the cost before considering another serialized admission service. + +## Hosting boundaries + +- **Managed and self-hosted platforms:** tenant Workers get only the authenticated + proxy interface. Platform services own credentials, delivery policy, quota + accounting and provider calls. Both installations use this design. +- **Native Cloudflare deployments:** the app keeps its own send binding and native + email event. No platform database, admission service, relay or outcome ledger is + required. Keep the existing setup preflight, ownership checks and local inbox. +- **Development:** capture remains local and authenticated with the dev-trigger + token. `sendInDev` does not create a production transport. + +Native deployments remain Workers Free-compatible for routing and verified +recipients. Arbitrary-recipient sending is an explicit Email Sending capability +requiring Workers Paid on the sending account. Probe entitlement only when that +capability is requested, before provisioning it; name the plan, enablement link +and permissions in the error. An app without email gets no email binding or probe. +These distinctions follow [Cloudflare's current pricing](https://developers.cloudflare.com/email-service/platform/pricing/). + +## Native Cloudflare setup Native setup lives in [email-cloudflare.ts](../../../packages/void/src/cli/email-cloudflare.ts). @@ -125,7 +63,7 @@ Native setup lives in read-only preflight and selected Wrangler session. The developer supplies `email.from`; Void never chooses a mail domain. -#### One keystroke +### One keystroke Interactive deployment shows the selected account, the domain and the unfinished account changes before offering setup. Non-interactive deployment @@ -138,7 +76,7 @@ The checklist separates account work, config updates and routing rules. rerun account onboarding. A refused Sending onboarding is retried only by an explicit `void email setup`. -#### The flow, by lane +### The flow, by lane 1. Read domain DNS, account identity, routing settings, existing rules and Sending state before applying anything. @@ -146,13 +84,13 @@ explicit `void email setup`. sender uses a subdomain. 3. Enable the zone's `support_subaddress` setting when needed; a literal address rule alone does not deliver `support+tag@`. -4. Attempt Sending onboarding; report plan or permission refusals without - touching unrelated records. +4. Attempt Sending onboarding only when arbitrary-recipient sending is + requested; report plan or permission refusals without touching unrelated records. 5. Reconcile the owned sender and binding configuration. Write `addresses` only when inbound routing is ready, then let pinned Wrangler apply it. 6. Print the inbound map and the remaining manual steps. -#### Credentials +### Credentials Use pinned Wrangler commands wherever one exists. For zone classification, subdomain routing and subaddressing — calls with no Wrangler command — borrow @@ -167,7 +105,7 @@ where the bridge needs a bearer. Prose parsers are pinned to the bundled Wrangler version and tested against its captured output; a parser miss yields unknown state and setup guidance, never permission to write. -#### The `addresses` array +### The `addresses` array Void owns the whole derived top-level `addresses` array. Hand-written entries it cannot derive skip setup without changing the array. Addresses already @@ -176,7 +114,7 @@ deleted, never written as `[]` — that would ask Wrangler to delete every owned rule. The root config is re-read after edits and the deployment verifier's whole-array check is preserved. -#### Error map and degraded branches +### Error map and degraded branches Known provider errors are classified for routing-not-enabled, already-onboarded and Sending-entitlement refusals. Unknown failures stay @@ -188,7 +126,7 @@ never reported complete merely because the Worker uploaded. Sender config and an inert send binding remain useful for verified destinations when arbitrary-recipient Sending is unavailable. -#### Unverified against live Cloudflare +### Unverified against live Cloudflare Unit tests are not provider acceptance. Still to establish with the selected credential type, per the [live release procedure](../release-acceptance.md): @@ -196,729 +134,543 @@ the subdomain routing POST and subaddressing PATCH, rule-plan permissions, conflict behavior after dashboard edits or Worker renames, and multi-label mail subdomains. -### Mode C — self-hosted platform - -The same proxy and consent rules apply to an operator-owned platform. The -operator configures its mail domain, sender, proxy binding and Email Routing -before enabling email; core installation does not do this automatically. Use -[platform operations](../operations.md) for the operator workflow. - -Users of a self-hosted platform may hold no Cloudflare credential at all. -[Administrator-managed domains](#administrator-managed-domains) covers -that case; the engine below is unchanged by it. - -## Cross-worker dispatch - -Cloudflare's `ForwardableEmailMessage` is not serializable over RPC. The -proxy buffers a bounded envelope and calls the tenant's -`WorkerEntrypoint.email()`; the generated handler returns action intents, -and the proxy validates and enacts them against the original message. - -The wire recipient travels as `__voidPlatformTo` for dispatch. The platform -slug prefix is stripped exactly once for the user-facing message. Matching is -case-insensitive and preserves the original case of captured parameters. - -Pre-buffering bounds the inbound raw body and the distinct header count before -the RPC envelope is built. Forward/reply/reject validation bounds action -count, address and header size and cumulative reply bytes. These limits are -independent — a raw byte cap alone permits an excessive number of short -headers. Invalid actions cannot bypass the outbound gate. - -### RPC result materialization — accepted limit - -The tenant's entire RPC return value is materialized inside the shared proxy -before action validation. The framework's action queue constrains cooperative -handlers; an arbitrary tenant entrypoint can return any object graph, and the -32 MiB serialized [RPC limit](https://developers.cloudflare.com/workers/runtime-apis/rpc/#limitations) -does not bound the receiver's heap — a dense array near the cap materializes -several times its serialized size against -[Worker memory](https://developers.cloudflare.com/workers/platform/limits/#memory). - -This is an accepted architectural limitation. Callee CPU limits reduce some -inputs but give no hard caller-heap bound, and no return-type convention can -constrain a hostile callee. Possible future boundaries — a reserved HTTP -endpoint with a bounded body, a dedicated inbound-email dispatch Worker, or a -separate email CPU budget — change the framework contract or deployment -architecture and are separate decisions. - -## Local development and testing - -The development inbox captures outbound MIME and requires the project's -dev-trigger token on every route. It is not a production transport. Skipping -capture with `sendInDev` creates no binding and guarantees no delivery. When -Void removes its own dev send transport it preserves the user's independently -named send bindings. - -Test harnesses exercise the same message construction, routing and action -semantics as production. Inbound parsing consumes a stream; handlers choose -when to parse it. Threaded replies treat sender-supplied headers as untrusted -and fall back safely when threading metadata is malformed. - -## Custom domains on Cloudflare - -A project can send as and receive at its own domain — `support@example.com`, -`noreply@mail.example.com` — when that domain's DNS zone is on Cloudflare. -The zone stays in the customer's own account. The customer grants the platform -a scoped credential once; the platform configures the zone and runs both -directions on their behalf. Inbound crosses accounts in a **relay worker** -deployed into the customer's account; outbound crosses back as a REST send -with the same credential. The relay needs no operator mail zone, so custom -domains work identically on a self-hosted platform, and the raw MIME arrives -unmodified — no `To:` recovery, no BCC loss, no SRS/ARC hop, no destination -verification click. The price is one wider token scope, `Workers Scripts: -Write`, which the customer sees on the token form. - -"On Cloudflare" means a zone under Cloudflare DNS in an account the customer -controls. A domain that only CNAMEs to Void through Cloudflare for SaaS is out -of scope: Email Routing needs MX records on a Cloudflare zone, and RFC 2181 -forbids MX beside a CNAME. - -After the one-time grant, a developer sees an address, recipients, a counter -and an error code — never a zone, a rule or a token scope. One domain belongs -to one project; a company uses one subdomain per project. - -### Why this model - -| Model | Needs from the customer | Verdict | -| ------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| **Bring your zone — a scoped token** _(adopted)_ | one credential, one dashboard step per sub. | zone stays theirs; apex MX untouched; routing on Free, sending on Paid; the domain signs its own DKIM, reputation per customer | -| NS delegation of the whole domain | move all DNS to us | we would own every record they have | -| `mail.example.com` as a zone in our account | delegate one subdomain | Cloudflare subdomain setup is Enterprise-only | -| Self-hosted SMTP relay | nothing | reinvents Email Routing | - -### The two paths - -A routing rule can only name a worker in its own account, so inbound from a -customer zone cannot reach `void-proxy` directly. - -``` -INBOUND support+T-42@example.com - │ MX in the customer's account (mail.example.com, or the apex when its MX is empty) - ▼ - catch-all rule → void-email-relay (a worker in the customer's account, deployed by setup) - │ envelope recipient exact — To:, Cc: and BCC alike · raw MIME unmodified - ▼ - POST /email/relay Authorization: the domain's relay secret - │ secret → registered domain → project - ▼ - project worker email() to = support+T-42@example.com viaDomain = example.com - dispatcher runs in no-prefix mode - -OUTBOUND sendEmail({ from: "noreply@example.com", … }) - │ proxy: from-domain is registered to this project → lease that domain's credential - ▼ - POST /accounts/{customer}/email/sending/send_raw { from, recipients, mime_message } - DKIM = the customer's domain · daily quota = the customer's · message_id returned -``` - -**The relay worker.** One per registered domain, named `void-email-relay` -(suffixed `-2`, `-3`… on collision within the account, up to 50). Its -`email()` handler streams `message.raw` straight into a POST with the domain's -relay secret — no parsing, no buffering, so it stays inside Workers Free CPU -limits. The stream rides through a `FixedLengthStream(rawSize)` because the -runtime derives Content-Length from the body and the proxy refuses a -length-less body before any crypto. `message.to` is the single envelope -recipient, so a multi-recipient message is one invocation per recipient. - -The catch-all is zone-scoped, so mail for a second domain on the same zone can -land on the first domain's relay: the relay `setReject`s any message whose -recipient domain is not its own — a loud bounce — and the proxy's `/email/relay` -branch independently 403s when the declared `X-Void-Email-Domain` does not -equal the recipient's domain, keying its mirror lookup on the recipient's -domain. Attribution binds to the envelope recipient, never the relay's claim. - -Setup deploys the relay with the stored credential (`PUT -/accounts/{a}/workers/scripts/{name}` plus the secret PUT — one `Workers -Scripts: Edit` token covers both) and points the zone's catch-all at it: - -``` -PUT /zones/{z}/email/routing/rules/catch_all -{ "matchers": [{ "type": "all" }], - "actions": [{ "type": "worker", "value": ["void-email-relay"] }], - "enabled": true } -``` - -The rule's omitted `source` defaults to `api`; if the customer later runs -`wrangler deploy` with an `addresses` array on the same zone, Wrangler reports -our rule as an externally-managed conflict and asks before taking over. This -is stated in `status` output, not fought. The relay name is stable once -chosen — renaming a worker detaches every rule pointing at it — so `sync` -redeploys in place. The code is ours but the worker is the customer's: they -can read, edit or delete it, and `status` reports drift rather than fighting -it. A leaked secret lets a stranger push mail into one project's inbound and -nothing else; `sync` rotates it. Worker secrets are write-only, so rotation is -overwrite, never read-compare. - -**Trust.** The proxy accepts a relayed message only with the domain's relay -secret, generated by the platform at setup. The secret maps to one registered -domain of one project, so `viaDomain` cannot be forged. The auth branch applies -header and length bounds before any crypto, looks the domain's mirror up in -routing KV, compares the secret's sha256 in constant time, and refuses any -mirror whose status is not `active` — a revoked or removed domain stops -receiving at the proxy, and the relay never learns why. - -The reply-sender pin accepts a second shape: any address on a domain -registered to the receiving project. Such a reply runs through the FROM -domain's own mirror and credential lease — two domains of one project may live -in different customer accounts. - -`replyEmail` on a relayed message defaults `from` to the address that received -it and goes out over the REST path. - -### Setup — `void email domain add example.com` - -Mirrors `void domain add`: a row that goes `pending → active`, printed -instructions for the steps only a human can do, and `status` to poll. - -| Step | Who | How | -| ------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| grant | customer, one click | Cloudflare's OAuth consent on Wrangler's public client; no browser or a failed consent falls back to the template-link token | -| zone lookup, MX check | platform | `GET /zones?name=`; MX over public DNS, no token needed | -| routing on the apex | platform | `POST /zones/{z}/email/routing/dns`, only when the apex carries no MX | -| routing on a subdomain | customer, once | dashboard — no API exists; the CLI prints the exact path and `status` polls | -| Email Sending onboarding | platform | `POST /zones/{z}/email/sending/subdomains { name }` | -| relay worker | platform | script PUT + relay secret as a worker secret | -| catch-all → relay | platform | `GET` then `PUT …/rules/catch_all` naming the relay — never written over an enabled foreign rule | -| status → active | platform | every probe green; the map printed | - -When the apex already carries MX records, the CLI proposes `mail.` -(`--subdomain` overrides). The catch-all is never written blind: an enabled -rule naming anything but this row's relay fails the row at `catch_all` with a -conflict message; a rule already naming it makes the write a no-op. The -sending-onboard read-back paginates the list endpoint until a short page. - -**Steps that ride along.** Email Sending is paid-plan-only while Email Routing -is not. An entitlement refusal (CF error codes 2036/10105) does not fail -setup: the relay and catch-all still deploy and the row lands `active` with -`remaining_steps: ['sending_onboarding']`; inbound works, outbound stays -refused at Cloudflare until a plan upgrade. Only `routing_subdomain` holds a -row at `pending`. - -**Self-clearing.** The status GET is read-only. A `pending` row whose only -remaining step is `routing_subdomain` probes public DNS for MX naming -Cloudflare's inbound exchanges (`route1..3.mx.cloudflare.net`) and on evidence -flips the row to `active`, mirror following. The `sending_onboarding` step -clears on the customer-credential read-back showing the subdomain onboarded; -**`sync` re-attempts the onboarding POST outright**, so after a Workers Paid -upgrade the answer is `sync`, not `status`. Every self-clear write is fenced on -the probed status and setup state and suppressed while a removal failure is -pending. - -**Verbs.** `status` reports `catch_all` (`points_here` / `points_elsewhere` / -`missing` / `disabled` / `unknown`) and `catch_all_drift`; it re-probes the -credential and the relay on every call. `sync` redeploys the relay in place, -rotates its secret and ensures the catch-all: missing, disabled or non-worker -rules are repointed; a rule already naming this relay is left alone; an enabled -rule naming a different worker is reported and never overwritten. `remove` -deletes the platform row, the credential and the relay secret, with Cloudflare -cleanup best-effort. A credential the customer revokes at Cloudflare shows as -`token_revoked` / `token_expired` on the next probe, inbound continuing until -they delete the rule or the relay themselves. - -**Re-runnable.** Re-adding a `failed` row re-runs the engine against the row's -recorded progress and never erases what the row learned: `zone_id`, -`account_id`, `mode` and `relay_worker_name` are seeded from the row. A -recorded mode skips the MX check (the first attempt put our MX on the domain); -a recorded relay name redeploys in place rather than walking to a fresh `-2`; -an "already done" 400/409 from enable-routing or onboard-sending is believed -only when a read-back of the zone confirms it. Healthy rows take the -sync-only path. - -### Concurrency and durability invariants - -- **Two partial unique indexes backstop check-then-write**: one live row per - zone (`status IN ('active','pending')`, so a `failed` row can still record - its zone) and one relay name per account (`relay_worker_name IS NOT NULL`). - Setup claims its walked relay name on its own row before any upload, so two - setups racing one account serialize first-to-claim; an engine throw after a - successful claim restores the row's pre-engine values. A loser that still - violates an index gets a 409, classified by the constraint name read from the - error's cause chain. The loser's Cloudflare-side work is compensated - best-effort: a zone race fully removes; a relay-name race never deletes the - contested worker, only conditionally detaches its zone rule. -- **A deploy checkpoint closes the catch-all race.** The engine persists - progress once — after the relay deploy and secret PUT, before the catch-all - write. A racing loser fails there and never writes its zone rule. - Checkpoints are skipped on in-place redeploys. -- **Any checkpoint failure compensates from the captured payload**, including - the row being cascade-deleted by teardown mid-setup, which answers 409 - `project is being deleted`. -- **A re-run that hits the zone index at the final apply repoints** its owned - catch-all at the winner instead of resetting it, probing the winner before - and after the PUT; a lookup failure degrades to the plain reset. -- **A non-unique apply failure does not orphan the relay.** The row is - re-read: relay name and `relay_version` both matching means the apply - committed; otherwise the deployed state is compensated and the error - rethrown. -- **Sync, add and revoke serialize under the project row lock (refusing when - teardown marked it `deleting`) and then the domain row lock; remove takes - the domain row lock and re-reads the row's status inside it**, re-reading - the row — credential included — under the lock. A credential replace that - lands while another operation waits is acted on as the new credential, - never the superseded one. Mirror writes ride the same transaction; a KV - failure rolls the row write back. The add path commits the row insert - first, then runs the engine in a follow-up serialized section that decides - sync versus full setup on the locked row; engine writes ride savepoints so - an expected index violation keeps the transaction committable. -- **A lease-time revocation publishes its mirror under the row lock**, - conditioned on the row still holding the credential that was revoked, so it - never overwrites a replace that committed in between. - -### Removal and teardown - -- **Detach before delete.** The zone catch-all is reset (when the ownership - read shows it still naming this row's relay) before the relay script is - deleted; if the read or reset fails the delete is skipped and both steps - report failed. An enabled catch-all never points at a deleted worker. -- **A failed removal keeps the row.** A destructive step failing marks - `setup_state.failed_step = 'remove'` and `removal_failed_steps`, and answers - `200 { ok: false, removed: false, failed_steps }`. The owner retries or - forces with `?force=1`. Two exceptions delete unconditionally: - `token_revoked` rows and a `revoke_grant`-only failure. While the mark is - present the status GET suppresses mirror repair. -- **Project teardown** revokes the KV mirrors first (fail-closed), then runs - the domain removal for each registered domain with a deployed relay, - best-effort and never throwing, before the DB cascade. -- **The admin surface follows the same order.** Full removal clears the - mirror first, runs the same engine removal, then deletes the row; a - mirror-clear failure keeps the row and runs nothing destructive. The - operator escape hatch `POST /admin/email/:projectId/domains/:domain/revoke-grant` - writes the mirror as `token_revoked` first (inbound stops at the proxy), - then revokes, then flips the row; a failed revoke answers 502 with the row - still active and the next status GET repairs the mirror. - -### Data and the credential - -`email_domains`: `project_id`, `domain` (globally unique), `zone_id`, -`account_id`, `mode: 'apex' | 'subdomain'`, `status: 'pending' | 'active' | -'token_revoked' | 'token_expired' | 'failed'`, `credential_kind`, -`relay_worker_name`, `relay_version`, the credential and relay-secret -ciphertext triples, `setup_state` (jsonb: `failed_step`, `remaining_steps`, -`removal_failed_steps`), `attempt_id` (the add attempt that last wrote the -credential), `token_id` and `token_expires_on` from `GET /user/tokens/verify`. -The two partial unique indexes above ride the same table. - -The credential is encrypted with `encryptProjectSecret` under the project's -envelope key, per domain; only the api and proxy decrypt it, and it is never -written to a manifest, a log or the relay. The relay carries only its own -domain's secret. AADs are `${projectId}:email-domain-token:` and -`${projectId}:email-domain-relay:`. - -The proxy never reads the row. The api mirrors what it needs to routing KV as -`email-domain:` — `{ projectId, status, relaySecretSha256, -relayWorkerName, accountId, zoneId, mode }` — rewritten on every status -transition and rotation, tightened before any revoke, deleted on removal, and -repaired by the status GET under the row lock when it drifts. - -Minimum scopes: zone-scoped `Zone Read`, `Email Routing Rules Edit` and `Zone -Settings Edit`; account-scoped `Workers Scripts: Write` and `Email Sending -Edit`. `Workers Scripts: Write` is account-wide — per-script scoping does not -exist — and the token summary page shows that before **Create Token**. - -### The OAuth grant on Wrangler's client - -The primary credential path is Cloudflare's OAuth consent on **Wrangler's -public OAuth client** (PKCE, no secret; endpoints -`dash.cloudflare.com/oauth2/{auth,token,revoke}`; redirect -`localhost:8976/oauth/callback`). The customer clicks **Allow** and the -platform stores the refresh token. What this costs: - -- **Breadth.** A grant is user-wide — every account the user belongs to, every - zone in them, for the granted scopes. The template-link token remains the - narrow option for a company with many zones. -- **Refresh.** Access tokens live about an hour; refresh tokens are single-use - and rotate. The platform runs its own grant chain — it never touches the - developer's `~/.wrangler` chain, which would race Wrangler's refreshes. - Refresh is serialized per domain row and the rotated token is persisted - atomically with it (the credential lease). A revoked grant surfaces as - `token_revoked`. -- **Scopes.** `zone:read`, `email_routing:write`, `email_sending:write`, - `workers_scripts:write`, `offline_access`. There is no `zone_settings` OAuth - scope; the email zone-settings endpoints are reached under - `email_routing:write`. -- **The consent screen names Wrangler.** The CLI prints one line before - opening the browser so the customer is not surprised. -- **The client id is not ours.** Cloudflare can rotate or revoke it, so the - template link + paste is the permanent fallback, not a legacy path. - -**Revocation** POSTs the RFC 7009 form to `dash.cloudflare.com/oauth2/revoke` -(`token_type_hint=refresh_token`, no Authorization header — a public client -authenticates with the token itself). It throws on a network failure or -non-2xx, because Cloudflare answers 200 even for a bogus token, and never logs -the token. Rules: - -- Removal revokes last, with the rotated chain head; teardown and admin - removal revoke. Conflict compensation does not — the loser's credential may - survive on another row. -- Credential replace revokes the old grant after the commit; a re-pasted - identical grant is kept, since revoking it would brick the just-stored row. -- A rejected add revokes the posted grant first — validation 400, - cross-project 409, teardown 409, and the project guards' 404/403 — because - the CLI mints a fresh grant per attempt and drops its only copy on any - error. The one guard: a grant equal to the conflicting row's stored - credential is kept. -- A lost answer is not a rejection. Every add attempt carries a random - `attempt_id`, stamped on the row at insert and at credential replace and - serialized on the status GET. When the POST's answer never arrives, or is - ambiguous (a 5xx, or a 401/403/413/426/429 from middleware or the edge — - only the route's deliberate 400/404/409 prove a server-side revoke), the CLI - polls the status, 15 tries a second apart. The row carrying this attempt's - id means the add committed; a different id means this grant was never - stored and is revoked; a 404 at every poll means nothing persisted and the - held grant is revoked; no informative read at all is reported as unknown — - a blind revoke could brick a row that did commit. The CLI claims a - revocation only on Cloudflare's 200. -- A consent exchange that completes after the flow settled minted a grant only - the CLI holds; it is revoked fire-and-forget and the browser tab gets a - cancelled page. - -**Rejected credential paths**, so nobody designs them again: minting a scoped -API token from the session (`POST /user/tokens`) needs `API Tokens Write`, -which is not an OAuth scope at all; and the session bearer is no substitute — -it expires in an hour and its refresh chain belongs to Wrangler. Borrowing the -**access** token via `wrangler auth token` is safe; refreshing it outside -Wrangler races the single-use rotation. - -### The token fallback — three clicks - -For a browserless terminal, a failed consent, or a company that wants a -zone-narrowed token. Cloudflare's dashboard accepts a template URL that -pre-fills the token form; the CLI opens it, the customer clicks **Continue to -summary**, **Create Token**, **Copy**, and the CLI takes the token from the -clipboard. - -``` -CLI browser CLI - │ MX check → apex or subdomain │ │ - │ build the link · snapshot clipboard │ │ - │ open ─────────────────────────────▶ │ form is pre-filled │ - │ watch the clipboard (≤ 10 min) │ 1 Continue to summary │ - │ │ 2 Create Token │ - │ ◀──────────────────────── clipboard │ 3 Copy │ - │ shape ok → GET /user/tokens/verify → clear the clipboard │ - │ GET /zones?name=… · scope check │ - │ send over TLS → platform stores with encryptProjectSecret │ - │ drop it from memory · continue with Zone / Routing … │ -``` - -The clipboard watch reads only between opening the link and getting a token, -ignores the pre-link snapshot, and accepts only a new value shaped like a -Cloudflare token (`cfut_` prefix + 40 characters + checksum, or a legacy -40-character `[A-Za-z0-9_-]` value); other vendor prefixes (`ghp_`, -`github_pat_`, `sk-`, `xox`, `cfk_`) are refused without a network call. Only -a shape-valid value reaches `GET /user/tokens/verify`, and only `status: -active` is accepted. The clipboard is cleared once the token is taken. Enter -at any time switches to the masked paste prompt; no clipboard tool (SSH, CI, a -Wayland session without `wl-paste`) falls back to it silently. Nothing on the -clipboard is printed or logged. - -The link: - -``` -https://dash.cloudflare.com/profile/api-tokens - ?permissionGroupKeys= - &accountId=* # required by the form; narrowed in the summary - &zoneId=all # required by the form; narrowed in the summary - &name=Void%20email%20%E2%80%94%20example.com +## Zone ownership and project routing + +### One zone ingress + +A zone owns its catch-all rule and ingress Worker. A project owns an exact mail +domain. Several project domains may reference the same zone ingress. The +installation's shared mail domain is a reserved route in that same map. + +```mermaid +flowchart TD + A["Incoming email: example.com zone"] --> B["Zone catch-all"] + B --> C["One zone ingress Worker"] + C --> D["Email gateway: authenticate ingress and envelope"] + D --> E{"Exact recipient domain"} + E -->|"mail.example.com"| F["Resolve project slug; strip prefix once"] + E -->|"hr.example.com"| G["HR project; keep local part"] + E -->|"support.example.com"| H["Support project; keep local part"] + E -->|"Unregistered or disabled"| I["Reject; never guess a project"] + F --> J["Bounded dispatch to selected tenant"] + G --> J + H --> J ``` -```json -[ - { "key": "zone", "type": "read" }, - { "key": "email_routing_rule", "type": "edit" }, - { "key": "email_sending", "type": "edit" }, - { "key": "workers_scripts", "type": "edit" }, - { "key": "zone_settings", "type": "edit" } -] +For example, `hr+alerts@mail.example.com` uses shared addressing, while +`alerts@hr.example.com` uses the HR project's custom domain. Registering +`support.example.com` changes the route map, not the catch-all target. Keep one +project per custom domain; a project may own several domains. The constraint +being removed is one live mail domain per zone, not domain-to-project exclusivity. + +The ingress streams the original MIME and exact SMTP envelope recipient over +HTTPS to the gateway. Routing never uses the MIME `To` or `Cc` fields, which do +not identify BCC recipients. Shared addressing strips the slug prefix exactly +once; custom-domain addressing preserves the local part. Existing route +precedence, case-insensitive matching and case-preserving captures remain. + +Unknown domains are rejected. Existing explicit Cloudflare rules may take +precedence over the catch-all: setup must enumerate them and report conflicting +addresses before claiming that an entire domain is routed to Void. An unrelated +enabled catch-all is a setup conflict. No automatic takeover or fallback to the +first registered project is permitted. + +### Trust and management scope + +An ingress credential authenticates one `(installation, account, zone, ingress)` +identity, not a caller-supplied project ID. The gateway verifies that the exact +recipient domain is active on that ingress and resolves its project from the +authoritative route map. A secret for one zone cannot inject into another zone. +The relay knows no provider credential. Its secret can inject inbound traffic +for registered domains in its zone; the zone administrator already controls mail +routing for those domains. This wider scope must be explicit in the design. + +Separate `managed_by` on a **zone connection** from `managed_by` on a **domain +assignment**. Creating the connection requires authority over the Cloudflare +zone. A project owner who can remove their assignment cannot redeploy the shared +Worker, rotate its credential, detach the catch-all or affect sibling domains. +Adding another assignment to an existing connection requires its manager's +approval or an existing authorization from that manager; matching a domain +suffix is not proof of authority. Multiple independent owners on one zone must +use the same administrator-approved connection. + +Administrator-managed connections use the operator credential only when the +zone account equals `CF_ACCOUNT_ID`. Owner-managed connections retain a scoped +credential in the platform's secret store. Shared resources must not be encrypted +under a project key that disappears when the first project is deleted; use a +connection-scoped envelope key and associated data. Moving an existing credential +requires an explicit, audited operation, never a silent ownership transfer. + +### Data model + +| Record | Identity and responsibility | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `email_zone_connections` | Unique account + zone within an installation; manager, credential reference, stable ingress name, deployment version and secret generations | +| `email_domain_routes` | Globally unique normalized exact domain; connection, custom project or shared-addressing mode, desired state and observed capabilities | +| `email_credentials` | Manager, resource scope, encrypted token or platform reference, credential generation and health; no secret in route caches | +| `email_operations` | Idempotency key, actor, resource, desired generation, durable step states and sanitized failure details | +| `email_actions` | Project, receipt or send ID, action ID, payload digest, recipient outcomes, quota debit and provider references | +| `email_quota_buckets` | Project and time window; atomic recipient-attempt usage | +| `email_cache_outbox` | Committed route/settings versions awaiting KV publication | + +Replace the existing one-live-domain-per-zone index only after all readers and +writers understand the connection relationship. Keep exact-domain uniqueness +and unique ingress name per account. Reserve shared mail domains so they cannot +also become custom project domains. A domain transfer first disables the old +assignment and drains its admitted work; a stale routing hint never authorizes +a delivery to the new or old project. + +## Recoverable provisioning + +### Setup control flow + +The owner CLI and administrator CLI call the same operation service. Authorization +differs; lifecycle and recovery do not. The existing owner/admin restrictions and +installation-wide `self-serve` / `admin` mode remain enforced server-side. + +```mermaid +flowchart TD + A["Add or sync domain"] --> B["Authorize manager; inspect DNS and existing routes"] + B --> C["Commit operation ID, desired state and resource claims"] + C --> D["Reconciler selects next unfinished step"] + D --> E["Commit step intent and exact request generation"] + E --> F["Call Cloudflare outside the database transaction"] + F --> G{"Result known?"} + G -->|"Yes"| H["Commit observed result and next checkpoint"] + G -->|"No"| I["Probe provider state"] + I -->|"Matches intent"| H + I -->|"Safe repeat established"| D + I -->|"Still ambiguous"| J["Needs attention; no competing mutation"] + H --> K{"More steps?"} + K -->|"Yes"| D + K -->|"No"| L["Publish readiness; retry cache publication independently"] ``` -Every key rides every link — `Zone Settings Edit` gates the routing POST on -both paths. The two email keys are community-verified rather than documented, -and unknown keys are silently dropped, so the docs also show the manual -token-creation steps. - -The dashboard never hands the token back — no redirect, no callback; the paste -is the transport. On the platform the token lives encrypted per project; on -the developer's machine, nowhere. A TTL the customer set on the form is the -one thing the platform copy cannot solve: sends stop, `status` reads `token -expired`, and `void email domain add` again is the renewal. - -### What changes in the shared-sender rules - -- **Reply-sender pin** — accepts the receiving slug on the shared domain _or_ - any address on a domain registered to the project. -- **Recipient allowlist** — does not gate custom-domain sends, relayed - forward/reply included: the customer's own onboarding lifts Cloudflare's - verified-destination gate, and the reputation at stake is theirs. The burst - cap, the monthly cap and the kill switch still apply. -- **The 200-destination cap is untouched** — a relay consumes no destination - address in either account. -- **One worker of ours lives in their account** — readable, editable and - deletable by the customer; `status` reports drift, it does not fight it. - -### Limits - -- The customer's account must be on **Workers Paid** to send; routing alone - works on Free. -- Two steps stay human: the credential grant and the routing-subdomain - dashboard form. -- The credential asks for account-wide `Workers Scripts: Write`. -- Inbound messages cap at 25 MiB (Cloudflare rejects larger ones before the - relay runs); a zone holds at most 30 email domains; a domain holds at most - 200 routing rules; the relay name walk caps at 50 names per account. -- A domain that is not on Cloudflare DNS is not covered. - -### Provider behavior the design relies on - -Established against a live zone with a user API token: - -- `POST …/email/routing/dns { name }` enables a subdomain and auto-creates - three MX records; the apex enable is an empty-body POST. `routing/dns` is - authorized by Zone Settings Write, rules by Email Routing Rules Write. -- Sending onboarding succeeds with a user API token although the schema - declares Global-key-only, and also stamps the apex SPF and DKIM. `10103 -bad_token_type` is Email Sending's credential-type rejection. -- One zone-scoped catch-all, auto-created disabled on first enable, covers the - apex and every subdomain; there is no per-email-domain rule. -- Relay script PUT, secret PUT and catch-all PUT all accept an API token. -- `send_raw` takes the JSON envelope `{ from, recipients, mime_message }` (a - raw `message/rfc822` body earns `10001 invalid_request_schema`) and returns - `200 queued` with a `message_id`. It accepts user and account tokens. -- The revocation endpoint answers 200 even for a bogus token. -- Cloudflare's cleanup does not remove `_dmarc.` on subdomain or routing - deletion; the engine never touches DNS, and the CLI prints the manual - cleanup list. - -Still open: the browser consent run (what the screen says, whether a -non-localhost redirect is accepted, rotation over several cycles, whether the -grant's `email_routing:write` covers the two calls Wrangler never makes), a -message-level inbound end-to-end check, the narrow template-token variants, -and every operation above with an **account-owned** token. - -### Where each piece lives - -- **Cloudflare calls from the api** follow `cfFetch` - (`platform/packages/api/src/provisioning/cloudflare-api.ts`); the relay - deploy is a multipart script PUT plus a non-namespace `putWorkerSecret`. -- **The relay source is an embedded asset in the api worker** — one constant - module plus `relay_version`; `sync` redeploys it. -- **`/email/relay` in the proxy** is a branch in the global auth middleware: - size bounds before any crypto, secret → mirror → project, then the second - half of `routeInbound` keyed by the domain's project. The relayed header - summary is bounded on two axes — distinct names and total header pieces. -- **Schema:** `email_domains`, with CHECK constraints declared in the schema - so drizzle-kit does not diff them away. -- **CLI:** `void email domain …` under the email group; `PlatformClient`'s - `/projects/:id/email/…` methods; owner-guard routes in `routes/email.ts`; - the admin section in `admin/routes/email.tsx`. - -## Administrator-managed domains - -### The scenario - -One Cloudflare administrator installs a Void platform inside a company. Staff -who do not write code deploy small applications to it through a coding agent. -They have no Cloudflare account, token or dashboard access; the administrator -has all three and owns the company zones. - -`void email domain add` cannot work for these users — its first step is a -consent or a paste. And most of what their applications want is "mail my -colleagues", which the shared sender already provides an address for; the -blocker there is the verified-destination gate, not the lack of a domain. - +Persist an operation before any provider mutation. Return its ID even while work +is pending; replaying the same idempotency key and request returns that operation. +Reusing a key with different intent is a conflict. The CLI resumes by ID after a +lost response rather than inferring success or revoking a credential from a short +series of missing reads. + +A scheduled reconciler resumes committed work; queue notifications may reduce +latency but are not the only way to discover unfinished operations. Each provider +step has an intent, request digest, resource identity, attempt number and outcome +(`pending`, `in_flight`, `confirmed`, `blocked`, `unknown`). `blocked` includes a +specific human action, such as granting a permission or enabling Sending. + +Use short database transactions to claim work and commit results. Do not hold a +project or domain row lock across provider calls. Serialize mutations of a zone +connection, including removal, and fence database updates by operation generation. +Cloudflare does not honor that fence: an expired execution lease alone is not +permission to start a conflicting provider write. After a timeout, establish the +outcome or stop for operator recovery. Repeat only an operation demonstrated to +be idempotent with the same stored payload. A late response cannot overwrite a +newer database generation. + +Setup proceeds through: + +1. Resolve the exact account and zone, check grant scope, inspect existing MX and + routing rules, and reserve the connection/domain assignment. +2. Enable only the requested routing domain. Preserve existing apex MX; select a + mail subdomain when necessary. Attempt the supported API, or report a precise + dashboard action if that credential/provider combination cannot complete it. +3. Deploy or reuse the zone ingress, provision its authenticated connection, and + confirm that the gateway accepts that identity before changing traffic. +4. Reconcile the owned catch-all. Report conflicting explicit rules and foreign + catch-all ownership; do not overwrite them. +5. Confirm inbound readiness. Onboard Sending separately when requested and + permitted; its failure does not erase functioning inbound routing. +6. Commit observed capabilities and an outbox entry. Cache failures leave the + operation committed and publication pending; they never undo provider progress. + +The first release may still need manual provider steps. It must show exactly what +is ready and what remains; successful Worker upload is not proof of mail flow. + +### Credentials and refresh + +For new owner connections, default to an API token limited to the selected zone +and account. Show the actual resource scope and required permissions before +accepting it. A template whose defaults cover all accounts/zones is not sufficient +proof of narrow scope. Verify operations with the selected token and retain manual +creation instructions when the dashboard template cannot express the scope. +`Workers Scripts: Write` remains account-wide; disclose that residual breadth. +Never describe the token as confined to one Worker. + +Do not use Wrangler's public OAuth client for the production credential flow. +A future Void-owned or explicitly supported OAuth integration requires a validated +consent screen, resource scope, refresh lifecycle and revocation flow. Experimental +grants in development environments can be explicitly replaced with scoped tokens; +there is no production OAuth compatibility requirement. + +Any rotating OAuth credentials retained for testing or supported in the future +must follow these rules: + +- Serialize by credential/grant identity, not by the domain using it. Commit + `refresh_started` before sending the refresh request. +- Commit the returned refresh token and incremented generation in a standalone + credential transaction before releasing the access token to any caller. + Provisioning and KV publication cannot roll that transaction back. +- A process crash or lost response can still consume the old token without + preserving its replacement. Record `refresh_unknown`, stop automatic refresh, + and request reauthorization unless the provider offers a documented recovery + mechanism. A database transaction cannot make token rotation atomic at Cloudflare. +- Replacement and revocation use the same serializer. Revoke a superseded grant + only after the new credential is committed and no connection still references it. + +The credential broker decrypts credentials and gives bounded leases only to the +trusted provider adapter, never tenants or ingress Workers. Check credential +revocation and domain authorization at each admission, even if the adapter still +holds a previously issued lease. Requests already submitted to Cloudflare cannot +be recalled. Operational credential failure pauses sending/management; it does +not automatically revoke independently authenticated inbound routing. An explicit +security revocation can disable both capabilities and the ingress identity. + +### Relay secret rotation + +Secret rotation is its own durable operation, not a side effect of every `status` +or `sync`. Store the new generation encrypted and register its accepted hash in +the authoritative gateway state before deploying it to the ingress. Keep the +previous generation accepted while the provider write is unconfirmed. + +A successful controlled ingress probe confirms the deployed generation. Then +commit the new active generation and a bounded overlap deadline for old in-flight +requests. Retire the old generation after that deadline. If deployment fails, +keep the old active generation and report the pending rotation. Reuse the same +staged secret on retry. A compromise-triggered rotation revokes the old generation +immediately and reports the possible interruption instead of promising continuity. +Neither route-cache lag nor a failed KV write can roll back the active secret. + +### Readiness and removal + +Expose three independent states with reasons and observation times: + +| Capability | Example states | +| --------------------- | ------------------------------------------------------------------ | +| Inbound | `pending`, `ready`, `disabled`, `drifted` | +| Outbound | `pending`, `verified_only`, `ready`, `blocked` | +| Management credential | `healthy`, `expired`, `revoked`, `refresh_unknown`, `probe_failed` | + +`status` performs provider reads and may save observed state or repair a cache; it +never changes provider configuration. `sync` requests reconciliation. Distinguish +these operations instead of describing a database-updating status read as pure. + +Removal first commits the domain's disabled state, preventing new admission, then +drains already admitted actions. Remove its assignment without modifying a sibling +project's route. Retain tombstones and operation records until cleanup is resolved. +Only the connection manager may remove the last connection: detach its catch-all +if it is still owned, then delete the ingress, then revoke an unreferenced grant. +Do not delete the Worker while an owned rule still targets it. Provider cleanup +failure leaves a retryable cleanup operation, including after project teardown. +Force removal acknowledges orphaned resources; it cannot silently erase that record. + +## Bounded tenant execution + +Cloudflare's native email message is not an RPC-serializable application object. +The existing bridge already uses an envelope and action intents. Keep that model, +but transport it through a reserved, authenticated `fetch` endpoint and a streamed, +versioned response instead of an arbitrary RPC object graph. Cloudflare's +[RPC serialized size limit](https://developers.cloudflare.com/workers/runtime-apis/rpc/#limitations) +is not a bound on the receiver's materialized heap. + +The gateway calls the resolved tenant through its trusted dispatch binding. The +reserved endpoint is available only through that path, with a short-lived signed +receipt capability bound to the project, deployment, recipient and protocol +version. Public HTTP must not expose it. The capability never authorizes sending +on its own; every action still passes admission. + +Use length-prefixed frames: bounded flat metadata plus separately bounded raw MIME +for replies. Validate length, type, nesting, field count and cumulative bytes while +reading. Do not call `response.json()` or deserialize a tenant-controlled graph. +Reject compressed bodies, cancel oversized or stalled streams, and impose a total +deadline and per-project concurrency bound. Validate the complete action batch +before executing any action; a truncated tail must not leave a partly validated +batch already sent. A reject intent is mutually exclusive with delivery intents. + +Initial protocol budgets are 10 MiB inbound MIME, 1,024 distinct inbound +headers with 128 KiB aggregate header bytes, 100 actions, 8 KiB metadata per action, +8 MiB cumulative action-response bytes, and 5 MiB per outbound MIME message. Limit +each send to 50 unique recipients and custom headers to 16 KB. Count encoded MIME +bytes, including attachment expansion; transport adapters may impose tighter +limits. Large inbound messages can be received even when too large to forward via +a particular sending transport. These are explicit platform limits, not claims +that every provider operation accepts the same payload. + +The 5 MiB / 50-recipient sending ceiling follows +[Cloudflare's current limits](https://developers.cloudflare.com/email-service/platform/limits/), +which separately allow larger inbound and verified-only messages. The +common sending ceiling deliberately leaves those larger cases unsupported until +transport-specific validation is exposed. Align the SDK, native transport adapters, +platform validation and documentation on these limits before production release. + +A dedicated email gateway deployment keeps parsing and tenant dispatch out of the +HTTP-serving proxy's execution path. Bounded parsing, concurrency admission and +load tests are still necessary; a separate Worker alone is not a memory guarantee. +Native deployments continue to use the actual email event without this bridge. + +## Authoritative admission and sending + +### Outbound control flow + +Direct sends and validated inbound forward/reply intents share the same admission +service. The tenant authenticates as a project; it never chooses its authority by +putting a different project ID or sender domain into the request. + +```mermaid +flowchart TD + A["sendEmail or validated handler action"] --> B["Authenticate project; validate sender, MIME and recipients"] + B --> C["Admission transaction"] + C --> D{"Policy, consent, suspension, capability and quota allow?"} + D -->|"No"| E["Record rejection; return actionable error"] + D -->|"Yes"| F["Commit action ID and quota reservation"] + F --> G["Commit attempt_started; call provider"] + G --> H{"Provider outcome"} + H -->|"Accepted"| I["Persist provider_accepted and provider reference"] + H -->|"Definitively refused"| J["Persist failed with reason"] + H -->|"Timeout or crash"| K["Persist outcome_unknown; no blind retry"] + I --> L["Return result; expose through project email logs"] + J --> L + K --> L ``` - operator's Cloudflare account · zone example.com - - Lane 1 shared sender Mode C + the recipient policy above - operator once: EMAIL_SENDER_DOMAIN=mail.example.com, routing on, proxy binding - every project: +tag@mail.example.com, in and out, no per-project work - - Lane 2 per-project domain the administrator runs the engine - admin per project: void platform email domain-add hr.example.com --project hr-portal - gives: hr@hr.example.com-style addresses, the zone's own DKIM - costs: one dashboard form per subdomain, 1 domain → 1 project -``` - -Lane 2 reuses the custom-domain engine unchanged and adds an operator entry -point. - -### Decisions - -| # | Decision | Reason | -| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | One domain → one project stays; a company uses one subdomain per project. | Address→project routing would change the relay lane, the mirror key and the trust model. | -| 2 | Administrators manage domains through `void platform email domain-…` and the admin UI, running the same `setupEmailDomain` / `syncEmailDomain` / `removeEmailDomain` engine. | One engine, two entry points. Owner-guard routes keep their behavior; operator routes act on any project. | -| 3 | Credential kind **`platform`**: the row holds no credential and the engine uses the runtime token (`CF_API_TOKEN`). A pasted token stays available as the fallback. | No per-domain token, nothing expires. Valid only when the zone is in the platform's own account (`CF_ACCOUNT_ID`); the zone lookup already returns the account. | -| 4 | The relay worker is kept even when the zone is in the platform's account. | Engine, probes, mirror and tests assume one; pointing the catch-all at the proxy directly is a second code path to save one hop. | -| 5 | Installation setting `email.domains`: `self-serve` (default) or `admin`. In `admin` mode the user CLI prints the administrator's command instead of starting a grant. | The CLI must know before it opens a browser. The printed command is the whole request flow. | -| 6 | A request inbox in the admin UI is not built. | A table, a page and a notification for what one printed line does. | -| 7 | Rows carry `managed_by: 'owner' \| 'admin'`. Owners can list and read an admin row; `sync`, `remove` and a re-`add` on it are refused with the administrator's command named. | An admin row runs on the platform's credential; a user must not tear it down, rotate it, or swap in their own grant. | -| 8 | No OAuth on the operator path. | A grant is user-wide across the administrator's accounts, and the operator CLI is `--plan` / `--yes` first. | -| 9 | Operator verbs are single tokens (`domain-add`, `policy-set`, …), and the administrator names the exact mail domain — no `--subdomain`. | The operator table is ` `; nested verbs would need parser and help-tree nesting for no functional gain. The engine's MX rule still applies. | -| 10 | The user CLI reads the mode from the authenticated `GET /projects/:id/email/settings`, not the discovery document. | Discovery is env-only and unauthenticated; the setting lives in the database. A platform predating the route answers 404, which reads as `self-serve`. | - -### Command surface - -Entries in `operatorCommands` (`packages/void/src/cli/operator-args.ts`), -served under `/operator/v1/email/…`, with the group's `--plan`, `--yes` and -`--json`, recorded in `operator_events`: - -``` -void platform email domains [--project ] -void platform email domain-add --project [--token-stdin] -void platform email domain-status -void platform email domain-sync -void platform email domain-remove [--force] -void platform email settings | settings-set --domains self-serve|admin -void platform email policy | policy-set [--domains a,b] -void platform email limit [--monthly N] [--burst N] -``` - -`domain-add` without `--token-stdin` uses the `platform` credential; with it -the token is read from standard input once and rides both the preview (which -only classifies it) and the apply, never the audit target. Every POST previews -first: the add preview resolves the project, the existing row and the public -MX decision without a single Cloudflare call, and on a re-run names the -stored mode rather than re-deciding it. A kept row after a failed -destructive step (the owner contract's `200 { ok: false }`) and a setup or -sync that ends with the row `failed` / `token_revoked` / `token_expired` -both surface as a top-level `ok: false` on the operator result, so the audit -records a failed mutation and the CLI exits nonzero with the row as the -partial result. The policy preview and the admin label state the -platform-domain exception next to `any` and `domains`. The admin UI's project page has -the add form (blank token = platform credential) and shows `managed_by`; its -`revoke` and `revoke-grant` actions stay. - -The owner verbs keep their paths and guard. Both surfaces call one service -module, `email/domain-service.ts`, that owns the serialized sections above -(row insert under the project lock, engine run under the row lock, -checkpoint, compensation); the orchestration moved out of `routes/email.ts` -unchanged, and the operator layer re-shapes its JSON responses. - -### The `platform` credential - -``` - kind stored on the row engine / lease resolve to revoke on remove - ─────────── ──────────────────────────── ──────────────────────────── ──────────────── - oauth_grant refresh token, encrypted refreshed access token RFC 7009 POST - api_token token, encrypted the token nothing - platform nothing env.CF_API_TOKEN nothing -``` - -- Schema: `credential_kind` includes `'platform'`; the `token_*` columns are - nullable with a CHECK that all three are null when the kind is `platform` - and all three present otherwise — the NOT NULL guarantee every other kind - had before, kept; `managed_by` defaults to `owner`. -- `decryptEmailDomainToken` is the one seam: a `platform` row resolves to - `CF_API_TOKEN` there, so the engine, the lease route (which hands it to the - proxy as an `api_token` lease), teardown and the admin surface all follow. - It is never written to the row, a mirror, a manifest or a log. -- The engine skips the user-token verify for a `platform` row (the runtime - token is not a user token) and refuses at `zone_lookup`, before any write, - when the zone's account is not `CF_ACCOUNT_ID`, naming `--token-stdin` for - a zone in another account. On the managed platform this is always the case, - so the platform's own token never touches a customer zone. The same pin - guards every later path: a pasted-token row whose recorded account is - foreign cannot be re-added or synced on the platform credential (409, the - stored token untouched), checked on the locked row. -- Ownership is authorized on the LOCKED row for add, sync and remove alike — - an owner's request and an administrator's add can interleave, and the - unlocked read only chooses the message. An administrator never takes over - an owner's row (409, "ask them to remove it first"); an owner never rotates - or removes an administrator's (403, the operator command named). The - `admin` mode's refusal of a NEW owner domain is read inside the insert's - locked section too, so an owner row removed between the owner's read and - their insert cannot slip a new row past the mode. -- A row of the `platform` kind is readable only by a runtime that knows the - kind: an api or proxy still serving from before the upgrade would fail its - lease, and that api authorizes the owner routes on project ownership alone - — it does not read `managed_by`. Register administrator domains after an - upgrade has finished, and remove them before rolling the api back below - this version; the migration itself is compatible with the previous - Workers. -- The status probe for a `platform` row is a zone-scoped read - (`GET /zones/{z}/email/routing`, or — before a zone is known — the same - suffix walk setup uses, so `mail.acme.com` finds the `acme.com` zone). - A refusal reads `probe_failed`, never `token_revoked` / `token_expired` — - those describe a stored credential's lifecycle. The probe's fenced update - compares `token_ciphertext IS NULL` for such rows; `= NULL` would never - match. -- The runtime token needs, beyond the self-hosting guide's table: **Zone - Read**, **Email Routing Rules Edit** and **Zone Settings Edit** on the mail - zones; **Email Sending Edit** on the account. The installer's token link - preselects them when the runtime enables email; a missing one fails `add` - at the first Cloudflare step with Cloudflare's own message. - -### Relay, limits and the human steps - -The relay is deployed into the platform's own account, so its name walk caps -admin-managed domains at 50 per platform account, and Cloudflare caps Email -Routing subdomains per zone. The two human steps are unchanged, now done by -the administrator: the Email Routing **Subdomains** form (the status poll -self-clears the row) and the Workers Paid upgrade for Email Sending, after -which `domain-sync` re-attempts the onboarding. - -### Ownership - -| Actor | On an `owner` row | On an `admin` row | -| ---------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| project owner | list · status · sync · remove · add | list · status; `sync` / `remove` / re-`add` → 403 naming the admin command; `add` only in `self-serve` mode | -| administrator | list · status · sync · remove · revoke | list · status · sync · remove · revoke · add | -| project teardown | removes relay + catch-all with the row's credential | same, with the runtime token | - -An administrator never takes over an owner's row: `domain-add` on one answers -409 and asks for the owner to remove it first; `domain-sync` and -`domain-remove` on it run with the owner's stored credential. The `admin` -mode refuses an owner's add of a NEW domain only — a row the owner registered -before the switch stays theirs to renew, sync and remove, on the credential it -already stores. The CLI reads the settings on the authenticated -`GET /projects/:id/email/settings`; a platform predating that route answers a -bare 404 and reads as `self-serve`, while the route's own -`project not found` is an error, so a stale project link never opens a -browser. - -### The mode switch - -`email.domains` lives in `platform_settings` and is served to the CLI on the -authenticated `GET /projects/:id/email/settings` (with the project slug for -the printed command), so `void email domain add` reads it before any DNS, -browser or Cloudflare work. In `admin` mode the CLI then lists the project's -rows once: a row the owner registered before the switch for the domain this -run targets (or its `mail.` fallback) keeps the owner flow — that is the -renewal path, and the matched row IS the target, skipping the MX decision -that would otherwise retarget an apex Email Routing has since put MX on. -Any other input goes through the owner flow's own MX decision over public -DNS first, so the printed command names the target setup will accept -(`mail.example.com` when the apex already receives mail), then prints: - -``` -$ void email domain add example.com - MX example.com carries MX for aspmx.l.google.com → apex is off limits - using mail.example.com [change with --subdomain] - Email domains on this platform are managed by its administrator. - Ask them to run: - - void platform email domain-add mail.example.com --project hr-portal - `void email domain list` and `void email domain status` keep working here. +### Policy and atomic quotas + +PostgreSQL is the authority for project identity, exact-domain ownership, verified +destination consent, installation policy, suspension and quota reservations. KV +may suggest a route or accelerate display, but cannot independently authorize +email. On a stale hint, re-resolve authoritatively; on authority unavailability, +fail closed with a service-unavailable outcome rather than sending. + +Each admission transaction locks the relevant policy/ownership state against +concurrent updates and serializes the project's quota row in one documented lock +order. Read the current policy version, check capabilities, insert the deduplicated +action and debit quota atomically. After an administrator's change commits, a new +admission uses it. Already admitted attempts may finish; the UI must state this +boundary. A suspension blocks new attempts, including automatic retries, without +claiming to recall mail already submitted to the provider. + +Preserve `verified` as the default shared-sender recipient policy; `domains` adds +exact approved domains and `any` permits external recipients. On the platform's +own shared mail domains, every mode still requires the existing per-project +verified-destination consent. Ownership inheritance is checked against the current +owner; account-level Cloudflare verification alone does not create project +consent. Custom-domain external sends retain their allowlist exemption, subject +to provider capability, suspension and quotas. The shared-mail-domain exception +also applies when the sender is custom, closing a cross-project loop path. + +Provider-native forwarding may still require verified destinations regardless of +the platform's policy mode. A REST resend is not automatically equivalent to +native forwarding's authentication and header handling. Each adapter must declare +its supported action semantics; if it cannot preserve them, return a visible +unsupported-action error rather than silently changing delivery behavior. Live +forward/reply acceptance is a rollout gate. + +Count **recipient submission attempts**, matching the conservative current intent. +Keep the default counts of 200 per UTC calendar month and 10 per minute, with +administrator overrides. Make the burst window a rolling 60 seconds, a deliberate +tightening of today's fixed minute buckets. Compute it from timestamped reservations +under the project quota lock, so adjacent minute boundaries cannot double the burst. +Deduplicate recipients before charging. A provider +call with several recipients reserves that many units; partial local admission +returns an outcome for each recipient and sends only admitted recipients. + +Persist an action ID before any provider side effect. Reusing the same project, +idempotency key and payload digest returns the existing result without another +charge or send; a different payload is a conflict. Handler action keys use the +persisted receipt ID plus action index and recipient identity. Public direct sends +need an optional caller idempotency key and a stable Void operation ID; finalize these fields +and their result semantics before release. Without a caller key, two +separate calls are two send requests. + +An unstarted reservation can be cancelled atomically and released. Once +`attempt_started` commits, its charge is retained on provider refusal, success or +uncertainty; this is an abuse cap, not a billing counter. An executor crash after +that commit but before the actual call is conservatively unknown. A retry that is +known safe is a new provider attempt with a fresh quota check and debit. Concurrent +retries cannot consume one reservation twice. Account-level Cloudflare limits +remain additional constraints, including when several projects share an account. + +### Cache publication + +Commit settings and versioned outbox work in the same transaction. A serialized +publisher and scheduled repair publish the latest committed value. Missed or +out-of-order cache updates may affect display freshness but not authorization. +Do not claim a global 60-second security boundary: Cloudflare documents visibility +delays of [60 seconds or more](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency). +Legacy senders relying on cached authorization must be drained before the new +policy guarantee is enabled. + +## Observable delivery and retry semantics + +### Receipt is not delivery + +A completed handler means its code ran. A persisted action means Void recorded +intent. `provider_accepted` means the upstream accepted the submission, not that +the recipient's mailbox received it. The UI, SDK and logs must use those exact +meanings. Do not label provider acceptance as `delivered` without a separate +verified delivery event. + +Record per-action and per-recipient states: `rejected`, `reserved`, +`attempt_started`, `provider_accepted`, `failed`, `outcome_unknown`, or `cancelled`. +Expose the Void operation/receipt ID, timestamps, transport, provider reference +when available, policy version, error code and safe next action. Persist an +operation before sending; a failure to save the final provider response leaves an +observable unresolved attempt, never an unrecorded send reported as successful. + +Retain operational metadata for 30 days by default with project authorization and +administrator audit access. Avoid subjects, raw headers, bodies, attachments and +credentials in the ledger. Recipient addresses are protected project data and +must follow the same retention/deletion policy. Keep idempotency tombstones for +at least that interval and document that reusing a key after expiry may send again. +An unresolved provider attempt may retain a cleanup fence after delivery metadata +expires, containing only its opaque ID, project, sender domain and start time. +That fence must contain no recipient address or message content. A completed +`outcome_unknown` remains non-replayable but no longer represents an active call +that must block resource cleanup. +Analytics, searchable message content and a hosted mailbox remain out of scope. + +`void email logs` becomes a view over this ledger, with receipt/action IDs that +connect handler logs to delivery outcomes. `replyEmail` and `message.forward` +inside a platform handler enqueue intents; awaiting them cannot claim upstream +acceptance because execution follows the handler's completion. Document this +existing distinction and make subsequent errors queryable. Native deployments +continue to expose their provider operation errors directly. + +### Inbound completion + +```mermaid +sequenceDiagram + participant I as Zone ingress + participant G as Email gateway + participant T as Tenant handler + participant A as Admission and ledger + participant P as Provider adapter + I->>G: Authenticated envelope and bounded MIME + G->>A: Authorize route and create receipt + G->>T: Bounded request and receipt capability + T-->>G: Stream action intents + G->>G: Validate complete bounded batch + G->>A: Record actions and atomically admit recipients + A-->>G: Approved actions and visible rejections + G->>P: Execute admitted attempts + P-->>G: Accepted, refused or unknown + G->>A: Persist outcomes + G-->>I: Receipt result with action summary + Note over I,A: Handler completion and action delivery are distinct ``` -Exit 0, Cloudflare never contacted, nothing stored. The mode is enforced -server-side — the add route answers 403 with the same text and revokes a -posted grant — so the CLI check only spares the browser round trip. `status` -on an administrator's row names the operator command for each step the owner -cannot take (`domain-sync` for drift, `domain-add` for a failed setup, -`domain-add … --token-stdin` for an expired pasted token). The default policy and mode -leave the managed platform's behavior unchanged: no new probe, binding or -account call for a platform that sets neither. - -## Out of scope - -Third-party provider wrappers, component templates, typed sender discovery -and persistent delivery logs are not part of this design; users call a -provider SDK directly where appropriate. - -Native setup detects email at the feature level rather than onboarding -inbound-only apps separately. Splitting that detection would need to handle -sends from dependencies, dynamic imports and direct binding access; it is not -a safe deletion of the existing binding. +The gateway awaits the result/ledger path within its invocation budget; it does +not rely on a best-effort background task as the only outcome record. Before any +outbound side effect, a permanent route or handler rejection can be returned to +the original event. Temporary infrastructure failures must not be translated into +a permanent recipient rejection. Verify the actual Email Routing retry/error +behavior before documenting automatic SMTP retries. + +Once a handler has run, a failed reply or forward does not retroactively reject +an otherwise accepted inbound message. Record the failed action and its reason. +If the provider outcome is uncertain, retain `outcome_unknown`; failing the entire +receipt must not blindly replay successful sends or arbitrary handler side effects. +The platform cannot roll back a handler's own database writes. + +Keep a relay request ID stable across HTTP retries within the same invocation, +scoped to its ingress and bound to recipient and content digest. Separate SMTP +redeliveries may lack a stable provider identifier; `Message-ID` is neither unique +nor trusted enough to promise deduplication. Do not claim exactly-once handler +execution or exactly-once delivery across that boundary. + +Automatically retry only a definitively unsubmitted or explicitly retry-safe +provider attempt, using the provider's documented idempotency contract when it +exists. An ambiguous timeout is not retry-safe. The first release does not retain +raw MIME for background redelivery; retries requiring message content need the +caller to resubmit it with the existing operation ID and digest. Native actions +requiring the original event cannot be replayed after it ends. Durable queued +redelivery would need a separate encrypted payload-retention design. + +## Administrator and developer experience + +Keep the existing `void email domain add|status|sync|remove` commands and operator +`void platform email domain-*` commands. They now manage an assignment through a +connection. `--plan` shows whether a zone ingress is created or reused, existing +routing conflicts, credential scope, capability changes and cleanup impact. + +In administrator mode, project owners see the exact command to give their +administrator and can inspect status/logs without a Cloudflare account. Owners +can maintain pre-existing owner-managed assignments; they cannot mutate an +administrator-managed connection. The mode check remains authenticated and +server-enforced before a credential flow starts. + +Show separate readiness and the operation ID in both CLI and admin UI. A failed +or ambiguous operation exits nonzero even when inbound remains usable; present +the usable capability alongside the specific failure. Removal clearly identifies +shared resources it will retain. No request inbox or approval-notification product +is required for the first release. + +## Implementation and release verification + +### Implementation sequence + +1. Introduce zone connections, domain assignments, connection-scoped credentials, + durable operations, action outcomes and atomic quota records. Replace the + one-live-domain-per-zone constraint with connection and exact-domain uniqueness. +2. Implement the shared provisioning service, resumable reconciler, secret rotation + and scoped-token setup. Route owner and administrator commands through the same + service while preserving their authorization boundaries. +3. Implement one ingress per zone and the bounded tenant protocol. Include its + version in deployment metadata and rebuild development/test apps to match. + Reject unsupported versions instead of falling back to unbounded RPC. +4. Wire direct sends and inbound actions through authoritative admission and the + outcome ledger. Remove KV-only authorization and counters from the email path. + Expose readiness, operation IDs and action results in the CLI and admin UI. +5. Complete the acceptance gates below, align user-facing documentation, and enable + email in production only when the complete flow passes. + +There are no production email users to migrate, so dual-running the old design +and maintaining legacy email protocol compatibility are not release requirements. +Development installations may be reset or explicitly converted as appropriate. +Any reset must account for real provider resources and credentials: inspect owned +catch-all rules, retain unrelated mail configuration, clean up obsolete relays, +and explicitly revoke unused test grants. Test shared and custom routes together +before release. + +### Acceptance gates + +- **Zone routing:** shared sender plus two project subdomains on one zone; + unknown and disabled domains; BCC; plus tags; conflicting explicit/catch-all + rules; concurrent add/remove; deleting one project leaves siblings functional. +- **Authority:** cross-zone secret replay, forged project/domain claims, public + access to the reserved handler, owner versus administrator permissions, expired + capabilities, policy changes during admission and domain transfer with stale KV. +- **Recovery:** inject a failure before and after every provider call and database + commit; kill a reconciler mid-step; delay an old provider response; fail KV after + success; verify refresh uncertainty and both phases of secret rotation. +- **Admission:** concurrent bursts never exceed configured recipient-attempt caps; + duplicate keys do not send or charge again; partial batches, UTC month rollover, + rolling windows, provider refusals and unknown outcomes retain correct accounting. +- **Tenant isolation:** oversized/deep metadata, too many frames, truncated MIME, + stalled streams and aggregate concurrency; measure memory under adversarial + payloads rather than trusting schema validation or serialized byte limits alone. +- **Outcomes:** handler success followed by blocked/failed reply; crash around + `attempt_started`; provider success followed by ledger write failure; lost relay + response; duplicate HTTP attempts; no successful recipient replay on partial failure. +- **Live Cloudflare:** token scope, routing/subdomain operations, shared/custom + ingress, secret rotation, provider forwarding/reply semantics, plan refusals, + real MIME/header/recipient limits, and original-event failure/retry behavior. + Earlier development probes are evidence, not substitutes for these gates. +- **Native and API contract:** Free routing and verified sends stay usable; + non-email apps emit no paid binding or entitlement probe; SDK results, MIME limits + and idempotency fields match the documented first-release contract. + +For implementation, clarify any change to these developer-experience decisions +before changing APIs: domain ownership, caller idempotency keys, quota units, +and outcome retention. Run focused `vp test run` tests during development and +`vp run check` after each implementation batch; investigate hangs immediately. +Run the full test suite for final implementation verification. After verification, +update the affected guides, API/CLI references, package guidance and shipped Void +skill when public behavior changes. New CLI options must also update command help +and interactive hints. Updating this design does not implement those changes. + +## Scope boundaries + +The first release includes routing ownership, recoverable configuration, credential +lifecycle, bounded dispatch, strict platform admission and minimal operational +outcomes. It does not build a mailbox, message search, marketing automation, +provider wrappers, automatic domain delegation or guaranteed exactly-once email. diff --git a/platform/meta/design-docs/README.md b/platform/meta/design-docs/README.md index a16a45bc7..4b1b935b3 100644 --- a/platform/meta/design-docs/README.md +++ b/platform/meta/design-docs/README.md @@ -34,7 +34,7 @@ as an instruction to modify a live installation. | Serving and routing | [Asset fallback](./0066-wfp-asset-r2-fallback.md), [direct R2 uploads](./0068-direct-r2-asset-upload.md), [route-aware ISR](./0077-route-aware-isr-ttl.md) | | Custom domains | [Record presentation](./0072-custom-domain-verification-ux-improvements.md), [HTTP certificate validation](./0073-custom-domain-http-dcv-migration.md) | | Administration | [Operator CLI](./0078-platform-operator-cli.md) | -| Email | [Transport, consent and setup decisions](./0078-email-cf-native.md) | +| Email | [Routing, recovery and delivery design](./0078-email-cf-native.md) | | Legacy Sandboxes | [Container ownership and teardown](./0067-cross-script-do-host-architecture.md) | ## Reading revisions diff --git a/platform/meta/operations.md b/platform/meta/operations.md index e8487ddcc..941ca2888 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -102,25 +102,32 @@ Container builds use the configured `BuildManager` or `BuildManagerLarge` class ## Email -Every project sends as `[+tag]@` and receives at `+anything@` through one shared mail facility; there is no per-project DNS work. The mail domain is the `EMAIL_SENDER_DOMAIN` var on the API and proxy Workers, handed to deployed user Workers as `__VOID_EMAIL_DOMAIN`. The two Worker values must match: the proxy validates every sender against its own copy, so a mismatch fails the API's own verification mail with `INVALID_FROM`. Every reader fails closed when the var is absent. Void Cloud uses `mail.void.cloud` and `mail.staging.void.cloud`, both subdomains of the `void.cloud` zone. +The dedicated email gateway receives inbound mail and dispatches bounded requests to tenant handlers. The proxy handles outbound sends and receipt verification. The API owns zone connections, exact domain assignments, policy, quota reservations, and durable operation and delivery records in PostgreSQL. -### One-time zone setup, per environment +### Configure the shared mail zone -Do these in order; step 4 before step 5, or the catch-all points at a Worker with no `email()` export. +For a managed installation, provide `VOID_EMAIL_SENDER_DOMAIN` and `VOID_EMAIL_SHARED_ZONE_ID` during installation or upgrade. These values are recorded in the installation; routine upgrades preserve them. The installer supplies the platform account and gateway identity separately from the application zone. -1. Extend `CF_API_TOKEN` with Email Routing: Edit. Without it every destination add returns 403, which the CLI reports as a 502 and the owner auto-add on project creation swallows. -2. Add the subdomain to Email Routing (dashboard: Email → Email Routing → the zone → Settings → Subdomains). Cloudflare adds and locks the MX, SPF, and DKIM records. The two-label staging name is unverified against this form. -3. Onboard the same name to Email Sending (dashboard, or `wrangler email sending enable `). Without it the binding sends only to verified destination addresses, capped at 200 per account across every project. Requires Workers Paid. -4. Deploy the proxy with `send_email` bound and the `email()` export live. Check the top level, `env.production`, and `env.staging` of `platform/packages/proxy/wrangler.jsonc`; Wrangler does not inherit `send_email` into a named env. -5. Create the catch-all rule on the subdomain: action _Send to a Worker_, destination the proxy Worker (`PUT /zones/{zone}/email/routing/rules/catch_all` with `{ "type": "worker", "value": ["void-proxy"] }`). Wrangler has no catch-all command and its `addresses` array cannot write it. This rule is the inbound kill switch. Leave the zone's subaddressing setting alone; the catch-all takes every address on the subdomain. -6. The slug mirror (`email-slug:` in `ROUTING` KV) is written on project creation and rewritten hourly by the rollover, so projects that predate the feature are covered within an hour of the API deploy. -7. Verify with the proxy tail and a message to `+test@`. Outbound sent through the binding shows as dropped in the Email Routing summary even when delivered; read Email Sending metrics instead. +For repository deployments, configure the equivalent Worker values before enabling email: -### Deploy order and rollback +- API, proxy, and email gateway: the same `EMAIL_SENDER_DOMAIN`. +- API and email gateway: `EMAIL_SHARED_ACCOUNT_ID`, `EMAIL_SHARED_ZONE_ID`, and `EMAIL_SHARED_INGRESS_NAME`, identifying the platform account, mail zone, and dedicated gateway Worker. +- API: `EMAIL_GATEWAY_ORIGIN`, the gateway's HTTPS origin reachable from customer ingress Workers. +- API, proxy, and email gateway: the same installation `JWT_SECRET`; the API retains the scoped runtime token and project-encryption keys. -Deploy the proxy before the API: the API's verification mail posts to the proxy's `/email/internal/send`. `vp run deploy` runs the API first, so run the two as explicit steps for the release that turns email on. To stop inbound, delete the catch-all rule; to stop outbound, redeploy the proxy without `send_email`. +The API's scheduled reconciliation creates the shared connection and reserved shared-domain route only when the complete identity is configured. Confirm the resulting operation and inbound readiness before directing traffic to the gateway. Provision routing and Sending independently: a provider permission or plan refusal must remain visible in the corresponding readiness state. Sending to arbitrary recipients requires Cloudflare Email Sending onboarding and its supported plan. -Two server-side changes are retroactive. Before the first API deploy that carries them, query `project_secrets.name IN ('SEND_EMAIL', '__VOID_EMAIL_DOMAIN', '__VOID_PROJECT_SLUG')` — those are now reserved binding names and a project holding one fails deploys — and check for projects already holding the reserved slugs `noreply`, `postmaster`, `abuse`, `bounce`, and `security`. +Customer connections deploy one ingress Worker in the customer's account and zone. Shared and custom domain assignments can coexist on one zone. Setup proves the deployed ingress secret and the gateway's acceptance before changing the owned catch-all. Inspect foreign rules and preserve them; never repoint a catch-all simply because its Worker name resembles Void's. + +### Deployment and recovery + +Deploy the outbound proxy, API, and gateway before enabling inbound routing. The gateway must expose the new bounded email protocol, and tenant apps with handlers must be rebuilt and redeployed with its deployment metadata. The proxy no longer accepts inbound `/email/relay` requests or native email events. + +Inspect all three readiness states and the operation ID with `void email domain status `. Use `sync` to reconcile recoverable steps and `rotate-secret` for explicit ingress-secret rotation. An uncertain provider write remains blocked until its outcome can be proved; neither a timeout nor a missing cache entry authorizes another write. Never erase the operation to force a retry. + +PostgreSQL is authoritative for consent, policy, suspension, and recipient-attempt quotas. Cache publication retries independently. `void email logs` exposes receipt and action metadata: provider acceptance is not proof of delivery, and an unknown result must not be retried with a new idempotency key. Removing one domain or project must preserve sibling routes and unresolved cleanup records. + +Before production enablement, complete the [email design's acceptance gates](./design-docs/0078-email-cf-native.md#acceptance-gates), including live Cloudflare routing, forwarding/reply, scoped-token, rotation, and failure-recovery checks. ## Staging Access Control diff --git a/platform/package.json b/platform/package.json index 31baf9228..ebe9fedc3 100644 --- a/platform/package.json +++ b/platform/package.json @@ -5,15 +5,17 @@ "scripts": { "build": "vp run --filter @voidcloud/dashboard build", "check": "vp run -r --parallel typecheck", - "deploy": "vp run deploy:api && vp run deploy:proxy && vp run deploy:tail && vp run deploy:dispatch && vp run deploy:dashboard", + "deploy": "vp run deploy:api && vp run deploy:proxy && vp run deploy:email-gateway && vp run deploy:tail && vp run deploy:dispatch && vp run deploy:dashboard", "deploy:api": "vp run --filter @voidcloud/api migrate && vp run --filter @voidcloud/api deploy --env production", "deploy:dashboard": "vp run --filter @voidcloud/dashboard deploy --env production", "deploy:dispatch": "vp run --filter @voidcloud/dispatch deploy --env production", + "deploy:email-gateway": "vp run --filter @voidcloud/email-gateway deploy --env production", "deploy:proxy": "vp run --filter @voidcloud/proxy deploy --env production", - "deploy:staging": "vp run deploy:staging:api && vp run deploy:staging:proxy && vp run deploy:staging:tail && vp run deploy:staging:dispatch && vp run deploy:staging:dashboard", + "deploy:staging": "vp run deploy:staging:api && vp run deploy:staging:proxy && vp run deploy:staging:email-gateway && vp run deploy:staging:tail && vp run deploy:staging:dispatch && vp run deploy:staging:dashboard", "deploy:staging:api": "vp run --filter @voidcloud/api migrate:staging && vp run --filter @voidcloud/api deploy --env staging", "deploy:staging:dashboard": "vp run --filter @voidcloud/dashboard deploy --env staging", "deploy:staging:dispatch": "vp run --filter @voidcloud/dispatch deploy --env staging", + "deploy:staging:email-gateway": "vp run --filter @voidcloud/email-gateway deploy --env staging", "deploy:staging:proxy": "vp run --filter @voidcloud/proxy deploy --env staging", "deploy:staging:tail": "vp run --filter @voidcloud/tail deploy --env staging", "deploy:tail": "vp run --filter @voidcloud/tail deploy --env production", diff --git a/platform/packages/api/drizzle/0047_email_gateway.sql b/platform/packages/api/drizzle/0047_email_gateway.sql new file mode 100644 index 000000000..af0952b1d --- /dev/null +++ b/platform/packages/api/drizzle/0047_email_gateway.sql @@ -0,0 +1,208 @@ +CREATE TABLE "email_cache_outbox" ( + "id" text PRIMARY KEY NOT NULL, + "installation_id" text NOT NULL, + "resource_kind" text NOT NULL, + "resource_id" text NOT NULL, + "version" integer NOT NULL, + "payload" jsonb, + "published_at" timestamp, + "created_at" timestamp DEFAULT now() NOT NULL +); +--> statement-breakpoint +CREATE TABLE "email_credentials" ( + "id" text PRIMARY KEY NOT NULL, + "installation_id" text NOT NULL, + "managed_by" text NOT NULL, + "manager_user_id" text, + "kind" text NOT NULL, + "account_id" text NOT NULL, + "zone_id" text NOT NULL, + "ciphertext" text, + "iv" text, + "key_version" text, + "token_id" text, + "expires_on" timestamp, + "generation" integer DEFAULT 1 NOT NULL, + "status" text DEFAULT 'healthy' NOT NULL, + "created_at" timestamp DEFAULT now() NOT NULL, + "updated_at" timestamp DEFAULT now() NOT NULL, + CONSTRAINT "email_credentials_material_check" CHECK (("email_credentials"."kind" = 'platform' AND "email_credentials"."ciphertext" IS NULL AND "email_credentials"."iv" IS NULL AND "email_credentials"."key_version" IS NULL) OR ("email_credentials"."kind" = 'api_token' AND "email_credentials"."ciphertext" IS NOT NULL AND "email_credentials"."iv" IS NOT NULL AND "email_credentials"."key_version" IS NOT NULL)) +); +--> statement-breakpoint +CREATE TABLE "email_domain_routes" ( + "id" text PRIMARY KEY NOT NULL, + "domain" text NOT NULL, + "connection_id" text NOT NULL, + "project_id" text, + "addressing" text NOT NULL, + "managed_by" text NOT NULL, + "assigned_by_user_id" text, + "desired_state" text DEFAULT 'active' NOT NULL, + "inbound_status" text DEFAULT 'pending' NOT NULL, + "inbound_reason" text, + "inbound_observed_at" timestamp, + "outbound_status" text DEFAULT 'pending' NOT NULL, + "outbound_reason" text, + "outbound_observed_at" timestamp, + "desired_generation" integer DEFAULT 1 NOT NULL, + "created_at" timestamp DEFAULT now() NOT NULL, + "updated_at" timestamp DEFAULT now() NOT NULL, + CONSTRAINT "email_domain_routes_assignment_check" CHECK (("email_domain_routes"."addressing" = 'custom' AND "email_domain_routes"."project_id" IS NOT NULL) OR ("email_domain_routes"."addressing" = 'shared' AND "email_domain_routes"."project_id" IS NULL)) +); +--> statement-breakpoint +CREATE TABLE "email_operation_steps" ( + "id" text PRIMARY KEY NOT NULL, + "operation_id" text NOT NULL, + "ordinal" integer NOT NULL, + "kind" text NOT NULL, + "resource_identity" text NOT NULL, + "request_digest" text NOT NULL, + "attempt" integer DEFAULT 0 NOT NULL, + "status" text DEFAULT 'pending' NOT NULL, + "outcome" jsonb, + "failure_code" text, + "failure_detail" text, + "started_at" timestamp, + "finished_at" timestamp +); +--> statement-breakpoint +CREATE TABLE "email_operations" ( + "id" text PRIMARY KEY NOT NULL, + "installation_id" text NOT NULL, + "connection_id" text NOT NULL, + "route_id" text, + "actor_kind" text NOT NULL, + "actor_user_id" text, + "actor_scope" text NOT NULL, + "kind" text NOT NULL, + "idempotency_key" text NOT NULL, + "request_digest" text NOT NULL, + "desired_generation" integer NOT NULL, + "status" text DEFAULT 'pending' NOT NULL, + "current_step" text, + "failure_code" text, + "failure_detail" text, + "created_at" timestamp DEFAULT now() NOT NULL, + "updated_at" timestamp DEFAULT now() NOT NULL +); +--> statement-breakpoint +CREATE TABLE "email_zone_connections" ( + "id" text PRIMARY KEY NOT NULL, + "installation_id" text NOT NULL, + "account_id" text NOT NULL, + "zone_id" text NOT NULL, + "zone_name" text NOT NULL, + "managed_by" text NOT NULL, + "manager_user_id" text, + "credential_id" text, + "ingress_worker_name" text NOT NULL, + "ingress_version" integer, + "desired_generation" integer DEFAULT 1 NOT NULL, + "active_secret_generation" integer DEFAULT 0 NOT NULL, + "staged_secret_generation" integer, + "secret_ciphertext" text NOT NULL, + "secret_iv" text NOT NULL, + "secret_key_version" text NOT NULL, + "staged_secret_ciphertext" text, + "staged_secret_iv" text, + "staged_secret_key_version" text, + "previous_secret_hash" text, + "previous_secret_until" timestamp, + "inbound_status" text DEFAULT 'pending' NOT NULL, + "inbound_reason" text, + "inbound_observed_at" timestamp, + "management_status" text DEFAULT 'probe_failed' NOT NULL, + "management_reason" text, + "management_observed_at" timestamp, + "created_at" timestamp DEFAULT now() NOT NULL, + "updated_at" timestamp DEFAULT now() NOT NULL, + CONSTRAINT "email_zone_connections_manager_check" CHECK (("email_zone_connections"."managed_by" = 'owner' AND "email_zone_connections"."manager_user_id" IS NOT NULL) OR ("email_zone_connections"."managed_by" = 'admin')) +); +--> statement-breakpoint +CREATE TABLE "email_action_recipients" ( + "id" text PRIMARY KEY NOT NULL, + "action_id" text NOT NULL, + "project_id" text NOT NULL, + "recipient" text NOT NULL, + "state" text NOT NULL, + "error_code" text, + "provider_reference" text, + "reserved_at" timestamp with time zone, + "attempt_started_at" timestamp with time zone, + "completed_at" timestamp with time zone, + CONSTRAINT "email_action_recipients_action_recipient_uq" UNIQUE("action_id","recipient"), + CONSTRAINT "email_action_recipients_state_check" CHECK ("email_action_recipients"."state" IN ('rejected', 'reserved', 'attempt_started', 'provider_accepted', 'failed', 'outcome_unknown', 'cancelled')) +); +--> statement-breakpoint +CREATE TABLE "email_actions" ( + "id" text PRIMARY KEY NOT NULL, + "project_id" text NOT NULL, + "sender_domain" text NOT NULL, + "receipt_id" text, + "kind" text NOT NULL, + "idempotency_key" text NOT NULL, + "payload_digest" text NOT NULL, + "transport" text NOT NULL, + "policy_version" integer NOT NULL, + "created_at" timestamp with time zone DEFAULT now() NOT NULL, + CONSTRAINT "email_actions_project_key_uq" UNIQUE("project_id","idempotency_key"), + CONSTRAINT "email_actions_kind_check" CHECK ("email_actions"."kind" IN ('direct', 'forward', 'reply')) +); +--> statement-breakpoint +CREATE TABLE "email_monthly_usage" ( + "project_id" text NOT NULL, + "month" text NOT NULL, + "recipient_attempts" integer DEFAULT 0 NOT NULL, + CONSTRAINT "email_monthly_usage_project_month_uq" UNIQUE("project_id","month"), + CONSTRAINT "email_monthly_usage_nonnegative_check" CHECK ("email_monthly_usage"."recipient_attempts" >= 0) +); +--> statement-breakpoint +CREATE TABLE "email_project_controls" ( + "project_id" text PRIMARY KEY NOT NULL, + "monthly_limit" integer DEFAULT 200 NOT NULL, + "burst_limit" integer DEFAULT 10 NOT NULL, + "suspended_at" timestamp with time zone, + "version" integer DEFAULT 1 NOT NULL +); +--> statement-breakpoint +CREATE TABLE "email_receipts" ( + "id" text PRIMARY KEY NOT NULL, + "project_id" text NOT NULL, + "status" text DEFAULT 'received' NOT NULL, + "payload_digest" text, + "final_reject" boolean, + "created_at" timestamp with time zone DEFAULT now() NOT NULL +); +--> statement-breakpoint +CREATE TABLE "email_unresolved_attempts" ( + "id" text PRIMARY KEY NOT NULL, + "project_id" text NOT NULL, + "sender_domain" text NOT NULL, + "started_at" timestamp with time zone NOT NULL +); +--> statement-breakpoint +ALTER TABLE "email_domain_routes" ADD CONSTRAINT "email_domain_routes_connection_id_email_zone_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."email_zone_connections"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint +ALTER TABLE "email_operation_steps" ADD CONSTRAINT "email_operation_steps_operation_id_email_operations_id_fk" FOREIGN KEY ("operation_id") REFERENCES "public"."email_operations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint +ALTER TABLE "email_operations" ADD CONSTRAINT "email_operations_connection_id_email_zone_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."email_zone_connections"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint +ALTER TABLE "email_operations" ADD CONSTRAINT "email_operations_route_id_email_domain_routes_id_fk" FOREIGN KEY ("route_id") REFERENCES "public"."email_domain_routes"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint +ALTER TABLE "email_action_recipients" ADD CONSTRAINT "email_action_recipients_action_id_email_actions_id_fk" FOREIGN KEY ("action_id") REFERENCES "public"."email_actions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint +ALTER TABLE "email_actions" ADD CONSTRAINT "email_actions_receipt_id_email_receipts_id_fk" FOREIGN KEY ("receipt_id") REFERENCES "public"."email_receipts"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint +ALTER TABLE "email_project_controls" ADD CONSTRAINT "email_project_controls_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint +CREATE UNIQUE INDEX "email_cache_outbox_version_uq" ON "email_cache_outbox" USING btree ("resource_kind","resource_id","version");--> statement-breakpoint +CREATE INDEX "email_cache_outbox_pending_idx" ON "email_cache_outbox" USING btree ("published_at","created_at");--> statement-breakpoint +CREATE INDEX "email_credentials_scope_idx" ON "email_credentials" USING btree ("installation_id","account_id","zone_id");--> statement-breakpoint +CREATE UNIQUE INDEX "email_domain_routes_domain_uq" ON "email_domain_routes" USING btree ("domain");--> statement-breakpoint +CREATE INDEX "email_domain_routes_connection_idx" ON "email_domain_routes" USING btree ("connection_id");--> statement-breakpoint +CREATE INDEX "email_domain_routes_project_idx" ON "email_domain_routes" USING btree ("project_id");--> statement-breakpoint +CREATE UNIQUE INDEX "email_operation_steps_order_uq" ON "email_operation_steps" USING btree ("operation_id","ordinal");--> statement-breakpoint +CREATE UNIQUE INDEX "email_operations_key_uq" ON "email_operations" USING btree ("installation_id","actor_scope","idempotency_key");--> statement-breakpoint +CREATE INDEX "email_operations_work_idx" ON "email_operations" USING btree ("status","updated_at");--> statement-breakpoint +CREATE INDEX "email_operations_connection_idx" ON "email_operations" USING btree ("connection_id");--> statement-breakpoint +CREATE UNIQUE INDEX "email_zone_connections_zone_uq" ON "email_zone_connections" USING btree ("installation_id","account_id","zone_id");--> statement-breakpoint +CREATE UNIQUE INDEX "email_zone_connections_ingress_uq" ON "email_zone_connections" USING btree ("account_id","ingress_worker_name");--> statement-breakpoint +CREATE INDEX "email_zone_connections_manager_idx" ON "email_zone_connections" USING btree ("manager_user_id");--> statement-breakpoint +CREATE INDEX "idx_email_action_recipients_project_reserved" ON "email_action_recipients" USING btree ("project_id","reserved_at");--> statement-breakpoint +CREATE INDEX "idx_email_actions_project_created" ON "email_actions" USING btree ("project_id","created_at");--> statement-breakpoint +CREATE INDEX "idx_email_receipts_project_created" ON "email_receipts" USING btree ("project_id","created_at");--> statement-breakpoint +CREATE INDEX "idx_email_unresolved_attempts_project" ON "email_unresolved_attempts" USING btree ("project_id");--> statement-breakpoint +CREATE INDEX "idx_email_unresolved_attempts_domain" ON "email_unresolved_attempts" USING btree ("sender_domain"); \ No newline at end of file diff --git a/platform/packages/api/drizzle/compatibility.json b/platform/packages/api/drizzle/compatibility.json index ae2b6c547..a3387e6ed 100644 --- a/platform/packages/api/drizzle/compatibility.json +++ b/platform/packages/api/drizzle/compatibility.json @@ -21,6 +21,10 @@ { "platformVersion": "0.10.14", "schemaDigest": "3dbf4c31d4bc97a11edca35c59b34ffad1f072df0ad7174d69e2de1057e2610b" + }, + { + "platformVersion": "0.20.1", + "schemaDigest": "6de871d9524b082bba675d0d653ade45f95206895a962fea2b9be4b85d486313" } ] } diff --git a/platform/packages/api/drizzle/meta/0047_snapshot.json b/platform/packages/api/drizzle/meta/0047_snapshot.json new file mode 100644 index 000000000..5c2d04b83 --- /dev/null +++ b/platform/packages/api/drizzle/meta/0047_snapshot.json @@ -0,0 +1,5220 @@ +{ + "id": "7a60f798-644e-40c9-9cc8-d042c56c9603", + "prevId": "7f4f0bae-80ca-4c61-890f-84d00a663065", + "version": "7", + "dialect": "postgresql", + "tables": { + "public.auth_codes": { + "name": "auth_codes", + "schema": "", + "columns": { + "code": { + "name": "code", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "jwt": { + "name": "jwt", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "cli_state": { + "name": "cli_state", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "code_challenge": { + "name": "code_challenge", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "code_challenge_method": { + "name": "code_challenge_method", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.builds": { + "name": "builds", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "executor": { + "name": "executor", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'container'" + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'queued'" + }, + "commit_sha": { + "name": "commit_sha", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "branch": { + "name": "branch", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "deployment_id": { + "name": "deployment_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "github_run_id": { + "name": "github_run_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "github_run_attempt": { + "name": "github_run_attempt", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "logs_url": { + "name": "logs_url", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "check_run_id": { + "name": "check_run_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "error": { + "name": "error", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "exit_code": { + "name": "exit_code", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "instance_type": { + "name": "instance_type", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "started_at": { + "name": "started_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "completed_at": { + "name": "completed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_builds_project_created": { + "name": "idx_builds_project_created", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_builds_status": { + "name": "idx_builds_status", + "columns": [ + { + "expression": "status", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_builds_user_status": { + "name": "idx_builds_user_status", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "status", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_builds_project_github_run_id": { + "name": "idx_builds_project_github_run_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "github_run_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "github_run_attempt", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "where": "\"builds\".\"github_run_id\" IS NOT NULL AND \"builds\".\"github_run_attempt\" IS NOT NULL AND \"builds\".\"status\" IN ('starting', 'building', 'deploying')", + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "builds_project_id_projects_id_fk": { + "name": "builds_project_id_projects_id_fk", + "tableFrom": "builds", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + }, + "builds_user_id_users_id_fk": { + "name": "builds_user_id_users_id_fk", + "tableFrom": "builds", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + }, + "builds_deployment_id_deployments_id_fk": { + "name": "builds_deployment_id_deployments_id_fk", + "tableFrom": "builds", + "tableTo": "deployments", + "columnsFrom": ["deployment_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.deployments": { + "name": "deployments", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "manifest": { + "name": "manifest", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "source": { + "name": "source", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "commit": { + "name": "commit", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "repository_url": { + "name": "repository_url", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "commit_url": { + "name": "commit_url", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "git_ref": { + "name": "git_ref", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "cli_version": { + "name": "cli_version", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "admission_protocol": { + "name": "admission_protocol", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "error_message": { + "name": "error_message", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "asset_hashes": { + "name": "asset_hashes", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "deployed_at": { + "name": "deployed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "retained": { + "name": "retained", + "type": "boolean", + "primaryKey": false, + "notNull": true, + "default": false + }, + "applied_migrations": { + "name": "applied_migrations", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "bundle_stored": { + "name": "bundle_stored", + "type": "boolean", + "primaryKey": false, + "notNull": true, + "default": false + } + }, + "indexes": { + "idx_deployments_project_id": { + "name": "idx_deployments_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_deployments_project_status": { + "name": "idx_deployments_project_status", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "status", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_deployments_created_id": { + "name": "idx_deployments_created_id", + "columns": [ + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "deployments_project_id_projects_id_fk": { + "name": "deployments_project_id_projects_id_fk", + "tableFrom": "deployments", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.domains": { + "name": "domains", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "hostname": { + "name": "hostname", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "cf_hostname_id": { + "name": "cf_hostname_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "verification_data": { + "name": "verification_data", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_domains_project_id": { + "name": "idx_domains_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "domains_project_id_projects_id_fk": { + "name": "domains_project_id_projects_id_fk", + "tableFrom": "domains", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "domains_hostname_unique": { + "name": "domains_hostname_unique", + "nullsNotDistinct": false, + "columns": ["hostname"] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_destinations": { + "name": "email_destinations", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "address": { + "name": "address", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "cf_destination_id": { + "name": "cf_destination_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "verified_at": { + "name": "verified_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "verification_source": { + "name": "verification_source", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'cf'" + }, + "verified_by_user_id": { + "name": "verified_by_user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "verified_by_email_snapshot": { + "name": "verified_by_email_snapshot", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_email_destinations_project_id": { + "name": "idx_email_destinations_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_email_destinations_cf_destination_id": { + "name": "idx_email_destinations_cf_destination_id", + "columns": [ + { + "expression": "cf_destination_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_email_destinations_verified_by_user_id": { + "name": "idx_email_destinations_verified_by_user_id", + "columns": [ + { + "expression": "verified_by_user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "verified_by_email_snapshot", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_destinations_project_id_projects_id_fk": { + "name": "email_destinations_project_id_projects_id_fk", + "tableFrom": "email_destinations", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "email_destinations_verified_by_user_id_users_id_fk": { + "name": "email_destinations_verified_by_user_id_users_id_fk", + "tableFrom": "email_destinations", + "tableTo": "users", + "columnsFrom": ["verified_by_user_id"], + "columnsTo": ["id"], + "onDelete": "set null", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "email_destinations_project_address_uq": { + "name": "email_destinations_project_address_uq", + "nullsNotDistinct": false, + "columns": ["project_id", "address"] + } + }, + "policies": {}, + "checkConstraints": { + "email_destinations_status_check": { + "name": "email_destinations_status_check", + "value": "\"email_destinations\".\"status\" IN ('pending', 'verified')" + }, + "email_destinations_verification_source_check": { + "name": "email_destinations_verification_source_check", + "value": "\"email_destinations\".\"verification_source\" IN ('cf', 'platform')" + } + }, + "isRLSEnabled": false + }, + "public.email_domains": { + "name": "email_domains", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "domain": { + "name": "domain", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "zone_id": { + "name": "zone_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "account_id": { + "name": "account_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "mode": { + "name": "mode", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "credential_kind": { + "name": "credential_kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "token_ciphertext": { + "name": "token_ciphertext", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "token_iv": { + "name": "token_iv", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "token_key_version": { + "name": "token_key_version", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "managed_by": { + "name": "managed_by", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'owner'" + }, + "relay_ciphertext": { + "name": "relay_ciphertext", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "relay_iv": { + "name": "relay_iv", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "relay_key_version": { + "name": "relay_key_version", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "relay_worker_name": { + "name": "relay_worker_name", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "relay_version": { + "name": "relay_version", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "token_id": { + "name": "token_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "token_expires_on": { + "name": "token_expires_on", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "attempt_id": { + "name": "attempt_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "setup_state": { + "name": "setup_state", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_email_domains_project_id": { + "name": "idx_email_domains_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_domains_zone_uq": { + "name": "email_domains_zone_uq", + "columns": [ + { + "expression": "zone_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "where": "\"email_domains\".\"zone_id\" IS NOT NULL AND \"email_domains\".\"status\" IN ('active', 'pending')", + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_domains_relay_uq": { + "name": "email_domains_relay_uq", + "columns": [ + { + "expression": "account_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "relay_worker_name", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "where": "\"email_domains\".\"relay_worker_name\" IS NOT NULL", + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_domains_project_id_projects_id_fk": { + "name": "email_domains_project_id_projects_id_fk", + "tableFrom": "email_domains", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "email_domains_domain_uq": { + "name": "email_domains_domain_uq", + "nullsNotDistinct": false, + "columns": ["domain"] + } + }, + "policies": {}, + "checkConstraints": { + "email_domains_mode_check": { + "name": "email_domains_mode_check", + "value": "\"email_domains\".\"mode\" IN ('apex', 'subdomain')" + }, + "email_domains_status_check": { + "name": "email_domains_status_check", + "value": "\"email_domains\".\"status\" IN ('pending', 'active', 'token_revoked', 'token_expired', 'failed')" + }, + "email_domains_credential_kind_check": { + "name": "email_domains_credential_kind_check", + "value": "\"email_domains\".\"credential_kind\" IN ('oauth_grant', 'api_token', 'platform')" + }, + "email_domains_platform_token_check": { + "name": "email_domains_platform_token_check", + "value": "(\"email_domains\".\"credential_kind\" = 'platform' AND \"email_domains\".\"token_ciphertext\" IS NULL AND \"email_domains\".\"token_iv\" IS NULL AND \"email_domains\".\"token_key_version\" IS NULL) OR (\"email_domains\".\"credential_kind\" <> 'platform' AND \"email_domains\".\"token_ciphertext\" IS NOT NULL AND \"email_domains\".\"token_iv\" IS NOT NULL AND \"email_domains\".\"token_key_version\" IS NOT NULL)" + }, + "email_domains_managed_by_check": { + "name": "email_domains_managed_by_check", + "value": "\"email_domains\".\"managed_by\" IN ('owner', 'admin')" + } + }, + "isRLSEnabled": false + }, + "public.github_connections": { + "name": "github_connections", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "repo_full_name": { + "name": "repo_full_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "repository_id": { + "name": "repository_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "authorized_by_user_id": { + "name": "authorized_by_user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "branch": { + "name": "branch", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'main'" + }, + "build_executor": { + "name": "build_executor", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'container'" + }, + "workflow_path": { + "name": "workflow_path", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'.github/workflows/void-deploy.yml'" + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_github_connections_installation_id": { + "name": "idx_github_connections_installation_id", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_github_connections_repo_full_name": { + "name": "idx_github_connections_repo_full_name", + "columns": [ + { + "expression": "repo_full_name", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_github_connections_installation_repo_id": { + "name": "idx_github_connections_installation_repo_id", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "repository_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "github_connections_project_id_projects_id_fk": { + "name": "github_connections_project_id_projects_id_fk", + "tableFrom": "github_connections", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "github_connections_authorized_by_user_id_users_id_fk": { + "name": "github_connections_authorized_by_user_id_users_id_fk", + "tableFrom": "github_connections", + "tableTo": "users", + "columnsFrom": ["authorized_by_user_id"], + "columnsTo": ["id"], + "onDelete": "set null", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "github_connections_project_id_unique": { + "name": "github_connections_project_id_unique", + "nullsNotDistinct": false, + "columns": ["project_id"] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.github_installation_members": { + "name": "github_installation_members", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "github_account_id": { + "name": "github_account_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "verified_at": { + "name": "verified_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_github_installation_members_install_user": { + "name": "idx_github_installation_members_install_user", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_github_installation_members_user_id": { + "name": "idx_github_installation_members_user_id", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "github_installation_members_user_id_users_id_fk": { + "name": "github_installation_members_user_id_users_id_fk", + "tableFrom": "github_installation_members", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.github_installation_revocations": { + "name": "github_installation_revocations", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "github_account_id": { + "name": "github_account_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "revoked_at": { + "name": "revoked_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_github_installation_revocations_install_account": { + "name": "idx_github_installation_revocations_install_account", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "github_account_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.github_installations": { + "name": "github_installations", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "account_login": { + "name": "account_login", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "account_id": { + "name": "account_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "account_type": { + "name": "account_type", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "repositories": { + "name": "repositories", + "type": "jsonb", + "primaryKey": false, + "notNull": true, + "default": "'[]'::jsonb" + }, + "repository_selection": { + "name": "repository_selection", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'selected'" + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'active'" + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_github_installations_user_id": { + "name": "idx_github_installations_user_id", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_github_installations_account_id": { + "name": "idx_github_installations_account_id", + "columns": [ + { + "expression": "account_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "github_installations_user_id_users_id_fk": { + "name": "github_installations_user_id_users_id_fk", + "tableFrom": "github_installations", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "set null", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "github_installations_installation_id_unique": { + "name": "github_installations_installation_id_unique", + "nullsNotDistinct": false, + "columns": ["installation_id"] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.github_webhook_redeliveries": { + "name": "github_webhook_redeliveries", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "guid": { + "name": "guid", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "delivery_id": { + "name": "delivery_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "event": { + "name": "event", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "status_code": { + "name": "status_code", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "redelivered_at": { + "name": "redelivered_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_github_webhook_redeliveries_guid": { + "name": "idx_github_webhook_redeliveries_guid", + "columns": [ + { + "expression": "guid", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.invitations": { + "name": "invitations", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "email": { + "name": "email", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "invited_by": { + "name": "invited_by", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "accepted_by": { + "name": "accepted_by", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "revoked_at": { + "name": "revoked_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "revoked_by": { + "name": "revoked_by", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "accepted_at": { + "name": "accepted_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + } + }, + "indexes": { + "idx_invitations_email": { + "name": "idx_invitations_email", + "columns": [ + { + "expression": "email", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_invitations_status": { + "name": "idx_invitations_status", + "columns": [ + { + "expression": "status", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.migration_renames": { + "name": "migration_renames", + "schema": "", + "columns": { + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "from_name": { + "name": "from_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "to_name": { + "name": "to_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_migration_renames_project_id": { + "name": "idx_migration_renames_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "migration_renames_project_id_projects_id_fk": { + "name": "migration_renames_project_id_projects_id_fk", + "tableFrom": "migration_renames", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": { + "migration_renames_project_id_from_name_to_name_pk": { + "name": "migration_renames_project_id_from_name_to_name_pk", + "columns": ["project_id", "from_name", "to_name"] + } + }, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.oauth_accounts": { + "name": "oauth_accounts", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "provider": { + "name": "provider", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "provider_id": { + "name": "provider_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_oauth_accounts_provider_id": { + "name": "idx_oauth_accounts_provider_id", + "columns": [ + { + "expression": "provider", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "provider_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_oauth_accounts_user_id": { + "name": "idx_oauth_accounts_user_id", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "oauth_accounts_user_id_users_id_fk": { + "name": "oauth_accounts_user_id_users_id_fk", + "tableFrom": "oauth_accounts", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.oauth_nonces": { + "name": "oauth_nonces", + "schema": "", + "columns": { + "nonce": { + "name": "nonce", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.operator_events": { + "name": "operator_events", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "login": { + "name": "login", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "action": { + "name": "action", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "target": { + "name": "target", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "http_status": { + "name": "http_status", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_operator_events_created": { + "name": "idx_operator_events_created", + "columns": [ + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.operator_sessions": { + "name": "operator_sessions", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "human_session_id": { + "name": "human_session_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_operator_sessions_expiry": { + "name": "idx_operator_sessions_expiry", + "columns": [ + { + "expression": "expires_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "operator_sessions_user_id_users_id_fk": { + "name": "operator_sessions_user_id_users_id_fk", + "tableFrom": "operator_sessions", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "operator_sessions_human_session_id_platform_human_sessions_id_fk": { + "name": "operator_sessions_human_session_id_platform_human_sessions_id_fk", + "tableFrom": "operator_sessions", + "tableTo": "platform_human_sessions", + "columnsFrom": ["human_session_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_auth_attempts": { + "name": "platform_auth_attempts", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "revision": { + "name": "revision", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "generation": { + "name": "generation", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "purpose": { + "name": "purpose", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "browser_hash": { + "name": "browser_hash", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "context": { + "name": "context", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "platform_auth_attempts_expiry": { + "name": "platform_auth_attempts_expiry", + "columns": [ + { + "expression": "expires_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "platform_auth_attempts_connection_id_platform_login_connections_id_fk": { + "name": "platform_auth_attempts_connection_id_platform_login_connections_id_fk", + "tableFrom": "platform_auth_attempts", + "tableTo": "platform_login_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_auth_bootstrap": { + "name": "platform_auth_bootstrap", + "schema": "", + "columns": { + "singleton": { + "name": "singleton", + "type": "boolean", + "primaryKey": true, + "notNull": true, + "default": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "credential_hash": { + "name": "credential_hash", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "request_hash": { + "name": "request_hash", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "''" + }, + "claim_hash": { + "name": "claim_hash", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "pending_identity": { + "name": "pending_identity", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + }, + "consumed_at": { + "name": "consumed_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + } + }, + "indexes": {}, + "foreignKeys": { + "platform_auth_bootstrap_connection_id_platform_login_connections_id_fk": { + "name": "platform_auth_bootstrap_connection_id_platform_login_connections_id_fk", + "tableFrom": "platform_auth_bootstrap", + "tableTo": "platform_login_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "platform_auth_bootstrap_singleton": { + "name": "platform_auth_bootstrap_singleton", + "value": "\"platform_auth_bootstrap\".\"singleton\" = true" + } + }, + "isRLSEnabled": false + }, + "public.platform_auth_settings": { + "name": "platform_auth_settings", + "schema": "", + "columns": { + "singleton": { + "name": "singleton", + "type": "boolean", + "primaryKey": true, + "notNull": true, + "default": true + }, + "revision": { + "name": "revision", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + }, + "admission": { + "name": "admission", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "protection": { + "name": "protection", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "session_seconds": { + "name": "session_seconds", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 2592000 + }, + "sessions_required": { + "name": "sessions_required", + "type": "boolean", + "primaryKey": false, + "notNull": true, + "default": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "platform_auth_settings_singleton": { + "name": "platform_auth_settings_singleton", + "value": "\"platform_auth_settings\".\"singleton\" = true" + }, + "platform_auth_settings_revision": { + "name": "platform_auth_settings_revision", + "value": "\"platform_auth_settings\".\"revision\" > 0" + }, + "platform_auth_settings_session_seconds": { + "name": "platform_auth_settings_session_seconds", + "value": "\"platform_auth_settings\".\"session_seconds\" BETWEEN 300 AND 2592000" + } + }, + "isRLSEnabled": false + }, + "public.platform_company_identities": { + "name": "platform_company_identities", + "schema": "", + "columns": { + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "issuer": { + "name": "issuer", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "subject": { + "name": "subject", + "type": "text", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "platform_company_identity_user": { + "name": "platform_company_identity_user", + "columns": [ + { + "expression": "issuer", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "platform_company_identities_user_id_users_id_fk": { + "name": "platform_company_identities_user_id_users_id_fk", + "tableFrom": "platform_company_identities", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": { + "platform_company_identities_issuer_subject_pk": { + "name": "platform_company_identities_issuer_subject_pk", + "columns": ["issuer", "subject"] + } + }, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_events": { + "name": "platform_events", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "batch_id": { + "name": "batch_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "action": { + "name": "action", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "worker_name": { + "name": "worker_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "environment": { + "name": "environment", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "version_id": { + "name": "version_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "script_name": { + "name": "script_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "error_message": { + "name": "error_message", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "admin_user_id": { + "name": "admin_user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "admin_login": { + "name": "admin_login", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_platform_events_batch_id": { + "name": "idx_platform_events_batch_id", + "columns": [ + { + "expression": "batch_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_platform_events_env_created": { + "name": "idx_platform_events_env_created", + "columns": [ + { + "expression": "environment", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_human_sessions": { + "name": "platform_human_sessions", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "generation": { + "name": "generation", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "audience": { + "name": "audience", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "access_issuer": { + "name": "access_issuer", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "access_subject": { + "name": "access_subject", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + }, + "revoked_at": { + "name": "revoked_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "platform_human_sessions_connection": { + "name": "platform_human_sessions_connection", + "columns": [ + { + "expression": "connection_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "platform_human_sessions_user": { + "name": "platform_human_sessions_user", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "platform_human_sessions_expiry": { + "name": "platform_human_sessions_expiry", + "columns": [ + { + "expression": "expires_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "platform_human_sessions_user_id_users_id_fk": { + "name": "platform_human_sessions_user_id_users_id_fk", + "tableFrom": "platform_human_sessions", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "platform_human_sessions_connection_id_platform_login_connections_id_fk": { + "name": "platform_human_sessions_connection_id_platform_login_connections_id_fk", + "tableFrom": "platform_human_sessions", + "tableTo": "platform_login_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "platform_human_sessions_audience": { + "name": "platform_human_sessions_audience", + "value": "\"platform_human_sessions\".\"audience\" IN ('api', 'admin')" + }, + "platform_human_sessions_access_identity": { + "name": "platform_human_sessions_access_identity", + "value": "(\"platform_human_sessions\".\"access_issuer\" IS NULL) = (\"platform_human_sessions\".\"access_subject\" IS NULL)" + } + }, + "isRLSEnabled": false + }, + "public.platform_login_connections": { + "name": "platform_login_connections", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "kind": { + "name": "kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "enabled": { + "name": "enabled", + "type": "boolean", + "primaryKey": false, + "notNull": true, + "default": false + }, + "active_revision": { + "name": "active_revision", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "revision": { + "name": "revision", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + }, + "generation": { + "name": "generation", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "platform_login_connections_kind": { + "name": "platform_login_connections_kind", + "value": "\"platform_login_connections\".\"kind\" IN ('github', 'google', 'oidc', 'cloudflare-access')" + }, + "platform_login_connections_revision": { + "name": "platform_login_connections_revision", + "value": "\"platform_login_connections\".\"revision\" > 0 AND \"platform_login_connections\".\"generation\" > 0" + }, + "platform_login_connections_active_revision": { + "name": "platform_login_connections_active_revision", + "value": "\"platform_login_connections\".\"active_revision\" IS NULL OR \"platform_login_connections\".\"active_revision\" BETWEEN 1 AND \"platform_login_connections\".\"revision\"" + }, + "platform_login_connections_enabled": { + "name": "platform_login_connections_enabled", + "value": "NOT \"platform_login_connections\".\"enabled\" OR \"platform_login_connections\".\"active_revision\" IS NOT NULL" + } + }, + "isRLSEnabled": false + }, + "public.platform_login_identities": { + "name": "platform_login_identities", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "issuer": { + "name": "issuer", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "subject": { + "name": "subject", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "last_authenticated_at": { + "name": "last_authenticated_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "platform_login_identity_subject": { + "name": "platform_login_identity_subject", + "columns": [ + { + "expression": "connection_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "issuer", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "subject", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "platform_login_identity_user": { + "name": "platform_login_identity_user", + "columns": [ + { + "expression": "connection_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "platform_login_identities_user_id_users_id_fk": { + "name": "platform_login_identities_user_id_users_id_fk", + "tableFrom": "platform_login_identities", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "platform_login_identities_connection_id_platform_login_connections_id_fk": { + "name": "platform_login_identities_connection_id_platform_login_connections_id_fk", + "tableFrom": "platform_login_identities", + "tableTo": "platform_login_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_login_revisions": { + "name": "platform_login_revisions", + "schema": "", + "columns": { + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "revision": { + "name": "revision", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "configuration": { + "name": "configuration", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "secret": { + "name": "secret", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": { + "platform_login_revisions_connection_id_platform_login_connections_id_fk": { + "name": "platform_login_revisions_connection_id_platform_login_connections_id_fk", + "tableFrom": "platform_login_revisions", + "tableTo": "platform_login_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": { + "platform_login_revisions_connection_id_revision_pk": { + "name": "platform_login_revisions_connection_id_revision_pk", + "columns": ["connection_id", "revision"] + } + }, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_login_tests": { + "name": "platform_login_tests", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "revision": { + "name": "revision", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "issuer": { + "name": "issuer", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "subject": { + "name": "subject", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "login": { + "name": "login", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "''" + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "platform_login_tests_expiry": { + "name": "platform_login_tests_expiry", + "columns": [ + { + "expression": "expires_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "platform_login_tests_user_id_users_id_fk": { + "name": "platform_login_tests_user_id_users_id_fk", + "tableFrom": "platform_login_tests", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "platform_login_tests_connection_id_platform_login_connections_id_fk": { + "name": "platform_login_tests_connection_id_platform_login_connections_id_fk", + "tableFrom": "platform_login_tests", + "tableTo": "platform_login_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.platform_settings": { + "name": "platform_settings", + "schema": "", + "columns": { + "key": { + "name": "key", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "value": { + "name": "value", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.project_database_credentials": { + "name": "project_database_credentials", + "schema": "", + "columns": { + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "ciphertext": { + "name": "ciphertext", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "iv": { + "name": "iv", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "key_version": { + "name": "key_version", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": { + "project_database_credentials_project_id_projects_id_fk": { + "name": "project_database_credentials_project_id_projects_id_fk", + "tableFrom": "project_database_credentials", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.project_deploy_credentials": { + "name": "project_deploy_credentials", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "issued_by": { + "name": "issued_by", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "name": { + "name": "name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + }, + "revoked_at": { + "name": "revoked_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "project_deploy_credentials_project": { + "name": "project_deploy_credentials_project", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "project_deploy_credentials_expiry": { + "name": "project_deploy_credentials_expiry", + "columns": [ + { + "expression": "expires_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "project_deploy_credentials_project_id_projects_id_fk": { + "name": "project_deploy_credentials_project_id_projects_id_fk", + "tableFrom": "project_deploy_credentials", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "project_deploy_credentials_issued_by_users_id_fk": { + "name": "project_deploy_credentials_issued_by_users_id_fk", + "tableFrom": "project_deploy_credentials", + "tableTo": "users", + "columnsFrom": ["issued_by"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "project_deploy_credentials_name": { + "name": "project_deploy_credentials_name", + "value": "length(\"project_deploy_credentials\".\"name\") BETWEEN 1 AND 80" + } + }, + "isRLSEnabled": false + }, + "public.project_migrations": { + "name": "project_migrations", + "schema": "", + "columns": { + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "name": { + "name": "name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "applied_at": { + "name": "applied_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "source_deployment_id": { + "name": "source_deployment_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_project_migrations_project_id": { + "name": "idx_project_migrations_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "applied_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "project_migrations_project_id_projects_id_fk": { + "name": "project_migrations_project_id_projects_id_fk", + "tableFrom": "project_migrations", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + }, + "project_migrations_source_deployment_id_deployments_id_fk": { + "name": "project_migrations_source_deployment_id_deployments_id_fk", + "tableFrom": "project_migrations", + "tableTo": "deployments", + "columnsFrom": ["source_deployment_id"], + "columnsTo": ["id"], + "onDelete": "set null", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": { + "project_migrations_project_id_name_pk": { + "name": "project_migrations_project_id_name_pk", + "columns": ["project_id", "name"] + } + }, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.project_secrets": { + "name": "project_secrets", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "name": { + "name": "name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "ciphertext": { + "name": "ciphertext", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "iv": { + "name": "iv", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "key_version": { + "name": "key_version", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "managed_reason": { + "name": "managed_reason", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_project_secrets_project_id": { + "name": "idx_project_secrets_project_id", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "project_secrets_project_id_projects_id_fk": { + "name": "project_secrets_project_id_projects_id_fk", + "tableFrom": "project_secrets", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "project_secrets_project_id_name_unique": { + "name": "project_secrets_project_id_name_unique", + "nullsNotDistinct": false, + "columns": ["project_id", "name"] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.projects": { + "name": "projects", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "slug": { + "name": "slug", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "mode": { + "name": "mode", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'worker'" + }, + "active_deployment_id": { + "name": "active_deployment_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "websocket_version": { + "name": "websocket_version", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'active'" + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_projects_slug": { + "name": "idx_projects_slug", + "columns": [ + { + "expression": "slug", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_projects_user_id": { + "name": "idx_projects_user_id", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "projects_user_id_users_id_fk": { + "name": "projects_user_id_users_id_fk", + "tableFrom": "projects", + "tableTo": "users", + "columnsFrom": ["user_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "projects_user_id_slug_unique": { + "name": "projects_user_id_slug_unique", + "nullsNotDistinct": false, + "columns": ["user_id", "slug"] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.resources": { + "name": "resources", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "type": { + "name": "type", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "cf_id": { + "name": "cf_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "binding_name": { + "name": "binding_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "metadata": { + "name": "metadata", + "type": "jsonb", + "primaryKey": false, + "notNull": true, + "default": "'{}'::jsonb" + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": { + "resources_project_id_projects_id_fk": { + "name": "resources_project_id_projects_id_fk", + "tableFrom": "resources", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "resources_project_id_type_binding_name_unique": { + "name": "resources_project_id_type_binding_name_unique", + "nullsNotDistinct": false, + "columns": ["project_id", "type", "binding_name"] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.sandbox_drain_checkpoints": { + "name": "sandbox_drain_checkpoints", + "schema": "", + "columns": { + "singleton": { + "name": "singleton", + "type": "boolean", + "primaryKey": true, + "notNull": true + }, + "admission_protocol": { + "name": "admission_protocol", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "generation": { + "name": "generation", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "state": { + "name": "state", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "phase": { + "name": "phase", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "cursor": { + "name": "cursor", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "lease_owner": { + "name": "lease_owner", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "lease_expires_at": { + "name": "lease_expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "started_at": { + "name": "started_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "completed_at": { + "name": "completed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.users": { + "name": "users", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "provider": { + "name": "provider", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'github'" + }, + "provider_id": { + "name": "provider_id", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "''" + }, + "login": { + "name": "login", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "''" + }, + "email": { + "name": "email", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "plan": { + "name": "plan", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'free'" + }, + "role": { + "name": "role", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'user'" + }, + "billing_cycle_start": { + "name": "billing_cycle_start", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "suspended_reason": { + "name": "suspended_reason", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_users_provider_id": { + "name": "idx_users_provider_id", + "columns": [ + { + "expression": "provider", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "provider_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_users_email": { + "name": "idx_users_email", + "columns": [ + { + "expression": "email", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_cache_outbox": { + "name": "email_cache_outbox", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "resource_kind": { + "name": "resource_kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "resource_id": { + "name": "resource_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "version": { + "name": "version", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "payload": { + "name": "payload", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "published_at": { + "name": "published_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "email_cache_outbox_version_uq": { + "name": "email_cache_outbox_version_uq", + "columns": [ + { + "expression": "resource_kind", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "resource_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "version", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_cache_outbox_pending_idx": { + "name": "email_cache_outbox_pending_idx", + "columns": [ + { + "expression": "published_at", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_credentials": { + "name": "email_credentials", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "managed_by": { + "name": "managed_by", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "manager_user_id": { + "name": "manager_user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "kind": { + "name": "kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "account_id": { + "name": "account_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "zone_id": { + "name": "zone_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "ciphertext": { + "name": "ciphertext", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "iv": { + "name": "iv", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "key_version": { + "name": "key_version", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "token_id": { + "name": "token_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "expires_on": { + "name": "expires_on", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "generation": { + "name": "generation", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'healthy'" + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "email_credentials_scope_idx": { + "name": "email_credentials_scope_idx", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "account_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "zone_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "email_credentials_material_check": { + "name": "email_credentials_material_check", + "value": "(\"email_credentials\".\"kind\" = 'platform' AND \"email_credentials\".\"ciphertext\" IS NULL AND \"email_credentials\".\"iv\" IS NULL AND \"email_credentials\".\"key_version\" IS NULL) OR (\"email_credentials\".\"kind\" = 'api_token' AND \"email_credentials\".\"ciphertext\" IS NOT NULL AND \"email_credentials\".\"iv\" IS NOT NULL AND \"email_credentials\".\"key_version\" IS NOT NULL)" + } + }, + "isRLSEnabled": false + }, + "public.email_domain_routes": { + "name": "email_domain_routes", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "domain": { + "name": "domain", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "addressing": { + "name": "addressing", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "managed_by": { + "name": "managed_by", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "assigned_by_user_id": { + "name": "assigned_by_user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "desired_state": { + "name": "desired_state", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'active'" + }, + "inbound_status": { + "name": "inbound_status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "inbound_reason": { + "name": "inbound_reason", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "inbound_observed_at": { + "name": "inbound_observed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "outbound_status": { + "name": "outbound_status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "outbound_reason": { + "name": "outbound_reason", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "outbound_observed_at": { + "name": "outbound_observed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "desired_generation": { + "name": "desired_generation", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "email_domain_routes_domain_uq": { + "name": "email_domain_routes_domain_uq", + "columns": [ + { + "expression": "domain", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_domain_routes_connection_idx": { + "name": "email_domain_routes_connection_idx", + "columns": [ + { + "expression": "connection_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_domain_routes_project_idx": { + "name": "email_domain_routes_project_idx", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_domain_routes_connection_id_email_zone_connections_id_fk": { + "name": "email_domain_routes_connection_id_email_zone_connections_id_fk", + "tableFrom": "email_domain_routes", + "tableTo": "email_zone_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "email_domain_routes_assignment_check": { + "name": "email_domain_routes_assignment_check", + "value": "(\"email_domain_routes\".\"addressing\" = 'custom' AND \"email_domain_routes\".\"project_id\" IS NOT NULL) OR (\"email_domain_routes\".\"addressing\" = 'shared' AND \"email_domain_routes\".\"project_id\" IS NULL)" + } + }, + "isRLSEnabled": false + }, + "public.email_operation_steps": { + "name": "email_operation_steps", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "operation_id": { + "name": "operation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "ordinal": { + "name": "ordinal", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "kind": { + "name": "kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "resource_identity": { + "name": "resource_identity", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "request_digest": { + "name": "request_digest", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "attempt": { + "name": "attempt", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "outcome": { + "name": "outcome", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "failure_code": { + "name": "failure_code", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "failure_detail": { + "name": "failure_detail", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "started_at": { + "name": "started_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "finished_at": { + "name": "finished_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + } + }, + "indexes": { + "email_operation_steps_order_uq": { + "name": "email_operation_steps_order_uq", + "columns": [ + { + "expression": "operation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "ordinal", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_operation_steps_operation_id_email_operations_id_fk": { + "name": "email_operation_steps_operation_id_email_operations_id_fk", + "tableFrom": "email_operation_steps", + "tableTo": "email_operations", + "columnsFrom": ["operation_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_operations": { + "name": "email_operations", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "connection_id": { + "name": "connection_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "route_id": { + "name": "route_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "actor_kind": { + "name": "actor_kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "actor_user_id": { + "name": "actor_user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "actor_scope": { + "name": "actor_scope", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "kind": { + "name": "kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "idempotency_key": { + "name": "idempotency_key", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "request_digest": { + "name": "request_digest", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "desired_generation": { + "name": "desired_generation", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "current_step": { + "name": "current_step", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "failure_code": { + "name": "failure_code", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "failure_detail": { + "name": "failure_detail", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "email_operations_key_uq": { + "name": "email_operations_key_uq", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "actor_scope", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "idempotency_key", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_operations_work_idx": { + "name": "email_operations_work_idx", + "columns": [ + { + "expression": "status", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "updated_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_operations_connection_idx": { + "name": "email_operations_connection_idx", + "columns": [ + { + "expression": "connection_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_operations_connection_id_email_zone_connections_id_fk": { + "name": "email_operations_connection_id_email_zone_connections_id_fk", + "tableFrom": "email_operations", + "tableTo": "email_zone_connections", + "columnsFrom": ["connection_id"], + "columnsTo": ["id"], + "onDelete": "no action", + "onUpdate": "no action" + }, + "email_operations_route_id_email_domain_routes_id_fk": { + "name": "email_operations_route_id_email_domain_routes_id_fk", + "tableFrom": "email_operations", + "tableTo": "email_domain_routes", + "columnsFrom": ["route_id"], + "columnsTo": ["id"], + "onDelete": "set null", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_zone_connections": { + "name": "email_zone_connections", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "installation_id": { + "name": "installation_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "account_id": { + "name": "account_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "zone_id": { + "name": "zone_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "zone_name": { + "name": "zone_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "managed_by": { + "name": "managed_by", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "manager_user_id": { + "name": "manager_user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "credential_id": { + "name": "credential_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "ingress_worker_name": { + "name": "ingress_worker_name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "ingress_version": { + "name": "ingress_version", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "desired_generation": { + "name": "desired_generation", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + }, + "active_secret_generation": { + "name": "active_secret_generation", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "staged_secret_generation": { + "name": "staged_secret_generation", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "secret_ciphertext": { + "name": "secret_ciphertext", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "secret_iv": { + "name": "secret_iv", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "secret_key_version": { + "name": "secret_key_version", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "staged_secret_ciphertext": { + "name": "staged_secret_ciphertext", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "staged_secret_iv": { + "name": "staged_secret_iv", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "staged_secret_key_version": { + "name": "staged_secret_key_version", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "previous_secret_hash": { + "name": "previous_secret_hash", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "previous_secret_until": { + "name": "previous_secret_until", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "inbound_status": { + "name": "inbound_status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "inbound_reason": { + "name": "inbound_reason", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "inbound_observed_at": { + "name": "inbound_observed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "management_status": { + "name": "management_status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'probe_failed'" + }, + "management_reason": { + "name": "management_reason", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "management_observed_at": { + "name": "management_observed_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "email_zone_connections_zone_uq": { + "name": "email_zone_connections_zone_uq", + "columns": [ + { + "expression": "installation_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "account_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "zone_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_zone_connections_ingress_uq": { + "name": "email_zone_connections_ingress_uq", + "columns": [ + { + "expression": "account_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "ingress_worker_name", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + }, + "email_zone_connections_manager_idx": { + "name": "email_zone_connections_manager_idx", + "columns": [ + { + "expression": "manager_user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "email_zone_connections_manager_check": { + "name": "email_zone_connections_manager_check", + "value": "(\"email_zone_connections\".\"managed_by\" = 'owner' AND \"email_zone_connections\".\"manager_user_id\" IS NOT NULL) OR (\"email_zone_connections\".\"managed_by\" = 'admin')" + } + }, + "isRLSEnabled": false + }, + "public.email_action_recipients": { + "name": "email_action_recipients", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "action_id": { + "name": "action_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "recipient": { + "name": "recipient", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "state": { + "name": "state", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "error_code": { + "name": "error_code", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "provider_reference": { + "name": "provider_reference", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "reserved_at": { + "name": "reserved_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "attempt_started_at": { + "name": "attempt_started_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "completed_at": { + "name": "completed_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + } + }, + "indexes": { + "idx_email_action_recipients_project_reserved": { + "name": "idx_email_action_recipients_project_reserved", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "reserved_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_action_recipients_action_id_email_actions_id_fk": { + "name": "email_action_recipients_action_id_email_actions_id_fk", + "tableFrom": "email_action_recipients", + "tableTo": "email_actions", + "columnsFrom": ["action_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "email_action_recipients_action_recipient_uq": { + "name": "email_action_recipients_action_recipient_uq", + "nullsNotDistinct": false, + "columns": ["action_id", "recipient"] + } + }, + "policies": {}, + "checkConstraints": { + "email_action_recipients_state_check": { + "name": "email_action_recipients_state_check", + "value": "\"email_action_recipients\".\"state\" IN ('rejected', 'reserved', 'attempt_started', 'provider_accepted', 'failed', 'outcome_unknown', 'cancelled')" + } + }, + "isRLSEnabled": false + }, + "public.email_actions": { + "name": "email_actions", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "sender_domain": { + "name": "sender_domain", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "receipt_id": { + "name": "receipt_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "kind": { + "name": "kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "idempotency_key": { + "name": "idempotency_key", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "payload_digest": { + "name": "payload_digest", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "transport": { + "name": "transport", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "policy_version": { + "name": "policy_version", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_email_actions_project_created": { + "name": "idx_email_actions_project_created", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "email_actions_receipt_id_email_receipts_id_fk": { + "name": "email_actions_receipt_id_email_receipts_id_fk", + "tableFrom": "email_actions", + "tableTo": "email_receipts", + "columnsFrom": ["receipt_id"], + "columnsTo": ["id"], + "onDelete": "set null", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "email_actions_project_key_uq": { + "name": "email_actions_project_key_uq", + "nullsNotDistinct": false, + "columns": ["project_id", "idempotency_key"] + } + }, + "policies": {}, + "checkConstraints": { + "email_actions_kind_check": { + "name": "email_actions_kind_check", + "value": "\"email_actions\".\"kind\" IN ('direct', 'forward', 'reply')" + } + }, + "isRLSEnabled": false + }, + "public.email_monthly_usage": { + "name": "email_monthly_usage", + "schema": "", + "columns": { + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "month": { + "name": "month", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "recipient_attempts": { + "name": "recipient_attempts", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "email_monthly_usage_project_month_uq": { + "name": "email_monthly_usage_project_month_uq", + "nullsNotDistinct": false, + "columns": ["project_id", "month"] + } + }, + "policies": {}, + "checkConstraints": { + "email_monthly_usage_nonnegative_check": { + "name": "email_monthly_usage_nonnegative_check", + "value": "\"email_monthly_usage\".\"recipient_attempts\" >= 0" + } + }, + "isRLSEnabled": false + }, + "public.email_project_controls": { + "name": "email_project_controls", + "schema": "", + "columns": { + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "monthly_limit": { + "name": "monthly_limit", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 200 + }, + "burst_limit": { + "name": "burst_limit", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 10 + }, + "suspended_at": { + "name": "suspended_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "version": { + "name": "version", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 1 + } + }, + "indexes": {}, + "foreignKeys": { + "email_project_controls_project_id_projects_id_fk": { + "name": "email_project_controls_project_id_projects_id_fk", + "tableFrom": "email_project_controls", + "tableTo": "projects", + "columnsFrom": ["project_id"], + "columnsTo": ["id"], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_receipts": { + "name": "email_receipts", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'received'" + }, + "payload_digest": { + "name": "payload_digest", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "final_reject": { + "name": "final_reject", + "type": "boolean", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_email_receipts_project_created": { + "name": "idx_email_receipts_project_created", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.email_unresolved_attempts": { + "name": "email_unresolved_attempts", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "project_id": { + "name": "project_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "sender_domain": { + "name": "sender_domain", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "started_at": { + "name": "started_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "idx_email_unresolved_attempts_project": { + "name": "idx_email_unresolved_attempts_project", + "columns": [ + { + "expression": "project_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "idx_email_unresolved_attempts_domain": { + "name": "idx_email_unresolved_attempts_domain", + "columns": [ + { + "expression": "sender_domain", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + } + }, + "enums": {}, + "schemas": {}, + "sequences": {}, + "roles": {}, + "policies": {}, + "views": {}, + "_meta": { + "columns": {}, + "schemas": {}, + "tables": {} + } +} diff --git a/platform/packages/api/drizzle/meta/_journal.json b/platform/packages/api/drizzle/meta/_journal.json index 6ab553c3f..ebe0e9d36 100644 --- a/platform/packages/api/drizzle/meta/_journal.json +++ b/platform/packages/api/drizzle/meta/_journal.json @@ -281,6 +281,13 @@ "when": 1789733775150, "tag": "0046_email_domains_platform_credential", "breakpoints": true + }, + { + "idx": 47, + "version": "7", + "when": 1789749117331, + "tag": "0047_email_gateway", + "breakpoints": true } ] } diff --git a/platform/packages/api/src/admin/platform-workers.ts b/platform/packages/api/src/admin/platform-workers.ts index 4d8bf77e4..fae494a09 100644 --- a/platform/packages/api/src/admin/platform-workers.ts +++ b/platform/packages/api/src/admin/platform-workers.ts @@ -1,4 +1,10 @@ -export type PlatformWorkerName = 'proxy' | 'tail' | 'api' | 'dashboard' | 'dispatch'; +export type PlatformWorkerName = + | 'proxy' + | 'email-gateway' + | 'tail' + | 'api' + | 'dashboard' + | 'dispatch'; type PlatformWorkerDef = Readonly<{ name: PlatformWorkerName; @@ -21,6 +27,13 @@ const WORKER_DEFS: ReadonlyArray = [ dependsOn: [], deployOrder: 1, }, + { + name: 'email-gateway', + prodScript: 'void-email-gateway', + stagingScript: 'void-email-gateway-staging', + dependsOn: ['api'], + deployOrder: 4, + }, { name: 'tail', prodScript: 'void-tail', diff --git a/platform/packages/api/src/admin/routes/email.tsx b/platform/packages/api/src/admin/routes/email.tsx index 8ee3b54b5..24a1c1a15 100644 --- a/platform/packages/api/src/admin/routes/email.tsx +++ b/platform/packages/api/src/admin/routes/email.tsx @@ -1,4 +1,4 @@ -import { asc, eq, sql } from 'drizzle-orm'; +import { asc, eq, gte, inArray, sql } from 'drizzle-orm'; import { Hono, type Context } from 'hono'; import { getPlatformCapabilities } from '../../capabilities.ts'; import { @@ -8,18 +8,21 @@ import { getProject, } from '../../db.ts'; import { - refreshOauthGrantSerialized, - revokeOauthGrantSerialized, - withEmailDomainRowLock, -} from '../../email/credential-lease.ts'; -import { addEmailDomainForProject } from '../../email/domain-service.ts'; + emailActionRecipients, + emailProjectControls, + emailReceipts, +} from '../../email/admission-schema.ts'; +import { setProjectEmailLimits, setProjectEmailSuspended } from '../../email/admission.ts'; import { - clearEmailDomainMirror, - decryptEmailDomainRelaySecret, - decryptEmailDomainToken, - hashEmailRelaySecret, - writeEmailDomainMirror, -} from '../../email/domains.ts'; + emailDomainRoutes, + emailZoneConnections, + emailCredentials, +} from '../../email/connection-schema.ts'; +import { + addEmailDomainForProject, + removeEmailDomainForProject, + rotateEmailIngressSecretForProject, +} from '../../email/domain-service.ts'; import { DEFAULT_EMAIL_BURST_LIMIT as DEFAULT_BURST_LIMIT, DEFAULT_EMAIL_MONTHLY_LIMIT as DEFAULT_MONTHLY_LIMIT, @@ -28,7 +31,6 @@ import { emailSuspendKey as suspendKey, parseEmailLimit as parseLimit, } from '../../email/limits.ts'; -import { removeEmailDomain } from '../../email/relay-engine.ts'; import { getEmailDomainManagement, getEmailRecipientPolicy, @@ -43,7 +45,6 @@ import { syncProjectAllowlistKvBestEffort, } from '../../provisioning/email-allowlist.ts'; import { deleteDestination } from '../../provisioning/email-routing.ts'; -import { emailDomains } from '../../schema.ts'; import { renderOperationError } from '../operation-error.tsx'; import { EmailSettingsPage } from '../views/email-settings.tsx'; import { STATUS_COLORS, formatDateTime } from '../views/format.ts'; @@ -141,28 +142,66 @@ app.get('/:projectId', async (context) => { } const month = monthBucket(); - const [sent, received, suspended, monthlyOverride, burstOverride, destinations, domains] = - await Promise.all([ - context.env.ROUTING.get(sentKey(projectId, month)), - context.env.ROUTING.get(recvKey(projectId, month)), - context.env.ROUTING.get(suspendKey(projectId)), - context.env.ROUTING.get(monthlyLimitKey(projectId)), - context.env.ROUTING.get(burstLimitKey(projectId)), - getEmailDestinationsByProjectId(context.get('db'), projectId), - context - .get('db') - .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)) - .orderBy(asc(emailDomains.created_at)), - ]); + const monthStart = `${month}-01T00:00:00.000Z`; + const [sentRows, receivedRows, controls, destinations, domainRows] = await Promise.all([ + context + .get('db') + .select({ count: sql`count(*)::int` }) + .from(emailActionRecipients) + .where( + sql`${emailActionRecipients.project_id} = ${projectId} AND ${emailActionRecipients.state} IN ('reserved','attempt_started','provider_accepted','failed','outcome_unknown') AND ${emailActionRecipients.reserved_at} >= ${monthStart}::timestamptz`, + ), + context + .get('db') + .select({ count: sql`count(*)::int` }) + .from(emailReceipts) + .where( + sql`${emailReceipts.project_id} = ${projectId} AND ${emailReceipts.created_at} >= ${monthStart}::timestamptz`, + ), + context + .get('db') + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + .limit(1), + getEmailDestinationsByProjectId(context.get('db'), projectId), + context + .get('db') + .select({ + route: emailDomainRoutes, + connection: emailZoneConnections, + credential: emailCredentials, + }) + .from(emailDomainRoutes) + .innerJoin(emailZoneConnections, eq(emailDomainRoutes.connection_id, emailZoneConnections.id)) + .leftJoin(emailCredentials, eq(emailZoneConnections.credential_id, emailCredentials.id)) + .where(eq(emailDomainRoutes.project_id, projectId)) + .orderBy(asc(emailDomainRoutes.created_at)), + ]); + const sent = sentRows[0]?.count ?? 0; + const received = receivedRows[0]?.count ?? 0; // Distinguish an override from the default so an operator can see at a // glance whether someone bumped a cap during a past incident — the // override keys are write-only otherwise. - const monthlyLimit = parseLimit(monthlyOverride); - const burstLimit = parseLimit(burstOverride); - const isSuspended = suspended !== null; + const control = controls[0]; + const monthlyLimit = + control && control.monthly_limit !== DEFAULT_MONTHLY_LIMIT ? control.monthly_limit : undefined; + const burstLimit = + control && control.burst_limit !== DEFAULT_BURST_LIMIT ? control.burst_limit : undefined; + const isSuspended = Boolean(control?.suspended_at); + const domains = domainRows.map(({ route, connection, credential }) => ({ + id: route.id, + domain: route.domain, + status: route.inbound_status, + managed_by: route.managed_by, + credential_kind: credential?.kind ?? 'platform', + mode: route.addressing, + relay_worker_name: connection.ingress_worker_name, + relay_version: connection.ingress_version, + token_id: credential?.token_id ?? null, + token_expires_on: credential?.expires_on ?? null, + })); const senderDomain = context.env.EMAIL_SENDER_DOMAIN; const tz = (context.req.raw.cf?.timezone as string | undefined) ?? undefined; @@ -207,13 +246,13 @@ app.get('/:projectId', async (context) => { Outbound (sent) - {parseCounter(sent)} / {monthlyLimit ?? DEFAULT_MONTHLY_LIMIT}{' '} + {sent} / {monthlyLimit ?? DEFAULT_MONTHLY_LIMIT}{' '} ({monthlyLimit === undefined ? 'default' : 'override'}) Inbound (received) - {parseCounter(received)} + {received} Burst cap @@ -225,8 +264,7 @@ app.get('/:projectId', async (context) => {

- Counters live in ROUTING KV and are written by the proxy worker. The monthly - buckets expire shortly after the month ends; there is no historical series here. + Recipient submission attempts and inbound receipts are recorded in the platform database.

Controls

@@ -256,27 +294,6 @@ app.get('/:projectId', async (context) => { Per-minute cap. Submit blank to drop the override. -

Danger Zone

- {/* Keep apostrophes out of the `onsubmit` text: oxfmt decodes `'` - back to a bare quote, which closes the handler's string literal. */} -
- {/* The typed slug is the real confirmation: it is checked on the server, - so the counter cannot be zeroed by a stray POST that never rendered - (or ever ran) the browser dialog above. */} - - {' '} - - Type {project.slug} to confirm. - -
-

Verified destinations ({destinations.length})

Recipient addresses this project is allowed to send to. A pending row is @@ -340,17 +357,9 @@ app.get('/:projectId', async (context) => {

Custom domains ({domains.length})

- Sender/recipient domains on a Cloudflare zone, registered by the project owner through{' '} - void email domain add or by an administrator below (the row then runs on the - platform's own credential and the zone must be in the platform's account — paste a token for - a zone elsewhere). Revoke clears the email-domain: ROUTING mirror FIRST — the - proxy trusts only that key, and a failed clear keeps the row so the retry can finish — then - deletes the relay worker and catch-all rule in the customer's account best-effort (a - stranded relay is inert without the mirror entry) and drops the row. For{' '} - oauth_grant rows, revoke grant is the lighter escape hatch: it kills just the - customer's OAuth grant at Cloudflare and flips the row to token_revoked, - leaving the row and mirror in place. The customer's credential and the relay secret are - never shown here. + Exact sender and recipient domains on a Cloudflare zone. One connection owns the ingress + Worker and catch-all; removing an assignment keeps shared resources while sibling domains + use them. The platform stores connection credentials and never shows them here.

{ {domain.token_expires_on ? formatDateTime(domain.token_expires_on, tz) : '-'} + + +
{/* Keep apostrophes out of the `onsubmit` text (see the Danger Zone note above); the typed slug is the real confirmation and is checked on the server. */}
{ revoke
- {/* OAuth rows only: kill just the customer's grant (the row - and mirror stay). API tokens are the customer's own — the - route refuses those and points at dash.cloudflare.com. */} - {domain.credential_kind === 'oauth_grant' ? ( -
- -
- ) : null} ))} @@ -538,9 +537,9 @@ app.post('/:projectId/suspend', async (context) => { const body = await context.req.parseBody(); const desired = body.state; if (desired === 'suspended') { - await context.env.ROUTING.put(suspendKey(projectId), new Date().toISOString()); + await setProjectEmailSuspended(context.get('db'), projectId, true); } else if (desired === 'active') { - await context.env.ROUTING.delete(suspendKey(projectId)); + await setProjectEmailSuspended(context.get('db'), projectId, false); } else { return context.html('

Invalid state

Expected "suspended" or "active".

', 400); } @@ -549,30 +548,12 @@ app.post('/:projectId/suspend', async (context) => { // POST /email/:projectId/limit — set (or clear) the monthly outbound override app.post('/:projectId/limit', async (context) => { - return setLimit(context, context.req.param('projectId'), monthlyLimitKey, 'limit'); + return setLimit(context, context.req.param('projectId'), 'monthly', 'limit'); }); // POST /email/:projectId/burst-limit — set (or clear) the per-minute override app.post('/:projectId/burst-limit', async (context) => { - return setLimit(context, context.req.param('projectId'), burstLimitKey, 'burstLimit'); -}); - -// POST /email/:projectId/reset-counter — zero this month's outbound counter -app.post('/:projectId/reset-counter', async (context) => { - const projectId = context.req.param('projectId'); - const project = await getProject(context.get('db'), projectId); - if (!project) { - return context.html('

Project not found

', 404); - } - const body = await context.req.parseBody(); - if (body.confirm !== project.slug) { - return context.html( - `

Not confirmed

Type the project slug (${project.slug}) to reset the counter.

`, - 400, - ); - } - await context.env.ROUTING.delete(sentKey(projectId, monthBucket())); - return context.redirect(`/admin/email/${projectId}`); + return setLimit(context, context.req.param('projectId'), 'burst', 'burstLimit'); }); // POST /email/:projectId/destinations/:destId/delete — revoke one recipient @@ -640,278 +621,45 @@ app.post('/:projectId/destinations/:destId/delete', async (context) => { return context.redirect(`/admin/email/${projectId}`); }); -// POST /email/:projectId/domains/:domain/revoke — operator revoke of a custom -// email domain: clear the proxy's mirror key, best-effort CF cleanup in the -// customer's account via the relay engine, then the row. The owner-facing -// twin is DELETE /projects/:id/email/domains/:domain in `routes/email.ts`. +// An administrator removes one exact assignment through the same durable +// operation service as the owner API. Sibling routes keep their shared ingress. app.post('/:projectId/domains/:domain/revoke', async (context) => { const projectId = context.req.param('projectId'); const project = await getProject(context.get('db'), projectId); if (!project) { return context.html('

Project not found

', 404); } - const domain = context.req.param('domain'); - const rows = await context - .get('db') - .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)); - const row = rows.find((r) => r.domain === domain); - if (!row) { - return context.html('

Email domain not found

', 404); - } const body = await context.req.parseBody(); if (body.confirm !== project.slug) { - return context.html( - `

Not confirmed

Type the project slug (${project.slug}) to revoke ${row.domain}.

`, - 400, - ); - } - - // Remove under the row's serialized lock, with the row and credential - // re-read inside it — the same shape as the owner DELETE. A replace that - // commits between the entry read and the cleanup must not have its fresh - // credential orphaned by the row delete: the replace never invalidates an - // old api_token, so cleanup built on a stale snapshot would SUCCEED and - // a newly committed oauth grant's only handle would go with the row. The - // lock also orders the mirror clear against a replacement sync's - // republish (both hold the row lock across their KV write). The - // serialized helpers take THIS tx — passing the pool handle would - // deadlock against the held FOR UPDATE. - const removal: Readonly<{ kind: 'removed' } | { kind: 'vanished' }> | null = await (async () => { - try { - return await withEmailDomainRowLock(context.get('db'), row.id, async (tx) => { - const locked = await tx - .select() - .from(emailDomains) - .where(eq(emailDomains.id, row.id)) - .limit(1); - const current = locked[0]; - if (!current) { - // Teardown's cascade can take the row mid-request — the - // idempotent re-clear below proceeds. - return { kind: 'vanished' } as const; - } - - // Tighten BEFORE anything destructive — the same inversion as the - // destination revoke above. The proxy trusts only the mirror key, - // and the row is what a retry re-runs from: a KV failure here - // throws, the transaction rolls back with the row intact, and the - // operator's retry starts from nothing-happened. - await clearEmailDomainMirror(context.env.ROUTING, current.domain); - - // Best-effort CF cleanup (relay script DELETE + catch-all reset); - // removeEmailDomain never throws. A stranded relay or rule in the - // customer's account is inert without the mirror entry, so neither - // a CF failure nor a decrypt failure (a rotated-away key version) - // may block the revoke — this log line is the trace an operator - // gets, same as the CF deleteDestination failure above. - try { - const credential = await decryptEmailDomainToken( - context.env, - projectId, - current.domain, - current, - ); - const { failed_steps } = await removeEmailDomain( - { - row: { - credential_kind: current.credential_kind, - account_id: current.account_id, - relay_worker_name: current.relay_worker_name, - zone_id: current.zone_id, - }, - credential, - }, - { - // Same doctrine as the owner DELETE: rotations persist - // through the row's serialized chain while it lives, and the - // grant is revoked (last, with the rotated head) — the row - // being deleted is the only place the rotated token exists, - // so omitting revokeGrant here would orphan a live grant - // with no platform handle. - refreshGrant: () => refreshOauthGrantSerialized(tx, context.env, current.id), - ...(current.credential_kind === 'oauth_grant' - ? { - revokeGrant: () => revokeOauthGrantSerialized(tx, context.env, current.id), - } - : {}), - }, - ); - if (failed_steps.length > 0) { - console.error('[admin-email] email-domain CF cleanup incomplete', { - projectId, - domain: current.domain, - failedSteps: failed_steps, - }); - } - } catch (error) { - console.error( - '[admin-email] email-domain credential decrypt failed; skipping CF cleanup', - { - projectId, - domain: current.domain, - error, - }, - ); - } - - await tx.delete(emailDomains).where(eq(emailDomains.id, current.id)); - return { kind: 'removed' } as const; - }); - } catch (error) { - console.error('[admin-email] email-domain mirror clear failed; keeping the row', { - projectId, - domain: row.domain, - error, - }); - return null; - } - })(); - - if (removal === null) { - return context.html('

Failed to clear the domain mirror. Try again.

', 503); + return context.html('

Not confirmed

', 400); } - if (removal.kind === 'vanished') { - // Teardown already cleared the mirror; the re-clear is idempotent. - await clearEmailDomainMirror(context.env.ROUTING, row.domain); + const result = await removeEmailDomainForProject( + context, + project, + context.req.param('domain'), + false, + 'admin', + ); + if (!result.ok) { + return context.html('

Email domain removal failed

', result.status as 400); } return context.redirect(`/admin/email/${projectId}`); }); -// POST /email/:projectId/domains/:domain/revoke-grant — operator revocation -// of one domain's OAuth grant: the support escape hatch when a customer asks -// us to kill their grant without tearing the domain down. Mirror write, RFC -// 7009 against dash.cloudflare.com, and the row flip run as ONE -// row-serialized operation — the lock is the credential fence: a replace -// either commits first (the locked re-read revokes and marks the NEW grant, -// never the stale snapshot's, and a replacement sync's `active` republish -// orders strictly before the mirror tighten) or waits and sees -// token_revoked. Mirror stays first inside the section (the proxy's relay -// auth checks its `active` status, so inbound stops here); a failed revoke -// leaves the row active with the mirror flipped, and the next status GET -// repairs the mirror back (self-healing, same as any drift). -app.post('/:projectId/domains/:domain/revoke-grant', async (context) => { +app.post('/:projectId/domains/:domain/rotate-secret', async (context) => { const projectId = context.req.param('projectId'); const project = await getProject(context.get('db'), projectId); if (!project) { return context.html('

Project not found

', 404); } - const domain = context.req.param('domain'); - const rows = await context - .get('db') - .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)); - const row = rows.find((r) => r.domain === domain); - if (!row) { - return context.html('

Email domain not found

', 404); - } - - type RevokeGrantOutcome = - | 'revoked' - | 'gone' - | 'not_oauth' - | 'decrypt_failed' - | 'mirror_failed' - | 'revoke_failed'; - const outcome: RevokeGrantOutcome = await withEmailDomainRowLock( - context.get('db'), - row.id, - async (tx): Promise => { - const locked = await tx - .select() - .from(emailDomains) - .where(eq(emailDomains.id, row.id)) - .limit(1); - const current = locked[0]; - if (!current) { - // Teardown's cascade took the row mid-request. - return 'gone'; - } - if (current.credential_kind !== 'oauth_grant') { - // A replace committed an api_token first (and revoked the old - // grant itself) — there is no platform-side grant left to revoke. - return 'not_oauth'; - } - let relaySecretSha256: string; - try { - relaySecretSha256 = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(context.env, projectId, current.domain, current), - ); - } catch (error) { - // No status change: without the relay secret the mirror cannot be - // tightened safely, so there is nothing to base the revoke on - // either. - console.error('[admin-email] grant revoke failed to decrypt the stored relay secret', { - projectId, - domain: current.domain, - error, - }); - return 'decrypt_failed'; - } - // Mirror BEFORE the revoke — the same inversion as the removal - // route. A failed write rolls back with nothing else written. - try { - await writeEmailDomainMirror( - context.env.ROUTING, - { ...current, status: 'token_revoked' }, - relaySecretSha256, - ); - } catch (error) { - console.error('[admin-email] grant revoke failed to tighten the mirror', { - projectId, - domain: current.domain, - error, - }); - return 'mirror_failed'; - } - try { - // The row's LIVE chain head, under the same lock: a token - // decrypted beforehand could already be consumed by an - // interleaved lease refresh, and CF answers 200 for a consumed - // token whether or not the grant survived. - await revokeOauthGrantSerialized(tx, context.env, current.id); - } catch (error) { - // Network/non-2xx — the grant's state is unknown, so the row keeps - // its status and the operator retries. The mirror already flipped - // (KV is not transactional); the next status GET repairs it while - // the row stays active. - console.error('[admin-email] grant revoke request failed', { - projectId, - domain: current.domain, - error, - }); - return 'revoke_failed'; - } - await tx - .update(emailDomains) - .set({ status: 'token_revoked', updated_at: sql`now()` }) - .where(eq(emailDomains.id, current.id)); - return 'revoked'; - }, + const result = await rotateEmailIngressSecretForProject( + context, + project, + context.req.param('domain'), + 'admin', ); - - if (outcome === 'gone') { - return context.html('

Email domain not found

', 404); - } - if (outcome === 'not_oauth') { - return context.html( - '

Not an OAuth grant

API tokens are revoked by the customer at dash.cloudflare.com; there is no platform-side grant to revoke.

', - 400, - ); - } - if (outcome === 'decrypt_failed') { - return context.html( - '

Failed to decrypt the stored relay secret

The grant cannot be revoked from here; the row keeps its current status.

', - 500, - ); - } - if (outcome === 'mirror_failed') { - return context.html('

Failed to tighten the domain mirror. Try again.

', 503); - } - if (outcome === 'revoke_failed') { - return context.html('

Failed to revoke the grant at Cloudflare. Try again.

', 502); + if (!result.ok) { + return context.html('

Email ingress rotation failed

', result.status as 400); } return context.redirect(`/admin/email/${projectId}`); }); @@ -924,7 +672,7 @@ app.post('/:projectId/domains/:domain/revoke-grant', async (context) => { async function setLimit( context: Context, projectId: string, - key: (projectId: string) => string, + kind: 'monthly' | 'burst', field: string, ): Promise { const project = await getProject(context.get('db'), projectId); @@ -935,14 +683,14 @@ async function setLimit( const submitted = body[field]; const raw = typeof submitted === 'string' ? submitted.trim() : ''; if (raw === '') { - await context.env.ROUTING.delete(key(projectId)); + await setProjectEmailLimits(context.get('db'), projectId, { [kind]: null }); return context.redirect(`/admin/email/${projectId}`); } const limit = parseLimit(raw); if (limit === undefined) { return context.html('

Invalid limit

Expected a positive integer, or blank.

', 400); } - await context.env.ROUTING.put(key(projectId), String(limit)); + await setProjectEmailLimits(context.get('db'), projectId, { [kind]: limit }); return context.redirect(`/admin/email/${projectId}`); } diff --git a/platform/packages/api/src/auth/profile.ts b/platform/packages/api/src/auth/profile.ts index 19261cd39..2edbbd27d 100644 --- a/platform/packages/api/src/auth/profile.ts +++ b/platform/packages/api/src/auth/profile.ts @@ -1,4 +1,5 @@ import { updateUser, revokeOwnerVerifiedDestinationsForUserChange, type Db } from '../db.ts'; +import { lockEmailPolicy } from '../email/admission.ts'; import { syncProjectAllowlistKv, syncProjectAllowlistKvBestEffort, @@ -112,6 +113,7 @@ export async function updateUserRevokingInheritedDestinations( let projectIds: Array; try { projectIds = await db.transaction(async (tx) => { + await lockEmailPolicy(tx); const txDb = tx as unknown as Db; await updateUser(txDb, userId, login, nextEmail); const affected = await revokeOwnerVerifiedDestinationsForUserChange( diff --git a/platform/packages/api/src/db.ts b/platform/packages/api/src/db.ts index b937060e5..d8cec75f6 100644 --- a/platform/packages/api/src/db.ts +++ b/platform/packages/api/src/db.ts @@ -20,6 +20,7 @@ import { import { drizzle } from 'drizzle-orm/node-postgres'; import { alias } from 'drizzle-orm/pg-core'; import { lockAuthSettings } from './auth/configuration.ts'; +import { lockEmailPolicy } from './email/admission.ts'; import { generateId } from './id.ts'; import * as schema from './schema.ts'; import { @@ -1684,14 +1685,23 @@ export async function tryCreateEmailDestination( }; let inserted: EmailDestination | undefined; if (!ownerAudit) { - inserted = await insertRow(db); + inserted = await db.transaction(async (tx) => { + await lockEmailPolicy(tx); + await tx + .select({ id: projects.id }) + .from(projects) + .where(eq(projects.id, projectId)) + .for('update'); + return insertRow(tx as unknown as Db); + }); } else { const outcome = await db.transaction(async (tx) => { + await lockEmailPolicy(tx); await tx .select({ id: projects.id }) .from(projects) .where(eq(projects.id, projectId)) - .for('key share') + .for('update') .limit(1); const [owner] = await tx .select({ email: users.email }) @@ -1814,6 +1824,26 @@ export async function revokeOwnerVerifiedDestinationsForUserChange( oldEmail: string, ): Promise> { const lowered = oldEmail.toLowerCase(); + // The caller holds the policy lock in its surrounding profile transaction. + // Lock affected projects before changing consent so admission cannot read + // their old verified destinations after this revocation commits. + const affected = await db + .selectDistinct({ project_id: emailDestinations.project_id }) + .from(emailDestinations) + .where( + and( + eq(emailDestinations.verified_by_user_id, userId), + sql`lower(${emailDestinations.verified_by_email_snapshot}) = ${lowered}`, + eq(emailDestinations.verification_source, 'cf'), + ), + ); + for (const projectId of affected.map((row) => row.project_id).sort()) { + await db + .select({ id: projects.id }) + .from(projects) + .where(eq(projects.id, projectId)) + .for('update'); + } const updated = await db .update(emailDestinations) .set({ @@ -1944,11 +1974,52 @@ export async function updateEmailDestinationStatus( if (verificationSource !== undefined) { patch.verification_source = verificationSource; } - await db.update(emailDestinations).set(patch).where(eq(emailDestinations.id, id)); + const [existing] = await db + .select({ project_id: emailDestinations.project_id }) + .from(emailDestinations) + .where(eq(emailDestinations.id, id)) + .limit(1); + if (!existing) { + return; + } + await db.transaction(async (tx) => { + await lockEmailPolicy(tx); + await tx + .select({ id: projects.id }) + .from(projects) + .where(eq(projects.id, existing.project_id)) + .for('update'); + await tx + .update(emailDestinations) + .set(patch) + .where( + and(eq(emailDestinations.id, id), eq(emailDestinations.project_id, existing.project_id)), + ); + }); } export async function deleteEmailDestination(db: Db, id: string): Promise { - await db.delete(emailDestinations).where(eq(emailDestinations.id, id)); + const [existing] = await db + .select({ project_id: emailDestinations.project_id }) + .from(emailDestinations) + .where(eq(emailDestinations.id, id)) + .limit(1); + if (!existing) { + return; + } + await db.transaction(async (tx) => { + await lockEmailPolicy(tx); + await tx + .select({ id: projects.id }) + .from(projects) + .where(eq(projects.id, existing.project_id)) + .for('update'); + await tx + .delete(emailDestinations) + .where( + and(eq(emailDestinations.id, id), eq(emailDestinations.project_id, existing.project_id)), + ); + }); } /** @@ -2003,11 +2074,12 @@ export async function promoteEmailDestinationWithOwnerAudit( ownerAudit: OwnerVerificationAudit, ): Promise { return db.transaction(async (tx) => { + await lockEmailPolicy(tx); await tx .select({ id: projects.id }) .from(projects) .where(eq(projects.id, projectId)) - .for('key share') + .for('update') .limit(1); const [owner] = await tx .select({ email: users.email }) diff --git a/platform/packages/api/src/email/admission-schema.ts b/platform/packages/api/src/email/admission-schema.ts new file mode 100644 index 000000000..7d969a99c --- /dev/null +++ b/platform/packages/api/src/email/admission-schema.ts @@ -0,0 +1,125 @@ +import { sql } from 'drizzle-orm'; +import { + boolean, + check, + index, + integer, + pgTable, + text, + timestamp, + unique, +} from 'drizzle-orm/pg-core'; +import { projects } from '../schema.ts'; + +export const emailProjectControls = pgTable('email_project_controls', { + project_id: text('project_id') + .primaryKey() + .references(() => projects.id, { onDelete: 'cascade' }), + monthly_limit: integer('monthly_limit').notNull().default(200), + burst_limit: integer('burst_limit').notNull().default(10), + suspended_at: timestamp('suspended_at', { mode: 'string', withTimezone: true }), + version: integer('version').notNull().default(1), +}); + +/** Quota history outlives the 30-day delivery ledger through month end. */ +export const emailMonthlyUsage = pgTable( + 'email_monthly_usage', + { + project_id: text('project_id').notNull(), + month: text('month').notNull(), + recipient_attempts: integer('recipient_attempts').notNull().default(0), + }, + (table) => [ + unique('email_monthly_usage_project_month_uq').on(table.project_id, table.month), + check('email_monthly_usage_nonnegative_check', sql`${table.recipient_attempts} >= 0`), + ], +); + +export const emailReceipts = pgTable( + 'email_receipts', + { + id: text('id').primaryKey(), + project_id: text('project_id').notNull(), + status: text('status').notNull().default('received'), + payload_digest: text('payload_digest'), + final_reject: boolean('final_reject'), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + }, + (table) => [index('idx_email_receipts_project_created').on(table.project_id, table.created_at)], +); + +export const emailActions = pgTable( + 'email_actions', + { + id: text('id').primaryKey(), + project_id: text('project_id').notNull(), + sender_domain: text('sender_domain').notNull(), + receipt_id: text('receipt_id').references(() => emailReceipts.id, { onDelete: 'set null' }), + kind: text('kind').notNull().$type<'direct' | 'forward' | 'reply'>(), + idempotency_key: text('idempotency_key').notNull(), + payload_digest: text('payload_digest').notNull(), + transport: text('transport').notNull(), + policy_version: integer('policy_version').notNull(), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + }, + (table) => [ + unique('email_actions_project_key_uq').on(table.project_id, table.idempotency_key), + index('idx_email_actions_project_created').on(table.project_id, table.created_at), + check('email_actions_kind_check', sql`${table.kind} IN ('direct', 'forward', 'reply')`), + ], +); + +export const emailActionRecipients = pgTable( + 'email_action_recipients', + { + id: text('id').primaryKey(), + action_id: text('action_id') + .notNull() + .references(() => emailActions.id, { onDelete: 'cascade' }), + project_id: text('project_id').notNull(), + recipient: text('recipient').notNull(), + state: text('state') + .notNull() + .$type< + | 'rejected' + | 'reserved' + | 'attempt_started' + | 'provider_accepted' + | 'failed' + | 'outcome_unknown' + | 'cancelled' + >(), + error_code: text('error_code'), + provider_reference: text('provider_reference'), + reserved_at: timestamp('reserved_at', { mode: 'string', withTimezone: true }), + attempt_started_at: timestamp('attempt_started_at', { mode: 'string', withTimezone: true }), + completed_at: timestamp('completed_at', { mode: 'string', withTimezone: true }), + }, + (table) => [ + unique('email_action_recipients_action_recipient_uq').on(table.action_id, table.recipient), + index('idx_email_action_recipients_project_reserved').on(table.project_id, table.reserved_at), + check( + 'email_action_recipients_state_check', + sql`${table.state} IN ('rejected', 'reserved', 'attempt_started', 'provider_accepted', 'failed', 'outcome_unknown', 'cancelled')`, + ), + ], +); + +/** PII-free fence retained if an active provider attempt outlives log retention. */ +export const emailUnresolvedAttempts = pgTable( + 'email_unresolved_attempts', + { + id: text('id').primaryKey(), + project_id: text('project_id').notNull(), + sender_domain: text('sender_domain').notNull(), + started_at: timestamp('started_at', { mode: 'string', withTimezone: true }).notNull(), + }, + (table) => [ + index('idx_email_unresolved_attempts_project').on(table.project_id), + index('idx_email_unresolved_attempts_domain').on(table.sender_domain), + ], +); diff --git a/platform/packages/api/src/email/admission.ts b/platform/packages/api/src/email/admission.ts new file mode 100644 index 000000000..4d1171156 --- /dev/null +++ b/platform/packages/api/src/email/admission.ts @@ -0,0 +1,911 @@ +import { and, asc, count, desc, eq, gte, ne, sql } from 'drizzle-orm'; +import type { Db, DbOrTx, Tx } from '../db.ts'; +import { generateId } from '../id.ts'; +import { isReservedEmailSlug } from '../reserved-slugs.ts'; +import { emailDestinations, projects, users } from '../schema.ts'; +import { + emailActionRecipients, + emailActions, + emailMonthlyUsage, + emailProjectControls, + emailReceipts, + emailUnresolvedAttempts, +} from './admission-schema.ts'; +import { emailCredentials, emailDomainRoutes } from './connection-schema.ts'; +import { resolveEmailDomain } from './connection-service.ts'; +import { getEmailRecipientPolicy } from './settings.ts'; + +export type EmailActionState = + | 'rejected' + | 'reserved' + | 'attempt_started' + | 'provider_accepted' + | 'failed' + | 'outcome_unknown' + | 'cancelled'; +export type EmailActionKind = 'direct' | 'forward' | 'reply'; +export type EmailActionRecipient = { + recipient: string; + state: EmailActionState; + errorCode: string | null; + providerReference: string | null; +}; +export type EmailAdmissionResult = { + operationId: string; + replay: boolean; + recipients: Array; + accountId?: string; +}; +export type EmailAdmissionInput = { + projectId: string; + kind: EmailActionKind; + key: string; + digest: string; + from: string; + recipients: Array; + transport: 'binding' | 'send_raw' | 'native_forward' | 'native_reply'; + receiptId?: string; + /** Only configured server-side; never accept this from a tenant request. */ + sharedSenderDomain: string; +}; + +export class EmailAdmissionError extends Error { + constructor( + readonly code: 'CONFLICT' | 'INVALID_REQUEST' | 'NOT_FOUND' | 'INVALID_STATE', + message: string, + ) { + super(message); + } +} + +/** Policy mutations take this exclusive lock; admission takes it shared. */ +export async function lockEmailPolicy(tx: Tx): Promise { + await tx.execute(sql`select pg_advisory_xact_lock(hashtext('email-admission:policy'))`); +} +async function lockEmailPolicyForAdmission(tx: Tx): Promise { + await tx.execute(sql`select pg_advisory_xact_lock_shared(hashtext('email-admission:policy'))`); +} + +export async function withProjectEmailControlLock( + db: Db, + projectId: string, + fn: (tx: Tx) => Promise, +): Promise { + return db.transaction(async (tx) => { + await lockEmailPolicy(tx); + const [project] = await tx + .select({ id: projects.id }) + .from(projects) + .where(eq(projects.id, projectId)) + .for('update'); + if (!project) { + throw new EmailAdmissionError('NOT_FOUND', 'project not found'); + } + return fn(tx); + }); +} + +async function ensureControls(tx: Tx, projectId: string) { + await tx.insert(emailProjectControls).values({ project_id: projectId }).onConflictDoNothing(); + const [row] = await tx + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + .for('update'); + return row!; +} + +export async function setProjectEmailLimits( + db: Db, + projectId: string, + limits: { monthly?: number | null; burst?: number | null }, +) { + return withProjectEmailControlLock(db, projectId, async (tx) => { + await ensureControls(tx, projectId); + const update: { + monthly_limit?: number; + burst_limit?: number; + version: ReturnType; + } = { version: sql`${emailProjectControls.version} + 1` }; + if (limits.monthly !== undefined) { + update.monthly_limit = limits.monthly ?? 200; + } + if (limits.burst !== undefined) { + update.burst_limit = limits.burst ?? 10; + } + for (const value of [update.monthly_limit, update.burst_limit]) { + if (value !== undefined && (!Number.isInteger(value) || value < 1 || value > 1_000_000)) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid email limit'); + } + } + const [row] = await tx + .update(emailProjectControls) + .set(update) + .where(eq(emailProjectControls.project_id, projectId)) + .returning(); + return row!; + }); +} + +export async function setProjectEmailSuspended(db: Db, projectId: string, suspended: boolean) { + return withProjectEmailControlLock(db, projectId, async (tx) => { + await ensureControls(tx, projectId); + const [row] = await tx + .update(emailProjectControls) + .set({ + suspended_at: suspended ? new Date().toISOString() : null, + version: sql`${emailProjectControls.version} + 1`, + }) + .where(eq(emailProjectControls.project_id, projectId)) + .returning(); + return row!; + }); +} + +function monthStart(now: Date): string { + return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString(); +} + +async function currentRecipients( + tx: DbOrTx, + actionId: string, +): Promise> { + const rows = await tx + .select() + .from(emailActionRecipients) + .where(eq(emailActionRecipients.action_id, actionId)) + .orderBy(asc(emailActionRecipients.id)); + return rows.map((r) => ({ + recipient: r.recipient, + state: r.state, + errorCode: r.error_code, + providerReference: r.provider_reference, + })); +} + +function validAddress(address: string): boolean { + return address.length <= 320 && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address); +} + +export async function admitEmailAction( + db: Db, + input: EmailAdmissionInput, +): Promise { + if ( + !input.key || + input.key.length > (input.kind === 'direct' ? 128 : 256) || + !/^[a-f0-9]{64}$/.test(input.digest) || + input.recipients.length > (input.kind === 'direct' ? 50 : 100) || + !validAddress(input.from) + ) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid email action'); + } + if (input.kind !== 'direct' && !input.receiptId) { + throw new EmailAdmissionError('INVALID_REQUEST', 'inbound action requires a receipt'); + } + const recipients = [...new Set(input.recipients.map((r) => r.trim().toLowerCase()))]; + if (recipients.length === 0 || recipients.some((r) => !validAddress(r))) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid recipient'); + } + return db.transaction(async (tx) => { + await lockEmailPolicyForAdmission(tx); + const [project] = await tx + .select() + .from(projects) + .where(eq(projects.id, input.projectId)) + .for('update'); + if (!project) { + throw new EmailAdmissionError('NOT_FOUND', 'project not found'); + } + const [existing] = await tx + .select() + .from(emailActions) + .where( + and( + eq(emailActions.project_id, input.projectId), + eq(emailActions.idempotency_key, input.key), + ), + ) + .limit(1); + if (existing) { + if (existing.payload_digest !== input.digest || existing.kind !== input.kind) { + throw new EmailAdmissionError( + 'CONFLICT', + 'idempotency key was used for a different action', + ); + } + return { + operationId: existing.id, + replay: true, + recipients: await currentRecipients(tx, existing.id), + }; + } + const controls = await ensureControls(tx, input.projectId); + const [owner] = await tx + .select({ suspended_reason: users.suspended_reason, email: users.email }) + .from(users) + .where(eq(users.id, project.user_id)) + .limit(1); + const policy = await getEmailRecipientPolicy(tx); + const senderDomain = input.from.toLowerCase().split('@')[1]!; + const shared = senderDomain === input.sharedSenderDomain.toLowerCase(); + if (shared && !/^[a-z0-9._-]+(?:\+[a-z0-9._=/-]+)?@[a-z0-9.-]+$/i.test(input.from)) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid shared sender'); + } + const expectedTransport = + input.kind === 'direct' + ? shared + ? 'binding' + : 'send_raw' + : shared + ? input.kind === 'forward' + ? 'native_forward' + : 'native_reply' + : 'send_raw'; + const nativeCustomTransport = + !shared && + input.kind !== 'direct' && + input.transport === (input.kind === 'forward' ? 'native_forward' : 'native_reply'); + if (input.transport !== expectedTransport && !nativeCustomTransport) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid email transport'); + } + let senderAllowed = false; + let verifiedOnlyTransport = false; + if (shared) { + senderAllowed = + !isReservedEmailSlug(project.slug) && + input.from.toLowerCase().split('@')[0]!.split('+')[0] === project.slug.toLowerCase(); + } else { + const domain = await resolveEmailDomain(tx, senderDomain); + senderAllowed = + domain?.route.project_id === input.projectId && + domain.route.desired_state === 'active' && + (domain.route.outbound_status === 'ready' || + domain.route.outbound_status === 'verified_only') && + domain.connection.management_status === 'healthy'; + verifiedOnlyTransport = + nativeCustomTransport || domain?.route.outbound_status === 'verified_only'; + if (senderAllowed && domain?.connection.credential_id) { + const [credential] = await tx + .select({ status: emailCredentials.status }) + .from(emailCredentials) + .where(eq(emailCredentials.id, domain.connection.credential_id)) + .limit(1); + senderAllowed = credential?.status === 'healthy'; + } else { + senderAllowed = false; + } + } + const destinations = await tx + .select() + .from(emailDestinations) + .where(eq(emailDestinations.project_id, input.projectId)); + const verified = new Set( + destinations + .filter( + (d) => + d.status === 'verified' && + (!d.verified_by_user_id || + (d.verified_by_user_id === project.user_id && + d.verified_by_email_snapshot?.toLowerCase() === owner?.email?.toLowerCase())), + ) + .map((d) => d.address.toLowerCase()), + ); + const now = new Date(); + const windowStart = new Date(now.getTime() - 60_000).toISOString(); + const [burst] = await tx + .select({ n: count() }) + .from(emailActionRecipients) + .where( + and( + eq(emailActionRecipients.project_id, input.projectId), + gte(emailActionRecipients.reserved_at, windowStart), + ne(emailActionRecipients.state, 'cancelled'), + ), + ); + const month = monthStart(now).slice(0, 7); + await tx + .insert(emailMonthlyUsage) + .values({ project_id: input.projectId, month }) + .onConflictDoNothing(); + const [monthly] = await tx + .select() + .from(emailMonthlyUsage) + .where( + and(eq(emailMonthlyUsage.project_id, input.projectId), eq(emailMonthlyUsage.month, month)), + ) + .for('update'); + let burstUsed = burst?.n ?? 0; + let monthUsed = monthly?.recipient_attempts ?? 0; + if (input.receiptId) { + const [receipt] = await tx + .select() + .from(emailReceipts) + .where(eq(emailReceipts.id, input.receiptId)) + .limit(1); + if ( + !receipt || + receipt.project_id !== input.projectId || + receipt.status !== 'handler_completed' + ) { + throw new EmailAdmissionError('INVALID_REQUEST', 'receipt is not ready for actions'); + } + } + const actionId = generateId('emailact'); + await tx.insert(emailActions).values({ + id: actionId, + project_id: input.projectId, + sender_domain: senderDomain, + receipt_id: input.receiptId ?? null, + kind: input.kind, + idempotency_key: input.key, + payload_digest: input.digest, + transport: input.transport, + policy_version: controls.version, + }); + let admittedCount = 0; + for (const recipient of recipients) { + const domain = recipient.split('@')[1]!; + const consent = verified.has(recipient); + const allowedByMode = + policy.mode === 'any' || (policy.mode === 'domains' && policy.domains.includes(domain)); + const destinationRoute = await resolveEmailDomain(tx, domain); + const sharedDestination = + domain === input.sharedSenderDomain.toLowerCase() || + destinationRoute?.route.addressing === 'shared'; + const allowed = + consent || (!sharedDestination && !verifiedOnlyTransport && (!shared || allowedByMode)); + let errorCode: string | null = null; + if (project.status !== 'active' || owner?.suspended_reason || controls.suspended_at) { + errorCode = 'SUSPENDED'; + } else if (!senderAllowed) { + errorCode = 'INVALID_FROM'; + } else if (!allowed) { + errorCode = 'UNVERIFIED_DESTINATION'; + } else if (burstUsed >= controls.burst_limit || monthUsed >= controls.monthly_limit) { + errorCode = 'QUOTA_EXCEEDED'; + } + const admitted = errorCode === null; + await tx.insert(emailActionRecipients).values({ + id: generateId('emailrcpt'), + action_id: actionId, + project_id: input.projectId, + recipient, + state: admitted ? 'reserved' : 'rejected', + error_code: errorCode, + reserved_at: admitted ? now.toISOString() : null, + }); + if (admitted) { + burstUsed++; + monthUsed++; + admittedCount++; + } + } + if (admittedCount) { + await tx + .update(emailMonthlyUsage) + .set({ + recipient_attempts: sql`${emailMonthlyUsage.recipient_attempts} + ${admittedCount}`, + }) + .where( + and( + eq(emailMonthlyUsage.project_id, input.projectId), + eq(emailMonthlyUsage.month, month), + ), + ); + } + return { + operationId: actionId, + replay: false, + recipients: await currentRecipients(tx, actionId), + ...(!shared && senderAllowed + ? { accountId: (await resolveEmailDomain(tx, senderDomain))!.connection.account_id } + : {}), + }; + }); +} + +export async function transitionEmailRecipients( + db: Db, + actionId: string, + recipients: Array, + next: 'attempt_started' | 'provider_accepted' | 'failed' | 'outcome_unknown' | 'cancelled', + details: { providerReference?: string; errorCode?: string } = {}, +) { + const normalized = [...new Set(recipients.map((r) => r.toLowerCase()))]; + return db.transaction(async (tx) => { + // Serialize starts with project teardown. Once deleting is visible, an + // admitted reservation cannot become a provider side effect. + if (next === 'attempt_started') { + await lockEmailPolicyForAdmission(tx); + } + const [actionIdentity] = await tx + .select({ projectId: emailActions.project_id }) + .from(emailActions) + .where(eq(emailActions.id, actionId)) + .limit(1); + if (!actionIdentity) { + throw new EmailAdmissionError('NOT_FOUND', 'email action not found'); + } + if (next === 'attempt_started') { + const [project] = await tx + .select({ status: projects.status }) + .from(projects) + .where(eq(projects.id, actionIdentity.projectId)) + .for('update'); + if (project?.status !== 'active') { + throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); + } + } + const [action] = await tx + .select() + .from(emailActions) + .where(eq(emailActions.id, actionId)) + .for('update'); + if (!action) { + throw new EmailAdmissionError('NOT_FOUND', 'email action not found'); + } + if (next === 'attempt_started') { + const [controls] = await tx + .select({ suspendedAt: emailProjectControls.suspended_at }) + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, action.project_id)) + .for('update'); + if (!controls || controls.suspendedAt) { + throw new EmailAdmissionError('INVALID_STATE', 'email sending is suspended'); + } + if ( + action.transport === 'send_raw' || + action.transport === 'native_forward' || + action.transport === 'native_reply' + ) { + const route = await resolveEmailDomain(tx, action.sender_domain); + if (action.transport === 'send_raw' || route?.route.addressing === 'custom') { + if ( + !route || + route.route.project_id !== action.project_id || + route.route.desired_state !== 'active' || + !['ready', 'verified_only'].includes(route.route.outbound_status) || + route.connection.management_status !== 'healthy' + ) { + throw new EmailAdmissionError('INVALID_STATE', 'email route is not active'); + } + } + } + } + const rows = await tx + .select() + .from(emailActionRecipients) + .where(eq(emailActionRecipients.action_id, actionId)); + if (normalized.some((r) => !rows.some((row) => row.recipient === r))) { + throw new EmailAdmissionError('INVALID_REQUEST', 'recipient is not in action'); + } + for (const recipient of normalized) { + const current = rows.find((row) => row.recipient === recipient)!; + const expected = + next === 'attempt_started' || next === 'cancelled' ? 'reserved' : 'attempt_started'; + if (current.state !== expected) { + throw new EmailAdmissionError('INVALID_STATE', `recipient is ${current.state}`); + } + await tx + .update(emailActionRecipients) + .set({ + state: next, + ...(next === 'attempt_started' + ? { attempt_started_at: new Date().toISOString() } + : { completed_at: new Date().toISOString() }), + ...(details.providerReference ? { provider_reference: details.providerReference } : {}), + ...(details.errorCode ? { error_code: details.errorCode } : {}), + }) + .where(eq(emailActionRecipients.id, current.id)); + if (next === 'attempt_started') { + await tx.insert(emailUnresolvedAttempts).values({ + id: current.id, + project_id: action.project_id, + sender_domain: action.sender_domain, + started_at: new Date().toISOString(), + }); + } else if (next !== 'cancelled') { + await tx.delete(emailUnresolvedAttempts).where(eq(emailUnresolvedAttempts.id, current.id)); + } + if (next === 'cancelled' && current.reserved_at) { + await tx + .update(emailMonthlyUsage) + .set({ + recipient_attempts: sql`greatest(0, ${emailMonthlyUsage.recipient_attempts} - 1)`, + }) + .where( + and( + eq(emailMonthlyUsage.project_id, action.project_id), + eq(emailMonthlyUsage.month, current.reserved_at.slice(0, 7)), + ), + ); + } + } + return currentRecipients(tx, actionId); + }); +} + +/** Fence all new starts and release only reservations that never reached a provider. */ +export async function drainProjectEmailAdmissions( + db: Db, + projectId: string, +): Promise<{ cancelled: number; inFlight: number }> { + return db.transaction(async (tx) => { + await lockEmailPolicy(tx); + const [project] = await tx + .select({ status: projects.status }) + .from(projects) + .where(eq(projects.id, projectId)) + .for('update'); + if (!project || project.status !== 'deleting') { + throw new EmailAdmissionError('INVALID_STATE', 'project must be deleting before email drain'); + } + const [controls] = await tx + .select({ id: emailProjectControls.project_id }) + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + .for('update'); + if (!controls) { + // A project with no email control row has never admitted an action. + return { cancelled: 0, inFlight: 0 }; + } + const cancelled = await tx + .update(emailActionRecipients) + .set({ state: 'cancelled', completed_at: new Date().toISOString() }) + .where( + and( + eq(emailActionRecipients.project_id, projectId), + eq(emailActionRecipients.state, 'reserved'), + ), + ) + .returning({ reservedAt: emailActionRecipients.reserved_at }); + const monthlyRefunds = new Map(); + for (const row of cancelled) { + if (row.reservedAt) { + const month = row.reservedAt.slice(0, 7); + monthlyRefunds.set(month, (monthlyRefunds.get(month) ?? 0) + 1); + } + } + for (const [month, amount] of monthlyRefunds) { + await tx + .update(emailMonthlyUsage) + .set({ + recipient_attempts: sql`greatest(0, ${emailMonthlyUsage.recipient_attempts} - ${amount})`, + }) + .where( + and(eq(emailMonthlyUsage.project_id, projectId), eq(emailMonthlyUsage.month, month)), + ); + } + const [unresolved] = await tx + .select({ n: count() }) + .from(emailUnresolvedAttempts) + .where(eq(emailUnresolvedAttempts.project_id, projectId)); + return { cancelled: cancelled.length, inFlight: unresolved?.n ?? 0 }; + }); +} + +/** Disable a custom route and drain its unstarted sends under the admission fence. */ +export async function disableEmailDomainRouteAndDrain( + db: Db, + routeId: string, +): Promise<{ cancelled: number; inFlight: number }> { + return db.transaction((tx) => disableEmailDomainRouteAndDrainTx(tx, routeId)); +} + +export async function disableEmailDomainRouteAndDrainTx( + tx: Tx, + routeId: string, +): Promise<{ cancelled: number; inFlight: number }> { + await lockEmailPolicy(tx); + const [route] = await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, routeId)) + .for('update'); + if (!route || route.addressing !== 'custom' || !route.project_id) { + throw new EmailAdmissionError('NOT_FOUND', 'custom email route not found'); + } + if (route.desired_state === 'removed') { + return { cancelled: 0, inFlight: 0 }; + } + await tx + .update(emailDomainRoutes) + .set({ + desired_state: 'disabled', + inbound_status: 'disabled', + desired_generation: sql`${emailDomainRoutes.desired_generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailDomainRoutes.id, routeId)); + const cancelled = await tx + .update(emailActionRecipients) + .set({ + state: 'cancelled', + completed_at: new Date().toISOString(), + }) + .where(sql` + ${emailActionRecipients.state} = 'reserved' + and ${emailActionRecipients.action_id} in ( + select ${emailActions.id} from ${emailActions} + where ${emailActions.project_id} = ${route.project_id} + and ${emailActions.sender_domain} = ${route.domain} + ) + `) + .returning({ reservedAt: emailActionRecipients.reserved_at }); + const monthlyRefunds = new Map(); + for (const row of cancelled) { + if (row.reservedAt) { + const month = row.reservedAt.slice(0, 7); + monthlyRefunds.set(month, (monthlyRefunds.get(month) ?? 0) + 1); + } + } + for (const [month, amount] of monthlyRefunds) { + await tx + .update(emailMonthlyUsage) + .set({ + recipient_attempts: sql`greatest(0, ${emailMonthlyUsage.recipient_attempts} - ${amount})`, + }) + .where( + and(eq(emailMonthlyUsage.project_id, route.project_id), eq(emailMonthlyUsage.month, month)), + ); + } + const [unresolved] = await tx + .select({ n: count() }) + .from(emailUnresolvedAttempts) + .where( + and( + eq(emailUnresolvedAttempts.project_id, route.project_id), + eq(emailUnresolvedAttempts.sender_domain, route.domain), + ), + ); + return { cancelled: cancelled.length, inFlight: unresolved?.n ?? 0 }; +} + +export async function countEmailDomainInFlight(db: Db, routeId: string): Promise { + const [route] = await db + .select({ projectId: emailDomainRoutes.project_id, domain: emailDomainRoutes.domain }) + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, routeId)) + .limit(1); + if (!route?.projectId) { + return 0; + } + const [row] = await db + .select({ n: count() }) + .from(emailUnresolvedAttempts) + .where( + and( + eq(emailUnresolvedAttempts.project_id, route.projectId), + eq(emailUnresolvedAttempts.sender_domain, route.domain), + ), + ); + return row?.n ?? 0; +} + +export async function getEmailAction( + db: Db, + actionId: string, +): Promise { + const [action] = await db + .select() + .from(emailActions) + .where(eq(emailActions.id, actionId)) + .limit(1); + if (!action) { + return null; + } + return { operationId: actionId, replay: true, recipients: await currentRecipients(db, actionId) }; +} + +export async function recordEmailReceipt( + db: Db, + input: { receiptId: string; projectId: string; status: string }, +): Promise { + if (!/^[a-zA-Z0-9_-]{1,128}$/.test(input.receiptId) || !/^[a-z_]{1,32}$/.test(input.status)) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid receipt'); + } + await db.transaction(async (tx) => { + const [project] = await tx + .select({ id: projects.id, status: projects.status }) + .from(projects) + .where(eq(projects.id, input.projectId)) + .for('update'); + if (!project) { + throw new EmailAdmissionError('NOT_FOUND', 'project not found'); + } + const [existing] = await tx + .select() + .from(emailReceipts) + .where(eq(emailReceipts.id, input.receiptId)) + .for('update'); + if (existing && existing.project_id !== input.projectId) { + throw new EmailAdmissionError('CONFLICT', 'receipt belongs to another project'); + } + if (!existing && project.status !== 'active') { + throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); + } + if (existing) { + await tx + .update(emailReceipts) + .set({ status: input.status }) + .where(eq(emailReceipts.id, input.receiptId)); + } else { + await tx + .insert(emailReceipts) + .values({ id: input.receiptId, project_id: input.projectId, status: input.status }); + } + }); +} + +export async function claimRelayedEmailReceipt( + db: Db, + input: { receiptId: string; projectId: string; payloadDigest: string }, +): Promise<{ state: 'claimed' | 'in_progress' | 'completed'; reject?: boolean }> { + if (!/^[a-f0-9]{64}$/.test(input.receiptId) || !/^[a-f0-9]{64}$/.test(input.payloadDigest)) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid relay claim'); + } + return db.transaction(async (tx) => { + const [project] = await tx + .select({ status: projects.status }) + .from(projects) + .where(eq(projects.id, input.projectId)) + .for('update'); + if (!project || project.status !== 'active') { + throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); + } + const inserted = await tx + .insert(emailReceipts) + .values({ + id: input.receiptId, + project_id: input.projectId, + payload_digest: input.payloadDigest, + status: 'received', + }) + .onConflictDoNothing() + .returning({ id: emailReceipts.id }); + if (inserted.length) { + return { state: 'claimed' }; + } + const [existing] = await tx + .select() + .from(emailReceipts) + .where(eq(emailReceipts.id, input.receiptId)) + .for('update'); + if ( + !existing || + existing.project_id !== input.projectId || + existing.payload_digest !== input.payloadDigest + ) { + throw new EmailAdmissionError('CONFLICT', 'relay invocation content conflict'); + } + return existing.status === 'delivery_completed' && existing.final_reject !== null + ? { state: 'completed', reject: existing.final_reject } + : { state: 'in_progress' }; + }); +} + +export async function completeRelayedEmailReceipt( + db: Db, + input: { receiptId: string; projectId: string; payloadDigest: string; reject: boolean }, +): Promise { + await db.transaction(async (tx) => { + const [existing] = await tx + .select() + .from(emailReceipts) + .where(eq(emailReceipts.id, input.receiptId)) + .for('update'); + if ( + !existing || + existing.project_id !== input.projectId || + existing.payload_digest !== input.payloadDigest + ) { + throw new EmailAdmissionError('CONFLICT', 'relay receipt mismatch'); + } + if (existing.status === 'delivery_completed') { + if (existing.final_reject !== input.reject) { + throw new EmailAdmissionError('CONFLICT', 'relay outcome conflict'); + } + return; + } + if (existing.status !== 'handler_completed') { + throw new EmailAdmissionError('INVALID_STATE', 'relay handler has not completed'); + } + await tx + .update(emailReceipts) + .set({ status: 'delivery_completed', final_reject: input.reject }) + .where(eq(emailReceipts.id, input.receiptId)); + }); +} + +export async function getProjectEmailUsage(db: Db, projectId: string) { + const now = new Date(); + const [controls] = await db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + .limit(1); + const [monthly] = await db + .select() + .from(emailMonthlyUsage) + .where( + and( + eq(emailMonthlyUsage.project_id, projectId), + eq(emailMonthlyUsage.month, monthStart(now).slice(0, 7)), + ), + ); + const [received] = await db + .select({ n: count() }) + .from(emailReceipts) + .where( + and(eq(emailReceipts.project_id, projectId), gte(emailReceipts.created_at, monthStart(now))), + ); + const limit = controls?.monthly_limit ?? 200; + const sent = monthly?.recipient_attempts ?? 0; + return { + month: monthStart(now).slice(0, 7), + sent, + received: received?.n ?? 0, + limit, + remaining: Math.max(0, limit - sent), + suspended: !!controls?.suspended_at, + }; +} + +export async function getProjectEmailLogs(db: Db, projectId: string, limit = 50) { + const cap = Math.max(1, Math.min(limit, 100)); + const rows = await db + .select({ action: emailActions, recipient: emailActionRecipients }) + .from(emailActionRecipients) + .innerJoin(emailActions, eq(emailActions.id, emailActionRecipients.action_id)) + .where(eq(emailActions.project_id, projectId)) + .orderBy(desc(emailActions.created_at)) + .limit(cap); + const receipts = await db + .select() + .from(emailReceipts) + .where(eq(emailReceipts.project_id, projectId)) + .orderBy(desc(emailReceipts.created_at)) + .limit(cap); + return { + logs: [ + ...rows.map(({ action, recipient }) => ({ + timestamp: Date.parse(action.created_at), + direction: 'sent' as const, + operationId: action.id, + receiptId: action.receipt_id, + recipient: recipient.recipient, + status: recipient.state, + transport: action.transport, + providerReference: recipient.provider_reference, + errorCode: recipient.error_code, + policyVersion: action.policy_version, + })), + ...receipts.map((receipt) => ({ + timestamp: Date.parse(receipt.created_at), + direction: 'received' as const, + operationId: receipt.id, + receiptId: receipt.id, + recipient: null, + status: receipt.status, + transport: 'email_event', + providerReference: null, + errorCode: null, + policyVersion: null, + })), + ] + .sort((a, b) => b.timestamp - a.timestamp) + .slice(0, cap), + }; +} + +export async function pruneEmailActionHistory( + db: Db, + before: Date = new Date(Date.now() - 30 * 86_400_000), +) { + // Active calls leave PII-free tombstones; delivery metadata expires normally. + await db.delete(emailActions).where(sql` + ${emailActions.created_at} < ${before.toISOString()} + `); + await db.delete(emailReceipts).where(sql`${emailReceipts.created_at} < ${before.toISOString()}`); +} diff --git a/platform/packages/api/src/email/cf-customer.ts b/platform/packages/api/src/email/cf-customer.ts index 5ac5d5901..53a89a195 100644 --- a/platform/packages/api/src/email/cf-customer.ts +++ b/platform/packages/api/src/email/cf-customer.ts @@ -19,9 +19,11 @@ import { CloudflareApiError } from '../provisioning/cloudflare-api.ts'; import { - RELAY_EMAIL_DOMAIN_BINDING, - RELAY_PROXY_ORIGIN_BINDING, + RELAY_ACCOUNT_BINDING, + RELAY_GATEWAY_ORIGIN_BINDING, + RELAY_INGRESS_BINDING, RELAY_SECRET_BINDING, + RELAY_ZONE_BINDING, } from './relay-worker.ts'; export const CF_CUSTOMER_API_BASE = 'https://api.cloudflare.com/client/v4'; @@ -83,10 +85,13 @@ export type RelayScriptUpload = Readonly<{ /** Module-syntax worker source (RELAY_SOURCE). */ source: string; compatibilityDate: string; - /** Declared as the VOID_PROXY_ORIGIN plain-text var. */ - proxyOrigin: string; - /** Declared as the VOID_EMAIL_DOMAIN plain-text var. */ - emailDomain: string; + gatewayOrigin?: string; + accountId?: string; + zoneId?: string; + ingressName?: string; + /** Pre-release call sites still pass these while migration is in progress. */ + proxyOrigin?: string; + emailDomain?: string; }>; export type SendRawMessage = Readonly<{ @@ -104,6 +109,11 @@ export type CfCatchAllRule = Readonly<{ /** The worker name a 'worker' action points at; null for any other action shape. */ workerName: string | null; }>; +export type CfEmailRoutingRule = Readonly<{ + enabled: boolean; + name: string | null; + addresses: ReadonlyArray; +}>; /** One entry of the sending-subdomain list; name + enabled are required on the wire. */ export type CfSendingSubdomain = Readonly<{ @@ -145,6 +155,10 @@ export type CfCustomerClient = Readonly<{ ) => Promise; /** PUT .../secrets — the non-namespace variant of putWorkerSecret (project-secrets.ts). */ putRelaySecret: (accountId: string, scriptName: string, secret: string) => Promise; + /** Public probe routing for the deployed ingress Worker. */ + getWorkersSubdomain: (accountId: string) => Promise; + getScriptSubdomainEnabled: (accountId: string, scriptName: string) => Promise; + enableScriptSubdomain: (accountId: string, scriptName: string) => Promise; /** PUT catch-all pointing the zone at the relay. `value` is a one-entry array, one action only. */ setCatchAll: (zoneId: string, relayWorkerName: string) => Promise; /** @@ -154,6 +168,8 @@ export type CfCustomerClient = Readonly<{ * write what they own. 404 → null. */ getCatchAll: (zoneId: string) => Promise; + /** Enabled explicit address rules outrank a zone catch-all. */ + listRoutingRules: (zoneId: string) => Promise>; /** PUT catch-all with wrangler's reset shape: one drop action, disabled. */ resetCatchAll: (zoneId: string) => Promise; /** @@ -253,8 +269,18 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { main_module: 'index.js', compatibility_date: upload.compatibilityDate, bindings: [ - { type: 'plain_text', name: RELAY_PROXY_ORIGIN_BINDING, text: upload.proxyOrigin }, - { type: 'plain_text', name: RELAY_EMAIL_DOMAIN_BINDING, text: upload.emailDomain }, + { + type: 'plain_text', + name: RELAY_GATEWAY_ORIGIN_BINDING, + text: upload.gatewayOrigin ?? upload.proxyOrigin, + }, + { type: 'plain_text', name: RELAY_ACCOUNT_BINDING, text: upload.accountId ?? accountId }, + { type: 'plain_text', name: RELAY_ZONE_BINDING, text: upload.zoneId ?? '' }, + { + type: 'plain_text', + name: RELAY_INGRESS_BINDING, + text: upload.ingressName ?? scriptName, + }, ], }; const formData = new FormData(); @@ -280,6 +306,28 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { }); }, + getWorkersSubdomain: async (accountId) => { + const result = await call<{ subdomain: string }>(`/accounts/${accountId}/workers/subdomain`); + if (!result?.subdomain) { + throw new Error('Cloudflare Workers account subdomain is unavailable'); + } + return result.subdomain; + }, + + getScriptSubdomainEnabled: async (accountId, scriptName) => { + const result = await call<{ enabled: boolean }>( + `/accounts/${accountId}/workers/scripts/${scriptName}/subdomain`, + ); + return result.enabled === true; + }, + + enableScriptSubdomain: async (accountId, scriptName) => { + await call(`/accounts/${accountId}/workers/scripts/${scriptName}/subdomain`, { + method: 'POST', + body: JSON.stringify({ enabled: true, previews_enabled: false }), + }); + }, + setCatchAll: async (zoneId, relayWorkerName) => { await call(`/zones/${zoneId}/email/routing/rules/catch_all`, { method: 'PUT', @@ -317,6 +365,47 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { return { enabled: (rule as { enabled?: unknown }).enabled === true, workerName }; }, + listRoutingRules: async (zoneId) => { + const rules: Array = []; + for (let page = 1; page <= 20; page++) { + const result = await call( + `/zones/${zoneId}/email/routing/rules?page=${page}&per_page=50`, + ); + if (!Array.isArray(result)) { + throw new Error('Cloudflare routing rules response was not an array'); + } + for (const value of result) { + if (!value || typeof value !== 'object') { + continue; + } + const rule = value as { enabled?: unknown; name?: unknown; matchers?: unknown }; + const addresses = Array.isArray(rule.matchers) + ? rule.matchers.flatMap((matcher: unknown) => { + if (!matcher || typeof matcher !== 'object') { + return []; + } + const m = matcher as { type?: unknown; field?: unknown; value?: unknown }; + return m.type === 'literal' && typeof m.value === 'string' + ? [m.value.toLowerCase()] + : []; + }) + : []; + rules.push({ + enabled: rule.enabled === true, + name: typeof rule.name === 'string' ? rule.name : null, + addresses, + }); + } + if (result.length < 50) { + break; + } + if (page === 20) { + throw new Error('Cloudflare routing rule list exceeded 1,000 entries'); + } + } + return rules; + }, + resetCatchAll: async (zoneId) => { await call(`/zones/${zoneId}/email/routing/rules/catch_all`, { method: 'PUT', diff --git a/platform/packages/api/src/email/connection-schema.ts b/platform/packages/api/src/email/connection-schema.ts new file mode 100644 index 000000000..971f5eee2 --- /dev/null +++ b/platform/packages/api/src/email/connection-schema.ts @@ -0,0 +1,231 @@ +import { sql } from 'drizzle-orm'; +import { + check, + index, + integer, + jsonb, + pgTable, + text, + timestamp, + uniqueIndex, +} from 'drizzle-orm/pg-core'; +// Ownership IDs remain as audit identities after a user or project is deleted; +// authorization always joins the current user/project records. + +/** One Cloudflare catch-all and ingress Worker per account/zone in an installation. */ +export const emailZoneConnections = pgTable( + 'email_zone_connections', + { + id: text('id').primaryKey(), + installation_id: text('installation_id').notNull(), + account_id: text('account_id').notNull(), + zone_id: text('zone_id').notNull(), + zone_name: text('zone_name').notNull(), + managed_by: text('managed_by').notNull().$type<'owner' | 'admin'>(), + manager_user_id: text('manager_user_id'), + credential_id: text('credential_id'), + ingress_worker_name: text('ingress_worker_name').notNull(), + ingress_version: integer('ingress_version'), + desired_generation: integer('desired_generation').notNull().default(1), + active_secret_generation: integer('active_secret_generation').notNull().default(0), + staged_secret_generation: integer('staged_secret_generation'), + secret_ciphertext: text('secret_ciphertext').notNull(), + secret_iv: text('secret_iv').notNull(), + secret_key_version: text('secret_key_version').notNull(), + staged_secret_ciphertext: text('staged_secret_ciphertext'), + staged_secret_iv: text('staged_secret_iv'), + staged_secret_key_version: text('staged_secret_key_version'), + previous_secret_hash: text('previous_secret_hash'), + previous_secret_until: timestamp('previous_secret_until', { mode: 'string' }), + inbound_status: text('inbound_status') + .notNull() + .default('pending') + .$type<'pending' | 'ready' | 'disabled' | 'drifted'>(), + inbound_reason: text('inbound_reason'), + inbound_observed_at: timestamp('inbound_observed_at', { mode: 'string' }), + management_status: text('management_status') + .notNull() + .default('probe_failed') + .$type<'healthy' | 'expired' | 'revoked' | 'refresh_unknown' | 'probe_failed'>(), + management_reason: text('management_reason'), + management_observed_at: timestamp('management_observed_at', { mode: 'string' }), + created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + }, + (table) => [ + uniqueIndex('email_zone_connections_zone_uq').on( + table.installation_id, + table.account_id, + table.zone_id, + ), + uniqueIndex('email_zone_connections_ingress_uq').on( + table.account_id, + table.ingress_worker_name, + ), + index('email_zone_connections_manager_idx').on(table.manager_user_id), + check( + 'email_zone_connections_manager_check', + sql`(${table.managed_by} = 'owner' AND ${table.manager_user_id} IS NOT NULL) OR (${table.managed_by} = 'admin')`, + ), + ], +); + +/** An exact SMTP envelope domain, with a single project assignment or shared addressing. */ +export const emailDomainRoutes = pgTable( + 'email_domain_routes', + { + id: text('id').primaryKey(), + domain: text('domain').notNull(), + connection_id: text('connection_id') + .notNull() + .references(() => emailZoneConnections.id), + project_id: text('project_id'), + addressing: text('addressing').notNull().$type<'custom' | 'shared'>(), + managed_by: text('managed_by').notNull().$type<'owner' | 'admin'>(), + assigned_by_user_id: text('assigned_by_user_id'), + desired_state: text('desired_state') + .notNull() + .default('active') + .$type<'active' | 'disabled' | 'removed'>(), + inbound_status: text('inbound_status') + .notNull() + .default('pending') + .$type<'pending' | 'ready' | 'disabled' | 'drifted'>(), + inbound_reason: text('inbound_reason'), + inbound_observed_at: timestamp('inbound_observed_at', { mode: 'string' }), + outbound_status: text('outbound_status') + .notNull() + .default('pending') + .$type<'pending' | 'verified_only' | 'ready' | 'blocked'>(), + outbound_reason: text('outbound_reason'), + outbound_observed_at: timestamp('outbound_observed_at', { mode: 'string' }), + desired_generation: integer('desired_generation').notNull().default(1), + created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + }, + (table) => [ + uniqueIndex('email_domain_routes_domain_uq').on(table.domain), + index('email_domain_routes_connection_idx').on(table.connection_id), + index('email_domain_routes_project_idx').on(table.project_id), + check( + 'email_domain_routes_assignment_check', + sql`(${table.addressing} = 'custom' AND ${table.project_id} IS NOT NULL) OR (${table.addressing} = 'shared' AND ${table.project_id} IS NULL)`, + ), + ], +); + +export const emailCredentials = pgTable( + 'email_credentials', + { + id: text('id').primaryKey(), + installation_id: text('installation_id').notNull(), + managed_by: text('managed_by').notNull().$type<'owner' | 'admin'>(), + manager_user_id: text('manager_user_id'), + kind: text('kind').notNull().$type<'api_token' | 'platform'>(), + account_id: text('account_id').notNull(), + zone_id: text('zone_id').notNull(), + ciphertext: text('ciphertext'), + iv: text('iv'), + key_version: text('key_version'), + token_id: text('token_id'), + expires_on: timestamp('expires_on', { mode: 'string' }), + generation: integer('generation').notNull().default(1), + status: text('status') + .notNull() + .default('healthy') + .$type<'healthy' | 'expired' | 'revoked' | 'probe_failed'>(), + created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + }, + (table) => [ + index('email_credentials_scope_idx').on(table.installation_id, table.account_id, table.zone_id), + check( + 'email_credentials_material_check', + sql`(${table.kind} = 'platform' AND ${table.ciphertext} IS NULL AND ${table.iv} IS NULL AND ${table.key_version} IS NULL) OR (${table.kind} = 'api_token' AND ${table.ciphertext} IS NOT NULL AND ${table.iv} IS NOT NULL AND ${table.key_version} IS NOT NULL)`, + ), + ], +); + +export const emailOperations = pgTable( + 'email_operations', + { + id: text('id').primaryKey(), + installation_id: text('installation_id').notNull(), + connection_id: text('connection_id') + .notNull() + .references(() => emailZoneConnections.id), + route_id: text('route_id').references(() => emailDomainRoutes.id, { onDelete: 'set null' }), + actor_kind: text('actor_kind').notNull().$type<'owner' | 'admin' | 'system'>(), + actor_user_id: text('actor_user_id'), + actor_scope: text('actor_scope').notNull(), + kind: text('kind').notNull().$type<'setup' | 'sync' | 'remove' | 'rotate_secret' | 'cleanup'>(), + idempotency_key: text('idempotency_key').notNull(), + request_digest: text('request_digest').notNull(), + desired_generation: integer('desired_generation').notNull(), + status: text('status') + .notNull() + .default('pending') + .$type<'pending' | 'running' | 'blocked' | 'unknown' | 'completed'>(), + current_step: text('current_step'), + failure_code: text('failure_code'), + failure_detail: text('failure_detail'), + created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + }, + (table) => [ + uniqueIndex('email_operations_key_uq').on( + table.installation_id, + table.actor_scope, + table.idempotency_key, + ), + index('email_operations_work_idx').on(table.status, table.updated_at), + index('email_operations_connection_idx').on(table.connection_id), + ], +); + +export const emailOperationSteps = pgTable( + 'email_operation_steps', + { + id: text('id').primaryKey(), + operation_id: text('operation_id') + .notNull() + .references(() => emailOperations.id), + ordinal: integer('ordinal').notNull(), + kind: text('kind').notNull(), + resource_identity: text('resource_identity').notNull(), + request_digest: text('request_digest').notNull(), + attempt: integer('attempt').notNull().default(0), + status: text('status') + .notNull() + .default('pending') + .$type<'pending' | 'in_flight' | 'confirmed' | 'blocked' | 'unknown'>(), + outcome: jsonb('outcome').$type | null>(), + failure_code: text('failure_code'), + failure_detail: text('failure_detail'), + started_at: timestamp('started_at', { mode: 'string' }), + finished_at: timestamp('finished_at', { mode: 'string' }), + }, + (table) => [uniqueIndex('email_operation_steps_order_uq').on(table.operation_id, table.ordinal)], +); + +export const emailCacheOutbox = pgTable( + 'email_cache_outbox', + { + id: text('id').primaryKey(), + installation_id: text('installation_id').notNull(), + resource_kind: text('resource_kind').notNull(), + resource_id: text('resource_id').notNull(), + version: integer('version').notNull(), + payload: jsonb('payload').$type | null>(), + published_at: timestamp('published_at', { mode: 'string' }), + created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), + }, + (table) => [ + uniqueIndex('email_cache_outbox_version_uq').on( + table.resource_kind, + table.resource_id, + table.version, + ), + index('email_cache_outbox_pending_idx').on(table.published_at, table.created_at), + ], +); diff --git a/platform/packages/api/src/email/connection-service.ts b/platform/packages/api/src/email/connection-service.ts new file mode 100644 index 000000000..45abb25ca --- /dev/null +++ b/platform/packages/api/src/email/connection-service.ts @@ -0,0 +1,2107 @@ +import { and, count, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm'; +import type { Db, DbOrTx } from '../db.ts'; +import type { ApiEnv } from '../env.ts'; +import { generateId } from '../id.ts'; +import { decryptPlatformCredential, encryptPlatformCredential } from '../project-secrets.ts'; +import { projects } from '../schema.ts'; +import { emailUnresolvedAttempts } from './admission-schema.ts'; +import { disableEmailDomainRouteAndDrainTx } from './admission.ts'; +import { createCfCustomerClient } from './cf-customer.ts'; +import { + emailCacheOutbox, + emailCredentials, + emailDomainRoutes, + emailOperations, + emailOperationSteps, + emailZoneConnections, +} from './connection-schema.ts'; +import { isValidEmailDomain, normalizeEmailDomain } from './domain-name.ts'; +import { + findZoneForEmailDomain, + lookupMxOverDns, + sendingOnboardedReadback, +} from './relay-engine.ts'; +import { RELAY_COMPATIBILITY_DATE, RELAY_SOURCE, RELAY_VERSION } from './relay-worker.ts'; + +type Bindings = ApiEnv['Bindings']; +export type EmailActor = + | { kind: 'owner'; userId: string } + | { kind: 'admin'; userId: string } + | { kind: 'system' }; +export class EmailOperationError extends Error { + constructor( + message: string, + readonly status = 409, + ) { + super(message); + } +} + +const SETUP_STEPS = [ + 'routing_enable', + 'ingress_deploy', + 'probe_route_enable', + 'secret_put', + 'relay_probe', + 'gateway_probe', + 'catchall_ensure', + 'inbound_probe', + 'sending_onboard', + 'publish', +] as const; +const SYNC_STEPS = [ + 'ingress_deploy', + 'probe_route_enable', + 'relay_probe', + 'gateway_probe', + 'catchall_ensure', + 'inbound_probe', + 'sending_onboard', + 'publish', +] as const; +const SIBLING_STEPS = [ + 'routing_enable', + 'gateway_probe', + 'inbound_probe', + 'sending_onboard', + 'publish', +] as const; +const SHARED_SYNC_STEPS = [ + 'routing_enable', + 'inbound_probe', + 'sending_onboard', + 'publish', +] as const; +const REMOVE_STEPS = ['route_disable', 'catchall_detach', 'ingress_delete', 'publish'] as const; +const ROTATE_STEPS = [ + 'secret_put', + 'relay_probe', + 'gateway_probe', + 'secret_promote', + 'publish', +] as const; +type StepKind = + | (typeof SETUP_STEPS)[number] + | (typeof REMOVE_STEPS)[number] + | (typeof ROTATE_STEPS)[number]; + +export function emailInstallationId(env: Bindings): string { + return env.PLATFORM_INSTALLATION_ID ?? 'void-hosted'; +} +function gatewayOrigin(env: Bindings): string { + const origin = (env as Bindings & { EMAIL_GATEWAY_ORIGIN?: string }).EMAIL_GATEWAY_ORIGIN; + if (!origin || !/^https:\/\/[^/]+$/i.test(origin)) { + throw new EmailOperationError( + 'EMAIL_GATEWAY_ORIGIN must be configured before email ingress setup', + 503, + ); + } + return origin; +} +async function digest(value: unknown): Promise { + const bytes = new TextEncoder().encode(JSON.stringify(value)); + return Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)), (x) => + x.toString(16).padStart(2, '0'), + ).join(''); +} +function randomSecret(): string { + const bytes = crypto.getRandomValues(new Uint8Array(32)); + return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join(''); +} +function constantTimeHexEqual(a: string, b: string): boolean { + if (a.length !== b.length) { + return false; + } + let diff = 0; + for (let i = 0; i < a.length; i++) { + diff |= a.charCodeAt(i) ^ b.charCodeAt(i); + } + return diff === 0; +} +async function relayProof( + secret: string, + connection: typeof emailZoneConnections.$inferSelect, + generation: number, + challenge: string, +): Promise { + const data = [ + 'email-relay-proof-v1', + connection.account_id, + connection.zone_id, + connection.ingress_worker_name, + String(generation), + challenge, + ].join('\n'); + const key = await crypto.subtle.importKey( + 'raw', + new TextEncoder().encode(secret), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign'], + ); + return Array.from( + new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data))), + (b) => b.toString(16).padStart(2, '0'), + ).join(''); +} +async function probeDeployedRelay( + client: ReturnType, + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, + staged: boolean, +): Promise> { + if ( + !(await client.getScriptSubdomainEnabled(connection.account_id, connection.ingress_worker_name)) + ) { + throw new EmailOperationError('ingress probe endpoint is disabled', 503); + } + const subdomain = await client.getWorkersSubdomain(connection.account_id); + if (!/^[a-z0-9-]+$/i.test(subdomain)) { + throw new EmailOperationError('invalid Cloudflare Workers subdomain', 503); + } + const generation = staged + ? connection.staged_secret_generation + : connection.active_secret_generation; + if (generation === null) { + throw new EmailOperationError('staged ingress generation is absent'); + } + const secret = staged + ? await readStagedConnectionSecret(env, connection) + : await readConnectionSecret(env, connection); + const challenge = randomSecret(); + const response = await fetch( + `https://${connection.ingress_worker_name}.${subdomain}.workers.dev/__void/email/probe`, + { + method: 'POST', + headers: { + 'X-Void-Probe-Challenge': challenge, + 'X-Void-Probe-Generation': String(generation), + }, + signal: AbortSignal.timeout(10_000), + }, + ); + if (!response.ok) { + throw new EmailOperationError(`deployed ingress probe returned HTTP ${response.status}`, 503); + } + if (!response.body) { + throw new EmailOperationError('deployed ingress proof body is empty', 503); + } + const reader = response.body.getReader(); + const chunks: Array = []; + let length = 0; + try { + for (;;) { + const { done, value } = await reader.read(); + if (done) { + break; + } + length += value.byteLength; + if (length > 2048) { + throw new EmailOperationError('deployed ingress proof is too large', 503); + } + chunks.push(value); + } + } finally { + await reader.cancel().catch(() => {}); + } + const bytes = new Uint8Array(length); + let offset = 0; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.byteLength; + } + let body: { + accountId?: unknown; + zoneId?: unknown; + ingressName?: unknown; + generation?: unknown; + challenge?: unknown; + proof?: unknown; + }; + try { + body = JSON.parse(new TextDecoder().decode(bytes)); + } catch { + throw new EmailOperationError('deployed ingress proof is invalid', 503); + } + if (!body || typeof body !== 'object' || Array.isArray(body)) { + throw new EmailOperationError('deployed ingress proof is invalid', 503); + } + if ( + body.accountId !== connection.account_id || + body.zoneId !== connection.zone_id || + body.ingressName !== connection.ingress_worker_name || + body.generation !== generation || + body.challenge !== challenge || + typeof body.proof !== 'string' || + !constantTimeHexEqual(body.proof, await relayProof(secret, connection, generation, challenge)) + ) { + throw new EmailOperationError('deployed ingress proof did not match staged identity', 503); + } + return { generation, workerName: connection.ingress_worker_name, proved: true }; +} +async function probeGatewayAcceptance( + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, + staged: boolean, +): Promise> { + const secret = staged + ? await readStagedConnectionSecret(env, connection) + : await readConnectionSecret(env, connection); + const payload = JSON.stringify({ + accountId: connection.account_id, + zoneId: connection.zone_id, + ingressName: connection.ingress_worker_name, + }); + const response = await fetch(`${gatewayOrigin(env)}/email/probe`, { + method: 'POST', + headers: { + Authorization: `Bearer ${secret}`, + 'Content-Type': 'application/json', + 'Content-Length': String(new TextEncoder().encode(payload).byteLength), + }, + body: payload, + signal: AbortSignal.timeout(10_000), + }); + await response.body?.cancel(); + if (response.status !== 204) { + throw new EmailOperationError( + `email gateway rejected ingress identity with HTTP ${response.status}`, + 503, + ); + } + return { + accepted: true, + generation: staged ? connection.staged_secret_generation : connection.active_secret_generation, + }; +} +function ingressName(installationId: string, zoneId: string): string { + // Stable, bounded, and owned by an installation/zone rather than a project. + const suffix = [installationId, zoneId] + .join('-') + .toLowerCase() + .replace(/[^a-z0-9-]/g, '-') + .slice(-48); + return `void-email-${suffix}`; +} +function isSharedGatewayConnection( + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, +): boolean { + const shared = env as Bindings & { + EMAIL_SHARED_ACCOUNT_ID?: string; + EMAIL_SHARED_ZONE_ID?: string; + EMAIL_SHARED_INGRESS_NAME?: string; + }; + return ( + !!shared.EMAIL_SHARED_ACCOUNT_ID && + !!shared.EMAIL_SHARED_ZONE_ID && + !!shared.EMAIL_SHARED_INGRESS_NAME && + connection.account_id === shared.EMAIL_SHARED_ACCOUNT_ID && + connection.zone_id === shared.EMAIL_SHARED_ZONE_ID && + connection.ingress_worker_name === shared.EMAIL_SHARED_INGRESS_NAME + ); +} +function canManageConnection( + actor: EmailActor, + connection: typeof emailZoneConnections.$inferSelect, +): boolean { + if (actor.kind === 'system') { + return true; + } + return ( + connection.managed_by === actor.kind && + (actor.kind === 'admin' || connection.manager_user_id === actor.userId) + ); +} + +export async function resolveEmailDomain(db: DbOrTx, rawDomain: string) { + const domain = normalizeEmailDomain(rawDomain); + const rows = await db + .select({ route: emailDomainRoutes, connection: emailZoneConnections }) + .from(emailDomainRoutes) + .innerJoin(emailZoneConnections, eq(emailDomainRoutes.connection_id, emailZoneConnections.id)) + .where(eq(emailDomainRoutes.domain, domain)) + .limit(1); + return rows[0] ?? null; +} + +export async function resolveEmailIngress( + db: DbOrTx, + input: { + installationId: string; + accountId: string; + zoneId: string; + ingressName: string; + recipient: string; + }, +) { + const at = input.recipient.lastIndexOf('@'); + if (at <= 0) { + return null; + } + const found = await resolveEmailDomain(db, input.recipient.slice(at + 1)); + if ( + !found || + found.route.desired_state !== 'active' || + found.route.inbound_status !== 'ready' || + found.connection.inbound_status !== 'ready' + ) { + return null; + } + if ( + found.connection.installation_id !== input.installationId || + found.connection.account_id !== input.accountId || + found.connection.zone_id !== input.zoneId || + found.connection.ingress_worker_name !== input.ingressName + ) { + return null; + } + if (found.route.addressing === 'custom' && !found.route.project_id) { + return null; + } + return found; +} + +export async function credentialFor( + env: Bindings, + db: DbOrTx, + connection: typeof emailZoneConnections.$inferSelect, +): Promise { + if (!connection.credential_id) { + throw new EmailOperationError('email connection has no credential', 503); + } + const row = ( + await db + .select() + .from(emailCredentials) + .where(eq(emailCredentials.id, connection.credential_id)) + .limit(1) + )[0]; + if ( + !row || + row.status !== 'healthy' || + row.installation_id !== connection.installation_id || + row.account_id !== connection.account_id || + row.zone_id !== connection.zone_id + ) { + throw new EmailOperationError('email connection credential is unavailable', 503); + } + if (row.kind === 'platform') { + if (connection.account_id !== env.CF_ACCOUNT_ID || !env.CF_API_TOKEN) { + throw new EmailOperationError('platform credential cannot manage this zone', 403); + } + return env.CF_API_TOKEN; + } + if (!row.ciphertext || !row.iv || !row.key_version) { + throw new EmailOperationError('stored email credential is incomplete', 503); + } + return decryptPlatformCredential(env, row.installation_id, row.id, { + ciphertext: row.ciphertext, + iv: row.iv, + keyVersion: row.key_version, + }); +} + +export async function readConnectionSecret( + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, +): Promise { + return decryptPlatformCredential( + env, + connection.installation_id, + `${connection.id}:secret:${connection.active_secret_generation}`, + { + ciphertext: connection.secret_ciphertext, + iv: connection.secret_iv, + keyVersion: connection.secret_key_version, + }, + ); +} +export async function readStagedConnectionSecret( + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, +): Promise { + if ( + connection.staged_secret_generation === null || + !connection.staged_secret_ciphertext || + !connection.staged_secret_iv || + !connection.staged_secret_key_version + ) { + throw new EmailOperationError('no staged ingress secret', 409); + } + return decryptPlatformCredential( + env, + connection.installation_id, + `${connection.id}:secret:${connection.staged_secret_generation}`, + { + ciphertext: connection.staged_secret_ciphertext, + iv: connection.staged_secret_iv, + keyVersion: connection.staged_secret_key_version, + }, + ); +} + +export async function requestEmailDomainAdd( + db: Db, + env: Bindings, + input: { + projectId: string; + domain: string; + actor: EmailActor; + token?: string; + attemptId?: string; + }, +): Promise<{ operationId: string; routeId: string }> { + const domain = normalizeEmailDomain(input.domain); + if (!isValidEmailDomain(domain)) { + throw new EmailOperationError('invalid email domain', 400); + } + if (input.actor.kind === 'system') { + throw new EmailOperationError('system cannot assign project email domains', 403); + } + const actor = input.actor as Exclude; + const installationId = emailInstallationId(env); + const key = input.attemptId ?? generateId('eadd'); + const actorScope = `${actor.kind}:${actor.userId}:${input.projectId}`; + const requestDigest = await digest({ + projectId: input.projectId, + domain, + actor: input.actor.kind, + tokenDigest: input.token ? await digest(input.token) : null, + }); + const previous = ( + await db + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, actorScope), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (previous) { + if (previous.request_digest !== requestDigest || !previous.route_id) { + throw new EmailOperationError('email operation key was reused with a different request'); + } + return { operationId: previous.id, routeId: previous.route_id }; + } + if (!input.token && input.actor.kind === 'owner') { + throw new EmailOperationError('a scoped Cloudflare API token is required', 400); + } + const token = input.token ?? env.CF_API_TOKEN; + if (!token) { + throw new EmailOperationError('platform Cloudflare credential is unavailable', 503); + } + const client = createCfCustomerClient(token); + const zone = await findZoneForEmailDomain(client, domain); + if (!zone) { + throw new EmailOperationError(`no Cloudflare zone found for ${domain}`, 404); + } + const shared = env as Bindings & { + EMAIL_SHARED_ACCOUNT_ID?: string; + EMAIL_SHARED_ZONE_ID?: string; + EMAIL_SHARED_INGRESS_NAME?: string; + }; + if ( + zone.account.id === shared.EMAIL_SHARED_ACCOUNT_ID && + zone.id === shared.EMAIL_SHARED_ZONE_ID + ) { + if (actor.kind !== 'admin') { + throw new EmailOperationError( + 'the installation shared mail zone is administrator-managed', + 403, + ); + } + const bootstrap = await ensureSharedEmailConnection(db, env); + if (bootstrap) { + await runEmailOperation(db, env, bootstrap); + } + } + if (!input.token && zone.account.id !== env.CF_ACCOUNT_ID) { + throw new EmailOperationError( + 'administrator must supply a token for this Cloudflare account', + 403, + ); + } + if (input.token) { + const verification = await client.verifyToken(); + if (verification.status !== 'active') { + throw new EmailOperationError('Cloudflare API token is not active', 403); + } + // The actual zone read above proves resource scope more reliably than a template URL. + await client.getRoutingSettings(zone.id); + } + const existingConnection = ( + await db + .select() + .from(emailZoneConnections) + .where( + and( + eq(emailZoneConnections.installation_id, installationId), + eq(emailZoneConnections.account_id, zone.account.id), + eq(emailZoneConnections.zone_id, zone.id), + ), + ) + .limit(1) + )[0]; + if (!existingConnection) { + const preflight = await Promise.all([ + lookupMxOverDns(domain), + client.getCatchAll(zone.id), + client.listRoutingRules(zone.id), + ]); + if (preflight[0].length > 0) { + throw new EmailOperationError( + `${domain} already has MX records; use an unused mail subdomain`, + 409, + ); + } + if (preflight[1]?.enabled && preflight[1].workerName !== ingressName(installationId, zone.id)) { + throw new EmailOperationError( + 'an unrelated catch-all already owns this Cloudflare zone', + 409, + ); + } + const conflicts = preflight[2].filter( + (rule) => rule.enabled && rule.addresses.some((address) => address.endsWith(`@${domain}`)), + ); + if (conflicts.length > 0) { + throw new EmailOperationError( + `enabled explicit Cloudflare email rules conflict with ${domain}`, + 409, + ); + } + } + gatewayOrigin(env); + const connectionId = generateId('econ'); + const routeId = generateId('eroute'); + const operationId = generateId('eop'); + const credentialId = generateId('ecred'); + const secret = randomSecret(); + const encryptedSecret = await encryptPlatformCredential( + env, + installationId, + `${connectionId}:secret:1`, + secret, + ); + const encryptedToken = input.token + ? await encryptPlatformCredential(env, installationId, credentialId, token) + : null; + try { + return await db.transaction(async (tx) => { + const project = ( + await tx + .select() + .from(projects) + .where(eq(projects.id, input.projectId)) + .for('update') + .limit(1) + )[0]; + if (!project || project.status === 'deleting') { + throw new EmailOperationError('project not available', 409); + } + if (actor.kind === 'owner' && project.user_id !== actor.userId) { + throw new EmailOperationError('forbidden', 403); + } + const existingRoute = ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.domain, domain)) + .limit(1) + )[0]; + if (existingRoute && existingRoute.project_id !== input.projectId) { + throw new EmailOperationError('email domain is assigned to another project', 409); + } + let connection = ( + await tx + .select() + .from(emailZoneConnections) + .where( + and( + eq(emailZoneConnections.installation_id, installationId), + eq(emailZoneConnections.account_id, zone.account.id), + eq(emailZoneConnections.zone_id, zone.id), + ), + ) + .for('update') + .limit(1) + )[0]; + const created = !connection; + if (connection && !canManageConnection(actor, connection)) { + throw new EmailOperationError('zone connection requires its manager approval', 403); + } + if (connection) { + const unresolved = ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connection.id), + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + ), + ) + .limit(1) + )[0]; + if (unresolved) { + throw new EmailOperationError(`connection operation ${unresolved.id} is unresolved`); + } + } + if (existingRoute) { + if ( + !connection || + !canManageConnection(actor, connection) || + existingRoute.managed_by !== actor.kind + ) { + throw new EmailOperationError( + 'email domain credential may be replaced only by its connection manager', + 403, + ); + } + if (!connection.credential_id) { + throw new EmailOperationError('connection credential missing', 503); + } + const replacement = input.token + ? await encryptPlatformCredential( + env, + installationId, + connection.credential_id, + input.token, + ) + : null; + await tx + .update(emailCredentials) + .set({ + kind: input.token ? 'api_token' : 'platform', + ciphertext: replacement?.ciphertext ?? null, + iv: replacement?.iv ?? null, + key_version: replacement?.keyVersion ?? null, + status: 'healthy', + generation: sql`${emailCredentials.generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailCredentials.id, connection.credential_id)); + const generation = connection.desired_generation + 1; + await tx + .update(emailZoneConnections) + .set({ + desired_generation: generation, + management_status: 'healthy', + management_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connection.id)); + await tx + .update(emailDomainRoutes) + .set({ desired_state: 'active', updated_at: sql`now()` }) + .where(eq(emailDomainRoutes.id, existingRoute.id)); + await tx.insert(emailOperations).values({ + id: operationId, + installation_id: installationId, + connection_id: connection.id, + route_id: existingRoute.id, + actor_kind: actor.kind, + actor_user_id: actor.userId, + actor_scope: actorScope, + kind: 'sync', + idempotency_key: key, + request_digest: requestDigest, + desired_generation: generation, + }); + for (let i = 0; i < SYNC_STEPS.length; i++) { + await tx.insert(emailOperationSteps).values({ + id: generateId('estep'), + operation_id: operationId, + ordinal: i, + kind: SYNC_STEPS[i], + resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, + request_digest: await digest({ + kind: SYNC_STEPS[i], + connectionId: connection.id, + generation, + }), + }); + } + return { operationId, routeId: existingRoute.id }; + } + if (!connection) { + await tx.insert(emailCredentials).values({ + id: credentialId, + installation_id: installationId, + managed_by: actor.kind, + manager_user_id: actor.kind === 'owner' ? actor.userId : null, + kind: input.token ? 'api_token' : 'platform', + account_id: zone.account.id, + zone_id: zone.id, + ciphertext: encryptedToken?.ciphertext ?? null, + iv: encryptedToken?.iv ?? null, + key_version: encryptedToken?.keyVersion ?? null, + }); + await tx.insert(emailZoneConnections).values({ + id: connectionId, + installation_id: installationId, + account_id: zone.account.id, + zone_id: zone.id, + zone_name: zone.name, + managed_by: actor.kind, + manager_user_id: actor.kind === 'owner' ? actor.userId : null, + credential_id: credentialId, + ingress_worker_name: ingressName(installationId, zone.id), + secret_ciphertext: encryptedSecret.ciphertext, + secret_iv: encryptedSecret.iv, + secret_key_version: encryptedSecret.keyVersion, + active_secret_generation: 1, + management_status: 'healthy', + management_observed_at: sql`now()`, + }); + connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connectionId)) + .limit(1) + )[0]!; + } else if (input.token) { + // A sibling assignment supplies the manager's current zone token. + // The connection, rather than either project, owns its ciphertext. + if (!connection.credential_id) { + throw new EmailOperationError('connection credential missing', 503); + } + const replacement = await encryptPlatformCredential( + env, + installationId, + connection.credential_id, + input.token, + ); + await tx + .update(emailCredentials) + .set({ + kind: 'api_token', + ciphertext: replacement.ciphertext, + iv: replacement.iv, + key_version: replacement.keyVersion, + status: 'healthy', + generation: sql`${emailCredentials.generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailCredentials.id, connection.credential_id)); + } + await tx.insert(emailDomainRoutes).values({ + id: routeId, + domain, + connection_id: connection.id, + project_id: input.projectId, + addressing: 'custom', + managed_by: actor.kind, + assigned_by_user_id: actor.userId, + }); + await tx.insert(emailOperations).values({ + id: operationId, + installation_id: installationId, + connection_id: connection.id, + route_id: routeId, + actor_kind: actor.kind, + actor_user_id: actor.userId, + actor_scope: actorScope, + kind: 'setup', + idempotency_key: key, + request_digest: requestDigest, + desired_generation: connection.desired_generation, + }); + const steps = created ? SETUP_STEPS : SIBLING_STEPS; + for (let i = 0; i < steps.length; i++) { + await tx.insert(emailOperationSteps).values({ + id: generateId('estep'), + operation_id: operationId, + ordinal: i, + kind: steps[i], + resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, + request_digest: await digest({ + kind: steps[i], + connectionId: connection.id, + generation: connection.desired_generation, + }), + }); + } + return { operationId, routeId }; + }); + } catch (error) { + // A concurrent insert may have committed the same caller attempt while this + // transaction waited on uniqueness. Fetch it, but never infer success from a domain row. + const winner = ( + await db + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, actorScope), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (winner && winner.request_digest === requestDigest && winner.route_id) { + return { operationId: winner.id, routeId: winner.route_id }; + } + throw error; + } +} + +/** Reserve the installation's shared sender as an exact route on its zone. + * This uses the same durable step runner as project assignments. It is safe to + * call from scheduled reconciliation: the stable key returns the same operation. */ +export async function ensureSharedEmailConnection(db: Db, env: Bindings): Promise { + const configured = env.EMAIL_SENDER_DOMAIN; + if (!configured) { + return null; + } + const shared = env as Bindings & { + EMAIL_SHARED_ACCOUNT_ID?: string; + EMAIL_SHARED_ZONE_ID?: string; + EMAIL_SHARED_INGRESS_NAME?: string; + }; + if ( + !shared.EMAIL_SHARED_ACCOUNT_ID || + !shared.EMAIL_SHARED_ZONE_ID || + !shared.EMAIL_SHARED_INGRESS_NAME + ) { + throw new EmailOperationError('shared email ingress identity is not configured', 503); + } + const domain = normalizeEmailDomain(configured); + if (!isValidEmailDomain(domain)) { + throw new EmailOperationError('EMAIL_SENDER_DOMAIN is invalid', 503); + } + gatewayOrigin(env); + const installationId = emailInstallationId(env); + const key = `shared:${domain}`; + const previous = ( + await db + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, 'system:shared'), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (previous) { + return previous.id; + } + const client = createCfCustomerClient(env.CF_API_TOKEN); + const zone = await findZoneForEmailDomain(client, domain); + if ( + !zone || + zone.account.id !== env.CF_ACCOUNT_ID || + zone.account.id !== shared.EMAIL_SHARED_ACCOUNT_ID || + zone.id !== shared.EMAIL_SHARED_ZONE_ID + ) { + throw new EmailOperationError( + 'shared sender zone does not match the configured gateway identity', + 503, + ); + } + const existingRule = await client.getCatchAll(zone.id); + const worker = shared.EMAIL_SHARED_INGRESS_NAME; + if (existingRule?.enabled && existingRule.workerName !== worker) { + throw new EmailOperationError('shared sender zone has a foreign catch-all', 409); + } + const routeId = generateId('eroute'), + connectionId = generateId('econ'), + credentialId = generateId('ecred'), + operationId = generateId('eop'); + const secret = await encryptPlatformCredential( + env, + installationId, + `${connectionId}:secret:1`, + randomSecret(), + ); + return db.transaction(async (tx) => { + const existingRoute = ( + await tx.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.domain, domain)).limit(1) + )[0]; + if (existingRoute) { + if (existingRoute.addressing !== 'shared') { + throw new EmailOperationError('shared sender domain is assigned to a project'); + } + const latest = ( + await tx + .select() + .from(emailOperations) + .where(eq(emailOperations.route_id, existingRoute.id)) + .orderBy(sql`${emailOperations.created_at} DESC`) + .limit(1) + )[0]; + return latest?.id ?? null; + } + let connection = ( + await tx + .select() + .from(emailZoneConnections) + .where( + and( + eq(emailZoneConnections.installation_id, installationId), + eq(emailZoneConnections.account_id, zone.account.id), + eq(emailZoneConnections.zone_id, zone.id), + ), + ) + .for('update') + .limit(1) + )[0]; + const created = !connection; + if (connection && connection.managed_by !== 'admin') { + throw new EmailOperationError('shared sender zone connection must be administrator-managed'); + } + if (connection && connection.ingress_worker_name !== worker) { + throw new EmailOperationError( + 'shared sender zone is already connected to a different ingress worker', + ); + } + if (!connection) { + await tx.insert(emailCredentials).values({ + id: credentialId, + installation_id: installationId, + managed_by: 'admin', + kind: 'platform', + account_id: zone.account.id, + zone_id: zone.id, + }); + await tx.insert(emailZoneConnections).values({ + id: connectionId, + installation_id: installationId, + account_id: zone.account.id, + zone_id: zone.id, + zone_name: zone.name, + managed_by: 'admin', + credential_id: credentialId, + ingress_worker_name: worker, + secret_ciphertext: secret.ciphertext, + secret_iv: secret.iv, + secret_key_version: secret.keyVersion, + active_secret_generation: 1, + management_status: 'healthy', + management_observed_at: sql`now()`, + }); + connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connectionId)) + .limit(1) + )[0]!; + } + await tx.insert(emailDomainRoutes).values({ + id: routeId, + domain, + connection_id: connection.id, + project_id: null, + addressing: 'shared', + managed_by: 'admin', + desired_state: 'active', + }); + const requestDigest = await digest({ shared: domain, connectionId: connection.id }); + await tx.insert(emailOperations).values({ + id: operationId, + installation_id: installationId, + connection_id: connection.id, + route_id: routeId, + actor_kind: 'system', + actor_scope: 'system:shared', + kind: 'setup', + idempotency_key: key, + request_digest: requestDigest, + desired_generation: connection.desired_generation, + }); + // Native gateway is deployed with the platform. Uploading the customer + // relay source here would replace it and sever shared mail delivery. + const steps = created + ? (['catchall_ensure', 'inbound_probe', 'publish'] as const) + : (['inbound_probe', 'publish'] as const); + for (let i = 0; i < steps.length; i++) { + await tx.insert(emailOperationSteps).values({ + id: generateId('estep'), + operation_id: operationId, + ordinal: i, + kind: steps[i], + resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, + request_digest: await digest({ + kind: steps[i], + connectionId: connection.id, + generation: connection.desired_generation, + }), + }); + } + return operationId; + }); +} + +export async function getEmailOperation(db: DbOrTx, projectId: string, key: string) { + const rows = await db + .select({ operation: emailOperations, route: emailDomainRoutes }) + .from(emailOperations) + .innerJoin(emailDomainRoutes, eq(emailOperations.route_id, emailDomainRoutes.id)) + .where( + and( + eq(emailDomainRoutes.project_id, projectId), + sql`(${emailOperations.id} = ${key} OR ${emailOperations.idempotency_key} = ${key})`, + ), + ) + .limit(1); + return rows[0] ?? null; +} + +export async function requestEmailDomainSync( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + key = generateId('esync'), +): Promise { + return requestExistingOperation(db, env, routeId, actor, 'sync', key); +} +export async function requestEmailDomainRemove( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + key = generateId('erem'), +): Promise { + return requestExistingOperation(db, env, routeId, actor, 'remove', key); +} +/** Stage a new zone secret. The old generation stays active until a signed + * challenge proves the deployed Worker actually received the new value. */ +export async function requestEmailSecretRotation( + db: Db, + env: Bindings, + connectionId: string, + actor: EmailActor, + key = generateId('erot'), +): Promise { + const installationId = emailInstallationId(env); + const actorScope = + actor.kind === 'system' ? 'system:rotation' : `${actor.kind}:${actor.userId}:${connectionId}`; + const requestDigest = await digest({ connectionId, kind: 'rotate_secret', actor: actor.kind }); + const prior = ( + await db + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, actorScope), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (prior) { + if (prior.request_digest !== requestDigest) { + throw new EmailOperationError('email operation key conflict'); + } + return prior.id; + } + const secret = randomSecret(); + return db.transaction(async (tx) => { + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connectionId)) + .for('update') + .limit(1) + )[0]; + if (!connection || connection.installation_id !== installationId) { + throw new EmailOperationError('connection not found', 404); + } + if (!canManageConnection(actor, connection)) { + throw new EmailOperationError('only the connection manager can rotate ingress', 403); + } + if (isSharedGatewayConnection(env, connection)) { + throw new EmailOperationError( + 'the installation gateway secret is managed by platform deployment, not zone rotation', + 409, + ); + } + if (connection.staged_secret_generation !== null) { + throw new EmailOperationError('ingress rotation already staged'); + } + const unresolved = ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connectionId), + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + ), + ) + .limit(1) + )[0]; + if (unresolved) { + throw new EmailOperationError(`connection operation ${unresolved.id} is unresolved`); + } + const generation = connection.desired_generation + 1, + secretGeneration = connection.active_secret_generation + 1; + const encrypted = await encryptPlatformCredential( + env, + installationId, + `${connection.id}:secret:${secretGeneration}`, + secret, + ); + await tx + .update(emailZoneConnections) + .set({ + desired_generation: generation, + staged_secret_generation: secretGeneration, + staged_secret_ciphertext: encrypted.ciphertext, + staged_secret_iv: encrypted.iv, + staged_secret_key_version: encrypted.keyVersion, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connectionId)); + const operationId = generateId('eop'); + await tx.insert(emailOperations).values({ + id: operationId, + installation_id: installationId, + connection_id: connectionId, + actor_kind: actor.kind, + actor_user_id: actor.kind === 'system' ? null : actor.userId, + actor_scope: actorScope, + kind: 'rotate_secret', + idempotency_key: key, + request_digest: requestDigest, + desired_generation: generation, + }); + for (let i = 0; i < ROTATE_STEPS.length; i++) { + await tx.insert(emailOperationSteps).values({ + id: generateId('estep'), + operation_id: operationId, + ordinal: i, + kind: ROTATE_STEPS[i], + resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}/secret/${secretGeneration}`, + request_digest: await digest({ + kind: ROTATE_STEPS[i], + connectionId, + generation, + secretGeneration, + }), + }); + } + return operationId; + }); +} +async function requestExistingOperation( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + kind: 'sync' | 'remove', + key: string, +): Promise { + const installationId = emailInstallationId(env); + const actorScope = + actor.kind === 'system' ? 'system' : `${actor.kind}:${actor.userId}:${routeId}`; + const requestDigest = await digest({ routeId, kind, actor: actor.kind }); + const existing = ( + await db + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, actorScope), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (existing) { + if (existing.request_digest !== requestDigest) { + throw new EmailOperationError('email operation key conflict'); + } + return existing.id; + } + return db.transaction(async (tx) => { + if (kind === 'remove') { + await disableEmailDomainRouteAndDrainTx(tx, routeId); + } + const route = ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, routeId)) + .for('update') + .limit(1) + )[0]; + if (!route) { + throw new EmailOperationError('email domain not available', 404); + } + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, route.connection_id)) + .for('update') + .limit(1) + )[0]; + const project = route.project_id + ? (await tx.select().from(projects).where(eq(projects.id, route.project_id)).limit(1))[0] + : null; + if (!connection || (actor.kind !== 'system' && (!project || project.status === 'deleting'))) { + throw new EmailOperationError('email domain not available', 404); + } + if ( + actor.kind === 'owner' && + (project?.user_id !== actor.userId || route.managed_by !== 'owner') + ) { + throw new EmailOperationError('forbidden', 403); + } + if (kind === 'sync' && !canManageConnection(actor, connection)) { + throw new EmailOperationError( + 'only the connection manager can reconcile shared ingress', + 403, + ); + } + const existingRemoval = + kind === 'remove' + ? ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.route_id, routeId), + eq(emailOperations.kind, 'remove'), + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + ), + ) + .orderBy(emailOperations.created_at, emailOperations.id) + .limit(1) + )[0] + : null; + if (existingRemoval) { + return existingRemoval.id; + } + const unresolved = ( + await tx + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connection.id), + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + ), + ) + .orderBy(desc(emailOperations.created_at), desc(emailOperations.id)) + .limit(1) + )[0]; + if (unresolved && kind !== 'remove') { + throw new EmailOperationError(`connection operation ${unresolved.id} is unresolved`); + } + const opId = generateId('eop'); + const generation = unresolved + ? connection.desired_generation + : connection.desired_generation + 1; + if (!unresolved) { + await tx + .update(emailZoneConnections) + .set({ desired_generation: generation, updated_at: sql`now()` }) + .where(eq(emailZoneConnections.id, connection.id)); + } + await tx.insert(emailOperations).values({ + id: opId, + installation_id: installationId, + connection_id: connection.id, + route_id: routeId, + actor_kind: actor.kind, + actor_user_id: actor.kind === 'system' ? null : actor.userId, + actor_scope: actorScope, + kind, + idempotency_key: key, + request_digest: requestDigest, + desired_generation: generation, + current_step: unresolved && kind === 'remove' ? `wait:${unresolved.id}` : null, + }); + const steps = + kind === 'sync' + ? isSharedGatewayConnection(env, connection) + ? SHARED_SYNC_STEPS + : SYNC_STEPS + : REMOVE_STEPS; + for (let i = 0; i < steps.length; i++) { + await tx.insert(emailOperationSteps).values({ + id: generateId('estep'), + operation_id: opId, + ordinal: i, + kind: steps[i], + resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, + request_digest: await digest({ + kind: steps[i], + connectionId: connection.id, + generation, + }), + }); + } + return opId; + }); +} + +/** Bounded synchronous driver. Cron calls this too, so a lost HTTP response cannot strand setup. */ +export async function runEmailOperation(db: Db, env: Bindings, operationId: string): Promise { + for (let iteration = 0; iteration < 12; iteration++) { + const claim = await db.transaction(async (tx) => { + const op = ( + await tx + .select() + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .for('update') + .limit(1) + )[0]; + if (!op || op.status === 'completed' || op.status === 'blocked' || op.status === 'unknown') { + return null; + } + if (op.kind === 'remove') { + // Removal intents form a durable chain. A later sibling removal may + // wait for this one, but must never stop it from making progress. + const predecessorId = op.current_step?.startsWith('wait:') + ? op.current_step.slice(5) + : null; + if (predecessorId) { + const predecessor = ( + await tx + .select({ status: emailOperations.status }) + .from(emailOperations) + .where(eq(emailOperations.id, predecessorId)) + .limit(1) + )[0]; + if ( + predecessor && + (predecessor.status === 'pending' || + predecessor.status === 'running' || + predecessor.status === 'unknown') + ) { + return null; + } + } + } + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, op.connection_id)) + .for('update') + .limit(1) + )[0]; + if (!connection || connection.desired_generation !== op.desired_generation) { + throw new EmailOperationError('email operation generation changed'); + } + const steps = await tx + .select() + .from(emailOperationSteps) + .where(eq(emailOperationSteps.operation_id, operationId)) + .orderBy(emailOperationSteps.ordinal); + const step = steps.find((s) => s.status !== 'confirmed'); + if (!step) { + await tx + .update(emailOperations) + .set({ status: 'completed', current_step: null, updated_at: sql`now()` }) + .where(eq(emailOperations.id, operationId)); + return null; + } + if (step.status === 'in_flight') { + // A second scheduler must leave the current driver alone. A crashed + // driver is fenced only after its lease ages out; its provider write + // is never replayed merely because the lease expired. + if (step.started_at && Date.now() - Date.parse(step.started_at) < 5 * 60_000) { + return null; + } + await tx + .update(emailOperationSteps) + .set({ status: 'unknown', failure_code: 'outcome_unknown' }) + .where( + and( + eq(emailOperationSteps.id, step.id), + eq(emailOperationSteps.status, 'in_flight'), + eq(emailOperationSteps.attempt, step.attempt), + ), + ); + await tx + .update(emailOperations) + .set({ + status: 'unknown', + current_step: step.kind, + failure_code: 'outcome_unknown', + updated_at: sql`now()`, + }) + .where(eq(emailOperations.id, operationId)); + return null; + } + if (step.status === 'unknown') { + return null; + } + if (step.status === 'blocked') { + return null; + } + if ( + op.kind === 'remove' && + (step.kind === 'catchall_detach' || step.kind === 'ingress_delete') && + op.route_id + ) { + const [route] = await tx + .select({ projectId: emailDomainRoutes.project_id, domain: emailDomainRoutes.domain }) + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1); + if (route?.projectId) { + const [active] = await tx + .select({ n: count() }) + .from(emailUnresolvedAttempts) + .where( + and( + eq(emailUnresolvedAttempts.project_id, route.projectId), + eq(emailUnresolvedAttempts.sender_domain, route.domain), + ), + ); + if ((active?.n ?? 0) > 0) { + return null; + } + } + } + await tx + .update(emailOperationSteps) + .set({ status: 'in_flight', attempt: step.attempt + 1, started_at: sql`now()` }) + .where(eq(emailOperationSteps.id, step.id)); + await tx + .update(emailOperations) + .set({ status: 'running', current_step: step.kind, updated_at: sql`now()` }) + .where(eq(emailOperations.id, operationId)); + return { op, connection, step, attempt: step.attempt + 1 }; + }); + if (!claim) { + return; + } + try { + const outcome = await executeEmailStep( + db, + env, + claim.op, + claim.connection, + claim.step.kind as StepKind, + ); + await db.transaction(async (tx) => { + const current = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, claim.connection.id)) + .for('update') + .limit(1) + )[0]; + if (!current || current.desired_generation !== claim.op.desired_generation) { + return; + } + const updated = await tx + .update(emailOperationSteps) + .set({ + status: 'confirmed', + outcome, + failure_code: null, + failure_detail: null, + finished_at: sql`now()`, + }) + .where( + and( + eq(emailOperationSteps.id, claim.step.id), + eq(emailOperationSteps.attempt, claim.attempt), + inArray(emailOperationSteps.status, ['in_flight', 'unknown']), + ), + ) + .returning({ id: emailOperationSteps.id }); + if (updated.length) { + await tx + .update(emailOperations) + .set({ + status: 'pending', + failure_code: null, + failure_detail: null, + updated_at: sql`now()`, + }) + .where( + and( + eq(emailOperations.id, operationId), + inArray(emailOperations.status, ['running', 'unknown']), + ), + ); + } + }); + } catch (error) { + // A write may have reached Cloudflare even if fetch failed. Stop until + // an explicit probe or operator decision establishes its outcome. + const detail = error instanceof Error ? error.message : String(error); + const blocked = error instanceof EmailOperationError && error.status < 500; + const status = blocked ? 'blocked' : 'unknown'; + await db.transaction(async (tx) => { + const updated = await tx + .update(emailOperationSteps) + .set({ + status, + failure_code: blocked ? 'blocked' : 'outcome_unknown', + failure_detail: detail.slice(0, 300), + finished_at: sql`now()`, + }) + .where( + and( + eq(emailOperationSteps.id, claim.step.id), + eq(emailOperationSteps.attempt, claim.attempt), + inArray(emailOperationSteps.status, ['in_flight', 'unknown']), + ), + ) + .returning({ id: emailOperationSteps.id }); + if (updated.length) { + await tx + .update(emailOperations) + .set({ + status, + current_step: claim.step.kind, + failure_code: blocked ? 'blocked' : 'outcome_unknown', + failure_detail: detail.slice(0, 300), + updated_at: sql`now()`, + }) + .where( + and( + eq(emailOperations.id, operationId), + inArray(emailOperations.status, ['running', 'unknown']), + ), + ); + } + }); + return; + } + } +} + +async function executeEmailStep( + db: Db, + env: Bindings, + op: typeof emailOperations.$inferSelect, + connection: typeof emailZoneConnections.$inferSelect, + kind: StepKind, +): Promise> { + const route = op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null; + if (kind === 'route_disable') { + return { disabled: true }; + } + if (kind === 'publish') { + if (route) { + await db.transaction(async (tx) => { + if (op.kind === 'remove') { + await tx + .update(emailDomainRoutes) + .set({ desired_state: 'removed', inbound_status: 'disabled', updated_at: sql`now()` }) + .where(eq(emailDomainRoutes.id, route.id)); + } + const state = op.kind === 'remove' ? 'removed' : route.desired_state; + await tx + .insert(emailCacheOutbox) + .values({ + id: generateId('eout'), + installation_id: connection.installation_id, + resource_kind: 'route', + resource_id: route.id, + version: route.desired_generation, + payload: { domain: route.domain, status: state, connectionId: connection.id }, + }) + .onConflictDoNothing(); + }); + } + return { published: false, queued: true }; + } + const credential = await credentialFor(env, db, connection); + const client = createCfCustomerClient(credential); + if (kind === 'routing_enable') { + if (!route) { + throw new EmailOperationError('route is unavailable'); + } + const subdomain = route.domain !== connection.zone_name; + await client.enableRouting(connection.zone_id, subdomain ? route.domain : undefined); + return { domain: route.domain }; + } + if (kind === 'ingress_deploy') { + await client.putRelayScript(connection.account_id, connection.ingress_worker_name, { + source: RELAY_SOURCE, + compatibilityDate: RELAY_COMPATIBILITY_DATE, + gatewayOrigin: gatewayOrigin(env), + accountId: connection.account_id, + zoneId: connection.zone_id, + ingressName: connection.ingress_worker_name, + }); + await db + .update(emailZoneConnections) + .set({ ingress_version: RELAY_VERSION, updated_at: sql`now()` }) + .where( + and( + eq(emailZoneConnections.id, connection.id), + eq(emailZoneConnections.desired_generation, op.desired_generation), + ), + ); + return { version: RELAY_VERSION }; + } + if (kind === 'probe_route_enable') { + if ( + !(await client.getScriptSubdomainEnabled( + connection.account_id, + connection.ingress_worker_name, + )) + ) { + await client.enableScriptSubdomain(connection.account_id, connection.ingress_worker_name); + } + return { enabled: true }; + } + if (kind === 'secret_put') { + const staged = op.kind === 'rotate_secret'; + const secret = staged + ? await readStagedConnectionSecret(env, connection) + : await readConnectionSecret(env, connection); + await client.putRelaySecret(connection.account_id, connection.ingress_worker_name, secret); + return { + generation: staged + ? connection.staged_secret_generation + : connection.active_secret_generation, + }; + } + if (kind === 'relay_probe') { + return probeDeployedRelay(client, env, connection, op.kind === 'rotate_secret'); + } + if (kind === 'gateway_probe') { + return probeGatewayAcceptance(env, connection, op.kind === 'rotate_secret'); + } + if (kind === 'secret_promote') { + if ( + op.kind !== 'rotate_secret' || + connection.staged_secret_generation === null || + !connection.staged_secret_ciphertext || + !connection.staged_secret_iv || + !connection.staged_secret_key_version + ) { + throw new EmailOperationError('staged ingress generation unavailable'); + } + const oldSecret = await readConnectionSecret(env, connection); + const oldHash = await digest(oldSecret); + const promoted = await db + .update(emailZoneConnections) + .set({ + active_secret_generation: connection.staged_secret_generation, + secret_ciphertext: connection.staged_secret_ciphertext, + secret_iv: connection.staged_secret_iv, + secret_key_version: connection.staged_secret_key_version, + staged_secret_generation: null, + staged_secret_ciphertext: null, + staged_secret_iv: null, + staged_secret_key_version: null, + previous_secret_hash: oldHash, + previous_secret_until: sql`now() + interval '10 minutes'`, + updated_at: sql`now()`, + }) + .where( + and( + eq(emailZoneConnections.id, connection.id), + eq(emailZoneConnections.desired_generation, op.desired_generation), + eq(emailZoneConnections.staged_secret_generation, connection.staged_secret_generation), + ), + ) + .returning({ id: emailZoneConnections.id }); + if (!promoted.length) { + throw new EmailOperationError('secret promotion lost its generation fence', 503); + } + return { generation: connection.staged_secret_generation }; + } + if (kind === 'catchall_ensure') { + const current = await client.getCatchAll(connection.zone_id); + if (current?.enabled && current.workerName !== connection.ingress_worker_name) { + throw new EmailOperationError('another enabled catch-all owns this zone'); + } + if (!current?.enabled) { + await client.setCatchAll(connection.zone_id, connection.ingress_worker_name); + } + return { workerName: connection.ingress_worker_name }; + } + if (kind === 'inbound_probe') { + const current = await client.getCatchAll(connection.zone_id); + if (!current?.enabled || current.workerName !== connection.ingress_worker_name) { + throw new EmailOperationError('zone catch-all does not point to this ingress'); + } + await db.transaction(async (tx) => { + await tx + .update(emailZoneConnections) + .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) + .where( + and( + eq(emailZoneConnections.id, connection.id), + eq(emailZoneConnections.desired_generation, op.desired_generation), + ), + ); + if (route && route.desired_state === 'active') { + await tx + .update(emailDomainRoutes) + .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) + .where(eq(emailDomainRoutes.id, route.id)); + } + }); + return { ready: true }; + } + if (kind === 'sending_onboard') { + if (!route || route.desired_state !== 'active') { + return { skipped: true }; + } + try { + await client.onboardSending(connection.zone_id, route.domain); + } catch { + if (!(await sendingOnboardedReadback(client, connection.zone_id, route.domain))) { + await db + .update(emailDomainRoutes) + .set({ + outbound_status: 'verified_only', + outbound_reason: 'Cloudflare Sending onboarding unavailable', + outbound_observed_at: sql`now()`, + }) + .where(eq(emailDomainRoutes.id, route.id)); + return { verifiedOnly: true }; + } + } + await db + .update(emailDomainRoutes) + .set({ outbound_status: 'ready', outbound_reason: null, outbound_observed_at: sql`now()` }) + .where(eq(emailDomainRoutes.id, route.id)); + return { ready: true }; + } + if (kind === 'catchall_detach' || kind === 'ingress_delete') { + // Every non-removed sibling, including a disabled assignment awaiting + // reconciliation, retains the shared zone resources. This check is + // repeated at each destructive provider step. + const sibling = ( + await db + .select({ id: emailDomainRoutes.id }) + .from(emailDomainRoutes) + .where( + and( + eq(emailDomainRoutes.connection_id, connection.id), + ne(emailDomainRoutes.desired_state, 'removed'), + ...(route ? [ne(emailDomainRoutes.id, route.id)] : []), + ), + ) + .limit(1) + )[0]; + if (sibling) { + return { retainedForSibling: true }; + } + if ( + !canManageConnection( + { kind: op.actor_kind, userId: op.actor_user_id ?? '' } as EmailActor, + connection, + ) + ) { + return { retainedForManager: true }; + } + if (kind === 'catchall_detach') { + const current = await client.getCatchAll(connection.zone_id); + if (current?.enabled && current.workerName === connection.ingress_worker_name) { + await client.resetCatchAll(connection.zone_id); + } + return { detached: true }; + } + const current = await client.getCatchAll(connection.zone_id); + if (current?.enabled && current.workerName === connection.ingress_worker_name) { + throw new EmailOperationError('owned catch-all still targets ingress'); + } + await client.deleteRelayScript(connection.account_id, connection.ingress_worker_name); + await db + .update(emailZoneConnections) + .set({ inbound_status: 'disabled', inbound_observed_at: sql`now()` }) + .where(eq(emailZoneConnections.id, connection.id)); + return { deleted: true }; + } + throw new EmailOperationError(`unsupported email step: ${kind}`); +} + +export async function reconcilePendingEmailOperations( + db: Db, + env: Bindings, + limit = 10, +): Promise { + const rows = await db + .select({ id: emailOperations.id, status: emailOperations.status }) + .from(emailOperations) + .where(inArray(emailOperations.status, ['pending', 'running', 'unknown'])) + .orderBy(emailOperations.created_at) + .limit(limit); + for (const row of rows) { + if (row.status === 'unknown') { + await reconcileUnknownEmailOperation(db, env, row.id); + } + await runEmailOperation(db, env, row.id); + } + return rows.length; +} + +/** Read-only recovery for ambiguous provider writes. A result is confirmed + * only where the currently observed resource proves this exact step's intent. + * Script upload and routing enable remain unknown without that proof. */ +export async function reconcileUnknownEmailOperation( + db: Db, + env: Bindings, + operationId: string, +): Promise { + const op = ( + await db.select().from(emailOperations).where(eq(emailOperations.id, operationId)).limit(1) + )[0]; + if (!op || op.status !== 'unknown') { + return false; + } + const connection = ( + await db + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, op.connection_id)) + .limit(1) + )[0]; + if (!connection || connection.desired_generation !== op.desired_generation) { + return false; + } + const step = ( + await db + .select() + .from(emailOperationSteps) + .where( + and( + eq(emailOperationSteps.operation_id, operationId), + eq(emailOperationSteps.status, 'unknown'), + ), + ) + .orderBy(emailOperationSteps.ordinal) + .limit(1) + )[0]; + if (!step) { + return false; + } + let outcome: Record | null = null; + try { + if (step.kind === 'route_disable') { + const route = op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null; + if (route?.desired_state === 'disabled') { + outcome = { disabled: true }; + } + } else if (step.kind === 'secret_promote') { + const target = Number(step.resource_identity.split('/secret/')[1]); + if ( + Number.isInteger(target) && + connection.staged_secret_generation === null && + connection.active_secret_generation === target + ) { + outcome = { generation: connection.active_secret_generation }; + } + } else if (step.kind === 'publish') { + const route = op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null; + const outbox = route + ? ( + await db + .select({ id: emailCacheOutbox.id }) + .from(emailCacheOutbox) + .where( + and( + eq(emailCacheOutbox.resource_kind, 'route'), + eq(emailCacheOutbox.resource_id, route.id), + eq(emailCacheOutbox.version, route.desired_generation), + ), + ) + .limit(1) + )[0] + : null; + if (outbox || op.kind === 'rotate_secret') { + outcome = { queued: true }; + } + } else { + const client = createCfCustomerClient(await credentialFor(env, db, connection)); + if (step.kind === 'probe_route_enable') { + if ( + await client.getScriptSubdomainEnabled( + connection.account_id, + connection.ingress_worker_name, + ) + ) { + outcome = { enabled: true }; + } + } else if (step.kind === 'secret_put' || step.kind === 'relay_probe') { + outcome = await probeDeployedRelay(client, env, connection, op.kind === 'rotate_secret'); + } else if (step.kind === 'gateway_probe') { + outcome = await probeGatewayAcceptance(env, connection, op.kind === 'rotate_secret'); + } else if (step.kind === 'catchall_ensure' || step.kind === 'inbound_probe') { + const catchall = await client.getCatchAll(connection.zone_id); + if (catchall?.enabled && catchall.workerName === connection.ingress_worker_name) { + outcome = { workerName: connection.ingress_worker_name }; + } + } else if (step.kind === 'catchall_detach') { + const catchall = await client.getCatchAll(connection.zone_id); + if (!catchall?.enabled || catchall.workerName !== connection.ingress_worker_name) { + outcome = { detached: true }; + } + } else if (step.kind === 'ingress_delete') { + if ( + !(await client.relayScriptExists(connection.account_id, connection.ingress_worker_name)) + ) { + outcome = { deleted: true }; + } + } else if (step.kind === 'sending_onboard') { + const route = op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null; + if (route && (await sendingOnboardedReadback(client, connection.zone_id, route.domain))) { + outcome = { ready: true }; + } + } + } + } catch { + return false; + } + if (!outcome) { + return false; + } + return db.transaction(async (tx) => { + const current = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connection.id)) + .for('update') + .limit(1) + )[0]; + if (!current || current.desired_generation !== op.desired_generation) { + return false; + } + const updated = await tx + .update(emailOperationSteps) + .set({ + status: 'confirmed', + outcome, + failure_code: null, + failure_detail: null, + finished_at: sql`now()`, + }) + .where( + and( + eq(emailOperationSteps.id, step.id), + eq(emailOperationSteps.status, 'unknown'), + eq(emailOperationSteps.attempt, step.attempt), + ), + ) + .returning({ id: emailOperationSteps.id }); + if (!updated.length) { + return false; + } + if (step.kind === 'inbound_probe') { + await tx + .update(emailZoneConnections) + .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) + .where(eq(emailZoneConnections.id, connection.id)); + if (op.route_id) { + await tx + .update(emailDomainRoutes) + .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) + .where( + and( + eq(emailDomainRoutes.id, op.route_id), + eq(emailDomainRoutes.desired_state, 'active'), + ), + ); + } + } + if (step.kind === 'sending_onboard' && op.route_id) { + await tx + .update(emailDomainRoutes) + .set({ outbound_status: 'ready', outbound_reason: null, outbound_observed_at: sql`now()` }) + .where(eq(emailDomainRoutes.id, op.route_id)); + } + await tx + .update(emailOperations) + .set({ status: 'pending', failure_code: null, failure_detail: null, updated_at: sql`now()` }) + .where(and(eq(emailOperations.id, operationId), eq(emailOperations.status, 'unknown'))); + return true; + }); +} + +/** Serialized cache publication. Versioned values are immutable; the mutable + * pointer is for display only and never authorizes mail. */ +export async function flushEmailCacheOutbox(db: Db, kv: KVNamespace, limit = 25): Promise { + const rows = await db + .select() + .from(emailCacheOutbox) + .where(isNull(emailCacheOutbox.published_at)) + .orderBy(emailCacheOutbox.created_at, emailCacheOutbox.id) + .limit(limit); + let count = 0; + for (const row of rows) { + const newest = ( + await db + .select({ version: emailCacheOutbox.version }) + .from(emailCacheOutbox) + .where( + and( + eq(emailCacheOutbox.resource_kind, row.resource_kind), + eq(emailCacheOutbox.resource_id, row.resource_id), + ), + ) + .orderBy(sql`${emailCacheOutbox.version} DESC`) + .limit(1) + )[0]; + if (newest?.version === row.version) { + const base = `email-cache:${row.resource_kind}:${row.resource_id}`; + await kv.put(`${base}:v${row.version}`, JSON.stringify(row.payload)); + // This mutable pointer is never security authority. Out-of-order + // publication may make display stale until a later refresh. + await kv.put(`${base}:latest`, String(row.version)); + } + await db + .update(emailCacheOutbox) + .set({ published_at: sql`now()` }) + .where(eq(emailCacheOutbox.id, row.id)); + count++; + } + return count; +} diff --git a/platform/packages/api/src/email/domain-service.ts b/platform/packages/api/src/email/domain-service.ts index fa5893f7d..40099cbaf 100644 --- a/platform/packages/api/src/email/domain-service.ts +++ b/platform/packages/api/src/email/domain-service.ts @@ -1,92 +1,34 @@ -/** - * Custom email domains on the customer's own Cloudflare zone — the - * orchestration around `relay-engine.ts` (design doc 0078, "Custom domains - * on Cloudflare" and "Administrator-managed domains"). - * - * Two surfaces call into this module and must never diverge: the owner - * routes (`routes/email.ts`, guarded by project ownership) and the operator - * API + admin UI (an administrator acting on any project). Everything that - * touches the `email_domains` row, its encrypted triples, the ROUTING KV - * mirror the proxy reads, or the customer's Cloudflare account lives here, - * so the serialized sections, checkpoints and compensations documented in - * the design record have exactly one implementation. - * - * Functions keep the Hono `Context` because their results are the owner - * routes' responses; the operator layer reads those responses back and - * re-shapes them. - */ - -import { and, eq, inArray, isNotNull, isNull, ne, sql } from 'drizzle-orm'; +/** Shared owner/operator email-domain service. Cloudflare writes are driven by + * committed operations in connection-service; no database transaction spans a + * provider request. */ +import { and, eq, sql } from 'drizzle-orm'; import type { Context } from 'hono'; -import type { Db, DbOrTx, Tx } from '../db.ts'; +import type { Db, DbOrTx } from '../db.ts'; import type { ApiEnv } from '../env.ts'; -import { generateId } from '../id.ts'; -import { isUniqueViolation, uniqueViolationConstraintName } from '../pg-errors.ts'; -import { emailDomains, projects, type EmailDomainSetupState } from '../schema.ts'; import type { Project } from '../types.ts'; -import { OAuthGrantError, createCfCustomerClient, revokeOauthGrant } from './cf-customer.ts'; -import type { CfCustomerClient } from './cf-customer.ts'; -import { - EmailDomainCredentialChangedError, - refreshOauthGrantSerialized, - revokeOauthGrantSerialized, - withEmailDomainRowLock, -} from './credential-lease.ts'; -import { MAX_DOMAIN_LENGTH, isValidEmailDomain, normalizeEmailDomain } from './domain-name.ts'; -import { - applyEmailDomainDeployCheckpoint, - clearEmailDomainMirror, - decryptEmailDomainRelaySecret, - decryptEmailDomainToken, - EmailDomainRowGoneError, - encryptEmailDomainRelaySecret, - encryptEmailDomainToken, - generateEmailRelaySecret, - hashEmailRelaySecret, - markEmailDomainRemovalFailed, - writeEmailDomainMirror, - type EmailDomain, - type EmailDomainMirror, -} from './domains.ts'; +import { emailDomainRoutes, emailOperations, emailZoneConnections } from './connection-schema.ts'; import { - ROUTING_SUBDOMAIN_STEP, - SENDING_ONBOARDING_STEP, - domainHasRoutingMx, - findZoneForEmailDomain, - removeEmailDomain, - sendingOnboardedReadback, - setupEmailDomain, - syncEmailDomain, - type EmailDomainSetupResult, -} from './relay-engine.ts'; -import { RELAY_VERSION } from './relay-worker.ts'; + EmailOperationError, + getEmailOperation, + requestEmailDomainAdd, + requestEmailDomainRemove, + requestEmailDomainSync, + requestEmailSecretRotation, + resolveEmailDomain, + runEmailOperation, +} from './connection-service.ts'; +import { normalizeEmailDomain } from './domain-name.ts'; import { getEmailDomainManagement } from './settings.ts'; -/** - * Cap for a posted credential, checked on the RAW string before any - * normalization (the domain cap is `MAX_DOMAIN_LENGTH`). Generous for either - * kind (a pasted API token is ~50 chars; an OAuth refresh token a few - * hundred) and exists only to bound the encrypt + CF call work. - */ export const MAX_CREDENTIAL_LENGTH = 2048; - export type EmailDomainAddInput = Readonly<{ - /** The raw domain as posted; normalized and validated here. */ domain: string; mode?: unknown; refreshToken?: string; apiToken?: string; attemptId?: unknown; - /** - * Who is registering. An `admin` caller may omit both credentials, in - * which case the row runs on the platform's runtime token - * (`credential_kind: 'platform'`) and the zone must be in the platform's - * own Cloudflare account. - */ - managedBy: EmailDomain['managed_by']; + managedBy: 'owner' | 'admin'; }>; - -/** The administrator command an owner is pointed at when a row is not theirs to change. */ export function adminEmailDomainCommand( verb: 'add' | 'sync' | 'remove', domain: string, @@ -95,60 +37,6 @@ export function adminEmailDomainCommand( const base = `void platform email domain-${verb} ${domain}`; return verb === 'add' && slug ? `${base} --project ${slug}` : base; } - -/** - * Who may change a row. An owner touching an administrator's row is pointed - * at the operator command (403) for every verb — the row runs on the - * platform's credential. An administrator may sync or remove an owner's - * row (the ownership table's maintenance powers) but never re-`add` it: a - * takeover would revoke the owner's grant and flip the row (409). `null` - * when allowed. Callers run this on the unlocked read for the message and - * AGAIN on the locked row, because either side can commit in between. - */ -function refuseCrossOwnership( - context: Context, - row: Pick, - actor: EmailDomain['managed_by'], - slug: string, - verb: 'add' | 'sync' | 'remove' = 'add', -): Response | null { - if (row.managed_by === actor) { - return null; - } - if (actor === 'owner') { - return context.json( - { - error: 'this email domain is managed by the platform administrator', - adminCommand: adminEmailDomainCommand(verb, row.domain, slug), - }, - 403, - ); - } - if (verb !== 'add') { - return null; - } - return context.json( - { error: 'this email domain was registered by its project owner; ask them to remove it first' }, - 409, - ); -} - -/** - * A `platform` row may only act on a zone in the platform's own account. - * A row that has not learned its account yet passes — the engine's zone - * lookup pins it before any write. - */ -function platformAccountAllows( - context: Context, - row: Pick, -): boolean { - return row.account_id === null || row.account_id === context.env.CF_ACCOUNT_ID; -} - -/** - * The proxy origin baked into the relay worker as VOID_PROXY_ORIGIN — the - * same resolution the platform discovery document uses. - */ export function proxyOriginForEmail(env: ApiEnv['Bindings']): string { const origin = env.PROXY_URL ?? @@ -157,1914 +45,324 @@ export function proxyOriginForEmail(env: ApiEnv['Bindings']): string { : 'https://proxy.void.cloud'); return origin.replace(/\/+$/, ''); } - -/** - * The mirror key spelling is owned by `src/email/domains.ts` (the writer — - * frozen for this phase); the status route's read-compare repair reads the - * same key. A rename there must move this spelling with it. - */ export function emailDomainMirrorKey(domain: string): string { return `email-domain:${domain}`; } - -export async function getEmailDomainRow( - db: Db, - projectId: string, - domain: string, -): Promise { - const rows = await db - .select() - .from(emailDomains) - .where(and(eq(emailDomains.project_id, projectId), eq(emailDomains.domain, domain))) - .limit(1); - return rows[0] ?? null; +export async function revokeRejectedGrant(): Promise { + /* OAuth grants are no longer accepted for platform email. */ } -export async function getEmailDomainRowById(db: DbOrTx, id: string): Promise { - const rows = await db.select().from(emailDomains).where(eq(emailDomains.id, id)).limit(1); - return rows[0] ?? null; -} - -/** - * Cross-project lookup: a domain is globally unique across projects - * (`email_domains_domain_uq`), because one domain produces exactly one - * `email-domain:` mirror key and one relay secret. - */ -export async function getEmailDomainRowByDomain( - db: Db, - domain: string, -): Promise { - const rows = await db.select().from(emailDomains).where(eq(emailDomains.domain, domain)).limit(1); - return rows[0] ?? null; -} - -/** - * The public shape of an email_domains row — metadata only. Neither - * ciphertext triple nor any plaintext secret ever appears here. - */ -export function serializeEmailDomain(row: EmailDomain, error?: string) { - return { - id: row.id, - domain: row.domain, - mode: row.mode, - status: row.status, - credential_kind: row.credential_kind, - managed_by: row.managed_by, - relay_worker_name: row.relay_worker_name, - relay_version: row.relay_version, - token_id: row.token_id, - token_expires_on: row.token_expires_on, - // Always present (null when the row predates attempt identity): key - // presence is how a reconciling CLI detects an api that stamps it. - attemptId: row.attempt_id ?? null, - setup_state: row.setup_state, - // The engine's failure text names the failing step / CF error — never - // credential material — so the CLI can print it verbatim. - ...(error === undefined ? {} : { error }), - created_at: row.created_at, - updated_at: row.updated_at, - }; -} - -/** - * Persist the engine's setup outcome onto the row and return the final - * row. Never touches the token_* triple: the caller wrote it at insert, - * and any rotation since was persisted by the serialized refresh under the - * row lock. - */ -async function applyEmailDomainSetupResult( - db: DbOrTx, - id: string, - result: EmailDomainSetupResult, - relay?: { ciphertext: string; iv: string; keyVersion: string }, -): Promise { - await db - .update(emailDomains) - .set({ - status: result.status, - zone_id: result.zone_id, - account_id: result.account_id, - mode: result.mode, - relay_worker_name: result.relay_worker_name, - relay_version: result.relay_version, - token_id: result.token_id, - token_expires_on: result.token_expires_on, - setup_state: result.setup_state, - ...(relay === undefined - ? {} - : { - relay_ciphertext: relay.ciphertext, - relay_iv: relay.iv, - relay_key_version: relay.keyVersion, - }), - updated_at: sql`now()`, - }) - .where(eq(emailDomains.id, id)); - const row = await getEmailDomainRowById(db, id); - if (!row) { - throw new Error('email_domains row vanished mid-setup'); - } - return row; -} - -/** - * The 23505 loser's best-effort CF compensation, shared by the apply-time - * backstop (applyEmailDomainSetupResultOrConflict) and the deploy-time - * checkpoint (persistProgress): both lose a zone (or one account's relay - * name) to a setup that already passed the engine's CF-side reads — - * first-to-persist wins. - * - * The relay-NAME branch is a safety net, not a live path: fresh setups - * CLAIM the name on their own row (the claimRelayName dep) BEFORE any - * upload, so a checkpoint-time relay-name 23505 is no longer reachable - * from the setup flow — the claim itself is the only relay-name 23505 - * left, and the walk absorbs it as 'taken'. The branch stays for rows - * written before the claim existed and as defense in depth. - * - * Works from what the engine RETURNED or checkpointed (the loser's row - * still holds nulls — a claimed name is undone before this runs). A - * relay-NAME conflict never deletes the worker — - * the name is contested, the winner is using it — so the compensation - * runs with account_id nulled: only the loser's zone rule is detached. On - * a ZONE conflict the winner is looked up and an owned catch-all is - * REPOINTED at its relay: the loser's conditional reset only detaches a - * rule naming its OWN relay, so without a repoint target the zone's rule - * dies with the loser; repointing hands it to the winner instead. (At - * checkpoint-time conflicts the loser never wrote its rule, so the - * repoint probe is a harmless no-op — one code path.) A failed winner - * lookup degrades to the plain reset. Deliberately NO revokeGrant dep: - * the loser's row/credential may survive — conflict compensation is not - * removal. - */ -async function compensateEmailDomainRace( - context: Context, - loserRowId: string, - race: { - credentialKind: EmailDomain['credential_kind']; - credential: string; - }, - loser: { - zone_id: string | null; - account_id: string | null; - relay_worker_name: string | null; - }, - err: unknown, -): Promise { - const relayRace = uniqueViolationConstraintName(err).includes('relay'); - let repointTo: string | null = null; - if (!relayRace && loser.zone_id !== null) { - try { - const winners = await context - .get('db') +export async function getEmailDomainRow(db: Db, projectId: string, domain: string) { + return ( + ( + await db .select() - .from(emailDomains) + .from(emailDomainRoutes) .where( and( - eq(emailDomains.zone_id, loser.zone_id), - // The exact live-status set of the schema's - // email_domains_zone_uq partial index — the rows this loser - // lost to. - inArray(emailDomains.status, ['active', 'pending']), - isNotNull(emailDomains.relay_worker_name), - ne(emailDomains.id, loserRowId), + eq(emailDomainRoutes.project_id, projectId), + eq(emailDomainRoutes.domain, normalizeEmailDomain(domain)), ), ) - .limit(1); - repointTo = winners[0]?.relay_worker_name ?? null; - } catch (lookupErr) { - console.error('[email] race winner lookup failed; falling back to reset:', lookupErr); - } - } - try { - await removeEmailDomain( - { - row: { - credential_kind: race.credentialKind, - // A contested relay name is never deleted (see the header). - account_id: relayRace ? null : loser.account_id, - relay_worker_name: loser.relay_worker_name, - zone_id: loser.zone_id, - }, - credential: race.credential, - ...(repointTo === null ? {} : { repoint_catch_all_to: repointTo }), - }, - { - // Grant refresh tokens are single-use: the compensation's refresh - // must persist its rotation through the row's serialized chain, - // or the cleanup would brick the credential it leaves behind. - refreshGrant: () => refreshOauthGrantSerialized(context.get('db'), context.env, loserRowId), - }, - ); - } catch (compensationErr) { - // removeEmailDomain never throws; this is paranoia for the log only. - console.error('[email] race compensation failed:', compensationErr); - } - return relayRace - ? 'another email domain is deploying the same relay worker — retry' - : 'another active email domain already uses this zone — remove it first'; + .limit(1) + )[0] ?? null + ); } - -/** - * Run one fallible statement of the serialized engine section behind a - * savepoint, so an expected constraint violation — the first-to-persist - * races the partial unique indexes exist to catch — aborts only that - * statement. The transaction stays committable, keeping the row and any - * grant rotations the engine already persisted through the row's - * serialized chain: without this a 23505 would poison the whole - * transaction, and the rollback would strand the rotated chain head (the - * only copy CF issued) with no database handle, breaking the race - * compensation's refresh-through-the-row. - */ -async function tryEmailDomainSavepoint( - tx: Tx, - name: string, - fn: () => Promise, -): Promise<{ ok: true; value: T } | { ok: false; err: unknown }> { - await tx.execute(sql.raw(`SAVEPOINT ${name}`)); - try { - const value = await fn(); - await tx.execute(sql.raw(`RELEASE SAVEPOINT ${name}`)); - return { ok: true, value }; - } catch (err) { - await tx.execute(sql.raw(`ROLLBACK TO SAVEPOINT ${name}`)); - return { ok: false, err }; - } +export async function getEmailDomainRowById(db: DbOrTx, id: string) { + return ( + (await db.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.id, id)).limit(1))[0] ?? + null + ); } - -/** - * Best-effort revocation of a POSTed OAuth grant the request is rejecting - * before persistence. The CLI mints a fresh user-wide grant (zone, email - * and workers scopes) per add attempt and drops its only copy on an error - * response, so a rejection without a revoke strands a live broad grant in - * the customer's account per retry. api_token credentials are out of - * scope: user-created out-of-band, and no token-delete primitive exists. - * - * `holder` is the conflicting row when one is in hand: a re-pasted grant - * equal to the row's stored credential must NOT be revoked — that would - * brick the live row (the same guard as the replace route's - * identical-grant skip). A holder whose credential can't be decrypted - * fails safe toward keeping. - */ -export async function revokeRejectedGrant( - context: Context, - refreshToken: string | undefined, - holder?: EmailDomain | null, -): Promise { - if (refreshToken === undefined) { - return; - } - // A holder on the platform's credential stored no grant; nothing to - // compare against, so the posted grant is revoked like any rejection. - if (holder && holder.credential_kind !== 'platform') { - let held: string | null = null; - try { - held = await decryptEmailDomainToken(context.env, holder.project_id, holder.domain, holder); - } catch (err) { - console.error('[email] rejected-grant holder decrypt failed; skipping revoke:', err); - return; - } - if (held === refreshToken) { - return; - } - } - try { - await revokeOauthGrant(refreshToken); - } catch (err) { - // Best-effort: the rejection stands either way, and this log line is - // the trace an operator gets. - console.error('[email] rejected-grant revoke failed:', err); - } +export async function getEmailDomainRowByDomain(db: Db, domain: string) { + return ( + ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.domain, normalizeEmailDomain(domain))) + .limit(1) + )[0] ?? null + ); } - -/** - * Best-effort compensation for a checkpoint write that failed for any - * non-race reason (a DB error, or the row cascade-deleted by teardown - * mid-setup): the relay and its secret are deployed but the row carries - * no reference to them, so remove them from the captured checkpoint - * payload before the error propagates. The catch-all was never written - * (the checkpoint precedes it), so the conditional reset is a no-op. - * `rowGone` switches the refresh to the engine default, which acts on the - * held credential directly — the serialized chain needs the row. - */ -async function compensateCheckpointDeploy( - context: Context, - rowId: string, - race: { credentialKind: EmailDomain['credential_kind']; credential: string }, - checkpoint: { zone_id: string | null; account_id: string | null; relay_worker_name: string }, - opts: { rowGone: boolean }, -): Promise { - try { - await removeEmailDomain( - { - row: { - credential_kind: race.credentialKind, - account_id: checkpoint.account_id, - relay_worker_name: checkpoint.relay_worker_name, - zone_id: checkpoint.zone_id, - }, - credential: race.credential, +export function serializeEmailRoute( + route: typeof emailDomainRoutes.$inferSelect, + connection: typeof emailZoneConnections.$inferSelect, + operationId?: string, +) { + return { + id: route.id, + domain: route.domain, + projectId: route.project_id, + managed_by: route.managed_by, + status: route.desired_state === 'active' ? route.inbound_status : 'disabled', + connectionId: connection.id, + account_id: connection.account_id, + zone_id: connection.zone_id, + relay_worker_name: connection.ingress_worker_name, + relay_version: connection.ingress_version, + operationId: operationId ?? null, + readiness: { + inbound: { + status: route.inbound_status, + reason: route.inbound_reason, + observedAt: route.inbound_observed_at, + }, + outbound: { + status: route.outbound_status, + reason: route.outbound_reason, + observedAt: route.outbound_observed_at, + }, + management: { + status: connection.management_status, + reason: connection.management_reason, + observedAt: connection.management_observed_at, }, - opts.rowGone - ? {} - : { - // Same single-use refresh doctrine as the race compensation. - refreshGrant: () => refreshOauthGrantSerialized(context.get('db'), context.env, rowId), - }, - ); - } catch (compErr) { - console.error('[email] checkpoint-failure compensation failed:', compErr); - } -} - -/** - * The sync sequence — relay redeploy, secret rotation, row apply, mirror - * publication — under one transaction holding the project lock and then - * the credential chain's row lock, shared by the sync route and the - * replace path's healthy-row branch. The row lock must span the worker - * secret PUT, the row persist, and the mirror PUT: two overlapping syncs - * would otherwise interleave them (A-put, B-put, B-apply, A-apply) and - * leave the worker or the mirror holding a secret the other side no - * longer names — inbound authentication fails until the next sync. The - * row FOR UPDATE is the lease chain's own, held across the CF calls - * exactly like the refresh holds it across the token round-trip; - * concurrent sends on an oauth_grant domain wait out the sync, which is - * rare and manual. - * - * The row — credential included — is RE-READ inside the lock: a replace - * that committed while this request waited for the lock is synced as its - * new credential, never verified as the superseded one (whose expired or - * revoked verdict would otherwise be stamped onto the replacement). The - * mirror PUT runs inside the serialized section even though KV is not - * transactional: a commit failure after it leaves the mirror briefly - * ahead of the row, which the status GET's drift repair converges — the - * inverse (publishing outside the lock) would let an older sync's hash - * land last and break inbound auth until someone polls. - */ -export async function syncEmailDomainAndApply( - context: Context, - projectId: string, - rowId: string, - proxyOrigin: string, - /** Who asked; authorization runs on the locked row, where it cannot be raced. */ - actor: Readonly<{ managedBy: EmailDomain['managed_by']; projectSlug: string }>, -): Promise { - const db = context.get('db'); - let outcome: - | Readonly<{ - kind: 'ok'; - result: Awaited>; - applied: EmailDomain; - }> - | Readonly<{ kind: 'project_gone' }> - | Readonly<{ kind: 'project_deleting' }> - | Readonly<{ kind: 'refused'; response: Response }>; - try { - outcome = await db.transaction(async (tx) => { - // The project lock comes FIRST — teardown's own order - // (lockAndMarkDeleting, deleteProjectCascade and the status route's - // mirror-repair fence all go project → row) — so a sync serializes - // with teardown instead of racing it. Without this recheck a sync - // that passed the route's entry guard could redeploy the relay and - // republish the mirror AFTER teardown cleared them, and the cascade - // would then delete the row, leaving a recreated mirror, worker and - // catch-all with no database handle. Holding the project lock - // across the CF calls blocks a teardown for the duration — the same - // tradeoff the mirror-repair fence makes, and safe: when the sync - // commits first, teardown's later clear/remove/cascade sees - // everything it created. - const projectRows = await tx - .select({ status: projects.status }) - .from(projects) - .where(eq(projects.id, projectId)) - .for('update') - .limit(1); - const project = projectRows[0]; - if (!project) { - return { kind: 'project_gone' } as const; - } - if (project.status === 'deleting') { - return { kind: 'project_deleting' } as const; - } - // The row lock is the lease chain's own FOR UPDATE — refreshes, - // revokes, replaces and removals serialize on it exactly as before. - const locked = await tx - .select() - .from(emailDomains) - .where(eq(emailDomains.id, rowId)) - .for('update') - .limit(1); - const current = locked[0]; - if (!current) { - // Teardown's cascade can take the row while this request waited - // on the lock. - throw new Error('email_domains row vanished mid-sync'); - } - const refused = - refuseCrossOwnership(context, current, actor.managedBy, actor.projectSlug, 'sync') ?? - refusePlatformCredentialOffAccount(context, current); - if (refused) { - return { kind: 'refused', response: refused } as const; - } - const { result, applied } = await syncEmailDomainLocked( - context, - tx, - projectId, - current, - proxyOrigin, - ); - return { kind: 'ok', result, applied } as const; - }); - } catch (err) { - if (isUniqueViolation(err)) { - // NO compensation here — sync deployed in place on the row's OWN - // relay, so the 409 just refuses the live-status flip: a 'failed' - // row carrying its zone can collide with the winner when sync - // flips it back to a live status. - return context.json( - { - error: uniqueViolationConstraintName(err).includes('relay') - ? 'another email domain is deploying the same relay worker — retry' - : 'another active email domain already uses this zone — remove it first', - }, - 409, - ); - } - throw err; - } - - if (outcome.kind === 'project_gone') { - return context.json({ error: 'project not found' }, 404); - } - if (outcome.kind === 'project_deleting') { - return context.json({ error: 'Project is being deleted' }, 409); - } - if (outcome.kind === 'refused') { - return outcome.response; - } - return context.json( - { - ...serializeEmailDomain(outcome.applied, outcome.result.error), - ...(outcome.result.catch_all === undefined ? {} : { catch_all: outcome.result.catch_all }), }, - 200, - ); + }; } - -/** - * A `platform` row whose recorded account is not the platform's must not be - * synced or re-run: that would send the runtime token to a customer account. - * Such a row can only come from a pasted-token registration later re-added - * on the platform credential, which the add path already refuses; this is - * the locked-row backstop. - */ -function refusePlatformCredentialOffAccount( - context: Context, - row: Pick, -): Response | null { - if (row.credential_kind !== 'platform') { - return null; - } - // Without the runtime token there is nothing to sync with; say so rather - // than let the credential seam's throw surface as a 500. - if (!context.env.CF_API_TOKEN) { - return context.json({ error: 'platform credential unavailable' }, 503); - } - if (platformAccountAllows(context, row)) { - return null; +export function serializeEmailDomain( + route: typeof emailDomainRoutes.$inferSelect, + connection?: typeof emailZoneConnections.$inferSelect, +) { + return connection + ? serializeEmailRoute(route, connection) + : { + id: route.id, + domain: route.domain, + project_id: route.project_id, + managed_by: route.managed_by, + status: route.inbound_status, + }; +} +function serviceError(context: Context, error: unknown): Response { + if (error instanceof EmailOperationError) { + return context.json({ error: error.message }, error.status as 400); } - return context.json( - { - error: `the zone for ${row.domain} is in Cloudflare account ${row.account_id}, not the platform's; re-add it with --token-stdin and a token for that account`, - }, - 409, - ); + throw error; } - -/** - * The sync sequence's locked core, shared by syncEmailDomainAndApply and - * the serialized engine section's healthy-row branch. Callers hold the - * project lock and the row's FOR UPDATE; `current` is the row as re-read - * under those locks — credential included, so a replace that committed - * while the caller waited is synced as its new credential. - */ -async function syncEmailDomainLocked( +async function domainResult( context: Context, - tx: Tx, - projectId: string, - current: EmailDomain, - proxyOrigin: string, -): Promise<{ - result: Awaited>; - applied: EmailDomain; -}> { - const domain = current.domain; - const credential = await decryptEmailDomainToken(context.env, projectId, domain, current); - const result = await syncEmailDomain( - { - row: { - domain, - credential_kind: current.credential_kind, - account_id: current.account_id, - relay_worker_name: current.relay_worker_name, - zone_id: current.zone_id, - // Lets sync re-attempt a pending sending onboarding (a - // Workers Paid upgrade) and report the cleared step. - setup_remaining_steps: current.setup_state?.remaining_steps, - }, - credential, - proxyOrigin, - }, - { refreshGrant: () => refreshOauthGrantSerialized(tx, context.env, current.id) }, - ); - - let relaySecretSha256: string; - const relayPatch: { - relay_ciphertext?: string; - relay_iv?: string; - relay_key_version?: string; - } = {}; - if (result.new_relay_secret !== undefined) { - const relayEnc = await encryptEmailDomainRelaySecret( - context.env, - projectId, - domain, - result.new_relay_secret, - ); - relayPatch.relay_ciphertext = relayEnc.ciphertext; - relayPatch.relay_iv = relayEnc.iv; - relayPatch.relay_key_version = relayEnc.keyVersion; - relaySecretSha256 = await hashEmailRelaySecret(result.new_relay_secret); - } else { - // No rotation happened (failed before the secret PUT) — the - // mirror still moves with the new status, hashed from the - // existing secret. - relaySecretSha256 = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(context.env, projectId, domain, current), - ); - } - // A successful sync does not clear a pending human step on its own: - // the engine cannot observe the routing-subdomain dashboard form, - // so remaining_steps survive — minus any the sync itself cleared - // (the sending-onboarding retry). The row stays 'pending' only - // while an INBOUND-BLOCKING step (routing_subdomain) remains; a - // sending_onboarding step rides along on an active row. - const keptSteps = current.setup_state?.remaining_steps?.filter( - (step) => !(result.cleared_steps ?? []).includes(step), - ); - const setupState: EmailDomainSetupState | null = - result.setup_state !== null - ? result.setup_state - : keptSteps && keptSteps.length > 0 - ? { remaining_steps: keptSteps } - : null; - const status: EmailDomain['status'] = - result.status === 'active' && setupState?.remaining_steps?.includes(ROUTING_SUBDOMAIN_STEP) - ? 'pending' - : result.status; - const appliedRows = await tx - .update(emailDomains) - .set({ - status, - relay_version: result.relay_version, - setup_state: setupState, - ...relayPatch, - updated_at: sql`now()`, - }) - .where(eq(emailDomains.id, current.id)) - .returning(); - const applied = appliedRows[0]; - if (!applied) { - throw new Error('email_domains row vanished mid-sync'); + project: Project, + domain: string, + operationId: string, +): Promise { + const resolved = await resolveEmailDomain(context.get('db'), domain); + const found = await getEmailOperation(context.get('db'), project.id, operationId); + if (!resolved || !found || resolved.route.project_id !== project.id) { + return context.json({ error: 'email operation is unavailable', operationId }, 503); } - // Mirror publication stays inside the serialized section: an - // overlapping sync publishes its own rotation behind this lock, so - // hashes land in the same order the secrets were written to the worker. - await writeEmailDomainMirror(context.env.ROUTING, applied, relaySecretSha256); - return { result, applied }; + return context.json({ + ...serializeEmailRoute(resolved.route, resolved.connection, operationId), + attemptId: found.operation.idempotency_key, + operationStatus: found.operation.status, + error: found.operation.failure_detail, + }); } - -/** - * The serialized engine section shared by the add route (after its insert - * transaction) and the replace route (after its credential commit). Both - * locks are held across the engine's CF calls, the apply, and the mirror - * publication: the PROJECT row FOR UPDATE first — teardown's own order - * (lockAndMarkDeleting, deleteProjectCascade and the status route's - * mirror-repair fence all go project → row) — then the credential chain's - * row FOR UPDATE. The project fence gives a total order with teardown: - * either teardown marked first (this refuses) or this commits first and - * teardown's later cleanup sees everything the engine created — an - * unfenced setup could otherwise finish AFTER teardown's one-time - * enumerations ran, and the cascade would delete the row without its - * domain handle, orphaning the mirror, the relay/catch-all in the - * customer account, and a fresh OAuth grant. - * - * The row — credential and recorded progress included — is RE-READ under - * the lock, and the branch is decided there: a COMPLETE row takes the - * sync path (redeploy in place + relay-secret rotation); an incomplete - * one re-runs the full engine seeded from the locked row. The row lock - * serializes concurrent full-setup retries: without it two of them could - * upload DIFFERENT relay secrets to the same relay and then apply their - * rows/mirrors in the opposite order — the worker holding secret B while - * KV expects A, rejecting every inbound message — or strand competing - * relay names. - * - * The fallible row writes (deploy checkpoint, final apply) run behind - * savepoints (tryEmailDomainSavepoint) so their expected 23505s abort - * only the one statement: the transaction then COMMITS the row and the - * engine's grant rotations, and the loser compensation below works - * through the row's live chain head exactly as it did when every write - * autocommitted. Holding the project lock across the CF calls blocks a - * teardown for the duration — the same tradeoff sync and the - * mirror-repair fence make. - */ -export async function runEmailDomainEngineSerialized( +export async function addEmailDomainForProject( context: Context, - projectId: string, - rowId: string, - proxyOrigin: string, - opts: Readonly<{ - relaySecret: string; - relayEnc: { ciphertext: string; iv: string; keyVersion: string }; - requestedMode: unknown; - created: boolean; - }>, + project: Project, + input: EmailDomainAddInput, ): Promise { - const db = context.get('db'); - const { relaySecret, relayEnc, requestedMode, created } = opts; - // Captured BEFORE each checkpoint write: a 23505 throw still needs the - // progress payload for compensation below. - let checkpoint: { - zone_id: string | null; - account_id: string | null; - mode: 'apex' | 'subdomain' | null; - relay_worker_name: string; - } | null = null; - // Set when the engine's name-walk claimed a relay name on the row, so - // an engine throw can restore the row's locked pre-engine values — the - // claim commits with this transaction even when the checkpoint's - // savepoint rolls back, and a leaked entry would park the name while - // pointing the row at a worker the compensation may have deleted. - let relayNameClaimed = false; - type EngineOutcome = - | Readonly<{ - kind: 'ok_sync'; - result: Awaited>; - applied: EmailDomain; - }> - | Readonly<{ kind: 'ok_setup'; result: EmailDomainSetupResult; applied: EmailDomain }> - | Readonly<{ kind: 'project_gone' }> - | Readonly<{ kind: 'project_deleting' }> - | Readonly<{ kind: 'row_gone' }> - | Readonly<{ kind: 'refused'; response: Response }> - | Readonly<{ - kind: 'engine_failed'; - err: unknown; - race: { credentialKind: EmailDomain['credential_kind']; credential: string }; - }> - | Readonly<{ - kind: 'apply_failed'; - err: unknown; - result: EmailDomainSetupResult; - race: { credentialKind: EmailDomain['credential_kind']; credential: string }; - }>; - let outcome: EngineOutcome; try { - outcome = await db.transaction(async (tx): Promise => { - const projectRows = await tx - .select({ status: projects.status }) - .from(projects) - .where(eq(projects.id, projectId)) - .for('update') - .limit(1); - const lockedProject = projectRows[0]; - if (!lockedProject) { - return { kind: 'project_gone' } as const; - } - if (lockedProject.status === 'deleting') { - return { kind: 'project_deleting' } as const; - } - // The row lock is the lease chain's own FOR UPDATE — refreshes, - // revokes, replaces and removals serialize on it exactly as before. - const locked = await tx - .select() - .from(emailDomains) - .where(eq(emailDomains.id, rowId)) - .for('update') - .limit(1); - const current = locked[0]; - if (!current) { - // An owner DELETE (or the admin revoke) took the row while this - // request waited on the lock; its cleanup owned the credential. - return { kind: 'row_gone' } as const; - } - - // Sync keeps a healthy row healthy; anything that never finished - // setup re-runs the full engine. A catch-all failure is the one - // 'failed' shape that still carries relay_worker_name/account_id — - // it must NOT take the sync path, which never writes the catch-all. - const setupIncomplete = - current.status === 'failed' || !current.relay_worker_name || !current.account_id; - if (!setupIncomplete) { - const refused = refusePlatformCredentialOffAccount(context, current); - if (refused) { - return { kind: 'refused', response: refused } as const; - } - const { result, applied } = await syncEmailDomainLocked( - context, - tx, - projectId, - current, - proxyOrigin, - ); - return { kind: 'ok_sync', result, applied } as const; - } - - // Setup never finished — re-run the full engine with a fresh relay - // secret, carrying the row's recorded progress so completed steps - // are idempotent (mode skips the MX check; a relay name redeploys in - // place; 'already done' 4xx is believed only on a confirming - // read-back). - const domain = current.domain; - const credential = await decryptEmailDomainToken(context.env, projectId, domain, current); - const race = { credentialKind: current.credential_kind, credential }; - let result: EmailDomainSetupResult | null = null; - let engineError: unknown = null; - try { - result = await setupEmailDomain( - { - row: { - domain, - credential_kind: current.credential_kind, - ...(current.mode === null ? {} : { mode: current.mode }), - ...(current.relay_worker_name === null - ? {} - : { relay_worker_name: current.relay_worker_name }), - ...(current.zone_id === null ? {} : { zone_id: current.zone_id }), - ...(current.account_id === null ? {} : { account_id: current.account_id }), - }, - credential, - relaySecret, - proxyOrigin, - // The platform's own token must never be pointed at a customer - // zone: a platform row may only register a zone in this account. - ...(current.credential_kind === 'platform' - ? { requireAccountId: context.env.CF_ACCOUNT_ID } - : {}), - }, - { - refreshGrant: () => refreshOauthGrantSerialized(tx, context.env, current.id), - claimRelayName: async (accountId, candidate) => { - // Reserve (account_id, candidate) on THIS row BEFORE any CF - // upload — first-to-claim turns the relay race into a walk - // skip: a concurrent setup's claim of the same name blocks - // on this uncommitted UPDATE, then 23505s past the winner's - // commit ('taken' → the walk advances) or proceeds past its - // rollback. The savepoint keeps a contested claim from - // poisoning the transaction (same machinery as the - // checkpoint). - const claim = await tryEmailDomainSavepoint(tx, 'void_email_relay_claim', () => - tx - .update(emailDomains) - .set({ account_id: accountId, relay_worker_name: candidate }) - .where(eq(emailDomains.id, current!.id)), - ); - if (claim.ok) { - relayNameClaimed = true; - return 'claimed' as const; - } - if (isUniqueViolation(claim.err)) { - return 'taken' as const; - } - throw claim.err; - }, - persistProgress: async (progress) => { - // Capture BEFORE the write: a 23505 throw still needs the - // checkpoint for compensation below. The savepoint keeps the - // transaction committable (see tryEmailDomainSavepoint). - checkpoint = progress; - const write = await tryEmailDomainSavepoint(tx, 'void_email_deploy_checkpoint', () => - applyEmailDomainDeployCheckpoint(tx, current!.id, progress), - ); - if (!write.ok) { - throw write.err; - } - }, - }, - ); - } catch (err) { - // The savepoint already rolled the failed statement back, so the - // transaction can still commit the row and the engine's grant - // rotations — the compensation outside then refreshes through the - // row's live chain head. - engineError = err; - } - if (result === null) { - // The engine threw AFTER a successful claim (the checkpoint's - // 23505 or a non-race failure): restore the row's locked - // pre-engine values so the claim doesn't outlive the setup it - // belonged to. Before the claim existed, the checkpoint's - // savepoint rollback left the row exactly this way. - if (relayNameClaimed) { - await tx - .update(emailDomains) - .set({ - account_id: current.account_id, - relay_worker_name: current.relay_worker_name, - }) - .where(eq(emailDomains.id, current.id)); - } - return { kind: 'engine_failed', err: engineError, race } as const; - } - const applied = await tryEmailDomainSavepoint(tx, 'void_email_apply', () => - applyEmailDomainSetupResult(tx, current.id, result, relayEnc), - ); - if (!applied.ok) { - return { kind: 'apply_failed', err: applied.err, result, race } as const; - } - // Mirror AFTER the row is final, and inside the serialized section: - // an overlapping retry publishes its own setup behind this lock, so - // hashes land in the same order the secrets were written to the - // worker. - await writeEmailDomainMirror( - context.env.ROUTING, - applied.value, - await hashEmailRelaySecret(relaySecret), - ); - return { kind: 'ok_setup', result, applied: applied.value } as const; - }); - } catch (err) { - if (isUniqueViolation(err)) { - // NO compensation here — the sync branch deployed in place on the - // row's OWN relay, so the 409 just refuses the live-status flip: a - // 'failed' row carrying its zone can collide with the winner when - // sync flips it back to a live status. + if (input.refreshToken) { return context.json( { - error: uniqueViolationConstraintName(err).includes('relay') - ? 'another email domain is deploying the same relay worker — retry' - : 'another active email domain already uses this zone — remove it first', + error: + 'Cloudflare OAuth grants are not accepted for platform email domains; use a scoped API token', }, - 409, - ); - } - throw err; - } - - if (outcome.kind === 'project_gone') { - return context.json({ error: 'project not found' }, 404); - } - if (outcome.kind === 'project_deleting') { - return context.json({ error: 'Project is being deleted' }, 409); - } - if (outcome.kind === 'row_gone') { - return context.json({ error: 'email domain not found' }, 404); - } - if (outcome.kind === 'refused') { - return outcome.response; - } - if (outcome.kind === 'engine_failed') { - const err = outcome.err; - if (isUniqueViolation(err) && checkpoint !== null) { - const conflict = await compensateEmailDomainRace( - context, - rowId, - outcome.race, - checkpoint, - err, + 400, ); - return context.json({ error: conflict }, 409); } - // Any other checkpoint failure leaves the deployed relay unreferenced - // (the savepoint rolled the UPDATE back): compensate from the captured - // checkpoint before propagating. - if (checkpoint !== null) { - await compensateCheckpointDeploy(context, rowId, outcome.race, checkpoint, { - rowGone: err instanceof EmailDomainRowGoneError, - }); + if (project.status === 'deleting') { + return context.json({ error: 'Project is being deleted' }, 409); } - if (err instanceof EmailDomainRowGoneError) { - return context.json({ error: 'project is being deleted' }, 409); - } - throw err; - } - if (outcome.kind === 'apply_failed') { - const { err, result } = outcome; - if (isUniqueViolation(err)) { - // The concurrent-setup backstop (the schema's partial unique - // indexes): two setups racing one zone both pass the engine's - // CF-side reads, so the loser is caught here — a 409, never a - // falsely-active second row. (A relay-NAME 23505 is no longer - // reachable from a fresh setup — the pre-upload claim absorbs it — - // but the mapping stays as a safety net.) The row stays in its - // pre-apply state; the loser's CF-side work is compensated - // best-effort inside. - const conflict = await compensateEmailDomainRace( - context, - rowId, - outcome.race, - { - zone_id: result.zone_id, - account_id: result.account_id, - relay_worker_name: result.relay_worker_name, - }, - err, - ); - return context.json({ error: conflict }, 409); - } - // A NON-unique apply failure after the engine deployed CF-side: the - // savepoint makes the apply decisively uncommitted, so the - // possibly-deployed relay is compensated best-effort — no orphan - // worker for a zone the row never recorded. Nothing to clean when - // setup failed before the deploy. - if (result.relay_worker_name !== null) { - try { - // Not a name race — the loser owns its relay, so the compensation - // runs with the result's OWN account_id (not nulled). - await removeEmailDomain( - { - row: { - credential_kind: outcome.race.credentialKind, - account_id: result.account_id, - relay_worker_name: result.relay_worker_name, - zone_id: result.zone_id, - }, - credential: outcome.race.credential, - }, + if ( + input.managedBy === 'owner' && + (await getEmailDomainManagement(context.get('db'))) === 'admin' + ) { + const existing = await resolveEmailDomain(context.get('db'), input.domain); + if ( + !existing || + existing.route.project_id !== project.id || + existing.route.managed_by !== 'owner' || + existing.connection.managed_by !== 'owner' || + existing.connection.manager_user_id !== context.get('user').id + ) { + return context.json( { - // Same single-use refresh doctrine as the race compensation. - refreshGrant: () => refreshOauthGrantSerialized(context.get('db'), context.env, rowId), + error: 'email domains on this platform are managed by its administrator', + adminCommand: adminEmailDomainCommand('add', input.domain, project.slug), }, + 403, ); - } catch (compErr) { - console.error('[email] orphan compensation failed:', compErr); } } - throw err; - } - if (outcome.kind === 'ok_sync') { - return context.json( - { - ...serializeEmailDomain(outcome.applied, outcome.result.error), - ...(outcome.result.catch_all === undefined ? {} : { catch_all: outcome.result.catch_all }), - }, - 200, - ); - } - const { result, applied: row } = outcome; - if (requestedMode !== undefined && row.mode !== null && requestedMode !== row.mode) { - return context.json( - { - error: `requested mode ${String(requestedMode)} but ${row.domain} is ${row.mode} on its zone`, - domain: serializeEmailDomain(row, result.error), - }, - 409, - ); + if (input.apiToken && input.apiToken.length > MAX_CREDENTIAL_LENGTH) { + return context.json({ error: 'invalid credential' }, 400); + } + const { operationId } = await requestEmailDomainAdd(context.get('db'), context.env, { + projectId: project.id, + domain: input.domain, + actor: { kind: input.managedBy, userId: context.get('user').id }, + token: input.apiToken, + attemptId: typeof input.attemptId === 'string' ? input.attemptId : undefined, + }); + await runEmailOperation(context.get('db'), context.env, operationId); + return domainResult(context, project, input.domain, operationId); + } catch (error) { + return serviceError(context, error); } - return context.json(serializeEmailDomain(row, result.error), created ? 201 : 200); } - -/** - * POST /domains on an existing row — "add again replaces the token, rules - * stay" (design doc, branch table). The new credential is stored first - * because the oauth_grant engine path refreshes THROUGH the row. Healthy - * rows (active / pending / credential renewal) take the sync path — - * redeploy in place + rotate the relay secret. A row that never finished - * setup re-runs the FULL engine with a fresh relay secret: status - * 'failed', or the relay/account fields missing. The engine is - * re-runnable against the row's recorded progress, so a catch-all - * failure gets its rule written rather than just re-deploying the relay. - * Both branches run inside runEmailDomainEngineSerialized, decided on the - * LOCKED row. - */ -async function replaceEmailDomainCredential( +export async function getEmailDomainStatusForProject( context: Context, - projectId: string, - existing: EmailDomain, - credentialKind: EmailDomain['credential_kind'], - /** `null` only for the platform's own credential, which the row does not store. */ - credential: string | null, - proxyOrigin: string, - requestedMode: unknown, - attemptId: string | undefined, - managedBy: EmailDomain['managed_by'], - projectSlug: string, + project: Project, + rawDomain: string, ): Promise { - const db = context.get('db'); - const domain = existing.domain; - const tokenEnc = - credential === null - ? null - : await encryptEmailDomainToken(context.env, projectId, domain, credential); - // Capture the old grant's CURRENT chain head and commit the replacement - // under one row lock: an interleaved lease refresh between an unlocked - // capture and the commit would rotate the old grant, the commit would - // overwrite the rotated head it persisted, and the revoke below would - // submit the already-consumed token — CF answers 200 either way, so the - // live chain head would be orphaned with no database handle. After the - // commit the row holds the NEW credential, so no old-chain rotation can - // follow. - let oldGrantRefreshToken: string | null = null; - type SwapOutcome = - | 'swapped' - | 'project_gone' - | 'project_deleting' - | 'row_gone' - | Readonly<{ refused: Response }>; - const swap: SwapOutcome = await db.transaction(async (tx): Promise => { - // The PROJECT row lock comes first — teardown's own order — with the - // 'deleting' verdict re-read under it: a replace admitted on the - // route's unlocked entry read could otherwise commit a fresh grant - // AFTER teardown's one-time cleanup enumeration ran, and the cascade - // would then delete the row with the new grant's only handle. - const projectRows = await tx - .select({ status: projects.status }) - .from(projects) - .where(eq(projects.id, projectId)) - .for('update') - .limit(1); - const lockedProject = projectRows[0]; - if (!lockedProject) { - return 'project_gone'; - } - if (lockedProject.status === 'deleting') { - return 'project_deleting'; - } - const locked = await tx - .select({ - credential_kind: emailDomains.credential_kind, - managed_by: emailDomains.managed_by, - account_id: emailDomains.account_id, - token_ciphertext: emailDomains.token_ciphertext, - token_iv: emailDomains.token_iv, - token_key_version: emailDomains.token_key_version, - }) - .from(emailDomains) - .where(eq(emailDomains.id, existing.id)) - .for('update') - .limit(1); - const current = locked[0]; - if (!current) { - return 'row_gone'; - } - // The unlocked checks in addEmailDomainForProject again, on the locked - // row: the other side may have committed its own add in between. - const refused = refuseCrossOwnership(context, { ...current, domain }, managedBy, projectSlug); - if (refused) { - return { refused }; - } - if (credentialKind === 'platform' && !platformAccountAllows(context, current)) { - return { - refused: context.json( - { - error: `the zone for ${domain} is in Cloudflare account ${current.account_id}, not the platform's; re-add it with --token-stdin and a token for that account`, - }, - 409, - ), - }; - } - if (current.credential_kind === 'oauth_grant') { - try { - oldGrantRefreshToken = await decryptEmailDomainToken(context.env, projectId, domain, { - credential_kind: current.credential_kind, - token_ciphertext: current.token_ciphertext, - token_iv: current.token_iv, - token_key_version: current.token_key_version, - }); - } catch (err) { - console.error('[email] old grant decrypt failed; skipping revoke:', err); - } - } - await tx - .update(emailDomains) - .set({ - credential_kind: credentialKind, - token_ciphertext: tokenEnc?.ciphertext ?? null, - token_iv: tokenEnc?.iv ?? null, - token_key_version: tokenEnc?.keyVersion ?? null, - managed_by: managedBy, - // Re-derived by the engine for api_token; grants carry neither. - token_id: null, - token_expires_on: null, - attempt_id: attemptId ?? null, - updated_at: sql`now()`, - }) - .where(eq(emailDomains.id, existing.id)); - return 'swapped'; - }); - if (swap !== 'swapped') { - // Nothing was persisted — the posted grant has no handle. Against a - // deleting project the holder guard spares a re-pasted grant the row - // still stores: teardown's cleanup revokes that one itself. - await revokeRejectedGrant( - context, - credentialKind === 'oauth_grant' && credential !== null ? credential : undefined, - swap === 'project_deleting' ? existing : null, - ); - if (typeof swap === 'object') { - return swap.refused; - } - return swap === 'project_gone' - ? context.json({ error: 'project not found' }, 404) - : swap === 'project_deleting' - ? context.json({ error: 'Project is being deleted' }, 409) - : context.json({ error: 'email domain not found' }, 404); - } - - // Revoke AFTER the commit so a failed replace never strands the old - // grant; a re-pasted identical grant is skipped — revoking it would - // brick the just-stored credential. A revoke failure (network/non-2xx — - // the helper throws on both) is logged, never fatal: the new credential - // is already committed. - if (oldGrantRefreshToken !== null && oldGrantRefreshToken !== credential) { - try { - await revokeOauthGrant(oldGrantRefreshToken); - } catch (err) { - console.error('[email] old grant revoke failed after credential replace:', err); - } - } - - // The branch decision — sync a healthy row, or re-run the full engine - // on one that never finished setup — is made inside the serialized - // section on the LOCKED row: two concurrent retries would otherwise run - // setupEmailDomain outside any lock, upload different relay secrets to - // the same relay, and apply their rows/mirrors in the opposite order - // (the worker holding secret B while KV expects A). - const relaySecret = generateEmailRelaySecret(); - const relayEnc = await encryptEmailDomainRelaySecret(context.env, projectId, domain, relaySecret); - return await runEmailDomainEngineSerialized(context, projectId, existing.id, proxyOrigin, { - relaySecret, - relayEnc, - requestedMode, - created: false, - }); -} - -/** True when the stored mirror already matches the row + hash exactly. */ -async function emailDomainMirrorMatches( - kv: KVNamespace, - row: EmailDomain, - relaySecretSha256: string, -): Promise { - const raw = await kv.get(emailDomainMirrorKey(row.domain)); - if (raw === null) { - return false; - } - try { - const mirror = JSON.parse(raw) as Partial; - return ( - mirror.projectId === row.project_id && - mirror.status === row.status && - mirror.relaySecretSha256 === relaySecretSha256 && - mirror.relayWorkerName === row.relay_worker_name && - mirror.accountId === row.account_id && - mirror.zoneId === row.zone_id && - mirror.mode === row.mode - ); - } catch { - // Unparseable mirror — rewrite. - return false; - } -} - -/** - * The status GET's mirror repair — the same read-compare-write self-heal - * shape as the allowlist listing (`projectAllowlistKvDiffers`): rewrite - * only on a real difference, so polling never amplifies into KV writes. - * - * The write is fenced against project teardown: the mirror is - * authorization material, and once the cascade takes the row nothing - * sweeps the key. Holding `SELECT … FOR UPDATE` on the PROJECT row across - * the KV put gives a total order with teardown's 'deleting' flip and its - * cascade (both take the same lock): either they committed first — the - * project reads deleting or gone, or the domain row is cascaded away — - * and the write is skipped, or this write lands first and teardown's own - * mirror clear removes it. Without the fence, a status poll admitted - * before teardown could recreate an active mirror after teardown cleared - * it, re-authorizing a possibly-stranded relay with no row left to retry - * from. - * - * The payload is derived from the DOMAIN row re-read under FOR UPDATE — - * in project→domain order, the same order sync takes both — never from - * the caller's unlocked snapshot. A sync that rotated the relay secret, - * or a lease that persisted token_revoked, while this poll was between - * its entry read and this transaction would otherwise have its committed - * state overwritten by the stale snapshot: the mirror would go back to - * the pre-rotation hash (inbound rejects every message) or back to - * active (re-authorizing a revoked credential). The drift check also - * re-runs against the locked row — the mirror may have converged while - * this transaction waited on the locks, and the write stays repair-only. - */ -export async function repairEmailDomainMirrorIfDrifted( - db: Db, - env: Pick< - ApiEnv['Bindings'], - 'ROUTING' | 'PROJECT_SECRET_KEYS_JSON' | 'PROJECT_SECRET_ACTIVE_KEY_VERSION' - >, - row: EmailDomain, -): Promise { - const relaySecretSha256 = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(env, row.project_id, row.domain, row), - ); - if (await emailDomainMirrorMatches(env.ROUTING, row, relaySecretSha256)) { - return; + const resolved = await resolveEmailDomain(context.get('db'), rawDomain); + if (!resolved || resolved.route.project_id !== project.id) { + return context.json({ error: 'email domain not found' }, 404); } - await db.transaction(async (tx) => { - const lockedProject = await tx - .select({ status: projects.status }) - .from(projects) - .where(eq(projects.id, row.project_id)) - .for('update') - .limit(1); - if (!lockedProject[0] || lockedProject[0].status === 'deleting') { - return; - } - const locked = await tx + const op = ( + await context + .get('db') .select() - .from(emailDomains) - .where(eq(emailDomains.id, row.id)) - .for('update') - .limit(1); - const current = locked[0]; - if (!current) { - return; - } - const currentSha256 = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(env, current.project_id, current.domain, current), - ); - if (await emailDomainMirrorMatches(env.ROUTING, current, currentSha256)) { - return; - } - await writeEmailDomainMirror(env.ROUTING, current, currentSha256); + .from(emailOperations) + .where(eq(emailOperations.route_id, resolved.route.id)) + .orderBy(sql`${emailOperations.created_at} DESC`) + .limit(1) + )[0]; + return context.json({ + ...serializeEmailRoute(resolved.route, resolved.connection, op?.id), + operationStatus: op?.status ?? null, + error: op?.failure_detail ?? null, }); } - -// --------------------------------------------------------------------------- -// The four operations, shared by the owner routes and the operator surfaces. -// Callers have already resolved and guarded the project (ownership for -// owners; any project for an administrator). Every rejection of an add that -// carried an OAuth grant revokes it first — the CLI mints a fresh user-wide -// grant per attempt and drops its only copy on any error response. -// --------------------------------------------------------------------------- - -export async function addEmailDomainForProject( +export async function syncEmailDomainForProject( context: Context, project: Project, - input: EmailDomainAddInput, + rawDomain: string, + actor: 'owner' | 'admin', ): Promise { - const projectId = project.id; - const postedRefreshToken = - typeof input.refreshToken === 'string' && input.refreshToken.length > 0 - ? input.refreshToken - : undefined; - // Same teardown guard the destinations POST uses — after the parse, so it - // too can revoke the stranded grant. - if (project.status === 'deleting') { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'Project is being deleted' }, 409); - } - // Length is checked on the RAW string before any normalization — same - // reason as the destinations route's address cap: the 400 costs nothing, - // the normalization and regex never run on attacker-sized input. - if (typeof input.domain !== 'string' || input.domain.length > MAX_DOMAIN_LENGTH) { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'invalid domain' }, 400); - } - const domain = normalizeEmailDomain(input.domain); - if (!isValidEmailDomain(domain)) { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'invalid domain' }, 400); - } - if (input.mode !== undefined && input.mode !== 'apex' && input.mode !== 'subdomain') { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'invalid mode' }, 400); - } - // Optional attempt identity from the CLI: when present it is stamped on - // the row so a CLI that lost this POST's answer can recognize its own - // commit. - if ( - input.attemptId !== undefined && - (typeof input.attemptId !== 'string' || - input.attemptId.length < 1 || - input.attemptId.length > 128) - ) { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'invalid attemptId' }, 400); - } - const attemptId = input.attemptId as string | undefined; - const refreshToken = postedRefreshToken; - const apiToken = - typeof input.apiToken === 'string' && input.apiToken.length > 0 ? input.apiToken : undefined; - if (refreshToken !== undefined && apiToken !== undefined) { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'exactly one of refreshToken or apiToken is required' }, 400); - } - // An owner must bring a credential. An administrator who brings none - // registers the zone on the platform's own runtime token — valid only for - // a zone in the platform's account, which the engine enforces. - let credentialKind: EmailDomain['credential_kind']; - let credential: string | null; - if (refreshToken !== undefined) { - credentialKind = 'oauth_grant'; - credential = refreshToken; - } else if (apiToken !== undefined) { - credentialKind = 'api_token'; - credential = apiToken; - } else if (input.managedBy === 'admin') { - if (!context.env.CF_API_TOKEN) { - return context.json({ error: 'platform credential unavailable' }, 503); - } - credentialKind = 'platform'; - credential = null; - } else { - return context.json({ error: 'exactly one of refreshToken or apiToken is required' }, 400); - } - if (credential !== null && credential.length > MAX_CREDENTIAL_LENGTH) { - await revokeRejectedGrant(context, postedRefreshToken); - return context.json({ error: 'invalid credential' }, 400); - } - const db = context.get('db'); - const proxyOrigin = proxyOriginForEmail(context.env); - - const existing = await getEmailDomainRow(db, projectId, domain); - if (existing) { - // Neither side re-runs the other's row. An administrator's row runs on - // the platform's credential, which a replace would swap for the owner's - // grant; an owner's row holds the owner's credential, which an - // administrator's re-add would revoke while flipping the row to admin. - // Both are re-checked under the row lock in replaceEmailDomainCredential. - const refused = refuseCrossOwnership(context, existing, input.managedBy, project.slug); - if (refused) { - await revokeRejectedGrant(context, postedRefreshToken); - return refused; - } - // The platform's own token must never be pointed at a customer zone: a - // row that learned a foreign account (registered with a pasted token) - // cannot be re-run on the platform credential, and refusing here keeps - // the stored token in place. - if (credentialKind === 'platform' && !platformAccountAllows(context, existing)) { - return context.json( - { - error: `the zone for ${domain} is in Cloudflare account ${existing.account_id}, not the platform's; re-add it with --token-stdin and a token for that account`, - }, - 409, - ); - } - // "add again replaces the token, rules stay" (design doc, branch - // table) — the credential renewal path for token_expired / - // token_revoked rows, and the retry path for failed ones. - return await replaceEmailDomainCredential( - context, - projectId, - existing, - credentialKind, - credential, - proxyOrigin, - input.mode, - attemptId, - input.managedBy, - project.slug, - ); - } - - // A domain belongs to exactly one project: the proxy proves a relay - // secret against the single `email-domain:` mirror key, and two - // projects registering the same domain would flip-flop that key and - // misroute inbound mail. Reject before any credential work. - const claimed = await getEmailDomainRowByDomain(db, domain); - if (claimed && claimed.project_id !== projectId) { - await revokeRejectedGrant(context, postedRefreshToken, claimed); - return context.json({ error: 'domain is registered to another project' }, 409); - } - - // New domain. Persist the credential + a fresh relay secret FIRST: the - // oauth_grant setup refreshes THROUGH the row (the serialized dep locks - // and re-reads it), so the grant must be stored before the engine runs. - const relaySecret = generateEmailRelaySecret(); - const tokenEnc = - credential === null - ? null - : await encryptEmailDomainToken(context.env, projectId, domain, credential); - const relayEnc = await encryptEmailDomainRelaySecret(context.env, projectId, domain, relaySecret); - const id = generateId('edom'); - - // The insert runs under the PROJECT row's FOR UPDATE — teardown's own - // first lock (lockAndMarkDeleting, deleteProjectCascade) — with the - // 'deleting' verdict re-read inside it: an add admitted on the unlocked - // entry snapshot could otherwise insert and finish setup AFTER - // teardown's one-time cleanup enumerations ran, and the later cascade - // would delete the row without its domain handle — the mirror, the - // relay/catch-all in the customer account, and a fresh OAuth grant all - // orphaned. The engine then runs in the follow-up serialized section - // (runEmailDomainEngineSerialized), which re-takes this same lock, so - // teardown either marks first (both transactions refuse) or runs - // strictly after the committed setup and cleans everything it created. - type InsertOutcome = 'inserted' | 'project_gone' | 'project_deleting' | 'admin_managed'; - let outcome: InsertOutcome; try { - outcome = await db.transaction(async (tx): Promise => { - const projectRows = await tx - .select({ status: projects.status }) - .from(projects) - .where(eq(projects.id, projectId)) - .for('update') - .limit(1); - const lockedProject = projectRows[0]; - if (!lockedProject) { - return 'project_gone'; - } - if (lockedProject.status === 'deleting') { - return 'project_deleting'; - } - // Authorized inside the locked section like every other ownership rule: - // while administrators manage domains an owner registers no NEW row. A - // row the owner registered before the switch takes the replace path - // above and never reaches this insert. - if (input.managedBy === 'owner' && (await getEmailDomainManagement(tx)) === 'admin') { - return 'admin_managed'; - } - await tx.insert(emailDomains).values({ - id, - project_id: projectId, - domain, - credential_kind: credentialKind, - managed_by: input.managedBy, - attempt_id: attemptId ?? null, - token_ciphertext: tokenEnc?.ciphertext ?? null, - token_iv: tokenEnc?.iv ?? null, - token_key_version: tokenEnc?.keyVersion ?? null, - relay_ciphertext: relayEnc.ciphertext, - relay_iv: relayEnc.iv, - relay_key_version: relayEnc.keyVersion, - }); - return 'inserted'; - }); - } catch (err) { - if (isUniqueViolation(err)) { - // Lost an add/add race on the domain-wide unique index. The winner - // decides the error: another project claimed the domain, or this - // project registered it concurrently. The transaction rolled back, - // so the posted grant was never persisted — revoke it (the - // decrypt-compare guard spares a re-pasted grant the winner stored). - const winner = await getEmailDomainRowByDomain(db, domain); - await revokeRejectedGrant(context, postedRefreshToken, winner); - if (winner && winner.project_id !== projectId) { - return context.json({ error: 'domain is registered to another project' }, 409); - } - return context.json({ error: 'domain concurrently modified, try again' }, 409); + const resolved = await resolveEmailDomain(context.get('db'), rawDomain); + if (!resolved || resolved.route.project_id !== project.id) { + return context.json({ error: 'email domain not found' }, 404); } - throw err; - } - if (outcome !== 'inserted') { - // Nothing was persisted — the posted grant has no handle. - await revokeRejectedGrant(context, postedRefreshToken); - return outcome === 'project_gone' - ? context.json({ error: 'project not found' }, 404) - : outcome === 'admin_managed' - ? context.json( - { - error: 'email domains on this platform are managed by its administrator', - adminCommand: adminEmailDomainCommand('add', domain, project.slug), - }, - 403, - ) - : context.json({ error: 'Project is being deleted' }, 409); + const operationId = await requestEmailDomainSync( + context.get('db'), + context.env, + resolved.route.id, + { kind: actor, userId: context.get('user').id }, + ); + await runEmailOperation(context.get('db'), context.env, operationId); + return domainResult(context, project, rawDomain, operationId); + } catch (error) { + return serviceError(context, error); } - - return await runEmailDomainEngineSerialized(context, projectId, id, proxyOrigin, { - relaySecret, - relayEnc, - requestedMode: input.mode, - created: true, - }); } - -export async function getEmailDomainStatusForProject( +export async function rotateEmailIngressSecretForProject( context: Context, project: Project, rawDomain: string, + actor: 'owner' | 'admin', + attemptId?: string, ): Promise { - const projectId = project.id; - const domain = normalizeEmailDomain(rawDomain); - const db = context.get('db'); - const row = await getEmailDomainRow(db, projectId, domain); - if (!row) { - return context.json({ error: 'email domain not found' }, 404); - } - - // Re-probe with the decrypted credential. Probe failures never hide the - // stored view — the row answers with credential_status 'probe_failed', - // the same non-fatal shape as the destinations listing's CF refresh. - let credentialStatus: 'active' | 'expired' | 'revoked' | 'probe_failed'; - let probeClient: CfCustomerClient | null = null; - let tokenPatch: { token_id: string | null; token_expires_on: string | null } | null = null; - if (row.credential_kind === 'platform') { - // The runtime token is not a user token, so /user/tokens/verify does - // not describe it; the probe is a zone-scoped read the token needs for - // every later step. A refusal reads probe_failed — never token_revoked - // or token_expired, which describe a stored credential's lifecycle. - try { - const client = createCfCustomerClient( - await decryptEmailDomainToken(context.env, projectId, row.domain, row), - ); - if (row.zone_id !== null) { - await client.getRoutingSettings(row.zone_id); - } else if ((await findZoneForEmailDomain(client, row.domain)) === null) { - throw new Error(`the platform credential cannot see a zone for ${row.domain}`); - } - credentialStatus = 'active'; - probeClient = client; - } catch (err) { - console.error('[email] platform credential probe failed:', err); - credentialStatus = 'probe_failed'; - } - } else if (row.credential_kind === 'api_token') { - try { - const credential = await decryptEmailDomainToken(context.env, projectId, row.domain, row); - const client = createCfCustomerClient(credential); - const verification = await client.verifyToken(); - if (verification.status === 'active') { - credentialStatus = 'active'; - probeClient = client; - tokenPatch = { - token_id: verification.id, - token_expires_on: verification.expires_on ?? null, - }; - } else if (verification.status === 'expired') { - credentialStatus = 'expired'; - } else { - credentialStatus = 'revoked'; - } - } catch (err) { - console.error('[email] domain credential probe failed:', err); - credentialStatus = 'probe_failed'; - } - } else { - try { - // The ONLY probe a grant supports is one refresh round-trip. The - // rotation is persisted under the row lock inside; the access token - // rides the drift probe below and is then dropped. - const tokens = await refreshOauthGrantSerialized(db, context.env, row.id); - credentialStatus = 'active'; - probeClient = createCfCustomerClient(tokens.accessToken); - } catch (err) { - if (err instanceof EmailDomainCredentialChangedError) { - // A replace committed mid-probe — the probe is void, nothing - // was written, and the fresh re-read below answers for the - // replacement credential. - credentialStatus = 'probe_failed'; - } else if (err instanceof OAuthGrantError && err.code === 'invalid_grant') { - // The row was already marked token_revoked under the lock. - credentialStatus = 'revoked'; - } else { - console.error('[email] domain grant probe failed:', err); - credentialStatus = 'probe_failed'; - } - } - } - - // Persist what the probe learned. A dead credential flips the row (and, - // via the mirror repair below, the proxy's view) to token_expired / - // token_revoked; a healthy api_token refreshes token_id/expires_on. - // Probes never RESURRECT a row — re-running add is the renewal path. - const patch: { - status?: EmailDomain['status']; - token_id?: string | null; - token_expires_on?: string | null; - } = {}; - if (credentialStatus === 'expired' && row.status !== 'token_expired') { - patch.status = 'token_expired'; - } else if (credentialStatus === 'revoked' && row.status !== 'token_revoked') { - patch.status = 'token_revoked'; - } - if ( - tokenPatch && - (tokenPatch.token_id !== row.token_id || tokenPatch.token_expires_on !== row.token_expires_on) - ) { - patch.token_id = tokenPatch.token_id; - patch.token_expires_on = tokenPatch.token_expires_on; - } - if (Object.keys(patch).length > 0) { - // Fenced on the probed credential's identity: a replace committing - // mid-probe (renewing an expired token is the case that bites) must - // not have the OLD credential's verdict — status flip or token - // metadata — stamped on the NEW one. A fenced-out patch voids the - // probe: the fresh re-read answers, and the next poll re-probes. - const applied = await db - .update(emailDomains) - .set({ ...patch, updated_at: sql`now()` }) - .where( - and( - eq(emailDomains.id, row.id), - eq(emailDomains.credential_kind, row.credential_kind), - // A platform row stores no ciphertext; `= NULL` would never match. - row.token_ciphertext === null - ? isNull(emailDomains.token_ciphertext) - : eq(emailDomains.token_ciphertext, row.token_ciphertext), - ), - ) - .returning({ id: emailDomains.id }); - if (applied.length === 0) { - credentialStatus = 'probe_failed'; - probeClient = null; - } - } - - let fresh = await getEmailDomainRowById(db, row.id); - if (!fresh) { - // Project teardown's cascade can take the row mid-request. - return context.json({ error: 'email domain not found' }, 404); - } - - // Self-clear recorded remaining steps on observable evidence. The - // routing-subdomain step's effect is public MX records naming - // Cloudflare's inbound exchanges; the sending-onboarding step's is - // the customer-credential read-back showing the subdomain onboarded - // (a Workers Paid upgrade plus a sync, which re-attempts the POST). - // No evidence — the probe failed or the step is genuinely undone — - // leaves the row for the next poll. The row flips pending → active - // only once no INBOUND-BLOCKING step (routing_subdomain) remains; a - // sending_onboarding step rides along on an active row. Suppressed - // while a removal failure is pending — the same doctrine as the - // mirror repair below: the row is mid-removal, and neither its - // status nor its setup state is this route's to rewrite. - const probedSetupState = fresh.setup_state; - const pendingSteps = probedSetupState?.remaining_steps; - if ( - probedSetupState && - probedSetupState.failed_step !== 'remove' && - pendingSteps && - pendingSteps.length > 0 - ) { - const cleared: Array = []; - if (pendingSteps.includes(ROUTING_SUBDOMAIN_STEP) && (await domainHasRoutingMx(fresh.domain))) { - cleared.push(ROUTING_SUBDOMAIN_STEP); - } + try { + const resolved = await resolveEmailDomain(context.get('db'), rawDomain); if ( - pendingSteps.includes(SENDING_ONBOARDING_STEP) && - probeClient !== null && - fresh.zone_id !== null && - (await sendingOnboardedReadback(probeClient, fresh.zone_id, fresh.domain)) + !resolved || + resolved.route.project_id !== project.id || + resolved.route.desired_state !== 'active' ) { - cleared.push(SENDING_ONBOARDING_STEP); - } - if (cleared.length > 0) { - const keptSteps = pendingSteps.filter((step) => !cleared.includes(step)); - // Fenced on the probed state: a revocation (or a removal-failure - // marker) landing while the evidence checks were in flight must - // not be overwritten back to a live state — the subsequent - // mirror repair would reauthorize inbound against it. A - // fenced-out update voids the self-clear: the re-read answers - // this poll, and the next poll re-proves the evidence. - await db - .update(emailDomains) - .set({ - ...(fresh.status === 'pending' && !keptSteps.includes(ROUTING_SUBDOMAIN_STEP) - ? { status: 'active' as const } - : {}), - setup_state: keptSteps.length > 0 ? { remaining_steps: keptSteps } : null, - updated_at: sql`now()`, - }) - .where( - and( - eq(emailDomains.id, fresh.id), - eq(emailDomains.status, fresh.status), - sql`${emailDomains.setup_state} IS NOT DISTINCT FROM ${JSON.stringify(probedSetupState)}::jsonb`, - ), - ); - fresh = await getEmailDomainRowById(db, row.id); - if (!fresh) { - return context.json({ error: 'email domain not found' }, 404); - } + return context.json({ error: 'email domain not found' }, 404); } - } - - // Relay drift: the version the row recorded vs the embedded - // RELAY_VERSION, plus an existence probe — the customer can edit or - // delete the relay in their own account, and status reports drift - // rather than fighting it. - let relayMissing: boolean | null = null; - if (probeClient && fresh.account_id && fresh.relay_worker_name) { - try { - relayMissing = !(await probeClient.relayScriptExists( - fresh.account_id, - fresh.relay_worker_name, - )); - } catch (err) { - console.error('[email] relay existence probe failed:', err); - } - } - const relayDrift = fresh.relay_version !== RELAY_VERSION || relayMissing === true; - - // Catch-all drift probe — the same try/catch-and-report-never-fight - // doctrine as the relay probe above. Read-only: healing is the sync - // POST's job (its ensure runs in the engine). - let catchAll: 'points_here' | 'points_elsewhere' | 'missing' | 'disabled' | 'unknown' = 'unknown'; - if (probeClient && fresh.zone_id && fresh.relay_worker_name) { - try { - const rule = await probeClient.getCatchAll(fresh.zone_id); - catchAll = - rule === null - ? 'missing' - : !rule.enabled - ? 'disabled' - : rule.workerName === fresh.relay_worker_name - ? 'points_here' - : 'points_elsewhere'; - } catch (err) { - console.error('[email] catch-all probe failed:', err); + const operationId = await requestEmailSecretRotation( + context.get('db'), + context.env, + resolved.connection.id, + { kind: actor, userId: context.get('user').id }, + attemptId, + ); + await runEmailOperation(context.get('db'), context.env, operationId); + const operation = ( + await context + .get('db') + .select() + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .limit(1) + )[0]; + const current = await resolveEmailDomain(context.get('db'), rawDomain); + if (!current) { + return context.json({ error: 'email domain not found' }, 404); } + return context.json({ + ...serializeEmailRoute(current.route, current.connection, operationId), + operationStatus: operation?.status, + error: operation?.failure_detail, + }); + } catch (error) { + return serviceError(context, error); } - const catchAllDrift = - (fresh.status === 'active' || fresh.status === 'pending') && - (catchAll === 'points_elsewhere' || catchAll === 'missing' || catchAll === 'disabled'); - - // This GET is the mirror's repair point (the same read-compare-write - // self-heal shape as the allowlist listing): probe transitions and any - // other drift land here; no difference means no write. Suppressed - // while a removal failure is pending — the row is mid-removal, and the - // proxy mirror must not be "repaired" against a state the operator is - // about to finish removing. - if (fresh.setup_state?.failed_step !== 'remove') { - await repairEmailDomainMirrorIfDrifted(db, context.env, fresh); - } - - return context.json({ - ...serializeEmailDomain(fresh), - credential_status: credentialStatus, - current_relay_version: RELAY_VERSION, - relay_drift: relayDrift, - relay_missing: relayMissing, - catch_all: catchAll, - catch_all_drift: catchAllDrift, - }); -} - -export async function syncEmailDomainForProject( - context: Context, - project: Project, - rawDomain: string, - /** Who asked: an owner may not touch an administrator's row, and vice versa. */ - actor: EmailDomain['managed_by'], -): Promise { - const projectId = project.id; - // Sync mutates CF state and the row — same teardown guard as add/remove. - if (project.status === 'deleting') { - return context.json({ error: 'Project is being deleted' }, 409); - } - const domain = normalizeEmailDomain(rawDomain); - const db = context.get('db'); - const row = await getEmailDomainRow(db, projectId, domain); - if (!row) { - return context.json({ error: 'email domain not found' }, 404); - } - // Sync redeploys the relay in place at RELAY_VERSION and rotates its - // secret (overwrite, never read-compare — worker secrets are - // write-only). The row and credential are re-read inside the row - // lock, so a replace that lands while this request waits is synced - // as the NEW credential, never verified as the superseded one. - return syncEmailDomainAndApply(context, projectId, row.id, proxyOriginForEmail(context.env), { - managedBy: actor, - projectSlug: project.slug, - }); } - export async function removeEmailDomainForProject( context: Context, project: Project, rawDomain: string, force: boolean, - /** Who asked: an owner may not touch an administrator's row, and vice versa. */ - actor: EmailDomain['managed_by'], + actor: 'owner' | 'admin', ): Promise { - const projectId = project.id; - if (project.status === 'deleting') { - return context.json({ error: 'Project is being deleted' }, 409); - } - const domain = normalizeEmailDomain(rawDomain); - const db = context.get('db'); - const row = await getEmailDomainRow(db, projectId, domain); - if (!row) { - return context.json({ error: 'email domain not found' }, 404); - } - // Remove under the row's serialized lock, with the row and credential - // re-read inside it: a replace that commits between this request's - // entry read and the cleanup must not have its fresh credential - // orphaned by the row delete — the replace never invalidates an old - // api_token, so cleanup built on a stale snapshot would SUCCEED, the - // row would be deleted, and a newly committed oauth grant's only - // handle would go with it (live at CF with its broad scopes, - // revocable by nobody). The lock serializes with the replace's commit - // and with lease refreshes; the serialized helpers take THIS tx — - // passing the pool handle here would deadlock. - // - // removeEmailDomain never throws; a decrypt failure skips CF cleanup - // entirely. A failed DESTRUCTIVE step (catch-all or relay delete) - // KEEPS the row so the operator can retry — unless forced, or the - // grant is already dead: token_revoked rows are always deleted (CF - // may be unreachable and keeping buys no retry leverage — re-add is - // the renewal path), and a 'revoke_grant'-only failure still deletes - // (a stranded grant breaks no mail). - type Removal = - | Readonly<{ kind: 'removed'; failedSteps: ReadonlyArray }> - | Readonly<{ kind: 'kept'; failedSteps: ReadonlyArray }> - | Readonly<{ kind: 'vanished' }> - | Readonly<{ kind: 'refused'; response: Response }>; - const removal: Removal = await withEmailDomainRowLock(db, row.id, async (tx) => { - const locked = await tx.select().from(emailDomains).where(eq(emailDomains.id, row.id)).limit(1); - const current = locked[0]; - if (!current) { - // Teardown's cascade can take the row mid-request — the - // idempotent delete branch below proceeds. - return { kind: 'vanished' }; - } - // Authorization on the LOCKED row: the other side may have committed - // its own add between this request's entry read and the lock. - const refused = refuseCrossOwnership(context, current, actor, project.slug, 'remove'); - if (refused) { - return { kind: 'refused', response: refused }; - } - let failedSteps: ReadonlyArray; - try { - const credential = await decryptEmailDomainToken( - context.env, - projectId, - current.domain, - current, - ); - const result = await removeEmailDomain( - { - row: { - credential_kind: current.credential_kind, - account_id: current.account_id, - relay_worker_name: current.relay_worker_name, - zone_id: current.zone_id, - }, - credential, - }, - { - // Refresh rotations must persist through the row's serialized - // chain while the row lives — in the keep-row world a failed - // removal KEEPS the row, and a bricked rotation would kill - // the retry. The revoke likewise goes through the chain: it - // revokes the row's LIVE head, so a lease refresh that - // committed before this removal cannot leave a rotated grant - // orphaned behind a 200-for-a-consumed-token. - refreshGrant: () => refreshOauthGrantSerialized(tx, context.env, current.id), - ...(current.credential_kind === 'oauth_grant' - ? { revokeGrant: () => revokeOauthGrantSerialized(tx, context.env, current.id) } - : {}), - }, - ); - failedSteps = result.failed_steps; - } catch (err) { - console.error('[email] domain remove credential decrypt failed:', err); - failedSteps = ['delete_relay', 'catch_all']; + try { + const resolved = await resolveEmailDomain(context.get('db'), rawDomain); + if (!resolved || resolved.route.project_id !== project.id) { + return context.json({ error: 'email domain not found' }, 404); } - - const destructive = failedSteps.some((s) => s === 'catch_all' || s === 'delete_relay'); - // Decide on the CURRENT status, not the pre-removal snapshot: an - // invalid_grant inside the removal's refresh persisted - // token_revoked through THIS tx, and a now-revoked row takes the - // unconditional-delete path exactly like one revoked before the - // request — keeping it would leave its stale active mirror - // accepting inbound with repair suppressed. The row cannot vanish - // here — this tx holds its lock. - const currentStatus = ( - await tx - .select({ status: emailDomains.status }) - .from(emailDomains) - .where(eq(emailDomains.id, current.id)) + const operationId = await requestEmailDomainRemove( + context.get('db'), + context.env, + resolved.route.id, + { kind: actor, userId: context.get('user').id }, + ); + await runEmailOperation(context.get('db'), context.env, operationId); + const op = ( + await context + .get('db') + .select() + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) .limit(1) - )[0]?.status; - if (destructive && !force && currentStatus !== 'token_revoked') { - await markEmailDomainRemovalFailed(tx, current.id, failedSteps); - return { kind: 'kept', failedSteps }; - } - - // Mirror key BEFORE the row — never destroy the record a retry - // would re-derive the mirror from (the destinations DELETE - // inversion). A KV failure rolls the transaction back with the row - // intact, so the retry can finish it. - await clearEmailDomainMirror(context.env.ROUTING, current.domain); - await tx.delete(emailDomains).where(eq(emailDomains.id, current.id)); - return { kind: 'removed', failedSteps }; - }); - - if (removal.kind === 'refused') { - return removal.response; - } - if (removal.kind === 'kept') { - return context.json({ ok: false, removed: false, failed_steps: removal.failedSteps }, 200); + )[0]; + return context.json({ + ok: op?.status === 'completed', + removed: op?.status === 'completed', + operationId, + operationStatus: op?.status, + error: op?.failure_detail, + forced: force && op?.status !== 'completed', + }); + } catch (error) { + return serviceError(context, error); } - if (removal.kind === 'vanished') { - // Teardown already cleared the mirror; the re-clear is idempotent. - await clearEmailDomainMirror(context.env.ROUTING, row.domain); +} +export async function getEmailOperationForProject( + context: Context, + project: Project, + key: string, +): Promise { + const found = await getEmailOperation(context.get('db'), project.id, key); + if (!found) { + return context.json({ error: 'email operation not found' }, 404); } - const failedSteps = removal.kind === 'removed' ? removal.failedSteps : []; + const status = await getEmailDomainStatusForProject(context, project, found.route.domain); + const domain = (await status.json()) as Record; return context.json({ - ok: true, - removed: true, - ...(force && failedSteps.length > 0 ? { forced: true } : {}), - ...(failedSteps.length > 0 ? { failed_steps: failedSteps } : {}), + operationId: found.operation.id, + attemptId: found.operation.idempotency_key, + status: found.operation.status, + domain: found.route.domain, + readiness: domain.readiness, + failedStep: found.operation.current_step, + error: found.operation.failure_detail, }); } diff --git a/platform/packages/api/src/email/ingress-resolution.ts b/platform/packages/api/src/email/ingress-resolution.ts new file mode 100644 index 000000000..17152da9c --- /dev/null +++ b/platform/packages/api/src/email/ingress-resolution.ts @@ -0,0 +1,311 @@ +import { and, eq } from 'drizzle-orm'; +import { Hono } from 'hono'; +import { hmacVerifyState } from '../auth/hmac.ts'; +import type { ApiEnv } from '../env.ts'; +import { getVersionedWorkerName } from '../project-secrets.ts'; +import { deployments, projects, users } from '../schema.ts'; +import { emailProjectControls } from './admission-schema.ts'; +import { emailZoneConnections } from './connection-schema.ts'; +import { + emailInstallationId, + readConnectionSecret, + readStagedConnectionSecret, + resolveEmailIngress, +} from './connection-service.ts'; +import { EmailInternalBodyError, readBoundedInternalJson } from './internal-body.ts'; + +const app = new Hono(); +app.use('*', async (context, next) => { + if (!context.req.header('x-void-internal')) { + return context.json({ error: 'forbidden' }, 403); + } + await next(); +}); +const encoder = new TextEncoder(); +function sameSecret(a: string, b: string): boolean { + const aa = encoder.encode(a), + bb = encoder.encode(b); + if (aa.byteLength !== bb.byteLength) { + return false; + } + let difference = 0; + for (let i = 0; i < aa.byteLength; i++) { + difference |= aa[i] ^ bb[i]; + } + return difference === 0; +} + +app.post('/probe-ingress', async (context) => { + let body: { accountId?: unknown; zoneId?: unknown; ingressName?: unknown; secret?: unknown }; + try { + body = (await readBoundedInternalJson(context.req.raw, 2048)) as typeof body; + } catch (error) { + return error instanceof EmailInternalBodyError + ? context.json({ error: error.message }, error.status) + : context.json({ error: 'invalid body' }, 400); + } + if (!body || typeof body !== 'object' || Array.isArray(body)) { + return context.json({ error: 'invalid body' }, 400); + } + const { accountId, zoneId, ingressName, secret } = body; + if ( + [accountId, zoneId, ingressName, secret].some( + (value) => typeof value !== 'string' || value.length === 0 || value.length > 512, + ) + ) { + return context.json({ error: 'invalid probe' }, 400); + } + const signed = `email-probe-v1\n${accountId}\n${zoneId}\n${ingressName}`; + const auth = context.req.header('x-void-internal'); + if (!auth || !(await hmacVerifyState(signed, auth, context.env.JWT_SECRET))) { + return context.json({ error: 'forbidden' }, 403); + } + const connection = ( + await context + .get('db') + .select() + .from(emailZoneConnections) + .where( + and( + eq(emailZoneConnections.installation_id, emailInstallationId(context.env)), + eq(emailZoneConnections.account_id, accountId as string), + eq(emailZoneConnections.zone_id, zoneId as string), + eq(emailZoneConnections.ingress_worker_name, ingressName as string), + ), + ) + .limit(1) + )[0]; + if (!connection) { + return context.json({ error: 'ingress unavailable' }, 404); + } + let accepted = false; + try { + accepted = sameSecret(await readConnectionSecret(context.env, connection), secret as string); + if (!accepted && connection.staged_secret_generation !== null) { + accepted = sameSecret( + await readStagedConnectionSecret(context.env, connection), + secret as string, + ); + } + } catch { + return context.json({ error: 'ingress identity unavailable' }, 503); + } + if (!accepted) { + return context.json({ error: 'forbidden' }, 403); + } + return context.body(null, 204); +}); + +/** Gateway-only read. The HMAC authenticates the service call; the zone + * bearer separately proves the deployed Cloudflare ingress identity. */ +app.post('/resolve-ingress', async (context) => { + let body: { + accountId?: unknown; + zoneId?: unknown; + ingressName?: unknown; + from?: unknown; + to?: unknown; + secret?: unknown; + native?: unknown; + }; + try { + body = (await readBoundedInternalJson(context.req.raw, 4096)) as typeof body; + } catch (error) { + return error instanceof EmailInternalBodyError + ? context.json({ error: error.message }, error.status) + : context.json({ error: 'invalid body' }, 400); + } + if (!body || typeof body !== 'object' || Array.isArray(body)) { + return context.json({ error: 'invalid body' }, 400); + } + const { accountId, zoneId, ingressName, to, secret } = body; + const native = body.native === true; + if ( + [accountId, zoneId, ingressName, to].some( + (x) => typeof x !== 'string' || x.length === 0 || x.length > 512, + ) || + (!native && (typeof secret !== 'string' || secret.length === 0 || secret.length > 512)) + ) { + return context.json({ error: 'invalid ingress identity' }, 400); + } + const recipient = (to as string).toLowerCase(); + const signed = `email-ingress-v1\n${accountId}\n${zoneId}\n${ingressName}\n${recipient}`; + const auth = context.req.header('x-void-internal'); + if (!auth || !(await hmacVerifyState(signed, auth, context.env.JWT_SECRET))) { + return context.json({ error: 'forbidden' }, 403); + } + const db = context.get('db'); + const resolved = await resolveEmailIngress(db, { + installationId: emailInstallationId(context.env), + accountId: accountId as string, + zoneId: zoneId as string, + ingressName: ingressName as string, + recipient: recipient, + }); + if (!resolved) { + return context.json({ error: 'unregistered or disabled email domain' }, 404); + } + const route = resolved.route; + if (native) { + const shared = context.env as ApiEnv['Bindings'] & { + EMAIL_SHARED_ACCOUNT_ID?: string; + EMAIL_SHARED_ZONE_ID?: string; + EMAIL_SHARED_INGRESS_NAME?: string; + }; + if ( + resolved.connection.managed_by !== 'admin' || + resolved.connection.account_id !== context.env.CF_ACCOUNT_ID || + !shared.EMAIL_SHARED_ACCOUNT_ID || + !shared.EMAIL_SHARED_ZONE_ID || + !shared.EMAIL_SHARED_INGRESS_NAME || + shared.EMAIL_SHARED_ACCOUNT_ID !== accountId || + shared.EMAIL_SHARED_ZONE_ID !== zoneId || + shared.EMAIL_SHARED_INGRESS_NAME !== ingressName + ) { + return context.json({ error: 'forbidden' }, 403); + } + if ( + route.addressing === 'shared' && + route.domain !== context.env.EMAIL_SENDER_DOMAIN?.toLowerCase() + ) { + return context.json({ error: 'forbidden' }, 403); + } + } else { + let expected: string; + try { + expected = await readConnectionSecret(context.env, resolved.connection); + } catch { + return context.json({ error: 'ingress identity unavailable' }, 503); + } + let authorized = sameSecret(expected, secret as string); + if (!authorized && resolved.connection.staged_secret_generation !== null) { + try { + authorized = sameSecret( + await readStagedConnectionSecret(context.env, resolved.connection), + secret as string, + ); + } catch { + return context.json({ error: 'staged ingress identity unavailable' }, 503); + } + } + if ( + !authorized && + resolved.connection.previous_secret_hash && + resolved.connection.previous_secret_until && + Date.parse(resolved.connection.previous_secret_until) > Date.now() + ) { + const hash = Array.from( + new Uint8Array( + await crypto.subtle.digest('SHA-256', encoder.encode(JSON.stringify(secret))), + ), + (x) => x.toString(16).padStart(2, '0'), + ).join(''); + authorized = sameSecret(resolved.connection.previous_secret_hash, hash); + } + if (!authorized) { + return context.json({ error: 'forbidden' }, 403); + } + } + let projectId = route.project_id; + let slug: string; + if (route.addressing === 'shared') { + const local = recipient.slice(0, recipient.lastIndexOf('@')); + const slugPart = local.split('+', 1)[0]; + if (!slugPart) { + return context.json({ error: 'unknown shared recipient' }, 404); + } + const project = ( + await db + .select({ + id: projects.id, + slug: projects.slug, + status: projects.status, + active_deployment_id: projects.active_deployment_id, + }) + .from(projects) + .where(and(eq(projects.slug, slugPart), eq(projects.status, 'active'))) + .limit(1) + )[0]; + if (!project) { + return context.json({ error: 'unknown shared recipient' }, 404); + } + projectId = project.id; + slug = project.slug; + } else { + const project = ( + await db + .select({ id: projects.id, slug: projects.slug, status: projects.status }) + .from(projects) + .where(eq(projects.id, projectId!)) + .limit(1) + )[0]; + if (!project || project.status !== 'active') { + return context.json({ error: 'project unavailable' }, 404); + } + slug = project.slug; + } + const authority = ( + await db + .select({ + projectStatus: projects.status, + suspendedReason: users.suspended_reason, + emailSuspendedAt: emailProjectControls.suspended_at, + }) + .from(projects) + .innerJoin(users, eq(projects.user_id, users.id)) + .leftJoin(emailProjectControls, eq(emailProjectControls.project_id, projects.id)) + .where(eq(projects.id, projectId!)) + .limit(1) + )[0]; + if ( + !authority || + authority.projectStatus !== 'active' || + authority.suspendedReason || + authority.emailSuspendedAt + ) { + return context.json({ error: 'project email is suspended' }, 403); + } + const project = ( + await db + .select({ active_deployment_id: projects.active_deployment_id }) + .from(projects) + .where(eq(projects.id, projectId!)) + .limit(1) + )[0]; + const deploymentId = project?.active_deployment_id; + if (!deploymentId) { + return context.json({ error: 'project has no deployment' }, 409); + } + const deployment = ( + await db + .select({ manifest: deployments.manifest, status: deployments.status }) + .from(deployments) + .where(and(eq(deployments.id, deploymentId), eq(deployments.project_id, projectId!))) + .limit(1) + )[0]; + let protocolVersion: unknown; + try { + protocolVersion = deployment?.manifest + ? JSON.parse(deployment.manifest).emailProtocolVersion + : null; + } catch { + protocolVersion = null; + } + if (deployment?.status !== 'live' || protocolVersion !== 1) { + return context.json( + { error: 'active deployment does not support email gateway protocol' }, + 409, + ); + } + return context.json({ + projectId, + slug, + deploymentId, + workerName: getVersionedWorkerName(slug, deploymentId), + addressing: route.addressing, + domain: route.domain, + connectionId: resolved.connection.id, + }); +}); + +export default app; diff --git a/platform/packages/api/src/email/internal-body.ts b/platform/packages/api/src/email/internal-body.ts new file mode 100644 index 000000000..f84c20b30 --- /dev/null +++ b/platform/packages/api/src/email/internal-body.ts @@ -0,0 +1,66 @@ +/** Read an internal JSON request within a strict byte and time budget. */ +export class EmailInternalBodyError extends Error { + constructor( + readonly status: 400 | 408 | 413, + message: string, + ) { + super(message); + } +} + +export async function readBoundedInternalJson( + request: Request, + maxBytes: number, +): Promise { + const length = Number(request.headers.get('content-length')); + if (Number.isFinite(length) && length > maxBytes) { + throw new EmailInternalBodyError(413, 'body too large'); + } + const reader = request.body?.getReader(); + if (!reader) { + throw new EmailInternalBodyError(400, 'invalid body'); + } + const chunks: Array = []; + let size = 0, + timedOut = false; + const deadline = setTimeout(() => { + timedOut = true; + void reader.cancel().catch(() => {}); + }, 5_000); + try { + for (;;) { + const { done, value } = await reader.read(); + if (timedOut) { + throw new EmailInternalBodyError(408, 'body timed out'); + } + if (done) { + break; + } + size += value.byteLength; + if (size > maxBytes) { + await reader.cancel(); + throw new EmailInternalBodyError(413, 'body too large'); + } + chunks.push(value); + } + } catch (error) { + if (timedOut) { + throw new EmailInternalBodyError(408, 'body timed out'); + } + throw error; + } finally { + clearTimeout(deadline); + reader.releaseLock(); + } + const bytes = new Uint8Array(size); + let offset = 0; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.byteLength; + } + try { + return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); + } catch { + throw new EmailInternalBodyError(400, 'invalid body'); + } +} diff --git a/platform/packages/api/src/email/relay-worker.ts b/platform/packages/api/src/email/relay-worker.ts index edef2890b..060ee5abd 100644 --- a/platform/packages/api/src/email/relay-worker.ts +++ b/platform/packages/api/src/email/relay-worker.ts @@ -1,22 +1,20 @@ /** * The relay worker — the one worker the platform deploys into the - * CUSTOMER's Cloudflare account, one per registered email domain (design - * doc 0078, "The two paths"). A routing rule can only name a worker in its - * own account, so inbound from a customer zone cannot reach the proxy - * directly; this ~30-line worker is the cross-account hop. It streams the - * raw MIME, unparsed and unbuffered, into the proxy's POST /email/relay - * with the domain's relay secret as the bearer. + * CUSTOMER's Cloudflare account, one per connected zone. An Email Routing + * catch-all can only name a Worker in its own account, so this Worker streams + * the raw MIME and SMTP envelope into the installation email gateway's + * POST /email/ingress, authenticated by the zone connection secret. * * The source is embedded as a string because the api deploys it at runtime * into an account it does not own — it is never bundled into the api * worker itself. * - * `void email domain sync` redeploys at the current RELAY_VERSION and - * rotates the secret. The deployed worker NAME is stable forever: renaming - * a worker detaches every routing rule that points at it. + * `void email domain sync` redeploys at the current RELAY_VERSION. Secret + * rotation is a separate durable operation proven against the deployed + * Worker before promotion. The Worker name stays stable for its zone. */ -export const RELAY_VERSION = 3; +export const RELAY_VERSION = 6; // Baked into the upload metadata; bump with RELAY_VERSION if the source // ever depends on newer runtime behavior. @@ -26,43 +24,54 @@ export const RELAY_COMPATIBILITY_DATE = '2026-09-01'; // the source reads. Pinned to RELAY_SOURCE by the unit tests — the two // must move together or the deployed relay reads undefined bindings. export const RELAY_SECRET_BINDING = 'VOID_RELAY_SECRET'; -export const RELAY_PROXY_ORIGIN_BINDING = 'VOID_PROXY_ORIGIN'; -export const RELAY_EMAIL_DOMAIN_BINDING = 'VOID_EMAIL_DOMAIN'; +export const RELAY_GATEWAY_ORIGIN_BINDING = 'VOID_EMAIL_GATEWAY_ORIGIN'; +export const RELAY_ACCOUNT_BINDING = 'VOID_EMAIL_ACCOUNT'; +export const RELAY_ZONE_BINDING = 'VOID_EMAIL_ZONE'; +export const RELAY_INGRESS_BINDING = 'VOID_EMAIL_INGRESS'; +// Legacy exports keep older pre-release fixtures compiling. +export const RELAY_PROXY_ORIGIN_BINDING = RELAY_GATEWAY_ORIGIN_BINDING; +export const RELAY_EMAIL_DOMAIN_BINDING = RELAY_ZONE_BINDING; /** - * Module-syntax worker source. Wire contract with the proxy (design doc - * 0078, contract 3): POST {VOID_PROXY_ORIGIN}/email/relay, bearer = - * VOID_RELAY_SECRET, X-Void-Email-* headers carrying the domain and the - * envelope sender/recipient, body = the raw MIME streamed straight from - * message.raw. The stream is piped through a FixedLengthStream(rawSize): + * Module-syntax Worker source. POST /email/ingress on the configured gateway + * with zone identity, envelope sender/recipient and the unparsed MIME. + * The stream is piped through a FixedLengthStream(rawSize): * the runtime derives Content-Length from the body and IGNORES a manually - * set one, so a plain ReadableStream would go out chunked — and the proxy + * set one, so a plain ReadableStream would go out chunked — and the gateway * rejects a length-less body before any crypto. The POST rides * ctx.waitUntil AND is awaited: waitUntil keeps the stream alive, the * await is what lets a non-2xx answer reject the message. The reject * reason is deliberately generic — it travels back to the original sender * in a bounce. * - * The recipient-domain guard is the relay-side half of the proxy's - * recipient-domain attribution rule: a catch-all rule can be zone-wide, - * so mail addressed to a DIFFERENT domain on the same zone can land here. - * That mail is not this relay's to forward — the proxy would (correctly) - * refuse it against this domain's secret — so it is refused here, loudly, - * rather than dropped. RELAY_VERSION 3. + * The gateway resolves the exact envelope recipient domain against the + * authoritative connection route map. This relay therefore forwards every + * recipient on its zone, including sibling domains. */ export const RELAY_SOURCE = `export default { + async fetch(request, env) { + const url = new URL(request.url); + if (request.method !== 'POST' || url.pathname !== '/__void/email/probe') return new Response(null, { status: 404 }); + const challenge = request.headers.get('X-Void-Probe-Challenge') ?? ''; + const generation = request.headers.get('X-Void-Probe-Generation') ?? ''; + if (!/^[a-f0-9]{64}$/.test(challenge) || !/^[1-9][0-9]{0,9}$/.test(generation)) return new Response(null, { status: 400 }); + const payload = ['email-relay-proof-v1', env.VOID_EMAIL_ACCOUNT, env.VOID_EMAIL_ZONE, env.VOID_EMAIL_INGRESS, generation, challenge].join('\\n'); + const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(env.VOID_RELAY_SECRET), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']); + const signature = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload))); + const proof = Array.from(signature, byte => byte.toString(16).padStart(2, '0')).join(''); + return Response.json({ accountId: env.VOID_EMAIL_ACCOUNT, zoneId: env.VOID_EMAIL_ZONE, ingressName: env.VOID_EMAIL_INGRESS, generation: Number(generation), challenge, proof }, { headers: { 'Cache-Control': 'no-store' } }); + }, async email(message, env, ctx) { - const recipientDomain = message.to.slice(message.to.lastIndexOf('@') + 1).toLowerCase(); - if (recipientDomain !== env.VOID_EMAIL_DOMAIN) { - message.setReject('Unable to deliver message'); - return; - } + const requestId = crypto.randomUUID(); const { readable, writable } = new FixedLengthStream(message.rawSize); - const relay = fetch(env.VOID_PROXY_ORIGIN + '/email/relay', { + const relay = fetch(env.VOID_EMAIL_GATEWAY_ORIGIN + '/email/ingress', { method: 'POST', headers: { Authorization: 'Bearer ' + env.VOID_RELAY_SECRET, - 'X-Void-Email-Domain': env.VOID_EMAIL_DOMAIN, + 'X-Void-Email-Account': env.VOID_EMAIL_ACCOUNT, + 'X-Void-Email-Zone': env.VOID_EMAIL_ZONE, + 'X-Void-Email-Ingress': env.VOID_EMAIL_INGRESS, + 'X-Void-Email-Request-Id': requestId, 'X-Void-Email-From': message.from, 'X-Void-Email-To': message.to, }, @@ -71,6 +80,9 @@ export const RELAY_SOURCE = `export default { ctx.waitUntil(message.raw.pipeTo(writable)); ctx.waitUntil(relay); const response = await relay; + if (response.status >= 500 || response.status === 408 || response.status === 429) { + throw new Error('Email gateway temporarily unavailable'); + } if (!response.ok) { message.setReject('Unable to deliver message'); } diff --git a/platform/packages/api/src/email/settings.ts b/platform/packages/api/src/email/settings.ts index d2222ebf0..e8b35763a 100644 --- a/platform/packages/api/src/email/settings.ts +++ b/platform/packages/api/src/email/settings.ts @@ -1,18 +1,11 @@ -/** - * Installation-wide email settings (design doc 0078, "Recipient policy" and - * "Administrator-managed domains"). Authoritative in `platform_settings`; - * the recipient policy is also mirrored to ROUTING KV because the proxy - * reads it on every shared-sender send and has no database. - * - * The mirror is a wire contract with `packages/proxy/src/email-policy.ts`: - * key `email-recipient-policy`, value `JSON.stringify(policy)`. An absent or - * unreadable mirror reads as `verified` there — today's behavior — so a - * failed publish can only tighten, never loosen, what the proxy enforces. - */ +/** Installation email policy is authoritative in Postgres. KV is a display hint. */ -import { sql } from 'drizzle-orm'; -import type { Db, DbOrTx, Tx } from '../db.ts'; +import { desc, eq, sql } from 'drizzle-orm'; +import type { Db, DbOrTx } from '../db.ts'; +import { generateId } from '../id.ts'; import { getPlatformSetting, setPlatformSetting } from '../platform-settings.ts'; +import { emailProjectControls } from './admission-schema.ts'; +import { emailCacheOutbox } from './connection-schema.ts'; import { isValidEmailDomain, MAX_DOMAIN_LENGTH, normalizeEmailDomain } from './domain-name.ts'; export type EmailRecipientPolicyMode = 'verified' | 'domains' | 'any'; @@ -148,97 +141,68 @@ export function serializeEmailRecipientPolicyMirror(policy: EmailRecipientPolicy return JSON.stringify({ mode: policy.mode, domains: [...policy.domains] }); } -/** - * The publisher and the repair serialize on one transaction-scoped advisory - * lock, so their read → compare → put sequences never interleave: KV has no - * compare-and-set, and without the lock a repair that read an older policy - * could land its put after a newer publish and reopen a gate the operator - * had just closed. The lock is held across the KV calls on purpose — the - * same total-order trick the email-domain mirror uses with the project row. - */ -function withRecipientPolicyLock(db: Db, fn: (tx: Tx) => Promise): Promise { - return db.transaction(async (tx) => { - await tx.execute( - sql`SELECT pg_advisory_xact_lock(hashtext(${EMAIL_RECIPIENT_POLICY_SETTING}))`, - ); - return fn(tx); - }); -} - -/** - * One KV write per publish — Workers KV refuses a second write to a key - * within a second, so the mirror is never cleared and re-put. The write is - * ordered so the mirror is never LOOSER than the database in any partial - * outcome: - * tightening put the mirror, then commit. A failed put changes nothing; - * a failed commit leaves the proxy stricter than the database - * until the next read republishes. - * widening commit, then put. A failed put leaves the proxy on the old, - * stricter policy — the operator is told — until a retry or - * the next read republishes. - * The mirror therefore never authorizes a domain the database has not - * committed; a list edited both ways goes as a widening, so its one residual - * is the removed domains staying reachable — the policy in force a moment - * earlier — until the republish. Publisher and repair share the advisory lock. - */ +/** Commit the policy and its publication intent under the admission policy lock. */ export async function setEmailRecipientPolicy( db: Db, kv: KVNamespace, policy: EmailRecipientPolicy, ): Promise { - const widened = await withRecipientPolicyLock(db, async (tx) => { - const widening = widensEmailRecipientPolicy(await getEmailRecipientPolicy(tx), policy); - if (!widening) { - try { - await kv.put( - EMAIL_RECIPIENT_POLICY_MIRROR_KEY, - serializeEmailRecipientPolicyMirror(policy), - ); - } catch (err) { - console.error('[email-settings] recipient policy mirror write failed:', err); - throw new Error( - 'the recipient policy routing mirror could not be updated; the saved policy is unchanged and the next read republishes it', - ); - } - } + await db.transaction(async (tx) => { + await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext('email-admission:policy'))`); + const latest = ( + await tx + .select() + .from(emailCacheOutbox) + .where(eq(emailCacheOutbox.resource_kind, 'policy')) + .orderBy(desc(emailCacheOutbox.version)) + .limit(1) + )[0]; + const version = (latest?.version ?? 0) + 1; await setPlatformSetting(tx, EMAIL_RECIPIENT_POLICY_SETTING, { mode: policy.mode, domains: [...policy.domains], }); - return widening; + await tx + .update(emailProjectControls) + .set({ version: sql`${emailProjectControls.version} + 1` }); + await tx.insert(emailCacheOutbox).values({ + id: generateId('eout'), + installation_id: 'installation', + resource_kind: 'policy', + resource_id: EMAIL_RECIPIENT_POLICY_SETTING, + version, + payload: { mode: policy.mode, domains: [...policy.domains] }, + }); }); - if (widened) { - try { - await publishEmailRecipientPolicyMirror(db, kv); - } catch (err) { - console.error('[email-settings] recipient policy mirror write failed:', err); - throw new Error( - 'recipient policy saved; publishing it to routing failed and the previous policy stays in force until a retry or the next read republishes it', - ); - } - } + await repairEmailRecipientPolicyMirror(db, kv); } -/** Under the publish lock: read the committed policy and put the mirror when it differs. */ -async function publishEmailRecipientPolicyMirror(db: Db, kv: KVNamespace): Promise { - await withRecipientPolicyLock(db, async (tx) => { - const [policy, mirrored] = await Promise.all([ - getEmailRecipientPolicy(tx), - kv.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY), - ]); +/** Immutable version keys prevent a delayed publish from replacing newer data. + * The unversioned value is a best-effort display hint and never authorizes sends. */ +export async function repairEmailRecipientPolicyMirror(db: Db, kv: KVNamespace): Promise { + try { + const latest = ( + await db + .select() + .from(emailCacheOutbox) + .where(eq(emailCacheOutbox.resource_kind, 'policy')) + .orderBy(desc(emailCacheOutbox.version)) + .limit(1) + )[0]; + const policy = await getEmailRecipientPolicy(db); const expected = serializeEmailRecipientPolicyMirror(policy); - if (mirrored !== expected) { + if (latest && !latest.published_at) { + await kv.put(`email-policy-version:${latest.version}`, JSON.stringify(latest.payload)); + await db + .update(emailCacheOutbox) + .set({ published_at: new Date().toISOString() }) + .where(eq(emailCacheOutbox.id, latest.id)); + } + if ((await kv.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)) !== expected) { await kv.put(EMAIL_RECIPIENT_POLICY_MIRROR_KEY, expected); } - }); -} - -/** Best-effort read-compare repair of the mirror; never throws. */ -export async function repairEmailRecipientPolicyMirror(db: Db, kv: KVNamespace): Promise { - try { - await publishEmailRecipientPolicyMirror(db, kv); - } catch (err) { - console.error('[email-settings] recipient policy mirror repair failed:', err); + } catch (error) { + console.error('[email-settings] display mirror publication failed:', error); } } diff --git a/platform/packages/api/src/env.ts b/platform/packages/api/src/env.ts index d1742b9a1..b79e0760c 100644 --- a/platform/packages/api/src/env.ts +++ b/platform/packages/api/src/env.ts @@ -34,6 +34,10 @@ export type ApiEnv = Env & { CF_ZONE_ID: string; AI_GATEWAY_ID?: string; JWT_SECRET: string; + EMAIL_GATEWAY_ORIGIN?: string; + EMAIL_SHARED_ACCOUNT_ID?: string; + EMAIL_SHARED_ZONE_ID?: string; + EMAIL_SHARED_INGRESS_NAME?: string; GITHUB_CLIENT_ID: string; GITHUB_CLIENT_SECRET: string; /** diff --git a/platform/packages/api/src/index.ts b/platform/packages/api/src/index.ts index 974b98ea6..20a7bbb5e 100644 --- a/platform/packages/api/src/index.ts +++ b/platform/packages/api/src/index.ts @@ -47,6 +47,15 @@ import { type Db, } from './db.ts'; import { escapeHtml } from './email.ts'; +import { pruneEmailActionHistory } from './email/admission.ts'; +import { + ensureSharedEmailConnection, + reconcilePendingEmailOperations, + runEmailOperation, + flushEmailCacheOutbox, +} from './email/connection-service.ts'; +import emailIngressResolution from './email/ingress-resolution.ts'; +import { repairEmailRecipientPolicyMirror } from './email/settings.ts'; import type { ApiEnv } from './env.ts'; import { ErrorAlertMonitor } from './error-alert-monitor.ts'; import { cancelContainerBuildDos } from './github/cancel-builds.ts'; @@ -75,6 +84,7 @@ import domains from './routes/domains.ts'; import emailConfirm from './routes/email-confirm.ts'; import emailRoutes from './routes/email.ts'; import { githubProjectRoutes, githubRoutes } from './routes/github.ts'; +import internalEmailActions from './routes/internal-email-actions.ts'; import internalEmailDomainCredential from './routes/internal-email.ts'; import internalGitHubWebhook from './routes/internal-github-webhook.ts'; import internalResolveResource from './routes/internal-resolve-resource.ts'; @@ -335,6 +345,8 @@ const app = new Hono() .route('/internal/revalidate', internalRevalidate) .use('/internal/email/*', capabilityMiddleware('email')) .route('/internal/email/domain-credential', internalEmailDomainCredential) + .route('/internal/email/actions', internalEmailActions) + .route('/internal/email', emailIngressResolution) .use('/internal/github-webhook', capabilityMiddleware('managedBuilds')) .route('/internal/github-webhook', internalGitHubWebhook) .route('/internal/resolve-resource', internalResolveResource) @@ -431,6 +443,27 @@ async function scheduled( const db = createDb(env.HYPERDRIVE.connectionString); const capabilities = getPlatformCapabilities(env); + if (capabilities.email) { + await (async () => { + const operationId = await ensureSharedEmailConnection(db, env); + if (operationId) { + await runEmailOperation(db, env, operationId); + } + })().catch((error) => console.error('[scheduled] shared email setup failed:', error)); + await reconcilePendingEmailOperations(db, env).catch((error) => + console.error('[scheduled] email operation reconciliation failed:', error), + ); + await flushEmailCacheOutbox(db, env.ROUTING).catch((error) => + console.error('[scheduled] email display publication failed:', error), + ); + if (controller.cron !== FAST_CRON) { + await pruneEmailActionHistory(db).catch((error) => + console.error('[scheduled] email history cleanup failed:', error), + ); + await repairEmailRecipientPolicyMirror(db, env.ROUTING); + } + } + // Fast tier (every 2 min): only reconcile recently-created pending domains // (within the last 30 min) so a freshly-configured custom domain comes online // quickly without the user polling. The heavier hourly maintenance does NOT diff --git a/platform/packages/api/src/operator/email-routes.ts b/platform/packages/api/src/operator/email-routes.ts index 3b838ce2f..36821f859 100644 --- a/platform/packages/api/src/operator/email-routes.ts +++ b/platform/packages/api/src/operator/email-routes.ts @@ -3,6 +3,9 @@ import { Hono } from 'hono'; import type { Context } from 'hono'; import { capabilityMiddleware } from '../capabilities.ts'; import { getProject, getProjectBySlug, type Db } from '../db.ts'; +import { emailProjectControls } from '../email/admission-schema.ts'; +import { setProjectEmailLimits } from '../email/admission.ts'; +import { emailDomainRoutes, emailZoneConnections } from '../email/connection-schema.ts'; import { MAX_DOMAIN_LENGTH, isValidEmailDomain, @@ -13,7 +16,8 @@ import { getEmailDomainRowByDomain, getEmailDomainStatusForProject, removeEmailDomainForProject, - serializeEmailDomain, + rotateEmailIngressSecretForProject, + serializeEmailRoute, syncEmailDomainForProject, } from '../email/domain-service.ts'; import { @@ -36,7 +40,7 @@ import { type EmailRecipientPolicy, } from '../email/settings.ts'; import type { ApiEnv } from '../env.ts'; -import { emailDomains, projects } from '../schema.ts'; +import { projects } from '../schema.ts'; import { dryRun, OperatorError, preview, readBody, stringField } from './common.ts'; /** @@ -164,11 +168,13 @@ export async function setOperatorEmailLimit( } const db = context.get('db'); const project = await resolveProject(db, selector); - const kv = context.env.ROUTING; - const [previousMonthly, previousBurst] = await Promise.all([ - kv.get(emailMonthlyLimitKey(project.id)), - kv.get(emailBurstLimitKey(project.id)), - ]); + const controls = ( + await db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, project.id)) + .limit(1) + )[0]; const action = 'email.limit.set'; const target = { projectId: project.id, @@ -177,41 +183,14 @@ export async function setOperatorEmailLimit( ...(burst === undefined ? {} : { burst }), }; const previous = { - monthly: parseEmailLimit(previousMonthly) ?? null, - burst: parseEmailLimit(previousBurst) ?? null, + monthly: controls?.monthly_limit ?? 200, + burst: controls?.burst_limit ?? 10, }; if (dryRunRequested) { return preview(action, target, { previous }); } - const applied: Array<'monthly' | 'burst'> = []; - const failed: Array<'monthly' | 'burst'> = []; - for (const [name, key, value] of [ - ['monthly', emailMonthlyLimitKey(project.id), monthly], - ['burst', emailBurstLimitKey(project.id), burst], - ] as const) { - if (value === undefined) { - continue; - } - try { - await kv.put(key, String(value)); - applied.push(name); - } catch (err) { - console.error(`[operator-email] ${name} cap write failed:`, err); - failed.push(name); - } - } - if (failed.length === 0) { - return { action, target, previous }; - } - if (applied.length === 0) { - throw new OperatorError( - 502, - 'No cap was changed: routing storage refused the write.', - 'kv_failed', - { failed }, - ); - } - return { action, target, previous, ok: false as const, partial: true as const, applied, failed }; + await setProjectEmailLimits(db, project.id, { monthly, burst }); + return { action, target, previous }; } emailOperatorRoutes.get('/email/policy', async (context) => @@ -309,6 +288,9 @@ async function requireDomainRow(db: Db, raw: string) { if (!row) { throw new OperatorError(404, 'Email domain not found.'); } + if (!row.project_id) { + throw new OperatorError(404, 'Project not found.'); + } const project = await getProject(db, row.project_id); if (!project) { throw new OperatorError(404, 'Project not found.'); @@ -320,11 +302,14 @@ export async function listOperatorEmailDomains(context: Context, selecto const db = context.get('db'); const project = selector ? await resolveProject(db, selector) : null; const rows = await db - .select() - .from(emailDomains) - .where(project ? eq(emailDomains.project_id, project.id) : undefined) - .orderBy(asc(emailDomains.created_at)); - const projectIds = [...new Set(rows.map((row) => row.project_id))]; + .select({ route: emailDomainRoutes, connection: emailZoneConnections }) + .from(emailDomainRoutes) + .innerJoin(emailZoneConnections, eq(emailDomainRoutes.connection_id, emailZoneConnections.id)) + .where(project ? eq(emailDomainRoutes.project_id, project.id) : undefined) + .orderBy(asc(emailDomainRoutes.created_at)); + const projectIds = [ + ...new Set(rows.map(({ route }) => route.project_id).filter((id): id is string => id !== null)), + ]; const owners = projectIds.length === 0 ? [] @@ -334,9 +319,12 @@ export async function listOperatorEmailDomains(context: Context, selecto .where(inArray(projects.id, projectIds)); const slugs = new Map(owners.map((owner) => [owner.id, owner.slug])); return { - domains: rows.map((row) => ({ - ...serializeEmailDomain(row), - project: { id: row.project_id, slug: slugs.get(row.project_id) ?? null }, + domains: rows.map(({ route, connection }) => ({ + ...serializeEmailRoute(route, connection), + project: { + id: route.project_id, + slug: route.project_id ? (slugs.get(route.project_id) ?? null) : null, + }, })), }; } @@ -372,11 +360,13 @@ export async function addOperatorEmailDomain( mx = 'unknown'; } return preview(action, target, { - existing: existing ? { status: existing.status, managed_by: existing.managed_by } : null, - plan: existing ? 'rerun' : 'setup', + existing: existing + ? { status: existing.inbound_status, managed_by: existing.managed_by } + : null, + plan: existing ? 'sync' : 'setup', mx, - effect: existing?.mode - ? `Re-runs setup for ${domain} on ${project.slug} in its stored ${existing.mode} mode; the credential is replaced, rules and the relay stay.` + effect: existing + ? `The existing assignment for ${domain} belongs to ${project.slug}; use sync to reconcile it.` : mx === 'subdomain' ? `${domain} already receives mail; setup will refuse it — name a subdomain such as mail.${domain} instead.` : credentialKind === 'platform' @@ -415,11 +405,10 @@ export async function syncOperatorEmailDomain( const target = { domain, projectId: project.id, slug: project.slug }; if (dryRunRequested) { return preview(action, target, { - status: row.status, + status: row.inbound_status, managed_by: row.managed_by, - relay_worker_name: row.relay_worker_name, - effect: - 'Redeploys the relay worker at the current version, rotates its secret and re-ensures the zone catch-all.', + connection_id: row.connection_id, + effect: 'Reconciles the shared zone ingress and this exact mail-domain assignment.', }); } return operatorResult( @@ -440,12 +429,12 @@ export async function removeOperatorEmailDomain( const target = { domain, projectId: project.id, slug: project.slug, force }; if (dryRunRequested) { return preview(action, target, { - status: row.status, + status: row.inbound_status, managed_by: row.managed_by, - relay_worker_name: row.relay_worker_name, + connection_id: row.connection_id, effect: force - ? 'Deletes the row even if the Cloudflare cleanup fails; anything left behind is reported for manual removal.' - : 'Resets the zone catch-all, deletes the relay worker, then deletes the row; a failed destructive step keeps the row for retry.', + ? 'Disables the assignment and records any unresolved provider cleanup for manual recovery.' + : 'Disables this assignment; shared ingress remains while sibling domains use it.', }); } return operatorResult( @@ -455,6 +444,27 @@ export async function removeOperatorEmailDomain( ); } +export async function rotateOperatorEmailIngressSecret( + context: Context, + rawDomain: string, + dryRunRequested = false, +) { + const { domain, row, project } = await requireDomainRow(context.get('db'), rawDomain); + const action = 'email.domain.rotate-secret', + target = { domain, projectId: project.id, slug: project.slug, connectionId: row.connection_id }; + if (dryRunRequested) { + return preview(action, target, { + effect: + 'Stages a new ingress secret and promotes it only after the deployed Worker proves it received the value.', + }); + } + return operatorResult( + await rotateEmailIngressSecretForProject(context, project, domain, 'admin'), + action, + target, + ); +} + emailOperatorRoutes.get('/email/domains', async (context) => context.json(await listOperatorEmailDomains(context, context.req.query('project') || undefined)), ); @@ -481,6 +491,12 @@ emailOperatorRoutes.post('/email/domains/:domain/sync', async (context) => { await syncOperatorEmailDomain(context, context.req.param('domain'), dryRun(body)), ); }); +emailOperatorRoutes.post('/email/domains/:domain/rotate-secret', async (context) => { + const body = await readBody(context); + return context.json( + await rotateOperatorEmailIngressSecret(context, context.req.param('domain'), dryRun(body)), + ); +}); emailOperatorRoutes.post('/email/domains/:domain/remove', async (context) => { const body = await readBody(context); if (body.force !== undefined && typeof body.force !== 'boolean') { diff --git a/platform/packages/api/src/provisioning/cleanup.ts b/platform/packages/api/src/provisioning/cleanup.ts index cb47eb4fc..4eabb3200 100644 --- a/platform/packages/api/src/provisioning/cleanup.ts +++ b/platform/packages/api/src/provisioning/cleanup.ts @@ -16,6 +16,9 @@ import { getProjectResources, terminateBuildsForProject, } from '../db.ts'; +import { drainProjectEmailAdmissions } from '../email/admission.ts'; +import { emailDomainRoutes } from '../email/connection-schema.ts'; +import { requestEmailDomainRemove, runEmailOperation } from '../email/connection-service.ts'; import { refreshOauthGrantSerialized, revokeOauthGrantSerialized, @@ -411,8 +414,8 @@ async function lockAndMarkDeleting( } export class ProjectOperationInProgressError extends Error { - constructor() { - super('project operation in progress'); + constructor(message = 'project operation in progress') { + super(message); this.name = 'ProjectOperationInProgressError'; } } @@ -507,15 +510,24 @@ export async function teardownProject( // their tokens are dead and their containers stopped before we touch CF. await cancelContainerBuildDos(context.env, cancelledOnLock, 'project deleted'); + const emailDrain = await drainProjectEmailAdmissions(context.get('db'), projectId); + if (emailDrain.inFlight > 0) { + throw new ProjectOperationInProgressError( + `${emailDrain.inFlight} email provider attempt(s) have unresolved outcomes`, + ); + } + await cleanupCriticalResources(context, projectId, project); - // Fail-closed, and BEFORE anything below is destroyed: these KV keys are - // what still authorizes the project's non-expiring proxy token to send - // mail and its relay secrets to submit inbound mail, and the project row - // is the only handle a retry has for them. - await revokeProjectEmailSendAuthorization(context.get('db'), context.env.ROUTING, projectId); - // Best-effort, and AFTER the mirrors above are gone: the relay worker and - // zone catch-all live in the CUSTOMER's account, so a stranded relay is - // already denied by the proxy. + // Legacy KV mirrors are display/routing hints. Database admission and + // exact route state are the authority, so a KV outage cannot block teardown. + await revokeProjectEmailSendAuthorization( + context.get('db'), + context.env.ROUTING, + projectId, + ).catch((error) => { + console.warn('[email] legacy mirror cleanup deferred', projectId, error); + }); + // Customer-side cleanup is durable and may continue after project deletion. await cleanupProjectEmailDomains(context, projectId); const { warnings: bestEffortWarnings, cleanedCfIds } = await cleanupBestEffortResources( context, @@ -699,6 +711,38 @@ async function cleanupProjectEmailDomains( projectId: string, ): Promise { const db = context.get('db'); + // New connection-backed assignments are independent of project cascade. + // Disable authority first; provider cleanup remains in the operation ledger + // even if project teardown later removes its owning row. + const assignments = await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.project_id, projectId)); + for (const assignment of assignments) { + if (assignment.desired_state === 'removed') { + continue; + } + // The durable intent must exist before the project can cascade away. + // A provider failure after that point is safe to reconcile later. + const opId = await requestEmailDomainRemove( + db, + context.env, + assignment.id, + { kind: 'system' }, + `teardown:${projectId}:${assignment.id}`, + ); + try { + await runEmailOperation(db, context.env, opId); + } catch (error) { + // The disabled assignment and connection survive project deletion; the + // scheduled reconciler or operator can inspect and resume the cleanup. + console.error( + '[email] project teardown left pending connection cleanup', + assignment.id, + error, + ); + } + } let rows: Array< Pick< EmailDomain, diff --git a/platform/packages/api/src/provisioning/provision.ts b/platform/packages/api/src/provisioning/provision.ts index 4edb3e7f8..848448b77 100644 --- a/platform/packages/api/src/provisioning/provision.ts +++ b/platform/packages/api/src/provisioning/provision.ts @@ -48,6 +48,8 @@ export async function provisionBindings( platform: { /** Project slug. Framework reads it as `__VOID_PROJECT_SLUG`. */ projectSlug: string; + /** Immutable deployment identity for signed inbound email receipts. */ + deploymentId?: string; /** * Platform mail domain for this environment (`EMAIL_SENDER_DOMAIN` on * the api worker — `mail.void.cloud` in production, @@ -177,6 +179,16 @@ export async function provisionBindings( // Emitted after the user's vars in the upload array, so it also stops // being shadowable — see `reserved-bindings.ts`. bindings.push({ type: 'plain_text', name: '__VOID_PROJECT_SLUG', text: platform.projectSlug }); + if (manifest.emailProtocolVersion === 1) { + if (!platform.deploymentId) { + throw new Error('email delivery requires a deployment identity'); + } + bindings.push({ + type: 'plain_text', + name: '__VOID_EMAIL_DEPLOYMENT_ID', + text: platform.deploymentId, + }); + } if (platform.emailSenderDomain) { bindings.push({ type: 'plain_text', diff --git a/platform/packages/api/src/reserved-bindings.ts b/platform/packages/api/src/reserved-bindings.ts index 8b4afc243..10a5ac409 100644 --- a/platform/packages/api/src/reserved-bindings.ts +++ b/platform/packages/api/src/reserved-bindings.ts @@ -34,6 +34,7 @@ export const RESERVED_BINDING_NAMES: ReadonlySet = new Set([ '__VOID_USER_ID', '__VOID_PROJECT_SLUG', '__VOID_EMAIL_DOMAIN', + '__VOID_EMAIL_DEPLOYMENT_ID', 'USAGE_EVENTS_QUEUE', 'SEND_EMAIL', 'ASSETS', diff --git a/platform/packages/api/src/routes/deploy.ts b/platform/packages/api/src/routes/deploy.ts index c33a0a373..49f4140b9 100644 --- a/platform/packages/api/src/routes/deploy.ts +++ b/platform/packages/api/src/routes/deploy.ts @@ -3848,6 +3848,7 @@ async function handleManifestOnlyDeploy(context: Context): Promise() return context.json({ error: 'forbidden' }, 403); } - const month = monthBucket(); - const [sent, recv, suspended, limitOverride] = await Promise.all([ - context.env.ROUTING.get(`email-sent:${projectId}:${month}`), - context.env.ROUTING.get(`email-recv:${projectId}:${month}`), - context.env.ROUTING.get(`email-suspended:${projectId}`), - context.env.ROUTING.get(`email-limit:${projectId}`), - ]); - - const limit = parseLimit(limitOverride) ?? 200; - const sentCount = parseCounter(sent); - const recvCount = parseCounter(recv); - - return context.json({ - month, - sent: sentCount, - received: recvCount, - limit, - remaining: Math.max(0, limit - sentCount), - suspended: suspended !== null, - }); + return context.json(await getProjectEmailUsage(context.get('db'), projectId)); }) .get('/:id/email/logs', async (context) => { @@ -135,15 +117,11 @@ const app = new Hono() return context.json({ error: 'forbidden' }, 403); } - // Log entries currently live only in worker `console.log` output — - // surfaced via the existing tail/observability pipeline. This endpoint - // returns an empty list with a marker so consumers know AE-backed logs - // aren't wired yet. - return context.json({ - logs: [], - pending: true, - note: 'Persistent log storage lands when Analytics Engine queries are wired.', - }); + const limit = Number(context.req.query('limit') ?? 50); + if (!Number.isInteger(limit) || limit < 1 || limit > 100) { + return context.json({ error: 'limit must be between 1 and 100' }, 400); + } + return context.json(await getProjectEmailLogs(context.get('db'), projectId, limit)); }) // ------------------------------------------------------------------------- @@ -553,88 +531,22 @@ const app = new Hono() return context.json({ error: 'destination not found' }, 404); } - // Tighten the KV mirror BEFORE anything destructive runs. The proxy - // enforces every send against `email-allowlist:`, and this row - // is what a retry would re-derive that mirror from — delete the row first - // and a failed KV write strands the revoked address in the allowlist with - // nothing left to repair it from, so a revoked recipient keeps receiving - // mail. (Same inversion as unretain-before-cleanup: never destroy the - // record the retry needs.) The sync must EXCLUDE this row explicitly: - // it is still `verified` in Postgres at this point, so a plain re-sync - // would write the address straight back. `status` is the snapshot's: a - // `pending` row is not in the mirror and has nothing to tighten, and the - // re-derive after the delete below covers a row that was promoted in - // between. - if (dest.status === 'verified') { + // Admission observes this committed revocation regardless of KV publication. + await deleteEmailDestination(context.get('db'), dest.id); + if ( + dest.cf_destination_id && + (await countProjectsUsingDestination(context.get('db'), dest.cf_destination_id)) === 0 + ) { try { - await syncProjectAllowlistKv(context.get('db'), context.env.ROUTING, projectId, { - excludeDestinationId: dest.id, - }); - } catch (err) { - console.error('[email] allowlist tighten failed; keeping destination row:', err); - return context.json({ error: 'failed to update send allowlist; try again' }, 503); - } - } - - // Best-effort CF cleanup. Only delete from CF if no other project - // references the same destination tag — destinations are account-wide. - // - // The count and the upstream delete are not one step, and nothing - // serializes them against a sibling project's POST. Two concurrent - // revokes of a shared tag can both read `refs === 2`, both decline the - // upstream delete, and both drop their row (an orphan). The mirror image: - // a POST for the same address on another project whose already-exists - // recovery listed this tag BEFORE the delete below lands, and whose row - // INSERT lands AFTER this count, commits a row pointing at a tag CF no - // longer has. The listing never re-checks a `verified` row against CF and - // a repeat POST returns the existing row without calling CF, so that row - // stays dangling until its owner runs `void email disallow` then `allow`: - // the DELETE's upstream call 404s (caught below), the row goes, and the - // re-add is a fresh create that mails a new link. Re-validating the tag - // from the POST side after its insert only narrows this to "insert and - // re-check both land between this count and this delete"; closing it - // needs both sides to compensate, and the same count-then-delete shape is - // in the admin revoke and in teardown, where the rows die later in the - // cascade and the window is far wider — so it belongs in one change - // across all three (design doc 0067), not here. - if (dest.cf_destination_id) { - const refs = await countProjectsUsingDestination(context.get('db'), dest.cf_destination_id); - if (refs <= 1) { - try { - await deleteDestination( - context.env.CF_ACCOUNT_ID, - context.env.CF_API_TOKEN, - dest.cf_destination_id, - ); - } catch (err) { - // Non-fatal — proceed with the row delete. There is NO sweep for the - // orphan this leaves, so this log line is the only trace an operator - // gets. A 404 here is also the recovery path for a dangling row (see - // above): the tag is already gone, and the row must go with it. - console.error('[email] CF deleteDestination failed:', err); - } + await deleteDestination( + context.env.CF_ACCOUNT_ID, + context.env.CF_API_TOKEN, + dest.cf_destination_id, + ); + } catch (error) { + console.error('[email] destination provider cleanup failed:', error); } } - - await deleteEmailDestination(context.get('db'), dest.id); - - // Re-derive the mirror now that the row is gone. The tighten above works - // from a snapshot, and the snapshot can go stale before this delete: a - // confirm click (or the listing's CF refresh) can flip a `pending` row to - // `verified` and write it into the mirror after the snapshot was taken, - // and a click on a SIBLING row re-derives the whole project from rows - // that still include this one. Either way the delete then drops the row - // and the mirror keeps granting an address nothing backs. Deriving after - // the delete cannot include the row. Best-effort on purpose: the row is - // already gone, so a 503 here would not be retryable, and the residual - // is bounded — Postgres and KV are written separately and KV has no - // compare-and-swap, so a concurrent writer that derived its mirror while - // the row still existed can still land its write after this one, and - // the grant then lasts until this project's next listing re-derives the - // mirror (`projectAllowlistKvDiffers`) or any other mirror write for the - // project. That is a revoke delayed, not consent bypassed: the recipient - // clicked to allow this project. Serializing the two routes is the - // project-level lock class from design doc 0067, deliberately not here. await syncProjectAllowlistKvBestEffort(context.get('db'), context.env.ROUTING, projectId); return context.json({ ok: true }); }) @@ -687,10 +599,18 @@ const app = new Hono() const rows = await context .get('db') .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)) - .orderBy(asc(emailDomains.created_at)); - return context.json(rows.map((row) => serializeEmailDomain(row))); + .from(emailDomainRoutes) + .innerJoin(emailZoneConnections, eq(emailZoneConnections.id, emailDomainRoutes.connection_id)) + .where( + and( + eq(emailDomainRoutes.project_id, projectId), + ne(emailDomainRoutes.desired_state, 'removed'), + ), + ) + .orderBy(asc(emailDomainRoutes.created_at)); + return context.json( + rows.map((row) => serializeEmailRoute(row.email_domain_routes, row.email_zone_connections)), + ); }) .post('/:id/email/domains', async (context) => { @@ -707,38 +627,40 @@ const app = new Hono() } catch { return context.json({ error: 'invalid domain' }, 400); } - // Parsed before EVERY guard so every rejection can revoke a posted - // grant: the CLI mints a fresh user-wide OAuth grant per attempt and - // drops its only copy on any error response, so any reject without a - // revoke strands a live broad grant in the customer's account per - // retry. Revocation asks for no ownership: for wrangler's public client - // the token itself is the only credential the RFC 7009 endpoint wants, - // so revoking what was posted grants no capability the caller did not - // already hold. - const postedRefreshToken = - typeof body.refreshToken === 'string' && body.refreshToken.length > 0 - ? body.refreshToken - : undefined; + if (body.refreshToken !== undefined) { + return context.json( + { error: 'OAuth grants are not supported; use a scoped Cloudflare API token' }, + 400, + ); + } const db = context.get('db'); const project = await getProject(db, projectId); if (!project) { - await revokeRejectedGrant(context, postedRefreshToken); return context.json({ error: 'project not found' }, 404); } if (project.user_id !== context.get('user').id) { - await revokeRejectedGrant(context, postedRefreshToken); return context.json({ error: 'forbidden' }, 403); } return addEmailDomainForProject(context, project, { domain: typeof body.domain === 'string' ? body.domain : '', mode: body.mode, - refreshToken: postedRefreshToken, apiToken: typeof body.apiToken === 'string' ? body.apiToken : undefined, attemptId: body.attemptId, managedBy: 'owner', }); }) + .get('/:id/email/operations/:operationId', async (context) => { + const project = await getProject(context.get('db'), context.req.param('id')); + if (!project) { + return context.json({ error: 'project not found' }, 404); + } + if (project.user_id !== context.get('user').id) { + return context.json({ error: 'forbidden' }, 403); + } + return getEmailOperationForProject(context, project, context.req.param('operationId')); + }) + .get('/:id/email/domains/:domain', async (context) => { const projectId = context.req.param('id'); const project = await getProject(context.get('db'), projectId); @@ -751,6 +673,41 @@ const app = new Hono() return getEmailDomainStatusForProject(context, project, context.req.param('domain')); }) + .post('/:id/email/domains/:domain/rotate-secret', async (context) => { + const project = await getProject(context.get('db'), context.req.param('id')); + if (!project) { + return context.json({ error: 'project not found' }, 404); + } + if (project.user_id !== context.get('user').id) { + return context.json({ error: 'forbidden' }, 403); + } + let attemptId: string | undefined; + if (context.req.header('content-type')?.includes('application/json')) { + let body: { attemptId?: unknown }; + try { + body = await context.req.json(); + } catch { + return context.json({ error: 'invalid JSON' }, 400); + } + if ( + body.attemptId !== undefined && + (typeof body.attemptId !== 'string' || + body.attemptId.length < 1 || + body.attemptId.length > 128) + ) { + return context.json({ error: 'invalid attemptId' }, 400); + } + attemptId = body.attemptId as string | undefined; + } + return rotateEmailIngressSecretForProject( + context, + project, + context.req.param('domain'), + 'owner', + attemptId, + ); + }) + .post('/:id/email/domains/:domain/sync', async (context) => { const projectId = context.req.param('id'); const db = context.get('db'); @@ -783,11 +740,6 @@ const app = new Hono() ); }); -function monthBucket(): string { - const d = new Date(); - return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`; -} - function parseCounter(raw: string | null): number { if (!raw) { return 0; @@ -796,14 +748,6 @@ function parseCounter(raw: string | null): number { return Number.isFinite(n) && n >= 0 ? n : 0; } -function parseLimit(raw: string | null): number | undefined { - if (!raw) { - return undefined; - } - const n = parseInt(raw, 10); - return Number.isFinite(n) && n > 0 ? n : undefined; -} - /** * Loose RFC 5322 sanity check. Defers real validation to CF Email * Routing — we just want to keep obviously-bad input out of the rate diff --git a/platform/packages/api/src/routes/internal-email-actions.ts b/platform/packages/api/src/routes/internal-email-actions.ts new file mode 100644 index 000000000..c21703518 --- /dev/null +++ b/platform/packages/api/src/routes/internal-email-actions.ts @@ -0,0 +1,268 @@ +import { Hono } from 'hono'; +import { hmacVerifyState } from '../auth/hmac.ts'; +import { + admitEmailAction, + claimRelayedEmailReceipt, + completeRelayedEmailReceipt, + EmailAdmissionError, + getEmailAction, + recordEmailReceipt, + transitionEmailRecipients, +} from '../email/admission.ts'; +import type { EmailAdmissionInput } from '../email/admission.ts'; +import type { ApiEnv } from '../env.ts'; + +const app = new Hono(); + +app.use('*', async (context, next) => { + const signature = context.req.header('x-void-internal'); + if (!signature) { + return context.json({ error: 'invalid internal auth' }, 403); + } + if (Number(context.req.header('content-length')) > 32_768) { + return context.json({ error: 'action request too large' }, 413); + } + const reader = context.req.raw.body?.getReader(); + if (!reader) { + return context.json({ error: 'invalid body' }, 400); + } + const chunks: Array = []; + let size = 0; + let timedOut = false; + const deadline = setTimeout(() => { + timedOut = true; + void reader.cancel().catch(() => {}); + }, 5_000); + try { + for (;;) { + const { done, value } = await reader.read(); + if (timedOut) { + return context.json({ error: 'action request timed out' }, 408); + } + if (done) { + break; + } + size += value.byteLength; + if (size > 32_768) { + await reader.cancel(); + return context.json({ error: 'action request too large' }, 413); + } + chunks.push(value); + } + } catch (error) { + if (timedOut) { + return context.json({ error: 'action request timed out' }, 408); + } + throw error; + } finally { + clearTimeout(deadline); + reader.releaseLock(); + } + const bytes = new Uint8Array(size); + let offset = 0; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.byteLength; + } + let raw: string; + try { + raw = new TextDecoder('utf-8', { fatal: true }).decode(bytes); + } catch { + return context.json({ error: 'invalid body' }, 400); + } + if (!(await hmacVerifyState(raw, signature, context.env.JWT_SECRET))) { + return context.json({ error: 'invalid internal auth' }, 403); + } + let body: unknown; + try { + body = JSON.parse(raw); + } catch { + return context.json({ error: 'invalid body' }, 400); + } + context.set('emailActionBody' as never, body as never); + await next(); +}); + +function status(error: EmailAdmissionError): 400 | 404 | 409 { + return error.code === 'NOT_FOUND' + ? 404 + : error.code === 'CONFLICT' || error.code === 'INVALID_STATE' + ? 409 + : 400; +} + +app.post('/admit', async (context) => { + const body = context.get('emailActionBody' as never) as unknown as EmailAdmissionInput; + if ( + !body || + typeof body !== 'object' || + typeof body.projectId !== 'string' || + typeof body.key !== 'string' || + typeof body.digest !== 'string' || + typeof body.from !== 'string' || + !Array.isArray(body.recipients) || + !body.recipients.every((r) => typeof r === 'string') || + !['direct', 'forward', 'reply'].includes(body.kind) || + !['binding', 'send_raw', 'native_forward', 'native_reply'].includes(body.transport) + ) { + return context.json({ error: 'invalid admission request' }, 400); + } + try { + return context.json( + await admitEmailAction(context.get('db'), { + ...body, + sharedSenderDomain: context.env.EMAIL_SENDER_DOMAIN ?? '', + }), + ); + } catch (error) { + if (error instanceof EmailAdmissionError) { + return context.json({ error: error.message, code: error.code }, status(error)); + } + throw error; + } +}); + +app.post('/receipts', async (context) => { + const body = context.get('emailActionBody' as never) as unknown as { + receiptId?: unknown; + projectId?: unknown; + status?: unknown; + }; + if ( + typeof body?.receiptId !== 'string' || + typeof body.projectId !== 'string' || + typeof body.status !== 'string' + ) { + return context.json({ error: 'invalid receipt' }, 400); + } + try { + await recordEmailReceipt(context.get('db'), { + receiptId: body.receiptId, + projectId: body.projectId, + status: body.status, + }); + return context.json({ ok: true }); + } catch (error) { + if (error instanceof EmailAdmissionError) { + return context.json({ error: error.message, code: error.code }, status(error)); + } + throw error; + } +}); + +app.post('/receipts/claim', async (context) => { + const body = context.get('emailActionBody' as never) as unknown as Record; + if ( + typeof body?.receiptId !== 'string' || + typeof body.projectId !== 'string' || + typeof body.payloadDigest !== 'string' + ) { + return context.json({ error: 'invalid relay claim' }, 400); + } + try { + return context.json( + await claimRelayedEmailReceipt(context.get('db'), { + receiptId: body.receiptId, + projectId: body.projectId, + payloadDigest: body.payloadDigest, + }), + ); + } catch (error) { + if (error instanceof EmailAdmissionError) { + return context.json({ error: error.message, code: error.code }, status(error)); + } + throw error; + } +}); + +app.post('/receipts/complete', async (context) => { + const body = context.get('emailActionBody' as never) as unknown as Record; + if ( + typeof body?.receiptId !== 'string' || + typeof body.projectId !== 'string' || + typeof body.payloadDigest !== 'string' || + typeof body.reject !== 'boolean' + ) { + return context.json({ error: 'invalid relay completion' }, 400); + } + try { + await completeRelayedEmailReceipt(context.get('db'), { + receiptId: body.receiptId, + projectId: body.projectId, + payloadDigest: body.payloadDigest, + reject: body.reject, + }); + return context.json({ ok: true }); + } catch (error) { + if (error instanceof EmailAdmissionError) { + return context.json({ error: error.message, code: error.code }, status(error)); + } + throw error; + } +}); + +app.post('/:id/start', async (context) => { + const body = context.get('emailActionBody' as never) as unknown as { recipients?: unknown }; + if (!Array.isArray(body?.recipients) || !body.recipients.every((r) => typeof r === 'string')) { + return context.json({ error: 'invalid recipients' }, 400); + } + try { + return context.json({ + recipients: await transitionEmailRecipients( + context.get('db'), + context.req.param('id'), + body.recipients, + 'attempt_started', + ), + }); + } catch (error) { + if (error instanceof EmailAdmissionError) { + return context.json({ error: error.message, code: error.code }, status(error)); + } + throw error; + } +}); + +app.post('/:id/finish', async (context) => { + const body = context.get('emailActionBody' as never) as unknown as { + recipients?: unknown; + state?: unknown; + providerReference?: unknown; + errorCode?: unknown; + }; + if ( + !Array.isArray(body?.recipients) || + !body.recipients.every((r) => typeof r === 'string') || + !['provider_accepted', 'failed', 'outcome_unknown', 'cancelled'].includes(String(body.state)) || + (body.providerReference !== undefined && typeof body.providerReference !== 'string') || + (body.errorCode !== undefined && typeof body.errorCode !== 'string') + ) { + return context.json({ error: 'invalid outcome' }, 400); + } + try { + return context.json({ + recipients: await transitionEmailRecipients( + context.get('db'), + context.req.param('id'), + body.recipients, + body.state as 'provider_accepted' | 'failed' | 'outcome_unknown' | 'cancelled', + { + providerReference: body.providerReference as string | undefined, + errorCode: body.errorCode as string | undefined, + }, + ), + }); + } catch (error) { + if (error instanceof EmailAdmissionError) { + return context.json({ error: error.message, code: error.code }, status(error)); + } + throw error; + } +}); + +app.post('/:id/status', async (context) => { + const action = await getEmailAction(context.get('db'), context.req.param('id')); + return action ? context.json(action) : context.json({ error: 'email action not found' }, 404); +}); + +export default app; diff --git a/platform/packages/api/src/routes/internal-email.ts b/platform/packages/api/src/routes/internal-email.ts index 36f385687..6a26b896b 100644 --- a/platform/packages/api/src/routes/internal-email.ts +++ b/platform/packages/api/src/routes/internal-email.ts @@ -1,146 +1,98 @@ -import { and, eq } from 'drizzle-orm'; +/** Trusted proxy credential broker. Every request rechecks the committed + * connection/domain authority; ROUTING KV is only a display hint. */ +import { eq } from 'drizzle-orm'; import { Hono } from 'hono'; import { hmacVerifyState } from '../auth/hmac.ts'; -import { leaseEmailDomainCredential, withEmailDomainRowLock } from '../email/credential-lease.ts'; -import { - decryptEmailDomainRelaySecret, - hashEmailRelaySecret, - writeEmailDomainMirror, -} from '../email/domains.ts'; -import type { EmailDomainMirror } from '../email/domains.ts'; +import { emailProjectControls } from '../email/admission-schema.ts'; +import { credentialFor, resolveEmailDomain } from '../email/connection-service.ts'; +import { normalizeEmailDomain } from '../email/domain-name.ts'; +import { EmailInternalBodyError, readBoundedInternalJson } from '../email/internal-body.ts'; import type { ApiEnv } from '../env.ts'; -import { emailDomains } from '../schema.ts'; +import { projects, users } from '../schema.ts'; const app = new Hono(); - -/** - * The mirror key spelling is owned by `src/email/domains.ts` (the writer — - * frozen for this phase). The lease reads the same key the domain - * mutations write; a rename there must move this spelling with it. - */ -function emailDomainMirrorKey(domain: string): string { - return `email-domain:${domain}`; -} - -/** - * Credential lease endpoint — called by the proxy via service binding when - * a send's from-domain is a registered custom domain (design doc 0078, - * contract 4). Authenticated with the platform-internal pattern the proxy - * already uses for the revalidation bridge: an HMAC under JWT_SECRET in - * the `x-void-internal` header. Here the signed value is the DOMAIN — the - * one value both sides of this call provably hold (the proxy's caller - * pinning happens on the proxy side, against the mirror, before it calls). - * - * POST /internal/email/domain-credential { "domain": "acme.com" } - * → { kind: 'api_token', token } | { kind: 'oauth_grant', accessToken } - * - * The response body IS a customer credential: it is never logged, never - * interpolated into an error, and never appears in any other payload. - */ +app.use('*', async (context, next) => { + if (!context.req.header('x-void-internal')) { + return context.json({ error: 'forbidden' }, 403); + } + await next(); +}); app.post('/', async (context) => { - let body: { domain?: unknown }; + let body: { domain?: unknown; projectId?: unknown }; try { - body = await context.req.json<{ domain?: unknown }>(); - } catch { - return context.json({ error: 'invalid body' }, 400); - } - // Verified verbatim — the HMAC signs the exact string the proxy sent. - const domain = body.domain; - if (typeof domain !== 'string' || domain.length === 0 || domain.length > 253) { - return context.json({ error: 'invalid domain' }, 400); + body = (await readBoundedInternalJson(context.req.raw, 4096)) as typeof body; + } catch (error) { + return error instanceof EmailInternalBodyError + ? context.json({ error: error.message }, error.status) + : context.json({ error: 'invalid body' }, 400); } - - const token = context.req.header('x-void-internal'); - if (!token) { - return context.json({ error: 'missing internal auth' }, 401); + if (!body || typeof body !== 'object' || Array.isArray(body)) { + return context.json({ error: 'invalid body' }, 400); } - if (!(await hmacVerifyState(domain, token, context.env.JWT_SECRET))) { - return context.json({ error: 'invalid internal auth' }, 403); + const domain = body.domain, + projectId = body.projectId; + if ( + typeof domain !== 'string' || + domain.length === 0 || + domain.length > 253 || + typeof projectId !== 'string' || + projectId.length === 0 || + projectId.length > 128 + ) { + return context.json({ error: 'invalid domain or project' }, 400); } - - // Resolve the row through the same mirror the proxy gated on: the mirror - // names exactly one project per domain, so a domain registered by two - // projects leases the credential of the project the proxy saw. - const mirrorRaw = await context.env.ROUTING.get(emailDomainMirrorKey(domain)); - if (!mirrorRaw) { - return context.json({ error: 'unknown email domain' }, 404); + const normalized = normalizeEmailDomain(domain); + const signature = context.req.header('x-void-internal'); + if ( + !signature || + !(await hmacVerifyState( + `email-lease-v1\n${projectId}\n${normalized}`, + signature, + context.env.JWT_SECRET, + )) + ) { + return context.json({ error: 'forbidden' }, 403); } - let mirror: EmailDomainMirror; - try { - mirror = JSON.parse(mirrorRaw) as EmailDomainMirror; - } catch { - return context.json({ error: 'corrupt email domain mirror' }, 500); + const db = context.get('db'); + const resolved = await resolveEmailDomain(db, normalized); + if ( + !resolved || + resolved.route.addressing !== 'custom' || + resolved.route.project_id !== projectId || + resolved.route.desired_state !== 'active' + ) { + return context.json({ error: 'email domain unavailable' }, 404); } - if (typeof mirror.projectId !== 'string' || mirror.projectId.length === 0) { - return context.json({ error: 'corrupt email domain mirror' }, 500); + if ( + resolved.route.outbound_status !== 'ready' && + resolved.route.outbound_status !== 'verified_only' + ) { + return context.json({ error: 'outbound email unavailable' }, 409); } - - const db = context.get('db'); - const rows = await db - .select() - .from(emailDomains) - .where(and(eq(emailDomains.project_id, mirror.projectId), eq(emailDomains.domain, domain))) - .limit(1); - const row = rows[0]; - if (!row) { - return context.json({ error: 'unknown email domain' }, 404); + if (resolved.connection.management_status !== 'healthy') { + return context.json({ error: 'email management credential unavailable' }, 503); } - if (row.status !== 'active') { - return context.json({ error: `email domain is ${row.status}, not active` }, 409); + const project = ( + await db + .select({ + status: projects.status, + ownerSuspended: users.suspended_reason, + emailSuspended: emailProjectControls.suspended_at, + }) + .from(projects) + .innerJoin(users, eq(projects.user_id, users.id)) + .leftJoin(emailProjectControls, eq(emailProjectControls.project_id, projects.id)) + .where(eq(projects.id, resolved.route.project_id)) + .limit(1) + )[0]; + if (!project || project.status !== 'active' || project.ownerSuspended || project.emailSuspended) { + return context.json({ error: 'project email unavailable' }, 403); } - - const outcome = await leaseEmailDomainCredential(db, context.env, row); - if (!outcome.ok) { - if (outcome.status === 'token_revoked') { - // The row flip was persisted inside the refresh transaction; re-mirror - // so the proxy stops accepting this domain's relay and sends. The write - // is fenced through the row lock: the row is re-read FOR UPDATE and the - // mirror is published from the LOCKED row inside the same transaction, - // and only while it still holds the credential that was revoked — a - // replace that committed in between published its own active mirror - // under the same lock, and this write must not overwrite it with the - // stale status and relay hash. The row is authoritative, so a KV - // failure here is logged, not fatal — the next mutation (or status - // probe) rewrites the mirror. - try { - await withEmailDomainRowLock(db, row.id, async (tx) => { - const locked = await tx - .select() - .from(emailDomains) - .where(eq(emailDomains.id, row.id)) - .for('update') - .limit(1); - const current = locked[0]; - if ( - !current || - current.status !== 'token_revoked' || - current.credential_kind !== row.credential_kind || - current.token_ciphertext !== row.token_ciphertext - ) { - return; - } - const relaySecret = await decryptEmailDomainRelaySecret( - context.env, - current.project_id, - current.domain, - current, - ); - await writeEmailDomainMirror( - context.env.ROUTING, - current, - await hashEmailRelaySecret(relaySecret), - ); - }); - } catch (err) { - console.error('[email] domain mirror update after revocation failed:', err); - } - return context.json({ error: 'email domain credential revoked' }, 403); - } - console.error('[email] credential lease failed:', outcome.error); - return context.json({ error: 'credential lease failed' }, 502); + try { + const token = await credentialFor(context.env, db, resolved.connection); + return context.json({ kind: 'api_token', token, accountId: resolved.connection.account_id }); + } catch { + return context.json({ error: 'email connection credential unavailable' }, 503); } - - return context.json(outcome.lease); }); - export default app; diff --git a/platform/packages/api/src/schema.ts b/platform/packages/api/src/schema.ts index 1c8939e36..37c837deb 100644 --- a/platform/packages/api/src/schema.ts +++ b/platform/packages/api/src/schema.ts @@ -1222,3 +1222,7 @@ export const invitations = pgTable( index('idx_invitations_status').on(table.status), ], ); + +export * from './email/connection-schema.ts'; + +export * from './email/admission-schema.ts'; diff --git a/platform/packages/api/test/integration/admin-email.test.ts b/platform/packages/api/test/integration/admin-email.test.ts index 1e38439fa..088772f1e 100644 --- a/platform/packages/api/test/integration/admin-email.test.ts +++ b/platform/packages/api/test/integration/admin-email.test.ts @@ -11,6 +11,9 @@ import { } from 'vite-plus/test'; import { createEmailDestination, getEmailDestinationsByProjectId } from '../../src/db.ts'; import type { Db } from '../../src/db.ts'; +import { emailProjectControls } from '../../src/email/admission-schema.ts'; +import { setProjectEmailLimits, setProjectEmailSuspended } from '../../src/email/admission.ts'; +import { emailDomainRoutes, emailZoneConnections } from '../../src/email/connection-schema.ts'; import { refreshOauthGrantSerialized } from '../../src/email/credential-lease.ts'; import { encryptEmailDomainRelaySecret, @@ -21,6 +24,7 @@ import { } from '../../src/email/domains.ts'; import { app } from '../../src/index.ts'; import { emailDomains, operatorEvents, platformSettings } from '../../src/schema.ts'; +import { stubCustomerCf, callsByTag } from './email-domain-cf-stub.ts'; import { setupEnv, teardownEnv, @@ -29,6 +33,7 @@ import { createTestProject, type TestEnv, } from './helpers.ts'; +import { CF_ACCOUNT_ID } from './helpers.ts'; import { setTestDb } from './setup.ts'; let env: TestEnv; @@ -84,6 +89,7 @@ afterAll(async () => { beforeEach(async () => { await clearTables(env.db); + Object.assign(env, { EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test' }); }); afterEach(() => { @@ -239,7 +245,14 @@ describe('admin write guard (cross-origin)', () => { ); expect(res.status).toBe(302); - expect(await env.ROUTING.get(`email-suspended:${projectId}`)).not.toBeNull(); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.suspended_at, + ).not.toBeNull(); }); test('leaves reads alone', async () => { @@ -263,7 +276,7 @@ describe('GET /admin/email/:projectId', () => { expect(res.status).toBe(200); const html = await res.text(); expect(html).toContain(slug); - expect(html).toContain('7 / 200'); + expect(html).toContain('0 / 200'); expect(html).toContain('(default)'); expect(html).toContain('Suspend email'); expect(html).toContain('No destinations yet.'); @@ -271,8 +284,8 @@ describe('GET /admin/email/:projectId', () => { test('labels an override as such and shows the suspended state', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); - await env.ROUTING.put(`email-limit:${projectId}`, '1000'); - await env.ROUTING.put(`email-suspended:${projectId}`, new Date().toISOString()); + await setProjectEmailLimits(env.db, projectId, { monthly: 1000 }); + await setProjectEmailSuspended(env.db, projectId, true); const html = await (await get(`/admin/email/${projectId}`, adminJwt)).text(); @@ -299,17 +312,31 @@ describe('POST /admin/email/:projectId/suspend', () => { expect(res.status).toBe(302); expect(res.headers.get('Location')).toBe(`/admin/email/${projectId}`); - expect(await env.ROUTING.get(`email-suspended:${projectId}`)).not.toBeNull(); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.suspended_at, + ).not.toBeNull(); }); test('unsuspending clears it', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); - await env.ROUTING.put(`email-suspended:${projectId}`, new Date().toISOString()); + await setProjectEmailSuspended(env.db, projectId, true); const res = await post(`/admin/email/${projectId}/suspend`, adminJwt, { state: 'active' }); expect(res.status).toBe(302); - expect(await env.ROUTING.get(`email-suspended:${projectId}`)).toBeNull(); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.suspended_at, + ).toBeNull(); }); test('suspending twice is idempotent, not a toggle', async () => { @@ -318,7 +345,14 @@ describe('POST /admin/email/:projectId/suspend', () => { await post(`/admin/email/${projectId}/suspend`, adminJwt, { state: 'suspended' }); await post(`/admin/email/${projectId}/suspend`, adminJwt, { state: 'suspended' }); - expect(await env.ROUTING.get(`email-suspended:${projectId}`)).not.toBeNull(); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.suspended_at, + ).not.toBeNull(); }); test('rejects a state that is neither terminal value', async () => { @@ -331,43 +365,6 @@ describe('POST /admin/email/:projectId/suspend', () => { }); }); -describe('POST /admin/email/:projectId/reset-counter', () => { - test('refuses without the typed slug and leaves the counter intact', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const key = `email-sent:${projectId}:${monthBucket()}`; - await env.ROUTING.put(key, '42'); - - const res = await post(`/admin/email/${projectId}/reset-counter`, adminJwt, {}); - - expect(res.status).toBe(400); - expect(await env.ROUTING.get(key)).toBe('42'); - }); - - test('refuses when the typed slug is wrong', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const key = `email-sent:${projectId}:${monthBucket()}`; - await env.ROUTING.put(key, '42'); - - const res = await post(`/admin/email/${projectId}/reset-counter`, adminJwt, { - confirm: 'not-the-slug', - }); - - expect(res.status).toBe(400); - expect(await env.ROUTING.get(key)).toBe('42'); - }); - - test('resets the current month once confirmed', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - const key = `email-sent:${projectId}:${monthBucket()}`; - await env.ROUTING.put(key, '42'); - - const res = await post(`/admin/email/${projectId}/reset-counter`, adminJwt, { confirm: slug }); - - expect(res.status).toBe(302); - expect(await env.ROUTING.get(key)).toBeNull(); - }); -}); - describe('POST /admin/email/:projectId/limit', () => { test('sets a monthly override', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); @@ -375,17 +372,31 @@ describe('POST /admin/email/:projectId/limit', () => { const res = await post(`/admin/email/${projectId}/limit`, adminJwt, { limit: '5000' }); expect(res.status).toBe(302); - expect(await env.ROUTING.get(`email-limit:${projectId}`)).toBe('5000'); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.monthly_limit, + ).toBe(5000); }); test('a blank value drops the override back to the platform default', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); - await env.ROUTING.put(`email-limit:${projectId}`, '5000'); + await setProjectEmailLimits(env.db, projectId, { monthly: 5000 }); const res = await post(`/admin/email/${projectId}/limit`, adminJwt, { limit: ' ' }); expect(res.status).toBe(302); - expect(await env.ROUTING.get(`email-limit:${projectId}`)).toBeNull(); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.monthly_limit, + ).toBe(200); }); test('rejects a value the proxy would not honour', async () => { @@ -402,11 +413,25 @@ describe('POST /admin/email/:projectId/limit', () => { const { adminJwt, projectId } = await seedAdminAndProject(); await post(`/admin/email/${projectId}/burst-limit`, adminJwt, { burstLimit: '60' }); - expect(await env.ROUTING.get(`email-burst-limit:${projectId}`)).toBe('60'); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.burst_limit, + ).toBe(60); expect(await env.ROUTING.get(`email-limit:${projectId}`)).toBeNull(); await post(`/admin/email/${projectId}/burst-limit`, adminJwt, { burstLimit: '' }); - expect(await env.ROUTING.get(`email-burst-limit:${projectId}`)).toBeNull(); + expect( + ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)) + )[0]?.burst_limit, + ).toBe(10); }); }); @@ -729,769 +754,42 @@ function breakMirrorDelete(domain: string): void { }) as typeof env.ROUTING.delete); } -describe('GET /admin/email/:projectId — custom domains', () => { - test('renders domain rows with relay and token metadata, and never secret material', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const row = await seedEmailDomain(projectId, 'acme-admin.com'); - - const res = await get(`/admin/email/${projectId}`, adminJwt); - - expect(res.status).toBe(200); - const html = await res.text(); - expect(html).toContain('Custom domains (1)'); - expect(html).toContain('acme-admin.com'); - expect(html).toContain('apex'); - expect(html).toContain('void-email-relay'); - expect(html).toContain('tok_dummy'); - expect(html).toContain(`/admin/email/${projectId}/domains/acme-admin.com/revoke`); - // Neither ciphertext triple nor any plaintext credential/relay secret - // ever renders — the page carries metadata only. - expect(html).not.toContain(CUSTOMER_TOKEN); - expect(html).not.toContain(RELAY_SECRET); - expect(html).not.toContain(row.token_ciphertext); - expect(html).not.toContain(row.relay_ciphertext); - }); - - test('shows the empty state when the project has no custom domains', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - - const html = await (await get(`/admin/email/${projectId}`, adminJwt)).text(); - - expect(html).toContain('Custom domains (0)'); - expect(html).toContain('No custom domains.'); - }); -}); - -describe('POST /admin/email/:projectId/domains/:domain/revoke', () => { - test('clears the mirror first, then deletes CF state best-effort and the row', async () => { +describe('admin email domain controls', () => { + test('registers, rotates and removes an exact route without exposing credential material', async () => { const { adminJwt, projectId, slug } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-revoke.com'); - const cfCalls = recordCustomerCfCalls(); - - // Ordering pin, same contract as the destination tighten above: the - // mirror key is deleted BEFORE any customer-side CF call. The row - // outliving the clear is now structural — the clear and the row delete - // are the first and last statements of ONE serialized transaction, so - // a request dying mid-cleanup rolls the row back for the operator's - // retry to re-run from. (A mid-transaction row read would deadlock - // the single-connection test database, so the pin is on the CF - // ordering instead.) - let cfCallsAtMirrorClear: number | undefined; - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - await originalDelete(k as never); - if (k === 'email-domain:acme-revoke.com') { - cfCallsAtMirrorClear = cfCalls.length; - } - }) as typeof env.ROUTING.delete); - - const res = await post(`/admin/email/${projectId}/domains/acme-revoke.com/revoke`, adminJwt, { - confirm: slug, + const stub = stubCustomerCf({ + zones: { + 'example.com': { id: 'zone-platform', name: 'example.com', accountId: CF_ACCOUNT_ID }, + }, }); - - expect(res.status).toBe(302); - expect(res.headers.get('Location')).toBe(`/admin/email/${projectId}`); - expect(cfCallsAtMirrorClear).toBe(0); - // Contract 7 remove shape: the catch-all ownership read, the - // conditional reset (the read shows it still naming our relay), then - // the relay DELETE — the enabled rule never outlives its worker. - expect(cfCalls.map((call) => `${call.method} ${call.url}`)).toEqual([ - 'GET https://api.cloudflare.com/client/v4/zones/zone_customer_1/email/routing/rules/catch_all', - 'PUT https://api.cloudflare.com/client/v4/zones/zone_customer_1/email/routing/rules/catch_all', - 'DELETE https://api.cloudflare.com/client/v4/accounts/acct_customer_1/workers/scripts/void-email-relay', - ]); - expect(cfCalls[1]?.body).toEqual({ - matchers: [{ type: 'all' }], - actions: [{ type: 'drop' }], - enabled: false, + const add = await post(`/admin/email/${projectId}/domains/add`, adminJwt, { + domain: 'mail.example.com', }); - expect(await env.ROUTING.get('email-domain:acme-revoke.com')).toBeNull(); - expect(await domainRow(projectId, 'acme-revoke.com')).toBeUndefined(); - }); - - test('revokes the OAuth grant during a full domain revoke for an oauth_grant row', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-revoke-oauth.com', { credentialKind: 'oauth_grant' }); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-revoke-oauth.com/revoke`, - adminJwt, - { confirm: slug }, - ); - - expect(res.status).toBe(302); - // Same remove contract as the owner DELETE: the serialized grant - // refresh FIRST (its rotation persists through the row while it - // lives), the customer-side cleanup, then the grant revoke LAST — - // against the ROTATED chain head. Without the revokeGrant dep the - // row's deletion would orphan the live grant with no platform handle. - expect(cfCalls.map((call) => `${call.method} ${call.url}`)).toEqual([ - 'POST https://dash.cloudflare.com/oauth2/token', - 'GET https://api.cloudflare.com/client/v4/zones/zone_customer_1/email/routing/rules/catch_all', - 'PUT https://api.cloudflare.com/client/v4/zones/zone_customer_1/email/routing/rules/catch_all', - 'DELETE https://api.cloudflare.com/client/v4/accounts/acct_customer_1/workers/scripts/void-email-relay', - 'POST https://dash.cloudflare.com/oauth2/revoke', - ]); - const revokeBody = cfCalls.find((call) => call.tag === 'oauthRevoke')!.body; - const form = new URLSearchParams(String(revokeBody)); - expect(form.get('token_type_hint')).toBe('refresh_token'); - expect(form.get('token')).toBe('cf-rotated-refresh-dummy-1'); - expect(await domainRow(projectId, 'acme-revoke-oauth.com')).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-revoke-oauth.com')).toBeNull(); - }); - - test('re-reads the row under the lock — a credential replace committed mid-removal is not orphaned', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - const row = await seedEmailDomain(projectId, 'acme-midswap.com'); - const cfCalls = recordCustomerCfCalls(); - - // Pause the removal's serialized section BEFORE it opens (no locks - // held), then land a committed credential replace: the entry snapshot - // says api_token, the LOCKED re-read says oauth_grant — the cleanup - // must follow the locked row, or the fresh grant's only handle goes - // with the row delete. - const gate = pauseFirstTransaction(env.db); - setTestDb(gate.wrappedDb); - try { - const resPromise = post( - `/admin/email/${projectId}/domains/acme-midswap.com/revoke`, - adminJwt, - { confirm: slug }, - ); - const winner = await Promise.race([ - gate.reached.then(() => 'paused' as const), - resPromise.then(() => 'settled' as const), - ]); - if (winner === 'paused') { - const swapped = await encryptEmailDomainToken( - env, - projectId, - 'acme-midswap.com', - GRANT_REFRESH_TOKEN, - ); - await env.db - .update(emailDomains) - .set({ - credential_kind: 'oauth_grant', - token_ciphertext: swapped.ciphertext, - token_iv: swapped.iv, - token_key_version: swapped.keyVersion, - token_id: null, - token_expires_on: null, - }) - .where(eq(emailDomains.id, row.id)); - gate.release(); - } - const res = await resPromise; - expect(res.status).toBe(302); - // The cleanup followed the LOCKED row: the grant was refreshed (its - // rotation persisted while the row lived), then revoked LAST with - // the rotated chain head — not silently dropped by an api_token - // cleanup built on the stale entry snapshot. - expect(cfCalls.map((call) => `${call.method} ${call.url}`)).toEqual([ - 'POST https://dash.cloudflare.com/oauth2/token', - 'GET https://api.cloudflare.com/client/v4/zones/zone_customer_1/email/routing/rules/catch_all', - 'PUT https://api.cloudflare.com/client/v4/zones/zone_customer_1/email/routing/rules/catch_all', - 'DELETE https://api.cloudflare.com/client/v4/accounts/acct_customer_1/workers/scripts/void-email-relay', - 'POST https://dash.cloudflare.com/oauth2/revoke', - ]); - expect(String(cfCalls.find((call) => call.tag === 'oauthRevoke')!.body)).toContain( - 'cf-rotated-refresh-dummy-1', - ); - expect(await domainRow(projectId, 'acme-midswap.com')).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-midswap.com')).toBeNull(); - } finally { - setTestDb(env.db); - } - }); - - test('refuses without the typed slug and leaves everything intact', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-noconfirm.com'); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-noconfirm.com/revoke`, + expect(add.status).toBe(302); + const html = await (await get(`/admin/email/${projectId}`, adminJwt)).text(); + expect(html).toContain('mail.example.com'); + expect(html).toContain('rotate secret'); + expect(html).not.toContain(env.CF_API_TOKEN); + expect(await env.db.select().from(emailZoneConnections)).toHaveLength(1); + const rotate = await post( + `/admin/email/${projectId}/domains/mail.example.com/rotate-secret`, adminJwt, - {}, ); - - expect(res.status).toBe(400); - expect(await domainRow(projectId, 'acme-noconfirm.com')).toBeDefined(); - expect(await env.ROUTING.get('email-domain:acme-noconfirm.com')).not.toBeNull(); - expect(cfCalls).toEqual([]); - }); - - test('refuses when the typed slug is wrong', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-wrongslug.com'); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-wrongslug.com/revoke`, + expect(rotate.status).toBe(302); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + const unconfirmed = await post( + `/admin/email/${projectId}/domains/mail.example.com/revoke`, adminJwt, - { confirm: 'not-the-slug' }, + { confirm: 'wrong' }, ); - - expect(res.status).toBe(400); - expect(await domainRow(projectId, 'acme-wrongslug.com')).toBeDefined(); - expect(await env.ROUTING.get('email-domain:acme-wrongslug.com')).not.toBeNull(); - expect(cfCalls).toEqual([]); - }); - - test('404s for a domain row that belongs to another project', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - const sibling = await createTestProject(env.db, (await createTestUser(env.db)).id); - await seedEmailDomain(sibling.id, 'acme-elsewhere.com'); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-elsewhere.com/revoke`, + expect(unconfirmed.status).toBe(400); + expect((await env.db.select().from(emailDomainRoutes))[0]?.desired_state).toBe('active'); + const removed = await post( + `/admin/email/${projectId}/domains/mail.example.com/revoke`, adminJwt, { confirm: slug }, ); - - expect(res.status).toBe(404); - expect(await domainRow(sibling.id, 'acme-elsewhere.com')).toBeDefined(); - expect(await env.ROUTING.get('email-domain:acme-elsewhere.com')).not.toBeNull(); - expect(cfCalls).toEqual([]); - }); - - test('keeps the row and runs nothing destructive when the mirror clear fails', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-kvfail.com'); - breakMirrorDelete('acme-kvfail.com'); - const cfCalls = recordCustomerCfCalls(); - - const res = await post(`/admin/email/${projectId}/domains/acme-kvfail.com/revoke`, adminJwt, { - confirm: slug, - }); - - // Tighten-before-delete: the failed clear is the ONLY thing that ran, so - // the operator can just click again — dropping the row first and - // swallowing the KV error would strand the domain working in the proxy - // with no row left to revoke. - expect(res.status).toBe(503); - expect(await domainRow(projectId, 'acme-kvfail.com')).toBeDefined(); - expect(await env.ROUTING.get('email-domain:acme-kvfail.com')).not.toBeNull(); - expect(cfCalls).toEqual([]); - }); - - test('still clears the mirror and row when the CF cleanup fails', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-cffail.com'); - failCustomerCfCalls(); - - const res = await post(`/admin/email/${projectId}/domains/acme-cffail.com/revoke`, adminJwt, { - confirm: slug, - }); - - // Best-effort CF cleanup: a stranded relay is inert without the mirror - // entry, so the revoke completes and the log line carries the trace. - expect(res.status).toBe(302); - expect(await domainRow(projectId, 'acme-cffail.com')).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-cffail.com')).toBeNull(); - }); - - test('revokes a row whose relay never deployed without any CF call', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-failed.com', { status: 'failed', deployed: false }); - const cfCalls = recordCustomerCfCalls(); - - const res = await post(`/admin/email/${projectId}/domains/acme-failed.com/revoke`, adminJwt, { - confirm: slug, - }); - - expect(res.status).toBe(302); - expect(cfCalls).toEqual([]); - expect(await domainRow(projectId, 'acme-failed.com')).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-failed.com')).toBeNull(); - }); - - test('still revokes when the stored credential can no longer be decrypted', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - const row = await seedEmailDomain(projectId, 'acme-badkey.com'); - // Re-encrypt under a different domain's AAD: the revoke's decrypt fails - // the GCM tag check, as a rotated-away key version would. The row must - // still be revocable — only the CF cleanup is skipped. - const foreign = await encryptEmailDomainToken(env, projectId, 'other.com', CUSTOMER_TOKEN); - await env.db - .update(emailDomains) - .set({ - token_ciphertext: foreign.ciphertext, - token_iv: foreign.iv, - token_key_version: foreign.keyVersion, - }) - .where(eq(emailDomains.id, row.id)); - const cfCalls = recordCustomerCfCalls(); - - const res = await post(`/admin/email/${projectId}/domains/acme-badkey.com/revoke`, adminJwt, { - confirm: slug, - }); - - expect(res.status).toBe(302); - expect(cfCalls).toEqual([]); - expect(await domainRow(projectId, 'acme-badkey.com')).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-badkey.com')).toBeNull(); - }); -}); - -describe('POST /admin/email/:projectId/domains/:domain/revoke-grant', () => { - test('revokes the grant at Cloudflare and flips the row to token_revoked', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-grant.com', { credentialKind: 'oauth_grant' }); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-grant.com/revoke-grant`, - adminJwt, - ); - - expect(res.status).toBe(302); - expect(res.headers.get('Location')).toBe(`/admin/email/${projectId}`); - // Exactly one RFC 7009 revocation against dash.cloudflare.com, and no - // relay-engine cleanup — the row (and its relay) stay in place. - expect(cfCalls.filter((call) => call.tag === 'oauthRevoke')).toHaveLength(1); - expect(cfCalls).toHaveLength(1); - const row = await domainRow(projectId, 'acme-grant.com'); - expect(row?.status).toBe('token_revoked'); - // The mirror flipped FIRST (same inversion as the removal route): the - // proxy's relay auth checks its `active` status, so inbound stops here - // rather than whenever the next status GET happens to repair drift. - const mirror = JSON.parse((await env.ROUTING.get('email-domain:acme-grant.com'))!) as { - status: string; - relayWorkerName: string | null; - }; - expect(mirror.status).toBe('token_revoked'); - expect(mirror.relayWorkerName).toBe('void-email-relay'); - }); - - test('keeps the row active when the grant revoke fails — the mirror already flipped', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-revokefail.com', { credentialKind: 'oauth_grant' }); - // The revoke request fails (the helper throws on a non-2xx); nothing - // else is called on this route. - vi.spyOn(globalThis, 'fetch').mockImplementation(async () => { - return Response.json({ error: 'boom' }, { status: 500 }); - }); - - const res = await post( - `/admin/email/${projectId}/domains/acme-revokefail.com/revoke-grant`, - adminJwt, - ); - - // The grant's state is unknown, so the row keeps its status and the - // operator retries; the mirror already flipped (mirror-first), and the - // next status GET repairs it while the row stays active. - expect(res.status).toBe(502); - expect((await domainRow(projectId, 'acme-revokefail.com'))?.status).toBe('active'); - const mirror = JSON.parse((await env.ROUTING.get('email-domain:acme-revokefail.com'))!) as { - status: string; - }; - expect(mirror.status).toBe('token_revoked'); - }); - - test('revokes the chain head live at revoke time when a lease rotation lands mid-request', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const row = await seedEmailDomain(projectId, 'acme-grant-race.com', { - credentialKind: 'oauth_grant', - }); - const cfCalls = recordCustomerCfCalls(); - // A lease rotation landing before the revoke's serialized section: - // the originally stored token is consumed by it, so a revoke captured - // beforehand would submit a dead token — CF answers 200 either way, - // and the rotated head would live on with no handle. The seam pauses - // the route's transaction BEFORE it opens (no locks held), so the - // rotation's own lock cannot deadlock the single-connection database. - const gate = pauseFirstTransaction(env.db); - setTestDb(gate.wrappedDb); - try { - const resPromise = post( - `/admin/email/${projectId}/domains/acme-grant-race.com/revoke-grant`, - adminJwt, - ); - await gate.reached; - await refreshOauthGrantSerialized(env.db, env, row.id); - gate.release(); - const res = await resPromise; - expect(res.status).toBe(302); - } finally { - setTestDb(env.db); - } - - const revocations = cfCalls.filter((call) => call.tag === 'oauthRevoke'); - expect(revocations).toHaveLength(1); - // The revoke went through the row lock, so it submitted the ROTATED - // head — not the stored-and-consumed original. - expect(String(revocations[0]!.body)).toContain('cf-rotated-refresh-dummy-1'); - expect(String(revocations[0]!.body)).not.toContain(GRANT_REFRESH_TOKEN); - expect((await domainRow(projectId, 'acme-grant-race.com'))?.status).toBe('token_revoked'); - }); - - test('a credential replace committed mid-revoke is revoked and marked — mirror and row stay paired', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const row = await seedEmailDomain(projectId, 'acme-grant-swap.com', { - credentialKind: 'oauth_grant', - }); - const cfCalls = recordCustomerCfCalls(); - // Land a committed credential replace + an `active` mirror republish - // while the revoke's serialized section is paused BEFORE it opens. - // Everything the route does must follow the LOCKED row: revoke the - // replacement grant and flip it, leaving mirror and row both - // token_revoked — never an `active` mirror over a revoked row, and - // never a revoked row over a live grant. - const gate = pauseFirstTransaction(env.db); - setTestDb(gate.wrappedDb); - try { - const resPromise = post( - `/admin/email/${projectId}/domains/acme-grant-swap.com/revoke-grant`, - adminJwt, - ); - await gate.reached; - const swapped = await encryptEmailDomainToken( - env, - projectId, - 'acme-grant-swap.com', - 'cf-grant-refresh-dummy-2', - ); - await env.db - .update(emailDomains) - .set({ - token_ciphertext: swapped.ciphertext, - token_iv: swapped.iv, - token_key_version: swapped.keyVersion, - }) - .where(eq(emailDomains.id, row.id)); - await writeEmailDomainMirror( - env.ROUTING, - (await domainRow(projectId, 'acme-grant-swap.com'))!, - await hashEmailRelaySecret(RELAY_SECRET), - ); - gate.release(); - const res = await resPromise; - expect(res.status).toBe(302); - } finally { - setTestDb(env.db); - } - - // The revoke submitted the REPLACEMENT grant (the row's live head at - // lock time) — not the stale snapshot's original… - const revocations = cfCalls.filter((call) => call.tag === 'oauthRevoke'); - expect(revocations).toHaveLength(1); - // Compare the parsed form field exactly — the replacement value carries - // the original as a prefix, so substring checks cannot tell them apart. - const revokedToken = new URLSearchParams(String(revocations[0]!.body)).get('token'); - expect(revokedToken).toBe('cf-grant-refresh-dummy-2'); - expect(revokedToken).not.toBe(GRANT_REFRESH_TOKEN); - // …and mirror and row agree. - expect((await domainRow(projectId, 'acme-grant-swap.com'))?.status).toBe('token_revoked'); - const mirror = JSON.parse((await env.ROUTING.get('email-domain:acme-grant-swap.com'))!) as { - status: string; - }; - expect(mirror.status).toBe('token_revoked'); - }); - - test('fails the grant revoke without touching CF when the mirror write fails', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-mirrorfail.com', { credentialKind: 'oauth_grant' }); - const originalPut = env.ROUTING.put.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( - key: string, - value: string, - options?: unknown, - ) => { - if (key === 'email-domain:acme-mirrorfail.com') { - throw new Error('forced mirror KV failure for test'); - } - return originalPut(key, value, options as never); - }) as typeof env.ROUTING.put); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-mirrorfail.com/revoke-grant`, - adminJwt, - ); - - // Mirror-first: nothing else ran — the grant is still live, the row is - // still active, and the operator can just click again. - expect(res.status).toBe(503); - expect(cfCalls).toEqual([]); - expect((await domainRow(projectId, 'acme-mirrorfail.com'))?.status).toBe('active'); - const mirror = JSON.parse((await env.ROUTING.get('email-domain:acme-mirrorfail.com'))!) as { - status: string; - }; - expect(mirror.status).toBe('active'); - }); - - test('refuses for an api_token row — the customer revokes those themselves', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - await seedEmailDomain(projectId, 'acme-token.com'); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-token.com/revoke-grant`, - adminJwt, - ); - - expect(res.status).toBe(400); - expect(await res.text()).toContain('dash.cloudflare.com'); - expect(cfCalls).toEqual([]); - expect((await domainRow(projectId, 'acme-token.com'))?.status).toBe('active'); - }); - - test('404s for a domain row that belongs to another project', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const sibling = await createTestProject(env.db, (await createTestUser(env.db)).id); - await seedEmailDomain(sibling.id, 'acme-grant-elsewhere.com', { - credentialKind: 'oauth_grant', - }); - const cfCalls = recordCustomerCfCalls(); - - const res = await post( - `/admin/email/${projectId}/domains/acme-grant-elsewhere.com/revoke-grant`, - adminJwt, - ); - - expect(res.status).toBe(404); - expect(cfCalls).toEqual([]); - expect((await domainRow(sibling.id, 'acme-grant-elsewhere.com'))?.status).toBe('active'); - }); -}); - -describe('admin email settings page', () => { - test('renders the recipient policy and domain management forms with the defaults selected', async () => { - const { adminJwt } = await seedAdminAndProject(); - // A stale, looser mirror is republished from the database on this read. - await env.ROUTING.put('email-recipient-policy', JSON.stringify({ mode: 'any', domains: [] })); - const res = await get('/admin/email', adminJwt); - expect(res.status).toBe(200); - expect(await env.ROUTING.get('email-recipient-policy')).toBe( - JSON.stringify({ mode: 'verified', domains: [] }), - ); - const html = await res.text(); - expect(html).toContain('Recipient policy'); - expect(html).toContain('Domain management'); - expect(html).toMatch(/name="mode" value="verified" checked/); - expect(html).toMatch(/name="domains" value="self-serve" checked/); - expect(html).toContain('UNVERIFIED_DESTINATION'); - expect(html).toContain('own mail domain'); - }); - - test('saves the recipient policy, mirrors it, audits it, and re-renders it selected', async () => { - const { adminJwt } = await seedAdminAndProject(); - const res = await post('/admin/email/policy', adminJwt, { - mode: 'domains', - domains: 'Corp.Example\nexample.net', - }); - expect(res.status).toBe(302); - expect(res.headers.get('Location')).toBe('/admin/email'); - expect(res.headers.get('X-Void-Audit-Id')).toBeTruthy(); - expect(await env.ROUTING.get('email-recipient-policy')).toBe( - JSON.stringify({ mode: 'domains', domains: ['corp.example', 'example.net'] }), - ); - const events = await env.db.select().from(operatorEvents); - expect(events).toHaveLength(1); - expect(events[0]).toMatchObject({ action: 'email/policy', status: 'success' }); - - const html = await (await get('/admin/email', adminJwt)).text(); - expect(html).toMatch(/name="mode" value="domains" checked/); - expect(html).toContain('corp.example'); - }); - - test('renders a 400 for an invalid policy and stores nothing', async () => { - const { adminJwt } = await seedAdminAndProject(); - await env.ROUTING.delete('email-recipient-policy'); - const res = await post('/admin/email/policy', adminJwt, { mode: 'domains', domains: '' }); - expect(res.status).toBe(400); - expect(await env.db.select().from(platformSettings)).toHaveLength(0); - expect(await env.ROUTING.get('email-recipient-policy')).toBeNull(); - }); - - test('is unavailable, reads and writes alike, when the platform does not enable email', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const disabled = { - ...env, - PLATFORM_CAPABILITIES: JSON.stringify({ - ai: true, - customDomains: true, - email: false, - githubActions: true, - githubOAuth: true, - googleOAuth: false, - managedBuilds: false, - sandbox: false, - }), - }; - const page = await app.fetch( - new Request('http://localhost/admin/email', { - headers: { Cookie: `admin_token=${adminJwt}` }, - }), - disabled, - ); - expect(page.status).toBe(501); - const write = await app.fetch( - new Request('http://localhost/admin/email/settings', { - method: 'POST', - headers: { - Cookie: `admin_token=${adminJwt}`, - 'Content-Type': 'application/x-www-form-urlencoded', - Origin: 'http://localhost', - }, - body: new URLSearchParams({ domains: 'admin' }).toString(), - }), - disabled, - ); - expect(write.status).toBe(501); - expect(await env.db.select().from(platformSettings)).toHaveLength(0); - const project = await app.fetch( - new Request(`http://localhost/admin/email/${projectId}`, { - headers: { Cookie: `admin_token=${adminJwt}` }, - }), - disabled, - ); - expect(project.status).toBe(501); - }); - - test('saves the domain management mode', async () => { - const { adminJwt } = await seedAdminAndProject(); - const res = await post('/admin/email/settings', adminJwt, { domains: 'admin' }); - expect(res.status).toBe(302); - const html = await (await get('/admin/email', adminJwt)).text(); - expect(html).toMatch(/name="domains" value="admin" checked/); - const bad = await post('/admin/email/settings', adminJwt, { domains: 'nobody' }); - expect(bad.status).toBe(400); - }); - - test('the project page still resolves under the index route', async () => { - const { adminJwt, projectId, slug } = await seedAdminAndProject(); - const res = await get(`/admin/email/${projectId}`, adminJwt); - expect(res.status).toBe(200); - expect(await res.text()).toContain(slug); - }); -}); - -describe('admin add domain form', () => { - test('registers an administrator-managed row on the platform credential and audits it', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const cfCalls: Array = []; - vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => { - const url = typeof input === 'string' ? input : (input as Request).url; - const method = init?.method ?? 'GET'; - cfCalls.push(`${method} ${url}`); - if (url.startsWith('https://cloudflare-dns.com/')) { - return Response.json({ Answer: [] }); - } - if (url.includes('/zones?')) { - return Response.json({ - success: true, - errors: [], - result: [{ id: 'zone_p', name: 'example.com', account: { id: env.CF_ACCOUNT_ID } }], - }); - } - if (/\/workers\/scripts\/[^/]+$/.test(url) && method === 'GET') { - return new Response('not found', { status: 404 }); - } - if (url.endsWith('/email/routing/rules/catch_all') && method === 'GET') { - return Response.json({ - success: true, - errors: [], - result: { enabled: false, matchers: [{ type: 'all' }], actions: [{ type: 'drop' }] }, - }); - } - return Response.json({ success: true, errors: [], result: {} }); - }); - - const res = await post(`/admin/email/${projectId}/domains/add`, adminJwt, { - domain: 'example.com', - token: '', - }); - expect(res.status).toBe(302); - expect(res.headers.get('Location')).toBe(`/admin/email/${projectId}`); - const row = (await domainRow(projectId, 'example.com'))!; - expect(row).toMatchObject({ - credential_kind: 'platform', - managed_by: 'admin', - status: 'active', - }); - expect(row.token_ciphertext).toBeNull(); - expect(cfCalls.some((call) => call.includes('/user/tokens/verify'))).toBe(false); - const events = await env.db.select().from(operatorEvents); - expect(events).toHaveLength(1); - expect(events[0]).toMatchObject({ action: 'email/domains', status: 'success' }); - expect(JSON.parse(events[0]!.target)).toEqual({ domain: 'example.com', project: projectId }); - - const html = await (await get(`/admin/email/${projectId}`, adminJwt)).text(); - expect(html).toContain('admin (platform credential)'); - }); - - test('renders a failed setup as a failed audited mutation while keeping the row', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => { - const url = typeof input === 'string' ? input : (input as Request).url; - if (url.includes('/zones?')) { - return Response.json( - { success: false, errors: [{ code: 10000, message: 'zone lookup unavailable' }] }, - { status: 502 }, - ); - } - throw new Error(`Unexpected fetch: ${url}`); - }); - - const res = await post(`/admin/email/${projectId}/domains/add`, adminJwt, { - domain: 'failed.example', - token: '', - }); - expect(res.status).toBe(502); - const html = await res.text(); - expect(html).toContain('Adding failed.example did not finish'); - expect(html).toContain('zone lookup unavailable'); - expect(await domainRow(projectId, 'failed.example')).toMatchObject({ status: 'failed' }); - const events = await env.db.select().from(operatorEvents); - expect(events).toHaveLength(1); - expect(events[0]).toMatchObject({ action: 'email/domains', status: 'failed' }); - }); - - test('refuses to take over a row the project owner registered', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const row = await seedEmailDomain(projectId, 'owned.test', { credentialKind: 'api_token' }); - const cfCalls = recordCustomerCfCalls(); - const res = await post(`/admin/email/${projectId}/domains/add`, adminJwt, { - domain: 'owned.test', - token: '', - }); - expect(res.status).toBe(409); - expect(await res.text()).toContain('registered by its project owner'); - const after = (await domainRow(projectId, 'owned.test'))!; - expect(after.managed_by).toBe('owner'); - expect(after.credential_kind).toBe('api_token'); - expect(after.token_ciphertext).toBe(row.token_ciphertext); - expect(cfCalls).toEqual([]); - }); - - test('renders a 400 for a blank domain and records the failed attempt', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const res = await post(`/admin/email/${projectId}/domains/add`, adminJwt, { domain: ' ' }); - expect(res.status).toBe(400); - expect(await env.db.select().from(emailDomains)).toHaveLength(0); - }); - - test('keeps a pasted token out of the audit log', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - vi.spyOn(globalThis, 'fetch').mockImplementation(async () => - Response.json( - { success: false, errors: [{ code: 10000, message: 'nope' }] }, - { status: 403 }, - ), - ); - const res = await post(`/admin/email/${projectId}/domains/add`, adminJwt, { - domain: 'elsewhere.test', - token: 'cf-pasted-token-dummy', - }); - // The engine records the refusal on the row; the form redirects. - expect([302, 400, 502]).toContain(res.status); - expect(JSON.stringify(await env.db.select().from(operatorEvents))).not.toContain( - 'cf-pasted-token-dummy', - ); + expect(removed.status).toBe(302); + expect((await env.db.select().from(emailDomainRoutes))[0]?.desired_state).toBe('removed'); }); }); diff --git a/platform/packages/api/test/integration/api-delete.test.ts b/platform/packages/api/test/integration/api-delete.test.ts index 42ecc3f9b..a5956bfb4 100644 --- a/platform/packages/api/test/integration/api-delete.test.ts +++ b/platform/packages/api/test/integration/api-delete.test.ts @@ -677,20 +677,13 @@ describe('DELETE /projects/:id — CF email destination cleanup', () => { }); // --------------------------------------------------------------------------- -// The proxy authorizes `/email/send` with `__VOID_PROXY_TOKEN`, an HMAC of the -// project id that never expires and that the tenant's own worker code can -// read. After teardown the ONLY things that stop that token from sending are -// the `email-slug:` and `email-allowlist:` KV mirrors -// (a missing slug mirror is a 502, a missing allowlist denies every -// recipient) — the proxy reads a missing routing blob as "not suspended". -// Once the cascade has run there is no row left to retry the deletes from -// and nothing sweeps them, so a mirror that outlives the project keeps a -// dead tenant sendable forever. Teardown therefore fails closed on those two -// deletes, exactly as the destination revoke paths do on their mirror write. +// Email authorization now reads the project and email control rows in PG. +// These legacy KV keys are display hints and cannot authorize a deleted +// project, so their cleanup is best effort. // --------------------------------------------------------------------------- describe('DELETE /projects/:id — email send authorization outlives nothing', () => { - it('keeps the project when the email mirrors cannot be deleted, and a retry finishes', async () => { + it('deletes the project even when obsolete email mirrors cannot be deleted', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'mail-kv-down'); mockCfApi(); @@ -720,29 +713,13 @@ describe('DELETE /projects/:id — email send authorization outlives nothing', ( }), env, ); - expect(res.status).toBe(503); - expect(((await res.json()) as { error: string }).error).toMatch(/try again/); - - // The row is the retry handle: it stays, marked deleting, with the - // mirrors it will delete on the next attempt still in place. + expect(res.status).toBe(200); const [kept] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(kept?.status).toBe('deleting'); + expect(kept).toBeUndefined(); expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBe(project.slug); expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).not.toBeNull(); failing.mockRestore(); - const retry = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(retry.status).toBe(200); - const [gone] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(gone).toBeUndefined(); - expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBeNull(); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); expect(await env.ROUTING.get(project.slug)).toBeNull(); }); @@ -772,20 +749,15 @@ describe('DELETE /projects/:id — email send authorization outlives nothing', ( }), env, ); - expect(res.status).toBe(503); + expect(res.status).toBe(200); expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBeNull(); const [kept] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(kept?.status).toBe('deleting'); + expect(kept).toBeUndefined(); }); }); // --------------------------------------------------------------------------- -// The inbound lane has the same shape: a registered domain's relay secret -// never expires, and the `email-domain:` mirror is what the proxy's -// /email/relay proves it against. The FK cascade destroys the email_domains -// rows — after it, the set of mirror keys is unrecoverable and nothing -// sweeps them — so teardown clears them fail-closed BEFORE the cascade, -// alongside the send mirrors. +// Legacy domain KV hints are no longer used for inbound authorization. // --------------------------------------------------------------------------- describe('DELETE /projects/:id — email domain mirrors outlive nothing', () => { @@ -838,7 +810,7 @@ describe('DELETE /projects/:id — email domain mirrors outlive nothing', () => expect(await env.ROUTING.get('email-domain:mail.acme.example')).toBeNull(); }); - it('keeps the project when an email-domain mirror cannot be deleted, and a retry finishes', async () => { + it('deletes the project when an obsolete domain mirror cannot be deleted', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'mail-domain-kv-down'); mockCfApi(); @@ -859,32 +831,18 @@ describe('DELETE /projects/:id — email domain mirrors outlive nothing', () => }), env, ); - expect(res.status).toBe(503); - expect(((await res.json()) as { error: string }).error).toMatch(/try again/); - - // The row is the retry handle: it stays, marked deleting, with the - // domain row and mirror it will delete on the next attempt in place. + expect(res.status).toBe(200); const [kept] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(kept?.status).toBe('deleting'); + expect(kept).toBeUndefined(); expect(await env.ROUTING.get('email-domain:acme.com')).not.toBeNull(); const [domainRow] = await env.db .select() .from(emailDomains) .where(eq(emailDomains.project_id, project.id)); - expect(domainRow?.domain).toBe('acme.com'); + expect(domainRow).toBeUndefined(); failing.mockRestore(); - const retry = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(retry.status).toBe(200); - const [gone] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(gone).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme.com')).toBeNull(); + expect(await env.ROUTING.get('email-domain:acme.com')).not.toBeNull(); }); }); diff --git a/platform/packages/api/test/integration/api-email-domains.test.ts b/platform/packages/api/test/integration/api-email-domains.test.ts index d8bfd1ab2..2944e98c6 100644 --- a/platform/packages/api/test/integration/api-email-domains.test.ts +++ b/platform/packages/api/test/integration/api-email-domains.test.ts @@ -1,26 +1,4 @@ -/** - * Control-plane coverage for custom email domains on the customer's own - * Cloudflare zone (design doc 0078, "Custom domains on Cloudflare"). - * - * Routes under test (mounted in `src/index.ts`): - * - `GET /projects/:id/email/domains` - * - `POST /projects/:id/email/domains` - * - `GET /projects/:id/email/domains/:domain` - * - `POST /projects/:id/email/domains/:domain/sync` - * - `DELETE /projects/:id/email/domains/:domain` - * - `POST /internal/email/domain-credential` (the proxy's lease) - * - * The CF calls go to the CUSTOMER's account with the customer's credential, - * so the platform-wide `mockCfApi` helper does not cover them — this file - * stubs fetch itself (`stubCustomerCf`), including the OAuth token endpoint - * (dash.cloudflare.com) and the public-DNS MX lookup (cloudflare-dns.com). - * - * All credential-shaped strings are dummy stand-ins, never real material. - * Secret-shaped request bodies are recorded by SHAPE (name/type/length), - * never by value, and no response may contain a credential fixture. - */ - -import { eq, sql } from 'drizzle-orm'; +import { eq } from 'drizzle-orm'; import { afterAll, afterEach, @@ -32,3036 +10,205 @@ import { vi, } from 'vite-plus/test'; import { hmacSignState } from '../../src/auth/hmac.ts'; -import type { Db } from '../../src/db.ts'; -import { - leaseEmailDomainCredential, - refreshOauthGrantSerialized, -} from '../../src/email/credential-lease.ts'; -import { - decryptEmailDomainRelaySecret, - decryptEmailDomainToken, - encryptEmailDomainRelaySecret, - encryptEmailDomainToken, - hashEmailRelaySecret, - markEmailDomainRemovalFailed, - writeEmailDomainMirror, -} from '../../src/email/domains.ts'; -import type { EmailDomain } from '../../src/email/domains.ts'; -import { RELAY_WORKER_BASE_NAME } from '../../src/email/relay-engine.ts'; -import { - RELAY_COMPATIBILITY_DATE, - RELAY_EMAIL_DOMAIN_BINDING, - RELAY_PROXY_ORIGIN_BINDING, - RELAY_SECRET_BINDING, - RELAY_VERSION, -} from '../../src/email/relay-worker.ts'; +import { emailCredentials, emailOperations } from '../../src/email/connection-schema.ts'; import app from '../../src/index.ts'; -import { emailDomains, platformSettings, projects } from '../../src/schema.ts'; -import { - callsByTag, - sleep, - stubCustomerCf, - tags, - type RecordedCall, - type StubFailTag, -} from './email-domain-cf-stub.ts'; +import { stubCustomerCf } from './email-domain-cf-stub.ts'; import { clearTables, createTestProject, createTestUser, + JWT_SECRET, setupEnv, teardownEnv, - JWT_SECRET, type TestEnv, } from './helpers.ts'; -import { setTestDb } from './setup.ts'; let env: TestEnv; - -// Dummy stand-ins — never real token/secret material. -const API_TOKEN = 'cf-api-token-dummy'; -const API_TOKEN_REPLACEMENT = 'cf-api-token-replacement-dummy'; -const REFRESH_TOKEN = 'cf-refresh-token-dummy'; -const RELAY_SECRET = 'relay-secret-dummy'; -const ZONE = { id: 'zone_1', name: 'acme.com', accountId: 'acct_1' }; - -/** - * Pause the app's Nth `db.transaction` until released — the seam for - * landing a committed write (a replace, a teardown status flip) between a - * route's unlocked entry checks and its serialized section. PGlite's - * single connection forbids touching the db from inside an open - * transaction, so the write must happen BEFORE the tx starts: the proxy - * pauses prior to delegating, the test writes through the unwrapped - * `realDb` (or a concurrent request's pass-through transactions), then - * releases. Same pattern as cli-version-gate.test.ts. - */ -function pauseNthTransaction( - realDb: Db, - n: number, -): { - wrappedDb: Db; - reached: Promise; - release: () => void; -} { - const realTransaction = realDb.transaction.bind(realDb); - let releaseFn: (() => void) | undefined; - let reachedFn: (() => void) | undefined; - const reached = new Promise((r) => { - reachedFn = r; - }); - let seen = 0; - const wrappedDb = new Proxy(realDb, { - get(target, prop, receiver) { - if (prop === 'transaction') { - return (async (fn: never) => { - seen += 1; - if (seen === n) { - reachedFn?.(); - await new Promise((r) => { - releaseFn = r; - }); - } - return realTransaction(fn); - }) as unknown as typeof realDb.transaction; - } - return Reflect.get(target, prop, receiver); - }, - }) as Db; - return { wrappedDb, reached, release: () => releaseFn?.() }; -} - -function pauseFirstTransaction(realDb: Db) { - return pauseNthTransaction(realDb, 1); +const token = 'customer-scoped-token'; +const zones = { + 'example.com': { id: 'zone-example', name: 'example.com', accountId: 'customer-account' }, +}; +function runtime() { + return { ...env, EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test' } as typeof env; +} +function call(projectId: string, jwt: string, method: string, path: string, body?: unknown) { + return app.fetch( + new Request(`http://localhost/projects/${projectId}/email${path}`, { + method, + headers: { + Authorization: `Bearer ${jwt}`, + ...(body ? { 'Content-Type': 'application/json' } : {}), + }, + body: body ? JSON.stringify(body) : undefined, + }), + runtime(), + ); } - beforeAll(async () => { env = await setupEnv(); }); - afterAll(async () => { await teardownEnv(); }); - beforeEach(async () => { await clearTables(env.db); - // ROUTING is file-scoped — sweep this suite's mirror keys so tests don't - // leak mirror state into each other. - const mirrors = await env.ROUTING.list({ prefix: 'email-domain:' }); - await Promise.all(mirrors.keys.map((key) => env.ROUTING.delete(key.name))); }); - afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); }); -// --------------------------------------------------------------------------- -// Request helpers -// --------------------------------------------------------------------------- - -function addDomain(projectId: string, jwt: string, body: unknown) { - return app.fetch( - new Request(`http://localhost/projects/${projectId}/email/domains`, { - method: 'POST', - headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' }, - body: JSON.stringify(body), - }), - env, - ); -} - -function listDomains(projectId: string, jwt: string) { - return app.fetch( - new Request(`http://localhost/projects/${projectId}/email/domains`, { - headers: { Authorization: `Bearer ${jwt}` }, - }), - env, - ); -} - -function domainStatus(projectId: string, domain: string, jwt: string) { - return app.fetch( - new Request(`http://localhost/projects/${projectId}/email/domains/${domain}`, { - headers: { Authorization: `Bearer ${jwt}` }, - }), - env, - ); -} - -function syncDomain(projectId: string, domain: string, jwt: string) { - return app.fetch( - new Request(`http://localhost/projects/${projectId}/email/domains/${domain}/sync`, { - method: 'POST', - headers: { Authorization: `Bearer ${jwt}` }, - }), - env, - ); -} - -function removeDomain( - projectId: string, - domain: string, - jwt: string, - options?: { force?: boolean }, -) { - return app.fetch( - new Request( - `http://localhost/projects/${projectId}/email/domains/${domain}${options?.force ? '?force=1' : ''}`, - { - method: 'DELETE', - headers: { Authorization: `Bearer ${jwt}` }, - }, - ), - env, - ); -} - -async function leaseCredential(domain: string, signAs?: string) { - const token = await hmacSignState(signAs ?? domain, JWT_SECRET); - return app.fetch( - new Request('http://localhost/internal/email/domain-credential', { - method: 'POST', - headers: { 'Content-Type': 'application/json', 'x-void-internal': token }, - body: JSON.stringify({ domain }), - }), - env, - ); -} - -function leaseCredentialUnsigned(domain: string) { - return app.fetch( - new Request('http://localhost/internal/email/domain-credential', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ domain }), - }), - env, - ); -} - -// --------------------------------------------------------------------------- -// Row / mirror helpers -// --------------------------------------------------------------------------- - -async function rowFor(projectId: string, domain: string): Promise { - const rows = await env.db - .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)); - return rows.find((row) => row.domain === domain); -} - -async function mirrorFor(domain: string): Promise | null> { - const raw = await env.ROUTING.get(`email-domain:${domain}`); - return raw === null ? null : (JSON.parse(raw as string) as Record); -} - -/** Seed a row directly (no orchestration), with an optional mirror. */ -async function seedEmailDomain( - projectId: string, - domain: string, - options: { - status: EmailDomain['status']; - credentialKind?: EmailDomain['credential_kind']; - credential?: string; - mirror?: boolean; - relayWorkerName?: string; - }, -): Promise { - const credentialKind = options.credentialKind ?? 'api_token'; - const tokenEnc = await encryptEmailDomainToken( - env, - projectId, - domain, - options.credential ?? API_TOKEN, - ); - const relayEnc = await encryptEmailDomainRelaySecret(env, projectId, domain, RELAY_SECRET); - const id = `edom_seed_${domain.replace(/[^a-z0-9]/g, '')}`; - await env.db.insert(emailDomains).values({ - id, - project_id: projectId, - domain, - zone_id: ZONE.id, - account_id: ZONE.accountId, - mode: 'apex', - status: options.status, - credential_kind: credentialKind, - token_ciphertext: tokenEnc.ciphertext, - token_iv: tokenEnc.iv, - token_key_version: tokenEnc.keyVersion, - relay_ciphertext: relayEnc.ciphertext, - relay_iv: relayEnc.iv, - relay_key_version: relayEnc.keyVersion, - relay_worker_name: options.relayWorkerName ?? RELAY_WORKER_BASE_NAME, - relay_version: RELAY_VERSION, - }); - const row = (await rowFor(projectId, domain))!; - if (options.mirror !== false) { - await writeEmailDomainMirror(env.ROUTING, row, await hashEmailRelaySecret(RELAY_SECRET)); - } - return row; -} - -describe('email_domains token triple constraint', () => { - it('rejects a partially-null stored token triple', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await expect( - env.db.insert(emailDomains).values({ - id: 'edom_partial_token', - project_id: project.id, - domain: 'partial-token.example', - credential_kind: 'api_token', - token_ciphertext: 'ciphertext', - token_iv: null, - token_key_version: 'v1', - relay_ciphertext: 'relay-ciphertext', - relay_iv: 'relay-iv', - relay_key_version: 'v1', - }), - ).rejects.toThrow(); - }); - - it('rejects a stored token on a platform row', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await expect( - env.db.insert(emailDomains).values({ - id: 'edom_platform_token', - project_id: project.id, - domain: 'platform-token.example', - credential_kind: 'platform', - managed_by: 'admin', - token_ciphertext: 'must-not-be-stored', - token_iv: null, - token_key_version: null, - relay_ciphertext: 'relay-ciphertext', - relay_iv: 'relay-iv', - relay_key_version: 'v1', - }), - ).rejects.toThrow(); - }); -}); - -/** Add an active api_token domain through the real route. */ -async function addActiveDomain( - projectId: string, - jwt: string, - domain = 'acme.com', - zones: Record = { 'acme.com': ZONE }, -) { - const stub = stubCustomerCf({ zones }); - const res = await addDomain(projectId, jwt, { domain, apiToken: API_TOKEN }); - expect(res.status).toBe(201); - return stub; -} - -// A token_expires_on value only the final apply ever writes (the verify -// stub returns it; the checkpoint never touches the column), so an AFTER -// UPDATE trigger on it fails exactly the apply — with a NON-unique error. -const APPLY_SENTINEL_EXPIRY = '2030-01-01T00:00:00.000Z'; - -async function installApplySentinelTrigger(): Promise { - await env.db.execute( - sql.raw( - `CREATE OR REPLACE FUNCTION email_apply_sentinel_raise() RETURNS trigger - LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'email apply sentinel'; END; $$`, - ), - ); - await env.db.execute( - sql.raw( - // Idempotent: tests pre-install before the request and the sentinel - // must survive any number of non-apply UPDATEs until the apply fires. - `DROP TRIGGER IF EXISTS email_apply_sentinel ON email_domains`, - ), - ); - await env.db.execute( - sql.raw( - `CREATE TRIGGER email_apply_sentinel AFTER UPDATE ON email_domains - FOR EACH ROW WHEN (NEW.token_expires_on = '2030-01-01 00:00:00'::timestamp) - EXECUTE FUNCTION email_apply_sentinel_raise()`, - ), - ); -} - -async function dropApplySentinelTrigger(): Promise { - await env.db.execute(sql.raw('DROP TRIGGER IF EXISTS email_apply_sentinel ON email_domains')); - await env.db.execute(sql.raw('DROP FUNCTION IF EXISTS email_apply_sentinel_raise()')); -} - -// Same mechanism as the apply sentinel, but firing on the deploy -// CHECKPOINT write instead. The engine's pre-upload claim writes -// relay_worker_name first, so the checkpoint's distinguishing transition -// is zone_id null→non-null (the claim never touches zone_id; the final -// apply writes it already-set) — a NON-unique error here fails exactly -// the checkpoint. -async function installCheckpointSentinelTrigger(): Promise { - await env.db.execute( - sql.raw( - `CREATE OR REPLACE FUNCTION email_checkpoint_sentinel_raise() RETURNS trigger - LANGUAGE plpgsql AS $$ BEGIN RAISE EXCEPTION 'email checkpoint sentinel'; END; $$`, - ), - ); - await env.db.execute( - sql.raw(`DROP TRIGGER IF EXISTS email_checkpoint_sentinel ON email_domains`), - ); - await env.db.execute( - sql.raw( - `CREATE TRIGGER email_checkpoint_sentinel AFTER UPDATE ON email_domains - FOR EACH ROW WHEN (OLD.zone_id IS NULL AND NEW.zone_id IS NOT NULL) - EXECUTE FUNCTION email_checkpoint_sentinel_raise()`, - ), - ); -} - -async function dropCheckpointSentinelTrigger(): Promise { - await env.db.execute( - sql.raw('DROP TRIGGER IF EXISTS email_checkpoint_sentinel ON email_domains'), - ); - await env.db.execute(sql.raw('DROP FUNCTION IF EXISTS email_checkpoint_sentinel_raise()')); -} - -// --------------------------------------------------------------------------- -// Owner guard -// --------------------------------------------------------------------------- - -describe('email domain routes — owner guard', () => { - it('401s unauthenticated', async () => { - const res = await app.fetch( - new Request('http://localhost/projects/proj_nope/email/domains', { method: 'POST' }), - env, - ); - expect(res.status).toBe(401); - }); - - it('404s for a nonexistent project', async () => { - const user = await createTestUser(env.db); - const res = await addDomain('proj_nope', user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(404); - }); - - it('403s a non-owner on every domain verb', async () => { - const owner = await createTestUser(env.db, 'owner'); - const other = await createTestUser(env.db, 'other'); - const project = await createTestProject(env.db, owner.id); - await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - - const responses = await Promise.all([ - addDomain(project.id, other.jwt, { domain: 'acme.com', apiToken: API_TOKEN }), - listDomains(project.id, other.jwt), - domainStatus(project.id, 'acme.com', other.jwt), - syncDomain(project.id, 'acme.com', other.jwt), - removeDomain(project.id, 'acme.com', other.jwt), - ]); - expect(responses.map((res) => res.status)).toEqual([403, 403, 403, 403, 403]); - // The non-owner never reached the row or the mirror. - expect(await rowFor(project.id, 'acme.com')).toBeDefined(); - expect(await mirrorFor('acme.com')).not.toBeNull(); - }); -}); - -describe('email domain routes — administrator-managed platform', () => { - it('refuses an owner add under admin management, names the command, and revokes the grant', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'hr-portal'); - await env.db.insert(platformSettings).values({ key: 'email.domains', value: 'admin' }); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'Acme.COM', - refreshToken: REFRESH_TOKEN, - }); - expect(res.status).toBe(403); - expect(await res.json()).toEqual({ - error: 'email domains on this platform are managed by its administrator', - adminCommand: 'void platform email domain-add acme.com --project hr-portal', - }); - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - }); - - it('still lets an owner renew, sync and remove a row they registered before the switch', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'hr-portal'); - await seedEmailDomain(project.id, 'acme.com', { status: 'token_expired' }); - await env.db.insert(platformSettings).values({ key: 'email.domains', value: 'admin' }); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - // Renewal re-add of the owner's own row: allowed, credential replaced. - const readd = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(readd.status).toBe(200); - expect((await rowFor(project.id, 'acme.com'))?.managed_by).toBe('owner'); - expect(callsByTag(stub.calls, 'verifyToken').length).toBeGreaterThan(0); - - expect((await syncDomain(project.id, 'acme.com', user.jwt)).status).toBe(200); - // A NEW domain is what admin mode refuses. - const fresh = await addDomain(project.id, user.jwt, { - domain: 'new.example', - apiToken: API_TOKEN, - }); - expect(fresh.status).toBe(403); - expect(await fresh.json()).toMatchObject({ - adminCommand: 'void platform email domain-add new.example --project hr-portal', - }); - expect((await removeDomain(project.id, 'acme.com', user.jwt)).status).toBe(200); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - }); - - it("lets an owner read but not sync, remove or re-add an administrator's row", async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'hr-portal'); - const seeded = await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - await env.db - .update(emailDomains) - .set({ managed_by: 'admin' }) - .where(eq(emailDomains.id, seeded.id)); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const list = await listDomains(project.id, user.jwt); - expect(list.status).toBe(200); - expect(await list.json()).toMatchObject([{ domain: 'acme.com', managed_by: 'admin' }]); - const status = await domainStatus(project.id, 'acme.com', user.jwt); +describe('project email domain authority', () => { + it('rejects unauthenticated, foreign-owner, malformed and OAuth requests before Cloudflare writes', async () => { + const owner = await createTestUser(env.db, 'domain-owner'), + other = await createTestUser(env.db, 'domain-other'); + const project = await createTestProject(env.db, owner.id, 'owned-mail'); + const stub = stubCustomerCf({ zones }); + expect((await call(project.id, '', 'GET', '/domains')).status).toBe(401); + expect( + ( + await call(project.id, other.jwt, 'POST', '/domains', { + domain: 'mail.example.com', + apiToken: token, + }) + ).status, + ).toBe(403); + expect( + ( + await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'bad domain', + apiToken: token, + }) + ).status, + ).toBe(400); + expect( + ( + await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'mail.example.com', + refreshToken: 'oauth-grant', + }) + ).status, + ).toBe(400); + expect(stub.calls).toHaveLength(0); + }); + + it('stores connection-scoped token ciphertext and returns operation/readiness without secret material', async () => { + const owner = await createTestUser(env.db, 'registered-owner'); + const project = await createTestProject(env.db, owner.id, 'registered-mail'); + stubCustomerCf({ zones }); + const response = await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'Mail.Example.COM', + apiToken: token, + attemptId: 'stable-add', + }); + expect(response.status).toBe(200); + const body = (await response.json()) as { + operationId: string; + attemptId: string; + readiness: { inbound: { status: string } }; + domain: string; + }; + expect(body.domain).toBe('mail.example.com'); + expect(body.attemptId).toBe('stable-add'); + expect(body.operationId).toMatch(/^eop/); + expect(body.readiness.inbound.status).toBe('ready'); + expect(JSON.stringify(body)).not.toContain(token); + const credential = (await env.db.select().from(emailCredentials))[0]!; + expect(credential.kind).toBe('api_token'); + expect(credential.ciphertext).not.toContain(token); + expect(credential.account_id).toBe('customer-account'); + const status = await call(project.id, owner.jwt, 'GET', '/operations/stable-add'); expect(status.status).toBe(200); - expect(await status.json()).toMatchObject({ managed_by: 'admin' }); - - const sync = await syncDomain(project.id, 'acme.com', user.jwt); - expect(sync.status).toBe(403); - expect(await sync.json()).toEqual({ - error: 'this email domain is managed by the platform administrator', - adminCommand: 'void platform email domain-sync acme.com', - }); - const remove = await removeDomain(project.id, 'acme.com', user.jwt); - expect(remove.status).toBe(403); - expect(await remove.json()).toMatchObject({ - adminCommand: 'void platform email domain-remove acme.com', - }); - const readd = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(readd.status).toBe(403); - expect(await readd.json()).toMatchObject({ - adminCommand: 'void platform email domain-add acme.com --project hr-portal', - }); - // Nothing destructive ran; the grant the re-add posted was revoked. - expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(0); - expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); - expect(callsByTag(stub.calls, 'oauthRevoke')).toHaveLength(1); - expect((await rowFor(project.id, 'acme.com'))?.credential_kind).toBe('api_token'); - }); -}); - -// --------------------------------------------------------------------------- -// POST /projects/:id/email/domains -// --------------------------------------------------------------------------- - -describe('POST /projects/:id/email/domains', () => { - it('rejects malformed input before any credential work', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const cases: Array<[unknown, string]> = [ - [{}, 'no domain'], - [{ domain: 42, apiToken: API_TOKEN }, 'non-string domain'], - [{ domain: 'not a domain', apiToken: API_TOKEN }, 'invalid shape'], - [{ domain: 'acme.com' }, 'no credential'], - [ - { domain: 'acme.com', apiToken: API_TOKEN, refreshToken: REFRESH_TOKEN }, - 'both credentials', - ], - [{ domain: 'acme.com', apiToken: API_TOKEN, mode: 'weird' }, 'bad mode'], - ]; - for (const [body, label] of cases) { - const res = await addDomain(project.id, user.jwt, body); - expect(res.status, label).toBe(400); - } - // Nothing was stored. The only CF call is the revoke of the 'both - // credentials' case's posted grant — a rejected minted grant whose only - // copy the CLI drops must not be stranded live in the customer's - // account. api_token bodies carry no revoke primitive. - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(stub.calls[0]!.form!.token).toBe(REFRESH_TOKEN); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - }); - - it('adds an apex domain with an api_token — full contract-7 order, encrypted storage, mirror', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ - domain: 'acme.com', - mode: 'apex', - status: 'active', - credential_kind: 'api_token', - relay_worker_name: RELAY_WORKER_BASE_NAME, - relay_version: RELAY_VERSION, - token_id: 'tok_dummy', - setup_state: null, - }); - // No ciphertext triples, no credential material in the response. - const raw = await Promise.resolve(JSON.stringify(json)); - for (const leaked of [API_TOKEN, 'ciphertext', 'relay_ciphertext', 'token_ciphertext']) { - expect(raw).not.toContain(leaked); - } - - // The step order is contract 7's: verify → zone → MX → routing → - // sending → relay deploy (exists → put → secret) → catch-all, with the - // ownership read ahead of the catch-all write. - expect(tags(stub.calls)).toEqual([ - 'verifyToken', - 'zones', - 'mxLookup', - 'routingDns', - 'onboardSending', - 'scriptGet', - 'scriptPut', - 'secretPut', - 'catchAllGet', - 'catchAll', - ]); - // Apex routing enable: empty body. - expect(callsByTag(stub.calls, 'routingDns')[0]!.body).toBeUndefined(); - expect(callsByTag(stub.calls, 'onboardSending')[0]!.body).toEqual({ name: 'acme.com' }); - - // The relay upload declares the two plain-text vars and the module. - const upload = callsByTag(stub.calls, 'scriptPut')[0]!.body as Record; - expect(upload).toMatchObject({ - main_module: 'index.js', - compatibility_date: RELAY_COMPATIBILITY_DATE, - bindings: [ - { type: 'plain_text', name: RELAY_PROXY_ORIGIN_BINDING, text: 'https://proxy.void.cloud' }, - { type: 'plain_text', name: RELAY_EMAIL_DOMAIN_BINDING, text: 'acme.com' }, - ], - }); - // The relay secret goes out as a worker secret — asserted by shape. - expect(callsByTag(stub.calls, 'secretPut')[0]!.secret).toEqual({ - name: RELAY_SECRET_BINDING, - type: 'secret_text', - textShape: 'len=43 base64url', - }); - // The catch-all names the relay, one action, enabled. - expect(callsByTag(stub.calls, 'catchAll')[0]!.body).toEqual({ - matchers: [{ type: 'all' }], - actions: [{ type: 'worker', value: [RELAY_WORKER_BASE_NAME] }], - enabled: true, - }); - - // Storage: ciphertexts decrypt under the fixed AAD names; the mirror - // carries the sha256 and no secret material. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe(API_TOKEN); - const relaySecret = await decryptEmailDomainRelaySecret(env, project.id, 'acme.com', row); - const mirror = (await mirrorFor('acme.com'))!; - expect(mirror).toEqual({ - projectId: project.id, - status: 'active', - relaySecretSha256: await hashEmailRelaySecret(relaySecret), - relayWorkerName: RELAY_WORKER_BASE_NAME, - accountId: ZONE.accountId, - zoneId: ZONE.id, - mode: 'apex', - }); - expect(JSON.stringify(mirror)).not.toContain(relaySecret); - expect(JSON.stringify(mirror)).not.toContain(API_TOKEN); - }); - - it('takes the subdomain path when the zone is the parent', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'mail.acme.com', - mode: 'subdomain', - apiToken: API_TOKEN, - }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ domain: 'mail.acme.com', mode: 'subdomain', status: 'active' }); - // Zone lookup walked the labels up. - expect(callsByTag(stub.calls, 'zones').map((call) => call.url)).toEqual([ - expect.stringContaining('name=mail.acme.com'), - expect.stringContaining('name=acme.com'), - ]); - // Subdomain routing enable carries { name }. - expect(callsByTag(stub.calls, 'routingDns')[0]!.body).toEqual({ name: 'mail.acme.com' }); - }); - - it('stays pending with the human step when the subdomain routing POST is refused', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { routingDns: { message: 'forbidden', status: 403 } }, - }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'mail.acme.com', - apiToken: API_TOKEN, - }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('pending'); - expect(json.setup_state).toEqual({ remaining_steps: ['routing_subdomain'] }); - // Everything after the refused POST still ran — relay deployed, mirror written. - expect(json.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect((await mirrorFor('mail.acme.com'))!.status).toBe('pending'); - }); - - it('completes inbound setup on a Workers Free sending refusal — active, the plan step recorded', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { - onboardSending: { - message: 'account is not entitled to Email Sending', - status: 403, - code: 10105, - }, - }, - }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - // Email Routing needs no paid plan: the relay deployed, the catch-all - // was written, and the row + mirror are ACTIVE — inbound works. Only - // the outbound lane stays refused at CF until a plan upgrade. - expect(json.status).toBe('active'); - expect(json.setup_state).toEqual({ remaining_steps: ['sending_onboarding'] }); - expect(json.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(tags(stub.calls)).toEqual( - expect.arrayContaining(['onboardSending', 'scriptPut', 'secretPut', 'catchAll']), - ); - expect((await mirrorFor('acme.com'))!.status).toBe('active'); - }); - - it('fails at mx_check when the domain already carries MX', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - mx: { 'acme.com': ['aspmx.l.google.com'] }, - }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('failed'); - expect(json.setup_state).toEqual({ failed_step: 'mx_check' }); - expect(String(json.error)).toContain('aspmx.l.google.com'); - // Partial progress is on the row; no routing/sending/relay calls ran. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row.zone_id).toBe(ZONE.id); - expect(row.account_id).toBe(ZONE.accountId); - expect(row.relay_worker_name).toBeNull(); - expect((await mirrorFor('acme.com'))!.status).toBe('failed'); - }); - - it('records the relay name when the secret PUT fails — a re-add redeploys in place', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { secretPut: { message: 'quota', status: 400 } }, - }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('failed'); - expect(json.setup_state).toEqual({ failed_step: 'deploy_relay' }); - - // The script upload succeeded before the secret PUT failed, so the row - // records the chosen name — a blind delete would race a concurrent - // deploy's upsert, and an unrecorded upload would leak the worker and - // walk the retry to '-2'. - const failedRow = (await rowFor(project.id, 'acme.com'))!; - expect(failedRow.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(failedRow.relay_version).toBeNull(); - - // The customer fixes the quota and re-adds: the recorded name is - // redeployed IN PLACE — no name-walk (no scriptGet), no '-2'. - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const retry = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN, - }); - expect(retry.status).toBe(200); - expect(((await retry.json()) as Record).status).toBe('active'); - expect(callsByTag(stub.calls, 'scriptGet')).toEqual([]); - expect(callsByTag(stub.calls, 'scriptPut').map((call) => call.url)).toEqual([ - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${RELAY_WORKER_BASE_NAME}`, - ]); - expect((await rowFor(project.id, 'acme.com'))!.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - }); - - it('maps a non-active api token to token_revoked at verify_credential', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ verifyStatus: 'disabled' }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('token_revoked'); - expect(json.setup_state).toEqual({ failed_step: 'verify_credential' }); - }); - - it('maps an expired api token to token_expired', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ verifyStatus: 'expired' }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - const json = (await res.json()) as Record; - expect(json.status).toBe('token_expired'); - }); - - it('409s when the requested mode contradicts the zone-derived mode', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - mode: 'subdomain', - apiToken: API_TOKEN, - }); - expect(res.status).toBe(409); - // The row records the derived truth. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row.mode).toBe('apex'); - expect(row.status).toBe('active'); - }); - - it('409s when the domain is registered to another project — one domain, one project', async () => { - const user = await createTestUser(env.db); - const first = await createTestProject(env.db, user.id); - const second = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const created = await addDomain(first.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN, - }); - expect(created.status).toBe(201); - const callsAfterFirst = stub.calls.length; - - // Same user, second project, same zone credential: a domain maps to - // exactly one project — the single `email-domain:` mirror key - // and relay secret cannot fan out to two. - const res = await addDomain(second.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN, - }); - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe( - 'domain is registered to another project', - ); - - // Nothing reached CF and no row exists for the second project; the - // first project's row and mirror are untouched. - expect(stub.calls.length).toBe(callsAfterFirst); - expect(await rowFor(second.id, 'acme.com')).toBeUndefined(); - expect((await rowFor(first.id, 'acme.com'))!.status).toBe('active'); - expect((await mirrorFor('acme.com'))!.projectId).toBe(first.id); - }); - - it('409s a conflicting oauth add and revokes the rejected grant — unless it is the winner’s own', async () => { - const user = await createTestUser(env.db); - const first = await createTestProject(env.db, user.id); - const second = await createTestProject(env.db, user.id); - // The winner holds an oauth grant. - await seedEmailDomain(first.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - const stub = stubCustomerCf({}); - - // A DIFFERENT freshly minted grant loses the claim: revoked. The CLI - // drops its only copy of the grant on the 409, so without the revoke a - // live broad grant strands in the customer's account per retry. - const res = await addDomain(second.id, user.jwt, { - domain: 'acme.com', - refreshToken: 'cf-refresh-token-dummy-other', - }); - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe( - 'domain is registered to another project', - ); - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(stub.calls[0]!.form!.token).toBe('cf-refresh-token-dummy-other'); - - // The SAME grant re-pasted must NOT be revoked — revoking the winner's - // own stored credential would brick its live row (the decrypt-compare - // guard fails safe toward keeping). - const repasted = await addDomain(second.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(repasted.status).toBe(409); - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect((await rowFor(first.id, 'acme.com'))!.status).toBe('active'); - }); - - it('409s when another live row already claims the zone — the loser is compensated, never activated', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - // Row one is seeded DIRECTLY: a route-registered first domain would - // leave the stub's catch-all naming its relay, and the second domain's - // engine run would then fail at its own catch-all precheck instead of - // reaching the checkpoint (that path is covered by its own test above). - await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - - // Domain two resolves to the SAME zone; its relay name-walk takes '-2' - // because the base name is taken in the account. The deploy CHECKPOINT - // (after the relay deploy, before the catch-all step) is where the zone - // backstop catches the race — the loser never writes its rule. - const stub = stubCustomerCf({ - zones: { 'other.com': { ...ZONE, name: 'other.com' } }, - existingScripts: [RELAY_WORKER_BASE_NAME], - }); - const res = await addDomain(project.id, user.jwt, { domain: 'other.com', apiToken: API_TOKEN }); - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe( - 'another active email domain already uses this zone — remove it first', - ); - - // Bounded compensation ran from the checkpoint payload: ONE ownership - // read (the zone's untouched disabled-drop default names no relay, so - // no reset) and the delete of the SECOND relay — never the first's. - expect(callsByTag(stub.calls, 'catchAllGet')).toHaveLength(1); - expect(callsByTag(stub.calls, 'scriptDelete').map((call) => call.url)).toEqual([ - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${RELAY_WORKER_BASE_NAME}-2`, - ]); - // The loser NEVER reached its catch-all write — the checkpoint aborts - // setup first — so the winner's zone rule is byte-identical. - expect(callsByTag(stub.calls, 'catchAll')).toEqual([]); - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ enabled: false, workerName: null }); - - // Row one is untouched; row two stayed pre-apply and got no mirror. - expect((await rowFor(project.id, 'acme.com'))!).toMatchObject({ - status: 'active', - zone_id: ZONE.id, - account_id: ZONE.accountId, - relay_worker_name: RELAY_WORKER_BASE_NAME, - }); - expect((await rowFor(project.id, 'other.com'))!).toMatchObject({ - status: 'pending', - zone_id: null, - account_id: null, - mode: null, - relay_worker_name: null, - }); - expect(await mirrorFor('other.com')).toBeNull(); - expect((await mirrorFor('acme.com'))!.projectId).toBe(project.id); - }); - - it('claims the relay name before the upload — a db-held name is skipped and never written', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - // Row one (seeded directly, same reason as the zone race above) already - // holds 'void-email-relay-2' in the account — committed, so a - // concurrent walk's claim of '-2' 23505s on the relay index. - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - relayWorkerName: `${RELAY_WORKER_BASE_NAME}-2`, - }); - - // Domain two resolves to a DIFFERENT zone in the SAME account. CF shows - // only the BASE name physically present, so the CF probe alone would - // walk to '-2' — pre-fix the loser OVERWROTE row one's worker there - // before its checkpoint 23505d. The pre-upload claim is what skips - // '-2' now, and the walk lands on '-3'. - const stub = stubCustomerCf({ - zones: { 'other.com': { id: 'zone_2', name: 'other.com', accountId: ZONE.accountId } }, - existingScripts: [RELAY_WORKER_BASE_NAME], - }); - // The winner's deployed secret on '-2', through the stub's own sha256 - // tracking (the same RELAY_SECRET the seeded mirror carries). - const contested = `${RELAY_WORKER_BASE_NAME}-2`; - await fetch( - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${contested}/secrets`, - { - method: 'PUT', - body: JSON.stringify({ - name: RELAY_SECRET_BINDING, - type: 'secret_text', - text: RELAY_SECRET, + expect(((await status.json()) as { operationId: string }).operationId).toBe(body.operationId); + const replay = await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'mail.example.com', + apiToken: token, + attemptId: 'stable-add', + }); + expect(((await replay.json()) as { operationId: string }).operationId).toBe(body.operationId); + const conflict = await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'mail.example.com', + apiToken: 'another-token', + attemptId: 'stable-add', + }); + expect(conflict.status).toBe(409); + expect(await env.db.select().from(emailOperations)).toHaveLength(1); + }); + + it('leases only an exact active route for the signed owning project', async () => { + const owner = await createTestUser(env.db, 'lease-owner'), + other = await createTestUser(env.db, 'lease-other'); + const project = await createTestProject(env.db, owner.id, 'lease-mail'); + const foreign = await createTestProject(env.db, other.id, 'foreign-mail'); + stubCustomerCf({ zones }); + expect( + ( + await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'lease.example.com', + apiToken: token, + }) + ).status, + ).toBe(200); + const lease = async (projectId: string, domain: string, signatureDomain = domain) => + app.fetch( + new Request('http://localhost/internal/email/domain-credential', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'x-void-internal': await hmacSignState( + `email-lease-v1\n${projectId}\n${signatureDomain}`, + JWT_SECRET, + ), + }, + body: JSON.stringify({ domain, projectId }), }), - }, - ); - const winnerHashBefore = stub.secretHashes.get(contested); - expect(winnerHashBefore).toBe(await hashEmailRelaySecret(RELAY_SECRET)); - const winnerMirrorBefore = await mirrorFor('acme.com'); - const callsBeforeAdd = stub.calls.length; - - const res = await addDomain(project.id, user.jwt, { domain: 'other.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - expect(json.relay_worker_name).toBe(`${RELAY_WORKER_BASE_NAME}-3`); - - // The walk CF-probed base, '-2' and '-3' in order… - const during = stub.calls.slice(callsBeforeAdd); - expect(callsByTag(during, 'scriptGet').map((call) => call.url)).toEqual([ - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${RELAY_WORKER_BASE_NAME}`, - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${contested}`, - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${RELAY_WORKER_BASE_NAME}-3`, - ]); - // …but the contested name was NEVER written — no script PUT, no - // secret PUT, no delete. Stronger than the old 'never deleted': the - // claim skips the name before any upload. - const writes = [...callsByTag(during, 'scriptPut'), ...callsByTag(during, 'secretPut')]; - expect(writes.length).toBeGreaterThan(0); - expect(writes.some((call) => call.url.includes(`/${contested}`))).toBe(false); - expect(callsByTag(during, 'scriptDelete')).toEqual([]); - - // The winner's worker secret and mirror are byte-identical; its row - // is untouched. - expect(stub.secretHashes.get(contested)).toBe(winnerHashBefore); - expect(await mirrorFor('acme.com')).toEqual(winnerMirrorBefore); - expect((await rowFor(project.id, 'acme.com'))!).toMatchObject({ - status: 'active', - zone_id: ZONE.id, - account_id: ZONE.accountId, - relay_worker_name: contested, - }); - - // The loser went active on '-3': its catch-all names its own relay, - // and worker, row and mirror carry ONE secret. - expect(stub.catchAllStates.get('zone_2')).toEqual({ - enabled: true, - workerName: `${RELAY_WORKER_BASE_NAME}-3`, - }); - const loserRow = (await rowFor(project.id, 'other.com'))!; - expect(loserRow).toMatchObject({ - status: 'active', - zone_id: 'zone_2', - account_id: ZONE.accountId, - relay_worker_name: `${RELAY_WORKER_BASE_NAME}-3`, - }); - const loserHash = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(env, project.id, 'other.com', loserRow), - ); - expect(stub.secretHashes.get(`${RELAY_WORKER_BASE_NAME}-3`)).toBe(loserHash); - expect((await mirrorFor('other.com'))!.relaySecretSha256).toBe(loserHash); - }); - - it('claims distinct relay names for two concurrent setups in the same account', async () => { - const user = await createTestUser(env.db); - const projectA = await createTestProject(env.db, user.id); - const projectB = await createTestProject(env.db, user.id); - - // Two zones in ONE customer account, nothing deployed yet: both - // name-walks start at the base name. The hold gives the overlap - // window — the FIRST setup to reach its secret PUT parks until the - // other settles or the cap fires (the same synchronization as - // 'serializes concurrent setup retries'). PGlite's single connection - // serializes the second request's transaction behind the first's - // commit, so the interleave this actually exercises is the - // COMMITTED-winner one: the loser's claim of the base name 23505s - // past the winner's commit and its walk advances to '-2'. Pre-fix - // the loser picked the same name from the CF probe, overwrote the - // winner's worker with its own binding + secret, and 409d at its - // checkpoint. - let holdFirstSecretPut = true; - const stub = stubCustomerCf({ - zones: { - 'a.com': { id: 'zone_a', name: 'a.com', accountId: ZONE.accountId }, - 'b.com': { id: 'zone_b', name: 'b.com', accountId: ZONE.accountId }, - }, - on: { - secretPut: async () => { - if (!holdFirstSecretPut) { - return; - } - holdFirstSecretPut = false; - await Promise.race([bothSettled, sleep(500)]); - }, - }, - }); - const first = addDomain(projectA.id, user.jwt, { domain: 'a.com', apiToken: API_TOKEN }); - const second = addDomain(projectB.id, user.jwt, { domain: 'b.com', apiToken: API_TOKEN }); - const bothSettled = Promise.allSettled([first, second]); - const [firstRes, secondRes] = await Promise.all([first, second]); - expect(firstRes.status).toBe(201); - expect(secondRes.status).toBe(201); - - const rowA = (await rowFor(projectA.id, 'a.com'))!; - const rowB = (await rowFor(projectB.id, 'b.com'))!; - expect(rowA.status).toBe('active'); - expect(rowB.status).toBe('active'); - // DISTINCT names — first-to-claim, never last-write-wins. - const names = [rowA.relay_worker_name, rowB.relay_worker_name]; - expect(new Set(names).size).toBe(2); - expect(names.sort()).toEqual([RELAY_WORKER_BASE_NAME, `${RELAY_WORKER_BASE_NAME}-2`].sort()); - - // THE invariant, per domain: the secret on the worker, the row's - // stored triple, and the proxy mirror's hash are ONE secret. - for (const [project, domain, row] of [ - [projectA, 'a.com', rowA], - [projectB, 'b.com', rowB], - ] as const) { - const rowHash = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(env, project.id, domain, row), + runtime(), ); - expect(stub.secretHashes.get(row.relay_worker_name!)).toBe(rowHash); - expect((await mirrorFor(domain))!.relaySecretSha256).toBe(rowHash); - } - }); - - it('409s and revokes the posted grant when the project is marked deleting before setup', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - // Pause the route's FIRST transaction — the project-lock + insert tx — - // before it opens (no locks held yet), so the teardown mark lands - // first and the locked re-read sees it. The engine can no longer be - // mid-flight when teardown starts: it runs under this same lock. - const gate = pauseFirstTransaction(env.db); - setTestDb(gate.wrappedDb); - try { - const resPromise = addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - await gate.reached; - await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); - gate.release(); - const res = await resPromise; - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe('Project is being deleted'); - // Nothing was persisted: no row, no mirror, no CF calls — and the - // freshly minted grant, whose only copy the CLI drops on an error - // response, was revoked rather than stranded. - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(callsByTag(stub.calls, 'oauthRevoke')[0]!.form!.token).toBe(REFRESH_TOKEN); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - } finally { - setTestDb(env.db); - } - }); - - it('409s and revokes the posted grant when the project is already being deleted on arrival', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); - const stub = stubCustomerCf({}); - - // The ENTRY guard rejects — the body is parsed before it precisely so - // this 409 can revoke the grant the CLI drops on the error response. - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe('Project is being deleted'); - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(stub.calls[0]!.form!.token).toBe(REFRESH_TOKEN); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - }); - - it('404s and revokes the posted grant when the project is gone', async () => { - const user = await createTestUser(env.db); - const stub = stubCustomerCf({}); - - // The project guard rejects like every other guard — the CLI drops its - // only copy of the grant on the 404, so the route revokes it first. - const res = await addDomain('prj_gone', user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(res.status).toBe(404); - expect(((await res.json()) as { error: string }).error).toBe('project not found'); - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(stub.calls[0]!.form!.token).toBe(REFRESH_TOKEN); - }); - - it('403s and revokes the posted grant when the caller does not own the project', async () => { - const owner = await createTestUser(env.db); - const project = await createTestProject(env.db, owner.id); - const stranger = await createTestUser(env.db); - const stub = stubCustomerCf({}); - - // Possession of the token already authorizes its revocation (RFC 7009 on - // a public client), so the ownership rejection revokes too — otherwise - // the CLI drops the grant it minted and nobody kills it. - const res = await addDomain(project.id, stranger.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(res.status).toBe(403); - expect(((await res.json()) as { error: string }).error).toBe('forbidden'); - expect(tags(stub.calls)).toEqual(['oauthRevoke']); - expect(stub.calls[0]!.form!.token).toBe(REFRESH_TOKEN); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - }); - - it('500s when the checkpoint write fails for a non-race reason — and compensates the deployed relay', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - await installCheckpointSentinelTrigger(); - let res; - try { - res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - } finally { - await dropCheckpointSentinelTrigger(); - } - - // A non-unique checkpoint failure is NOT a race: it propagates. - expect(res.status).toBe(500); - // …but only after compensating the relay the rolled-back UPDATE never - // recorded: ONE ownership read (no reset — the zone's default names no - // relay) and the relay DELETE. - expect(callsByTag(stub.calls, 'catchAllGet')).toHaveLength(1); - expect(callsByTag(stub.calls, 'catchAll')).toEqual([]); - expect(callsByTag(stub.calls, 'scriptDelete').map((call) => call.url)).toEqual([ - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${RELAY_WORKER_BASE_NAME}`, - ]); - // The row carries no reference to the deleted relay. - expect((await rowFor(project.id, 'acme.com'))!).toMatchObject({ - status: 'pending', - relay_worker_name: null, - }); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('repoints an owned catch-all at the zone winner when the final apply loses the race', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - // Row A crashed AFTER the checkpoint: 'failed', but carrying its zone - // and relay. Re-running it deploys in place (no checkpoint), so the - // zone conflict surfaces only at the FINAL apply — the re-run window. - await seedEmailDomain(project.id, 'acme.com', { - status: 'failed', - relayWorkerName: `${RELAY_WORKER_BASE_NAME}-a`, - }); - // Row B is the live winner of the same zone. - await seedEmailDomain(project.id, 'other.com', { - status: 'active', - relayWorkerName: `${RELAY_WORKER_BASE_NAME}-b`, - }); - - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { - routingDns: { message: 'already enabled', status: 400 }, - onboardSending: { message: 'already exists', status: 409 }, - }, - routingSettings: { enabled: true, status: 'ready' }, - sendingSubdomains: [{ name: 'acme.com', enabled: true }], - // The repoint path proves the winner's relay exists before AND after. - existingScripts: [`${RELAY_WORKER_BASE_NAME}-b`], - }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe( - 'another active email domain already uses this zone — remove it first', + const valid = await lease(project.id, 'lease.example.com'); + expect(valid.status).toBe(200); + expect(await valid.json()).toMatchObject({ + kind: 'api_token', + token, + accountId: 'customer-account', + }); + expect((await lease(foreign.id, 'lease.example.com')).status).toBe(404); + expect((await lease(project.id, 'lease.example.com', 'other.example.com')).status).toBe(403); + const signed = await hmacSignState( + `email-lease-v1\n${project.id}\nlease.example.com`, + JWT_SECRET, + ); + const oversized = await app.fetch( + new Request('http://localhost/internal/email/domain-credential', { + method: 'POST', + headers: { 'Content-Type': 'application/json', 'x-void-internal': signed }, + body: JSON.stringify({ + domain: 'lease.example.com', + projectId: project.id, + padding: 'x'.repeat(5000), + }), + }), + runtime(), + ); + expect(oversized.status).toBe(413); + const malformed = await app.fetch( + new Request('http://localhost/internal/email/domain-credential', { + method: 'POST', + headers: { 'Content-Type': 'application/json', 'x-void-internal': signed }, + body: 'null', + }), + runtime(), + ); + expect(malformed.status).toBe(400); + const unsigned = await app.fetch( + new Request('http://localhost/internal/email/domain-credential', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: 'null', + }), + runtime(), ); - - // The engine wrote A's rule; the compensation REPOINTED it at B's relay - // instead of resetting — the zone's inbound keeps working for the - // winner. - expect(callsByTag(stub.calls, 'catchAllGet')).toHaveLength(2); - expect(callsByTag(stub.calls, 'catchAll').map((call) => call.body)).toEqual([ - { - matchers: [{ type: 'all' }], - actions: [{ type: 'worker', value: [`${RELAY_WORKER_BASE_NAME}-a`] }], - enabled: true, - }, - { - matchers: [{ type: 'all' }], - actions: [{ type: 'worker', value: [`${RELAY_WORKER_BASE_NAME}-b`] }], - enabled: true, - }, - ]); - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ - enabled: true, - workerName: `${RELAY_WORKER_BASE_NAME}-b`, - }); - // A zone race keeps the account id: A's own relay is deleted. - expect(callsByTag(stub.calls, 'scriptDelete').map((call) => call.url)).toEqual([ - `https://api.cloudflare.com/client/v4/accounts/${ZONE.accountId}/workers/scripts/${RELAY_WORKER_BASE_NAME}-a`, - ]); - - // A stays exactly as seeded; B is untouched. - expect((await rowFor(project.id, 'acme.com'))!).toMatchObject({ - status: 'failed', - zone_id: ZONE.id, - relay_worker_name: `${RELAY_WORKER_BASE_NAME}-a`, - }); - expect((await rowFor(project.id, 'other.com'))!).toMatchObject({ - status: 'active', - zone_id: ZONE.id, - relay_worker_name: `${RELAY_WORKER_BASE_NAME}-b`, - }); - }); - - it('serializes concurrent setup retries — the worker secret, row and mirror move together', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - // A row whose setup never finished: both retries re-run the full - // engine (the branch is decided on the LOCKED row). - await seedEmailDomain(project.id, 'acme.com', { status: 'failed' }); - - // Hold the FIRST engine run at its secret PUT until the other request - // has settled (or a cap fires) — the maximal-overlap window. The hook - // touches no db, so holding it inside the serialized section is safe; - // the queued second request cannot settle, so the cap is what - // releases the first. - let holdFirstSecretPut = true; - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { - routingDns: { message: 'already enabled', status: 400 }, - onboardSending: { message: 'already exists', status: 409 }, - }, - routingSettings: { enabled: true, status: 'ready' }, - sendingSubdomains: [{ name: 'acme.com', enabled: true }], - existingScripts: [RELAY_WORKER_BASE_NAME], - on: { - secretPut: async () => { - if (!holdFirstSecretPut) { - return; - } - holdFirstSecretPut = false; - await Promise.race([bothSettled, sleep(500)]); - }, - }, - }); - const first = addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - const second = addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - const bothSettled = Promise.allSettled([first, second]); - const [firstRes, secondRes] = await Promise.all([first, second]); - expect(firstRes.status).toBe(200); - expect(secondRes.status).toBe(200); - - // THE invariant: the secret on the worker, the row's stored triple, - // and the proxy mirror's hash are ONE secret. Two UNLOCKED engine - // runs interleave their secret PUTs and applies — the last PUT is one - // request's secret, the last apply the other's — and this diverges. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row.status).toBe('active'); - const rowHash = await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(env, project.id, 'acme.com', row), - ); - expect(stub.secretHashes.get(RELAY_WORKER_BASE_NAME)).toBe(rowHash); - expect((await mirrorFor('acme.com'))!.relaySecretSha256).toBe(rowHash); - }); - - it('adds an oauth_grant domain — one refresh round-trip, rotation persisted', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ - status: 'active', - credential_kind: 'oauth_grant', - token_id: null, - }); - - // The refresh ran on wrangler's public client with the posted grant… - const oauth = callsByTag(stub.calls, 'oauthToken'); - expect(oauth).toHaveLength(1); - expect(oauth[0]!.form).toEqual({ - grant_type: 'refresh_token', - client_id: '54d11594-84e4-41aa-b438-e81b8fa78ee7', - refresh_token: REFRESH_TOKEN, - }); - // …and every customer call rode the fresh access token, so the grant - // path never calls /user/tokens/verify. - expect(callsByTag(stub.calls, 'verifyToken')).toEqual([]); - // The rotated refresh token replaced the posted one on the row. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe( - 'cf-rotated-refresh-dummy-1', - ); - const raw = JSON.stringify(json); - expect(raw).not.toContain(REFRESH_TOKEN); - expect(raw).not.toContain('cf-rotated-refresh-dummy-1'); - }); - - it('stamps a posted attemptId on the row and serializes it back', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN, - attemptId: 'attempt-add-1', - }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.attemptId).toBe('attempt-add-1'); - expect((await rowFor(project.id, 'acme.com'))!.attempt_id).toBe('attempt-add-1'); - }); - - it('serializes attemptId as null when the add posted none — the old-CLI shape', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - // The key is always present — presence is the new-api signal. - expect(json.attemptId).toBeNull(); - expect((await rowFor(project.id, 'acme.com'))!.attempt_id).toBeNull(); - }); - - it('rejects a malformed attemptId and revokes the posted grant', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - - for (const attemptId of [42, '', 'x'.repeat(129)]) { - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - attemptId, - }); - expect(res.status, JSON.stringify(attemptId)).toBe(400); - } - // Every rejection revokes a posted grant — this one included. - expect(tags(stub.calls)).toEqual(['oauthRevoke', 'oauthRevoke', 'oauthRevoke']); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - }); - - it('re-stamps attempt_id when a re-add replaces the credential', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - expect((await rowFor(project.id, 'acme.com'))!.attempt_id).toBeNull(); - - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - attemptId: 'attempt-readd-1', - }); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.attemptId).toBe('attempt-readd-1'); - expect((await rowFor(project.id, 'acme.com'))!.attempt_id).toBe('attempt-readd-1'); - }); - - it('maps invalid_grant on add to token_revoked, mirrored', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE }, oauth: 'invalid_grant' }); - - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: REFRESH_TOKEN, - }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('token_revoked'); - expect(json.setup_state).toEqual({ failed_step: 'verify_credential' }); - expect(callsByTag(stub.calls, 'zones')).toEqual([]); - expect((await mirrorFor('acme.com'))!.status).toBe('token_revoked'); - }); - - it('re-adds a failed row — the credential is replaced and setup re-runs', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - mx: { 'acme.com': ['aspmx.l.google.com'] }, - }); - await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect((await rowFor(project.id, 'acme.com'))!.status).toBe('failed'); - - // The customer fixes DNS (MX gone) and re-adds with a fresh token. - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - const row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe( - API_TOKEN_REPLACEMENT, - ); - expect(row.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - }); - - it('re-adds an active row — rules stay, the relay is redeployed and its secret rotated', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const before = await mirrorFor('acme.com'); - - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - expect(json.catch_all).toBe('already_set'); - - // The sync path: verify + relay redeploy + secret PUT + the catch-all - // ensure probe — no zone, MX, routing, or sending calls, and no - // catch-all WRITE (the rule already names this row's relay). - expect(tags(stub.calls)).toEqual(['verifyToken', 'scriptPut', 'secretPut', 'catchAllGet']); - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ - enabled: true, - workerName: RELAY_WORKER_BASE_NAME, - }); - const row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe( - API_TOKEN_REPLACEMENT, - ); - // Relay name never changes; the mirror's sha256 rotated with the secret. - expect(row.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - const after = await mirrorFor('acme.com'); - expect(after!.relaySecretSha256).not.toBe(before!.relaySecretSha256); - expect(after!.status).toBe('active'); - }); - - it('re-adds with a dead credential — token_revoked, but the recorded progress is kept', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const before = (await rowFor(project.id, 'acme.com'))!; - expect(before.status).toBe('active'); - - // The replacement token verifies as non-active — the engine fails at - // verify_credential, before re-learning any lifecycle field. - stubCustomerCf({ verifyStatus: 'disabled' }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('token_revoked'); - expect(json.setup_state).toEqual({ failed_step: 'verify_credential' }); - - // The early failure must not erase what the row already recorded. - const after = (await rowFor(project.id, 'acme.com'))!; - expect(after.status).toBe('token_revoked'); - expect(after.zone_id).toBe(before.zone_id); - expect(after.account_id).toBe(before.account_id); - expect(after.mode).toBe(before.mode); - expect(after.relay_worker_name).toBe(before.relay_worker_name); - expect((await mirrorFor('acme.com'))!.status).toBe('token_revoked'); - }); - - it('refuses to overwrite an enabled catch-all that names another worker', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - catchAllRule: { enabled: true, workerName: 'someone-elses-worker' }, - }); - - const res = await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - expect(res.status).toBe(201); - const json = (await res.json()) as Record; - expect(json.status).toBe('failed'); - expect(json.setup_state).toEqual({ failed_step: 'catch_all' }); - expect(String(json.error)).toContain('someone-elses-worker'); - // The relay deployed (the row keeps its name for repair), but the - // foreign rule was never overwritten. - expect(json.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(callsByTag(stub.calls, 'catchAllGet')).toHaveLength(1); - expect(callsByTag(stub.calls, 'catchAll')).toEqual([]); - }); - - it('re-adds a catch_all-failed row — the full setup re-runs and writes the rule', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { catchAll: { message: 'rules quota', status: 400 } }, - }); - await addDomain(project.id, user.jwt, { domain: 'acme.com', apiToken: API_TOKEN }); - const failedRow = (await rowFor(project.id, 'acme.com'))!; - expect(failedRow.status).toBe('failed'); - expect(failedRow.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - - // Re-add: the engine re-runs against the row's recorded progress — no - // MX check (the first attempt's MX is ours), the already-done steps' - // 4xx are believed only on their read-backs, the relay redeploys in - // place, and the step the first attempt missed finally runs. - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { - routingDns: { message: 'already enabled', status: 400 }, - onboardSending: { message: 'already exists', status: 409 }, - }, - routingSettings: { enabled: true, status: 'ready' }, - sendingSubdomains: [{ name: 'acme.com', enabled: true }], - }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - - const tagList = tags(stub.calls); - expect(tagList).not.toContain('mxLookup'); - // In-place redeploy: no name-walk, the recorded name is reused. - expect(tagList).not.toContain('scriptGet'); - expect(tagList).toContain('routingSettingsGet'); - expect(tagList).toContain('sendingSubdomainsGet'); - expect(callsByTag(stub.calls, 'catchAll')[0]!.body).toEqual({ - matchers: [{ type: 'all' }], - actions: [{ type: 'worker', value: [RELAY_WORKER_BASE_NAME] }], - enabled: true, - }); - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row.status).toBe('active'); - expect(row.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect((await mirrorFor('acme.com'))!.status).toBe('active'); - }); - - it('revokes the old grant once the replaced credential is safely stored', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - await addDomain(project.id, user.jwt, { domain: 'acme.com', refreshToken: REFRESH_TOKEN }); - // The first add rotated the chain: the row now holds - // cf-rotated-refresh-dummy-1 — that is the grant the replace revokes. - - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: 'cf-refresh-token-dummy-2', - }); - expect(res.status).toBe(200); - // One revoke, of the OLD chain head, fired right after the credential - // replace committed — before the new grant's first refresh. - const revocations = callsByTag(stub.calls, 'oauthRevoke'); - expect(revocations).toHaveLength(1); - expect(revocations[0]!.form!.token).toBe('cf-rotated-refresh-dummy-1'); - expect(tags(stub.calls).indexOf('oauthRevoke')).toBeLessThan( - tags(stub.calls).indexOf('oauthToken'), - ); - }); - - it('skips the revoke when the identical grant is re-pasted', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - await addDomain(project.id, user.jwt, { domain: 'acme.com', refreshToken: REFRESH_TOKEN }); - - // The stored chain head is cf-rotated-refresh-dummy-1; re-pasting THAT - // exact plaintext must not revoke it — the revoke would brick the - // just-stored credential. - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - refreshToken: 'cf-rotated-refresh-dummy-1', - }); - expect(res.status).toBe(200); - expect(callsByTag(stub.calls, 'oauthRevoke')).toEqual([]); - // …and the chain simply continued from the re-pasted head. - expect(callsByTag(stub.calls, 'oauthToken')[0]!.form!.refresh_token).toBe( - 'cf-rotated-refresh-dummy-1', - ); - }); - - it('compensates and 500s a post-deploy non-unique apply failure', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - verifyExpiresOn: APPLY_SENTINEL_EXPIRY, - }); - // Pre-installed: the sentinel fires only on the apply's UPDATE (the - // checkpoint never writes token_expires_on), so installing it up front - // fails exactly the apply — with a NON-unique error. The reconciliation's - // re-read finds the checkpoint-persisted relay NAME but not the - // apply's relay_version (the checkpoint never writes it), so the - // row is NOT taken as applied: the orphaned relay is compensated - // and the original error rethrows. - await installApplySentinelTrigger(); - try { - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN, - }); - expect(res.status).toBe(500); - // Compensation ran with the loser's OWN account_id (not a name - // race): catch-all ownership read → reset, then the relay DELETE. - expect(callsByTag(stub.calls, 'catchAllGet')).toHaveLength(2); - expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(2); - expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); - // The stub's catch-all ends reset (disabled drop) — the engine's - // write was rolled back CF-side by the compensation. - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ enabled: false, workerName: null }); - // The row keeps the checkpoint state: progress stands, but status - // and token fields stay pre-apply, and no mirror was written. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row).toMatchObject({ - status: 'pending', - zone_id: ZONE.id, - account_id: ZONE.accountId, - relay_worker_name: RELAY_WORKER_BASE_NAME, - relay_version: null, - token_id: null, - token_expires_on: null, - }); - expect(await mirrorFor('acme.com')).toBeNull(); - } finally { - await dropApplySentinelTrigger(); - } - }); - - it('500s a non-unique apply failure when setup failed before the deploy', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - mx: { 'acme.com': ['aspmx.l.google.com'] }, - verifyExpiresOn: APPLY_SENTINEL_EXPIRY, - }); - // Same pre-install: the MX conflict fails setup before any deploy, so - // the sentinel's first victim is the FAILURE-result apply. - await installApplySentinelTrigger(); - try { - const res = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN, - }); - // Nothing deployed → nothing to compensate: the error rethrows. - expect(res.status).toBe(500); - expect(callsByTag(stub.calls, 'catchAllGet')).toEqual([]); - expect(callsByTag(stub.calls, 'scriptDelete')).toEqual([]); - // The row keeps its pre-apply state. - expect((await rowFor(project.id, 'acme.com'))!).toMatchObject({ - status: 'pending', - zone_id: null, - relay_worker_name: null, - }); - expect(await mirrorFor('acme.com')).toBeNull(); - } finally { - await dropApplySentinelTrigger(); - } - }); -}); - -// --------------------------------------------------------------------------- -// GET list / status -// --------------------------------------------------------------------------- - -describe('GET /projects/:id/email/domains', () => { - it('lists rows without secret material', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - // A public ID may contain `_iv`; only secret field names must be excluded. - const id = 'edom_ivm16k7p54l5'; - await env.db.update(emailDomains).set({ id }).where(eq(emailDomains.project_id, project.id)); - - const res = await listDomains(project.id, user.jwt); - expect(res.status).toBe(200); - const rows = (await res.json()) as Array>; - expect(rows).toHaveLength(1); - expect(rows[0]).toMatchObject({ id, domain: 'acme.com', status: 'active' }); - expect(JSON.stringify(rows)).not.toContain(API_TOKEN); - for (const field of [ - 'token_ciphertext', - 'token_iv', - 'token_key_version', - 'relay_ciphertext', - 'relay_iv', - 'relay_key_version', - ]) { - expect(rows[0]).not.toHaveProperty(field); - } - }); -}); - -describe('GET /projects/:id/email/domains/:domain', () => { - it('re-probes the credential and reports no drift on a healthy row', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const mirrorBefore = await env.ROUTING.get('email-domain:acme.com'); - - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ - status: 'active', - credential_status: 'active', - relay_version: RELAY_VERSION, - current_relay_version: RELAY_VERSION, - relay_drift: false, - relay_missing: false, - catch_all: 'points_here', - catch_all_drift: false, - }); - // The probe re-verified the token, checked the relay exists, and read - // the zone catch-all. - expect(tags(stub.calls)).toEqual(['verifyToken', 'scriptGet', 'catchAllGet']); - // A healthy probe does not rewrite the mirror (read-compare repair). - expect(await env.ROUTING.get('email-domain:acme.com')).toBe(mirrorBefore); - }); - - it('reports a catch-all pointing at another worker as drift', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: 'someone-elses-worker' }, - }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ catch_all: 'points_elsewhere', catch_all_drift: true }); - }); - - it('reports a missing or disabled catch-all as drift', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - // No rule at all (CF 404). - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: null, - }); - let res = await domainStatus(project.id, 'acme.com', user.jwt); - expect((await res.json()) as Record).toMatchObject({ - catch_all: 'missing', - catch_all_drift: true, - }); - - // CF's real default for a zone that never had a rule: a disabled drop. - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - }); - res = await domainStatus(project.id, 'acme.com', user.jwt); - expect((await res.json()) as Record).toMatchObject({ - catch_all: 'disabled', - catch_all_drift: true, - }); - }); - - it('reports an unreachable catch-all probe as unknown, not drift', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - failOn: { catchAllGet: { message: 'boom', status: 500 } }, - }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ catch_all: 'unknown', catch_all_drift: false }); - }); - - it('skips mirror repair while a removal failure is pending', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - // A keep-row DELETE left its mark: the row is mid-removal… - await env.db - .update(emailDomains) - .set({ - setup_state: { - failed_step: 'remove', - removal_failed_steps: ['catch_all', 'delete_relay'], - }, - }) - .where(eq(emailDomains.id, row.id)); - // …and the mirror drifted — a healthy row WOULD repair this back. - await writeEmailDomainMirror( - env.ROUTING, - { ...row, status: 'failed' }, - await hashEmailRelaySecret(RELAY_SECRET), - ); - const drifted = await env.ROUTING.get('email-domain:acme.com'); - - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ status: 'active', catch_all: 'points_here' }); - // The proxy mirror must not be "repaired" against a state the operator - // is about to finish removing. - expect(await env.ROUTING.get('email-domain:acme.com')).toBe(drifted); - }); - - it('repairs a drifted mirror from the LOCKED row — a concurrent rotation is not overwritten', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - // Force drift: the mirror is missing, so the poll's repair path runs. - await env.ROUTING.delete('email-domain:acme.com'); - - const ROTATED_SECRET = 'relay-secret-rotated-dummy'; - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - on: { - // The catch-all probe runs AFTER the route's row snapshot was read - // and BEFORE the repair: a concurrent sync rotating the relay - // secret and republishing the mirror lands exactly in the repair's - // race window. No transaction is open during the probes, so these - // writes are safe. - catchAllGet: async () => { - const rotated = await encryptEmailDomainRelaySecret( - env, - project.id, - 'acme.com', - ROTATED_SECRET, - ); - await env.db - .update(emailDomains) - .set({ - relay_ciphertext: rotated.ciphertext, - relay_iv: rotated.iv, - relay_key_version: rotated.keyVersion, - }) - .where(eq(emailDomains.domain, 'acme.com')); - await writeEmailDomainMirror( - env.ROUTING, - (await rowFor(project.id, 'acme.com'))!, - await hashEmailRelaySecret(ROTATED_SECRET), - ); - }, - }, - }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - - // The mirror converges to the ROTATED secret: the repair re-reads the - // row under the lock, finds the republished mirror already matching, - // and writes nothing. Writing from the route's stale snapshot would - // restore the pre-rotation hash — inbound would reject every message. - expect((await mirrorFor('acme.com'))!.relaySecretSha256).toBe( - await hashEmailRelaySecret(ROTATED_SECRET), - ); - }); - - it('self-clears the sending-onboarding step once the read-back confirms it', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - await env.db - .update(emailDomains) - .set({ setup_state: { remaining_steps: ['sending_onboarding'] } }) - .where(eq(emailDomains.id, row.id)); - - // Not onboarded yet — the step survives the poll. - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - let res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - expect((await rowFor(project.id, 'acme.com'))!.setup_state).toEqual({ - remaining_steps: ['sending_onboarding'], - }); - - // Onboarded (a post-upgrade sync landed it) — the poll clears the - // step; the row was already active, so only setup_state moves. - const stub2 = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - sendingSubdomains: [{ name: 'acme.com', enabled: true }], - }); - res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - expect(json.setup_state).toBeNull(); - expect(callsByTag(stub2.calls, 'sendingSubdomainsGet')).toHaveLength(1); - }); - - it('does not apply a stale probe verdict when the credential was replaced mid-poll', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - verifyStatus: 'expired', - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - on: { - // A renewal replace commits while the expired-verdict probe is in - // flight: the OLD token's verdict must not land on the NEW - // credential. - verifyToken: async () => { - const enc = await encryptEmailDomainToken( - env, - project.id, - 'acme.com', - API_TOKEN_REPLACEMENT, - ); - await env.db - .update(emailDomains) - .set({ - credential_kind: 'api_token', - token_ciphertext: enc.ciphertext, - token_iv: enc.iv, - token_key_version: enc.keyVersion, - token_id: null, - token_expires_on: null, - }) - .where(eq(emailDomains.id, row.id)); - }, - }, - }); - - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - // The fenced update refused the stale verdict; the probe is reported - // void, and the row keeps the replacement's state and status. - expect(json.credential_status).toBe('probe_failed'); - const fresh = (await rowFor(project.id, 'acme.com'))!; - expect(fresh.status).toBe('active'); - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', fresh)).toBe( - API_TOKEN_REPLACEMENT, - ); - expect((await mirrorFor('acme.com'))!.status).toBe('active'); - }); - - it('does not recreate the mirror when the project is torn down mid-poll', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - existingScripts: [RELAY_WORKER_BASE_NAME], - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - on: { - // Teardown lands between the last row re-read and the mirror - // repair: its mirror clear ran, then the cascade took the rows. - catchAllGet: async () => { - await env.ROUTING.delete('email-domain:acme.com'); - await env.db.delete(projects).where(eq(projects.id, project.id)); - }, - }, - }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - // The repair must not resurrect the key teardown cleared — nothing - // else would ever sweep it. - expect(await env.ROUTING.get('email-domain:acme.com')).toBeNull(); - }); - - it('flips a revoked token to token_revoked and repairs the mirror', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - stubCustomerCf({ verifyStatus: 'disabled' }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json.credential_status).toBe('revoked'); - expect(json.status).toBe('token_revoked'); - expect((await rowFor(project.id, 'acme.com'))!.status).toBe('token_revoked'); - expect((await mirrorFor('acme.com'))!.status).toBe('token_revoked'); - }); - - it('probes an oauth_grant with one serialized refresh and drops the access token', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - await addDomain(project.id, user.jwt, { domain: 'acme.com', refreshToken: REFRESH_TOKEN }); - - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ credential_status: 'active', status: 'active' }); - // The status probe refreshed with the ROTATED token (the chain moved). - expect(callsByTag(stub.calls, 'oauthToken')[0]!.form!.refresh_token).toBe( - 'cf-rotated-refresh-dummy-1', - ); - const row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe( - 'cf-rotated-refresh-dummy-2', - ); - expect(JSON.stringify(json)).not.toContain('cf-access-dummy'); - }); - - it('reports relay drift when the deployed version predates RELAY_VERSION', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - await env.db - .update(emailDomains) - .set({ relay_version: RELAY_VERSION - 1 }) - .where(eq(emailDomains.project_id, project.id)); - - stubCustomerCf({ zones: { 'acme.com': ZONE }, existingScripts: [RELAY_WORKER_BASE_NAME] }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json.relay_version).toBe(RELAY_VERSION - 1); - expect(json.relay_drift).toBe(true); - expect(json.relay_missing).toBe(false); - }); - - it('reports a missing relay as drift', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - // scriptGet 404s by default — the customer deleted the relay themselves. - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json.relay_missing).toBe(true); - expect(json.relay_drift).toBe(true); - }); - - it('self-clears the routing-subdomain human step once public MX names Cloudflare', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { routingDns: { message: 'forbidden', status: 403 } }, - }); - await addDomain(project.id, user.jwt, { domain: 'mail.acme.com', apiToken: API_TOKEN }); - expect((await rowFor(project.id, 'mail.acme.com'))!.status).toBe('pending'); - - // The human did the dashboard step: the subdomain's MX now points at - // Cloudflare's inbound exchanges. - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - mx: { 'mail.acme.com': ['route1.mx.cloudflare.net', 'route2.mx.cloudflare.net'] }, - existingScripts: [RELAY_WORKER_BASE_NAME], - }); - const res = await domainStatus(project.id, 'mail.acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - expect(json.setup_state).toBe(null); - expect((await rowFor(project.id, 'mail.acme.com'))!.status).toBe('active'); - // The mirror repair carried the new status to the proxy. - expect((await mirrorFor('mail.acme.com'))!.status).toBe('active'); - }); - - it('does not self-clear steps or reactivate while a removal failure is pending', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { routingDns: { message: 'forbidden', status: 403 } }, - }); - await addDomain(project.id, user.jwt, { domain: 'mail.acme.com', apiToken: API_TOKEN }); - const pending = (await rowFor(project.id, 'mail.acme.com'))!; - expect(pending.status).toBe('pending'); - - // A DELETE then fails its CF cleanup: the row is kept for retry, - // marked with failed_step 'remove' (the DELETE route's real writer). - await markEmailDomainRemovalFailed(env.db, pending.id, ['relay_delete']); - - // The human did the dashboard step mid-removal: the subdomain's MX - // now points at Cloudflare. The poll must neither clear the steps - // nor flip active — the row is the operator's to finish removing, - // and the mirror repair suppression (failed_step) must survive. - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - mx: { 'mail.acme.com': ['route1.mx.cloudflare.net', 'route2.mx.cloudflare.net'] }, - existingScripts: [RELAY_WORKER_BASE_NAME], - }); - const res = await domainStatus(project.id, 'mail.acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('pending'); - const fresh = (await rowFor(project.id, 'mail.acme.com'))!; - expect(fresh.status).toBe('pending'); - expect(fresh.setup_state).toEqual({ - remaining_steps: ['routing_subdomain'], - failed_step: 'remove', - removal_failed_steps: ['relay_delete'], - }); - // The mirror keeps the pending status — not reactivated mid-removal. - expect((await mirrorFor('mail.acme.com'))!.status).toBe('pending'); - }); - - it('does not flip a revoked row back to active when the revocation lands mid-poll', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { routingDns: { message: 'forbidden', status: 403 } }, - }); - await addDomain(project.id, user.jwt, { domain: 'mail.acme.com', apiToken: API_TOKEN }); - const pending = (await rowFor(project.id, 'mail.acme.com'))!; - - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - mx: { 'mail.acme.com': ['route1.mx.cloudflare.net', 'route2.mx.cloudflare.net'] }, - existingScripts: [RELAY_WORKER_BASE_NAME], - on: { - // A concurrent refresh consumes the dead grant (invalid_grant) - // and persists token_revoked while the MX evidence check is in - // flight — the self-clear must not overwrite it back to active. - mxLookup: async () => { - await env.db - .update(emailDomains) - .set({ status: 'token_revoked', updated_at: sql`now()` }) - .where(eq(emailDomains.id, pending.id)); - }, - }, - }); - const res = await domainStatus(project.id, 'mail.acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - // The fenced-out self-clear voided: the row keeps the revoked state - // and its recorded steps... - expect(json.status).toBe('token_revoked'); - const fresh = (await rowFor(project.id, 'mail.acme.com'))!; - expect(fresh.status).toBe('token_revoked'); - expect(fresh.setup_state).toEqual({ remaining_steps: ['routing_subdomain'] }); - // ...and the mirror repair converges the mirror to the true row. - expect((await mirrorFor('mail.acme.com'))!.status).toBe('token_revoked'); - }); - - it('stays pending while the subdomain has no Cloudflare MX', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { routingDns: { message: 'forbidden', status: 403 } }, - }); - await addDomain(project.id, user.jwt, { domain: 'mail.acme.com', apiToken: API_TOKEN }); - - stubCustomerCf({ zones: { 'acme.com': ZONE }, existingScripts: [RELAY_WORKER_BASE_NAME] }); - const res = await domainStatus(project.id, 'mail.acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json.status).toBe('pending'); - expect(json.setup_state).toEqual({ remaining_steps: ['routing_subdomain'] }); - }); - - it('404s for an unknown domain', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const res = await domainStatus(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(404); - }); -}); - -// --------------------------------------------------------------------------- -// sync / remove -// --------------------------------------------------------------------------- - -describe('POST /projects/:id/email/domains/:domain/sync', () => { - it('redeploys the relay and rotates the secret, mirroring the new sha256', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const before = await mirrorFor('acme.com'); - - // The stub's zone starts at CF's disabled-drop default, so the sync's - // catch-all ensure repoints it at the row's relay. - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json).toMatchObject({ - status: 'active', - relay_version: RELAY_VERSION, - catch_all: 'ensured', - }); - expect(tags(stub.calls)).toEqual([ - 'verifyToken', - 'scriptPut', - 'secretPut', - 'catchAllGet', - 'catchAll', - ]); - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ - enabled: true, - workerName: RELAY_WORKER_BASE_NAME, - }); - const after = await mirrorFor('acme.com'); - expect(after!.relaySecretSha256).not.toBe(before!.relaySecretSha256); - }); - - it('rolls the row back when the mirror write fails mid-sync', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const before = (await rowFor(project.id, 'acme.com'))!; - const beforeMirror = (await mirrorFor('acme.com'))!; - - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - // The mirror PUT is part of the serialized sync: its failure must - // roll the row apply back with it — never leave the row rotated to a - // secret the mirror does not name. (The reverse ordering is what the - // lock is for: two overlapping syncs publishing hashes out of order - // would break inbound auth the same way.) - const put = vi.spyOn(env.ROUTING, 'put').mockRejectedValueOnce(new Error('kv down')); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(500); - put.mockRestore(); - - const after = (await rowFor(project.id, 'acme.com'))!; - expect(after.relay_ciphertext).toBe(before.relay_ciphertext); - expect(after.relay_version).toBe(before.relay_version); - expect(after.status).toBe(before.status); - expect((await mirrorFor('acme.com'))!.relaySecretSha256).toBe(beforeMirror.relaySecretSha256); - }); - - it('refuses the sync when teardown marks the project deleting before the lock', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const before = (await rowFor(project.id, 'acme.com'))!; - const beforeMirror = (await mirrorFor('acme.com'))!; - - // Teardown's status flip lands between the route's entry guard and - // the serialized section: the in-transaction project recheck must - // refuse the sync — otherwise the relay would be redeployed and the - // mirror republished AFTER teardown cleared them, and the cascade - // would delete the row, leaving a recreated mirror, worker and - // catch-all with no database handle. - const realDb = env.db; - const gate = pauseFirstTransaction(realDb); - setTestDb(gate.wrappedDb); - try { - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const reqPromise = syncDomain(project.id, 'acme.com', user.jwt); - await gate.reached; - await realDb.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); - gate.release(); - - const res = await reqPromise; - expect(res.status).toBe(409); - expect(await res.json()).toEqual({ error: 'Project is being deleted' }); - // Refused before the engine ran — no CF call, no mirror write. - expect(stub.calls).toEqual([]); - const after = (await rowFor(project.id, 'acme.com'))!; - expect(after.relay_ciphertext).toBe(before.relay_ciphertext); - expect(after.status).toBe(before.status); - expect((await mirrorFor('acme.com'))!.relaySecretSha256).toBe(beforeMirror.relaySecretSha256); - } finally { - setTestDb(realDb); - } - }); - - it('reports a foreign catch-all without overwriting it', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - catchAllRule: { enabled: true, workerName: 'someone-elses-worker' }, - }); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - // Report, don't fight: the conflict surfaces in the response, the - // redeploy/rotation still succeed, and the foreign rule is never - // written. - expect(json).toMatchObject({ status: 'active', catch_all: 'foreign_conflict' }); - expect(tags(stub.calls)).toEqual(['verifyToken', 'scriptPut', 'secretPut', 'catchAllGet']); - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ - enabled: true, - workerName: 'someone-elses-worker', - }); - }); - - it('409s when the live-status flip collides with the zone winner', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - // A 'failed' row still RECORDS its zone (the partial zone index ignores - // 'failed'), so sync's flip back to a live status is where the race - // surfaces. No compensation runs on the sync path: the deploy was in - // place on the row's OWN relay, so only the flip is refused. - await seedEmailDomain(project.id, 'acme.com', { - status: 'failed', - relayWorkerName: `${RELAY_WORKER_BASE_NAME}-a`, - }); - await seedEmailDomain(project.id, 'other.com', { - status: 'active', - relayWorkerName: `${RELAY_WORKER_BASE_NAME}-b`, - }); - - const stub = stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(409); - expect(((await res.json()) as { error: string }).error).toBe( - 'another active email domain already uses this zone — remove it first', - ); - - // The redeploy + catch-all ensure ran; the refused flip changed nothing - // else — no compensation delete, and the row and mirror keep 'failed'. - expect(tags(stub.calls)).toEqual([ - 'verifyToken', - 'scriptPut', - 'secretPut', - 'catchAllGet', - 'catchAll', - ]); - expect(callsByTag(stub.calls, 'scriptDelete')).toEqual([]); - expect((await rowFor(project.id, 'acme.com'))!.status).toBe('failed'); - expect((await mirrorFor('acme.com'))!.status).toBe('failed'); - }); - - it('keeps a pending human step on the row', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - stubCustomerCf({ - zones: { 'acme.com': ZONE }, - failOn: { routingDns: { message: 'forbidden', status: 403 } }, - }); - await addDomain(project.id, user.jwt, { domain: 'mail.acme.com', apiToken: API_TOKEN }); - - stubCustomerCf({ zones: { 'acme.com': ZONE } }); - const res = await syncDomain(project.id, 'mail.acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json.status).toBe('pending'); - expect(json.setup_state).toEqual({ remaining_steps: ['routing_subdomain'] }); - }); - - it('re-attempts a pending sending onboarding and clears the step', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - await env.db - .update(emailDomains) - .set({ setup_state: { remaining_steps: ['sending_onboarding'] } }) - .where(eq(emailDomains.id, row.id)); - - // The upgrade landed; the sync's retry onboards and the step clears. - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - expect(json.status).toBe('active'); - expect(json.setup_state).toBeNull(); - expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(1); - }); - - it('keeps the sending step when the sync retry is refused again', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - await env.db - .update(emailDomains) - .set({ setup_state: { remaining_steps: ['sending_onboarding'] } }) - .where(eq(emailDomains.id, row.id)); - - const stub = stubCustomerCf({ - zones: { 'acme.com': ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { - onboardSending: { - message: 'account is not entitled to Email Sending', - status: 403, - code: 10105, - }, - }, - }); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - const json = (await res.json()) as Record; - // The sync itself succeeded; only the step rides along. - expect(json.status).toBe('active'); - expect(json.setup_state).toEqual({ remaining_steps: ['sending_onboarding'] }); - expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(1); - }); - - it('marks the row failed when the redeploy fails', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - stubCustomerCf({ failOn: { scriptPut: { message: 'quota', status: 400 } } }); - const res = await syncDomain(project.id, 'acme.com', user.jwt); - const json = (await res.json()) as Record; - expect(json.status).toBe('failed'); - expect(json.setup_state).toEqual({ failed_step: 'deploy_relay' }); - expect((await mirrorFor('acme.com'))!.status).toBe('failed'); - }); -}); - -describe('DELETE /projects/:id/email/domains/:domain', () => { - it('removes CF state best-effort, then the mirror key and the row', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true, removed: true }); - // Contract 7 remove shape: catch-all ownership read, the conditional - // reset (drop, disabled) since the read names our relay, then the - // relay DELETE — the enabled rule never outlives its worker. - expect(tags(stub.calls)).toEqual(['catchAllGet', 'catchAll', 'scriptDelete']); - expect(callsByTag(stub.calls, 'catchAll')[0]!.body).toEqual({ - matchers: [{ type: 'all' }], - actions: [{ type: 'drop' }], - enabled: false, - }); - expect(stub.catchAllStates.get(ZONE.id)).toEqual({ enabled: false, workerName: null }); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('keeps the row and mirror when destructive CF cleanup fails, marked for retry', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { - catchAll: { message: 'boom', status: 500 }, - }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - // The reset failed, so the relay DELETE is skipped deliberately — an - // enabled catch-all must never point at a deleted worker, so the rule - // and its relay stay a consistent pair and both steps report failed. - // A failed DESTRUCTIVE step KEEPS the row so the operator can retry. - expect(await res.json()).toEqual({ - ok: false, - removed: false, - failed_steps: ['catch_all', 'delete_relay'], - }); - expect(tags(stub.calls)).toEqual(['catchAllGet', 'catchAll']); - // The row is marked mid-removal; the mirror stays for the proxy. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row.status).toBe('active'); - expect(row.setup_state).toEqual({ - failed_step: 'remove', - removal_failed_steps: ['catch_all', 'delete_relay'], - }); - expect((await mirrorFor('acme.com'))!.status).toBe('active'); - }); - - it('force-removes the row and mirror despite failed destructive cleanup', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { - catchAll: { message: 'boom', status: 500 }, - }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt, { force: true }); - expect(res.status).toBe(200); - // The same destructive failure that KEEPS the row without force is - // overridden — and the response says so. - expect(await res.json()).toEqual({ - ok: true, - removed: true, - forced: true, - failed_steps: ['catch_all', 'delete_relay'], - }); - expect(tags(stub.calls)).toEqual(['catchAllGet', 'catchAll']); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('removes a token_revoked row even when destructive CF cleanup fails', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { status: 'token_revoked' }); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { - catchAll: { message: 'boom', status: 500 }, - }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - // token_revoked rows always delete — keeping buys no retry leverage - // (re-add is the renewal path). `forced` stays absent without ?force=1. - expect(await res.json()).toEqual({ - ok: true, - removed: true, - failed_steps: ['catch_all', 'delete_relay'], - }); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('revokes the grant LAST, with the rotated refresh token, on an oauth_grant remove', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true, removed: true }); - // Refresh first (the CF calls ride the fresh access token), revoke LAST - // — and the revoked token is the ROTATED chain head, since the refresh - // consumed the stored original. - expect(tags(stub.calls)).toEqual([ - 'oauthToken', - 'catchAllGet', - 'catchAll', - 'scriptDelete', - 'oauthRevoke', - ]); - const revocations = callsByTag(stub.calls, 'oauthRevoke'); - expect(revocations).toHaveLength(1); - expect(revocations[0]!.form!.token).toBe('cf-rotated-refresh-dummy-1'); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('serializes a lease refresh behind the removal — the revoke submits the live head', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - - // The removal holds the row lock across the cleanup, so a lease - // refresh fired mid-cleanup cannot interleave: its transaction queues - // behind the removal's and finds the row gone afterwards. Fired - // without awaiting inside the hook — awaiting would deadlock PGlite's - // single connection against the removal's open transaction. - let leaseAttempt: Promise<'refreshed' | unknown> | undefined; - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - on: { - catchAllGet: () => { - leaseAttempt = refreshOauthGrantSerialized(env.db, env, row.id).then( - () => 'refreshed' as const, - (err: unknown) => err, - ); - }, - }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true, removed: true }); - // One rotation (the removal's own); the lease's token call could not - // have interleaved — its transaction had not started yet. - expect(tags(stub.calls)).toEqual([ - 'oauthToken', - 'catchAllGet', - 'catchAll', - 'scriptDelete', - 'oauthRevoke', - ]); - const revocations = callsByTag(stub.calls, 'oauthRevoke'); - expect(revocations).toHaveLength(1); - // The removal's own rotation IS the live head at revoke time — the - // lock makes the round-2 interleaving impossible, so revoking it - // kills the chain. - expect(revocations[0]!.form!.token).toBe('cf-rotated-refresh-dummy-1'); - // The queued refresh ran after the commit and found the row gone. - const leaseOutcome = await leaseAttempt; - expect(leaseOutcome).toBeInstanceOf(Error); - expect(String(leaseOutcome)).toContain('vanished mid-refresh'); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('revokes the replacement credential when a replace commits before the removal lock', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - const row = (await rowFor(project.id, 'acme.com'))!; - - // A replace committing an oauth_grant between the DELETE's entry read - // and its row lock: the removal must clean up with the credential the - // row holds at LOCK time — and revoke that grant — never delete the - // row over a stale api_token snapshot and orphan the grant (the - // replace never invalidates an old api_token, so the stale cleanup - // would have SUCCEEDED). - const realDb = env.db; - const gate = pauseFirstTransaction(realDb); - setTestDb(gate.wrappedDb); - try { - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const reqPromise = Promise.resolve(removeDomain(project.id, 'acme.com', user.jwt)); - const winner = await Promise.race([ - gate.reached.then(() => 'tx' as const), - reqPromise.then(() => 'request' as const), - ]); - if (winner === 'tx') { - // The replace's commit lands while the removal waits for the lock. - const enc = await encryptEmailDomainToken(env, project.id, 'acme.com', REFRESH_TOKEN); - await realDb - .update(emailDomains) - .set({ - credential_kind: 'oauth_grant', - token_ciphertext: enc.ciphertext, - token_iv: enc.iv, - token_key_version: enc.keyVersion, - token_id: null, - token_expires_on: null, - }) - .where(eq(emailDomains.id, row.id)); - gate.release(); - } - const res = await reqPromise; - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true, removed: true }); - // The cleanup ran with the replacement grant — refreshed through - // the row, revoked LAST — not orphaned by the row delete. - expect(tags(stub.calls)).toEqual([ - 'oauthToken', - 'catchAllGet', - 'catchAll', - 'scriptDelete', - 'oauthRevoke', - ]); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - } finally { - setTestDb(realDb); - } - }); - - it('removes an active oauth row whose removal refresh hits invalid_grant — token_revoked lands mid-removal', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - oauth: 'invalid_grant', - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - // invalid_grant persisted token_revoked inside the removal, so the - // destructive failure takes the SAME unconditional-delete path as a - // row revoked before the request — keeping it would strand a stale - // active mirror with status-GET repair suppressed (failed_step - // 'remove'). - expect(await res.json()).toEqual({ - ok: true, - removed: true, - failed_steps: ['delete_relay', 'catch_all'], - }); - // The refresh failed before any customer-zone call, and invalid_grant - // skips the revoke — CF already killed the grant. - expect(tags(stub.calls)).toEqual(['oauthToken']); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('still removes the row when the grant revocation itself fails', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { oauthRevoke: { message: 'boom', status: 500 } }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - // A stranded grant breaks no mail, but it is no longer SILENT: - // revokeOauthGrant throws on the 500, the engine records revoke_grant, - // and the route surfaces it — non-destructive, so removal proceeds. - expect(await res.json()).toEqual({ ok: true, removed: true, failed_steps: ['revoke_grant'] }); - expect(callsByTag(stub.calls, 'oauthRevoke')).toHaveLength(1); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); - - it('leaves a catch-all pointing at another worker untouched', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await addActiveDomain(project.id, user.jwt); - - const stub = stubCustomerCf({ - catchAllRule: { enabled: true, workerName: 'someone-elses-worker' }, - }); - const res = await removeDomain(project.id, 'acme.com', user.jwt); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true, removed: true }); - // The relay is ours to delete; the foreign catch-all is not ours to reset. - expect(tags(stub.calls)).toEqual(['catchAllGet', 'scriptDelete']); - expect(await rowFor(project.id, 'acme.com')).toBeUndefined(); - expect(await mirrorFor('acme.com')).toBeNull(); - }); -}); - -// --------------------------------------------------------------------------- -// POST /internal/email/domain-credential — the proxy's lease -// --------------------------------------------------------------------------- - -describe('POST /internal/email/domain-credential', () => { - it('401s without the internal header and 403s on a bad signature', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - - expect((await leaseCredentialUnsigned('acme.com')).status).toBe(401); - // Signed over a different value than the body carries. - expect((await leaseCredential('acme.com', 'other.com')).status).toBe(403); - }); - - it('404s a domain with no mirror', async () => { - const res = await leaseCredential('unknown.com'); - expect(res.status).toBe(404); - }); - - it('409s a non-active row', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { status: 'pending' }); - - const res = await leaseCredential('acme.com'); - expect(res.status).toBe(409); - }); - - it('leases an api_token verbatim', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { status: 'active' }); - const stub = stubCustomerCf(); - - const res = await leaseCredential('acme.com'); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ kind: 'api_token', token: API_TOKEN }); - // No refresh, no CF calls — the stored token IS the lease. - expect(stub.calls).toEqual([]); - }); - - it('leases an oauth_grant access token and persists the rotation, serialized per row', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - const stub = stubCustomerCf(); - - const first = await leaseCredential('acme.com'); - expect(await first.json()).toEqual({ kind: 'oauth_grant', accessToken: 'cf-access-dummy-1' }); - // The rotated refresh token was persisted atomically with the lease. - let row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe( - 'cf-rotated-refresh-dummy-1', - ); - - // The next lease continues the chain from the row, not from memory. - const second = await leaseCredential('acme.com'); - expect(await second.json()).toEqual({ kind: 'oauth_grant', accessToken: 'cf-access-dummy-2' }); - row = (await rowFor(project.id, 'acme.com'))!; - expect(await decryptEmailDomainToken(env, project.id, 'acme.com', row)).toBe( - 'cf-rotated-refresh-dummy-2', - ); - expect(callsByTag(stub.calls, 'oauthToken').map((call) => call.form!.refresh_token)).toEqual([ - REFRESH_TOKEN, - 'cf-rotated-refresh-dummy-1', - ]); - }); - - it('leases the replacement credential when a replace commits before the refresh lock', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - const row = await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - const stub = stubCustomerCf(); - // The replace commits between the caller's unlocked row read and the - // refresh's lock: the row now holds an API token. - const replacement = await encryptEmailDomainToken(env, project.id, 'acme.com', API_TOKEN); - await env.db - .update(emailDomains) - .set({ - credential_kind: 'api_token', - token_ciphertext: replacement.ciphertext, - token_iv: replacement.iv, - token_key_version: replacement.keyVersion, - }) - .where(eq(emailDomains.id, row.id)); - - // The stale oauth snapshot re-reads and leases what the row NOW - // holds. The grant endpoint never sees the API token — a real one - // would answer invalid_grant and the flip would mark the FRESH - // credential revoked. - const outcome = await leaseEmailDomainCredential(env.db, env, row); - expect(outcome).toEqual({ ok: true, lease: { kind: 'api_token', token: API_TOKEN } }); - expect(callsByTag(stub.calls, 'oauthToken')).toEqual([]); - expect((await rowFor(project.id, 'acme.com'))!.status).toBe('active'); - }); - - it('maps invalid_grant at lease time to token_revoked, persisted and mirrored', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - stubCustomerCf({ oauth: 'invalid_grant' }); - - const res = await leaseCredential('acme.com'); - expect(res.status).toBe(403); - expect((await rowFor(project.id, 'acme.com'))!.status).toBe('token_revoked'); - expect((await mirrorFor('acme.com'))!.status).toBe('token_revoked'); - // The lease failure never carries credential material. - const body = await res.text(); - expect(body).not.toContain(REFRESH_TOKEN); - }); - - it('fences the revoked mirror write against a replace that committed first', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - const oldHash = (await mirrorFor('acme.com'))!.relaySecretSha256; - - // A's refresh gets invalid_grant (committing token_revoked); B's - // api_token replace + sync never touches the OAuth token endpoint, so - // one stub covers both requests. - stubCustomerCf({ zones: { 'acme.com': ZONE }, oauth: 'invalid_grant' }); - - // Park the lease route's SECOND transaction — the fenced mirror write — - // so B's replace commits and publishes its active mirror in between. - const realDb = env.db; - const gate = pauseNthTransaction(realDb, 2); - setTestDb(gate.wrappedDb); - try { - const reqPromise = leaseCredential('acme.com'); - const parked = await Promise.race([ - gate.reached.then(() => 'parked' as const), - reqPromise.then(() => 'settled' as const), - ]); - // The mirror write must be a transaction of its own: unfenced, the - // request settles without one and its stale write can land last. - expect(parked).toBe('parked'); - - try { - const replaceRes = await addDomain(project.id, user.jwt, { - domain: 'acme.com', - apiToken: API_TOKEN_REPLACEMENT, - }); - expect(replaceRes.status).toBe(200); - } finally { - gate.release(); - } - - // The caller's answer is unchanged: the grant the lease refreshed - // was revoked, even though the row has since been replaced. - const res = await reqPromise; - expect(res.status).toBe(403); - - // The replacement's under-lock publication is authoritative: no - // token_revoked write with the pre-rotation hash landed after it. - const row = (await rowFor(project.id, 'acme.com'))!; - expect(row.status).toBe('active'); - const mirror = (await mirrorFor('acme.com'))!; - expect(mirror.status).toBe('active'); - expect(mirror.relaySecretSha256).toBe( - await hashEmailRelaySecret( - await decryptEmailDomainRelaySecret(env, project.id, 'acme.com', row), - ), - ); - expect(mirror.relaySecretSha256).not.toBe(oldHash); - } finally { - setTestDb(realDb); - } - }); - - it('502s a transient OAuth failure without touching the row status', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedEmailDomain(project.id, 'acme.com', { - status: 'active', - credentialKind: 'oauth_grant', - credential: REFRESH_TOKEN, - }); - stubCustomerCf({ oauth: 'server_error' }); - - const res = await leaseCredential('acme.com'); - expect(res.status).toBe(502); - expect((await rowFor(project.id, 'acme.com'))!.status).toBe('active'); + expect(unsigned.status).toBe(403); + const list = await call(project.id, other.jwt, 'GET', '/domains'); + expect(list.status).toBe(403); }); }); diff --git a/platform/packages/api/test/integration/api-email.test.ts b/platform/packages/api/test/integration/api-email.test.ts index edd2a696f..e0ec179a8 100644 --- a/platform/packages/api/test/integration/api-email.test.ts +++ b/platform/packages/api/test/integration/api-email.test.ts @@ -40,6 +40,12 @@ import { import { signConfirmToken } from '../../src/auth/confirm-token.ts'; import { revokeOwnerVerifiedDestinationsForUserChange } from '../../src/db.ts'; import * as dbModule from '../../src/db.ts'; +import { emailMonthlyUsage } from '../../src/email/admission-schema.ts'; +import { + recordEmailReceipt, + setProjectEmailLimits, + setProjectEmailSuspended, +} from '../../src/email/admission.ts'; import { hashSendContent, PLATFORM_INTERNAL_EMAIL_SENTINEL, @@ -1137,92 +1143,6 @@ describe('email-allowlist KV sync', () => { expect(await readAllowlist(project.id)).toEqual(['keep@example.com']); }); - it('tightens the mirror while the revoked row is still present', async () => { - // Ordering is the whole point. The mirror is what the proxy enforces, and - // the row is what a retry would re-derive that mirror from. So the write - // lands FIRST, and it must already EXCLUDE the row being revoked — - // `getVerifiedEmailDestinationsByProjectId` still returns it at that - // moment, so a plain re-sync would write the revoked address straight back. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedVerifiedPair(project.id); - - const observed: Array<{ written: Array | null; rowIds: Array }> = []; - observeAllowlistWrites(project.id, async (written) => { - const rows = await rowsFor(project.id); - observed.push({ written, rowIds: rows.map((r) => r.id).sort() }); - }); - - mockCfApi(); - const res = await removeDestination(project.id, 'edst_v2', user.jwt); - expect(res.status).toBe(200); - - // Two writes. The tighten lands while BOTH rows are still present and - // already excludes the revoked one; the re-derive after the delete sees - // the row gone and agrees. - expect(observed).toEqual([ - { written: ['keep@example.com'], rowIds: ['edst_v1', 'edst_v2'] }, - { written: ['keep@example.com'], rowIds: ['edst_v1'] }, - ]); - expect(await readAllowlist(project.id)).toEqual(['keep@example.com']); - expect(await rowsFor(project.id)).toHaveLength(1); - }); - - it('keeps the row and fails the revoke when the mirror write fails', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedVerifiedPair(project.id); - breakAllowlistWrites(project.id); - - const fetchMock = mockCfApi(); - const res = await removeDestination(project.id, 'edst_v2', user.jwt); - - // Non-2xx, and nothing destructive ran: DELETE stays retryable. Dropping - // the row first and swallowing the KV error would strand - // `gone@example.com` in the allowlist forever — no row left for a retry - // to re-derive the mirror from, so the proxy keeps delivering to a - // revoked recipient. - expect(res.status).toBe(503); - expect((await rowsFor(project.id)).map((r) => r.id).sort()).toEqual(['edst_v1', 'edst_v2']); - expect(await readAllowlist(project.id)).toEqual(['keep@example.com', 'gone@example.com']); - expect(cfCalls(fetchMock, 'DELETE', '/email/routing/addresses/')).toHaveLength(0); - }); - - it('keeps the row when clearing the last address fails', async () => { - // Same inversion on the delete-on-empty branch of the mirror sync. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.insert(emailDestinations).values({ - id: 'edst_v1', - project_id: project.id, - address: 'only@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-only', - verified_at: '2026-04-29T00:00:00Z', - }); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['only@example.com'])); - breakAllowlistWrites(project.id); - - mockCfApi(); - const res = await removeDestination(project.id, 'edst_v1', user.jwt); - - expect(res.status).toBe(503); - expect(await rowsFor(project.id)).toHaveLength(1); - expect(await readAllowlist(project.id)).toEqual(['only@example.com']); - }); - - // ------------------------------------------------------------------------- - // Self-heal: the listing repairs a mirror a best-effort write lost. - // - // `syncProjectAllowlistKvBestEffort` swallows a KV failure that lands AFTER - // Postgres already committed `verified`, and nothing else re-derives the - // key — the confirm route early-returns on an already-verified row, the - // hourly `scheduled()` backfill touches only `email-slug:`, and no deploy - // hook calls the sync. The proxy reads a missing key as deny-all, so the - // owner is left looking at a `verified` destination that every send - // rejects as unverified, with no user-visible cause. - // ------------------------------------------------------------------------- - it('repairs a mirror a swallowed write left empty, on the next listing', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); @@ -1414,167 +1334,8 @@ describe('email-allowlist KV sync', () => { env, ); } - - it('does not let a confirm click that lands mid-revoke outlive the deleted row', async () => { - const { projectId, jwt, token } = await seedRevokeVsConfirm(); - expect(await env.ROUTING.get(`email-allowlist:${projectId}`)).toBeNull(); - - // Park the revoke AFTER its row snapshot (`pending`) and BEFORE its row - // delete — the reference count is the first thing it awaits past the - // snapshot, and it sits next to the upstream Cloudflare call, the widest - // window in the route. Run the click to completion in there. - const original = dbModule.countProjectsUsingDestination; - let clicked = false; - vi.spyOn(dbModule, 'countProjectsUsingDestination').mockImplementation(async (db, tag) => { - if (!clicked) { - clicked = true; - const res = await confirmClick(token); - expect(res.status).toBe(200); - // The click flipped the row and derived the mirror from it. - expect(await readAllowlist(projectId)).toEqual(['shared@example.com']); - } - return original(db, tag); - }); - - const fetchMock = mockCfApi(); - const res = await removeDestination(projectId, 'edst_pend', jwt); - expect(res.status).toBe(200); - expect(clicked).toBe(true); - - // The row is gone, the shared Cloudflare address was (correctly) kept for - // the sibling — and the mirror must not keep granting the address. - expect(await rowsFor(projectId)).toHaveLength(0); - expect(cfCalls(fetchMock, 'DELETE', '/email/routing/addresses/')).toHaveLength(0); - expect(await readAllowlist(projectId)).toEqual([]); - }); - - it('does not let a sibling row confirmed mid-revoke write the revoked address back', async () => { - // Same window, other row. The snapshot says `verified`, so the tighten - // ran and excluded this row — but a click on ANOTHER row of the project - // re-derives the whole mirror from rows that still include this one, - // because the delete has not happened yet. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.insert(emailDestinations).values([ - { - id: 'edst_gone', - project_id: project.id, - address: 'gone@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-gone', - verified_at: '2026-04-29T00:00:00Z', - }, - { - id: 'edst_other', - project_id: project.id, - address: 'other@example.com', - status: 'pending', - cf_destination_id: 'cf-tag-other', - verified_at: null, - verification_source: 'platform', - }, - ]); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['gone@example.com'])); - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken( - { - v: 1, - pid: project.id, - did: 'edst_other', - addr: 'other@example.com', - iat: now, - exp: now + 24 * 60 * 60, - }, - env.JWT_SECRET, - ); - - const original = dbModule.countProjectsUsingDestination; - let clicked = false; - vi.spyOn(dbModule, 'countProjectsUsingDestination').mockImplementation(async (db, tag) => { - if (!clicked) { - clicked = true; - // The tighten already ran: the mirror no longer grants the revoked row. - expect(await readAllowlist(project.id)).toEqual([]); - expect((await confirmClick(token)).status).toBe(200); - // ...and the sibling's click just wrote it back. - expect((await readAllowlist(project.id)).sort()).toEqual([ - 'gone@example.com', - 'other@example.com', - ]); - } - return original(db, tag); - }); - - mockCfApi(); - expect((await removeDestination(project.id, 'edst_gone', user.jwt)).status).toBe(200); - expect(clicked).toBe(true); - expect((await rowsFor(project.id)).map((r) => r.id)).toEqual(['edst_other']); - expect(await readAllowlist(project.id)).toEqual(['other@example.com']); - }); - - it('heals a click whose mirror write lands after the revoke, on the next listing', async () => { - // The residual. Postgres and KV are written separately and KV has no - // compare-and-swap, so a click that derived its mirror while the row was - // still verified can land its write AFTER the revoke's own. Pinned here - // so the bound is explicit: the grant is stale until this project's next - // listing, which re-derives the mirror from the rows and drops it. - const { projectId, jwt, token } = await seedRevokeVsConfirm(); - const key = `email-allowlist:${projectId}`; - - // Hold the click's mirror write (the only write that grants the address) - // until the revoke has finished everything it does. - const originalPut = env.ROUTING.put.bind(env.ROUTING); - let releasePut!: () => void; - const putReleased = new Promise((resolve) => { - releasePut = resolve; - }); - let putStarted!: () => void; - const putHeld = new Promise((resolve) => { - putStarted = resolve; - }); - vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( - k: string, - value: string | ArrayBuffer | ArrayBufferView | ReadableStream, - options?: KVNamespacePutOptions, - ) => { - if (k === key && String(value).includes('shared@example.com')) { - putStarted(); - await putReleased; - } - return originalPut(k, value as never, options as never); - }) as typeof env.ROUTING.put); - - const original = dbModule.countProjectsUsingDestination; - let click: Promise | null = null; - vi.spyOn(dbModule, 'countProjectsUsingDestination').mockImplementation(async (db, tag) => { - if (!click) { - click = confirmClick(token); - await putHeld; - } - return original(db, tag); - }); - - mockCfApi(); - const res = await removeDestination(projectId, 'edst_pend', jwt); - expect(res.status).toBe(200); - expect(await rowsFor(projectId)).toHaveLength(0); - - releasePut(); - expect((await click!).status).toBe(200); - // Lost update: the click's write was last, and no row backs it. - expect(await readAllowlist(projectId)).toEqual(['shared@example.com']); - - vi.restoreAllMocks(); - mockCfApi(); - expect((await listDestinations(projectId, jwt)).status).toBe(200); - expect(await readAllowlist(projectId)).toEqual([]); - }); }); -// --------------------------------------------------------------------------- -// Per-project verification: Option C (inherit) vs Option B (re-verify) -// --------------------------------------------------------------------------- - describe('per-project verification (Option C + Option B)', () => { it("Option C: the owner's own CF-verified address is inherited, with no platform email", async () => { const user = await createTestUser(env.db); @@ -2553,14 +2314,22 @@ describe('GET /projects/:id/email/usage', () => { }); }); - it('reads the month counters, the per-project limit override, and the suspend flag', async () => { + it('reads the PostgreSQL month counter, limit override, and suspend flag', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); const month = monthBucket(); - await env.ROUTING.put(`email-sent:${project.id}:${month}`, '7'); - await env.ROUTING.put(`email-recv:${project.id}:${month}`, '3'); - await env.ROUTING.put(`email-limit:${project.id}`, '50'); - await env.ROUTING.put(`email-suspended:${project.id}`, '1'); + await env.db + .insert(emailMonthlyUsage) + .values({ project_id: project.id, month, recipient_attempts: 7 }); + for (let n = 0; n < 3; n++) { + await recordEmailReceipt(env.db, { + receiptId: `receipt_${n}`, + projectId: project.id, + status: 'received', + }); + } + await setProjectEmailLimits(env.db, project.id, { monthly: 50 }); + await setProjectEmailSuspended(env.db, project.id, true); const res = await usage(project.id, user.jwt); expect(res.status).toBe(200); @@ -2591,10 +2360,12 @@ describe('GET /projects/:id/email/usage', () => { expect(body.remaining).toBe(200); }); - it('clamps remaining at zero once the limit is exceeded', async () => { + it('clamps remaining at zero once PostgreSQL usage exceeds the limit', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); - await env.ROUTING.put(`email-sent:${project.id}:${monthBucket()}`, '500'); + await env.db + .insert(emailMonthlyUsage) + .values({ project_id: project.id, month: monthBucket(), recipient_attempts: 500 }); const body = (await (await usage(project.id, user.jwt)).json()) as { remaining: number }; expect(body.remaining).toBe(0); @@ -2632,17 +2403,14 @@ describe('GET /projects/:id/email/logs', () => { expect((await logs(project.id, intruder.jwt)).status).toBe(403); }); - it('returns an empty list marked pending until AE-backed storage is wired', async () => { + it('returns an empty durable ledger for a project with no email activity', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); const res = await logs(project.id, user.jwt); expect(res.status).toBe(200); - const body = (await res.json()) as { logs: Array; pending: boolean }; + const body = (await res.json()) as { logs: Array }; expect(body.logs).toEqual([]); - // The marker is the contract consumers branch on — dropping it would - // make "no logs yet" indistinguishable from "this project sent none". - expect(body.pending).toBe(true); }); }); diff --git a/platform/packages/api/test/integration/email-admission.test.ts b/platform/packages/api/test/integration/email-admission.test.ts new file mode 100644 index 000000000..b475c0fb1 --- /dev/null +++ b/platform/packages/api/test/integration/email-admission.test.ts @@ -0,0 +1,340 @@ +import { eq } from 'drizzle-orm'; +import { beforeAll, afterAll, beforeEach, describe, expect, it } from 'vite-plus/test'; +import { deleteEmailDestination } from '../../src/db.ts'; +import { emailUnresolvedAttempts } from '../../src/email/admission-schema.ts'; +import { + admitEmailAction, + claimRelayedEmailReceipt, + completeRelayedEmailReceipt, + recordEmailReceipt, + drainProjectEmailAdmissions, + EmailAdmissionError, + getProjectEmailLogs, + getProjectEmailUsage, + pruneEmailActionHistory, + setProjectEmailLimits, + setProjectEmailSuspended, + transitionEmailRecipients, +} from '../../src/email/admission.ts'; +import { setEmailRecipientPolicy } from '../../src/email/settings.ts'; +import { emailDestinations, projects } from '../../src/schema.ts'; +import { + clearTables, + createTestProject, + createTestUser, + setupEnv, + teardownEnv, + type TestEnv, +} from './helpers.ts'; + +let env: TestEnv; +beforeAll(async () => { + env = await setupEnv(); +}); +afterAll(async () => { + await teardownEnv(); +}); +beforeEach(async () => { + await clearTables(env.db); +}); + +async function fixture() { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'acme'); + await env.db.insert(emailDestinations).values({ + id: `dest_${project.id}`, + project_id: project.id, + address: 'one@example.com', + status: 'verified', + }); + await env.db.insert(emailDestinations).values({ + id: `dest2_${project.id}`, + project_id: project.id, + address: 'two@example.com', + status: 'verified', + }); + return project; +} + +function input(projectId: string, key: string, recipients = ['one@example.com']) { + return { + projectId, + kind: 'direct' as const, + key, + digest: 'a'.repeat(64), + from: 'acme+news@mail.example.com', + recipients, + transport: 'binding' as const, + sharedSenderDomain: 'mail.example.com', + }; +} + +describe('authoritative email admission', () => { + it('claims a relay invocation once and replays its completed outcome without rerunning it', async () => { + const project = await fixture(); + const identity = { + receiptId: 'a'.repeat(64), + projectId: project.id, + payloadDigest: 'b'.repeat(64), + }; + const claims = await Promise.all( + Array.from({ length: 3 }, () => claimRelayedEmailReceipt(env.db, identity)), + ); + expect(claims.filter((claim) => claim.state === 'claimed')).toHaveLength(1); + expect(claims.filter((claim) => claim.state === 'in_progress')).toHaveLength(2); + await expect( + completeRelayedEmailReceipt(env.db, { ...identity, reject: false }), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + await recordEmailReceipt(env.db, { + receiptId: identity.receiptId, + projectId: project.id, + status: 'handler_completed', + }); + await completeRelayedEmailReceipt(env.db, { ...identity, reject: false }); + expect(await claimRelayedEmailReceipt(env.db, identity)).toEqual({ + state: 'completed', + reject: false, + }); + await expect( + claimRelayedEmailReceipt(env.db, { ...identity, payloadDigest: 'c'.repeat(64) }), + ).rejects.toMatchObject({ code: 'CONFLICT' }); + await expect( + completeRelayedEmailReceipt(env.db, { ...identity, reject: true }), + ).rejects.toMatchObject({ code: 'CONFLICT' }); + }); + it('fences new starts during deletion, cancels only reserved work, and retains the audit after deletion', async () => { + const project = await fixture(); + const reserved = await admitEmailAction(env.db, input(project.id, 'reserved')); + const started = await admitEmailAction( + env.db, + input(project.id, 'started', ['two@example.com']), + ); + await transitionEmailRecipients( + env.db, + started.operationId, + ['two@example.com'], + 'attempt_started', + ); + await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); + await expect( + transitionEmailRecipients( + env.db, + reserved.operationId, + ['one@example.com'], + 'attempt_started', + ), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect(await drainProjectEmailAdmissions(env.db, project.id)).toEqual({ + cancelled: 1, + inFlight: 1, + }); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + await transitionEmailRecipients( + env.db, + started.operationId, + ['two@example.com'], + 'outcome_unknown', + ); + expect(await drainProjectEmailAdmissions(env.db, project.id)).toEqual({ + cancelled: 0, + inFlight: 0, + }); + await env.db.delete(projects).where(eq(projects.id, project.id)); + const logs = await getProjectEmailLogs(env.db, project.id); + expect(logs.logs).toEqual( + expect.arrayContaining([ + expect.objectContaining({ operationId: reserved.operationId, status: 'cancelled' }), + expect.objectContaining({ operationId: started.operationId, status: 'outcome_unknown' }), + ]), + ); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + }); + + it('expires completed unknown metadata but retains a PII-free active-attempt fence', async () => { + const project = await fixture(); + const active = await admitEmailAction(env.db, input(project.id, 'active')); + const uncertain = await admitEmailAction( + env.db, + input(project.id, 'uncertain', ['two@example.com']), + ); + await transitionEmailRecipients( + env.db, + active.operationId, + ['one@example.com'], + 'attempt_started', + ); + await transitionEmailRecipients( + env.db, + uncertain.operationId, + ['two@example.com'], + 'attempt_started', + ); + await transitionEmailRecipients( + env.db, + uncertain.operationId, + ['two@example.com'], + 'outcome_unknown', + ); + await pruneEmailActionHistory(env.db, new Date(Date.now() + 60_000)); + expect((await getProjectEmailLogs(env.db, project.id)).logs).toHaveLength(0); + const tombstones = await env.db.select().from(emailUnresolvedAttempts); + expect(tombstones).toHaveLength(1); + expect(tombstones[0]).toMatchObject({ + project_id: project.id, + sender_domain: 'mail.example.com', + }); + expect(JSON.stringify(tombstones)).not.toContain('one@example.com'); + await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); + expect(await drainProjectEmailAdmissions(env.db, project.id)).toEqual({ + cancelled: 0, + inFlight: 1, + }); + }); + + it('replays one operation without a second quota debit and conflicts on changed payload', async () => { + const project = await fixture(); + const first = await admitEmailAction(env.db, input(project.id, 'same')); + expect(first.replay).toBe(false); + expect(first.recipients[0]?.state).toBe('reserved'); + const again = await admitEmailAction(env.db, input(project.id, 'same')); + expect(again.operationId).toBe(first.operationId); + expect(again.replay).toBe(true); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + await expect( + admitEmailAction(env.db, { ...input(project.id, 'same'), digest: 'b'.repeat(64) }), + ).rejects.toMatchObject({ code: 'CONFLICT' } satisfies Partial); + }); + + it('admits a partial batch under atomic recipient quotas and keeps charges after uncertain outcomes', async () => { + const project = await fixture(); + await setProjectEmailLimits(env.db, project.id, { burst: 1, monthly: 1 }); + const result = await admitEmailAction( + env.db, + input(project.id, 'batch', ['one@example.com', 'two@example.com', 'one@example.com']), + ); + expect(result.recipients).toHaveLength(2); + expect(Object.fromEntries(result.recipients.map((r) => [r.recipient, r.state]))).toEqual({ + 'one@example.com': 'reserved', + 'two@example.com': 'rejected', + }); + await transitionEmailRecipients( + env.db, + result.operationId, + ['one@example.com'], + 'attempt_started', + ); + await transitionEmailRecipients( + env.db, + result.operationId, + ['one@example.com'], + 'outcome_unknown', + { errorCode: 'OUTCOME_UNKNOWN' }, + ); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + const replay = await admitEmailAction( + env.db, + input(project.id, 'batch', ['one@example.com', 'two@example.com']), + ); + expect(replay.recipients.find((r) => r.recipient === 'one@example.com')?.state).toBe( + 'outcome_unknown', + ); + await expect( + transitionEmailRecipients(env.db, result.operationId, ['one@example.com'], 'attempt_started'), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + }); + + it('rejects new attempts after suspension and keeps a rejection in the ledger', async () => { + const project = await fixture(); + await setProjectEmailSuspended(env.db, project.id, true); + const result = await admitEmailAction(env.db, input(project.id, 'blocked')); + expect(result.recipients[0]).toMatchObject({ state: 'rejected', errorCode: 'SUSPENDED' }); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(0); + }); + + it('applies a tightened policy and revoked consent on the next operation', async () => { + const project = await fixture(); + const kv = { put: async () => {}, get: async () => null } as unknown as KVNamespace; + await setEmailRecipientPolicy(env.db, kv, { mode: 'any', domains: [] }); + const open = await admitEmailAction(env.db, input(project.id, 'open', ['new@example.net'])); + expect(open.recipients[0]?.state).toBe('reserved'); + await setEmailRecipientPolicy(env.db, kv, { mode: 'verified', domains: [] }); + await deleteEmailDestination(env.db, `dest_${project.id}`); + const closed = await admitEmailAction( + env.db, + input(project.id, 'closed', ['one@example.com', 'new@example.net']), + ); + expect(closed.recipients.map((r) => r.state)).toEqual(['rejected', 'rejected']); + expect(closed.recipients.every((r) => r.errorCode === 'UNVERIFIED_DESTINATION')).toBe(true); + }); + + it('holds monthly quota after 30-day metadata pruning and clears it at month boundary', async () => { + const project = await fixture(); + await setProjectEmailLimits(env.db, project.id, { monthly: 1, burst: 10 }); + const first = await admitEmailAction(env.db, input(project.id, 'first')); + await transitionEmailRecipients( + env.db, + first.operationId, + ['one@example.com'], + 'attempt_started', + ); + await transitionEmailRecipients( + env.db, + first.operationId, + ['one@example.com'], + 'provider_accepted', + ); + await pruneEmailActionHistory(env.db, new Date(Date.now() + 60_000)); + expect((await getProjectEmailLogs(env.db, project.id)).logs).toHaveLength(0); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + const second = await admitEmailAction(env.db, input(project.id, 'second')); + expect(second.recipients[0]).toMatchObject({ state: 'rejected', errorCode: 'QUOTA_EXCEEDED' }); + expect(first.operationId).not.toBe(second.operationId); + }); + + it('refunds only cancelled reservations and never restarts an uncertain attempt', async () => { + const project = await fixture(); + const first = await admitEmailAction(env.db, input(project.id, 'cancel')); + await transitionEmailRecipients(env.db, first.operationId, ['one@example.com'], 'cancelled'); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(0); + await expect( + transitionEmailRecipients(env.db, first.operationId, ['one@example.com'], 'attempt_started'), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + const second = await admitEmailAction(env.db, input(project.id, 'uncertain')); + await transitionEmailRecipients( + env.db, + second.operationId, + ['one@example.com'], + 'attempt_started', + ); + await transitionEmailRecipients( + env.db, + second.operationId, + ['one@example.com'], + 'outcome_unknown', + ); + expect( + (await admitEmailAction(env.db, input(project.id, 'uncertain'))).recipients[0]?.state, + ).toBe('outcome_unknown'); + await expect( + transitionEmailRecipients(env.db, second.operationId, ['one@example.com'], 'cancelled'), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + }); + + it('enforces direct caller bounds at the authoritative API', async () => { + const project = await fixture(); + await expect( + admitEmailAction(env.db, input(project.id, 'x'.repeat(129))), + ).rejects.toMatchObject({ code: 'INVALID_REQUEST' }); + await expect( + admitEmailAction( + env.db, + input( + project.id, + 'many', + Array.from({ length: 51 }, (_, n) => `user${n}@example.com`), + ), + ), + ).rejects.toMatchObject({ code: 'INVALID_REQUEST' }); + }); +}); diff --git a/platform/packages/api/test/integration/email-connections.test.ts b/platform/packages/api/test/integration/email-connections.test.ts new file mode 100644 index 000000000..cfd195b71 --- /dev/null +++ b/platform/packages/api/test/integration/email-connections.test.ts @@ -0,0 +1,644 @@ +import { eq } from 'drizzle-orm'; +import { + afterAll, + afterEach, + beforeAll, + beforeEach, + describe, + expect, + it, + vi, +} from 'vite-plus/test'; +import { emailUnresolvedAttempts } from '../../src/email/admission-schema.ts'; +import { disableEmailDomainRouteAndDrain } from '../../src/email/admission.ts'; +import { + emailDomainRoutes, + emailOperationSteps, + emailOperations, + emailZoneConnections, +} from '../../src/email/connection-schema.ts'; +import { + ensureSharedEmailConnection, + reconcilePendingEmailOperations, + requestEmailDomainAdd, + requestEmailDomainRemove, + requestEmailDomainSync, + requestEmailSecretRotation, + resolveEmailDomain, + resolveEmailIngress, + runEmailOperation, +} from '../../src/email/connection-service.ts'; +import type { ApiEnv } from '../../src/env.ts'; +import { projects } from '../../src/schema.ts'; +import { callsByTag, stubCustomerCf } from './email-domain-cf-stub.ts'; +import { + clearTables, + createTestProject, + createTestUser, + setupEnv, + teardownEnv, + type TestEnv, +} from './helpers.ts'; + +const zones = { + 'example.com': { id: 'zone-example', name: 'example.com', accountId: 'customer-account' }, +}; +const TOKEN = 'customer-scoped-token'; +let env: TestEnv; +function bindings(): ApiEnv['Bindings'] { + return { + ...env, + EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test', + } as unknown as ApiEnv['Bindings']; +} + +beforeAll(async () => { + env = await setupEnv(); +}); +afterAll(async () => { + await teardownEnv(); +}); +beforeEach(async () => { + await clearTables(env.db); +}); +afterEach(() => { + vi.restoreAllMocks(); + vi.unstubAllGlobals(); +}); + +describe('durable zone email connections', () => { + it('persists removal behind an unknown setup and resumes after project deletion', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'remove-unknown'); + const failures: { scriptPut?: { message: string; status: number } } = { + scriptPut: { message: 'lost response', status: 504 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'unknown.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0]?.status, + ).toBe('unknown'); + const remove = await requestEmailDomainRemove(env.db, bindings(), add.routeId, { + kind: 'system', + }); + expect((await resolveEmailDomain(env.db, 'unknown.example.com'))?.route.desired_state).toBe( + 'disabled', + ); + await runEmailOperation(env.db, bindings(), remove); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + await env.db.delete(projects).where(eq(projects.id, project.id)); + delete failures.scriptPut; + await reconcilePendingEmailOperations(env.db, bindings()); + await reconcilePendingEmailOperations(env.db, bindings()); + // The failed upload cannot be proved by readback, so the removal stays + // durably queued instead of replaying or deleting a possibly live relay. + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] + ?.status, + ).toBe('pending'); + expect((await resolveEmailDomain(env.db, 'unknown.example.com'))?.route.desired_state).toBe( + 'disabled', + ); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(1); + }); + + it('runs a persisted system removal after its project row is gone', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'removed-owner'); + stubCustomerCf({ zones }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'gone.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + await env.db.delete(projects).where(eq(projects.id, project.id)); + const remove = await requestEmailDomainRemove(env.db, bindings(), add.routeId, { + kind: 'system', + }); + await runEmailOperation(env.db, bindings(), remove); + expect((await resolveEmailDomain(env.db, 'gone.example.com'))?.route.desired_state).toBe( + 'removed', + ); + }); + + it('keeps ingress while a disabled sibling still owns the connection', async () => { + const user = await createTestUser(env.db); + const first = await createTestProject(env.db, user.id, 'disabled-first'); + const second = await createTestProject(env.db, user.id, 'disabled-second'); + const stub = stubCustomerCf({ zones }); + const a = await requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'one.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), a.operationId); + const b = await requestEmailDomainAdd(env.db, bindings(), { + projectId: second.id, + domain: 'two.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), b.operationId); + await env.db + .update(emailDomainRoutes) + .set({ desired_state: 'disabled', inbound_status: 'disabled' }) + .where(eq(emailDomainRoutes.id, b.routeId)); + const remove = await requestEmailDomainRemove(env.db, bindings(), a.routeId, { + kind: 'owner', + userId: user.id, + }); + await runEmailOperation(env.db, bindings(), remove); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + expect((await resolveEmailDomain(env.db, 'two.example.com'))?.route.desired_state).toBe( + 'disabled', + ); + }); + + it('defers destructive removal while an admitted provider attempt is live', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'active-send'); + const stub = stubCustomerCf({ zones }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'active.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + await env.db.insert(emailUnresolvedAttempts).values({ + id: 'live-provider-test', + project_id: project.id, + sender_domain: 'active.example.com', + started_at: new Date().toISOString(), + }); + const remove = await requestEmailDomainRemove(env.db, bindings(), add.routeId, { + kind: 'owner', + userId: user.id, + }); + await runEmailOperation(env.db, bindings(), remove); + expect((await resolveEmailDomain(env.db, 'active.example.com'))?.route.desired_state).toBe( + 'disabled', + ); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + expect(['pending', 'running']).toContain( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] + ?.status, + ); + await env.db + .delete(emailUnresolvedAttempts) + .where(eq(emailUnresolvedAttempts.id, 'live-provider-test')); + await runEmailOperation(env.db, bindings(), remove); + expect((await resolveEmailDomain(env.db, 'active.example.com'))?.route.desired_state).toBe( + 'removed', + ); + }); + + it('serializes two sibling removals behind an unresolved connection write', async () => { + const user = await createTestUser(env.db); + const aProject = await createTestProject(env.db, user.id, 'queued-a'); + const bProject = await createTestProject(env.db, user.id, 'queued-b'); + stubCustomerCf({ zones }); + const a = await requestEmailDomainAdd(env.db, bindings(), { + projectId: aProject.id, + domain: 'queue-a.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), a.operationId); + const b = await requestEmailDomainAdd(env.db, bindings(), { + projectId: bProject.id, + domain: 'queue-b.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), b.operationId); + await env.db + .update(emailOperations) + .set({ status: 'unknown' }) + .where(eq(emailOperations.id, b.operationId)); + const removeA = await requestEmailDomainRemove(env.db, bindings(), a.routeId, { + kind: 'system', + }); + const removeB = await requestEmailDomainRemove(env.db, bindings(), b.routeId, { + kind: 'system', + }); + const queuedB = ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, removeB)) + )[0]!; + expect(queuedB.current_step).toBe(`wait:${removeA}`); + await runEmailOperation(env.db, bindings(), removeA); + await runEmailOperation(env.db, bindings(), removeB); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, removeB)))[0] + ?.status, + ).toBe('pending'); + // Represent an operator-proven resolution of the earlier ambiguous write. + await env.db + .update(emailOperations) + .set({ status: 'completed' }) + .where(eq(emailOperations.id, b.operationId)); + await runEmailOperation(env.db, bindings(), removeA); + await runEmailOperation(env.db, bindings(), removeB); + expect((await resolveEmailDomain(env.db, 'queue-a.example.com'))?.route.desired_state).toBe( + 'removed', + ); + expect((await resolveEmailDomain(env.db, 'queue-b.example.com'))?.route.desired_state).toBe( + 'removed', + ); + }); + it('shares one ingress across exact sibling routes and retains it on one removal', async () => { + const user = await createTestUser(env.db); + const first = await createTestProject(env.db, user.id, 'first-mail'); + const second = await createTestProject(env.db, user.id, 'second-mail'); + const stub = stubCustomerCf({ zones }); + const a = await requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'hr.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + attemptId: 'first-attempt', + }); + await runEmailOperation(env.db, bindings(), a.operationId); + const aOp = ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, a.operationId)) + )[0]!; + expect(aOp.status).toBe('completed'); + const b = await requestEmailDomainAdd(env.db, bindings(), { + projectId: second.id, + domain: 'support.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + attemptId: 'second-attempt', + }); + await runEmailOperation(env.db, bindings(), b.operationId); + const [aRoute, bRoute, connections] = await Promise.all([ + resolveEmailDomain(env.db, 'hr.example.com'), + resolveEmailDomain(env.db, 'support.example.com'), + env.db.select().from(emailZoneConnections), + ]); + expect(connections).toHaveLength(1); + expect(aRoute?.connection.id).toBe(bRoute?.connection.id); + expect(aRoute?.route.project_id).toBe(first.id); + expect(bRoute?.route.project_id).toBe(second.id); + expect(aRoute?.route.outbound_status).toBe('ready'); + expect(bRoute?.route.outbound_status).toBe('ready'); + expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(2); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(1); + const removed = await requestEmailDomainRemove(env.db, bindings(), a.routeId, { + kind: 'owner', + userId: user.id, + }); + await runEmailOperation(env.db, bindings(), removed); + expect((await resolveEmailDomain(env.db, 'hr.example.com'))?.route.desired_state).toBe( + 'removed', + ); + expect((await resolveEmailDomain(env.db, 'support.example.com'))?.route.inbound_status).toBe( + 'ready', + ); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + }); + + it('commits step intent before provider writes and fences an ambiguous result', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'uncertain-mail'); + let observedIntent = false; + const stub = stubCustomerCf({ + zones, + on: { + scriptPut: async () => { + const steps = await env.db.select().from(emailOperationSteps); + observedIntent = steps.some( + (step) => step.kind === 'ingress_deploy' && step.status === 'in_flight', + ); + }, + }, + failOn: { scriptPut: { message: 'upstream timeout', status: 504 } }, + }); + const requested = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'alerts.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + attemptId: 'stable-key', + }); + await runEmailOperation(env.db, bindings(), requested.operationId); + const op = ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, requested.operationId)) + )[0]!; + expect(observedIntent).toBe(true); + expect(op.status).toBe('unknown'); + const writes = callsByTag(stub.calls, 'scriptPut').length; + await reconcilePendingEmailOperations(env.db, bindings()); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(writes); + const replay = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'alerts.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + attemptId: 'stable-key', + }); + expect(replay.operationId).toBe(requested.operationId); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'alerts.example.com', + actor: { kind: 'owner', userId: user.id }, + token: 'different-token', + attemptId: 'stable-key', + }), + ).rejects.toThrow('reused'); + }); + + it('does not let a second driver invalidate an in-flight provider result', async () => { + const user = await createTestUser(env.db), + project = await createTestProject(env.db, user.id, 'race-mail'); + let release!: () => void, entered!: () => void; + const gate = new Promise((resolve) => { + release = resolve; + }); + const seen = new Promise((resolve) => { + entered = resolve; + }); + stubCustomerCf({ + zones, + on: { + scriptPut: async () => { + entered(); + await gate; + }, + }, + }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'race.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + const first = runEmailOperation(env.db, bindings(), add.operationId); + await seen; + await runEmailOperation(env.db, bindings(), add.operationId); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0]?.status, + ).toBe('running'); + release(); + await first; + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0]?.status, + ).toBe('completed'); + }); + + it('promotes a rotated secret only after the gateway accepts it', async () => { + const user = await createTestUser(env.db), + project = await createTestProject(env.db, user.id, 'rotation-mail'); + const failures: { gatewayProbe?: { message: string; status: number } } = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'rotate.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const route = (await resolveEmailDomain(env.db, 'rotate.example.com'))!; + const before = route.connection.active_secret_generation; + const operationId = await requestEmailSecretRotation(env.db, bindings(), route.connection.id, { + kind: 'owner', + userId: user.id, + }); + failures.gatewayProbe = { message: 'gateway refused secret', status: 403 }; + await runEmailOperation(env.db, bindings(), operationId); + const pending = ( + await env.db + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, route.connection.id)) + )[0]!; + expect(pending.active_secret_generation).toBe(before); + expect(pending.staged_secret_generation).toBe(before + 1); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, operationId)))[0] + ?.status, + ).toBe('unknown'); + delete failures.gatewayProbe; + await reconcilePendingEmailOperations(env.db, bindings()); + const promoted = ( + await env.db + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, route.connection.id)) + )[0]!; + expect(promoted.active_secret_generation).toBe(before + 1); + expect(promoted.staged_secret_generation).toBeNull(); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, operationId)))[0] + ?.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + }); + + it('recovers a lost secret PUT response by proving the staged deployed value', async () => { + const user = await createTestUser(env.db), + project = await createTestProject(env.db, user.id, 'lost-rotation'); + const failures: { secretPut?: { message: string; status: number } } = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'lost.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const connection = (await resolveEmailDomain(env.db, 'lost.example.com'))!.connection; + const rotation = await requestEmailSecretRotation(env.db, bindings(), connection.id, { + kind: 'owner', + userId: user.id, + }); + failures.secretPut = { message: 'response lost', status: 504 }; + await runEmailOperation(env.db, bindings(), rotation); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('unknown'); + delete failures.secretPut; + await reconcilePendingEmailOperations(env.db, bindings()); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + }); + + it('does not replace a foreign zone catch-all', async () => { + const user = await createTestUser(env.db), + project = await createTestProject(env.db, user.id, 'foreign-mail'); + const stub = stubCustomerCf({ + zones, + catchAllRule: { enabled: true, workerName: 'somebody-else' }, + }); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'foreign.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }), + ).rejects.toThrow('unrelated catch-all'); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(0); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(0); + }); + + it('does not install catch-all until the gateway accepts the zone secret', async () => { + const user = await createTestUser(env.db), + project = await createTestProject(env.db, user.id, 'gateway-refusal'); + const stub = stubCustomerCf({ + zones, + failOn: { gatewayProbe: { message: 'refused', status: 403 } }, + }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'refused.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0]?.status, + ).toBe('unknown'); + expect((await resolveEmailDomain(env.db, 'refused.example.com'))?.route.inbound_status).toBe( + 'pending', + ); + expect(callsByTag(stub.calls, 'relayProbe')).toHaveLength(1); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(0); + }); + + it('keeps the installation gateway Worker when a custom sibling is added, synced and removed', async () => { + const owner = await createTestUser(env.db), + project = await createTestProject(env.db, owner.id, 'shared-sibling'); + const shared = { + ...bindings(), + EMAIL_SENDER_DOMAIN: 'example.com', + EMAIL_SHARED_ACCOUNT_ID: env.CF_ACCOUNT_ID, + EMAIL_SHARED_ZONE_ID: 'platform-mail-zone', + EMAIL_SHARED_INGRESS_NAME: 'void-email-gateway', + } as ApiEnv['Bindings']; + const stub = stubCustomerCf({ + zones: { + 'example.com': { + id: 'platform-mail-zone', + name: 'example.com', + accountId: env.CF_ACCOUNT_ID, + }, + }, + }); + const bootstrap = await ensureSharedEmailConnection(env.db, shared); + expect(bootstrap).toBeTruthy(); + await runEmailOperation(env.db, shared, bootstrap!); + const added = await requestEmailDomainAdd(env.db, shared, { + projectId: project.id, + domain: 'alerts.example.com', + actor: { kind: 'admin', userId: owner.id }, + }); + await runEmailOperation(env.db, shared, added.operationId); + const route = await resolveEmailDomain(env.db, 'alerts.example.com'); + expect(route?.route.inbound_status).toBe('ready'); + expect(route?.route.outbound_status).toBe('ready'); + expect(route?.connection.ingress_worker_name).toBe('void-email-gateway'); + const nativeRoute = await resolveEmailIngress(env.db, { + installationId: 'void-hosted', + accountId: env.CF_ACCOUNT_ID, + zoneId: 'platform-mail-zone', + ingressName: 'void-email-gateway', + recipient: 'inbox@alerts.example.com', + }); + expect(nativeRoute?.route.project_id).toBe(project.id); + expect(nativeRoute?.route.addressing).toBe('custom'); + const sync = await requestEmailDomainSync(env.db, shared, added.routeId, { + kind: 'admin', + userId: owner.id, + }); + await runEmailOperation(env.db, shared, sync); + await expect( + requestEmailSecretRotation(env.db, shared, route!.connection.id, { + kind: 'admin', + userId: owner.id, + }), + ).rejects.toThrow('managed by platform deployment'); + const remove = await requestEmailDomainRemove(env.db, shared, added.routeId, { + kind: 'admin', + userId: owner.id, + }); + await runEmailOperation(env.db, shared, remove); + const removedRoute = (await resolveEmailDomain(env.db, 'alerts.example.com'))!.route; + expect(removedRoute.desired_state).toBe('removed'); + expect(await disableEmailDomainRouteAndDrain(env.db, removedRoute.id)).toEqual({ + cancelled: 0, + inFlight: 0, + }); + const repeatedRemoval = (await resolveEmailDomain(env.db, 'alerts.example.com'))!.route; + expect(repeatedRemoval.desired_state).toBe('removed'); + expect(repeatedRemoval.desired_generation).toBe(removedRoute.desired_generation); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(0); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(0); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + expect((await resolveEmailDomain(env.db, 'example.com'))?.route.desired_state).toBe('active'); + }); + + it('requires the zone manager for sibling claims and blocks credential renewal while outcome is unknown', async () => { + const manager = await createTestUser(env.db, 'zone-manager'), + other = await createTestUser(env.db, 'zone-other'); + const first = await createTestProject(env.db, manager.id, 'manager-project'), + second = await createTestProject(env.db, other.id, 'other-project'); + const failures: { secretPut?: { message: string; status: number } } = {}; + stubCustomerCf({ zones, failOn: failures }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'manager.example.com', + actor: { kind: 'owner', userId: manager.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: second.id, + domain: 'other.example.com', + actor: { kind: 'owner', userId: other.id }, + token: TOKEN, + }), + ).rejects.toThrow('manager approval'); + const connection = (await resolveEmailDomain(env.db, 'manager.example.com'))!.connection; + const rotation = await requestEmailSecretRotation(env.db, bindings(), connection.id, { + kind: 'owner', + userId: manager.id, + }); + failures.secretPut = { message: 'unknown write', status: 504 }; + await runEmailOperation(env.db, bindings(), rotation); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'manager.example.com', + actor: { kind: 'owner', userId: manager.id }, + token: 'renewed-token', + }), + ).rejects.toThrow('unresolved'); + }); +}); diff --git a/platform/packages/api/test/integration/email-domain-cf-stub.ts b/platform/packages/api/test/integration/email-domain-cf-stub.ts index 074675c18..4f13a5fe8 100644 --- a/platform/packages/api/test/integration/email-domain-cf-stub.ts +++ b/platform/packages/api/test/integration/email-domain-cf-stub.ts @@ -15,9 +15,14 @@ export type StubFailTag = | 'sendingSubdomainsGet' | 'scriptGet' | 'scriptPut' + | 'workersSubdomain' + | 'scriptSubdomain' + | 'relayProbe' + | 'gatewayProbe' | 'secretPut' | 'catchAll' | 'catchAllGet' + | 'routingRulesGet' | 'routingSettingsGet' | 'scriptDelete' | 'oauthToken' @@ -74,6 +79,8 @@ export function stubCustomerCf( const catchAllStates = new Map(); // Per-script sha256 of the last secret PUT text (never the text). const secretHashes = new Map(); + const relaySecrets = new Map(); + const scriptSubdomains = new Map(); const catchAllStateFor = (zoneId: string) => { if (!catchAllStates.has(zoneId)) { catchAllStates.set( @@ -149,11 +156,98 @@ export function stubCustomerCf( }); } + if (url.endsWith('.workers.dev/__void/email/probe')) { + await record({ tag: 'relayProbe', method, url }); + const failure = fail('relayProbe'); + if (failure) { + return failure; + } + const name = new URL(url).hostname.split('.')[0]!; + const secret = relaySecrets.get(name); + if (!secret || !scriptSubdomains.get(name)) { + return new Response(null, { status: 404 }); + } + const challenge = new Headers(init?.headers).get('X-Void-Probe-Challenge') ?? ''; + const generation = Number(new Headers(init?.headers).get('X-Void-Probe-Generation')); + const metadata = [...calls] + .reverse() + .find((call) => call.tag === 'scriptPut' && call.url.includes(`/scripts/${name}`))?.body as + | { bindings?: Array<{ name: string; text: string }> } + | undefined; + const binding = (name: string) => + metadata?.bindings?.find((row) => row.name === name)?.text ?? ''; + const accountId = binding('VOID_EMAIL_ACCOUNT'), + zoneId = binding('VOID_EMAIL_ZONE'), + ingressName = binding('VOID_EMAIL_INGRESS'); + const data = [ + 'email-relay-proof-v1', + accountId, + zoneId, + ingressName, + String(generation), + challenge, + ].join('\n'); + const key = await crypto.subtle.importKey( + 'raw', + new TextEncoder().encode(secret), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign'], + ); + const proof = Array.from( + new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data))), + (byte) => byte.toString(16).padStart(2, '0'), + ).join(''); + return Response.json({ accountId, zoneId, ingressName, generation, challenge, proof }); + } + + if (url === 'https://email-gateway.example.test/email/probe') { + await record({ tag: 'gatewayProbe', method, url }); + const failure = fail('gatewayProbe'); + if (failure) { + return failure; + } + const body = + typeof init?.body === 'string' ? (JSON.parse(init.body) as { ingressName?: string }) : {}; + const bearer = new Headers(init?.headers).get('Authorization')?.replace(/^Bearer /, ''); + if ( + !bearer || + (relaySecrets.has(body.ingressName ?? '') && + relaySecrets.get(body.ingressName ?? '') !== bearer) + ) { + return new Response(null, { status: 403 }); + } + return new Response(null, { status: 204 }); + } + if (!url.startsWith('https://api.cloudflare.com/client/v4/')) { throw new Error(`Unmocked fetch: ${method} ${url}`); } const path = url.slice('https://api.cloudflare.com/client/v4'.length); + if (/\/accounts\/[^/]+\/workers\/subdomain$/.test(path) && method === 'GET') { + await record({ tag: 'workersSubdomain', method, url }); + return fail('workersSubdomain') ?? cfSuccess({ subdomain: 'customer' }); + } + const scriptSubdomainMatch = /\/accounts\/[^/]+\/workers\/scripts\/([^/]+)\/subdomain$/.exec( + path, + ); + if (scriptSubdomainMatch) { + await record({ tag: 'scriptSubdomain', method, url }); + const failure = fail('scriptSubdomain'); + if (failure) { + return failure; + } + if (method === 'POST') { + scriptSubdomains.set(scriptSubdomainMatch[1]!, true); + return cfSuccess({ enabled: true, previews_enabled: false }); + } + return cfSuccess({ + enabled: scriptSubdomains.get(scriptSubdomainMatch[1]!) ?? false, + previews_enabled: false, + }); + } + if (path === '/user/tokens/verify') { await record({ tag: 'verifyToken', method, url }); const failure = fail('verifyToken'); @@ -212,6 +306,11 @@ export function stubCustomerCf( return cfSuccess(config.routingSettings ?? { enabled: true }); } + if (/\/zones\/[^/]+\/email\/routing\/rules\?/.test(path) && method === 'GET') { + await record({ tag: 'routingRulesGet', method, url }); + return fail('routingRulesGet') ?? cfSuccess([]); + } + const catchAllMatch = /\/zones\/([^/]+)\/email\/routing\/rules\/catch_all$/.exec(path); if (catchAllMatch && method === 'GET') { await record({ tag: 'catchAllGet', method, url }); @@ -260,6 +359,7 @@ export function stubCustomerCf( // form the ROUTING mirror stores — so a test can prove worker, row // and mirror carry ONE secret without the value ever being recorded. secretHashes.set(secretsMatch[1]!, await hashEmailRelaySecret(text)); + relaySecrets.set(secretsMatch[1]!, text); await record({ tag: 'secretPut', method, diff --git a/platform/packages/api/test/integration/helpers.ts b/platform/packages/api/test/integration/helpers.ts index 4d2b8f0ff..b476953da 100644 --- a/platform/packages/api/test/integration/helpers.ts +++ b/platform/packages/api/test/integration/helpers.ts @@ -467,6 +467,22 @@ export async function teardownEnv(): Promise { } export async function clearTables(db: Db): Promise { + for (const table of [ + schema.emailOperationSteps, + schema.emailOperations, + schema.emailDomainRoutes, + schema.emailZoneConnections, + schema.emailCredentials, + schema.emailCacheOutbox, + schema.emailUnresolvedAttempts, + schema.emailActionRecipients, + schema.emailActions, + schema.emailReceipts, + schema.emailProjectControls, + schema.emailMonthlyUsage, + ]) { + await db.delete(table); + } await db.delete(sandboxDrainCheckpoints); await db.delete(domains); await db.delete(resources); diff --git a/platform/packages/api/test/integration/operator-audit.test.ts b/platform/packages/api/test/integration/operator-audit.test.ts index 77fe8e3ff..a58a8be29 100644 --- a/platform/packages/api/test/integration/operator-audit.test.ts +++ b/platform/packages/api/test/integration/operator-audit.test.ts @@ -149,6 +149,7 @@ test('records complete and partial 207 mutation outcomes as failed', async () => environment: 'staging', versions: { dispatch: 'previous', + 'email-gateway': 'previous', dashboard: 'previous', api: 'previous', tail: 'previous', @@ -250,6 +251,7 @@ test('browser rollback-all records a failed outcome when its result page is HTML '/platform/rollback-all', new URLSearchParams({ version_dispatch: 'previous', + 'version_email-gateway': 'previous', version_dashboard: 'previous', version_api: 'previous', version_tail: 'previous', @@ -273,6 +275,7 @@ test('records the effective worker environment for implicit and explicit rollbac const staging = { ...env, PLATFORM_ENV: 'staging' }; const versions = { dispatch: 'previous', + 'email-gateway': 'previous', dashboard: 'previous', api: 'previous', tail: 'previous', diff --git a/platform/packages/api/test/integration/operator-email-domains.test.ts b/platform/packages/api/test/integration/operator-email-domains.test.ts index d2a4c4a84..ca33d31ed 100644 --- a/platform/packages/api/test/integration/operator-email-domains.test.ts +++ b/platform/packages/api/test/integration/operator-email-domains.test.ts @@ -1,4 +1,3 @@ -import { eq } from 'drizzle-orm'; import { afterAll, afterEach, @@ -6,45 +5,44 @@ import { beforeEach, describe, expect, - test, + it, vi, } from 'vite-plus/test'; -import { hmacSignState } from '../../src/auth/hmac.ts'; -import { - encryptEmailDomainRelaySecret, - encryptEmailDomainToken, - type EmailDomain, -} from '../../src/email/domains.ts'; -import { RELAY_WORKER_BASE_NAME } from '../../src/email/relay-engine.ts'; -import { RELAY_VERSION } from '../../src/email/relay-worker.ts'; +import { emailDomainRoutes, emailZoneConnections } from '../../src/email/connection-schema.ts'; import type { ApiEnv } from '../../src/env.ts'; -import { app } from '../../src/index.ts'; -import { emailDomains, operatorEvents } from '../../src/schema.ts'; -import { callsByTag, stubCustomerCf, tags } from './email-domain-cf-stub.ts'; +import app from '../../src/index.ts'; +import { callsByTag, stubCustomerCf } from './email-domain-cf-stub.ts'; import { CF_ACCOUNT_ID, - CF_API_TOKEN, clearTables, createOperatorToken, createTestProject, createTestUser, - JWT_SECRET, setupEnv, teardownEnv, type TestEnv, } from './helpers.ts'; -let env: TestEnv; -let token: string; - -// Dummy stand-ins — never real token material. -const CUSTOMER_TOKEN = 'cf-customer-token-dummy'; -const RELAY_SECRET = 'relay-secret-dummy'; -/** A zone in the platform's own account — what the platform credential may register. */ -const PLATFORM_ZONE = { id: 'zone_platform', name: 'example.com', accountId: CF_ACCOUNT_ID }; -/** A zone in a customer's account — refused on the platform credential. */ -const FOREIGN_ZONE = { id: 'zone_foreign', name: 'elsewhere.test', accountId: 'acct_customer' }; - +let env: TestEnv, operatorToken: string; +const zones = { + 'example.com': { id: 'zone-platform', name: 'example.com', accountId: CF_ACCOUNT_ID }, +}; +function request(path: string, body?: Record, token = operatorToken) { + return app.fetch( + new Request(`http://localhost/operator/v1${path}`, { + method: body ? 'POST' : 'GET', + headers: { + Authorization: `Bearer ${token}`, + ...(body ? { 'Content-Type': 'application/json' } : {}), + }, + body: body ? JSON.stringify(body) : undefined, + }), + { + ...env, + EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test', + } as unknown as ApiEnv['Bindings'], + ); +} beforeAll(async () => { env = await setupEnv(); }); @@ -53,651 +51,67 @@ afterAll(async () => { }); beforeEach(async () => { await clearTables(env.db); - const mirrors = await env.ROUTING.list({ prefix: 'email-domain:' }); - await Promise.all(mirrors.keys.map((key) => env.ROUTING.delete(key.name))); - const admin = await createTestUser(env.db, 'domain-admin', 'github', undefined, 'free', 'admin'); - token = await createOperatorToken(env.db, admin); + const admin = await createTestUser(env.db, 'operator-mail', 'github', undefined, 'free', 'admin'); + operatorToken = await createOperatorToken(env.db, admin); }); afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); }); -function req( - path: string, - body?: Record, - overrides?: Partial, -) { - return app.fetch( - new Request(`http://localhost/operator/v1${path}`, { - method: body ? 'POST' : 'GET', - headers: { - Authorization: `Bearer ${token}`, - ...(body ? { 'Content-Type': 'application/json' } : {}), - }, - body: body ? JSON.stringify(body) : undefined, - }), - { ...env, ...overrides }, - ); -} - -async function rowFor(domain: string): Promise { - const rows = await env.db.select().from(emailDomains).where(eq(emailDomains.domain, domain)); - return rows[0]; -} - -async function events() { - return env.db.select().from(operatorEvents); -} - -async function seedOwnerDomain(projectId: string, domain: string): Promise { - const tokenEnc = await encryptEmailDomainToken(env, projectId, domain, CUSTOMER_TOKEN); - const relayEnc = await encryptEmailDomainRelaySecret(env, projectId, domain, RELAY_SECRET); - await env.db.insert(emailDomains).values({ - id: `edom_owner_${domain.replace(/[^a-z0-9]/g, '')}`, - project_id: projectId, - domain, - zone_id: FOREIGN_ZONE.id, - account_id: FOREIGN_ZONE.accountId, - mode: 'apex', - status: 'active', - credential_kind: 'api_token', - managed_by: 'owner', - token_ciphertext: tokenEnc.ciphertext, - token_iv: tokenEnc.iv, - token_key_version: tokenEnc.keyVersion, - relay_ciphertext: relayEnc.ciphertext, - relay_iv: relayEnc.iv, - relay_key_version: relayEnc.keyVersion, - relay_worker_name: RELAY_WORKER_BASE_NAME, - relay_version: RELAY_VERSION, +describe('operator email domain management', () => { + it('requires operator authentication and validates a project before provider calls', async () => { + const stub = stubCustomerCf({ zones }); + expect((await request('/email/domains', undefined, 'invalid')).status).toBe(401); + const bad = await request('/email/domains', { domain: 'mail.example.com', project: 'missing' }); + expect(bad.status).toBe(404); + expect(stub.calls).toHaveLength(0); }); - return (await rowFor(domain))!; -} - -async function seedProject(slug = 'hr-portal') { - const owner = await createTestUser(env.db, `${slug}-owner`); - return createTestProject(env.db, owner.id, slug); -} - -describe('operator email domain-add', () => { - test('previews without any Cloudflare call, then registers on the platform credential', async () => { - const project = await seedProject(); - const stub = stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - const preview = await req('/email/domains', { - domain: 'Example.COM', + it('previews without mutations and then manages one exact route with a platform token', async () => { + const owner = await createTestUser(env.db, 'managed-owner'), + project = await createTestProject(env.db, owner.id, 'managed-project'); + const stub = stubCustomerCf({ zones }); + const preview = await request('/email/domains', { + domain: 'mail.example.com', project: project.slug, dryRun: true, }); expect(preview.status).toBe(200); - expect(await preview.json()).toMatchObject({ - dryRun: true, - action: 'email.domain.add', - target: { - domain: 'example.com', - projectId: project.id, - slug: project.slug, - credentialKind: 'platform', - }, - existing: null, - plan: 'setup', - mx: 'apex', - }); - // Public DNS only — the credential is never spent on a preview. - expect(tags(stub.calls)).toEqual(['mxLookup']); - expect(await rowFor('example.com')).toBeUndefined(); - expect(await events()).toHaveLength(0); - - const response = await req('/email/domains', { domain: 'example.com', project: project.id }); - expect(response.status).toBe(200); - const body = (await response.json()) as { action: string; domain: Record }; - expect(body.action).toBe('email.domain.add'); - expect(body.domain).toMatchObject({ - domain: 'example.com', - status: 'active', - credential_kind: 'platform', - managed_by: 'admin', - relay_worker_name: RELAY_WORKER_BASE_NAME, - }); - const row = (await rowFor('example.com'))!; - expect(row.credential_kind).toBe('platform'); - expect(row.managed_by).toBe('admin'); - expect(row.token_ciphertext).toBeNull(); - expect(row.token_iv).toBeNull(); - expect(row.token_key_version).toBeNull(); - expect(row.account_id).toBe(CF_ACCOUNT_ID); - // No user-token verify: the runtime token is not a user token. - expect(callsByTag(stub.calls, 'verifyToken')).toHaveLength(0); - // Every customer-account call went out with the runtime token. - for (const call of stub.fn.mock.calls) { - const init = call[1] as RequestInit | undefined; - const auth = new Headers(init?.headers).get('Authorization'); - if (auth) { - expect(auth).toBe(`Bearer ${CF_API_TOKEN}`); - } - } - const recorded = await events(); - expect(recorded).toHaveLength(1); - expect(recorded[0]).toMatchObject({ action: 'email/domains', status: 'success' }); - expect(JSON.parse(recorded[0]!.target)).toEqual({ - domain: 'example.com', - project: project.id, - }); - }); - - test('previews a re-run in the stored mode even when public MX is present', async () => { - const project = await seedProject(); - stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - expect( - (await req('/email/domains', { domain: 'example.com', project: project.id })).status, - ).toBe(200); - stubCustomerCf({ mx: { 'example.com': ['route1.mx.cloudflare.net'] } }); - - const preview = await req('/email/domains', { - domain: 'example.com', - project: project.id, - dryRun: true, - }); - const body = (await preview.json()) as Record; - expect(body).toMatchObject({ - plan: 'rerun', - mx: 'subdomain', - effect: expect.stringContaining('stored apex mode'), - }); - expect(String(body.effect)).not.toContain('setup will refuse'); - }); - - test('keeps the MX refusal preview for an existing row with no stored mode', async () => { - const project = await seedProject(); - stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - expect( - (await req('/email/domains', { domain: 'example.com', project: project.id })).status, - ).toBe(200); - await env.db - .update(emailDomains) - .set({ mode: null }) - .where(eq(emailDomains.domain, 'example.com')); - stubCustomerCf({ mx: { 'example.com': ['route1.mx.cloudflare.net'] } }); - - const preview = await req('/email/domains', { - domain: 'example.com', - project: project.id, - dryRun: true, - }); - expect(await preview.json()).toMatchObject({ - plan: 'rerun', - mx: 'subdomain', - effect: expect.stringContaining('setup will refuse'), - }); - }); - - test('reports a failed setup as a partial failure and a failed audit event', async () => { - const project = await seedProject(); - stubCustomerCf({ - zones: { 'example.com': PLATFORM_ZONE }, - failOn: { zones: { message: 'zone lookup failed', status: 502 } }, - }); - - const response = await req('/email/domains', { domain: 'example.com', project: project.id }); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ - ok: false, - domain: { status: 'failed', setup_state: { failed_step: 'zone_lookup' } }, - }); - expect((await events()).at(-1)).toMatchObject({ action: 'email/domains', status: 'failed' }); - }); - - test('keeps a pending setup as a successful operator result', async () => { - const project = await seedProject(); - stubCustomerCf({ - zones: { 'example.com': PLATFORM_ZONE }, - failOn: { routingDns: { message: 'use the dashboard', status: 403 } }, - }); - - const response = await req('/email/domains', { + expect(((await preview.json()) as { dryRun: boolean }).dryRun).toBe(true); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(0); + expect(await env.db.select().from(emailDomainRoutes)).toHaveLength(0); + const add = await request('/email/domains', { domain: 'mail.example.com', - project: project.id, - }); - expect(response.status).toBe(200); - const body = (await response.json()) as Record & { - domain: Record; - }; - expect(body.domain.status).toBe('pending'); - expect(Object.hasOwn(body, 'ok')).toBe(false); - }); - - test('refuses a zone outside the platform account before any write', async () => { - const project = await seedProject(); - const stub = stubCustomerCf({ zones: { 'elsewhere.test': FOREIGN_ZONE } }); - const response = await req('/email/domains', { domain: 'elsewhere.test', project: project.id }); - // The engine records the failure on the row; the operator answers 200 - // with the row's error like the owner route does. - expect(response.status).toBe(200); - const body = (await response.json()) as { domain: Record }; - expect(body.domain).toMatchObject({ - status: 'failed', - setup_state: { failed_step: 'zone_lookup' }, - }); - expect(String(body.domain.error)).toContain(FOREIGN_ZONE.accountId); - expect(String(body.domain.error)).toContain(CF_ACCOUNT_ID); - expect(String(body.domain.error)).toContain('--token-stdin'); - // Zone lookup only — nothing was enabled, deployed or written to the zone. - expect(new Set(tags(stub.calls))).toEqual(new Set(['zones'])); - expect((await rowFor('elsewhere.test'))?.status).toBe('failed'); - }); - - test('a pasted token registers a zone elsewhere as an api_token admin row', async () => { - const project = await seedProject(); - const stub = stubCustomerCf({ zones: { 'elsewhere.test': FOREIGN_ZONE } }); - const preview = await req('/email/domains', { - domain: 'elsewhere.test', - project: project.id, - apiToken: CUSTOMER_TOKEN, - dryRun: true, - }); - expect(await preview.json()).toMatchObject({ target: { credentialKind: 'api_token' } }); - - const response = await req('/email/domains', { - domain: 'elsewhere.test', - project: project.id, - apiToken: CUSTOMER_TOKEN, - }); - expect(response.status).toBe(200); - const row = (await rowFor('elsewhere.test'))!; - expect(row).toMatchObject({ - credential_kind: 'api_token', - managed_by: 'admin', - status: 'active', - account_id: FOREIGN_ZONE.accountId, - }); - expect(row.token_ciphertext).not.toBeNull(); - expect(callsByTag(stub.calls, 'verifyToken')).toHaveLength(1); - const recorded = await events(); - expect(JSON.stringify(recorded)).not.toContain(CUSTOMER_TOKEN); - }); - - test('refuses to re-run a pasted-token row on the platform credential when its zone is elsewhere', async () => { - const project = await seedProject(); - stubCustomerCf({ zones: { 'elsewhere.test': FOREIGN_ZONE } }); - expect( - ( - await req('/email/domains', { - domain: 'elsewhere.test', - project: project.id, - apiToken: CUSTOMER_TOKEN, - }) - ).status, - ).toBe(200); - const before = (await rowFor('elsewhere.test'))!; - expect(before).toMatchObject({ credential_kind: 'api_token', status: 'active' }); - - const stub = stubCustomerCf({ zones: { 'elsewhere.test': FOREIGN_ZONE } }); - const response = await req('/email/domains', { domain: 'elsewhere.test', project: project.id }); - expect(response.status).toBe(409); - expect(await response.json()).toMatchObject({ - message: expect.stringContaining(FOREIGN_ZONE.accountId), - }); - // The stored token is untouched and the runtime token never left. - const after = (await rowFor('elsewhere.test'))!; - expect(after.credential_kind).toBe('api_token'); - expect(after.token_ciphertext).toBe(before.token_ciphertext); - expect(stub.calls).toEqual([]); - }); - - test('does not take over a row the project owner registered', async () => { - const project = await seedProject(); - await seedOwnerDomain(project.id, 'owned.test'); - const stub = stubCustomerCf({ zones: { 'owned.test': FOREIGN_ZONE } }); - const response = await req('/email/domains', { domain: 'owned.test', project: project.id }); - expect(response.status).toBe(409); - expect(await response.json()).toMatchObject({ - message: expect.stringContaining('registered by its project owner'), + project: project.slug, }); - expect(stub.calls).toEqual([]); - expect((await rowFor('owned.test'))?.managed_by).toBe('owner'); - }); - - test('refuses a domain registered to another project', async () => { - const project = await seedProject(); - const other = await seedProject('other-app'); - await seedOwnerDomain(other.id, 'taken.test'); - const response = await req('/email/domains', { domain: 'taken.test', project: project.id }); - expect(response.status).toBe(409); - }); - - test.each([ - ['an unknown project', { domain: 'example.com', project: 'nope' }, 404], - ['an invalid domain', { domain: 'not a domain', project: 'hr-portal' }, 400], - ['a missing project', { domain: 'example.com' }, 400], - ])('rejects %s', async (_label, body, status) => { - await seedProject(); - const response = await req('/email/domains', body); - expect(response.status).toBe(status); - }); - - test('answers 503 when the platform has no runtime token', async () => { - const project = await seedProject(); - stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - const response = await req( - '/email/domains', - { domain: 'example.com', project: project.id }, - { CF_API_TOKEN: '' }, - ); - expect(response.status).toBe(503); - expect(await rowFor('example.com')).toBeUndefined(); - }); -}); - -describe('operator email domain list, status, sync and remove', () => { - async function addPlatformDomain(projectId: string, domain = 'example.com') { - const stub = stubCustomerCf({ zones: { [domain]: { ...PLATFORM_ZONE, name: domain } } }); - const response = await req('/email/domains', { domain, project: projectId }); - expect(response.status).toBe(200); - return stub; - } - - test("lists every row with its project, or one project's rows", async () => { - const project = await seedProject(); - const other = await seedProject('other-app'); - await addPlatformDomain(project.id); - await seedOwnerDomain(other.id, 'owned.test'); - - const all = (await (await req('/email/domains')).json()) as { - domains: Array<{ domain: string; managed_by: string; project: { slug: string } }>; + expect(add.status).toBe(200); + const payload = (await add.json()) as { + domain: { operationId: string; readiness: { inbound: { status: string } } }; }; - expect(all.domains.map((d) => [d.domain, d.managed_by, d.project.slug])).toEqual([ - ['example.com', 'admin', project.slug], - ['owned.test', 'owner', other.slug], - ]); - const filtered = (await (await req(`/email/domains?project=${other.slug}`)).json()) as { - domains: Array<{ domain: string }>; - }; - expect(filtered.domains.map((d) => d.domain)).toEqual(['owned.test']); - expect((await req('/email/domains?project=missing')).status).toBe(404); - }); - - test('status probes a platform row with a zone-scoped read, never token verify', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - const stub = stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - const response = await req('/email/domains/example.com'); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ - domain: 'example.com', - credential_kind: 'platform', - managed_by: 'admin', - credential_status: 'active', - project: { id: project.id, slug: project.slug }, - }); - expect(callsByTag(stub.calls, 'verifyToken')).toHaveLength(0); - expect(callsByTag(stub.calls, 'routingSettingsGet').length).toBeGreaterThan(0); - }); - - test('status walks parent zones for a platform row that has not stored its zone yet', async () => { - const project = await seedProject(); - const zone = { ...PLATFORM_ZONE, name: 'acme.com' }; - stubCustomerCf({ zones: { 'acme.com': zone } }); - expect( - (await req('/email/domains', { domain: 'mail.acme.com', project: project.id })).status, - ).toBe(200); - await env.db - .update(emailDomains) - .set({ zone_id: null }) - .where(eq(emailDomains.domain, 'mail.acme.com')); - const stub = stubCustomerCf({ zones: { 'acme.com': zone } }); - - const response = await req('/email/domains/mail.acme.com'); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ credential_status: 'active' }); - expect( - callsByTag(stub.calls, 'zones').map((call) => new URL(call.url).searchParams.get('name')), - ).toEqual(['mail.acme.com', 'acme.com']); - }); - - test('status reports probe_failed when no parent zone is visible for a platform row', async () => { - const project = await seedProject(); - const zone = { ...PLATFORM_ZONE, name: 'acme.com' }; - stubCustomerCf({ zones: { 'acme.com': zone } }); - expect( - (await req('/email/domains', { domain: 'mail.acme.com', project: project.id })).status, - ).toBe(200); - await env.db - .update(emailDomains) - .set({ zone_id: null }) - .where(eq(emailDomains.domain, 'mail.acme.com')); - stubCustomerCf({ zones: {} }); - - const response = await req('/email/domains/mail.acme.com'); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ credential_status: 'probe_failed' }); - }); - - test('status reports probe_failed, not revoked, when the runtime token is refused', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - stubCustomerCf({ - zones: { 'example.com': PLATFORM_ZONE }, - failOn: { routingSettingsGet: { message: 'forbidden', status: 403 } }, - }); - const body = (await (await req('/email/domains/example.com')).json()) as Record< - string, - unknown - >; - expect(body.credential_status).toBe('probe_failed'); - expect(body.status).toBe('active'); - expect((await rowFor('example.com'))?.status).toBe('active'); - }); - - test('sync previews, then redeploys the relay and rotates its secret', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - const before = (await rowFor('example.com'))!; - const stub = stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - - const preview = await req('/email/domains/example.com/sync', { dryRun: true }); - expect(await preview.json()).toMatchObject({ - dryRun: true, - action: 'email.domain.sync', - target: { domain: 'example.com', projectId: project.id }, - }); - expect(stub.calls).toEqual([]); - - const response = await req('/email/domains/example.com/sync', {}); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ action: 'email.domain.sync' }); - expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(1); - expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(1); - const after = (await rowFor('example.com'))!; - expect(after.relay_ciphertext).not.toBe(before.relay_ciphertext); - expect(after.credential_kind).toBe('platform'); - const recorded = await events(); - expect(recorded.map((event) => event.action).sort()).toEqual( - ['email/domains', 'email/domains/example.com/sync'].sort(), - ); - const syncEvent = recorded.find((event) => event.action === 'email/domains/example.com/sync'); - expect(JSON.parse(syncEvent!.target)).toEqual({ domain: 'example.com' }); - }); - - test('reports a sync whose stored token was revoked as a partial failure', async () => { - const project = await seedProject(); - stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - expect( - ( - await req('/email/domains', { - domain: 'example.com', - project: project.id, - apiToken: CUSTOMER_TOKEN, - }) - ).status, - ).toBe(200); - stubCustomerCf({ verifyStatus: 'revoked' }); - - const response = await req('/email/domains/example.com/sync', {}); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ - ok: false, - domain: { status: 'token_revoked' }, - }); - expect((await events()).at(-1)).toMatchObject({ - action: 'email/domains/example.com/sync', - status: 'failed', - }); - }); - - test('remove resets the catch-all, deletes the relay and drops the row', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - const stub = stubCustomerCf({ - zones: { 'example.com': PLATFORM_ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const preview = await req('/email/domains/example.com/remove', { dryRun: true }); - expect(await preview.json()).toMatchObject({ - dryRun: true, - action: 'email.domain.remove', - target: { domain: 'example.com', force: false }, - managed_by: 'admin', - }); - const response = await req('/email/domains/example.com/remove', {}); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ - action: 'email.domain.remove', - domain: { ok: true, removed: true }, - }); - expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); - expect(await rowFor('example.com')).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:example.com')).toBeNull(); - const recorded = await events(); - expect(JSON.parse(recorded.at(-1)!.target)).toEqual({ domain: 'example.com', force: false }); - }); - - test('a kept row after a failed relay delete is reported as a failed mutation, not success', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - stubCustomerCf({ - zones: { 'example.com': PLATFORM_ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { scriptDelete: { message: 'boom', status: 500 } }, - }); - const response = await req('/email/domains/example.com/remove', {}); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ - action: 'email.domain.remove', - ok: false, - domain: { ok: false, removed: false, failed_steps: expect.arrayContaining(['delete_relay']) }, - }); - expect((await rowFor('example.com'))?.setup_state).toMatchObject({ failed_step: 'remove' }); - const recorded = await events(); - expect(recorded.at(-1)).toMatchObject({ - action: 'email/domains/example.com/remove', - status: 'failed', - }); - }); - - test('remove --force is a JSON boolean and drops the row past a failed relay delete', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - stubCustomerCf({ - zones: { 'example.com': PLATFORM_ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { scriptDelete: { message: 'boom', status: 500 } }, - }); - expect((await req('/email/domains/example.com/remove', { force: 'yes' })).status).toBe(400); - const response = await req('/email/domains/example.com/remove', { force: true }); - expect(response.status).toBe(200); - expect(await response.json()).toMatchObject({ - domain: { ok: true, removed: true, forced: true }, - }); - expect(await rowFor('example.com')).toBeUndefined(); - }); - - test("an administrator may sync and remove an owner's row, but never re-add it", async () => { - const project = await seedProject(); - await seedOwnerDomain(project.id, 'owned.test'); + expect(payload.domain.operationId).toMatch(/^eop/); + expect(payload.domain.readiness.inbound.status).toBe('ready'); + expect((await env.db.select().from(emailZoneConnections))[0]?.managed_by).toBe('admin'); + expect((await request('/email/domains/mail.example.com')).status).toBe(200); + expect((await request('/email/domains/mail.example.com/rotate-secret', {})).status).toBe(200); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + expect((await request('/email/domains/mail.example.com/remove', {})).status).toBe(200); + expect((await env.db.select().from(emailDomainRoutes))[0]?.desired_state).toBe('removed'); + }); + + it('leaves a foreign catch-all untouched and reports the refusal', async () => { + const owner = await createTestUser(env.db, 'foreign-owner'), + project = await createTestProject(env.db, owner.id, 'foreign-project'); const stub = stubCustomerCf({ - zones: { 'owned.test': FOREIGN_ZONE }, - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - expect( - (await req('/email/domains', { domain: 'owned.test', project: project.id })).status, - ).toBe(409); - const sync = await req('/email/domains/owned.test/sync', {}); - expect(sync.status).toBe(200); - expect(await sync.json()).toMatchObject({ action: 'email.domain.sync' }); - // The owner's stored token did the work — never the runtime token. - for (const call of stub.fn.mock.calls) { - const auth = new Headers((call[1] as RequestInit | undefined)?.headers).get('Authorization'); - if (auth) { - expect(auth).toBe(`Bearer ${CUSTOMER_TOKEN}`); - } - } - expect((await rowFor('owned.test'))?.managed_by).toBe('owner'); - - const remove = await req('/email/domains/owned.test/remove', {}); - expect(remove.status).toBe(200); - expect(await remove.json()).toMatchObject({ domain: { ok: true, removed: true } }); - expect(await rowFor('owned.test')).toBeUndefined(); - }); - - test('an existing platform row survives runtime-token loss: probe_failed, no lease, 503 sync', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - const stub = stubCustomerCf({ zones: { 'example.com': PLATFORM_ZONE } }); - const noToken = { CF_API_TOKEN: '' }; - - const status = await req('/email/domains/example.com', undefined, noToken); - expect(status.status).toBe(200); - expect(await status.json()).toMatchObject({ - status: 'active', - credential_status: 'probe_failed', + zones, + catchAllRule: { enabled: true, workerName: 'foreign-worker' }, }); - expect((await rowFor('example.com'))?.status).toBe('active'); - - const lease = await app.fetch( - new Request('http://localhost/internal/email/domain-credential', { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'x-void-internal': await hmacSignState('example.com', JWT_SECRET), - }, - body: JSON.stringify({ domain: 'example.com' }), - }), - { ...env, ...noToken }, - ); - expect(lease.status).toBe(502); - expect(JSON.stringify(await lease.json())).not.toContain('token'); - - const sync = await req('/email/domains/example.com/sync', {}, noToken); - expect(sync.status).toBe(503); - expect(await sync.json()).toMatchObject({ - message: expect.stringContaining('platform credential unavailable'), + const response = await request('/email/domains', { + domain: 'mail.example.com', + project: project.slug, }); - expect(stub.calls).toEqual([]); - }); - - test('status, sync and remove answer 404 for an unknown domain', async () => { - expect((await req('/email/domains/nope.test')).status).toBe(404); - expect((await req('/email/domains/nope.test/sync', {})).status).toBe(404); - expect((await req('/email/domains/nope.test/remove', {})).status).toBe(404); - }); - - test('the proxy leases the runtime token for a platform row', async () => { - const project = await seedProject(); - await addPlatformDomain(project.id); - const response = await app.fetch( - new Request('http://localhost/internal/email/domain-credential', { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'x-void-internal': await hmacSignState('example.com', JWT_SECRET), - }, - body: JSON.stringify({ domain: 'example.com' }), - }), - env, - ); - expect(response.status).toBe(200); - expect(await response.json()).toEqual({ kind: 'api_token', token: CF_API_TOKEN }); + expect(response.status).toBe(409); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(0); + expect(await env.db.select().from(emailDomainRoutes)).toHaveLength(0); }); }); diff --git a/platform/packages/api/test/integration/operator-email.test.ts b/platform/packages/api/test/integration/operator-email.test.ts index 357ba002d..6a7388a69 100644 --- a/platform/packages/api/test/integration/operator-email.test.ts +++ b/platform/packages/api/test/integration/operator-email.test.ts @@ -9,6 +9,8 @@ import { test, vi, } from 'vite-plus/test'; +import { emailProjectControls } from '../../src/email/admission-schema.ts'; +import { setProjectEmailLimits } from '../../src/email/admission.ts'; import { EMAIL_DOMAIN_MANAGEMENT_SETTING, EMAIL_RECIPIENT_POLICY_MIRROR_KEY, @@ -163,12 +165,11 @@ describe('operator email recipient policy', () => { expect(recorded[0]).toMatchObject({ action: 'email/policy', status: 'failed' }); }); - test('a mirror write failure commits the policy but leaves the proxy on the previous, stricter policy until republished', async () => { + test('a display mirror failure leaves committed policy authoritative and repairs on read', async () => { await req('/email/policy', { mode: 'domains', domains: 'corp.example' }); const put = vi.spyOn(env.ROUTING, 'put').mockRejectedValueOnce(new Error('kv down')); const response = await req('/email/policy', { mode: 'any' }); - expect(response.status).toBe(503); - expect(await response.json()).toMatchObject({ error: 'mirror_failed' }); + expect(response.status).toBe(200); expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ mode: 'any', domains: [] }); expect(await env.ROUTING.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)).toBe( JSON.stringify({ mode: 'domains', domains: ['corp.example'] }), @@ -180,30 +181,33 @@ describe('operator email recipient policy', () => { ); }); - test('a failed tightening changes nothing', async () => { + test('a failed display mirror write does not undo a tighter policy', async () => { await req('/email/policy', { mode: 'any' }); const put = vi.spyOn(env.ROUTING, 'put').mockRejectedValueOnce(new Error('kv down')); const response = await req('/email/policy', { mode: 'verified' }); - expect(response.status).toBe(503); - expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ mode: 'any', domains: [] }); + expect(response.status).toBe(200); + expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ + mode: 'verified', + domains: [], + }); expect(await env.ROUTING.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)).toBe( JSON.stringify({ mode: 'any', domains: [] }), ); put.mockRestore(); }); - test('publishes with exactly one KV write', async () => { + test('publishes display hints without deleting policy keys', async () => { const put = vi.spyOn(env.ROUTING, 'put'); const del = vi.spyOn(env.ROUTING, 'delete'); expect((await req('/email/policy', { mode: 'domains', domains: 'a.example' })).status).toBe( 200, ); - expect(put).toHaveBeenCalledTimes(1); + expect(put).toHaveBeenCalled(); expect(del).not.toHaveBeenCalled(); expect((await req('/email/policy', { mode: 'verified' })).status).toBe(200); - expect(put).toHaveBeenCalledTimes(2); + expect(put.mock.calls.length).toBeGreaterThan(1); expect(del).not.toHaveBeenCalled(); }); @@ -214,7 +218,7 @@ describe('operator email recipient policy', () => { mode: 'domains', domains: 'b.example,c.example', }); - expect(response.status).toBe(503); + expect(response.status).toBe(200); expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ mode: 'domains', domains: ['b.example', 'c.example'], @@ -236,7 +240,7 @@ describe('operator email recipient policy', () => { mode: 'domains', domains: 'a.example,b.example', }); - expect(response.status).toBe(503); + expect(response.status).toBe(200); expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ mode: 'domains', domains: ['a.example', 'b.example'], @@ -305,11 +309,10 @@ describe('operator email settings', () => { }); describe('operator email limits', () => { - test('sets both caps by project slug and reports the previous overrides', async () => { + test('previews and commits both limits in authoritative project controls', async () => { const owner = await createTestUser(env.db, 'limit-owner'); const project = await createTestProject(env.db, owner.id, 'limit-project'); - await env.ROUTING.put(`email-limit:${project.id}`, '500'); - + await setProjectEmailLimits(env.db, project.id, { monthly: 500 }); const preview = await req(`/email/projects/${project.slug}/limit`, { monthly: '1000', burst: '25', @@ -318,88 +321,58 @@ describe('operator email limits', () => { expect(await preview.json()).toMatchObject({ dryRun: true, action: 'email.limit.set', - target: { projectId: project.id, slug: project.slug, monthly: 1000, burst: 25 }, - previous: { monthly: 500, burst: null }, + target: { projectId: project.id, monthly: 1000, burst: 25 }, + previous: { monthly: 500, burst: 10 }, }); - expect(await env.ROUTING.get(`email-limit:${project.id}`)).toBe('500'); - expect(await env.ROUTING.get(`email-burst-limit:${project.id}`)).toBeNull(); - const response = await req(`/email/projects/${project.slug}/limit`, { monthly: '1000', burst: '25', }); expect(response.status).toBe(200); - expect(await env.ROUTING.get(`email-limit:${project.id}`)).toBe('1000'); - expect(await env.ROUTING.get(`email-burst-limit:${project.id}`)).toBe('25'); - const recorded = await events(); - expect(recorded).toHaveLength(1); - expect(JSON.parse(recorded[0]!.target)).toEqual({ - project: project.slug, - monthly: '1000', - burst: '25', - }); - }); - - test('reports a partial cap write with 207 and a failed audit event', async () => { - const owner = await createTestUser(env.db, 'limit-partial-owner'); - const project = await createTestProject(env.db, owner.id, 'limit-partial'); - const burstKey = `email-burst-limit:${project.id}`; - await env.ROUTING.put(burstKey, '3'); - const originalPut = env.ROUTING.put.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'put').mockImplementation(async (key, value, options) => { - if (key === burstKey) { - throw new Error('burst storage down'); - } - return originalPut(key, value, options); - }); - vi.spyOn(console, 'error').mockImplementation(() => {}); - - const response = await req(`/email/projects/${project.id}/limit`, { - monthly: '1000', - burst: '25', - }); - expect(response.status).toBe(207); - expect(await response.json()).toMatchObject({ - ok: false, - partial: true, - applied: ['monthly'], - failed: ['burst'], - }); - expect(await env.ROUTING.get(`email-limit:${project.id}`)).toBe('1000'); - expect(await env.ROUTING.get(burstKey)).toBe('3'); + const control = ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, project.id)) + )[0]; + expect(control).toMatchObject({ monthly_limit: 1000, burst_limit: 25 }); expect((await events()).at(-1)).toMatchObject({ - action: `email/projects/${project.id}/limit`, - status: 'failed', + action: `email/projects/${project.slug}/limit`, + status: 'success', }); }); - test('returns kv_failed when routing storage refuses every cap', async () => { - const owner = await createTestUser(env.db, 'limit-failed-owner'); - const project = await createTestProject(env.db, owner.id, 'limit-failed'); + test('a KV failure cannot partially apply or undo database limits', async () => { + const owner = await createTestUser(env.db, 'limit-kv-owner'); + const project = await createTestProject(env.db, owner.id, 'limit-kv'); vi.spyOn(env.ROUTING, 'put').mockRejectedValue(new Error('storage down')); - vi.spyOn(console, 'error').mockImplementation(() => {}); - const response = await req(`/email/projects/${project.id}/limit`, { monthly: '1000', burst: '25', }); - expect(response.status).toBe(502); - expect(await response.json()).toMatchObject({ - error: 'kv_failed', - details: { failed: ['monthly', 'burst'] }, - }); - expect(await env.ROUTING.get(`email-limit:${project.id}`)).toBeNull(); - expect(await env.ROUTING.get(`email-burst-limit:${project.id}`)).toBeNull(); + expect(response.status).toBe(200); + const control = ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, project.id)) + )[0]; + expect(control).toMatchObject({ monthly_limit: 1000, burst_limit: 25 }); }); - test('sets one cap by project id and leaves the other override untouched', async () => { + test('sets one cap without changing the other', async () => { const owner = await createTestUser(env.db, 'limit-owner-2'); const project = await createTestProject(env.db, owner.id, 'limit-project-2'); - await env.ROUTING.put(`email-burst-limit:${project.id}`, '3'); + await setProjectEmailLimits(env.db, project.id, { burst: 3 }); const response = await req(`/email/projects/${project.id}/limit`, { monthly: '42' }); expect(response.status).toBe(200); - expect(await env.ROUTING.get(`email-limit:${project.id}`)).toBe('42'); - expect(await env.ROUTING.get(`email-burst-limit:${project.id}`)).toBe('3'); + const control = ( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, project.id)) + )[0]; + expect(control).toMatchObject({ monthly_limit: 42, burst_limit: 3 }); }); test.each([ @@ -409,16 +382,21 @@ describe('operator email limits', () => { ['a negative', { monthly: '-5' }], ['a value over the cap', { monthly: '1000001' }], ])('rejects %s with 400', async (_label, body) => { - const owner = await createTestUser(env.db, 'limit-owner-3'); - const project = await createTestProject(env.db, owner.id, 'limit-project-3'); + const owner = await createTestUser(env.db, 'limit-invalid-owner'); + const project = await createTestProject(env.db, owner.id, 'limit-invalid'); const response = await req(`/email/projects/${project.id}/limit`, body); expect(response.status).toBe(400); - expect(await env.ROUTING.get(`email-limit:${project.id}`)).toBeNull(); - expect(await env.ROUTING.get(`email-burst-limit:${project.id}`)).toBeNull(); + expect( + await env.db + .select() + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, project.id)), + ).toHaveLength(0); }); test('answers 404 for an unknown project', async () => { - const response = await req('/email/projects/no-such-project/limit', { monthly: '10' }); - expect(response.status).toBe(404); + expect((await req('/email/projects/no-such-project/limit', { monthly: '10' })).status).toBe( + 404, + ); }); }); diff --git a/platform/packages/api/test/integration/operator-operations.test.ts b/platform/packages/api/test/integration/operator-operations.test.ts index f2c0f0c5b..1726fd4cf 100644 --- a/platform/packages/api/test/integration/operator-operations.test.ts +++ b/platform/packages/api/test/integration/operator-operations.test.ts @@ -809,6 +809,7 @@ describe('operator installation-aware system and worker operations', () => { api: 'previous', dashboard: 'previous', dispatch: 'previous', + 'email-gateway': 'previous', }, }); expect(fetch.mock.calls.every(([, init]) => init?.method !== 'POST')).toBe(true); @@ -819,6 +820,7 @@ describe('operator installation-aware system and worker operations', () => { const fetch = cloudflareWorkerStub('void-dashboard-staging'); const versions = { dispatch: 'previous', + 'email-gateway': 'previous', dashboard: 'previous', api: 'previous', tail: 'previous', @@ -829,6 +831,7 @@ describe('operator installation-aware system and worker operations', () => { const result = (await response.json()) as { events: Array<{ status: string }> }; expect(result).toMatchObject({ ok: false, partial: true, environment: 'staging' }); expect(result.events.map((event: { status: string }) => event.status)).toEqual([ + 'success', 'success', 'failed', 'skipped', @@ -836,7 +839,7 @@ describe('operator installation-aware system and worker operations', () => { 'skipped', ]); const writes = fetch.mock.calls.filter(([, init]) => init?.method === 'POST'); - expect(writes).toHaveLength(2); + expect(writes).toHaveLength(3); expect(writes[0][0]).toContain('void-dispatch-staging'); expect(JSON.parse(String(writes[0][1]?.body))).toMatchObject({ versions: [{ version_id: 'previous', percentage: 100 }], diff --git a/platform/packages/api/test/unit/email-cf-customer.test.ts b/platform/packages/api/test/unit/email-cf-customer.test.ts index e921118e3..20faf304b 100644 --- a/platform/packages/api/test/unit/email-cf-customer.test.ts +++ b/platform/packages/api/test/unit/email-cf-customer.test.ts @@ -224,10 +224,12 @@ describe('cf-customer client', () => { bindings: [ { type: 'plain_text', - name: 'VOID_PROXY_ORIGIN', + name: 'VOID_EMAIL_GATEWAY_ORIGIN', text: 'https://proxy.example.test', }, - { type: 'plain_text', name: 'VOID_EMAIL_DOMAIN', text: 'acme.com' }, + { type: 'plain_text', name: 'VOID_EMAIL_ACCOUNT', text: ACCOUNT }, + { type: 'plain_text', name: 'VOID_EMAIL_ZONE', text: '' }, + { type: 'plain_text', name: 'VOID_EMAIL_INGRESS', text: RELAY }, ], }); const modulePart = formData.get('index.js') as File; diff --git a/platform/packages/api/test/unit/email-migration.test.ts b/platform/packages/api/test/unit/email-migration.test.ts new file mode 100644 index 000000000..e161b92c4 --- /dev/null +++ b/platform/packages/api/test/unit/email-migration.test.ts @@ -0,0 +1,70 @@ +import { createHash } from 'node:crypto'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { PGlite } from '@electric-sql/pglite'; +import { platformDatabaseSchemaDigest } from '@void/platform/installer'; +import { expect, it } from 'vite-plus/test'; + +it('adds the email ledger without changing tables used by the previous runtime', async () => { + const root = resolve(import.meta.dirname, '../../drizzle'); + const journal = JSON.parse(readFileSync(resolve(root, 'meta/_journal.json'), 'utf8')) as { + entries: Array<{ tag: string; idx: number; when: number }>; + }; + const emailIndex = journal.entries.findIndex((entry) => entry.tag === '0047_email_gateway'); + expect(journal.entries[emailIndex]?.idx).toBe(47); + const previous = journal.entries.slice(0, emailIndex); + const compatibility = JSON.parse(readFileSync(resolve(root, 'compatibility.json'), 'utf8')); + expect(compatibility.rollbackSafeFrom).toContainEqual({ + platformVersion: '0.20.1', + schemaDigest: platformDatabaseSchemaDigest( + compatibility.lineage, + previous.map((entry) => ({ + index: entry.idx, + tag: entry.tag, + timestampMillis: entry.when, + sha256: createHash('sha256') + .update(readFileSync(resolve(root, `${entry.tag}.sql`))) + .digest('hex'), + })), + ), + }); + const db = new PGlite(); + try { + for (const entry of previous) { + await db.exec(readFileSync(resolve(root, `${entry.tag}.sql`), 'utf8')); + } + const tables = ( + await db.query<{ tablename: string }>( + "select tablename from pg_tables where schemaname = 'public' order by tablename", + ) + ).rows.map((row) => row.tablename); + const catalog = async () => ({ + columns: ( + await db.query( + "select table_name, column_name, data_type, is_nullable, column_default from information_schema.columns where table_schema = 'public' and table_name = any($1::text[]) order by table_name, ordinal_position", + [tables], + ) + ).rows, + indexes: ( + await db.query( + "select tablename, indexname, indexdef from pg_indexes where schemaname = 'public' and tablename = any($1::text[]) order by tablename, indexname", + [tables], + ) + ).rows, + constraints: ( + await db.query( + "select conrelid::regclass::text as relation, conname, pg_get_constraintdef(oid) as definition from pg_constraint where conrelid in (select oid from pg_class where relnamespace = 'public'::regnamespace and relname = any($1::text[])) order by relation, conname", + [tables], + ) + ).rows, + }); + const before = await catalog(); + await db.exec(readFileSync(resolve(root, '0047_email_gateway.sql'), 'utf8')); + expect(await catalog()).toEqual(before); + expect((await db.query("select to_regclass('email_actions') as actions")).rows).toEqual([ + { actions: 'email_actions' }, + ]); + } finally { + await db.close(); + } +}, 15_000); diff --git a/platform/packages/api/test/unit/email-relay-engine.test.ts b/platform/packages/api/test/unit/email-relay-engine.test.ts index 867340f4d..15a1f6baf 100644 --- a/platform/packages/api/test/unit/email-relay-engine.test.ts +++ b/platform/packages/api/test/unit/email-relay-engine.test.ts @@ -74,6 +74,10 @@ function makeFakeClient(config: FakeClientConfig = {}): { record('listSendingSubdomains')(zoneId); return config.sendingSubdomains ?? []; }, + listRoutingRules: async (zoneId: string) => { + record('listRoutingRules')(zoneId); + return []; + }, relayScriptExists: async (accountId: string, scriptName: string) => { record('relayScriptExists')(accountId, scriptName); return config.scriptNamesTaken?.includes(scriptName) ?? false; @@ -82,6 +86,16 @@ function makeFakeClient(config: FakeClientConfig = {}): { record('putRelayScript')(accountId, scriptName, upload), putRelaySecret: async (accountId: string, scriptName: string, secret: string) => record('putRelaySecret')(accountId, scriptName, secret), + getWorkersSubdomain: async (accountId: string) => { + record('getWorkersSubdomain')(accountId); + return 'example'; + }, + getScriptSubdomainEnabled: async (accountId: string, scriptName: string) => { + record('getScriptSubdomainEnabled')(accountId, scriptName); + return true; + }, + enableScriptSubdomain: async (accountId: string, scriptName: string) => + record('enableScriptSubdomain')(accountId, scriptName), setCatchAll: async (zoneId: string, relayWorkerName: string) => record('setCatchAll')(zoneId, relayWorkerName), getCatchAll: async (zoneId: string) => { diff --git a/platform/packages/api/test/unit/email-relay-worker.test.ts b/platform/packages/api/test/unit/email-relay-worker.test.ts index d68be94f9..26899fec5 100644 --- a/platform/packages/api/test/unit/email-relay-worker.test.ts +++ b/platform/packages/api/test/unit/email-relay-worker.test.ts @@ -1,8 +1,10 @@ import { describe, it, expect, vi, afterEach } from 'vite-plus/test'; import { RELAY_COMPATIBILITY_DATE, - RELAY_EMAIL_DOMAIN_BINDING, - RELAY_PROXY_ORIGIN_BINDING, + RELAY_GATEWAY_ORIGIN_BINDING, + RELAY_ACCOUNT_BINDING, + RELAY_ZONE_BINDING, + RELAY_INGRESS_BINDING, RELAY_SECRET_BINDING, RELAY_SOURCE, RELAY_VERSION, @@ -53,6 +55,7 @@ type RelayMessage = { * export, so the wire test exercises the exact code the api deploys. */ function loadRelayWorker(): { + fetch: (request: Request, env: RelayEnv) => Promise; email: ( message: RelayMessage, env: RelayEnv, @@ -60,6 +63,7 @@ function loadRelayWorker(): { ) => Promise; } { const factory = new Function(RELAY_SOURCE.replace('export default', 'return')) as () => { + fetch: (request: Request, env: RelayEnv) => Promise; email: ( message: RelayMessage, env: RelayEnv, @@ -72,8 +76,10 @@ function loadRelayWorker(): { function relayContext() { const env: RelayEnv = { [RELAY_SECRET_BINDING]: RELAY_SECRET, - [RELAY_PROXY_ORIGIN_BINDING]: 'https://proxy.example.test', - [RELAY_EMAIL_DOMAIN_BINDING]: 'acme.com', + [RELAY_GATEWAY_ORIGIN_BINDING]: 'https://gateway.example.test', + [RELAY_ACCOUNT_BINDING]: 'acct_1', + [RELAY_ZONE_BINDING]: 'zone_1', + [RELAY_INGRESS_BINDING]: 'void-zone-ingress', }; const rawBytes = new TextEncoder().encode(MIME_BODY); const message: RelayMessage = { @@ -102,21 +108,23 @@ describe('RELAY_SOURCE', () => { expect(RELAY_SOURCE).toContain('export default'); expect(RELAY_SOURCE).toContain('async email(message, env, ctx)'); // No parsing, no buffering, no third-party imports. - expect(RELAY_SOURCE).not.toContain('import'); + expect(RELAY_SOURCE).not.toMatch(/^\s*import\s/m); }); it('reads exactly the binding names the uploader declares', () => { for (const binding of [ RELAY_SECRET_BINDING, - RELAY_PROXY_ORIGIN_BINDING, - RELAY_EMAIL_DOMAIN_BINDING, + RELAY_GATEWAY_ORIGIN_BINDING, + RELAY_ACCOUNT_BINDING, + RELAY_ZONE_BINDING, + RELAY_INGRESS_BINDING, ]) { expect(RELAY_SOURCE).toContain(`env.${binding}`); } expect(RELAY_COMPATIBILITY_DATE).toMatch(/^\d{4}-\d{2}-\d{2}$/); }); - it('POSTs the raw MIME to /email/relay through a FixedLengthStream with the contract-3 headers', async () => { + it('POSTs the raw MIME to the gateway through a FixedLengthStream with the zone identity', async () => { const fetchMock = vi.fn().mockResolvedValueOnce(new Response('ok', { status: 200 })); vi.stubGlobal('fetch', fetchMock); const { env, message, ctx } = relayContext(); @@ -125,14 +133,17 @@ describe('RELAY_SOURCE', () => { expect(fetchMock).toHaveBeenCalledOnce(); const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit]; - expect(url).toBe('https://proxy.example.test/email/relay'); + expect(url).toBe('https://gateway.example.test/email/ingress'); expect(init.method).toBe('POST'); // No hand-set Content-Length: the runtime ignores one on a stream body // and derives it from the FixedLengthStream instead — a plain stream // would go out chunked, and the proxy refuses a length-less body. expect(init.headers).toEqual({ Authorization: `Bearer ${RELAY_SECRET}`, - 'X-Void-Email-Domain': 'acme.com', + 'X-Void-Email-Account': 'acct_1', + 'X-Void-Email-Zone': 'zone_1', + 'X-Void-Email-Ingress': 'void-zone-ingress', + 'X-Void-Email-Request-Id': expect.stringMatching(/^[a-f0-9-]{36}$/), 'X-Void-Email-From': 'sender@example.org', 'X-Void-Email-To': 'support@acme.com', }); @@ -151,27 +162,23 @@ describe('RELAY_SOURCE', () => { expect(message.setReject).not.toHaveBeenCalled(); }); - it('refuses mail addressed to a different domain on the zone, without POSTing', async () => { - // The catch-all can be zone-wide: mail addressed to a DIFFERENT domain - // on the same zone can land here. It is not this relay's to forward — - // refuse it loudly (a bounce for the sender), never forward it under - // this domain's secret. RELAY_VERSION 3. - const fetchMock = vi.fn(); + it('forwards another domain on the same zone for exact gateway resolution', async () => { + const fetchMock = vi.fn().mockResolvedValueOnce(new Response('ok', { status: 200 })); vi.stubGlobal('fetch', fetchMock); const { env, message, ctx } = relayContext(); message.to = 'user@other-acme.com'; await loadRelayWorker().email(message, env, ctx); - expect(message.setReject).toHaveBeenCalledOnce(); - const reason = (message.setReject as ReturnType).mock.calls[0][0] as string; - expect(reason).not.toContain(RELAY_SECRET); - expect(reason).not.toContain('other-acme.com'); - expect(fetchMock).not.toHaveBeenCalled(); - expect(ctx.waitUntil).not.toHaveBeenCalled(); + expect(message.setReject).not.toHaveBeenCalled(); + expect(fetchMock).toHaveBeenCalledOnce(); + expect((fetchMock.mock.calls[0][1] as RequestInit).headers).toMatchObject({ + 'X-Void-Email-To': 'user@other-acme.com', + }); + expect(ctx.waitUntil).toHaveBeenCalledTimes(2); }); - it('matches the recipient domain against VOID_EMAIL_DOMAIN case-insensitively', async () => { + it('forwards the SMTP envelope recipient without changing its case', async () => { const fetchMock = vi.fn().mockResolvedValueOnce(new Response('ok', { status: 200 })); vi.stubGlobal('fetch', fetchMock); const { env, message, ctx } = relayContext(); @@ -183,8 +190,8 @@ describe('RELAY_SOURCE', () => { expect(fetchMock).toHaveBeenCalledOnce(); }); - it('rejects with a short generic reason on a non-2xx answer', async () => { - const fetchMock = vi.fn().mockResolvedValueOnce(new Response('nope', { status: 502 })); + it('rejects with a short generic reason on a permanent refusal', async () => { + const fetchMock = vi.fn().mockResolvedValueOnce(new Response('nope', { status: 403 })); vi.stubGlobal('fetch', fetchMock); const { env, message, ctx } = relayContext(); @@ -196,7 +203,72 @@ describe('RELAY_SOURCE', () => { expect(reason.length).toBeLessThanOrEqual(64); // The bounce goes back to the original sender — no internals leak. expect(reason).not.toContain(RELAY_SECRET); - expect(reason).not.toContain('proxy.example.test'); + expect(reason).not.toContain('gateway.example.test'); expect(reason).not.toContain('502'); }); + + it('throws temporary gateway failures without permanently rejecting the message', async () => { + vi.stubGlobal('fetch', vi.fn().mockResolvedValueOnce(new Response(null, { status: 503 }))); + const { env, message, ctx } = relayContext(); + await expect(loadRelayWorker().email(message, env, ctx)).rejects.toThrow( + 'temporarily unavailable', + ); + expect(message.setReject).not.toHaveBeenCalled(); + }); + + it('proves the deployed secret with a challenge bound to the zone and generation', async () => { + const { env } = relayContext(); + const challenge = 'a'.repeat(64); + const response = await loadRelayWorker().fetch( + new Request('https://worker.example/__void/email/probe', { + method: 'POST', + headers: { 'X-Void-Probe-Challenge': challenge, 'X-Void-Probe-Generation': '7' }, + }), + env, + ); + expect(response.status).toBe(200); + const proof = (await response.json()) as { + accountId: string; + zoneId: string; + ingressName: string; + generation: number; + challenge: string; + proof: string; + }; + expect(proof).toMatchObject({ + accountId: 'acct_1', + zoneId: 'zone_1', + ingressName: 'void-zone-ingress', + generation: 7, + challenge, + }); + const key = await crypto.subtle.importKey( + 'raw', + new TextEncoder().encode(RELAY_SECRET), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign'], + ); + const payload = [ + 'email-relay-proof-v1', + 'acct_1', + 'zone_1', + 'void-zone-ingress', + '7', + challenge, + ].join('\n'); + const expected = Array.from( + new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(payload))), + (b) => b.toString(16).padStart(2, '0'), + ).join(''); + expect(proof.proof).toBe(expected); + expect( + ( + await loadRelayWorker().fetch( + new Request('https://worker.example/__void/email/probe', { method: 'POST' }), + env, + ) + ).status, + ).toBe(400); + }); }); diff --git a/platform/packages/api/test/unit/platform-deployment-manifest.test.ts b/platform/packages/api/test/unit/platform-deployment-manifest.test.ts index 32aebb1a1..7882534d5 100644 --- a/platform/packages/api/test/unit/platform-deployment-manifest.test.ts +++ b/platform/packages/api/test/unit/platform-deployment-manifest.test.ts @@ -16,6 +16,7 @@ describe('platform deployment manifest', () => { dashboardWorker: 'void-developer-platform-experience-dashboard', dispatchNamespace: 'void-developer-platform-experience-users', dispatchWorker: 'void-developer-platform-experience-dispatch', + emailGatewayWorker: 'void-developer-platform-experience-email-gateway', hyperdrive: 'void-developer-platform-experience-database', isrCacheKv: 'void-developer-platform-experience-isr-cache', legacyAssetsKv: 'void-developer-platform-experience-legacy-assets', diff --git a/platform/packages/api/test/unit/platform-worker-config.test.ts b/platform/packages/api/test/unit/platform-worker-config.test.ts index 521b8ce72..d8bef8c26 100644 --- a/platform/packages/api/test/unit/platform-worker-config.test.ts +++ b/platform/packages/api/test/unit/platform-worker-config.test.ts @@ -17,6 +17,7 @@ describe('platform Worker configuration', () => { ownershipNonce: '0123456789abcdef0123456789abcdef', platformVersion: '1.0.0', proxyUrl: 'https://void-example-proxy.example.workers.dev', + emailGatewayUrl: 'https://void-example-email-gateway.example.workers.dev', resources: { hyperdrive: 'hyperdrive', isrCacheKv: 'isr', @@ -28,11 +29,14 @@ describe('platform Worker configuration', () => { api: '/runtime/api.js', dispatch: '/runtime/dispatch.js', proxy: '/runtime/proxy.js', + emailGateway: '/runtime/email-gateway.js', tail: '/runtime/tail.js', }, }); expect(configs.api).not.toHaveProperty('containers'); + expect(configs.emailGateway).not.toHaveProperty('send_email'); + expect(configs.emailGateway.vars).not.toHaveProperty('EMAIL_SHARED_ZONE_ID'); expect(JSON.stringify(configs)).not.toContain('BuildManager'); expect(JSON.stringify(configs)).not.toContain('BUILD_SCHEDULER'); expect(configs.proxy.vars).toMatchObject({ @@ -84,6 +88,7 @@ describe('platform Worker configuration', () => { ownershipNonce: '0123456789abcdef0123456789abcdef', platformVersion: '1.0.0', proxyUrl: 'https://proxy.example.com', + emailGatewayUrl: 'https://void-example-email-gateway.example.workers.dev', publicEndpoints: false, trafficState: 'staging', resources: { @@ -97,6 +102,7 @@ describe('platform Worker configuration', () => { api: '/runtime/api.js', dispatch: '/runtime/dispatch.js', proxy: '/runtime/proxy.js', + emailGateway: '/runtime/email-gateway.js', tail: '/runtime/tail.js', }, }); diff --git a/platform/packages/api/test/unit/reserved-bindings.test.ts b/platform/packages/api/test/unit/reserved-bindings.test.ts index b0a0f70e7..dca6ae2c1 100644 --- a/platform/packages/api/test/unit/reserved-bindings.test.ts +++ b/platform/packages/api/test/unit/reserved-bindings.test.ts @@ -107,3 +107,37 @@ describe('reserved binding names cover every platform-injected binding', () => { expect(RESERVED_BINDING_NAMES.has('__VOID_PROXY_TOKEN')).toBe(true); }); }); + +it('pins managed email to its deployment identity and reserves that binding', async () => { + const args = [ + stubDb, + 'test-account', + 'test-token', + 'proj_abc123', + { ...EMPTY_MANIFEST, emailProtocolVersion: 1 }, + 'test-jwt-secret', + 'void-proxy', + { projectSlug: 'my-app', deploymentId: 'deploy_a' }, + ] as const; + const bindings = await provisionBindings(...args); + expect(bindings).toContainEqual({ + type: 'plain_text', + name: '__VOID_EMAIL_DEPLOYMENT_ID', + text: 'deploy_a', + }); + expect(isReservedBindingName('__VOID_EMAIL_DEPLOYMENT_ID')).toBe(true); + await expect( + provisionBindings( + ...(args.slice(0, 7) as [ + (typeof args)[0], + string, + string, + string, + (typeof args)[4], + string, + string, + ]), + { projectSlug: 'my-app' }, + ), + ).rejects.toThrow('deployment identity'); +}); diff --git a/platform/packages/email-gateway/package.json b/platform/packages/email-gateway/package.json new file mode 100644 index 000000000..c5ca86f3a --- /dev/null +++ b/platform/packages/email-gateway/package.json @@ -0,0 +1,21 @@ +{ + "name": "@voidcloud/email-gateway", + "private": true, + "type": "module", + "scripts": { + "deploy": "node ../../scripts/wrangler-deploy.ts", + "dev": "wrangler dev", + "typecheck": "tsc --noEmit" + }, + "dependencies": { + "@void/platform": "workspace:*", + "@voidcloud/api": "workspace:*", + "@voidcloud/proxy": "workspace:*" + }, + "devDependencies": { + "@cloudflare/workers-types": "catalog:platform", + "typescript": "catalog:", + "vite-plus": "catalog:", + "wrangler": "catalog:platform" + } +} diff --git a/platform/packages/email-gateway/src/index.ts b/platform/packages/email-gateway/src/index.ts new file mode 100644 index 000000000..e08bbe976 --- /dev/null +++ b/platform/packages/email-gateway/src/index.ts @@ -0,0 +1,516 @@ +import { claimRelayedReceipt, completeRelayedReceipt } from '../../proxy/src/email-admission.ts'; +import { + routeInbound, + routeRelayed, + MAX_INBOUND_BYTES, + MAX_INBOUND_HEADERS, +} from '../../proxy/src/email-router.ts'; +import type { EmailEnvelope } from '../../proxy/src/email-router.ts'; +import type { Env as ProxyEnv } from '../../proxy/src/types.ts'; + +type Env = ProxyEnv & { + PLATFORM_INSTALLATION_ID?: string; + PLATFORM_TRAFFIC_STATE?: string; + EMAIL_SHARED_ACCOUNT_ID?: string; + EMAIL_SHARED_ZONE_ID?: string; + EMAIL_SHARED_INGRESS_NAME?: string; +}; + +const encoder = new TextEncoder(); +const decoder = new TextDecoder(); +const MAX_HEADER_BYTES = 128 * 1024; +const MAX_ENVELOPE_HEADER = 320; +const MAX_CONCURRENT_DELIVERIES = 2; +let activeDeliveries = 0; + +async function withDeliverySlot(run: () => Promise): Promise { + if (activeDeliveries >= MAX_CONCURRENT_DELIVERIES) { + throw new Error('email gateway busy'); + } + activeDeliveries++; + try { + return await run(); + } finally { + activeDeliveries--; + } +} + +async function sign(value: string, secret: string): Promise { + const key = await crypto.subtle.importKey( + 'raw', + encoder.encode(secret), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign'], + ); + const signature = new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(value))); + let binary = ''; + for (const byte of signature) { + binary += String.fromCharCode(byte); + } + return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', ''); +} + +type Route = { + connectionId: string; + projectId: string; + workerName: string; + deploymentId: string; + slug: string; + domain: string; + addressing: 'shared' | 'custom'; + limits?: Record; +}; + +async function resolveIngress( + env: Env, + input: { + accountId: string; + zoneId: string; + ingressName: string; + from: string; + to: string; + secret?: string; + native?: true; + }, +): Promise { + const proof = await sign( + `email-ingress-v1\n${input.accountId}\n${input.zoneId}\n${input.ingressName}\n${input.to.toLowerCase()}`, + env.JWT_SECRET, + ); + const response = await env.API.fetch('https://api/internal/email/resolve-ingress', { + method: 'POST', + headers: { 'content-type': 'application/json', 'x-void-internal': proof }, + body: JSON.stringify(input), + signal: AbortSignal.timeout(5_000), + }); + if (!response.ok) { + if (response.status >= 500 || response.status === 429) { + throw new Error('email routing unavailable'); + } + return null; + } + const contentLength = Number(response.headers.get('content-length')); + if (Number.isFinite(contentLength) && contentLength > 4096) { + return null; + } + const reader = response.body?.getReader(); + if (!reader) { + return null; + } + const chunks: Array = []; + let total = 0; + const deadline = Date.now() + 5_000; + try { + while (true) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + return null; + } + let timer: ReturnType | undefined; + const chunk = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('ingress resolution timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (chunk.done) { + break; + } + total += chunk.value.byteLength; + if (total > 4096) { + return null; + } + chunks.push(chunk.value); + } + } finally { + await reader.cancel().catch(() => {}); + reader.releaseLock(); + } + const bytes = new Uint8Array(total); + let offset = 0; + for (const chunk of chunks) { + bytes.set(chunk, offset); + offset += chunk.byteLength; + } + const text = decoder.decode(bytes); + let route: unknown; + try { + route = JSON.parse(text); + } catch { + return null; + } + if (!route || typeof route !== 'object') { + return null; + } + const value = route as Partial; + if ( + typeof value.projectId !== 'string' || + typeof value.connectionId !== 'string' || + typeof value.workerName !== 'string' || + typeof value.deploymentId !== 'string' || + typeof value.slug !== 'string' || + typeof value.domain !== 'string' || + (value.addressing !== 'shared' && value.addressing !== 'custom') + ) { + return null; + } + return value as Route; +} + +async function readMime( + stream: ReadableStream | null, + declared: number, +): Promise { + if (!stream || !Number.isSafeInteger(declared) || declared < 0 || declared > MAX_INBOUND_BYTES) { + throw new Error('invalid MIME length'); + } + const reader = stream.getReader(); + const result = new Uint8Array(declared); + let size = 0; + const deadline = Date.now() + 15_000; + try { + while (true) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('MIME timeout'); + } + let timer: ReturnType | undefined; + const chunk = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('MIME timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (chunk.done) { + break; + } + size += chunk.value.byteLength; + if (size > declared || size > MAX_INBOUND_BYTES) { + throw new Error('MIME too large'); + } + result.set(chunk.value, size - chunk.value.byteLength); + } + if (size !== declared) { + throw new Error('truncated MIME'); + } + return result; + } catch (error) { + await reader.cancel().catch(() => {}); + throw error; + } finally { + reader.releaseLock(); + } +} + +function parseHeaders(raw: Uint8Array): Record { + let end = -1; + for (let i = 0; i < raw.length - 3 && i < MAX_HEADER_BYTES + 4; i++) { + if (raw[i] === 13 && raw[i + 1] === 10 && raw[i + 2] === 13 && raw[i + 3] === 10) { + end = i; + break; + } + } + if (end < 0 || end > MAX_HEADER_BYTES) { + throw new Error('invalid MIME headers'); + } + const lines = decoder.decode(raw.subarray(0, end)).split('\r\n'); + const headers: Record = Object.create(null); + let current = ''; + let physicalLines = 0; + for (const line of lines) { + if (++physicalLines > MAX_INBOUND_HEADERS) { + throw new Error('too many MIME headers'); + } + if (/^[ \t]/.test(line)) { + if (!current) { + throw new Error('invalid MIME header fold'); + } + headers[current] += ` ${line.trim()}`; + continue; + } + const colon = line.indexOf(':'); + if (colon <= 0) { + throw new Error('invalid MIME header'); + } + const name = line.slice(0, colon).toLowerCase(); + if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name)) { + throw new Error('invalid MIME header name'); + } + headers[name] = headers[name] + ? `${headers[name]}, ${line.slice(colon + 1).trim()}` + : line.slice(colon + 1).trim(); + current = name; + } + return headers; +} + +async function ingress(request: Request, env: Env, ctx: ExecutionContext): Promise { + if (env.PLATFORM_TRAFFIC_STATE === 'staging' || env.PLATFORM_TRAFFIC_STATE === 'sandbox-drain') { + return new Response(null, { status: 503 }); + } + if (request.headers.get('content-encoding')) { + return new Response(null, { status: 415 }); + } + const accountId = request.headers.get('x-void-email-account') ?? ''; + const zoneId = request.headers.get('x-void-email-zone') ?? ''; + const ingressName = request.headers.get('x-void-email-ingress') ?? ''; + const requestId = request.headers.get('x-void-email-request-id') ?? ''; + const from = request.headers.get('x-void-email-from') ?? ''; + const to = request.headers.get('x-void-email-to') ?? ''; + const authorization = request.headers.get('authorization') ?? ''; + if ( + [accountId, zoneId, ingressName, from, to, authorization].some( + (value) => !value || value.length > MAX_ENVELOPE_HEADER, + ) || + !authorization.startsWith('Bearer ') || + !/^[a-f0-9-]{36}$/.test(requestId) + ) { + return new Response(null, { status: 400 }); + } + const declaredHeader = request.headers.get('content-length'); + if (declaredHeader === null || !/^\d+$/.test(declaredHeader)) { + return new Response(null, { status: 411 }); + } + const declared = Number(declaredHeader); + if (!Number.isSafeInteger(declared) || declared < 0) { + return new Response(null, { status: 411 }); + } + if (declared > MAX_INBOUND_BYTES) { + return new Response(null, { status: 413 }); + } + let route: Route | null; + try { + route = await resolveIngress(env, { + accountId, + zoneId, + ingressName, + from, + to, + secret: authorization.slice(7), + }); + } catch { + return new Response(null, { status: 503 }); + } + if (!route) { + return new Response(null, { status: 403 }); + } + try { + const raw = await readMime(request.body, declared); + const headers = parseHeaders(raw); + const domain = to.slice(to.lastIndexOf('@') + 1).toLowerCase(); + if (domain !== route.domain) { + return new Response(null, { status: 403 }); + } + const envelope: EmailEnvelope = { + from, + to, + raw, + rawSize: raw.byteLength, + headers, + ...(route.addressing === 'custom' ? { viaDomain: domain } : {}), + }; + const receiptId = await sha256(encoder.encode(JSON.stringify([route.connectionId, requestId]))); + const payloadDigest = await sha256( + encoder.encode(JSON.stringify([from, to, await sha256(raw)])), + ); + const identity = { receiptId, projectId: route.projectId, payloadDigest }; + let claim; + try { + claim = await claimRelayedReceipt(env, identity); + } catch (error) { + if (error instanceof Error && error.message === 'IDEMPOTENCY_CONFLICT') { + return new Response(null, { status: 409 }); + } + throw error; + } + if (claim.state === 'completed' && typeof claim.reject === 'boolean') { + return new Response(null, { + status: claim.reject ? 403 : 204, + headers: { 'x-void-email-receipt': receiptId }, + }); + } + if (claim.state !== 'claimed') { + return new Response(null, { status: 503, headers: { 'x-void-email-receipt': receiptId } }); + } + const result = await routeRelayed(env, ctx, { + projectId: route.projectId, + domain, + envelope, + authoritative: route, + receiptId, + }); + if (result.temporary) { + return new Response(null, { status: 503 }); + } + try { + await completeRelayedReceipt(env, identity, result.reject); + } catch { + // The receipt remains unresolved. Never rerun completed tenant work or + // already-submitted actions just because its final checkpoint was lost. + console.error('[email-gateway] receipt completion remains unresolved', receiptId); + } + return new Response(null, { + status: result.reject ? 403 : 204, + headers: { 'x-void-email-receipt': receiptId }, + }); + } catch (error) { + console.error( + '[email-gateway] ingress failed:', + error instanceof Error ? error.message.slice(0, 200) : 'unknown', + ); + return new Response(null, { status: 502 }); + } +} + +async function sha256(bytes: Uint8Array): Promise { + return Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)), (byte) => + byte.toString(16).padStart(2, '0'), + ).join(''); +} + +async function probe(request: Request, env: Env): Promise { + if (request.headers.get('content-encoding')) { + return new Response(null, { status: 400 }); + } + const declared = request.headers.get('content-length'); + if (declared && (!/^\d+$/.test(declared) || Number(declared) > 1024)) { + return new Response(null, { status: 400 }); + } + const authorization = request.headers.get('authorization') ?? ''; + if (!authorization.startsWith('Bearer ') || authorization.length > MAX_ENVELOPE_HEADER) { + return new Response(null, { status: 403 }); + } + const reader = request.body?.getReader(); + if (!reader) { + return new Response(null, { status: 400 }); + } + const bytes = new Uint8Array(1024); + let size = 0; + const deadline = Date.now() + 5_000; + try { + while (true) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + return new Response(null, { status: 400 }); + } + let timer: ReturnType | undefined; + const chunk = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('probe timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (chunk.done) { + break; + } + size += chunk.value.byteLength; + if (size > bytes.byteLength) { + return new Response(null, { status: 400 }); + } + bytes.set(chunk.value, size - chunk.value.byteLength); + } + } catch { + return new Response(null, { status: 400 }); + } finally { + await reader.cancel().catch(() => {}); + reader.releaseLock(); + } + if (size === 0 || (declared && size !== Number(declared))) { + return new Response(null, { status: 400 }); + } + let input: unknown; + try { + input = JSON.parse(decoder.decode(bytes.subarray(0, size))); + } catch { + return new Response(null, { status: 400 }); + } + if (!input || typeof input !== 'object') { + return new Response(null, { status: 400 }); + } + const { accountId, zoneId, ingressName } = input as Record; + if ( + [accountId, zoneId, ingressName].some( + (value) => typeof value !== 'string' || !value || value.length > MAX_ENVELOPE_HEADER, + ) + ) { + return new Response(null, { status: 400 }); + } + const proof = await sign( + `email-probe-v1\n${accountId}\n${zoneId}\n${ingressName}`, + env.JWT_SECRET, + ); + try { + const response = await env.API.fetch('https://api/internal/email/probe-ingress', { + method: 'POST', + headers: { 'content-type': 'application/json', 'x-void-internal': proof }, + body: JSON.stringify({ accountId, zoneId, ingressName, secret: authorization.slice(7) }), + signal: AbortSignal.timeout(5_000), + }); + return new Response(null, { status: response.status === 204 ? 204 : 403 }); + } catch { + return new Response(null, { status: 503 }); + } +} + +export default { + async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { + const url = new URL(request.url); + if (request.method === 'GET' && url.pathname === '/health') { + return Response.json({ ok: true }); + } + if (request.method !== 'POST') { + return new Response(null, { status: 404 }); + } + if (url.pathname === '/email/probe') { + return probe(request, env); + } + if (url.pathname === '/email/ingress') { + try { + return await withDeliverySlot(() => ingress(request, env, ctx)); + } catch { + return new Response(null, { status: 503 }); + } + } + return new Response(null, { status: 404 }); + }, + async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise { + const accountId = env.EMAIL_SHARED_ACCOUNT_ID; + const zoneId = env.EMAIL_SHARED_ZONE_ID; + const ingressName = env.EMAIL_SHARED_INGRESS_NAME; + if (!accountId || !zoneId || !ingressName) { + message.setReject('Email routing is not configured'); + return; + } + let route: Route | null; + try { + route = await resolveIngress(env, { + accountId, + zoneId, + ingressName, + from: message.from, + to: message.to, + native: true, + }); + } catch { + throw new Error('Email route temporarily unavailable'); + } + if (!route) { + message.setReject('Email route unavailable'); + return; + } + await withDeliverySlot(() => routeInbound(message, env, ctx, route)); + }, +}; diff --git a/platform/packages/email-gateway/src/tenant-dispatch.ts b/platform/packages/email-gateway/src/tenant-dispatch.ts new file mode 100644 index 000000000..f616cd950 --- /dev/null +++ b/platform/packages/email-gateway/src/tenant-dispatch.ts @@ -0,0 +1,77 @@ +import { + EMAIL_PROTOCOL_VERSION, + EMAIL_RECEIPT_PATH, + encodeEmailEnvelope, + readEmailActions, + signEmailReceipt, + type EmailWireAction, + type EmailWireEnvelope, +} from '@void/platform/email-protocol'; + +const MAX_CONCURRENT_PER_PROJECT = 8; +const active = new Map(); + +export async function dispatchBoundedEmailToTenant( + stub: Pick, + env: { JWT_SECRET: string }, + input: { + projectId: string; + deploymentId: string; + envelope: EmailWireEnvelope; + receiptId: string; + }, +): Promise<{ actions: Array; receiptId: string }> { + if (!input.deploymentId || !input.projectId) { + throw new Error('email deployment identity missing'); + } + const receiptId = input.receiptId; + if (!/^[a-f0-9-]{16,64}$/.test(receiptId)) { + throw new Error('invalid email receipt ID'); + } + const count = active.get(input.projectId) ?? 0; + if (count >= MAX_CONCURRENT_PER_PROJECT) { + throw new Error('email project concurrency exceeded'); + } + active.set(input.projectId, count + 1); + try { + const receipt = await signEmailReceipt( + { + version: EMAIL_PROTOCOL_VERSION, + receiptId, + projectId: input.projectId, + deploymentId: input.deploymentId, + recipient: input.envelope.to, + expiresAt: Date.now() + 30_000, + }, + env.JWT_SECRET, + ); + const response = await stub.fetch(`https://worker${EMAIL_RECEIPT_PATH}`, { + method: 'POST', + headers: { + 'content-type': 'application/vnd.void.email-envelope; version=1', + 'x-void-email-receipt': receipt, + 'x-void-email-recipient': input.envelope.to, + }, + body: encodeEmailEnvelope(input.envelope), + signal: AbortSignal.timeout(20_000), + }); + if ( + !response.ok || + response.headers.get('content-encoding') || + response.headers.get('content-type') !== + `application/vnd.void.email-actions; version=${EMAIL_PROTOCOL_VERSION}` || + !response.body + ) { + throw new Error(`invalid email tenant response (${response.status})`); + } + const actions = await readEmailActions(response.body, 15_000); + return { actions, receiptId }; + } finally { + const remaining = (active.get(input.projectId) ?? 1) - 1; + if (remaining === 0) { + active.delete(input.projectId); + } else { + active.set(input.projectId, remaining); + } + } +} diff --git a/platform/packages/email-gateway/test/unit/gateway.test.ts b/platform/packages/email-gateway/test/unit/gateway.test.ts new file mode 100644 index 000000000..9c5a41396 --- /dev/null +++ b/platform/packages/email-gateway/test/unit/gateway.test.ts @@ -0,0 +1,286 @@ +import { beforeEach, describe, expect, it, vi } from 'vite-plus/test'; + +const router = vi.hoisted(() => ({ routeInbound: vi.fn(), routeRelayed: vi.fn() })); +vi.mock('../../../proxy/src/email-router.ts', () => ({ + ...router, + MAX_INBOUND_BYTES: 10 * 1024 * 1024, + MAX_INBOUND_HEADERS: 1024, +})); + +import { hmacVerifyState } from '../../../api/src/auth/hmac.ts'; +import gateway from '../../src/index.ts'; + +const identityHeaders = { + authorization: 'Bearer relay-secret', + 'x-void-email-account': 'account-1', + 'x-void-email-zone': 'zone-1', + 'x-void-email-ingress': 'gateway-1', + 'x-void-email-request-id': '12345678-1234-4234-8234-123456789abc', + 'x-void-email-from': 'sender@example.net', + 'x-void-email-to': 'support@example.com', +}; +const route = { + connectionId: 'connection-1', + projectId: 'project-1', + slug: 'support', + deploymentId: 'deployment-1', + workerName: 'worker-1', + addressing: 'custom', + domain: 'example.com', +}; +const context = { waitUntil: vi.fn() } as unknown as ExecutionContext; +const env = (apiFetch: (...args: Array) => Promise) => + ({ + JWT_SECRET: 'platform-secret', + API: { fetch: apiFetch }, + EMAIL_SHARED_ACCOUNT_ID: 'account-1', + EMAIL_SHARED_ZONE_ID: 'zone-1', + EMAIL_SHARED_INGRESS_NAME: 'gateway-1', + }) as never; + +function request(body: BodyInit, headers: Record = {}) { + return new Request('https://gateway.example/email/ingress', { + method: 'POST', + body, + headers: { + ...identityHeaders, + 'content-length': String(body instanceof Uint8Array ? body.byteLength : 0), + ...headers, + }, + ...(body instanceof ReadableStream ? { duplex: 'half' as const } : {}), + } as RequestInit); +} + +beforeEach(() => { + router.routeInbound.mockReset(); + router.routeRelayed.mockReset(); + router.routeRelayed.mockResolvedValue({ reject: false }); +}); + +describe('dedicated email gateway', () => { + function receiptApi() { + const receipts = new Map(); + return vi.fn(async (url: unknown, init?: unknown) => { + if (String(url).endsWith('/resolve-ingress')) { + return Response.json(route); + } + const request = new Request(String(url), init as RequestInit); + const raw = await request.text(); + expect( + await hmacVerifyState(raw, request.headers.get('x-void-internal') ?? '', 'platform-secret'), + ).toBe(true); + const input = JSON.parse(raw); + const existing = receipts.get(input.receiptId); + if (String(url).endsWith('/receipts/claim')) { + if (!existing) { + receipts.set(input.receiptId, { digest: input.payloadDigest }); + return Response.json({ state: 'claimed' }); + } + if (existing.digest !== input.payloadDigest) { + return Response.json({ error: 'content conflict' }, { status: 409 }); + } + return Response.json( + existing.reject === undefined + ? { state: 'in_progress' } + : { state: 'completed', reject: existing.reject }, + ); + } + expect(String(url)).toContain('/receipts/complete'); + existing!.reject = input.reject; + return Response.json({ ok: true }); + }); + } + + it('deduplicates completed HTTP attempts and binds the invocation to sender, recipient and MIME', async () => { + const environment = env(receiptApi()); + const raw = new TextEncoder().encode('From: sender@example.net\r\n\r\nbody'); + const first = await gateway.fetch(request(raw), environment, context); + expect(first.status).toBe(204); + expect(first.headers.get('x-void-email-receipt')).toMatch(/^[a-f0-9]{64}$/); + expect((await gateway.fetch(request(raw), environment, context)).status).toBe(204); + for (const headers of [ + { 'x-void-email-from': 'other@example.net' }, + { 'x-void-email-to': 'other@example.com' }, + ]) { + expect((await gateway.fetch(request(raw, headers), environment, context)).status).toBe(409); + } + expect( + ( + await gateway.fetch( + request(new TextEncoder().encode('From: sender@example.net\r\n\r\nchanged')), + environment, + context, + ) + ).status, + ).toBe(409); + expect(router.routeRelayed).toHaveBeenCalledTimes(1); + }); + + it('does not rerun an in-progress invocation on a concurrent duplicate', async () => { + const environment = env(receiptApi()); + let finish!: () => void; + let started!: () => void; + const entered = new Promise((resolve) => { + started = resolve; + }); + router.routeRelayed.mockImplementationOnce(async () => { + started(); + await new Promise((resolve) => { + finish = resolve; + }); + return { reject: false }; + }); + const raw = new TextEncoder().encode('From: sender@example.net\r\n\r\nbody'); + const first = gateway.fetch(request(raw), environment, context); + await entered; + expect((await gateway.fetch(request(raw), environment, context)).status).toBe(503); + finish(); + expect((await first).status).toBe(204); + expect(router.routeRelayed).toHaveBeenCalledTimes(1); + }); + + it('preserves transient routing failures for both HTTP and native ingress', async () => { + const environment = env(async () => new Response(null, { status: 503 })); + expect((await gateway.fetch(request(new Uint8Array()), environment, context)).status).toBe(503); + const message = { + from: 'sender@example.net', + to: 'support@example.com', + setReject: vi.fn(), + } as unknown as ForwardableEmailMessage; + await expect(gateway.email(message, environment, context)).rejects.toThrow( + 'temporarily unavailable', + ); + expect(message.setReject).not.toHaveBeenCalled(); + }); + it('authenticates ingress before consuming MIME bytes', async () => { + const pulled = vi.fn(() => { + throw new Error('body must stay unread'); + }); + const body = new ReadableStream({ pull: pulled }, { highWaterMark: 0 }); + const response = await gateway.fetch( + request(body, { 'content-length': '5' }), + env(async () => new Response(null, { status: 403 })), + context, + ); + expect(response.status).toBe(403); + expect(pulled).not.toHaveBeenCalled(); + }); + + it('rejects oversize MIME before route resolution or body reading', async () => { + const apiFetch = vi.fn(); + const response = await gateway.fetch( + request(new Uint8Array(), { 'content-length': String(10 * 1024 * 1024 + 1) }), + env(apiFetch), + context, + ); + expect(response.status).toBe(413); + expect(apiFetch).not.toHaveBeenCalled(); + }); + + it('requires complete ingress identity', async () => { + const apiFetch = vi.fn(); + const response = await gateway.fetch( + request(new Uint8Array(), { 'x-void-email-zone': '' }), + env(apiFetch), + context, + ); + expect(response.status).toBe(400); + expect(apiFetch).not.toHaveBeenCalled(); + }); + + it('counts repeated physical MIME headers before routing to a tenant', async () => { + const raw = new TextEncoder().encode(`${'X-A: value\r\n'.repeat(1025)}\r\nbody`); + const response = await gateway.fetch( + request(raw), + env(async () => Response.json(route)), + context, + ); + expect(response.status).toBe(502); + expect(router.routeRelayed).not.toHaveBeenCalled(); + }); + + it('limits concurrent deliveries per isolate', async () => { + let finish!: (response: Response) => void; + const pending = new Promise((resolve) => { + finish = resolve; + }); + const environment = env(async () => pending); + const first = gateway.fetch(request(new Uint8Array()), environment, context); + const second = gateway.fetch(request(new Uint8Array()), environment, context); + const third = await gateway.fetch(request(new Uint8Array()), environment, context); + expect(third.status).toBe(503); + finish(new Response(null, { status: 403 })); + expect((await first).status).toBe(403); + expect((await second).status).toBe(403); + }); + + it('passes an authenticated custom domain on the platform zone to the native email router', async () => { + const rejects: Array = []; + const message = { + from: 'sender@example.net', + to: 'support@example.com', + setReject: (reason: string) => rejects.push(reason), + } as ForwardableEmailMessage; + await gateway.email( + message, + env(async (url, init) => { + expect(url).toBe('https://api/internal/email/resolve-ingress'); + const request = new Request(String(url), init as RequestInit); + const identity = (await request.json()) as Record; + expect(identity).toMatchObject({ + accountId: 'account-1', + zoneId: 'zone-1', + ingressName: 'gateway-1', + native: true, + }); + expect( + await hmacVerifyState( + 'email-ingress-v1\naccount-1\nzone-1\ngateway-1\nsupport@example.com', + request.headers.get('x-void-internal') ?? '', + 'platform-secret', + ), + ).toBe(true); + return Response.json(route); + }), + context, + ); + expect(rejects).toEqual([]); + expect(router.routeInbound).toHaveBeenCalledWith(message, expect.anything(), context, route); + }); + + it('probes exact staged ingress identity through the authoritative API', async () => { + const body = JSON.stringify({ + accountId: 'account-1', + zoneId: 'zone-1', + ingressName: 'gateway-1', + }); + const probe = new Request('https://gateway.example/email/probe', { + method: 'POST', + body, + headers: { authorization: 'Bearer staged-secret', 'content-type': 'application/json' }, + }); + const response = await gateway.fetch( + probe, + env(async (url, init) => { + expect(url).toBe('https://api/internal/email/probe-ingress'); + const request = new Request(String(url), init as RequestInit); + expect( + await hmacVerifyState( + 'email-probe-v1\naccount-1\nzone-1\ngateway-1', + request.headers.get('x-void-internal') ?? '', + 'platform-secret', + ), + ).toBe(true); + expect(await request.json()).toEqual({ + accountId: 'account-1', + zoneId: 'zone-1', + ingressName: 'gateway-1', + secret: 'staged-secret', + }); + return new Response(null, { status: 204 }); + }), + context, + ); + expect(response.status).toBe(204); + }); +}); diff --git a/platform/packages/email-gateway/tsconfig.json b/platform/packages/email-gateway/tsconfig.json new file mode 100644 index 000000000..0366da85c --- /dev/null +++ b/platform/packages/email-gateway/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "lib": ["ES2022"], + "moduleResolution": "NodeNext", + "strict": true, + "skipLibCheck": true, + "noEmit": true, + "types": ["@cloudflare/workers-types"], + "allowImportingTsExtensions": true + }, + "include": ["src"] +} diff --git a/platform/packages/email-gateway/wrangler.jsonc b/platform/packages/email-gateway/wrangler.jsonc new file mode 100644 index 000000000..ae8e20114 --- /dev/null +++ b/platform/packages/email-gateway/wrangler.jsonc @@ -0,0 +1,32 @@ +{ + "name": "void-email-gateway", + "main": "src/index.ts", + "compatibility_date": "2026-09-01", + "compatibility_flags": ["nodejs_compat"], + "workers_dev": true, + "services": [{ "binding": "API", "service": "void-api" }], + "dispatch_namespaces": [{ "binding": "DISPATCH", "namespace": "void-users" }], + "kv_namespaces": [{ "binding": "ROUTING", "id": "9250c33f3db6494ebe8ad6272812c8c0" }], + "send_email": [{ "name": "SEND_EMAIL" }], + "vars": { "EMAIL_SENDER_DOMAIN": "mail.void.cloud" }, + "env": { + "production": { + "name": "void-email-gateway", + "workers_dev": true, + "services": [{ "binding": "API", "service": "void-api" }], + "dispatch_namespaces": [{ "binding": "DISPATCH", "namespace": "void-users" }], + "kv_namespaces": [{ "binding": "ROUTING", "id": "9250c33f3db6494ebe8ad6272812c8c0" }], + "send_email": [{ "name": "SEND_EMAIL" }], + "vars": { "EMAIL_SENDER_DOMAIN": "mail.void.cloud" }, + }, + "staging": { + "name": "void-email-gateway-staging", + "workers_dev": true, + "services": [{ "binding": "API", "service": "void-api-staging" }], + "dispatch_namespaces": [{ "binding": "DISPATCH", "namespace": "void-users-staging" }], + "kv_namespaces": [{ "binding": "ROUTING", "id": "60240eecea804f39bf8b7395cd6c6b08" }], + "send_email": [{ "name": "SEND_EMAIL" }], + "vars": { "EMAIL_SENDER_DOMAIN": "mail.staging.void.cloud" }, + }, + }, +} diff --git a/platform/packages/proxy/package.json b/platform/packages/proxy/package.json index 0f6c276c9..2fc998465 100644 --- a/platform/packages/proxy/package.json +++ b/platform/packages/proxy/package.json @@ -8,6 +8,7 @@ "typecheck": "tsc --noEmit" }, "dependencies": { + "@void/platform": "workspace:*", "@voidcloud/api": "workspace:*", "email-validator": "^2.0.4", "hono": "catalog:platform" diff --git a/platform/packages/proxy/src/email-admission.ts b/platform/packages/proxy/src/email-admission.ts new file mode 100644 index 000000000..441938c00 --- /dev/null +++ b/platform/packages/proxy/src/email-admission.ts @@ -0,0 +1,249 @@ +import type { Env } from './types.ts'; + +export type ActionRecipient = { + recipient: string; + state: + | 'rejected' + | 'reserved' + | 'attempt_started' + | 'provider_accepted' + | 'failed' + | 'outcome_unknown' + | 'cancelled'; + errorCode: string | null; + providerReference: string | null; +}; +export type Admission = { + operationId: string; + replay: boolean; + recipients: Array; + accountId?: string; +}; + +const encoder = new TextEncoder(); +const decoder = new TextDecoder(); + +async function sign(data: string, secret: string): Promise { + const key = await crypto.subtle.importKey( + 'raw', + encoder.encode(secret), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign'], + ); + const bytes = new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(data))); + return btoa(String.fromCharCode(...bytes)) + .replace(/\+/g, '-') + .replace(/\//g, '_') + .replace(/=+$/, ''); +} + +async function call( + env: Pick, + path: string, + body: unknown, +): Promise { + const raw = JSON.stringify(body); + const response = await env.API.fetch(`https://api/internal/email/actions${path}`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + 'x-void-internal': await sign(raw, env.JWT_SECRET), + }, + body: raw, + signal: AbortSignal.timeout(5_000), + }); + if (!response.ok) { + if (response.status === 409) { + throw new Error('IDEMPOTENCY_CONFLICT'); + } + throw new Error(`EMAIL_ADMISSION_${response.status}`); + } + const reader = response.body?.getReader(); + if (!reader) { + throw new Error('EMAIL_ADMISSION_EMPTY_RESPONSE'); + } + const bytes = new Uint8Array(65_536); + let size = 0; + const deadline = Date.now() + 5_000; + try { + for (;;) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('EMAIL_ADMISSION_TIMEOUT'); + } + let timer: ReturnType | undefined; + const chunk = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('EMAIL_ADMISSION_TIMEOUT')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (chunk.done) { + break; + } + if (size + chunk.value.byteLength > bytes.length) { + throw new Error('EMAIL_ADMISSION_RESPONSE_TOO_LARGE'); + } + bytes.set(chunk.value, size); + size += chunk.value.byteLength; + } + return JSON.parse(decoder.decode(bytes.subarray(0, size))) as T; + } finally { + void reader.cancel().catch(() => {}); + reader.releaseLock(); + } +} + +export type RelayedReceiptIdentity = { + receiptId: string; + projectId: string; + payloadDigest: string; +}; + +export function claimRelayedReceipt( + env: Pick, + identity: RelayedReceiptIdentity, +): Promise<{ state: 'claimed' | 'in_progress' | 'completed'; reject?: boolean }> { + return call(env, '/receipts/claim', identity); +} + +export function completeRelayedReceipt( + env: Pick, + identity: RelayedReceiptIdentity, + reject: boolean, +): Promise<{ ok: true }> { + return call(env, '/receipts/complete', { ...identity, reject }); +} + +/** Only generated, transport-irrelevant MIME fields are normalized. Body text stays byte-sensitive. */ +export function canonicalizeVoidMime(raw: Uint8Array): Uint8Array { + const mime = decoder.decode(raw); + if (!mime.includes('\r\n\r\n')) { + return raw; + } + const lines = mime.split('\r\n'); + const boundaries = new Map(); + const output: Array = []; + let inHeaders = true; + let topHeaders = true; + for (const line of lines) { + if (inHeaders) { + if (line === '') { + output.push(line); + inHeaders = false; + topHeaders = false; + continue; + } + if (topHeaders && /^(?:Date|Message-ID): /i.test(line)) { + continue; + } + if (/^Content-Type:\s*multipart\//i.test(line)) { + output.push( + line.replace( + /boundary="(=_void_(?:mixed|alternative|related)_[A-Za-z0-9_-]+)"/g, + (_, token: string) => { + let marker = boundaries.get(token); + if (!marker) { + marker = ``; + boundaries.set(token, marker); + } + return `boundary="${marker}"`; + }, + ), + ); + continue; + } + output.push(line); + continue; + } + let delimiter = false; + for (const [token, marker] of boundaries) { + if (line === `--${token}`) { + output.push(`--${marker}`); + inHeaders = true; + delimiter = true; + break; + } + if (line === `--${token}--`) { + output.push(`--${marker}--`); + delimiter = true; + break; + } + } + if (!delimiter) { + output.push(line); + } + } + return encoder.encode(output.join('\r\n')); +} + +export async function emailPayloadDigest( + kind: string, + from: string, + recipients: Array, + raw: Uint8Array, +): Promise { + const canonical = canonicalizeVoidMime(raw); + const prefix = encoder.encode( + JSON.stringify({ + kind, + from: from.toLowerCase(), + recipients: [...new Set(recipients.map((r) => r.toLowerCase()))].sort(), + }), + ); + const input = new Uint8Array(prefix.length + 1 + canonical.length); + input.set(prefix); + input[prefix.length] = 0; + input.set(canonical, prefix.length + 1); + return [...new Uint8Array(await crypto.subtle.digest('SHA-256', input))] + .map((b) => b.toString(16).padStart(2, '0')) + .join(''); +} + +export function admitEmail( + env: Pick, + body: { + projectId: string; + kind: 'direct' | 'forward' | 'reply'; + key: string; + digest: string; + from: string; + recipients: Array; + transport: 'binding' | 'send_raw' | 'native_forward' | 'native_reply'; + receiptId?: string; + }, +): Promise { + return call(env, '/admit', body); +} + +export function startEmailAttempt( + env: Pick, + operationId: string, + recipients: Array, +): Promise<{ recipients: Array }> { + return call(env, `/${encodeURIComponent(operationId)}/start`, { recipients }); +} + +export function finishEmailAttempt( + env: Pick, + operationId: string, + recipients: Array, + state: 'provider_accepted' | 'failed' | 'outcome_unknown' | 'cancelled', + details: { providerReference?: string; errorCode?: string } = {}, +): Promise<{ recipients: Array }> { + return call(env, `/${encodeURIComponent(operationId)}/finish`, { recipients, state, ...details }); +} + +export function recordEmailReceipt( + env: Pick, + receiptId: string, + projectId: string, + status: string, +): Promise<{ ok: true }> { + return call(env, '/receipts', { receiptId, projectId, status }); +} diff --git a/platform/packages/proxy/src/email-lease.ts b/platform/packages/proxy/src/email-lease.ts index 0a1967f75..70ce88abc 100644 --- a/platform/packages/proxy/src/email-lease.ts +++ b/platform/packages/proxy/src/email-lease.ts @@ -19,9 +19,8 @@ * The api owns the OAuth refresh chain (serialized per row, the rotated * refresh token persisted atomically with it) and returns a fresh access * token on every lease — there is no access-token cache on the api side. - * The proxy caches the leased credential in-memory per domain for at most - * 45 minutes; the OAuth access token (~1 hour) outlives that, so a cached - * lease is never used past its own validity. + * The proxy requests a fresh lease for every provider submission so a + * revoked or rotated credential cannot be reused from an isolate cache. * * A leased credential is a customer secret: it is never logged, never * interpolated into an error message, and never leaves this module except @@ -31,34 +30,18 @@ import type { Env } from './types.ts'; export type EmailDomainLease = - | { kind: 'api_token'; token: string } - | { kind: 'oauth_grant'; accessToken: string }; - -/** The contract's ceiling for the proxy-side cache: at most 45 minutes. */ -const LEASE_CACHE_TTL_MS = 45 * 60 * 1000; - -interface LeaseCacheEntry { - lease: EmailDomainLease; - expiresAt: number; -} - -// In-memory per-isolate cache, keyed by domain. Same pattern as -// resolve.ts's resource cache. -const leaseCache = new Map(); + | { kind: 'api_token'; token: string; accountId: string } + | { kind: 'oauth_grant'; accessToken: string; accountId: string }; /** @internal Exposed for testing only. */ -export function clearEmailDomainLeaseCache(): void { - leaseCache.clear(); -} +export function clearEmailDomainLeaseCache(): void {} /** * Drop one cached lease. Called when Cloudflare refused the credential * (401/403 from send_raw) so the next send re-leases instead of replaying a * credential the api may already have marked revoked. */ -export function dropEmailDomainLease(domain: string): void { - leaseCache.delete(domain); -} +export function dropEmailDomainLease(_domain: string): void {} /** The bearer value for the send_raw Authorization header. */ export function leaseBearer(lease: EmailDomainLease): string { @@ -74,21 +57,21 @@ export function leaseBearer(lease: EmailDomainLease): string { export async function leaseEmailDomainCredential( env: Pick, domain: string, + projectId: string, ): Promise { - const cached = leaseCache.get(domain); - if (cached && cached.expiresAt > Date.now()) { - return cached.lease; - } let res: Response; try { - const token = await hmacSign(domain, env.JWT_SECRET); + const token = await hmacSign( + `email-lease-v1\n${projectId}\n${domain.toLowerCase()}`, + env.JWT_SECRET, + ); res = await env.API.fetch('https://api/internal/email/domain-credential', { method: 'POST', headers: { 'content-type': 'application/json', 'x-void-internal': token, }, - body: JSON.stringify({ domain }), + body: JSON.stringify({ domain, projectId }), }); } catch { return null; @@ -106,7 +89,6 @@ export async function leaseEmailDomainCredential( if (!lease) { return null; } - leaseCache.set(domain, { lease, expiresAt: Date.now() + LEASE_CACHE_TTL_MS }); return lease; } @@ -115,13 +97,19 @@ function parseLease(data: unknown): EmailDomainLease | null { return null; } const kind = (data as { kind?: unknown }).kind; + const accountId = (data as { accountId?: unknown }).accountId; + if (typeof accountId !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(accountId)) { + return null; + } if (kind === 'api_token') { const token = (data as { token?: unknown }).token; - return typeof token === 'string' && token.length > 0 ? { kind, token } : null; + return typeof token === 'string' && token.length > 0 ? { kind, token, accountId } : null; } if (kind === 'oauth_grant') { const accessToken = (data as { accessToken?: unknown }).accessToken; - return typeof accessToken === 'string' && accessToken.length > 0 ? { kind, accessToken } : null; + return typeof accessToken === 'string' && accessToken.length > 0 + ? { kind, accessToken, accountId } + : null; } return null; } diff --git a/platform/packages/proxy/src/email-router.ts b/platform/packages/proxy/src/email-router.ts index 191c4cad6..4075b1578 100644 --- a/platform/packages/proxy/src/email-router.ts +++ b/platform/packages/proxy/src/email-router.ts @@ -25,6 +25,14 @@ import { isReservedEmailSlug } from '@voidcloud/api/reserved-slugs'; import { EmailMessage } from 'cloudflare:email'; import { validate as isValidEmailSyntax } from 'email-validator'; +import { dispatchBoundedEmailToTenant } from '../../email-gateway/src/tenant-dispatch.ts'; +import { + admitEmail, + emailPayloadDigest, + finishEmailAttempt, + recordEmailReceipt, + startEmailAttempt, +} from './email-admission.ts'; import { dropEmailDomainLease, leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; import { VERIFIED_ONLY, @@ -117,6 +125,7 @@ function describeUntrusted(value: unknown, maxLen: number): string { interface RoutingEntry { workerName?: string; projectId?: string; + version?: string; /** * Per-project dispatch limits (`{ cpuMs?, subRequests? }`), written by the * api worker and applied by `packages/dispatch` on every HTTP request. @@ -136,6 +145,16 @@ interface RoutingEntry { // we only care about these here. } +export interface AuthoritativeEmailRoute { + projectId: string; + workerName: string; + deploymentId: string; + slug: string; + addressing: 'shared' | 'custom'; + domain?: string; + limits?: Record; +} + /** * Mirrors `void/email`'s EmailEnvelope. RPC-safe primitives only. * @@ -227,6 +246,7 @@ export const MAX_INBOUND_BYTES = 10 * 1024 * 1024; * `MAX_INBOUND_HEADERS + 1` pairs. */ export const MAX_INBOUND_HEADERS = 1024; +export const MAX_INBOUND_HEADER_BYTES = 128 * 1024; /** * Cap user-supplied reject reasons — surfaced to remote MTAs and our logs. @@ -300,7 +320,7 @@ export const MAX_FORWARD_HEADER_LENGTH = 1024; * failure is logged here and the reply silently never goes out). Checked * BEFORE `readMimeFromAddrSpec`, whose scan is linear in `raw`. */ -const MAX_REPLY_BYTES = MAX_MIME_BYTES; +const MAX_REPLY_BYTES = 5 * 1024 * 1024; /** * Cumulative reply-byte budget for ONE delivery. Twin of the framework's @@ -313,7 +333,7 @@ const MAX_REPLY_BYTES = MAX_MIME_BYTES; * injection attempt is the worse failure. An oversized reply is a resource * bound, and the in-budget replies cost no more than a compliant list. */ -const MAX_REPLY_BYTES_TOTAL = 2 * MAX_REPLY_BYTES; +const MAX_REPLY_BYTES_TOTAL = 8 * 1024 * 1024; // workerd's RPC layer throws TypeError with messages like // "The RPC receiver does not implement the method 'X'". Match a couple of @@ -336,6 +356,13 @@ class InboundTooManyHeadersError extends Error { } } +class InboundHeadersTooLargeError extends Error { + constructor() { + super(`inbound headers exceed ${MAX_INBOUND_HEADER_BYTES} bytes`); + this.name = 'InboundHeadersTooLargeError'; + } +} + /** * The address rule for `forward.to`, `reply.from` and `reply.to`: * `email-validator`, the SAME package the framework's `validateAddressParts` @@ -475,6 +502,9 @@ function forwardHeadersWithinBounds(headers: unknown): headers is Record 0 && localPrefix === pin.slug) { return true; } - // Fall through: the received domain may itself be registered to the - // receiving project — on the relay lane it always is — in which case - // any address on it is a permitted sender. + if (pin.authoritative) { + return false; + } } + if (pin.authoritative) { + return true; + } // PostgreSQL admission checks exact sender ownership. return isRegisteredDomainSender(fromDomain, pin); } @@ -626,6 +662,7 @@ async function getMonthlyLimit(kv: KVNamespace, projectId: string): Promise { // Every reject reason is prefixed with the zone this router serves, so a // bounce tells the remote MTA which platform environment refused it. The @@ -684,98 +722,119 @@ export async function routeInbound( // entry, whatever its origin, can hand a reserved mailbox to a worker. // The reject matches what an unclaimed slug gets today: there is no // platform mailbox behind these addresses either. - if (isReservedEmailSlug(slug)) { + if (authoritative?.addressing !== 'custom' && isReservedEmailSlug(slug)) { message.setReject(`${label}: "${sanitize(slug, 64)}" is a reserved platform address`); return; } - // Look up project routing — same KV the HTTP dispatcher uses. - const routingJson = await env.ROUTING.get(slug); - if (!routingJson) { - message.setReject(`${label}: no project found for slug "${sanitize(slug, 64)}"`); - return; - } + let routing: RoutingEntry; + let workerName: string; + if (authoritative) { + if ( + !authoritative.projectId || + !authoritative.workerName || + (authoritative.domain && authoritative.domain.toLowerCase() !== receivedDomain) || + (authoritative.addressing === 'shared' && authoritative.slug.toLowerCase() !== slug) + ) { + message.setReject(`${label}: authoritative route mismatch`); + return; + } + workerName = authoritative.workerName; + routing = { + projectId: authoritative.projectId, + workerName, + version: authoritative.deploymentId, + limits: authoritative.limits, + }; + } else { + // Look up project routing — same KV the HTTP dispatcher uses. + const routingJson = await env.ROUTING.get(slug); + if (!routingJson) { + message.setReject(`${label}: no project found for slug "${sanitize(slug, 64)}"`); + return; + } - let parsedRouting: unknown; - try { - parsedRouting = JSON.parse(routingJson); - } catch { - message.setReject(`${label}: routing data corrupt`); - return; - } - // `JSON.parse` also succeeds on `null`, on a bare number and on a string, - // none of which carry a suspension marker to read. Every producer of this - // value writes a `JSON.stringify`d object, so there is no legitimate writer - // of a non-object entry — treat one as corrupt rather than reaching for - // `.suspended` on it. Reading it as "not suspended" would disable the - // platform-wide gate for exactly the project whose entry got corrupted, - // which is the same reason the outbound path fails closed on `corrupt`. - if (typeof parsedRouting !== 'object' || parsedRouting === null) { - message.setReject(`${label}: routing data corrupt`); - return; - } - const routing = parsedRouting as RoutingEntry; - - // Platform-wide suspension — the marker `packages/dispatch` answers with a - // 429. Checked BEFORE dispatch (and before the email-only kill-switch) so - // a suspended tenant's code never runs on platform CPU, and so a project - // suspended for abuse loses inbound and outbound mail at the same moment - // it loses HTTP. - if (routing.suspended) { - // The marker is declared `string`, but it arrives from KV — a non-string - // value would crash `sanitize`, which turns a suspended project into an - // unhandled handler error instead of a clean refusal. - const reason = typeof routing.suspended === 'string' ? routing.suspended : 'suspended'; - message.setReject( - `${label}: project "${sanitize(slug, 64)}" is suspended (${sanitize(reason, 64)})`, - ); - return; - } + let parsedRouting: unknown; + try { + parsedRouting = JSON.parse(routingJson); + } catch { + message.setReject(`${label}: routing data corrupt`); + return; + } + // `JSON.parse` also succeeds on `null`, on a bare number and on a string, + // none of which carry a suspension marker to read. Every producer of this + // value writes a `JSON.stringify`d object, so there is no legitimate writer + // of a non-object entry — treat one as corrupt rather than reaching for + // `.suspended` on it. Reading it as "not suspended" would disable the + // platform-wide gate for exactly the project whose entry got corrupted, + // which is the same reason the outbound path fails closed on `corrupt`. + if (typeof parsedRouting !== 'object' || parsedRouting === null) { + message.setReject(`${label}: routing data corrupt`); + return; + } + routing = parsedRouting as RoutingEntry; + + // Platform-wide suspension — the marker `packages/dispatch` answers with a + // 429. Checked BEFORE dispatch (and before the email-only kill-switch) so + // a suspended tenant's code never runs on platform CPU, and so a project + // suspended for abuse loses inbound and outbound mail at the same moment + // it loses HTTP. + if (routing.suspended) { + // The marker is declared `string`, but it arrives from KV — a non-string + // value would crash `sanitize`, which turns a suspended project into an + // unhandled handler error instead of a clean refusal. + const reason = typeof routing.suspended === 'string' ? routing.suspended : 'suspended'; + message.setReject( + `${label}: project "${sanitize(slug, 64)}" is suspended (${sanitize(reason, 64)})`, + ); + return; + } - const workerName = routing.workerName; - if (!workerName) { - // Static-only deploys (KV/R2 path) don't have a worker — nothing to - // dispatch inbound mail to. - message.setReject(`${label}: project "${sanitize(slug, 64)}" has no worker (static deploy)`); - return; - } - // Declared `string`, but it arrives from KV like `suspended` does. Every - // failure handler below renders the name through `sanitize`, which throws - // on a non-string — a worker that cannot be reached would then surface as - // an unhandled handler error instead of a reject. `buildRoutingJson` only - // ever writes a string, so anything else is corrupt data, refused the same - // way as a non-object blob. - if (typeof workerName !== 'string') { - message.setReject(`${label}: routing data corrupt`); - return; - } + workerName = routing.workerName ?? ''; + if (!workerName) { + // Static-only deploys (KV/R2 path) don't have a worker — nothing to + // dispatch inbound mail to. + message.setReject(`${label}: project "${sanitize(slug, 64)}" has no worker (static deploy)`); + return; + } + // Declared `string`, but it arrives from KV like `suspended` does. Every + // failure handler below renders the name through `sanitize`, which throws + // on a non-string — a worker that cannot be reached would then surface as + // an unhandled handler error instead of a reject. `buildRoutingJson` only + // ever writes a string, so anything else is corrupt data, refused the same + // way as a non-object blob. + if (typeof workerName !== 'string') { + message.setReject(`${label}: routing data corrupt`); + return; + } - // `projectId` arrives from KV the same way. The email-only kill-switch - // below is keyed `email-suspended:`, and a template literal - // coerces whatever is there — a number, an object, an empty string — into - // a key that names no real project, so the lookup misses and a suspended - // tenant keeps receiving mail. Every failure handler after dispatch also - // renders the id through `sanitize`, which throws on a non-string. Every - // writer of a worker routing has put a string id in the blob since the - // first one (`buildRoutingJson` types it, and there is no static-deploy - // reading for a missing id the way there is for a missing `workerName`), - // so absent, empty or mistyped is corrupt data and is refused the same - // way — the suspension state cannot be read, so the message must not run. - if (typeof routing.projectId !== 'string' || routing.projectId === '') { - message.setReject(`${label}: routing data corrupt`); - return; - } + // `projectId` arrives from KV the same way. The email-only kill-switch + // below is keyed `email-suspended:`, and a template literal + // coerces whatever is there — a number, an object, an empty string — into + // a key that names no real project, so the lookup misses and a suspended + // tenant keeps receiving mail. Every failure handler after dispatch also + // renders the id through `sanitize`, which throws on a non-string. Every + // writer of a worker routing has put a string id in the blob since the + // first one (`buildRoutingJson` types it, and there is no static-deploy + // reading for a missing id the way there is for a missing `workerName`), + // so absent, empty or mistyped is corrupt data and is refused the same + // way — the suspension state cannot be read, so the message must not run. + if (typeof routing.projectId !== 'string' || routing.projectId === '') { + message.setReject(`${label}: routing data corrupt`); + return; + } - // Email-only suspend kill-switch — the narrower control, set by the admin - // UI to stop mail without taking the whole project offline. Gates inbound - // as well as outbound so a suspended project doesn't keep accepting + - // dispatching mail (which costs CPU and storage on the user worker). - // No cacheTtl: this is an abuse-response control; we eat the extra KV - // get per inbound message so a suspend takes effect immediately - // (subject only to KV's ~near-instant per-colo consistency). - if (await env.ROUTING.get(`email-suspended:${routing.projectId}`)) { - message.setReject(`${label}: project "${sanitize(slug, 64)}" inbound is suspended`); - return; + // Email-only suspend kill-switch — the narrower control, set by the admin + // UI to stop mail without taking the whole project offline. Gates inbound + // as well as outbound so a suspended project doesn't keep accepting + + // dispatching mail (which costs CPU and storage on the user worker). + // No cacheTtl: this is an abuse-response control; we eat the extra KV + // get per inbound message so a suspend takes effect immediately + // (subject only to KV's ~near-instant per-colo consistency). + if (await env.ROUTING.get(`email-suspended:${routing.projectId}`)) { + message.setReject(`${label}: project "${sanitize(slug, 64)}" inbound is suspended`); + return; + } } let stub: EmailEntrypointStub; @@ -789,6 +848,9 @@ export async function routeInbound( : env.DISPATCH.get(workerName)) as unknown as EmailEntrypointStub; } catch (e) { console.error(`[email-router] DISPATCH.get(${sanitize(workerName, 320)}) failed:`, e); + if (authoritative) { + throw new Error('email worker temporarily unavailable'); + } message.setReject(`${label}: project worker unavailable`); return; } @@ -815,6 +877,9 @@ export async function routeInbound( let envelope: EmailEnvelope; try { envelope = await buildEnvelope(message); + if (authoritative?.addressing === 'custom') { + envelope.viaDomain = receivedDomain; + } } catch (e) { if (e instanceof InboundTooLargeError) { message.setReject(`${label}: message too large (max ${MAX_INBOUND_BYTES} bytes)`); @@ -824,6 +889,10 @@ export async function routeInbound( message.setReject(`${label}: too many headers (max ${MAX_INBOUND_HEADERS})`); return; } + if (e instanceof InboundHeadersTooLargeError) { + message.setReject(`${label}: headers too large (max ${MAX_INBOUND_HEADER_BYTES} bytes)`); + return; + } console.error(`[email-router] failed to read message body for ${sanitize(slug, 64)}:`, e); message.setReject(`${label}: could not read inbound message body`); return; @@ -836,60 +905,42 @@ export async function routeInbound( // weaponize inbound mail to fan out to addresses verified by another // project — nullifying the architectural premise that the platform's // per-project allowlist is the security boundary. - let gate: OutboundGate; - try { - gate = await loadOutboundGate(env, routing.projectId, { receivedDomain }); - } catch (e) { - console.error( - `[email-router] failed to load outbound gate for ${sanitize(routing.projectId ?? '', 64)}:`, - e, - ); - // Closing the gate (no allowlist, exhausted quota) means forward/reply - // actions get dropped with a logged error — the user message is still - // accepted by CF (we don't reject), matching the documented behavior - // that quota exhaustion never breaks message acceptance. - gate = { - projectId: routing.projectId, - skipAllowlist: false, - allowlist: new Set(), - policy: VERIFIED_ONLY, - platformDomains: [], - burstKey: '', - burstLimit: 0, - burstCurrent: 0, - monthKey: '', - monthLimit: 0, - monthCurrent: 0, - quotaExhausted: true, - }; - } + const gate: OutboundGate = { + projectId: routing.projectId, + skipAllowlist: false, + allowlist: new Set(), + policy: VERIFIED_ONLY, + platformDomains: [], + burstKey: '', + burstLimit: 0, + burstCurrent: 0, + monthKey: '', + monthLimit: 0, + monthCurrent: 0, + quotaExhausted: false, + }; let actions: Array; + const receiptId = crypto.randomUUID(); try { - // This await materializes the tenant's WHOLE return value in this isolate - // before any bound below can look at it. workerd deserializes an RPC - // result eagerly, in one call, with no size hook; the only transport - // bound is the callee-side 32 MiB cap on SERIALIZED bytes, and a dense - // array turns 32 MiB of nulls into 128 MiB of caller heap, or of `{}` - // into ~500 MiB (measured, workerd 1.20260701.1, pointer-compressed V8). - // No proxy-side code can bound that; a contract change binds only - // cooperative tenants. Accepted limit — design doc 0078, "RPC result - // materialization", records the numbers and the architectural options. - const result = await stub.email!(envelope); - if (result === undefined || result === null) { - actions = []; - } else if (Array.isArray(result)) { - actions = result; - } else { - // Handler authors who return e.g. `{ actions: [...] }` instead of - // the bare array would otherwise see a silent no-op. Warn so the - // mistake is debuggable. - console.warn( - `[email-router] ${sanitize(workerName, 320)} email handler returned non-array; treating as no-op`, - ); - actions = []; + await recordEmailReceipt(env, receiptId, routing.projectId!, 'received'); + } catch { + if (authoritative) { + throw new Error('email admission temporarily unavailable'); } + message.setReject(`${label}: email admission unavailable`); + return; + } + try { + const result = await dispatchBoundedEmailToTenant(stub as Fetcher, env, { + projectId: routing.projectId!, + deploymentId: routing.version ?? '', + envelope, + receiptId, + }); + actions = result.actions; } catch (e) { + await recordEmailReceipt(env, receiptId, routing.projectId!, 'handler_failed').catch(() => {}); // The thrown value is the tenant's: a handler can throw an Error with any // message, or any value that crosses RPC. Only a bounded prefix is // inspected — workerd's own "does not implement" text is well under 320 @@ -910,6 +961,9 @@ export async function routeInbound( return; } console.error(`[email-router] dispatch to ${sanitize(workerName, 320)} failed:`, msg); + if (authoritative) { + throw new Error('email handler execution unresolved'); + } message.setReject(`${label}: project handler error`); ctx.waitUntil( logRecv(env, routing.projectId, message, [{ type: 'reject', reason: 'dispatch-error' }]), @@ -917,13 +971,30 @@ export async function routeInbound( return; } - await enactActions(env, message, actions, gate, { - slug, - domain: receivedDomain, - projectId: routing.projectId, - kv: env.ROUTING, - registeredDomains: new Map(), - }); + try { + await recordEmailReceipt(env, receiptId, routing.projectId!, 'handler_completed'); + } catch { + console.error('[email-router] handler completed but receipt status could not be saved'); + message.setReject(`${label}: email admission unavailable`); + return; + } + + gate.receiptId = receiptId; + try { + await enactActions(env, message, actions, gate, { + receiptId, + authoritative: !!authoritative, + customDomain: authoritative?.addressing === 'custom', + slug: authoritative?.slug ?? slug, + domain: receivedDomain, + projectId: routing.projectId, + kv: env.ROUTING, + registeredDomains: new Map(), + }); + } catch { + console.error('[email-router] action execution unresolved', receiptId); + return; + } // Async log to the metering pipeline. Best-effort. Logged after every // dispatch — including reject-only outcomes — so operators have a @@ -940,6 +1011,7 @@ export async function routeInbound( */ export interface RelayRouteOutcome { reject: boolean; + temporary?: boolean; } /** @@ -960,72 +1032,97 @@ export interface RelayRouteOutcome { export async function routeRelayed( env: Env, ctx: ExecutionContext, - input: { projectId: string; domain: string; envelope: EmailEnvelope }, + input: { + projectId: string; + domain: string; + envelope: EmailEnvelope; + authoritative?: AuthoritativeEmailRoute; + receiptId?: string; + }, ): Promise { - const { projectId, domain, envelope } = input; + const { projectId, domain, envelope, authoritative } = input; - // The platform lane resolves routing by the slug parsed from the - // recipient; a relayed recipient carries no slug, so resolve the - // project's slug via the `email-slug:` mirror the api writes - // on project create, then read the same routing blob by slug. - const slug = await env.ROUTING.get(`email-slug:${projectId}`); - if (!slug) { - console.error(`[email-relay] no slug mirror for project ${sanitize(projectId, 64)}`); - return { reject: true }; - } - const routingJson = await env.ROUTING.get(slug); - if (!routingJson) { - console.error( - `[email-relay] no routing entry for slug ${sanitize(slug, 64)} (project ${sanitize(projectId, 64)})`, - ); - return { reject: true }; - } - let parsedRouting: unknown; - try { - parsedRouting = JSON.parse(routingJson); - } catch { - console.error(`[email-relay] routing data corrupt for slug ${sanitize(slug, 64)}`); - return { reject: true }; - } - // Same corrupt-data rule as the platform lane: every writer of this blob - // emits a `JSON.stringify`d object, so a non-object parse has no - // legitimate writer. - if (typeof parsedRouting !== 'object' || parsedRouting === null) { - console.error(`[email-relay] routing data corrupt for slug ${sanitize(slug, 64)}`); - return { reject: true }; - } - const routing = parsedRouting as RoutingEntry; + let slug: string | null; + let routing: RoutingEntry; + let workerName: string; + if (authoritative) { + if (authoritative.projectId !== projectId || !authoritative.workerName || !authoritative.slug) { + return { reject: true }; + } + slug = authoritative.slug; + workerName = authoritative.workerName; + routing = { + projectId, + workerName, + version: authoritative.deploymentId, + limits: authoritative.limits, + }; + } else { + // The platform lane resolves routing by the slug parsed from the + // recipient; a relayed recipient carries no slug, so resolve the + // project's slug via the `email-slug:` mirror the api writes + // on project create, then read the same routing blob by slug. + slug = await env.ROUTING.get(`email-slug:${projectId}`); + if (!slug) { + console.error(`[email-relay] no slug mirror for project ${sanitize(projectId, 64)}`); + return { reject: true }; + } + const routingJson = await env.ROUTING.get(slug); + if (!routingJson) { + console.error( + `[email-relay] no routing entry for slug ${sanitize(slug, 64)} (project ${sanitize(projectId, 64)})`, + ); + return { reject: true }; + } + let parsedRouting: unknown; + try { + parsedRouting = JSON.parse(routingJson); + } catch { + console.error(`[email-relay] routing data corrupt for slug ${sanitize(slug, 64)}`); + return { reject: true }; + } + // Same corrupt-data rule as the platform lane: every writer of this blob + // emits a `JSON.stringify`d object, so a non-object parse has no + // legitimate writer. + if (typeof parsedRouting !== 'object' || parsedRouting === null) { + console.error(`[email-relay] routing data corrupt for slug ${sanitize(slug, 64)}`); + return { reject: true }; + } + routing = parsedRouting as RoutingEntry; - // The mirror's projectId is the authenticated identity (the relay secret - // proved it); the routing blob's is data. A disagreement is corrupt data - // — fail closed rather than dispatch one project's mail into another's - // worker. - if (routing.projectId !== projectId) { - console.error( - `[email-relay] routing blob names another project for slug ${sanitize(slug, 64)}`, - ); - return { reject: true }; - } + // The mirror's projectId is the authenticated identity (the relay secret + // proved it); the routing blob's is data. A disagreement is corrupt data + // — fail closed rather than dispatch one project's mail into another's + // worker. + if (routing.projectId !== projectId) { + console.error( + `[email-relay] routing blob names another project for slug ${sanitize(slug, 64)}`, + ); + return { reject: true }; + } - // Platform-wide suspension, then the email-only kill-switch — the same - // gates as the platform lane, so a suspended project loses relayed - // inbound at the same moment it loses everything else. - if (routing.suspended) { - console.error(`[email-relay] project ${sanitize(projectId, 64)} is suspended`); - return { reject: true }; - } - const workerName = routing.workerName; - if (!workerName || typeof workerName !== 'string') { - // Static-only deploys have no worker to dispatch to; a truthy - // non-string is KV-corrupt data. Same refusal either way. - console.error(`[email-relay] project ${sanitize(projectId, 64)} has no worker (static deploy)`); - return { reject: true }; - } - // No cacheTtl, as on the platform lane: an abuse-response control where - // convergence latency is the whole point. - if (await env.ROUTING.get(`email-suspended:${projectId}`)) { - console.error(`[email-relay] project ${sanitize(projectId, 64)} inbound is suspended`); - return { reject: true }; + // Platform-wide suspension, then the email-only kill-switch — the same + // gates as the platform lane, so a suspended project loses relayed + // inbound at the same moment it loses everything else. + if (routing.suspended) { + console.error(`[email-relay] project ${sanitize(projectId, 64)} is suspended`); + return { reject: true }; + } + workerName = routing.workerName ?? ''; + if (!workerName || typeof workerName !== 'string') { + // Static-only deploys have no worker to dispatch to; a truthy + // non-string is KV-corrupt data. Same refusal either way. + console.error( + `[email-relay] project ${sanitize(projectId, 64)} has no worker (static deploy)`, + ); + return { reject: true }; + } + // No cacheTtl, as on the platform lane: an abuse-response control where + // convergence latency is the whole point. + if (await env.ROUTING.get(`email-suspended:${projectId}`)) { + console.error(`[email-relay] project ${sanitize(projectId, 64)} inbound is suspended`); + return { reject: true }; + } } let stub: EmailEntrypointStub; @@ -1036,7 +1133,7 @@ export async function routeRelayed( : env.DISPATCH.get(workerName)) as unknown as EmailEntrypointStub; } catch (e) { console.error(`[email-relay] DISPATCH.get(${sanitize(workerName, 320)}) failed:`, e); - return { reject: true }; + return { reject: true, ...(authoritative ? { temporary: true } : {}) }; } // Built before dispatch so the dispatch-failure paths can log the @@ -1050,43 +1147,40 @@ export async function routeRelayed( // send leaves through the customer's own account, credential, DKIM and // quota — the reputation at stake is theirs. The burst cap and the kill // switch still apply. - let gate: OutboundGate; - try { - gate = await loadOutboundGate(env, projectId, { skipAllowlist: true }); - } catch (e) { - console.error(`[email-relay] failed to load outbound gate for ${sanitize(projectId, 64)}:`, e); - gate = { - projectId, - skipAllowlist: true, - allowlist: new Set(), - policy: VERIFIED_ONLY, - platformDomains: [], - burstKey: '', - burstLimit: 0, - burstCurrent: 0, - monthKey: '', - monthLimit: 0, - monthCurrent: 0, - quotaExhausted: true, - }; - } + const gate: OutboundGate = { + projectId: projectId, + skipAllowlist: authoritative?.addressing === 'custom' || !authoritative, + allowlist: new Set(), + policy: VERIFIED_ONLY, + platformDomains: [], + burstKey: '', + burstLimit: 0, + burstCurrent: 0, + monthKey: '', + monthLimit: 0, + monthCurrent: 0, + quotaExhausted: false, + }; let actions: Array; + const receiptId = input.receiptId ?? crypto.randomUUID(); try { - // The RPC materialization note on the platform lane's dispatch applies - // unchanged here. - const result = await stub.email!(envelope); - if (result === undefined || result === null) { - actions = []; - } else if (Array.isArray(result)) { - actions = result; - } else { - console.warn( - `[email-relay] ${sanitize(workerName, 320)} email handler returned non-array; treating as no-op`, - ); - actions = []; + if (!input.receiptId) { + await recordEmailReceipt(env, receiptId, projectId, 'received'); } + } catch { + return { reject: true, ...(authoritative ? { temporary: true } : {}) }; + } + try { + const result = await dispatchBoundedEmailToTenant(stub as Fetcher, env, { + projectId, + deploymentId: routing.version ?? '', + envelope, + receiptId, + }); + actions = result.actions; } catch (e) { + await recordEmailReceipt(env, receiptId, projectId, 'handler_failed').catch(() => {}); // Same bounded classification as the platform lane. const msg = e instanceof Error ? e.message.slice(0, 320) : describeUntrusted(e, 320); if (RPC_METHOD_MISSING.test(msg)) { @@ -1103,16 +1197,44 @@ export async function routeRelayed( ctx.waitUntil( logRecv(env, projectId, relayed.message, [{ type: 'reject', reason: 'dispatch-error' }]), ); - return { reject: true }; + return { reject: true, ...(authoritative ? { temporary: true } : {}) }; } - await enactActions(env, relayed.message, actions, gate, { - slug: slug.toLowerCase(), - domain, - projectId, - kv: env.ROUTING, - registeredDomains: new Map(), - }); + try { + await recordEmailReceipt(env, receiptId, projectId, 'handler_completed'); + } catch { + console.error('[email-relay] handler completed but receipt status could not be saved'); + return { reject: false }; + } + + // A relayed forward resubmits the inbound MIME through send_raw. Validate + // every action's transport budget before any earlier action can send. + if ( + envelope.raw.byteLength > MAX_REPLY_BYTES && + actions.some((action) => action.type === 'forward') + ) { + console.error( + '[email-relay] action list dropped: forwarded message exceeds outbound MIME limit', + ); + return { reject: false }; + } + + gate.receiptId = receiptId; + try { + await enactActions(env, relayed.message, actions, gate, { + receiptId, + authoritative: !!authoritative, + customDomain: authoritative?.addressing === 'custom', + slug: slug.toLowerCase(), + domain, + projectId, + kv: env.ROUTING, + registeredDomains: new Map(), + }); + } catch { + console.error('[email-relay] action execution unresolved', receiptId); + return { reject: false }; + } // Same audit trail as the platform lane — including reject-only outcomes. ctx.waitUntil(logRecv(env, projectId, relayed.message, actions)); @@ -1170,14 +1292,7 @@ function createRelayedMessage( // branch): the account id comes from it, and a row revoked or // re-registered to another project between the auth and this send must // not push mail into the account the mirror named then. - const mirror = await readEmailDomainMirror(env.ROUTING, senderDomain); - if (!mirror || mirror.projectId !== relay.projectId || mirror.status !== 'active') { - throw new Error('email domain registration is no longer active'); - } - if (!mirror.accountId) { - throw new Error('email domain registration is incomplete'); - } - const lease = await leaseEmailDomainCredential(env, senderDomain); + const lease = await leaseEmailDomainCredential(env, senderDomain, relay.projectId); if (!lease) { throw new Error('could not lease the domain credential'); } @@ -1188,7 +1303,7 @@ function createRelayedMessage( let res: Response; try { res = await fetch( - `https://api.cloudflare.com/client/v4/accounts/${mirror.accountId}/email/sending/send_raw`, + `https://api.cloudflare.com/client/v4/accounts/${lease.accountId}/email/sending/send_raw`, { method: 'POST', headers: { @@ -1409,10 +1524,16 @@ async function buildEnvelope(message: ForwardableEmailMessage): Promise = []; + let headerBytes = 0; + const encoder = new TextEncoder(); for (const entry of message.headers) { if (entries.length >= MAX_INBOUND_HEADERS) { throw new InboundTooManyHeadersError(); } + headerBytes += encoder.encode(entry[0]).byteLength + encoder.encode(entry[1]).byteLength; + if (headerBytes > MAX_INBOUND_HEADER_BYTES) { + throw new InboundHeadersTooLargeError(); + } entries.push(entry); } const raw = await readStreamToBytes(message.raw); @@ -1687,79 +1808,100 @@ async function enactSanitized( actions: Array, gate: OutboundGate, ): Promise { - let counterDirty = false; - for (const action of actions) { + if (!gate.projectId || !gate.receiptId) { + console.error( + '[email-router] action admission unavailable: missing project or receipt identity', + ); + return; + } + for (const [index, action] of actions.entries()) { if (action.type === 'reject') { message.setReject(action.reason); - // Reject is terminal — flush any counters we already incremented - // before exiting so the burst window reflects forward/reply work - // that already fired ahead of the reject. - if (counterDirty) { - await commitGateCounters(env, gate); - } return; } - if (action.type === 'forward') { - if (!checkOutboundGate(gate, action.to, 'forward')) { - continue; - } - try { - await message.forward(action.to, action.headers); - gate.burstCurrent += 1; - gate.monthCurrent += 1; - counterDirty = true; - } catch (e) { - console.error( - `[email-router] forward to ${sanitize(action.to, 320)} failed:`, - e instanceof Error ? sanitize(e.message, 320) : sanitize(String(e), 320), - ); - } - } else if (action.type === 'reply') { - if (!checkOutboundGate(gate, action.to, 'reply')) { - continue; - } - try { - // The relay lane's stand-in holds no CF email event, so a reply is - // a fresh REST send of the recorded bytes through the customer - // account (send_raw with the domain's leased credential — design - // doc 0078, "Inbound identity"), not a native reply on a real - // message. The stand-in advertises that channel as - // `__voidRelayReply`; a native EmailMessage could not carry the - // bytes anyway (no public body accessor). + const to = action.to.toLowerCase(); + const from = action.type === 'reply' ? action.from : message.to; + const digest = await emailPayloadDigest( + action.type, + from, + [to], + action.type === 'reply' + ? action.raw + : new TextEncoder().encode(JSON.stringify([...(action.headers?.entries() ?? [])].sort())), + ); + let admission; + try { + admission = await admitEmail(env, { + projectId: gate.projectId, + kind: action.type, + key: `${gate.receiptId}:${index}:${digest.slice(0, 16)}`, + digest, + from, + recipients: [to], + transport: + action.type === 'forward' + ? gate.skipAllowlist + ? 'send_raw' + : 'native_forward' + : gate.skipAllowlist + ? 'send_raw' + : 'native_reply', + receiptId: gate.receiptId, + }); + } catch (error) { + console.error( + '[email-router] action admission unavailable:', + error instanceof Error ? error.message : 'unknown', + ); + continue; + } + const admitted = admission.recipients.find((r) => r.recipient === to); + if (admission.replay || admitted?.state !== 'reserved') { + continue; + } + try { + await startEmailAttempt(env, admission.operationId, [to]); + } catch { + console.error('[email-router] could not commit attempt_started'); + continue; + } + try { + if (action.type === 'forward') { + await message.forward(to, action.headers); + } else { const relayReply = ( message as unknown as { __voidRelayReply?: (from: string, to: string, raw: Uint8Array) => Promise; } ).__voidRelayReply; - if (relayReply !== undefined) { - await relayReply(action.from, action.to, action.raw); + if (relayReply) { + await relayReply(action.from, to, action.raw); } else { - // EmailMessage's `raw` parameter is `string | ReadableStream`; - // wrap the action's bytes as a one-shot stream rather than - // decoding to UTF-8 (which would corrupt non-text MIME parts). const stream = new ReadableStream({ start(controller) { controller.enqueue(action.raw); controller.close(); }, }); - const reply = new EmailMessage(action.from, action.to, stream); - await message.reply(reply as never); + await message.reply(new EmailMessage(action.from, to, stream) as never); } - gate.burstCurrent += 1; - gate.monthCurrent += 1; - counterDirty = true; - } catch (e) { - console.error( - `[email-router] reply ${sanitize(action.from, 320)}->${sanitize(action.to, 320)} failed:`, - e instanceof Error ? sanitize(e.message, 320) : sanitize(String(e), 320), - ); } + try { + await finishEmailAttempt(env, admission.operationId, [to], 'provider_accepted'); + } catch { + console.error('[email-router] provider accepted action but outcome ledger write failed'); + } + } catch { + try { + await finishEmailAttempt(env, admission.operationId, [to], 'outcome_unknown', { + errorCode: 'OUTCOME_UNKNOWN', + }); + } catch { + /* attempt_started remains visible for operator reconciliation */ + } + console.error('[email-router] action provider outcome unknown'); } } - if (counterDirty) { - await commitGateCounters(env, gate); - } } /** diff --git a/platform/packages/proxy/src/email.ts b/platform/packages/proxy/src/email.ts index b90b41286..db836280e 100644 --- a/platform/packages/proxy/src/email.ts +++ b/platform/packages/proxy/src/email.ts @@ -3,6 +3,12 @@ import { EmailMessage } from 'cloudflare:email'; import { Hono } from 'hono'; import type { Context } from 'hono'; import { asString } from './body.ts'; +import { + admitEmail, + emailPayloadDigest, + finishEmailAttempt, + startEmailAttempt, +} from './email-admission.ts'; import { dropEmailDomainLease, leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; import { readAllowlist, @@ -19,7 +25,56 @@ const app = new Hono(); * framework enforces the same cap client-side; this is the proxy-side belt to * the framework's suspenders. */ -export const MAX_MIME_BYTES = 10 * 1024 * 1024; +export const MAX_MIME_BYTES = 5 * 1024 * 1024; +const MAX_CUSTOM_HEADER_BYTES = 16 * 1024; +const BUILTIN_MIME_HEADERS = new Set([ + 'from', + 'to', + 'cc', + 'bcc', + 'subject', + 'reply-to', + 'date', + 'message-id', + 'in-reply-to', + 'references', + 'mime-version', + 'content-type', + 'content-transfer-encoding', + 'content-disposition', +]); + +/** Bound only app-defined top-level fields, including folded continuation lines. */ +export function customMimeHeaderBytesWithinLimit(raw: Uint8Array): boolean { + let used = 0; + let custom = false; + for (let start = 0; start < raw.byteLength;) { + let end = start; + while (end < raw.byteLength && raw[end] !== 10) { + end++; + } + const lineEnd = end > start && raw[end - 1] === 13 ? end - 1 : end; + if (lineEnd === start) { + return true; + } + if (raw[start] !== 32 && raw[start] !== 9) { + let colon = start; + while (colon < lineEnd && raw[colon] !== 58) { + colon++; + } + const name = new TextDecoder().decode(raw.subarray(start, colon)).toLowerCase(); + custom = colon < lineEnd && !BUILTIN_MIME_HEADERS.has(name); + } + if (custom) { + used += lineEnd - start + 2; + if (used > MAX_CUSTOM_HEADER_BYTES) { + return false; + } + } + start = end + 1; + } + return true; +} /** * Cap the recipient list. Every entry costs a trimmed+lowercased copy, a @@ -576,6 +631,21 @@ app.post('/send', async (context) => { const requestIdRaw = asString(body.requestId); const requestId = requestIdRaw === null ? 'unknown' : sanitizeForLog(requestIdRaw, MAX_REQUEST_ID_LENGTH); + const callerKey = asString(body.idempotencyKey); + if ( + callerKey !== null && + (callerKey.length === 0 || callerKey.length > 128 || !/^[\x20-\x7e]+$/.test(callerKey)) + ) { + return context.json( + { ok: false, error: { code: 'INVALID_TO', message: 'invalid idempotency key' } }, + 400, + ); + } + const operationKey = + callerKey ?? + (requestIdRaw && requestIdRaw.length <= 128 && /^[\x20-\x7e]+$/.test(requestIdRaw) + ? requestIdRaw + : crypto.randomUUID()); const recipientsRaw = Array.isArray(body.recipients) ? body.recipients : null; if (!from || !mimeBase64 || !recipientsRaw) { @@ -731,6 +801,15 @@ app.post('/send', async (context) => { 413, ); } + if (!customMimeHeaderBytesWithinLimit(raw)) { + return context.json( + { + ok: false, + error: { code: 'MIME_ERROR', message: 'custom headers exceed the 16 KiB limit' }, + }, + 413, + ); + } // Custom sender domains (design doc 0078, "Custom domains on // Cloudflare"): a `from` whose domain is NOT the platform sender domain @@ -751,71 +830,12 @@ app.post('/send', async (context) => { recipients, raw, requestId, + operationKey, ); } - // Resolve the project's slug via the `email-slug:` mirror - // the API writes on project create. We use this to enforce that the - // `from` address belongs to the calling project — without this check, - // project A could submit `from: +...@` and - // impersonate B (the account-level send_email binding accepts any - // sender on the zone). - // - // No cacheTtl: slug↔projectId is permanent, so KV's edge cache (60s - // free-tier window) gives us locality without us pinning it. - const expectedSlug = await context.env.ROUTING.get(`email-slug:${projectId}`); - if (!expectedSlug) { - return context.json( - { - ok: false, - error: { - code: 'UPSTREAM_ERROR', - message: 'project slug unknown — refusing to send', - }, - }, - 502, - ); - } - // Defense-in-depth: reject malformed slugs from KV so a poisoned mirror - // can't smuggle a bad `from` past the strict regex below or DoS future - // sends with mismatched comparisons. - if (!SLUG_RE.test(expectedSlug)) { - console.error( - `[email-send] project ${projectId} slug malformed in KV: ${sanitizeForLog(expectedSlug, 64)}`, - ); - return context.json( - { - ok: false, - error: { - code: 'UPSTREAM_ERROR', - message: 'project slug malformed in routing', - }, - }, - 502, - ); - } - // A slug that is an email identity of the domain itself (`noreply`, the - // platform's own verification sender; `postmaster`, `abuse`, …) may not - // send at all. `RESERVED_SLUGS` stops NEW projects from claiming one, but - // a project registered before those were reserved still holds its slug, - // and the mirror alone would let it send as `noreply@` — - // indistinguishable from the platform. The api's backfill withholds and - // removes the mirror for such a project; this refusal covers the mirror - // that already exists until that pass runs, and any write that bypasses - // the backfill. Refused as a bad `from` rather than a 502: nothing - // upstream is missing, the identity is simply not the project's to use. - if (isReservedEmailSlug(expectedSlug)) { - return context.json( - { - ok: false, - error: { - code: 'INVALID_FROM', - message: `project slug "${expectedSlug}" is a reserved email identity on ${senderDomain} — refusing to send`, - }, - }, - 403, - ); - } + // Sender ownership is checked against PostgreSQL by the admission service. + const expectedSlug = from.split('@')[0]?.split('+')[0] ?? ''; // Lowercase once for the strict regex + slug compare; the regex anchors // the whole string and intentionally rejects CR/LF, quotes, brackets, // and display-name forms before we touch EmailMessage. @@ -885,162 +905,88 @@ app.post('/send', async (context) => { ); } - // Platform-wide suspension — the same marker dispatch answers with a 429. - // Checked before the email-only kill-switch so an account suspended for - // abuse loses every egress path at once. - const platformSuspension = await readRoutingSuspension(context.env.ROUTING, expectedSlug); - // A blob we cannot parse leaves the marker's state unknown, so it fails - // closed exactly like a poisoned slug mirror above: operator-visible 502, - // no send, no quota burned. - if (platformSuspension.kind === 'corrupt') { - console.error( - `[email-send] project ${projectId} routing blob malformed in KV for slug ${sanitizeForLog(expectedSlug, 64)}`, - ); - return context.json( - { - ok: false, - error: { - code: 'UPSTREAM_ERROR', - message: 'project routing entry malformed', - }, - }, - 502, - ); - } - if (platformSuspension.kind === 'suspended') { + // The API transaction is authoritative for project state, sender identity, consent, + // suspension and both recipient-attempt quotas. KV is only a routing hint. + let admission; + try { + admission = await admitEmail(context.env, { + projectId, + kind: 'direct', + key: operationKey, + digest: await emailPayloadDigest('direct', from, recipients, raw), + from, + recipients, + transport: 'binding', + }); + } catch (error) { + const conflict = error instanceof Error && error.message === 'IDEMPOTENCY_CONFLICT'; return context.json( { ok: false, error: { - code: 'QUOTA_EXCEEDED', - message: `project is suspended (${sanitizeForLog(platformSuspension.reason, 64)})`, + code: conflict ? 'IDEMPOTENCY_CONFLICT' : 'UPSTREAM_ERROR', + message: conflict + ? 'idempotency key has different content' + : 'email admission unavailable', }, }, - 200, - ); - } - - // Suspend kill-switch — set by admin UI for abuse response. Also gates - // inbound (see email-router.ts). No cacheTtl: this is an abuse-response - // control where convergence latency is the whole point — we want to - // pay for the extra KV get on every send so a suspend takes effect - // immediately (subject only to KV's ~near-instant per-colo consistency). - if (await context.env.ROUTING.get(`email-suspended:${projectId}`)) { - return context.json( - { ok: false, error: { code: 'QUOTA_EXCEEDED', message: 'project email is suspended' } }, - 200, + conflict ? 409 : 503, ); } - - // Per-project verified-destinations allowlist, widened by the - // installation's recipient policy (email-policy.ts). Both are KV mirrors - // the API maintains; cacheTtl bounds convergence at ~60s per colo. A - // missing allowlist reads as empty and a missing policy as `verified`, so - // a brand-new project with no verified destinations gets every recipient - // rejected — matches the design intent. - const [allowlist, policy] = await Promise.all([ - readAllowlist(context.env.ROUTING, projectId), - readRecipientPolicy(context.env.ROUTING), - ]); - - const allowed: Array = []; - const deliveries: Array = []; - for (const r of recipients) { - if (recipientAllowed(policy, allowlist, r, [senderDomain])) { - allowed.push(r); - } else { + const deliveries: Array = admission.recipients + .filter((r) => r.state !== 'reserved') + .map((r) => ({ + recipient: r.recipient, + ok: r.state === 'provider_accepted', + state: r.state, + messageId: r.providerReference ?? undefined, + error: + r.state === 'provider_accepted' + ? undefined + : { + code: + r.errorCode ?? + (r.state === 'outcome_unknown' || r.state === 'attempt_started' + ? 'OUTCOME_UNKNOWN' + : 'UNVERIFIED_DESTINATION'), + message: + r.state === 'outcome_unknown' || r.state === 'attempt_started' + ? 'provider outcome unknown; inspect email logs before retrying' + : 'recipient was not admitted', + }, + })); + if (admission.replay) { + for (const row of admission.recipients.filter((r) => r.state === 'reserved')) { deliveries.push({ - recipient: r, + recipient: row.recipient, ok: false, + state: 'reserved', error: { - code: 'UNVERIFIED_DESTINATION', - message: recipientRefusalMessage(policy, r), + code: 'OUTCOME_UNKNOWN', + message: 'email action remains reserved; inspect email logs before retrying', }, }); } + return emailActionResponse(context, admission.operationId, deliveries); } - if (allowed.length === 0) { - return context.json({ ok: false, deliveries }, 200); - } - - // Burst cap — fixed-window per-minute counter. Caps the spike before it - // reaches CF's MTA so a noisy project can't trip the per-zone rate limit - // for the shared platform sender. - const now = new Date(); - const burstKey = `email-burst:${projectId}:${minuteBucket(now)}`; - const burstCurrent = readCounter(await context.env.ROUTING.get(burstKey)); - const burstLimit = await getBurstLimit(context.env.ROUTING, projectId); - if (burstCurrent + allowed.length > burstLimit) { - return context.json( - { - ok: false, - error: { - code: 'QUOTA_EXCEEDED', - message: `outbound burst limit ${burstLimit}/min exceeded`, - }, - }, - 429, - ); - } - - // Monthly counter. YYYY-MM bucket auto-rolls. - const counterKey = `email-sent:${projectId}:${monthBucket(now)}`; - const monthCurrent = readCounter(await context.env.ROUTING.get(counterKey)); - const monthLimit = await getMonthlyLimit(context.env.ROUTING, projectId); - if (monthCurrent + allowed.length > monthLimit) { - return context.json( - { - ok: false, - error: { - code: 'QUOTA_EXCEEDED', - message: `monthly outbound limit ${monthLimit} exceeded`, - }, - }, - 429, - ); - } - - // Optimistic increment of both counters. - // - // **Both caps are best-effort, and the monthly one is NOT a backstop for - // the burst one.** Each counter is a KV read-modify-write, so concurrent - // isolates read the same value and overshoot by - // `(parallel_isolates × per_request_recipients)`. A wider window does not - // fix that: KV accepts at most one write per second per key, so once the - // send rate passes ~1 request/second the month counter stops advancing for - // the rest of that second and every request inside it charges against the - // same stale read. KV answers those rejected writes with a 429, which the - // `.catch()` below swallows. The bypass scales with request rate and - // degrades the monthly cap by the same factor as the burst cap. It does - // not round to nothing. - // - // What these gates buy is a bound on accidental floods and a cheap reject - // for the ordinary case. The real abuse control is the suspend - // kill-switch (`email-suspended:` and the platform-wide - // `routing.suspended` marker), which is why both are read uncached on - // every send. Making either cap strict means moving the counter into a - // Durable Object (or fronting it with CF rate limiting) — a platform - // architecture decision, deliberately not taken here. - // - // Each put is wrapped independently so one failed write cannot drop the - // other. A failed put means the next request reads a stale count and the - // overshoot widens, which is accepted for the same reason as above. - await Promise.all([ - context.env.ROUTING.put(counterKey, String(monthCurrent + allowed.length), { - expirationTtl: monthTtlSeconds(now), - }).catch((e) => { - console.error(`[email-send] monthly counter put failed for ${projectId}:`, e); - }), - context.env.ROUTING.put(burstKey, String(burstCurrent + allowed.length), { - expirationTtl: 5 * 60, - }).catch((e) => { - console.error(`[email-send] burst counter put failed for ${projectId}:`, e); - }), - ]); + const allowed = admission.recipients + .filter((r) => r.state === 'reserved') + .map((r) => r.recipient); // Send fan-out. CF's `send_email` binding takes one recipient per // EmailMessage — we already split by recipient above. for (const r of allowed) { + try { + await startEmailAttempt(context.env, admission.operationId, [r]); + } catch { + deliveries.push({ + recipient: r, + ok: false, + state: 'outcome_unknown', + error: { code: 'OUTCOME_UNKNOWN', message: 'could not confirm email attempt status' }, + }); + continue; + } try { // EmailMessage accepts string | ReadableStream — wrap our buffered // bytes as a single-chunk stream. We can't reuse one stream across @@ -1049,18 +995,44 @@ app.post('/send', async (context) => { // Some CF builds don't return the messageId; we surface "" rather // than crash and let the framework decide whether to fall back. const result = await sendBinding.send(msg); + const providerReference = typeof result?.messageId === 'string' ? result.messageId : ''; + try { + await finishEmailAttempt(context.env, admission.operationId, [r], 'provider_accepted', { + providerReference, + }); + } catch { + deliveries.push({ + recipient: r, + ok: false, + state: 'outcome_unknown', + error: { + code: 'OUTCOME_UNKNOWN', + message: 'provider accepted email but outcome could not be recorded', + }, + }); + continue; + } deliveries.push({ recipient: r, ok: true, - messageId: typeof result?.messageId === 'string' ? result.messageId : '', + state: 'provider_accepted', + messageId: providerReference, }); - } catch (e) { + } catch { + try { + await finishEmailAttempt(context.env, admission.operationId, [r], 'outcome_unknown', { + errorCode: 'OUTCOME_UNKNOWN', + }); + } catch { + /* persisted attempt_started remains unresolved */ + } deliveries.push({ recipient: r, ok: false, + state: 'outcome_unknown', error: { - code: classifyUpstream(e, projectId), - message: e instanceof Error ? e.message : String(e), + code: 'OUTCOME_UNKNOWN', + message: 'provider outcome unknown; inspect email logs before retrying', }, }); } @@ -1073,13 +1045,15 @@ app.post('/send', async (context) => { // a mid-batch failure so callers can retry per-recipient. const anyFailed = deliveries.some((d) => !d.ok); if (anyFailed) { - return context.json({ ok: false, deliveries }, 200); + return context.json({ ok: false, operationId: admission.operationId, deliveries }, 200); } return context.json({ ok: true, + operationId: admission.operationId, ids: deliveries.map((d) => ({ recipient: d.recipient, messageId: (d as { messageId: string }).messageId, + state: 'provider_accepted', })), }); }); @@ -1145,6 +1119,7 @@ async function sendViaCustomDomain( recipients: Array, raw: Uint8Array, requestId: string, + operationKey: string, ): Promise { // The envelope is forwarded verbatim to the customer's account, so the // printable-ASCII guard runs here for the same reason as on the shared @@ -1160,34 +1135,8 @@ async function sendViaCustomDomain( } const fromLower = from.toLowerCase(); - // The mirror IS the authorization: it names the one project this domain - // belongs to. A missing row, another project's row, and a row that never - // reached (or left) `active` all refuse identically. The message names - // the configured sender domain too: a `from` on another environment's - // platform zone lands here, and naming the zone is what makes that - // misconfiguration debuggable. - const mirror = await readEmailDomainMirror(context.env.ROUTING, fromDomain, { cacheTtl: 60 }); - if (!mirror || mirror.projectId !== projectId || mirror.status !== 'active') { - return context.json( - { - ok: false, - error: { - code: 'INVALID_FROM', - message: `from address must be on the configured sender domain (${senderDomain}) or a domain registered to this project`, - }, - }, - 403, - ); - } - if (!mirror.accountId) { - return context.json( - { - ok: false, - error: { code: 'UPSTREAM_ERROR', message: 'email domain registration is incomplete' }, - }, - 502, - ); - } + // PostgreSQL domain ownership is checked by the project-bound lease and + // again by admission. A stale ROUTING mirror cannot authorize or deny send. // Pin what the recipient will SEE, exactly as the shared path does: the // MIME `From:` must be the envelope sender. The mirror already bounds the @@ -1212,160 +1161,135 @@ async function sendViaCustomDomain( ); } - // The suspension and quota gates below key on the project exactly as the - // shared path does; the slug mirror is the join to the routing blob the - // suspension marker lives on. Fail closed the same way when it is missing - // or malformed. - const slug = await context.env.ROUTING.get(`email-slug:${projectId}`); - if (!slug) { - return context.json( - { - ok: false, - error: { - code: 'UPSTREAM_ERROR', - message: 'project slug unknown — refusing to send', - }, - }, - 502, - ); - } - if (!SLUG_RE.test(slug)) { - console.error( - `[email-send] project ${projectId} slug malformed in KV: ${sanitizeForLog(slug, 64)}`, - ); + // send_raw carries the MIME as a JSON string. Decode FATALLY: the + // framework's builder emits 7-bit-clean MIME, and a body that is not + // valid UTF-8 would be silently altered by a lenient decode — refuse it + // instead. Local validation, so it runs before any quota is burned. + let mimeMessage: string; + try { + mimeMessage = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(raw); + } catch { return context.json( - { - ok: false, - error: { - code: 'UPSTREAM_ERROR', - message: 'project slug malformed in routing', - }, - }, - 502, + { ok: false, error: { code: 'MIME_ERROR', message: 'mime must be valid UTF-8' } }, + 400, ); } - // Platform-wide suspension — same marker, same codes as the shared path. - const platformSuspension = await readRoutingSuspension(context.env.ROUTING, slug); - if (platformSuspension.kind === 'corrupt') { - console.error( - `[email-send] project ${projectId} routing blob malformed in KV for slug ${sanitizeForLog(slug, 64)}`, - ); + let admission; + try { + admission = await admitEmail(context.env, { + projectId, + kind: 'direct', + key: operationKey, + digest: await emailPayloadDigest('direct', from, recipients, raw), + from, + recipients, + transport: 'send_raw', + }); + } catch (error) { + const conflict = error instanceof Error && error.message === 'IDEMPOTENCY_CONFLICT'; return context.json( { ok: false, error: { - code: 'UPSTREAM_ERROR', - message: 'project routing entry malformed', + code: conflict ? 'IDEMPOTENCY_CONFLICT' : 'UPSTREAM_ERROR', + message: conflict + ? 'idempotency key has different content' + : 'email admission unavailable', }, }, - 502, + conflict ? 409 : 503, ); } - if (platformSuspension.kind === 'suspended') { - return context.json( - { + const deliveries: Array = admission.recipients + .filter((r) => r.state !== 'reserved') + .map((r) => ({ + recipient: r.recipient, + ok: r.state === 'provider_accepted', + state: r.state, + messageId: r.providerReference ?? undefined, + error: + r.state === 'provider_accepted' + ? undefined + : { + code: + r.errorCode ?? + (r.state === 'outcome_unknown' || r.state === 'attempt_started' + ? 'OUTCOME_UNKNOWN' + : 'UNVERIFIED_DESTINATION'), + message: + r.state === 'outcome_unknown' || r.state === 'attempt_started' + ? 'provider outcome unknown; inspect email logs before retrying' + : 'recipient was not admitted', + }, + })); + if (admission.replay) { + for (const row of admission.recipients.filter((r) => r.state === 'reserved')) { + deliveries.push({ + recipient: row.recipient, ok: false, + state: 'reserved', error: { - code: 'QUOTA_EXCEEDED', - message: `project is suspended (${sanitizeForLog(platformSuspension.reason, 64)})`, + code: 'OUTCOME_UNKNOWN', + message: 'email action remains reserved; inspect email logs before retrying', }, - }, - 200, - ); + }); + } + return emailActionResponse(context, admission.operationId, deliveries); } - - // Email-only kill-switch. No cacheTtl, for the same reason as the shared - // path: an abuse-response control where convergence latency is the point. - if (await context.env.ROUTING.get(`email-suspended:${projectId}`)) { - return context.json( - { ok: false, error: { code: 'QUOTA_EXCEEDED', message: 'project email is suspended' } }, - 200, - ); + recipients = admission.recipients.filter((r) => r.state === 'reserved').map((r) => r.recipient); + if (recipients.length === 0) { + return emailActionResponse(context, admission.operationId, deliveries); } - - // Burst + monthly quota checks against the whole recipient list — with no - // allowlist filtering on this path, every recipient counts. Same - // counters, same limits, same codes as the shared path. - const now = new Date(); - const burstKey = `email-burst:${projectId}:${minuteBucket(now)}`; - const burstCurrent = readCounter(await context.env.ROUTING.get(burstKey)); - const burstLimit = await getBurstLimit(context.env.ROUTING, projectId); - if (burstCurrent + recipients.length > burstLimit) { + // A duplicate must return its durable outcome even if the credential was + // subsequently revoked. Fresh attempts lease only after admission, then + // cancel reservations if there can be no provider submission. + const lease = await leaseEmailDomainCredential(context.env, fromDomain, projectId); + if (!lease) { + await finishEmailAttempt(context.env, admission.operationId, recipients, 'cancelled').catch( + () => {}, + ); return context.json( { ok: false, - error: { - code: 'QUOTA_EXCEEDED', - message: `outbound burst limit ${burstLimit}/min exceeded`, - }, + operationId: admission.operationId, + error: { code: 'UPSTREAM_ERROR', message: 'could not lease the domain credential' }, }, - 429, + 502, ); } - const counterKey = `email-sent:${projectId}:${monthBucket(now)}`; - const monthCurrent = readCounter(await context.env.ROUTING.get(counterKey)); - const monthLimit = await getMonthlyLimit(context.env.ROUTING, projectId); - if (monthCurrent + recipients.length > monthLimit) { + if (admission.accountId !== lease.accountId) { + await finishEmailAttempt(context.env, admission.operationId, recipients, 'cancelled').catch( + () => {}, + ); return context.json( { ok: false, - error: { - code: 'QUOTA_EXCEEDED', - message: `monthly outbound limit ${monthLimit} exceeded`, - }, + operationId: admission.operationId, + error: { code: 'UPSTREAM_ERROR', message: 'email domain changed during admission' }, }, - 429, + 503, ); } - - // send_raw carries the MIME as a JSON string. Decode FATALLY: the - // framework's builder emits 7-bit-clean MIME, and a body that is not - // valid UTF-8 would be silently altered by a lenient decode — refuse it - // instead. Local validation, so it runs before any quota is burned. - let mimeMessage: string; try { - mimeMessage = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(raw); + await startEmailAttempt(context.env, admission.operationId, recipients); } catch { - return context.json( - { ok: false, error: { code: 'MIME_ERROR', message: 'mime must be valid UTF-8' } }, - 400, - ); - } - - // Lease the domain's credential from the api. A lease failure is a - // platform-side condition (the api owns the row's status transitions on - // real credential failures), so it costs the project no quota — the - // counters increment below, ahead of the one external call, the same - // optimistic increment the shared path uses. - const lease = await leaseEmailDomainCredential(context.env, fromDomain); - if (!lease) { - return context.json( - { + for (const recipient of recipients) { + deliveries.push({ + recipient, ok: false, - error: { code: 'UPSTREAM_ERROR', message: 'could not lease the domain credential' }, - }, - 502, - ); + state: 'outcome_unknown', + error: { code: 'OUTCOME_UNKNOWN', message: 'could not confirm email attempt status' }, + }); + } + return emailActionResponse(context, admission.operationId, deliveries); } - await Promise.all([ - context.env.ROUTING.put(counterKey, String(monthCurrent + recipients.length), { - expirationTtl: monthTtlSeconds(now), - }).catch((e) => { - console.error(`[email-send] monthly counter put failed for ${projectId}:`, e); - }), - context.env.ROUTING.put(burstKey, String(burstCurrent + recipients.length), { - expirationTtl: 5 * 60, - }).catch((e) => { - console.error(`[email-send] burst counter put failed for ${projectId}:`, e); - }), - ]); - // One REST call carries every recipient — unlike the platform binding's // one EmailMessage per recipient. The response's message id is shared by // the whole list. let failure: { code: string; message: string } | null = null; + let outcomeUnknown = false; let messageId = ''; // Per-recipient permanent outcomes from the send_raw result: a recipient // on either list was NOT sent to, and reporting it as delivered would @@ -1375,7 +1299,7 @@ async function sendViaCustomDomain( let cfRes: Response | null = null; try { cfRes = await fetch( - `https://api.cloudflare.com/client/v4/accounts/${mirror.accountId}/email/sending/send_raw`, + `https://api.cloudflare.com/client/v4/accounts/${lease.accountId}/email/sending/send_raw`, { method: 'POST', headers: { @@ -1387,6 +1311,7 @@ async function sendViaCustomDomain( ); } catch { failure = { code: 'UPSTREAM_ERROR', message: 'email sending request failed' }; + outcomeUnknown = true; } if (cfRes) { if (!cfRes.ok) { @@ -1400,6 +1325,7 @@ async function sendViaCustomDomain( code: cfRes.status === 429 ? 'QUOTA_EXCEEDED' : 'UPSTREAM_ERROR', message: `email sending API returned ${cfRes.status}`, }; + outcomeUnknown = cfRes.status >= 500; } else { let data: unknown = null; try { @@ -1423,7 +1349,6 @@ async function sendViaCustomDomain( } } - const deliveries: Array = []; for (const r of recipients) { if (failure) { deliveries.push({ recipient: r, ok: false, error: failure }); @@ -1450,16 +1375,55 @@ async function sendViaCustomDomain( } } + for (const delivery of deliveries.filter((d) => + admission.recipients.some((r) => r.recipient === d.recipient && r.state === 'reserved'), + )) { + try { + await finishEmailAttempt( + context.env, + admission.operationId, + [delivery.recipient], + delivery.ok ? 'provider_accepted' : outcomeUnknown ? 'outcome_unknown' : 'failed', + { + providerReference: delivery.messageId, + errorCode: delivery.ok + ? undefined + : outcomeUnknown + ? 'OUTCOME_UNKNOWN' + : (failure?.code ?? delivery.error?.code), + }, + ); + delivery.state = delivery.ok + ? 'provider_accepted' + : outcomeUnknown + ? 'outcome_unknown' + : 'failed'; + if (outcomeUnknown && !delivery.ok) { + delivery.error = { + code: 'OUTCOME_UNKNOWN', + message: 'provider outcome unknown; inspect email logs before retrying', + }; + } + } catch { + delivery.ok = false; + delivery.state = 'outcome_unknown'; + delivery.error = { + code: 'OUTCOME_UNKNOWN', + message: 'provider outcome could not be recorded', + }; + } + } logSend(projectId, requestId, deliveries); // Same mid-batch contract as the shared path: any per-recipient failure // (bounce, suppression, or a whole-call failure) answers ok:false with // the per-recipient list so the caller retries exactly the failed ones. if (deliveries.some((d) => !d.ok)) { - return context.json({ ok: false, deliveries }, 200); + return context.json({ ok: false, operationId: admission.operationId, deliveries }, 200); } return context.json({ ok: true, + operationId: admission.operationId, ids: deliveries.map((d) => ({ recipient: d.recipient, messageId: (d as { messageId: string }).messageId, @@ -1478,18 +1442,12 @@ async function sendViaCustomDomain( * 404 (and earlier did so silently). */ export async function recordInboundDelivery( - env: { ROUTING: KVNamespace }, + _env: { ROUTING: KVNamespace }, projectId: string, info: { from: string; to: string; subject: string; byteSize: number; status: string }, ): Promise { - const now = new Date(); - const counterKey = `email-recv:${projectId}:${monthBucket(now)}`; - const current = readCounter(await env.ROUTING.get(counterKey)); - await env.ROUTING.put(counterKey, String(current + 1), { - expirationTtl: monthTtlSeconds(now), - }); console.log( - `[email-recv] ${projectId} ${sanitizeForLog(info.from, 320)} -> ${sanitizeForLog(info.to, 320)} ${info.status} (${info.byteSize}B) @${Date.now()} subject="${sanitizeForLog(info.subject)}"`, + `[email-recv] ${projectId} ${sanitizeForLog(info.from, 320)} -> ${sanitizeForLog(info.to, 320)} ${info.status} (${info.byteSize}B) @${Date.now()}`, ); } @@ -1500,10 +1458,43 @@ export async function recordInboundDelivery( interface RecipientResult { recipient: string; ok: boolean; + state?: string; messageId?: string; error?: { code: string; message: string }; } +function emailActionResponse( + context: Context, + operationId: string, + deliveries: Array, +) { + if (deliveries.length === 0) { + return context.json( + { + ok: false, + operationId, + error: { code: 'OUTCOME_UNKNOWN', message: 'email action remains reserved' }, + }, + 200, + ); + } + if (deliveries.some((d) => !d.ok)) { + return context.json({ ok: false, operationId, deliveries }, 200); + } + return context.json( + { + ok: true, + operationId, + ids: deliveries.map((d) => ({ + recipient: d.recipient, + messageId: d.messageId ?? '', + state: d.state, + })), + }, + 200, + ); +} + /** * Map an error thrown by the platform's `send_email` binding to a * framework-facing error code. Mirrors `classifyBindingError` in diff --git a/platform/packages/proxy/src/index.ts b/platform/packages/proxy/src/index.ts index 5b0626d8e..8012ae01d 100644 --- a/platform/packages/proxy/src/index.ts +++ b/platform/packages/proxy/src/index.ts @@ -1,18 +1,11 @@ +import { verifyEmailReceipt } from '@void/platform/email-protocol'; import { Hono } from 'hono'; import { cors } from 'hono/cors'; import { ai } from './ai.ts'; import { asNumber, asString, isProxyBody } from './body.ts'; import { proxyCapabilityEnabled } from './capabilities.ts'; import { d1 } from './d1.ts'; -import { emailRelay } from './email-relay.ts'; -import { routeInbound } from './email-router.ts'; -import { - email, - MAX_MIME_BYTES, - MAX_RECIPIENT_LENGTH, - MAX_SENDER_LENGTH, - readEmailDomainMirror, -} from './email.ts'; +import { email, MAX_MIME_BYTES, MAX_RECIPIENT_LENGTH, MAX_SENDER_LENGTH } from './email.ts'; import { guardHumanStream } from './human-stream.ts'; import { kv } from './kv.ts'; import { PLATFORM_DISABLED_KEY, PLATFORM_DISABLED_VALUE } from './platform-lifecycle.ts'; @@ -113,88 +106,97 @@ const PLATFORM_TOKEN_MAX_SKEW_SECONDS = 5 * 60; */ const PLATFORM_TOKEN_LENGTH = 43; -// Auth middleware — parses body, authenticates, sets projectId -app.post('/*', async (context, next) => { - const path = new URL(context.req.url).pathname; +async function hmacSign(data: string, secret: string): Promise { + const key = await crypto.subtle.importKey( + 'raw', + new TextEncoder().encode(secret), + { name: 'HMAC', hash: 'SHA-256' }, + false, + ['sign'], + ); + const bytes = new Uint8Array( + await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(data)), + ); + let binary = ''; + for (const byte of bytes) { + binary += String.fromCharCode(byte); + } + return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', ''); +} - // /email/relay — the custom-domain inbound hop (design doc 0078, "Custom - // domains on Cloudflare"). A relay worker in the CUSTOMER's account POSTs - // the raw MIME as the request body — not JSON — with the envelope in - // headers: - // - // Authorization: Bearer - // X-Void-Email-Domain / X-Void-Email-From / X-Void-Email-To - // - // so this branch MUST run ahead of the JSON parse below. Modelled on the - // /email/internal/ branch: every size bound runs BEFORE any crypto, so an - // unauthenticated caller cannot choose how much hashing or KV work a - // malformed request buys. - if (path === '/email/relay') { - const relayDomain = context.req.header('X-Void-Email-Domain'); - const relayFrom = context.req.header('X-Void-Email-From'); - const relayTo = context.req.header('X-Void-Email-To'); - const relayAuth = context.req.header('Authorization'); - if (!relayDomain || !relayFrom || !relayTo || !relayAuth) { - return context.json({ error: 'relay envelope required' }, 400); - } - // Each header is bounded before it is used. 256 is generous: the - // bearer is a 43-char secret and RFC 5321 caps an address at 254. - if ( - relayDomain.length > 256 || - relayFrom.length > 256 || - relayTo.length > 256 || - relayAuth.length > 256 - ) { - return context.json({ error: 'relay envelope required' }, 400); - } - // The MIME cap is checked against the DECLARED length before the body - // is touched; the handler re-bounds while streaming, since a declared - // length can lie. A missing length is refused outright — the relay - // knows rawSize and always sets it. - const contentLengthRaw = context.req.header('content-length'); - if (!contentLengthRaw) { - return context.json({ error: 'content-length required' }, 400); - } - const contentLength = Number(contentLengthRaw); - if (!Number.isInteger(contentLength) || contentLength < 0) { - return context.json({ error: 'content-length required' }, 400); - } - if (contentLength > MAX_MIME_BYTES) { - return context.json({ error: 'mime too large' }, 413); - } - const relaySecret = relayAuth.startsWith('Bearer ') ? relayAuth.slice(7) : null; - if (!relaySecret) { - return context.json({ error: 'invalid relay credentials' }, 403); - } - // Attribution binds to the envelope RECIPIENT's domain, never to the - // relay's declared domain header: a catch-all rule can be zone-wide, so - // a relay can receive mail addressed to a different domain on the same - // zone — and its secret must not author that mail. The declared header - // must equal the recipient's domain; a mismatch means the relay or its - // wiring is wrong, and the cheap string check runs before any KV work. - const recipientDomain = relayTo.slice(relayTo.lastIndexOf('@') + 1).toLowerCase(); - if (recipientDomain.length === 0 || recipientDomain !== relayDomain.toLowerCase()) { - return context.json({ error: 'relay domain mismatch' }, 403); - } - // secret → domain → project. The mirror carries only the sha256 of the - // relay secret, so knowledge is proved without KV holding anything - // reusable; the compare is constant-time against that hash. Read - // uncached: a revoked or rotated secret must stop working at KV speed. - const mirror = await readEmailDomainMirror(context.env.ROUTING, recipientDomain); - if (!mirror) { - return context.json({ error: 'invalid relay credentials' }, 403); +// The tenant calls this over its internal service binding. JWT_SECRET never +// enters the tenant, so a project token cannot mint a gateway receipt. +app.post('/email/verify-receipt', async (context) => { + const declaredLength = context.req.header('content-length'); + if (declaredLength && (!/^\d+$/.test(declaredLength) || Number(declaredLength) > 2048)) { + return context.json({ valid: false }, 400); + } + let body: unknown; + try { + const reader = context.req.raw.body?.getReader(); + if (!reader) { + return context.json({ valid: false }, 400); } - const presented = await sha256Hex(relaySecret); - if (!constantTimeEqual(presented, mirror.relaySecretSha256)) { - return context.json({ error: 'invalid relay credentials' }, 403); + const bytes = new Uint8Array(2048); + let size = 0; + try { + while (true) { + const chunk = await reader.read(); + if (chunk.done) { + break; + } + size += chunk.value.byteLength; + if (size > bytes.byteLength) { + return context.json({ valid: false }, 400); + } + bytes.set(chunk.value, size - chunk.value.byteLength); + } + } finally { + await reader.cancel().catch(() => {}); + reader.releaseLock(); } - if (mirror.status !== 'active') { - return context.json({ error: 'email domain is not active' }, 403); + if (size === 0 || (declaredLength && size !== Number(declaredLength))) { + return context.json({ valid: false }, 400); } - context.set('projectId', mirror.projectId); - await next(); - return; + body = JSON.parse(new TextDecoder().decode(bytes.subarray(0, size))); + } catch { + return context.json({ valid: false }, 400); + } + if (!body || typeof body !== 'object') { + return context.json({ valid: false }, 400); + } + const input = body as Record; + if ( + typeof input.projectId !== 'string' || + input.projectId.length > 128 || + typeof input.deploymentId !== 'string' || + input.deploymentId.length > 128 || + typeof input.recipient !== 'string' || + input.recipient.length > 320 || + typeof input.receipt !== 'string' || + input.receipt.length > 1536 + ) { + return context.json({ valid: false }, 400); + } + const projectToken = await hmacSign(input.projectId, context.env.JWT_SECRET); + if (context.req.header('x-void-internal') !== projectToken) { + return context.json({ valid: false }, 403); } + const claims = await verifyEmailReceipt(input.receipt, context.env.JWT_SECRET, { + projectId: input.projectId, + deploymentId: input.deploymentId, + recipient: input.recipient, + }); + return context.json({ valid: claims !== null, receiptId: claims?.receiptId }); +}); + +// The former relay endpoint is gone. Reject it before the generic JSON auth +// middleware so an untrusted MIME stream is never parsed or buffered here. +app.post('/email/relay', (context) => context.json({ error: 'not found' }, 404)); + +// Auth middleware — parses body, authenticates, sets projectId +app.post('/*', async (context, next) => { + const path = new URL(context.req.url).pathname; let body: ProxyBody; try { @@ -437,18 +439,8 @@ app.route('/kv', kv); app.route('/r2', r2); app.route('/revalidate', revalidate); app.route('/email', email); -app.route('/email', emailRelay); - -export default { - fetch: app.fetch, - /** - * Inbound email entry point — bound as the catch-all CF Email Routing rule - * on the platform mail zone. See `email-router.ts`. - */ - async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise { - await routeInbound(message, env, ctx); - }, -}; + +export default { fetch: app.fetch }; // --- HMAC verification --- @@ -483,23 +475,6 @@ async function sha256Hex(input: string): Promise { return out; } -/** - * Constant-time equality for two sha256-hex strings. Length is checked - * first: both sides are 64-char hex digests in every legitimate use (the - * mirror's `relaySecretSha256` and the presented secret's hash), so the - * early out leaks nothing an attacker doesn't already know. - */ -function constantTimeEqual(a: string, b: string): boolean { - if (a.length !== b.length) { - return false; - } - let diff = 0; - for (let i = 0; i < a.length; i++) { - diff |= a.charCodeAt(i) ^ b.charCodeAt(i); - } - return diff === 0; -} - async function verifyHmac(data: string, signature: string, secret: string): Promise { try { const key = await getVerifyKey(secret); diff --git a/platform/packages/proxy/test/unit/email-admission-send.test.ts b/platform/packages/proxy/test/unit/email-admission-send.test.ts new file mode 100644 index 000000000..7da527dbe --- /dev/null +++ b/platform/packages/proxy/test/unit/email-admission-send.test.ts @@ -0,0 +1,152 @@ +import { Hono } from 'hono'; +import { describe, expect, it, vi } from 'vite-plus/test'; + +vi.mock('cloudflare:email', () => ({ + EmailMessage: class { + constructor( + public from: string, + public to: string, + public raw: unknown, + ) {} + }, +})); +const { email } = await import('../../src/email.ts'); + +function fixture() { + const actions = new Map< + string, + { + operationId: string; + digest: string; + recipients: Array<{ + recipient: string; + state: string; + errorCode: string | null; + providerReference: string | null; + }>; + } + >(); + const apiFetch = vi.fn(async (request: Request | string, init?: RequestInit) => { + const path = new URL(typeof request === 'string' ? request : request.url).pathname; + const body = ( + typeof request === 'string' ? JSON.parse(String(init?.body)) : await request.json() + ) as Record; + if (path.endsWith('/admit')) { + const key = body.key as string; + const previous = actions.get(key); + if (previous && previous.digest !== body.digest) { + return Response.json({ code: 'CONFLICT' }, { status: 409 }); + } + if (previous) { + return Response.json({ + operationId: previous.operationId, + replay: true, + recipients: previous.recipients, + }); + } + const entry = { + operationId: `act_${key}`, + digest: body.digest as string, + recipients: (body.recipients as Array).map((recipient) => ({ + recipient, + state: 'reserved', + errorCode: null, + providerReference: null, + })), + }; + actions.set(key, entry); + return Response.json({ + operationId: entry.operationId, + replay: false, + recipients: entry.recipients, + }); + } + const operationId = path.split('/').at(-2)!; + const entry = [...actions.values()].find((a) => a.operationId === operationId)!; + if (path.endsWith('/start')) { + for (const recipient of body.recipients as Array) { + entry.recipients.find((r) => r.recipient === recipient)!.state = 'attempt_started'; + } + } else if (path.endsWith('/finish')) { + for (const recipient of body.recipients as Array) { + const row = entry.recipients.find((r) => r.recipient === recipient)!; + row.state = body.state as string; + row.providerReference = (body.providerReference as string) ?? null; + row.errorCode = (body.errorCode as string) ?? null; + } + } + return Response.json({ recipients: entry.recipients }); + }); + const sender = vi.fn(async () => ({ messageId: 'provider-1' })); + const env = { + API: { fetch: apiFetch }, + JWT_SECRET: 'test-secret', + SEND_EMAIL: { send: sender }, + EMAIL_SENDER_DOMAIN: 'mail.example.com', + ROUTING: { get: vi.fn() }, + }; + const app = new Hono(); + app.use('*', async (context, next) => { + context.set('projectId', 'proj_1'); + context.set('body', await context.req.json()); + await next(); + }); + app.route('/email', email); + const send = async (key: string, recipients = ['one@example.com']) => + app.request( + '/email/send', + { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + from: 'acme+news@mail.example.com', + recipients, + mimeBase64: btoa('From: acme+news@mail.example.com\r\nSubject: hello\r\n\r\nbody'), + idempotencyKey: key, + }), + }, + env, + ); + return { send, sender, apiFetch, actions }; +} + +describe('proxy email admission delivery', () => { + it('replays a caller key without another provider submission', async () => { + const test = fixture(); + expect((await test.send('one')).status).toBe(200); + expect((await test.send('one')).status).toBe(200); + expect(test.sender).toHaveBeenCalledTimes(1); + expect(test.actions.get('one')?.recipients[0]?.state).toBe('provider_accepted'); + }); + + it('persists uncertainty for one recipient while continuing a partial fanout', async () => { + const test = fixture(); + test.sender.mockImplementationOnce(async () => { + throw new Error('timeout'); + }); + const result = await test.send('partial', ['one@example.com', 'two@example.com']); + const body = (await result.json()) as { + deliveries: Array<{ recipient: string; state: string }>; + }; + expect(body.deliveries).toEqual( + expect.arrayContaining([ + { + recipient: 'one@example.com', + state: 'outcome_unknown', + ok: false, + error: expect.any(Object), + }, + { + recipient: 'two@example.com', + state: 'provider_accepted', + ok: true, + messageId: 'provider-1', + }, + ]), + ); + expect(test.actions.get('partial')?.recipients.map((r) => r.state)).toEqual([ + 'outcome_unknown', + 'provider_accepted', + ]); + }); +}); diff --git a/platform/packages/proxy/test/unit/email-admission.test.ts b/platform/packages/proxy/test/unit/email-admission.test.ts new file mode 100644 index 000000000..58720c615 --- /dev/null +++ b/platform/packages/proxy/test/unit/email-admission.test.ts @@ -0,0 +1,97 @@ +import { describe, expect, it } from 'vite-plus/test'; +import { emailPayloadDigest } from '../../src/email-admission.ts'; + +const encoder = new TextEncoder(); +function message(date: string, id: string, boundary: string, body: string) { + return encoder.encode( + [ + `Date: ${date}`, + 'From: acme@mail.example.com', + 'To: recipient@example.com', + 'Subject: hello', + `Message-ID: <${id}>`, + 'MIME-Version: 1.0', + `Content-Type: multipart/mixed; boundary="${boundary}"`, + '', + `--${boundary}`, + 'Content-Type: text/plain; charset=UTF-8', + '', + body, + `--${boundary}--`, + '', + ].join('\r\n'), + ); +} + +describe('email admission payload digest', () => { + it('deduplicates retries when generated date, message ID and multipart boundary change', async () => { + const a = message( + 'Fri, 18 Sep 2026 01:00:00 +0000', + 'one@mail.example.com', + '=_void_mixed_AAAA', + 'hello', + ); + const b = message( + 'Fri, 18 Sep 2026 01:01:00 +0000', + 'two@mail.example.com', + '=_void_mixed_BBBB', + 'hello', + ); + expect( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], a), + ).toBe( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], b), + ); + }); + + it('conflicts on changed message content and preserves boundary-like body text', async () => { + const a = message( + 'Fri, 18 Sep 2026 01:00:00 +0000', + 'one@mail.example.com', + '=_void_mixed_AAAA', + 'hello =_void_mixed_AAAA', + ); + const b = message( + 'Fri, 18 Sep 2026 01:01:00 +0000', + 'two@mail.example.com', + '=_void_mixed_BBBB', + 'hello =_void_mixed_BBBB', + ); + expect( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], a), + ).not.toBe( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], b), + ); + const c = message( + 'Fri, 18 Sep 2026 01:00:00 +0000', + 'one@mail.example.com', + '=_void_mixed_AAAA', + 'changed', + ); + expect( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], a), + ).not.toBe( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], c), + ); + }); + + it('does not normalize a boundary declaration written as ordinary body text', async () => { + const a = message( + 'Fri, 18 Sep 2026 01:00:00 +0000', + 'one@mail.example.com', + '=_void_mixed_AAAA', + 'literal boundary="=_void_mixed_body_A"', + ); + const b = message( + 'Fri, 18 Sep 2026 01:01:00 +0000', + 'two@mail.example.com', + '=_void_mixed_BBBB', + 'literal boundary="=_void_mixed_body_B"', + ); + expect( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], a), + ).not.toBe( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], b), + ); + }); +}); diff --git a/platform/packages/proxy/test/unit/email-custom-domain.test.ts b/platform/packages/proxy/test/unit/email-custom-domain.test.ts index 87c821cf9..6678b7238 100644 --- a/platform/packages/proxy/test/unit/email-custom-domain.test.ts +++ b/platform/packages/proxy/test/unit/email-custom-domain.test.ts @@ -83,9 +83,74 @@ function createMockKv(data: Record = {}) { } function createMockEnv(kv: MockKv) { - const apiFetch = vi.fn( - async () => new Response(JSON.stringify({ kind: 'api_token', token: LEASED }), { status: 200 }), - ); + const actions = new Map< + string, + { + operationId: string; + digest: string; + recipients: Array<{ + recipient: string; + state: string; + errorCode: string | null; + providerReference: string | null; + }>; + } + >(); + const apiFetch = vi.fn(async (url: string, init: RequestInit) => { + const path = new URL(url).pathname; + if (path.endsWith('/domain-credential')) { + return Response.json({ kind: 'api_token', token: LEASED, accountId: 'acct_customer' }); + } + const body = JSON.parse(String(init.body)) as Record; + if (path.endsWith('/admit')) { + const key = body.key as string; + const previous = actions.get(key); + if (previous && previous.digest !== body.digest) { + return Response.json({ code: 'CONFLICT' }, { status: 409 }); + } + if (previous) { + return Response.json({ + operationId: previous.operationId, + replay: true, + recipients: previous.recipients, + accountId: 'acct_customer', + }); + } + const entry = { + operationId: `act_${actions.size + 1}`, + digest: body.digest as string, + recipients: (body.recipients as Array).map((recipient) => ({ + recipient, + state: 'reserved', + errorCode: null, + providerReference: null, + })), + }; + actions.set(key, entry); + return Response.json({ + operationId: entry.operationId, + replay: false, + recipients: entry.recipients, + accountId: 'acct_customer', + }); + } + const operationId = path.split('/').at(-2)!; + const entry = [...actions.values()].find((action) => action.operationId === operationId)!; + if (path.endsWith('/start')) { + for (const recipient of body.recipients as Array) { + entry.recipients.find((row) => row.recipient === recipient)!.state = 'attempt_started'; + } + } + if (path.endsWith('/finish')) { + for (const recipient of body.recipients as Array) { + const row = entry.recipients.find((item) => item.recipient === recipient)!; + row.state = body.state as string; + row.errorCode = (body.errorCode as string) ?? null; + row.providerReference = (body.providerReference as string) ?? null; + } + } + return Response.json({ recipients: entry.recipients }); + }); const sendEmail = vi.fn(async () => ({ messageId: 'msg_platform' })); const env = { AI: {}, @@ -223,16 +288,26 @@ describe('POST /email/send — custom sender domain', () => { expect(await res.json()).toEqual({ ok: true, ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_1' }], + operationId: 'act_1', }); // The lease: one POST to the api's internal endpoint, HMAC-authed. - expect(apiFetch).toHaveBeenCalledTimes(1); - const [leaseUrl, leaseInit] = apiFetch.mock.calls[0] as [string, RequestInit]; + expect( + apiFetch.mock.calls.filter(([url]) => String(url).endsWith('/domain-credential')), + ).toHaveLength(1); + const [leaseUrl, leaseInit] = apiFetch.mock.calls.find(([url]) => + String(url).endsWith('/domain-credential'), + )! as [string, RequestInit]; expect(leaseUrl).toBe('https://api/internal/email/domain-credential'); expect(leaseInit.method).toBe('POST'); - expect(JSON.parse(leaseInit.body as string)).toEqual({ domain: CUSTOM_DOMAIN }); + expect(JSON.parse(leaseInit.body as string)).toEqual({ + domain: CUSTOM_DOMAIN, + projectId: 'proj_1', + }); const leaseHeaders = new Headers(leaseInit.headers); - expect(leaseHeaders.get('x-void-internal')).toBe(await signHmac(CUSTOM_DOMAIN, JWT_SECRET)); + expect(leaseHeaders.get('x-void-internal')).toBe( + await signHmac(`email-lease-v1\nproj_1\n${CUSTOM_DOMAIN}`, JWT_SECRET), + ); // The delivery: one POST to the CUSTOMER account's send_raw, leased // credential as Bearer, envelope + MIME in the JSON body. @@ -251,19 +326,18 @@ describe('POST /email/send — custom sender domain', () => { // The platform binding is never touched on this path. expect(sendEmail).not.toHaveBeenCalled(); - // Quota counters burned exactly as the shared path does. - expect(kvKeysMatching(kv, 'email-sent:proj_1:')).toHaveLength(1); - expect(kvKeysMatching(kv, 'email-burst:proj_1:')).toHaveLength(1); + expect(kvKeysMatching(kv, 'email-sent:proj_1:')).toHaveLength(0); + expect(kvKeysMatching(kv, 'email-burst:proj_1:')).toHaveLength(0); }); it('sends with an oauth_grant lease (accessToken) as the Bearer', async () => { const kv = customDomainKv(); const { env, apiFetch } = createMockEnv(kv); - apiFetch.mockImplementation( - async () => - new Response(JSON.stringify({ kind: 'oauth_grant', accessToken: LEASED }), { - status: 200, - }), + const normalFetch = apiFetch.getMockImplementation()!; + apiFetch.mockImplementation(async (url, init) => + String(url).endsWith('/domain-credential') + ? Response.json({ kind: 'oauth_grant', accessToken: LEASED, accountId: 'acct_customer' }) + : normalFetch(url, init), ); const calls = stubCloudflare(); const res = await postSend(env, await sendBody()); @@ -272,16 +346,34 @@ describe('POST /email/send — custom sender domain', () => { expect(sendHeaders.get('authorization')).toBe(`Bearer ${LEASED}`); }); - it('caches the lease per domain: two sends cost one api call', async () => { + it('re-leases the domain for each send', async () => { const kv = customDomainKv(); const { env, apiFetch } = createMockEnv(kv); stubCloudflare(); await postSend(env, await sendBody()); await postSend(env, await sendBody({ requestId: 'req_2' })); - expect(apiFetch).toHaveBeenCalledTimes(1); + expect( + apiFetch.mock.calls.filter(([url]) => String(url).endsWith('/domain-credential')), + ).toHaveLength(2); }); - it('drops the cached lease on a 401 from send_raw and re-leases next time', async () => { + it('replays a completed operation without consulting a later revoked credential', async () => { + const { env, apiFetch } = createMockEnv(customDomainKv()); + const calls = stubCloudflare(); + const body = await sendBody({ idempotencyKey: 'same-operation' }); + expect((await (await postSend(env, body)).json()).ok).toBe(true); + const leaseCalls = apiFetch.mock.calls.filter(([url]) => + String(url).endsWith('/domain-credential'), + ).length; + const replay = await postSend(env, body); + expect((await replay.json()).ok).toBe(true); + expect(calls).toHaveLength(1); + expect( + apiFetch.mock.calls.filter(([url]) => String(url).endsWith('/domain-credential')), + ).toHaveLength(leaseCalls); + }); + + it('re-leases after a definitive 401 from send_raw', async () => { const kv = customDomainKv(); const { env, apiFetch } = createMockEnv(kv); let sendCount = 0; @@ -310,10 +402,12 @@ describe('POST /email/send — custom sender domain', () => { expect(first.status).toBe(200); expect(await first.json()).toEqual({ ok: false, + operationId: 'act_1', deliveries: [ { recipient: 'dev@example.com', ok: false, + state: 'failed', error: { code: 'UPSTREAM_ERROR', message: 'email sending API returned 401' }, }, ], @@ -324,8 +418,11 @@ describe('POST /email/send — custom sender domain', () => { expect(await second.json()).toEqual({ ok: true, ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_2' }], + operationId: 'act_2', }); - expect(apiFetch).toHaveBeenCalledTimes(2); + expect( + apiFetch.mock.calls.filter(([url]) => String(url).endsWith('/domain-credential')), + ).toHaveLength(2); }); it('maps a 429 from send_raw to QUOTA_EXCEEDED', async () => { @@ -339,7 +436,7 @@ describe('POST /email/send — custom sender domain', () => { expect(body.deliveries[0].error.code).toBe('QUOTA_EXCEEDED'); }); - it('maps a network failure on send_raw to UPSTREAM_ERROR', async () => { + it('marks a network failure on send_raw as an unknown outcome', async () => { const kv = customDomainKv(); const { env } = createMockEnv(kv); vi.stubGlobal( @@ -353,59 +450,36 @@ describe('POST /email/send — custom sender domain', () => { const body = await res.json(); expect(body.ok).toBe(false); expect(body.deliveries[0].error).toEqual({ - code: 'UPSTREAM_ERROR', - message: 'email sending request failed', + code: 'OUTCOME_UNKNOWN', + message: 'provider outcome unknown; inspect email logs before retrying', }); }); - it.each([ - ['another project', domainMirror({ projectId: 'p_other' })], - ['a non-active status', domainMirror({ status: 'pending' })], - ])('rejects a mirror naming %s with 403 before any external call', async (_label, mirror) => { - const kv = customDomainKv({ [`email-domain:${CUSTOM_DOMAIN}`]: mirror }); - const { env, apiFetch } = createMockEnv(kv); - const cfFetch = vi.fn(); - vi.stubGlobal('fetch', cfFetch); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(403); - const body = await res.json(); - expect(body.error.code).toBe('INVALID_FROM'); - expect(body.error.message).toContain('registered to this project'); - expect(apiFetch).not.toHaveBeenCalled(); - expect(cfFetch).not.toHaveBeenCalled(); - // No quota burned on an unauthorized send. - expect(kvKeysMatching(kv, 'email-sent:proj_1:')).toHaveLength(0); - }); - - it('rejects a from on an unregistered domain with 403', async () => { - const kv = createMockKv({ 'email-slug:proj_1': 'acme' }); - const { env, apiFetch } = createMockEnv(kv); - const cfFetch = vi.fn(); - vi.stubGlobal('fetch', cfFetch); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(403); - expect(apiFetch).not.toHaveBeenCalled(); - expect(cfFetch).not.toHaveBeenCalled(); - }); - - it('answers 502 when the mirror is missing the account id', async () => { + it('sends with a stale KV domain mirror when PostgreSQL lease and admission agree', async () => { const kv = customDomainKv({ - [`email-domain:${CUSTOM_DOMAIN}`]: domainMirror({ accountId: null }), + [`email-domain:${CUSTOM_DOMAIN}`]: domainMirror({ + projectId: 'p_other', + status: 'pending', + accountId: null, + }), }); - const { env, apiFetch } = createMockEnv(kv); - const cfFetch = vi.fn(); - vi.stubGlobal('fetch', cfFetch); + const { env } = createMockEnv(kv); + const calls = stubCloudflare(); const res = await postSend(env, await sendBody()); - expect(res.status).toBe(502); - expect((await res.json()).error.code).toBe('UPSTREAM_ERROR'); - expect(apiFetch).not.toHaveBeenCalled(); - expect(cfFetch).not.toHaveBeenCalled(); + expect(res.status).toBe(200); + expect((await res.json()).ok).toBe(true); + expect(calls).toHaveLength(1); }); it('answers 502 when the lease fails, without burning quota or calling send_raw', async () => { const kv = customDomainKv(); const { env, apiFetch } = createMockEnv(kv); - apiFetch.mockImplementation(async () => new Response('denied', { status: 403 })); + const normalFetch = apiFetch.getMockImplementation()!; + apiFetch.mockImplementation(async (url, init) => + String(url).endsWith('/domain-credential') + ? new Response('denied', { status: 403 }) + : normalFetch(url, init), + ); const cfFetch = vi.fn(); vi.stubGlobal('fetch', cfFetch); const res = await postSend(env, await sendBody()); @@ -419,34 +493,6 @@ describe('POST /email/send — custom sender domain', () => { expect(kvKeysMatching(kv, 'email-burst:proj_1:')).toHaveLength(0); }); - it('honors the email kill-switch before leasing', async () => { - const kv = customDomainKv({ 'email-suspended:proj_1': '1' }); - const { env, apiFetch } = createMockEnv(kv); - const cfFetch = vi.fn(); - vi.stubGlobal('fetch', cfFetch); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(200); - expect((await res.json()).error.code).toBe('QUOTA_EXCEEDED'); - expect(apiFetch).not.toHaveBeenCalled(); - expect(cfFetch).not.toHaveBeenCalled(); - }); - - it('honors the burst quota before leasing', async () => { - // Freeze the clock so the seeded bucket is the handler's bucket even at - // a minute boundary. - vi.useFakeTimers({ toFake: ['Date'] }); - vi.setSystemTime(new Date('2026-04-29T12:34:56.000Z')); - const kv = customDomainKv({ 'email-burst:proj_1:20260429T1234': '9999' }); - const { env, apiFetch } = createMockEnv(kv); - const cfFetch = vi.fn(); - vi.stubGlobal('fetch', cfFetch); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(429); - expect((await res.json()).error.code).toBe('QUOTA_EXCEEDED'); - expect(apiFetch).not.toHaveBeenCalled(); - expect(cfFetch).not.toHaveBeenCalled(); - }); - it('pins the MIME From to the envelope sender on the custom domain too', async () => { const kv = customDomainKv(); const { env, apiFetch } = createMockEnv(kv); @@ -507,10 +553,12 @@ describe('POST /email/send — custom sender domain', () => { expect(res.status).toBe(200); expect(await res.json()).toEqual({ ok: false, + operationId: 'act_1', deliveries: [ { recipient: 'dev@example.com', ok: false, + state: 'failed', error: { code: 'UNVERIFIED_DESTINATION', message: "recipient 'dev@example.com' permanently bounced", @@ -543,10 +591,12 @@ describe('POST /email/send — custom sender domain', () => { expect(res.status).toBe(200); expect(await res.json()).toEqual({ ok: false, + operationId: 'act_1', deliveries: [ { recipient: 'dev@example.com', ok: false, + state: 'failed', error: { code: 'UNVERIFIED_DESTINATION', message: "recipient 'dev@example.com' is on the suppression list", @@ -582,11 +632,18 @@ describe('POST /email/send — custom sender domain', () => { expect(res.status).toBe(200); expect(await res.json()).toEqual({ ok: false, + operationId: 'act_1', deliveries: [ - { recipient: 'dev@example.com', ok: true, messageId: 'cf_msg_m' }, + { + recipient: 'dev@example.com', + ok: true, + state: 'provider_accepted', + messageId: 'cf_msg_m', + }, { recipient: 'gone@example.com', ok: false, + state: 'failed', error: { code: 'UNVERIFIED_DESTINATION', message: "recipient 'gone@example.com' permanently bounced", diff --git a/platform/packages/proxy/test/unit/email-relay.test.ts b/platform/packages/proxy/test/unit/email-relay.test.ts index 7be26371d..1f8c69c4b 100644 --- a/platform/packages/proxy/test/unit/email-relay.test.ts +++ b/platform/packages/proxy/test/unit/email-relay.test.ts @@ -1,862 +1,42 @@ -/** - * Tests for POST /email/relay — the inbound hop for custom sender domains - * (design doc 0078, "Custom domains on Cloudflare"). - * - * A relay worker in the CUSTOMER's Cloudflare account streams the raw MIME - * here with the envelope in headers; the auth branch in the proxy's global - * middleware (index.ts) bounds the inputs before any crypto, proves the - * relay secret against the domain's KV mirror, and resolves the project. - * The handler (email-relay.ts) builds the EmailEnvelope and runs the second - * half of routeInbound — `routeRelayed` — for the mirror's project. - * - * The relay worker answers any non-2xx with `message.setReject`, so every - * refusal below asserts a non-2xx status. Patterns mirror `email.test.ts`: - * the real worker entry, an in-memory KV mock, and a vi.fn'd dispatch stub. - * The secret and checksums below are dummy fixture values, never real - * credentials. - */ +import { describe, expect, it, vi } from 'vite-plus/test'; -import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; - -// `cloudflare:email` is a workerd built-in with no npm shim — same mock as -// email.test.ts, hoisted above the worker import. vi.mock('cloudflare:email', () => ({ - EmailMessage: class MockEmailMessage { - constructor( - public readonly from: string, - public readonly to: string, - public readonly raw: unknown, - ) {} - }, + EmailMessage: class MockEmailMessage {}, })); const worker = (await import('../../src/index.ts')).default; -const { MAX_MIME_BYTES } = await import('../../src/email.ts'); -const { clearEmailDomainLeaseCache } = await import('../../src/email-lease.ts'); - -const JWT_SECRET = 'test-secret-key'; -const PROD_DOMAIN = 'mail.void.cloud'; - -/** Dummy fixture secret; the mirror only ever holds its sha256. */ -const RELAY_SECRET = 'dGVzdC1yZWxheS1zZWNyZXQtZml4dHVyZS12YWx1ZS0xMjM'; -/** Dummy fixture value for the leased credential — not a real token. */ -const LEASED = 'leased-credential-fixture-value'; - -async function sha256Hex(input: string): Promise { - const digest = new Uint8Array( - await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input)), - ); - let hex = ''; - for (const b of digest) { - hex += b.toString(16).padStart(2, '0'); - } - return hex; -} - -const MIME = - 'From: sender@example.com\r\nTo: support+T-42@acme.com\r\nSubject: hi\r\n\r\nhello\r\n'; - -// ----------------------------------------------------------------------- -// Mocks — same shapes as email.test.ts / email-router.test.ts. -// ----------------------------------------------------------------------- - -function createMockKv(data: Record = {}) { - const store = new Map(Object.entries(data)); - return { - store, - get: vi.fn(async (key: string, _options?: unknown) => store.get(key) ?? null), - put: vi.fn(async (key: string, value: string, _options?: unknown) => { - store.set(key, value); - }), - delete: vi.fn(async (key: string) => { - store.delete(key); - }), - }; -} - -type MockKv = ReturnType; - -interface MakeEnvOptions { - emailReturn?: unknown; - emailThrow?: unknown; - capabilities?: string; -} - -function createMockEnv(kv: MockKv, options: MakeEnvOptions = {}) { - const emailFn = vi.fn(async (_envelope: unknown) => { - if (options.emailThrow) { - throw options.emailThrow; - } - return options.emailReturn; - }); - const dispatchGet = vi.fn((_name: string, _args?: unknown, _opts?: unknown) => ({ - email: emailFn, - })); - const env = { - AI: {}, - JWT_SECRET, - ROUTING: kv, - CF_ACCOUNT_ID: 'acct', - CF_API_TOKEN: 'cf-token', - API: { fetch: vi.fn() }, - DISPATCH: { get: dispatchGet }, - SANDBOX_CONCURRENCY_COUNTER: {}, - SEND_EMAIL: { send: vi.fn(async () => ({ messageId: 'msg_1' })) }, - EMAIL_SENDER_DOMAIN: PROD_DOMAIN, - ...(options.capabilities ? { PLATFORM_CAPABILITIES: options.capabilities } : {}), - }; - return { env, emailFn, dispatchGet }; -} - -/** The standard fixture set: active mirror for acme.com + routing for p_test. */ -async function relayKv(extra: Record = {}): Promise { - const mirror = { - projectId: 'p_test', - status: 'active', - relaySecretSha256: await sha256Hex(RELAY_SECRET), - relayWorkerName: 'void-email-relay', - accountId: 'acct_customer', - zoneId: 'zone_1', - mode: 'subdomain', - }; - return createMockKv({ - 'email-domain:acme.com': JSON.stringify(mirror), - 'email-slug:p_test': 'myslug', - myslug: JSON.stringify({ workerName: 'user-worker', projectId: 'p_test' }), - ...extra, - }); -} - -interface RelayOptions { - /** Full Authorization header value; `null` omits it. Default: the fixture bearer. */ - auth?: string | null; - domain?: string; - from?: string; - to?: string; - mime?: string; - /** 'omit' sends a stream body without a content-length; any other string is set verbatim. */ - contentLength?: 'omit' | string; - /** Raw bytes override (for the over-cap case). */ - body?: Uint8Array; -} -function postRelay(env: Record, opts: RelayOptions = {}): Promise { - const bytes = opts.body ?? new TextEncoder().encode(opts.mime ?? MIME); - const headers: Record = { - 'content-type': 'application/octet-stream', - 'x-void-email-domain': opts.domain ?? 'acme.com', - 'x-void-email-from': opts.from ?? 'sender@example.com', - 'x-void-email-to': opts.to ?? 'support+T-42@acme.com', - }; - const auth = opts.auth === undefined ? `Bearer ${RELAY_SECRET}` : opts.auth; - if (auth !== null) { - headers.authorization = auth; - } - let body: BodyInit = bytes; - if (opts.contentLength === 'omit') { - body = new ReadableStream({ - start(controller) { - controller.enqueue(bytes); - controller.close(); - }, - }); - } else { - // undici's Request constructor never derives a content-length, not even - // for a fixed-size body — the relay contract requires one, so the test - // client sets it explicitly (and a stream keeps it verbatim, which lets - // the "lying length" case through). - headers['content-length'] = - typeof opts.contentLength === 'string' ? opts.contentLength : String(bytes.byteLength); - if (typeof opts.contentLength === 'string') { - body = new ReadableStream({ - start(controller) { - controller.enqueue(bytes); +describe('retired proxy email relay endpoint', () => { + it('rejects before reading MIME or invoking a tenant', async () => { + const dispatch = vi.fn(); + const read = vi.fn(); + const body = new ReadableStream( + { + pull(controller) { + read(); + controller.enqueue(new TextEncoder().encode('From: sender@example.com\r\n\r\nsecret')); controller.close(); }, - }); - } - } - const init = { - method: 'POST', - headers, - body, - ...(body instanceof ReadableStream ? { duplex: 'half' } : {}), - } as RequestInit; - return (worker.fetch as (req: Request, env: unknown) => Promise)( - new Request('https://proxy.void.cloud/email/relay', init), - env, - ); -} - -// ----------------------------------------------------------------------- -// Console spies — the relay lane logs its refusal detail; tests keep it -// off the test output and can assert on it. -// ----------------------------------------------------------------------- - -beforeEach(() => { - // The lease cache is module-level — isolate every test from its neighbours. - clearEmailDomainLeaseCache(); - vi.spyOn(console, 'error').mockImplementation(() => {}); - vi.spyOn(console, 'warn').mockImplementation(() => {}); - vi.spyOn(console, 'log').mockImplementation(() => {}); -}); - -afterEach(() => { - vi.unstubAllGlobals(); - vi.restoreAllMocks(); -}); - -// ----------------------------------------------------------------------- -// Relay-lane sends go through the CUSTOMER's account as REST send_raw with -// the domain's leased credential (design doc 0078, "Inbound identity") — -// the platform's own send_email binding rejects a sender outside its -// verified zones. This helper wires both halves of that path: env.API.fetch -// answers the lease, and the stubbed global fetch is api.cloudflare.com. -// ----------------------------------------------------------------------- - -function stubRelayRest( - env: { API: { fetch: ReturnType } }, - handler?: (call: { url: string; init: RequestInit }) => Response, -) { - env.API.fetch.mockImplementation( - async () => new Response(JSON.stringify({ kind: 'api_token', token: LEASED }), { status: 200 }), - ); - const calls: Array<{ url: string; init: RequestInit }> = []; - vi.stubGlobal( - 'fetch', - vi.fn(async (url: string, init: RequestInit) => { - calls.push({ url, init }); - if (handler) { - return handler({ url, init }); - } - const recipients = - (JSON.parse(init.body as string) as { recipients?: Array }).recipients ?? []; - return new Response( - JSON.stringify({ - success: true, - result: { - message_id: 'cf_msg_relay', - delivered: recipients, - permanent_bounces: [], - queued: [], - suppressed_recipients: [], - }, - }), - { status: 200 }, - ); - }), - ); - return calls; -} - -// ----------------------------------------------------------------------- -// The auth branch (index.ts) -// ----------------------------------------------------------------------- - -describe('POST /email/relay — auth branch', () => { - it('rejects a bad relay secret with 403 before any dispatch', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { auth: 'Bearer wrong-secret' }); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a missing Authorization header with 400', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { auth: null }); - expect(res.status).toBe(400); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a non-Bearer Authorization scheme with 403', async () => { - const kv = await relayKv(); - const { env } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { auth: `token ${RELAY_SECRET}` }); - expect(res.status).toBe(403); - }); - - it.each([ - ['X-Void-Email-Domain', { domain: `${'a'.repeat(257)}` }], - ['X-Void-Email-From', { from: `s${'a'.repeat(256)}@x.com` }], - ['X-Void-Email-To', { to: `s${'a'.repeat(256)}@acme.com` }], - ['Authorization', { auth: `Bearer ${'a'.repeat(300)}` }], - ])('rejects an overlong %s header before any KV read', async (_name, overrides) => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, overrides); - expect(res.status).toBe(400); - // The size bound runs before the mirror lookup and before any crypto: - // KV was never touched. - expect(kv.get).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects when no mirror exists for the domain', async () => { - const kv = await relayKv(); - kv.store.delete('email-domain:acme.com'); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a declared domain that does not match the envelope recipient domain', async () => { - // A catch-all rule can be zone-wide: mail for a DIFFERENT domain on - // the same zone can arrive via this relay, and its secret must not - // author it. Attribution binds to the recipient, never the claim. - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { domain: 'acme.com', to: 'user@other-acme.com' }); - expect(res.status).toBe(403); - expect(await res.json()).toEqual({ error: 'relay domain mismatch' }); - // The cheap string check runs before the mirror lookup and any crypto. - expect(kv.get).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a recipient with no domain part', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { to: 'not-an-address' }); - expect(res.status).toBe(403); - expect(kv.get).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('matches the declared and recipient domains case-insensitively', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { domain: 'ACME.COM', to: 'Support+T-42@Acme.COM' }); - expect(res.status).toBe(200); - expect(emailFn).toHaveBeenCalledTimes(1); - }); - - it.each(['pending', 'token_revoked', 'token_expired', 'failed'])( - 'rejects a mirror whose status is %s', - async (status) => { - const kv = await relayKv(); - const mirror = JSON.parse(kv.store.get('email-domain:acme.com')!) as Record; - mirror.status = status; - kv.store.set('email-domain:acme.com', JSON.stringify(mirror)); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); - }, - ); - - it('rejects a request without a content-length', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { contentLength: 'omit' }); - expect(res.status).toBe(400); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a declared body over the MIME cap before reading it', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { - body: new Uint8Array(MAX_MIME_BYTES + 1), - }); - expect(res.status).toBe(413); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a body that outgrows the cap mid-stream (declared length lied)', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never, { - body: new Uint8Array(MAX_MIME_BYTES + 1), - contentLength: '100', - }); - expect(res.status).toBe(413); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a header block that repeats one name past the total-pieces cap', async () => { - // The distinct-name cap counts map keys only; one name repeated - // thousands of times must hit the total-pieces cap instead. - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const repeated = Array.from({ length: 5000 }, () => 'X-Repeat: v').join('\r\n'); - const res = await postRelay(env as never, { - mime: `From: sender@example.com\r\nTo: support+T-42@acme.com\r\n${repeated}\r\n\r\nhi\r\n`, - }); - expect(res.status).toBe(413); - expect(await res.json()).toEqual({ error: 'too many headers' }); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects a header block that folds one header past the total-pieces cap', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const folds = Array.from({ length: 5000 }, () => '\tcontinued').join('\r\n'); - const res = await postRelay(env as never, { - mime: `From: sender@example.com\r\nTo: support+T-42@acme.com\r\nX-Folded: start\r\n${folds}\r\n\r\nhi\r\n`, - }); - expect(res.status).toBe(413); - expect(await res.json()).toEqual({ error: 'too many headers' }); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('is covered by the email capability gate', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { - emailReturn: [], - capabilities: JSON.stringify({ email: false }), - }); - const res = await postRelay(env as never); - expect(res.status).toBe(501); - expect(emailFn).not.toHaveBeenCalled(); - }); -}); - -// ----------------------------------------------------------------------- -// The handler (email-relay.ts) + routeRelayed (email-router.ts) -// ----------------------------------------------------------------------- - -describe('POST /email/relay — dispatch', () => { - it('dispatches the relayed message to the project worker and answers 200', async () => { - const kv = await relayKv(); - const { env, emailFn, dispatchGet } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true }); - expect(dispatchGet).toHaveBeenCalledWith('user-worker'); - expect(emailFn).toHaveBeenCalledTimes(1); - - // The envelope is built from the header envelope + body, with - // viaDomain set so the framework dispatcher runs in no-prefix mode. - const envelope = emailFn.mock.calls[0]?.[0] as { - from: string; - to: string; - headers: Record; - raw: Uint8Array; - rawSize: number; - viaDomain?: string; - }; - expect(envelope.from).toBe('sender@example.com'); - expect(envelope.to).toBe('support+T-42@acme.com'); - expect(envelope.viaDomain).toBe('acme.com'); - expect(envelope.headers.subject).toBe('hi'); - expect(envelope.raw).toBeInstanceOf(Uint8Array); - expect(new TextDecoder().decode(envelope.raw)).toBe(MIME); - expect(envelope.rawSize).toBe(new TextEncoder().encode(MIME).byteLength); - - // The delivery is metered like a platform-lane one: the recv counter - // is written before the response settles (the test's fallback ctx - // flushes waitUntil work). - const recvPuts = kv.put.mock.calls.filter((call) => - String(call[0]).startsWith('email-recv:p_test:'), - ); - expect(recvPuts).toHaveLength(1); - }); - - it('parses folded and duplicated MIME headers into the envelope', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const mime = - 'From: sender@example.com\r\n' + - 'Received: first\r\n' + - 'X-Custom: one\r\n\ttwo\r\n' + - 'Received: second\r\n' + - 'Subject: folded\r\n\r\nbody\r\n'; - const res = await postRelay(env as never, { mime }); - expect(res.status).toBe(200); - const envelope = emailFn.mock.calls[0]?.[0] as { headers: Record }; - expect(envelope.headers['x-custom']).toBe('one two'); - // Duplicates fold with ", ", matching workerd's Headers on the platform lane. - expect(envelope.headers.received).toBe('first, second'); - }); - - it('joins repeated occurrences of one header name with ", "', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const mime = - 'From: sender@example.com\r\n' + - 'X-Loop: one\r\n' + - 'X-Loop: two\r\n' + - 'X-Loop: three\r\n' + - 'Subject: hi\r\n\r\nbody\r\n'; - const res = await postRelay(env as never, { mime }); - expect(res.status).toBe(200); - const envelope = emailFn.mock.calls[0]?.[0] as { headers: Record }; - expect(envelope.headers['x-loop']).toBe('one, two, three'); - }); - - it('unfolds multi-line continuations onto the header they extend', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const mime = - 'From: sender@example.com\r\n' + - 'X-Folded: one\r\n' + - '\ttwo\r\n' + - ' three\r\n' + - 'Subject: hi\r\n\r\nbody\r\n'; - const res = await postRelay(env as never, { mime }); - expect(res.status).toBe(200); - const envelope = emailFn.mock.calls[0]?.[0] as { headers: Record }; - expect(envelope.headers['x-folded']).toBe('one two three'); - }); - - it('parses a large repeated-header block (one name, many occurrences)', async () => { - const kv = await relayKv(); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - // One DISTINCT name (under MAX_INBOUND_HEADERS) repeated thousands of - // times but under the total-pieces cap: the accumulation must not - // concatenate the whole value per line. - const occurrences = 2_000; - const mime = 'From: sender@example.com\r\n' + 'X-Loop: v\r\n'.repeat(occurrences) + '\r\n'; - const res = await postRelay(env as never, { mime }); - expect(res.status).toBe(200); - const envelope = emailFn.mock.calls[0]?.[0] as { headers: Record }; - expect(envelope.headers['x-loop']).toBe(new Array(occurrences).fill('v').join(', ')); - }); - - it('a handler reject action answers non-2xx so the relay setRejects', async () => { - const kv = await relayKv(); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'reject', reason: 'not for us' }], - }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - }); - - it('a dispatch failure answers non-2xx (the relay setRejects)', async () => { - const kv = await relayKv(); - const { env } = createMockEnv(kv, { emailThrow: new Error('boom') }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - }); - - it('rejects when the project has no email handler (RPC method missing)', async () => { - const kv = await relayKv(); - const { env } = createMockEnv(kv, { - emailThrow: new TypeError('The RPC receiver does not implement the method "email"'), - }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - }); - - it('enacts an allowlisted forward through the customer account via send_raw', async () => { - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const calls = stubRelayRest(env as never); - const res = await postRelay(env as never); - expect(res.status).toBe(200); - - // The platform's own binding cannot carry a customer-domain send — - // Email Service rejects a sender outside its verified zones. - expect(env.SEND_EMAIL.send).not.toHaveBeenCalled(); - - // One REST send_raw to the CUSTOMER account, leased credential as - // Bearer. The submitted sender is the envelope RECIPIENT — the - // customer account verified only its own domain, so the original - // external sender would be rejected as MAIL FROM. - expect(calls).toHaveLength(1); - expect(calls[0]?.url).toBe( - 'https://api.cloudflare.com/client/v4/accounts/acct_customer/email/sending/send_raw', - ); - const sendHeaders = new Headers(calls[0]?.init.headers); - expect(sendHeaders.get('authorization')).toBe(`Bearer ${LEASED}`); - expect(JSON.parse(calls[0]?.init.body as string)).toEqual({ - // Owned address on the registered domain, not the external sender. - from: 'support+T-42@acme.com', - recipients: ['admin@example.com'], - // Byte-identical MIME: the real From: header is preserved. - mime_message: MIME, - }); - }); - - it('sends a forward to a non-allowlisted address through the customer account and accepts the message', async () => { - // The recipient allowlist does not gate the relay lane (design doc - // 0078, "What changes in the existing rules"): the send leaves through - // the customer's own account, credential, DKIM and quota — the - // reputation at stake is theirs. The seeded allowlist proves absence - // from it no longer drops the action. - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'forward', to: 'stranger@example.net' }], - }); - const calls = stubRelayRest(env as never); - const res = await postRelay(env as never); - expect(res.status).toBe(200); - expect(env.SEND_EMAIL.send).not.toHaveBeenCalled(); - expect(calls).toHaveLength(1); - expect(calls[0]?.url).toBe( - 'https://api.cloudflare.com/client/v4/accounts/acct_customer/email/sending/send_raw', - ); - expect(JSON.parse(calls[0]?.init.body as string)).toEqual({ - // Same sender substitution as the allowlisted forward above. - from: 'support+T-42@acme.com', - recipients: ['stranger@example.net'], - mime_message: MIME, - }); - // The allowlist is not even read on this lane. - expect( - kv.get.mock.calls.filter((call) => String(call[0]).startsWith('email-allowlist:')), - ).toHaveLength(0); - }); - - it('sends a relay-lane reply to the non-allowlisted original sender via send_raw', async () => { - // Same carve-out for a reply: the original external sender is not on - // the project's allowlist, and the reply still leaves through the - // customer account. - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const replyFrom = 'support@acme.com'; - const replyMime = `From: ${replyFrom}\r\n\r\nreply body\r\n`; - const replyRaw = new TextEncoder().encode(replyMime); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'reply', from: replyFrom, to: 'sender@example.com', raw: replyRaw }], - }); - const calls = stubRelayRest(env as never); - const res = await postRelay(env as never); - expect(res.status).toBe(200); - expect(env.SEND_EMAIL.send).not.toHaveBeenCalled(); - expect(calls).toHaveLength(1); - expect(calls[0]?.url).toBe( - 'https://api.cloudflare.com/client/v4/accounts/acct_customer/email/sending/send_raw', - ); - expect(JSON.parse(calls[0]?.init.body as string)).toEqual({ - from: replyFrom, - recipients: ['sender@example.com'], - mime_message: replyMime, - }); - }); - - it('still drops relay-lane actions when the burst quota is exhausted', async () => { - // skipAllowlist lifts ONLY the allowlist gate — the burst cap still - // applies (design doc 0078). Frozen clock so the seeded counter lands - // in the minute bucket the router reads. - vi.useFakeTimers({ toFake: ['Date'] }); - vi.setSystemTime(new Date('2026-04-29T12:34:56.000Z')); - try { - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - 'email-burst-limit:p_test': '1', - // Pre-seed the counter at the limit so +1 trips. - 'email-burst:p_test:20260429T1234': '1', - }); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'forward', to: 'stranger@example.net' }], - }); - const calls = stubRelayRest(env as never); - const res = await postRelay(env as never); - // Quota exhaustion never breaks message acceptance. - expect(res.status).toBe(200); - expect(calls).toHaveLength(0); - expect(env.API.fetch).not.toHaveBeenCalled(); - } finally { - vi.useRealTimers(); - } - }); - - it('enacts a reply from an address on the relayed domain via send_raw (registered-domain pin)', async () => { - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const replyFrom = 'support@acme.com'; - const replyMime = `From: ${replyFrom}\r\n\r\nreply body\r\n`; - const replyRaw = new TextEncoder().encode(replyMime); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'reply', from: replyFrom, to: 'admin@example.com', raw: replyRaw }], - }); - const calls = stubRelayRest(env as never); - const res = await postRelay(env as never); - expect(res.status).toBe(200); - expect(env.SEND_EMAIL.send).not.toHaveBeenCalled(); - expect(calls).toHaveLength(1); - expect(calls[0]?.url).toBe( - 'https://api.cloudflare.com/client/v4/accounts/acct_customer/email/sending/send_raw', - ); - expect(JSON.parse(calls[0]?.init.body as string)).toEqual({ - from: replyFrom, - recipients: ['admin@example.com'], - mime_message: replyMime, - }); - }); - - it('enacts a reply from a SECOND project domain through that domain’s own account and credential', async () => { - // One project, two customer domains in DIFFERENT accounts: the message - // arrives on acme.com, but the reply's from sits on billing.com. - // isPermittedReplySender permits any active project domain, and Email - // Service rejects a sender outside the sending account's verified - // zones — so the mirror + lease must key off the FROM domain, not the - // receiving one (a cross-account send under the receiving domain's - // credential is CF-rejected). - const kv = await relayKv({ - 'email-domain:billing.com': JSON.stringify({ - projectId: 'p_test', - status: 'active', - relaySecretSha256: await sha256Hex(RELAY_SECRET), - relayWorkerName: 'void-email-relay', - accountId: 'acct_customer_b', - zoneId: 'zone_b', - mode: 'apex', - }), - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const replyFrom = 'billing@billing.com'; - const replyMime = `From: ${replyFrom}\r\n\r\nreply body\r\n`; - const replyRaw = new TextEncoder().encode(replyMime); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'reply', from: replyFrom, to: 'admin@example.com', raw: replyRaw }], - }); - // The lease answers per-domain, so the asserted Bearer proves WHICH - // domain's credential carried the send. - const LEASED_B = 'leased-credential-fixture-billing'; - env.API.fetch.mockImplementation(async (_url: string, init?: RequestInit) => { - const { domain } = JSON.parse(String(init?.body)) as { domain: string }; - return new Response( - JSON.stringify({ kind: 'api_token', token: domain === 'billing.com' ? LEASED_B : LEASED }), - { status: 200 }, - ); - }); - const calls: Array<{ url: string; init: RequestInit }> = []; - vi.stubGlobal( - 'fetch', - vi.fn(async (url: string, init: RequestInit) => { - calls.push({ url, init }); - return new Response( - JSON.stringify({ - success: true, - result: { - message_id: 'cf_msg_relay', - delivered: ['admin@example.com'], - permanent_bounces: [], - queued: [], - suppressed_recipients: [], - }, - }), - { status: 200 }, - ); - }), - ); - - const res = await postRelay(env as never); - expect(res.status).toBe(200); - - // The lease named the SENDER domain… - const leaseBodies = env.API.fetch.mock.calls.map( - ([, init]) => JSON.parse(String((init as RequestInit)?.body)) as { domain: string }, - ); - expect(leaseBodies).toEqual([{ domain: 'billing.com' }]); - // …and the send went to the SENDER domain's account under its - // credential — not the receiving domain's. - expect(calls).toHaveLength(1); - expect(calls[0]?.url).toBe( - 'https://api.cloudflare.com/client/v4/accounts/acct_customer_b/email/sending/send_raw', + }, + { highWaterMark: 0 }, ); - expect(new Headers(calls[0]?.init.headers).get('authorization')).toBe(`Bearer ${LEASED_B}`); - expect(JSON.parse(calls[0]?.init.body as string)).toEqual({ - from: replyFrom, - recipients: ['admin@example.com'], - mime_message: replyMime, - }); - }); - - it('a failed relayed send is logged like the platform lane and the message stays accepted', async () => { - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - // send_raw reports the one recipient as permanently bounced: success - // at the envelope level, a permanent per-recipient failure in result. - stubRelayRest( + const env = { + JWT_SECRET: 'test-secret', + ROUTING: { get: vi.fn(async () => null) }, + DISPATCH: { get: dispatch }, + }; + const response = await worker.fetch( + new Request('https://proxy.void.cloud/email/relay', { + method: 'POST', + body, + duplex: 'half', + headers: { 'content-type': 'message/rfc822' }, + } as RequestInit), env as never, - () => - new Response( - JSON.stringify({ - success: true, - result: { - message_id: 'cf_msg_relay', - delivered: [], - permanent_bounces: ['admin@example.com'], - queued: [], - suppressed_recipients: [], - }, - }), - { status: 200 }, - ), + {} as ExecutionContext, ); - const res = await postRelay(env as never); - expect(res.status).toBe(200); - expect(console.error).toHaveBeenCalled(); - }); - - it('evicts the leased credential when send_raw refuses it (401) and re-leases next time', async () => { - const kv = await relayKv({ - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }); - const { env } = createMockEnv(kv, { - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - stubRelayRest(env as never, () => new Response('nope', { status: 401 })); - const first = await postRelay(env as never); - // The action failure is logged; the message itself stays accepted, - // exactly as a failed native forward does on the platform lane. - expect(first.status).toBe(200); - expect(env.API.fetch).toHaveBeenCalledTimes(1); - - // The refusal evicted the cached lease — the next relayed send - // re-leases instead of replaying the refused credential. - stubRelayRest(env as never); - const second = await postRelay(env as never); - expect(second.status).toBe(200); - expect(env.API.fetch).toHaveBeenCalledTimes(2); - }); - - it('rejects when the project routing is suspended', async () => { - const kv = await relayKv({ - myslug: JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', - suspended: 'abuse', - }), - }); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects when the project email kill-switch is set', async () => { - const kv = await relayKv({ 'email-suspended:p_test': '2026-09-16T00:00:00Z' }); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects when the routing blob belongs to another project', async () => { - const kv = await relayKv({ - myslug: JSON.stringify({ workerName: 'user-worker', projectId: 'p_other' }), - }); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('rejects when the project has no slug mirror', async () => { - const kv = await relayKv(); - kv.store.delete('email-slug:p_test'); - const { env, emailFn } = createMockEnv(kv, { emailReturn: [] }); - const res = await postRelay(env as never); - expect(res.status).toBe(403); - expect(emailFn).not.toHaveBeenCalled(); + expect(response.status).toBe(404); + expect(read).not.toHaveBeenCalled(); + expect(dispatch).not.toHaveBeenCalled(); }); }); diff --git a/platform/packages/proxy/test/unit/email-router.test.ts b/platform/packages/proxy/test/unit/email-router.test.ts index 7509342ed..fef72b170 100644 --- a/platform/packages/proxy/test/unit/email-router.test.ts +++ b/platform/packages/proxy/test/unit/email-router.test.ts @@ -27,6 +27,22 @@ */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; +// This suite exercises router validation against a fake tenant. The gateway +// wire framing has its own tests; preserve direct access to malformed action +// fixtures that the production decoder now rejects before the router. +vi.mock('../../../email-gateway/src/tenant-dispatch.ts', () => ({ + dispatchBoundedEmailToTenant: async ( + stub: { email: (envelope: unknown) => Promise }, + _env: unknown, + input: { envelope: unknown; receiptId: string }, + ) => { + const actions = await stub.email(input.envelope); + if (!Array.isArray(actions)) { + throw new Error('invalid email tenant response'); + } + return { actions, receiptId: input.receiptId }; + }, +})); // The framework's own proxy — the record-time twin of this router's bounds. // The platform depends on the framework, never the reverse, so the router // cannot import its numbers; this test is where the two are pinned equal. @@ -275,13 +291,58 @@ function makeEnv(options: MakeEnvOptions = {}) { return { email: emailFn }; }); const senderDomain = options.senderDomain === undefined ? PROD_DOMAIN : options.senderDomain; + const actions = new Map< + string, + { + operationId: string; + recipients: Array<{ + recipient: string; + state: string; + errorCode: string | null; + providerReference: string | null; + }>; + } + >(); + const apiFetch = vi.fn(async (request: Request | string, init?: RequestInit) => { + const path = new URL(typeof request === 'string' ? request : request.url).pathname; + const body = ( + typeof request === 'string' ? JSON.parse(String(init?.body)) : await request.json() + ) as Record; + if (path.endsWith('/receipts')) { + return Response.json({ ok: true }); + } + if (path.endsWith('/admit')) { + const key = body.key as string; + const previous = actions.get(key); + if (previous) { + return Response.json({ ...previous, replay: true }); + } + const recipients = (body.recipients as Array).map((recipient) => ({ + recipient, + state: 'reserved', + errorCode: null, + providerReference: null, + })); + const entry = { operationId: `act_${actions.size}`, recipients }; + actions.set(key, entry); + return Response.json({ ...entry, replay: false }); + } + const operationId = path.split('/').at(-2)!; + const entry = [...actions.values()].find((a) => a.operationId === operationId)!; + for (const recipient of body.recipients as Array) { + const row = entry.recipients.find((r) => r.recipient === recipient)!; + row.state = path.endsWith('/start') ? 'attempt_started' : (body.state as string); + row.errorCode = (body.errorCode as string) ?? null; + } + return Response.json({ recipients: entry.recipients }); + }); const env = { AI: {}, JWT_SECRET: 'test-secret', ROUTING: kv, CF_ACCOUNT_ID: 'acct', CF_API_TOKEN: 'token', - API: { fetch: vi.fn() }, + API: { fetch: apiFetch }, DISPATCH: { get: dispatchGet }, SEND_EMAIL: { send: vi.fn() }, ...(senderDomain === null ? {} : { EMAIL_SENDER_DOMAIN: senderDomain }), @@ -919,7 +980,7 @@ describe('routeInbound — inbound header count cap', () => { // ----------------------------------------------------------------------- describe('routeInbound — dispatch result handling', () => { - it('treats undefined return as empty action list (no crash)', async () => { + it('rejects an undefined action response', async () => { const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: undefined, @@ -930,12 +991,12 @@ describe('routeInbound — dispatch result handling', () => { const { ctx } = createCtx(); await routeInbound(message, env, ctx); expect(emailFn).toHaveBeenCalled(); - expect(rejectCalls).toHaveLength(0); + expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project handler error`]); expect(forwardCalls).toHaveLength(0); expect(replyCalls).toHaveLength(0); }); - it('treats null return as empty action list', async () => { + it('rejects a null action response', async () => { const { env } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: null, @@ -943,10 +1004,10 @@ describe('routeInbound — dispatch result handling', () => { const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(0); + expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project handler error`]); }); - it('treats non-array return as empty action list (logs warning)', async () => { + it('rejects a non-array action response', async () => { const { env } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: { actions: [] }, @@ -954,8 +1015,7 @@ describe('routeInbound — dispatch result handling', () => { const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(0); - expect(warnSpy).toHaveBeenCalled(); + expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project handler error`]); }); it('classifies workerd "does not implement the method" as no-handler reject', async () => { @@ -1289,8 +1349,8 @@ describe('routeInbound — action enaction', () => { ]); }); - it('a reject after a successful forward still flushes the quota counters', async () => { - const { env, kv } = makeEnv({ + it('a reject after a successful forward preserves the earlier submission', async () => { + const { env } = makeEnv({ kvSeed: withAllowlist(['admin@example.com']), emailReturn: [ { type: 'forward', to: 'admin@example.com' }, @@ -1305,10 +1365,6 @@ describe('routeInbound — action enaction', () => { expect(order).toEqual(['forward:admin@example.com', 'reject:done']); expect(forwardCalls).toHaveLength(1); expect(rejectCalls).toEqual(['done']); - // The forward that already fired must be charged before the terminal - // reject returns. - expect(kv.store.get(SENT_KEY)).toBe('1'); - expect(kv.store.get(BURST_KEY)).toBe('1'); }); it('forward with invalid `to` is dropped with console.error', async () => { @@ -1410,8 +1466,8 @@ describe('routeInbound — action enaction', () => { expect(errorSpy).toHaveBeenCalled(); }); - it('a throwing forward is logged, charges no quota, and does not abort the list', async () => { - const { env, kv } = makeEnv({ + it('a throwing forward is logged and does not abort the list', async () => { + const { env } = makeEnv({ kvSeed: withAllowlist(), emailReturn: [ { type: 'forward', to: 'admin@example.com' }, @@ -1432,8 +1488,6 @@ describe('routeInbound — action enaction', () => { expect(forwardCalls).toHaveLength(0); // The later reply still fires… expect(replyCalls).toHaveLength(1); - // …and only IT is charged — the failed forward isn't. - expect(kv.store.get(SENT_KEY)).toBe('1'); expect(errorSpy).toHaveBeenCalled(); }); @@ -1621,7 +1675,7 @@ describe('routeInbound — envelope header bag (prototype pollution guard)', () describe('routeInbound — log-recv via ctx.waitUntil', () => { it('schedules log-recv after a successful dispatch', async () => { - const { env, kv } = makeEnv({ + const { env } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [], }); @@ -1633,12 +1687,10 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { await routeInbound(message, env, ctx); expect(waited).toHaveLength(1); await Promise.all(waited); - // recordInboundDelivery wrote a recv counter. - expect(kv.store.get(RECV_KEY)).toBe('1'); }); it('schedules log-recv even when the dispatch threw (no-handler reject path)', async () => { - const { env, kv } = makeEnv({ + const { env } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailThrow: new TypeError('The RPC receiver does not implement the method "email"'), }); @@ -1647,11 +1699,10 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { await routeInbound(message, env, ctx); expect(waited).toHaveLength(1); await Promise.all(waited); - expect(kv.store.get(RECV_KEY)).toBe('1'); }); it('schedules log-recv on the generic dispatch-error reject path', async () => { - const { env, kv } = makeEnv({ + const { env } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailThrow: new Error('boom'), }); @@ -1660,7 +1711,6 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { await routeInbound(message, env, ctx); expect(waited).toHaveLength(1); await Promise.all(waited); - expect(kv.store.get(RECV_KEY)).toBe('1'); }); // FINDING (pre-existing, also present in pr117): `logRecv` reads @@ -1672,7 +1722,7 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { // outside logRecv's own try/catch). Expressed as the correct // expectation; this test fails until logRecv guards the entry. it('logs the inbound delivery even when the action list carries a non-object entry', async () => { - const { env, kv } = makeEnv({ + const { env } = makeEnv({ kvSeed: withAllowlist(['admin@example.com']), emailReturn: [null, { type: 'forward', to: 'admin@example.com' }], }); @@ -1681,7 +1731,7 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { await routeInbound(message, env, ctx); expect(waited).toHaveLength(1); await Promise.allSettled(waited); - expect(kv.store.get(RECV_KEY)).toBe('1'); + expect(logSpy).toHaveBeenCalled(); }); it('does NOT log-recv for messages rejected before dispatch (suspended)', async () => { @@ -1702,1269 +1752,172 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { }); }); -// ----------------------------------------------------------------------- -// HIGH H1 — per-project allowlist + quota gating on forward/reply -// -// CF Email Routing destinations are account-wide. Without these gates, -// inbound mail is a fan-out primitive against any tenant's verified -// addresses. The platform's per-project allowlist is the security -// boundary; CF's account-wide verified flag is NOT a substitute. -// ----------------------------------------------------------------------- - -describe('routeInbound — per-project gating on forward/reply (HIGH H1)', () => { - it('drops forward to an address not in the per-project allowlist', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - // CF would accept this account-wide; the project allowlist - // doesn't include it, so we drop. - { type: 'forward', to: 'someone-elses-verified@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - }); - - it('drops reply to an address not in the per-project allowlist', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'someone-elses-verified@example.com', - raw: new Uint8Array(), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - }); +// Recipient consent and atomic quotas are covered by the API admission integration tests. - it('drops every forward/reply when the project has no allowlist at all', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, +describe('routeInbound — authoritative native custom domain', () => { + it('dispatches the full custom recipient without KV and enacts native forward and reply', async () => { + const from = 'support@custom.example.com'; + const { env, kv, emailFn, dispatchGet } = makeEnv({ emailReturn: [ { type: 'forward', to: 'admin@example.com' }, - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: new Uint8Array(), - }, + { type: 'reply', from, to: 'sender@example.com', raw: replyRaw(from) }, ], }); - const { message, forwardCalls, replyCalls } = createFakeMessage({ - to: `myslug@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(replyCalls).toHaveLength(0); - }); - - it('matches the allowlist case-insensitively', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['Admin@Example.com']), - emailReturn: [{ type: 'forward', to: 'ADMIN@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); + const { message, forwardCalls, replyCalls, rejectCalls } = createFakeMessage({ + to: 'support@custom.example.com', + }); + const { ctx } = createCtx(); + await routeInbound(message, env, ctx, { + projectId: 'p_test', + workerName: 'custom-worker', + deploymentId: 'v1', + slug: 'myslug', + addressing: 'custom', + domain: 'custom.example.com', + }); + expect(dispatchGet).toHaveBeenCalledWith('custom-worker'); + expect(emailFn).toHaveBeenCalledWith( + expect.objectContaining({ + to: 'support@custom.example.com', + viaDomain: 'custom.example.com', + }), + ); + expect(kv.get).not.toHaveBeenCalled(); expect(forwardCalls).toHaveLength(1); + expect(replyCalls).toHaveLength(1); + expect(rejectCalls).toHaveLength(0); }); +}); - it('widens the gate to a same-domain forward under the `domains` recipient policy', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-recipient-policy': JSON.stringify({ mode: 'domains', domains: ['corp.test'] }), - }), - emailReturn: [ - { type: 'forward', to: 'anyone@corp.test' }, - { type: 'forward', to: 'anyone@other.test' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls.map((call) => call.to)).toEqual(['anyone@corp.test']); - }); +describe('routeInbound — reply size limits', () => { + const MIB = 1024 * 1024; + const SENDER = `myslug+support@${PROD_DOMAIN}`; - it('still enacts an allowlisted forward when the recipient-policy read rejects', async () => { - const { env } = makeEnv({ + /** `size` bytes of reply MIME with a valid `From:` naming the sender. */ + function sizedReply(size: number, from = SENDER): Uint8Array { + const head = new TextEncoder().encode(`From: ${from}\r\n\r\n`); + const raw = new Uint8Array(size); + raw.set(head); + raw.fill(0x41, head.length); + return raw; + } + + function replyAction(raw: Uint8Array) { + return { type: 'reply', from: SENDER, to: 'admin@example.com', raw }; + } + + it('drops a reply over 5 MiB before the MIME From scan', async () => { + // No `From:` header at all: if the size check ran AFTER the scan, the + // drop would be logged as a missing From header instead. + const raw = new Uint8Array(5 * MIB + 1).fill(0x41); + const { env, kv } = makeEnv({ kvSeed: withAllowlist(['admin@example.com']), - kvGetFailures: ['email-recipient-policy'], - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], + emailReturn: [replyAction(raw)], }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); + const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - expect(forwardCalls.map((call) => call.to)).toEqual(['admin@example.com']); + expect(replyCalls).toHaveLength(0); expect(errorSpy).toHaveBeenCalledWith( - '[email-policy] recipient policy read failed; enforcing verified:', - expect.any(Error), + expect.stringContaining(`reply dropped: raw is ${5 * MIB + 1} bytes (max ${5 * MIB})`), ); + expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining('no From header')); + expect(kv.store.get(SENT_KEY)).toBeUndefined(); }); - it('under `any`, still drops a reply that claims another project as sender', async () => { + it('accepts a reply of exactly 5 MiB', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist([], { - 'email-recipient-policy': JSON.stringify({ mode: 'any', domains: [] }), - }), - emailReturn: [ - { - type: 'reply', - from: `otherproject+support@${PROD_DOMAIN}`, - to: 'anyone@elsewhere.test', - raw: replyRaw(`otherproject+support@${PROD_DOMAIN}`, 'r'), - }, - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'anyone@elsewhere.test', - raw: replyRaw(`myslug+support@${PROD_DOMAIN}`, 'r'), - }, - ], + kvSeed: withAllowlist(['admin@example.com']), + emailReturn: [replyAction(sizedReply(5 * MIB))], }); const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - // The sender pin does not move with the policy: only the project's own - // sender goes out, to a recipient the policy now permits. expect(replyCalls).toHaveLength(1); + expect(replyCalls[0]?.from).toBe(SENDER); }); - it("never widens a forward to another tenant's inbox on the platform's own mail domain", async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist([`consented+tag@${PROD_DOMAIN}`], { - 'email-recipient-policy': JSON.stringify({ mode: 'any', domains: [] }), - }), - emailReturn: [ - { type: 'forward', to: `otherproject+intake@${PROD_DOMAIN}` }, - { type: 'forward', to: `consented+tag@${PROD_DOMAIN}` }, - { type: 'forward', to: 'anyone@elsewhere.test' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls.map((call) => call.to)).toEqual([ - `consented+tag@${PROD_DOMAIN}`, - 'anyone@elsewhere.test', - ]); - }); - - it("uses the received domain when EMAIL_SENDER_DOMAIN is absent, so `any` cannot reach another tenant's inbox", async () => { - const { env } = makeEnv({ - senderDomain: null, - kvSeed: withAllowlist([], { - 'email-recipient-policy': JSON.stringify({ mode: 'any', domains: [] }), - }), - emailReturn: [{ type: 'forward', to: `project-b+x@${PROD_DOMAIN}` }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('recipient policy')); - }); - - it('protects both the configured sender domain and a distinct received domain', async () => { - const receivedDomain = 'example.test'; - const configuredDomain = 'mail.example.test'; + it('drops a reply that exceeds the 8 MiB cumulative budget and accepts a later smaller reply', async () => { + // The overrunning reply is dropped and NOT charged, exactly as the + // framework's `reply()` throws before advancing `replyBytesUsed`: a + // later reply that fits the remaining budget (3 + 3 + 2 = 8 MiB) still + // goes. const { env } = makeEnv({ - senderDomain: configuredDomain, - kvSeed: withAllowlist([], { - 'email-recipient-policy': JSON.stringify({ mode: 'any', domains: [] }), - }), + kvSeed: withAllowlist(['admin@example.com']), emailReturn: [ - { type: 'forward', to: `b+x@${receivedDomain}` }, - { type: 'forward', to: `b+x@${configuredDomain}` }, - { type: 'forward', to: 'someone@other.test' }, + replyAction(sizedReply(3 * MIB)), + replyAction(sizedReply(3 * MIB)), + replyAction(sizedReply(3 * MIB)), + replyAction(sizedReply(2 * MIB)), ], }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${receivedDomain}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls.map((call) => call.to)).toEqual(['someone@other.test']); - }); - - it('keeps the gate closed for the same forward under the default `verified` policy', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [{ type: 'forward', to: 'anyone@corp.test' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); + const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); + expect(replyCalls).toHaveLength(3); + expect(errorSpy).toHaveBeenCalledTimes(1); + expect(errorSpy).toHaveBeenCalledWith( + expect.stringContaining( + `reply dropped: cumulative reply bytes ${9 * MIB} exceed this delivery's budget of ${8 * MIB}`, + ), + ); }); +}); - it('fails CLOSED when the routing entry has no projectId — refused before dispatch', async () => { - // No projectId → no per-project guard is available, so forward/reply - // must be refused rather than falling back to CF's account-wide flag. - // This used to pin "dispatch, then drop the forward". A worker routing - // with no id is corrupt data (every writer has put one in the blob since - // the first), and the email-only suspension key cannot be built from it - // either — so the router now refuses it in front of dispatch, which is - // strictly more closed: no tenant code runs, no forward can fire. - const { env, emailFn, dispatchGet } = makeEnv({ - kvSeed: { myslug: JSON.stringify({ workerName: 'user-worker' }) }, - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls, rejectCalls } = createFakeMessage({ - to: `myslug@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toEqual([`${PROD_DOMAIN}: routing data corrupt`]); - expect(dispatchGet).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(0); - }); +// ----------------------------------------------------------------------- +// Framework ↔ router parity for the record-time bounds. +// +// The framework's `createMessageProxy` restates `MAX_FORWARD_HEADERS`, +// `MAX_FORWARD_HEADER_LENGTH` and `MAX_REJECT_REASON_LENGTH` and applies +// them where the action is RECORDED — in the handler's own call — so the +// test harness (which builds its message with that proxy) and a native +// own-account replay answer what this router answers. A number that +// drifted on one side would reopen the gap: a forward the harness reports +// and this router drops, or a reject reason that is clean here and injects +// into the SMTP reply natively. The numbers are pinned equal, and the +// agreement is pinned at the bound in both directions: the largest bag the +// proxy records is enacted here, one past it is refused there and dropped +// here, and a reason the proxy has normalized passes through this router +// unchanged. +// +// The harness also restates this router's ADMISSION — `MAX_INBOUND_BYTES` +// and `MAX_INBOUND_HEADERS` — and refuses a synthetic message before the +// handler runs, as `routeInbound` refuses the real one before dispatch. A +// number that drifted there would let a test invoke a handler on a message +// this router bounces. Pinned equal, and pinned in behaviour: the same +// bytes, one past each cap, draw the same reject string from both sides +// with the handler never called. +// ----------------------------------------------------------------------- - it('fails CLOSED when the gate cannot be loaded (KV read error)', async () => { - const { env, emailFn } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - kvGetFailures: ['email-allowlist:p_test'], - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls, rejectCalls } = createFakeMessage({ - to: `myslug@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(emailFn).toHaveBeenCalledTimes(1); - expect(forwardCalls).toHaveLength(0); - // Quota/gate failures never turn into a bounce. - expect(rejectCalls).toHaveLength(0); - }); +describe('framework ↔ router bound parity', () => { + const ENVELOPE = { + from: 'sender@example.com', + to: 'tag@example.com', + headers: {}, + raw: new TextEncoder().encode('Subject: hi\r\n\r\nbody\r\n'), + rawSize: 21, + }; - it('drops forward when burst limit would be exceeded', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-burst-limit:p_test': '1', - // Pre-seed counter at the limit so +1 trips. - [BURST_KEY]: '1', - }), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - // Counter not advanced. - expect(kv.store.get(BURST_KEY)).toBe('1'); + it('restates the same numbers', () => { + // Guarded on type: an export missing on either side reads `undefined`, + // and `undefined === undefined` is not parity. + for (const [framework, router] of [ + [FRAMEWORK_MAX_FORWARD_HEADERS, MAX_FORWARD_HEADERS], + [FRAMEWORK_MAX_FORWARD_HEADER_LENGTH, MAX_FORWARD_HEADER_LENGTH], + [FRAMEWORK_MAX_REJECT_REASON_LENGTH, MAX_REJECT_REASON_LENGTH], + [FRAMEWORK_MAX_INBOUND_BYTES, MAX_INBOUND_BYTES], + [FRAMEWORK_MAX_INBOUND_HEADERS, MAX_INBOUND_HEADERS], + ]) { + expect(router).toBeTypeOf('number'); + expect(framework).toBe(router); + } }); - it('drops forward when monthly limit would be exceeded', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-limit:p_test': '5', - [SENT_KEY]: '5', - }), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(kv.store.get(SENT_KEY)).toBe('5'); - }); - - it('once quota is exhausted, further forward/reply are also dropped', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'support@example.com'], { - 'email-limit:p_test': '5', - [SENT_KEY]: '5', - }), - emailReturn: [ - { type: 'forward', to: 'admin@example.com' }, - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: new Uint8Array(), - }, - ], - }); - const { message, forwardCalls, replyCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(replyCalls).toHaveLength(0); - }); - - it('quota exhaustion does not bounce the inbound message', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-limit:p_test': '1', - [SENT_KEY]: '1', - }), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(0); - }); - - it('charges quota per action — two forwards cost two', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'support@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com' }, - { type: 'forward', to: 'support@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(2); - expect(kv.store.get(SENT_KEY)).toBe('2'); - expect(kv.store.get(BURST_KEY)).toBe('2'); - }); - - it('the burst limit cuts a run of forwards off mid-list', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'support@example.com'], { - 'email-burst-limit:p_test': '1', - }), - emailReturn: [ - { type: 'forward', to: 'admin@example.com' }, - { type: 'forward', to: 'support@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(1); - expect(forwardCalls[0]?.to).toBe('admin@example.com'); - expect(kv.store.get(BURST_KEY)).toBe('1'); - }); - - it('successful forward increments burst + monthly counters', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(1); - expect(kv.store.get(SENT_KEY)).toBe('1'); - const burstWrite = kv.writes.find((w) => w.key.startsWith('email-burst:p_test:')); - expect(burstWrite?.key).toBe(BURST_KEY); - expect(burstWrite?.value).toBe('1'); - // Burst window is short-lived; the monthly counter outlives the month. - expect(burstWrite?.options?.expirationTtl).toBe(5 * 60); - const monthWrite = kv.writes.find((w) => w.key === SENT_KEY); - expect(monthWrite?.options?.expirationTtl).toBeGreaterThan(60); - }); - - it('successful reply increments counters', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(), - emailReturn: [ - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`myslug+support@${PROD_DOMAIN}`, 'reply'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - expect(kv.store.get(SENT_KEY)).toBe('1'); - }); - - it('a NaN-poisoned counter reads as zero rather than disabling the gate', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { [SENT_KEY]: 'not-a-number' }), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(1); - expect(kv.store.get(SENT_KEY)).toBe('1'); - }); - - // Suspended is already covered above (it rejects before dispatch); the - // gate's "suspended drops both" assertion is implicit — no dispatch - // happens, so no forward/reply runs. This test pins it explicitly. - it('suspended project: dispatch never runs and forward/reply are not enacted', async () => { - const { env, emailFn } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { 'email-suspended:p_test': '1' }), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(0); - }); - - it('platform-suspended project: dispatch never runs and forward/reply are not enacted', async () => { - const { env, emailFn } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', - suspended: 'abuse', - }), - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }, - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(0); - }); -}); - -// ----------------------------------------------------------------------- -// F1 — reply sender pin -// -// The reply branch builds `new EmailMessage(action.from, …)` from a value -// the tenant's worker returned over RPC. CF Email Routing's own reply rule -// is DOMAIN-level only, and every tenant plus the platform's reserved -// `noreply` slug share one mail zone — so without a pin here any project -// can emit mail as any other project, or as the platform. This is the -// inbound analogue of the outbound `from` pin in `email.ts` (strict shape -// + local-part-before-`+` equals the project's slug). -// -// The expected DOMAIN comes from the RECEIVED `message.to`, not from -// `EMAIL_SENDER_DOMAIN`: that is the domain CF pinned when it accepted the -// message, and `routeInbound` deliberately treats a missing -// `EMAIL_SENDER_DOMAIN` as non-fatal (a cosmetic var must not stop mail). -// ----------------------------------------------------------------------- - -describe('routeInbound — reply sender pin (F1)', () => { - it("drops a reply that claims ANOTHER project's slug", async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - // `otherproject` is a different tenant on the same mail zone. - from: `otherproject+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: new TextEncoder().encode('r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalled(); - }); - - it('drops a reply as the platform noreply address', async () => { - // `noreply` is a RESERVED slug, so this inbound reply path is the only - // way to emit it at all — the outbound `/email/send` pin can't be - // satisfied by any project for it. - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `noreply@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`noreply@${PROD_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - }); - - it('drops a reply whose MIME From names another address than the envelope sender', async () => { - // The sender pin above checks `action.from`; the recipient's client - // shows the `From:` header inside `raw`, which is the tenant's bytes. - // Same pin as `/email/send`, applied to the recorded reply. - const shapes: Array<[string, unknown]> = [ - ['sibling project in From:', replyRaw(`otherproject+support@${PROD_DOMAIN}`)], - [ - 'display name around a sibling', - replyRaw(`"Support" `), - ], - ['no From: header', new TextEncoder().encode('Subject: hi\r\n\r\nreply body\r\n')], - [ - 'two From: headers', - new TextEncoder().encode( - `From: myslug+support@${PROD_DOMAIN}\r\nFrom: otherproject+support@${PROD_DOMAIN}\r\n\r\nr\r\n`, - ), - ], - ['raw is not bytes', `From: myslug+support@${PROD_DOMAIN}\r\n\r\nr\r\n`], - ]; - for (const [label, raw] of shapes) { - errorSpy.mockClear(); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { type: 'reply', from: `myslug+support@${PROD_DOMAIN}`, to: 'admin@example.com', raw }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls, label).toHaveLength(0); - expect(errorSpy, label).toHaveBeenCalledWith(expect.stringContaining('reply dropped')); - } - }); - - it('accepts a MIME From that differs from the envelope sender only by case, or carries a display name', async () => { - for (const header of [ - `MySlug+Support@${PROD_DOMAIN.toUpperCase()}`, - `"Acme Support" `, - `=?UTF-8?B?5pSv5o+0?= `, - ]) { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(header), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls, header).toHaveLength(1); - } - }); - - it("accepts replyEmail's default sender, +noreply@", async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `myslug+noreply@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`myslug+noreply@${PROD_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - expect(replyCalls[0]?.from).toBe(`myslug+noreply@${PROD_DOMAIN}`); - }); - - it('accepts the tag-less @ form', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `myslug@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`myslug@${PROD_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - }); - - // DECISION — a bare `@` reply is REFUSED. - // - // The framework strips the `+` prefix from `message.to` before the - // handler sees it, so a handler that hand-rolls `from: message.to` emits - // `@`. CF accepts that today, so refusing it is a - // deliberate, breaking narrowing. It has to be: a bare local-part is - // indistinguishable from another tenant's slug (`otherproject@`) - // and from the platform's reserved `noreply@`, so allowing the - // shape at all would re-open exactly the impersonation this pin closes. - // `replyEmail`'s default (`+noreply@`) and the wire form - // `+@` both keep working; a hand-rolled sender must - // use the preserved `message.__voidPlatformTo` (the un-stripped - // recipient) or an explicit `+…` address. - it('drops a bare @ reply (the slug-stripped message.to)', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - // What `from: message.to` yields inside a handler: the framework - // stripped `myslug+` before the handler ever saw the address. - from: `tag@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: new TextEncoder().encode('r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - }); - - it('matches the slug case-insensitively (the routed slug is lowercased, action.from is not)', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `MySlug+Support@${PROD_DOMAIN.toUpperCase()}`, - to: 'admin@example.com', - raw: replyRaw(`MySlug+Support@${PROD_DOMAIN.toUpperCase()}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - // The address is handed to EmailMessage VERBATIM — we compare folded, - // we do not rewrite the tenant's sender. - expect(replyCalls[0]?.from).toBe(`MySlug+Support@${PROD_DOMAIN.toUpperCase()}`); - }); - - it('drops a local-part that only case-FOLDS to the slug (U+212A KELVIN SIGN)', async () => { - // `'K'.toLowerCase() === 'k'`, so a lowercased compare alone would - // accept this while `EmailMessage` still receives the non-ASCII bytes - // verbatim. Same reasoning as the printable-ASCII guard in email.ts. - const { env } = makeEnv({ - kvSeed: { - kslug: DEFAULT_ROUTING, - 'email-allowlist:p_test': JSON.stringify(['admin@example.com']), - }, - emailReturn: [ - { - type: 'reply', - from: `Kslug@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`Kslug@${PROD_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `kslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - }); - - it('pins the domain to the RECEIVED recipient, not EMAIL_SENDER_DOMAIN', async () => { - // A message received on the staging zone may only be replied to from - // the staging zone — even though EMAIL_SENDER_DOMAIN says production. - const { env } = makeEnv({ - senderDomain: PROD_DOMAIN, - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`myslug+support@${PROD_DOMAIN}`, 'r'), - }, - { - type: 'reply', - from: `myslug+support@${STAGING_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`myslug+support@${STAGING_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${STAGING_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - expect(replyCalls[0]?.from).toBe(`myslug+support@${STAGING_DOMAIN}`); - }); - - it('still pins the sender when EMAIL_SENDER_DOMAIN is unset', async () => { - // The var is cosmetic here (it only labels reject reasons), so the pin - // must not acquire a dependency on it — routing keeps working without. - const { env } = makeEnv({ - senderDomain: null, - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `noreply@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`noreply@${PROD_DOMAIN}`, 'r'), - }, - { - type: 'reply', - from: `myslug+noreply@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`myslug+noreply@${PROD_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - expect(replyCalls[0]?.from).toBe(`myslug+noreply@${PROD_DOMAIN}`); - }); - - it('a dropped reply consumes NO quota', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `otherproject+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`otherproject+support@${PROD_DOMAIN}`, 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - expect(kv.store.get(SENT_KEY)).toBeUndefined(); - expect(kv.store.get(BURST_KEY)).toBeUndefined(); - expect(kv.writes.filter((w) => w.key.startsWith('email-sent:'))).toHaveLength(0); - expect(kv.writes.filter((w) => w.key.startsWith('email-burst:'))).toHaveLength(0); - }); - - it('a dropped reply does not abort the rest of the list', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: `noreply@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: replyRaw(`noreply@${PROD_DOMAIN}`, 'r'), - }, - { type: 'forward', to: 'admin@example.com' }, - ], - }); - const { message, replyCalls, forwardCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - expect(forwardCalls).toHaveLength(1); - }); -}); - -// ----------------------------------------------------------------------- -// Reply sender pin extension (design doc 0078, "What changes in the -// existing rules"): beyond `[+tag]@`, a reply may -// send as ANY address on a custom domain whose `email-domain:` -// mirror is `active` and maps to the receiving project. The mirror is the -// authorization — the router has no other view of `email_domains`. -// ----------------------------------------------------------------------- - -describe('routeInbound — reply sender pin: registered custom domains', () => { - // Dummy mirror fixture — the sha field is a placeholder hex string, never - // a real secret or checksum of one. - const registeredMirror = (projectId = 'p_test', status = 'active') => - JSON.stringify({ - projectId, - status, - relaySecretSha256: '00'.repeat(32), - relayWorkerName: 'void-email-relay', - accountId: 'acct_customer', - zoneId: 'zone_1', - mode: 'subdomain', - }); - - it('accepts any address on a domain whose active mirror maps to the receiving project', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-domain:acme.com': registeredMirror(), - }), - emailReturn: [ - { - type: 'reply', - from: 'support@acme.com', - to: 'admin@example.com', - raw: replyRaw('support@acme.com', 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - expect(replyCalls[0]?.from).toBe('support@acme.com'); - }); - - it('rejects a custom-domain sender whose mirror maps to ANOTHER project', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-domain:acme.com': registeredMirror('p_other'), - }), - emailReturn: [ - { - type: 'reply', - from: 'support@acme.com', - to: 'admin@example.com', - raw: replyRaw('support@acme.com', 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('reply dropped')); - }); - - it.each(['pending', 'token_revoked', 'token_expired', 'failed'])( - 'rejects a custom-domain sender whose mirror status is %s', - async (status) => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-domain:acme.com': registeredMirror('p_test', status), - }), - emailReturn: [ - { - type: 'reply', - from: 'support@acme.com', - to: 'admin@example.com', - raw: replyRaw('support@acme.com', 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - }, - ); - - it('rejects a custom-domain sender with no mirror at all', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'reply', - from: 'support@unregistered.example', - to: 'admin@example.com', - raw: replyRaw('support@unregistered.example', 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - }); - - it('fails closed when the mirror read throws — the reply is dropped, the delivery is not retried', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-domain:acme.com': registeredMirror(), - }), - kvGetFailures: ['email-domain:acme.com'], - emailReturn: [ - { - type: 'reply', - from: 'support@acme.com', - to: 'admin@example.com', - raw: replyRaw('support@acme.com', 'r'), - }, - ], - }); - const { message, rejectCalls, replyCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - // A dropped action is not a bounce. - expect(rejectCalls).toHaveLength(0); - }); - - it('memoizes the mirror lookup across replies from one domain in a message', async () => { - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - 'email-domain:acme.com': registeredMirror(), - }), - emailReturn: [ - { - type: 'reply', - from: 'support@acme.com', - to: 'admin@example.com', - raw: replyRaw('support@acme.com', 'r'), - }, - { - type: 'reply', - from: 'sales@acme.com', - to: 'admin@example.com', - raw: replyRaw('sales@acme.com', 'r'), - }, - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(2); - const mirrorReads = kv.get.mock.calls.filter(([key]) => key === 'email-domain:acme.com'); - expect(mirrorReads).toHaveLength(1); - }); -}); - -// ----------------------------------------------------------------------- -// Reject reasons are truncated BEFORE control chars are stripped. -// -// `sanitize()` used to run its global replacement over the whole string and -// only then slice. A control-heavy reason makes V8 materialize one part per -// match (~68 B each, measured), so a 4 MB `\0a\0a…` reason — 8x below the -// 32 MiB RPC ceiling — is ~140 MB of transient heap in the 128 MB proxy -// isolate, ahead of every outbound gate. Slicing first bounds the work to -// `maxLen` code units. -// ----------------------------------------------------------------------- - -describe('routeInbound — reject reason is truncated before sanitizing', () => { - it('bounds a multi-megabyte control-heavy reason without a full-string pass', async () => { - // 32 MiB of alternating NUL / letter: one regex match per NUL, which is - // the shape that maximizes the parts array. The RPC transport could not - // deliver a larger reason. - const reason = '\x00a'.repeat(16 * 1024 * 1024); - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [{ type: 'reject', reason }], - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const t0 = performance.now(); - await routeInbound(message, env, ctx); - const elapsed = performance.now() - t0; - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]!.length).toBeLessThanOrEqual(1000); - // oxlint-disable-next-line no-control-regex - expect(rejectCalls[0]).not.toMatch(new RegExp('[\\u0000-\\u001f\\u007f]')); - // Generous: the slice-first path is ~0 ms; the old order measured 800+ ms - // on this input on a laptop, and an OOM under a 128 MB heap. - expect(elapsed).toBeLessThan(500); - }); - - it('collapses controls inside the 1000-char window and does not refill from beyond it', async () => { - // 300 x "line\r\n" is 1800 chars. Slice-first keeps the first 1000 code - // units — 166 full lines (996) plus "line" — then each CRLF becomes one - // space, so the reason is 834 clean chars, not 1000. The reason is DSN - // text for a remote MTA, so a shorter window is the acceptable trade. - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [{ type: 'reject', reason: 'line\r\n'.repeat(300) }], - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toBe('line '.repeat(166) + 'line'); - }); -}); - -// ----------------------------------------------------------------------- -// Untrusted values are never coerced with `String()` for a log line. -// -// `sanitize(String(x), 320)` is bounded only when `x` is a string. A typed -// array or an Array as an action's `type` (or as an address that failed -// validation) is joined element by element before the slice — measured, a -// 30 MB `Uint8Array` is a 107M-char string, +385 MB and ~580 ms, an OOM -// under the 128 MB isolate — and a BigInt as the action itself is a decimal -// conversion superlinear in its size (4 MiB: 1.9 s; 32 MiB: 20 s of CPU). -// All of it runs ahead of every outbound gate, from any hand-built -// entrypoint. `describeUntrusted` renders such values by kind only. -// ----------------------------------------------------------------------- - -describe('routeInbound — non-string action fields are described, not coerced', () => { - /** Heap growth across `fn`, in MB, with a GC before when one is exposed. */ - async function heapDeltaMB(fn: () => Promise): Promise { - (globalThis as { gc?: () => void }).gc?.(); - const before = process.memoryUsage().heapUsed; - await fn(); - return (process.memoryUsage().heapUsed - before) / (1024 * 1024); - } - - function warnLines(): Array { - return warnSpy.mock.calls.map((call) => String(call[0])); - } - function errorLines(): Array { - return errorSpy.mock.calls.map((call) => String(call[0])); - } - - it('a 30 MB Uint8Array as an unknown action `type` is logged by kind, in bounded time and heap', async () => { - const type = new Uint8Array(30 * 1024 * 1024).fill(0x41); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [{ type }, { type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const t0 = performance.now(); - const grew = await heapDeltaMB(() => routeInbound(message, env, ctx)); - const elapsed = performance.now() - t0; - const line = warnLines().find((l) => l.includes('dropping unknown action type')); - expect(line).toBe('[email-router] dropping unknown action type: [object Uint8Array]'); - // The list continues: the unknown entry is skipped, the forward fires. - expect(forwardCalls).toHaveLength(1); - // `String(type)` alone measured ~580 ms and +385 MB on this input. - expect(elapsed).toBeLessThan(100); - expect(grew).toBeLessThan(64); - }); - - it.each([ - ['a nested Array', [[1, 2], [3]], '[object Array]'], - ['a plain object', { nested: true }, '[object Object]'], - ['a BigInt', 1n << 4096n, '[bigint]'], - ['null', null, 'null'], - ['a number', 42, '42'], - ['a boolean', false, 'false'], - ['undefined', undefined, 'undefined'], - ])('an unknown action `type` that is %s is rendered by kind', async (_label, type, rendered) => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [{ type }], - }); - const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(warnLines()).toContain(`[email-router] dropping unknown action type: ${rendered}`); - }); - - it('a string `type` is still rendered, sliced then stripped', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [{ type: `quarantine\r\n${'x'.repeat(1000)}` }], - }); - const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - const line = warnLines().find((l) => l.includes('dropping unknown action type')); - expect(line).toBe(`[email-router] dropping unknown action type: quarantine ${'x'.repeat(308)}`); - }); - - it('a 30 MB control-heavy string as the action itself is bounded', async () => { - // Already closed by the slice-first `sanitize` — `String()` of a string - // is the string — pinned here beside the cases it does not cover. - const action = '\x00a'.repeat(15 * 1024 * 1024); - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [action], - }); - const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const t0 = performance.now(); - await routeInbound(message, env, ctx); - expect(performance.now() - t0).toBeLessThan(100); - const line = errorLines().find((l) => l.includes('dropping non-object action')); - expect(line).toBeDefined(); - expect(line!.length).toBeLessThanOrEqual( - '[email-router] dropping non-object action: '.length + 320, - ); - // oxlint-disable-next-line no-control-regex - expect(line).not.toMatch(new RegExp('[\\u0000-\\u001f\\u007f]')); - }); - - it('a BigInt as the action itself is logged by kind, never converted to decimal', async () => { - // 4 MiB of magnitude: `String()` of it measured 1.9 s of CPU. The - // transport could carry eight times this. - const action = 1n << BigInt(4 * 1024 * 1024 * 8); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [action, { type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const t0 = performance.now(); - await routeInbound(message, env, ctx); - expect(performance.now() - t0).toBeLessThan(100); - expect(errorLines()).toContain('[email-router] dropping non-object action: [bigint]'); - expect(forwardCalls).toHaveLength(1); - }); - - it('a 30 MB Uint8Array as a forward `to` is logged by kind', async () => { - // `logAddress` renders whatever failed `isValidEmailAddress`, which is - // not necessarily a string. - const to = new Uint8Array(30 * 1024 * 1024).fill(0x41); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [{ type: 'forward', to }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const t0 = performance.now(); - const grew = await heapDeltaMB(() => routeInbound(message, env, ctx)); - expect(performance.now() - t0).toBeLessThan(100); - expect(grew).toBeLessThan(64); - expect(errorLines()).toContain( - '[email-router] forward dropped: invalid "to" address [object Uint8Array]', - ); - expect(forwardCalls).toHaveLength(0); - }); -}); - -// ----------------------------------------------------------------------- -// Proxy-side reply size limits. -// -// The framework bounds a `reply()` at `MAX_MESSAGE_BYTES` (10 MiB) and one -// dispatch's replies at `MAX_REPLY_BYTES_TOTAL` (20 MiB), but those checks -// run inside the tenant's own worker. A hand-written Workers-for-Platforms -// entrypoint can return any `Uint8Array` the 32 MiB RPC transport carries, -// and the router used to scan it for `From:` and stream it into -// `message.reply()` with no bound of its own. Same belt-and-suspenders split -// as `MAX_ACTIONS`. -// ----------------------------------------------------------------------- - -describe('routeInbound — reply size limits', () => { - const MIB = 1024 * 1024; - const SENDER = `myslug+support@${PROD_DOMAIN}`; - - /** `size` bytes of reply MIME with a valid `From:` naming the sender. */ - function sizedReply(size: number, from = SENDER): Uint8Array { - const head = new TextEncoder().encode(`From: ${from}\r\n\r\n`); - const raw = new Uint8Array(size); - raw.set(head); - raw.fill(0x41, head.length); - return raw; - } - - function replyAction(raw: Uint8Array) { - return { type: 'reply', from: SENDER, to: 'admin@example.com', raw }; - } - - it('drops a reply over 10 MiB before the MIME From scan', async () => { - // No `From:` header at all: if the size check ran AFTER the scan, the - // drop would be logged as a missing From header instead. - const raw = new Uint8Array(10 * MIB + 1).fill(0x41); - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [replyAction(raw)], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalledWith( - expect.stringContaining(`reply dropped: raw is ${10 * MIB + 1} bytes (max ${10 * MIB})`), - ); - expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining('no From header')); - expect(kv.store.get(SENT_KEY)).toBeUndefined(); - }); - - it('accepts a reply of exactly 10 MiB', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [replyAction(sizedReply(10 * MIB))], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(1); - expect(replyCalls[0]?.from).toBe(SENDER); - }); - - it('three 8 MiB replies: the third overruns the 20 MiB budget and is dropped, the rest fire', async () => { - // The overrunning reply is dropped and NOT charged, exactly as the - // framework's `reply()` throws before advancing `replyBytesUsed`: a - // later reply that fits the remaining budget (16 + 4 = 20 MiB) still - // goes. - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - replyAction(sizedReply(8 * MIB)), - replyAction(sizedReply(8 * MIB)), - replyAction(sizedReply(8 * MIB)), - replyAction(sizedReply(4 * MIB)), - ], - }); - const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(3); - expect(errorSpy).toHaveBeenCalledTimes(1); - expect(errorSpy).toHaveBeenCalledWith( - expect.stringContaining( - `reply dropped: cumulative reply bytes ${24 * MIB} exceed this delivery's budget of ${20 * MIB}`, - ), - ); - // Three enacted replies, three quota units. - expect(kv.store.get(SENT_KEY)).toBe('3'); - expect(kv.store.get(BURST_KEY)).toBe('3'); - }); -}); - -// ----------------------------------------------------------------------- -// Framework ↔ router parity for the record-time bounds. -// -// The framework's `createMessageProxy` restates `MAX_FORWARD_HEADERS`, -// `MAX_FORWARD_HEADER_LENGTH` and `MAX_REJECT_REASON_LENGTH` and applies -// them where the action is RECORDED — in the handler's own call — so the -// test harness (which builds its message with that proxy) and a native -// own-account replay answer what this router answers. A number that -// drifted on one side would reopen the gap: a forward the harness reports -// and this router drops, or a reject reason that is clean here and injects -// into the SMTP reply natively. The numbers are pinned equal, and the -// agreement is pinned at the bound in both directions: the largest bag the -// proxy records is enacted here, one past it is refused there and dropped -// here, and a reason the proxy has normalized passes through this router -// unchanged. -// -// The harness also restates this router's ADMISSION — `MAX_INBOUND_BYTES` -// and `MAX_INBOUND_HEADERS` — and refuses a synthetic message before the -// handler runs, as `routeInbound` refuses the real one before dispatch. A -// number that drifted there would let a test invoke a handler on a message -// this router bounces. Pinned equal, and pinned in behaviour: the same -// bytes, one past each cap, draw the same reject string from both sides -// with the handler never called. -// ----------------------------------------------------------------------- - -describe('framework ↔ router bound parity', () => { - const ENVELOPE = { - from: 'sender@example.com', - to: 'tag@example.com', - headers: {}, - raw: new TextEncoder().encode('Subject: hi\r\n\r\nbody\r\n'), - rawSize: 21, - }; - - it('restates the same numbers', () => { - // Guarded on type: an export missing on either side reads `undefined`, - // and `undefined === undefined` is not parity. - for (const [framework, router] of [ - [FRAMEWORK_MAX_FORWARD_HEADERS, MAX_FORWARD_HEADERS], - [FRAMEWORK_MAX_FORWARD_HEADER_LENGTH, MAX_FORWARD_HEADER_LENGTH], - [FRAMEWORK_MAX_REJECT_REASON_LENGTH, MAX_REJECT_REASON_LENGTH], - [FRAMEWORK_MAX_INBOUND_BYTES, MAX_INBOUND_BYTES], - [FRAMEWORK_MAX_INBOUND_HEADERS, MAX_INBOUND_HEADERS], - ]) { - expect(router).toBeTypeOf('number'); - expect(framework).toBe(router); - } - }); - - it('enacts the largest forward header bag the framework records', async () => { + it('enacts the maximum forward header count within the action metadata budget', async () => { const bag: Record = {}; for (let i = 0; i < MAX_FORWARD_HEADERS; i++) { const suffix = String(i).padStart(2, '0'); - bag[`X-${'a'.repeat(MAX_FORWARD_HEADER_LENGTH - 2 - suffix.length)}${suffix}`] = 'v'.repeat( - MAX_FORWARD_HEADER_LENGTH, - ); + bag[`X-Forward-${suffix}`] = 'v'.repeat(200); } const proxy = createMessageProxy(ENVELOPE); await proxy.message.forward('admin@example.com', bag as unknown as Headers); diff --git a/platform/packages/proxy/test/unit/email.test.ts b/platform/packages/proxy/test/unit/email.test.ts index ae4cd3033..73e5f14eb 100644 --- a/platform/packages/proxy/test/unit/email.test.ts +++ b/platform/packages/proxy/test/unit/email.test.ts @@ -85,13 +85,76 @@ function createMockEnv( kv: MockKv, overrides: Record = {}, ): Record { + const actions = new Map< + string, + { + operationId: string; + digest: string; + recipients: Array<{ + recipient: string; + state: string; + errorCode: string | null; + providerReference: string | null; + }>; + } + >(); + const apiFetch = vi.fn(async (url: string, init: RequestInit) => { + const path = new URL(url).pathname; + const body = JSON.parse(String(init.body)) as Record; + if (path.endsWith('/admit')) { + const key = body.key as string; + const previous = actions.get(key); + if (previous && previous.digest !== body.digest) { + return Response.json({ code: 'CONFLICT' }, { status: 409 }); + } + if (previous) { + return Response.json({ + operationId: previous.operationId, + replay: true, + recipients: previous.recipients, + }); + } + const entry = { + operationId: `act_${actions.size + 1}`, + digest: body.digest as string, + recipients: (body.recipients as Array).map((recipient) => ({ + recipient, + state: 'reserved', + errorCode: null, + providerReference: null, + })), + }; + actions.set(key, entry); + return Response.json({ + operationId: entry.operationId, + replay: false, + recipients: entry.recipients, + }); + } + const operationId = path.split('/').at(-2)!; + const entry = [...actions.values()].find((action) => action.operationId === operationId)!; + if (path.endsWith('/start')) { + for (const recipient of body.recipients as Array) { + entry.recipients.find((row) => row.recipient === recipient)!.state = 'attempt_started'; + } + } + if (path.endsWith('/finish')) { + for (const recipient of body.recipients as Array) { + const row = entry.recipients.find((item) => item.recipient === recipient)!; + row.state = body.state as string; + row.errorCode = (body.errorCode as string) ?? null; + row.providerReference = (body.providerReference as string) ?? null; + } + } + return Response.json({ recipients: entry.recipients }); + }); return { AI: {}, JWT_SECRET, ROUTING: kv, CF_ACCOUNT_ID: 'acct', CF_API_TOKEN: 'cf-token', - API: { fetch: vi.fn() }, + API: { fetch: apiFetch }, DISPATCH: { get: vi.fn(() => ({ email: vi.fn(async () => []) })) }, SEND_EMAIL: { send: vi.fn(async () => ({ messageId: 'msg_1' })) }, EMAIL_SENDER_DOMAIN: PROD_DOMAIN, @@ -288,7 +351,8 @@ describe('POST /email/send — sender domain', () => { expect(res.status).toBe(200); expect(await res.json()).toEqual({ ok: true, - ids: [{ recipient: 'dev@example.com', messageId: 'msg_1' }], + ids: [{ recipient: 'dev@example.com', messageId: 'msg_1', state: 'provider_accepted' }], + operationId: 'act_1', }); }); @@ -297,8 +361,7 @@ describe('POST /email/send — sender domain', () => { const res = await postSend(env, await sendBody()); const body = (await res.json()) as { ok: boolean; error: { code: string; message: string } }; expect(body.ok).toBe(false); - expect(body.error.code).toBe('INVALID_FROM'); - expect(body.error.message).toContain(STAGING_DOMAIN); + expect(body.error.code).toBe('UPSTREAM_ERROR'); expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); }); @@ -374,145 +437,6 @@ describe('POST /email/send — platform capability', () => { }); }); -describe('POST /email/send — suspension', () => { - it('refuses when the routing blob carries the platform-wide suspended marker', async () => { - const kv = happyPathKv({ acme: JSON.stringify({ projectId: 'proj_1', suspended: 'abuse' }) }); - const env = createMockEnv(kv); - const res = await postSend(env, await sendBody()); - const body = (await res.json()) as { ok: boolean; error: { code: string; message: string } }; - expect(body.ok).toBe(false); - expect(body.error.code).toBe('QUOTA_EXCEEDED'); - expect(body.error.message).toContain('abuse'); - expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); - }); - - it('still sends when the routing blob exists without a suspended marker', async () => { - const kv = happyPathKv({ acme: JSON.stringify({ projectId: 'proj_1', workerName: 'w' }) }); - const res = await postSend(createMockEnv(kv), await sendBody()); - expect(((await res.json()) as { ok: boolean }).ok).toBe(true); - }); - - it('still sends when the project has no routing blob at all', async () => { - // A missing blob is a legitimate production state: the marker is only - // ever written INTO an existing entry, so a project that has not been - // routed yet has nothing suspended. Failing closed on absence would - // break every send made before the first routing write. - const kv = happyPathKv(); - const res = await postSend(createMockEnv(kv), await sendBody()); - expect(((await res.json()) as { ok: boolean }).ok).toBe(true); - expect(kv.get.mock.calls.some((call) => call[0] === 'acme')).toBe(true); - }); - - it('fails closed with 502 when the routing blob is unparseable', async () => { - // Unlike a missing blob, a malformed one has no legitimate writer — - // every producer JSON.stringify's an object. Reading a parse failure as - // "not suspended" would silently disable the platform-wide suspension - // gate for exactly the project whose routing entry got corrupted. - const kv = happyPathKv({ acme: '{"projectId":"proj_1","suspended":' }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); - try { - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(502); - const body = await readSend(res); - expect(body.error?.code).toBe('UPSTREAM_ERROR'); - expect(body.error?.message).toContain('malformed'); - expect(consoleError).toHaveBeenCalled(); - expect(sender.calls).toHaveLength(0); - expect(kv.put).not.toHaveBeenCalled(); - } finally { - consoleError.mockRestore(); - } - }); - - // A truthy marker that is not a string has no writer — every producer - // stamps a non-empty reason string or deletes the key — but the two - // sibling readers refuse on it by truthiness: dispatch answers - // `if (routing.suspended)` with a 429 and the inbound router rejects. The - // send path must not be the one gate that reads the same value as "clear", - // so it fails closed exactly like an unparseable blob. - it.each([ - ['true', true], - ['a number', 42], - ['an object', {}], - ['an array', ['x']], - ])('fails closed with 502 when the suspended marker is %s', async (_kind, suspended) => { - const kv = happyPathKv({ acme: JSON.stringify({ projectId: 'proj_1', suspended }) }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); - try { - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(502); - const body = await readSend(res); - expect(body.error?.code).toBe('UPSTREAM_ERROR'); - expect(body.error?.message).toContain('malformed'); - expect(consoleError).toHaveBeenCalled(); - expect(sender.calls).toHaveLength(0); - expect(kv.put).not.toHaveBeenCalled(); - } finally { - consoleError.mockRestore(); - } - }); - - // A falsy present marker is "not suspended" to both sibling readers, and - // no writer produces one today (an unsuspend DELETES the key). The send - // path stays aligned so a future clear that stamps `suspended: null` - // cannot brick every send. `undefined` is the absent key: `JSON.stringify` - // drops it, so that row pins the no-marker blob through the same table. - it.each([ - ['absent', undefined], - ['null', null], - ['false', false], - ['an empty string', ''], - ['zero', 0], - ])( - 'still sends when the suspended marker is %s (falsy to every reader)', - async (_kind, suspended) => { - const kv = happyPathKv({ acme: JSON.stringify({ projectId: 'proj_1', suspended }) }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(200); - expect((await readSend(res)).ok).toBe(true); - expect(sender.calls).toHaveLength(1); - }, - ); - - it('refuses when the email-only kill-switch is set', async () => { - const kv = happyPathKv({ 'email-suspended:proj_1': '1' }); - const env = createMockEnv(kv); - const res = await postSend(env, await sendBody()); - expect(((await res.json()) as { error: { code: string } }).error.code).toBe('QUOTA_EXCEEDED'); - expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); - }); - - // Suspension is an abuse-response control: convergence latency is the whole - // point, so both suspension reads deliberately pay for an uncached KV get. - // Nothing else pins this — a stray `{ cacheTtl: 60 }` would leave a - // suspended project sending for another minute per colo. - it('reads both suspension keys with no cacheTtl', async () => { - const kv = happyPathKv({ acme: JSON.stringify({ projectId: 'proj_1' }) }); - await postSend(createMockEnv(kv), await sendBody()); - - const suspendCall = kv.get.mock.calls.find((call) => call[0] === 'email-suspended:proj_1'); - expect(suspendCall, 'the email suspend key was never read').toBeDefined(); - expect(suspendCall?.[1]).toBeUndefined(); - - const routingCall = kv.get.mock.calls.find((call) => call[0] === 'acme'); - expect(routingCall, 'the routing blob was never read').toBeDefined(); - expect(routingCall?.[1]).toBeUndefined(); - }); - - it('reads the allowlist with a cacheTtl (the non-abuse-response path)', async () => { - const kv = happyPathKv(); - await postSend(createMockEnv(kv), await sendBody()); - const call = kv.get.mock.calls.find((c) => c[0] === 'email-allowlist:proj_1'); - expect(call?.[1]).toEqual({ cacheTtl: 60 }); - }); -}); - describe('POST /email/internal/send', () => { async function internalBody( domain: string, @@ -598,141 +522,6 @@ describe('POST /email/internal/send', () => { }); }); -describe('inbound email router', () => { - function routingKv(entry: Record, extra: Record = {}) { - return createMockKv({ - acme: JSON.stringify(entry), - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com']), - ...extra, - }); - } - - it('passes the project dispatch limits into DISPATCH.get', async () => { - const kv = routingKv({ - workerName: 'user-worker', - projectId: 'proj_1', - limits: { cpuMs: 12_345 }, - }); - const env = createMockEnv(kv); - await routeInboundMessage(env, createInboundMessage(`acme+support@${PROD_DOMAIN}`)); - - const dispatchGet = (env.DISPATCH as { get: ReturnType }).get; - expect(dispatchGet).toHaveBeenCalledWith('user-worker', {}, { limits: { cpuMs: 12_345 } }); - }); - - it('omits the limits argument when routing has none', async () => { - const kv = routingKv({ workerName: 'user-worker', projectId: 'proj_1' }); - const env = createMockEnv(kv); - await routeInboundMessage(env, createInboundMessage(`acme@${PROD_DOMAIN}`)); - expect((env.DISPATCH as { get: ReturnType }).get).toHaveBeenCalledWith( - 'user-worker', - ); - }); - - it('rejects — without dispatching — when the project is platform-suspended', async () => { - const kv = routingKv({ workerName: 'user-worker', projectId: 'proj_1', suspended: 'abuse' }); - const env = createMockEnv(kv); - const message = createInboundMessage(`acme+support@${PROD_DOMAIN}`); - await routeInboundMessage(env, message); - - expect((env.DISPATCH as { get: ReturnType }).get).not.toHaveBeenCalled(); - expect(message.setReject).toHaveBeenCalledTimes(1); - expect(String(message.setReject.mock.calls[0][0])).toContain('suspended'); - }); - - it('rejects — without dispatching — when the email kill-switch is set', async () => { - const kv = routingKv( - { workerName: 'user-worker', projectId: 'proj_1' }, - { 'email-suspended:proj_1': '1' }, - ); - const env = createMockEnv(kv); - const message = createInboundMessage(`acme+support@${PROD_DOMAIN}`); - await routeInboundMessage(env, message); - - expect((env.DISPATCH as { get: ReturnType }).get).not.toHaveBeenCalled(); - expect(message.setReject).toHaveBeenCalledTimes(1); - }); - - it('reads the inbound suspend key with no cacheTtl', async () => { - const kv = routingKv({ workerName: 'user-worker', projectId: 'proj_1' }); - await routeInboundMessage(createMockEnv(kv), createInboundMessage(`acme@${PROD_DOMAIN}`)); - const call = kv.get.mock.calls.find((c) => c[0] === 'email-suspended:proj_1'); - expect(call, 'the email suspend key was never read').toBeDefined(); - expect(call?.[1]).toBeUndefined(); - }); - - // The routing blob is keyed by slug, so a project that registered - // `noreply` before it was reserved would receive every bounce and reply to - // the platform's own verification mail (`noreply@`), and a - // `postmaster` project the domain's abuse reports. - it.each([ - ['bare noreply', 'noreply', `noreply@${PROD_DOMAIN}`], - ['tagged noreply', 'noreply', `noreply+bounce@${PROD_DOMAIN}`], - ['postmaster', 'postmaster', `postmaster@${PROD_DOMAIN}`], - ['mixed case', 'abuse', `Abuse@${PROD_DOMAIN}`], - ])( - 'rejects mail to a reserved email identity (%s) without reading routing or dispatching', - async (_label, slug, to) => { - const kv = createMockKv({ - [slug]: JSON.stringify({ workerName: 'legacy-worker', projectId: 'proj_legacy' }), - }); - const env = createMockEnv(kv); - const message = createInboundMessage(to); - await routeInboundMessage(env, message); - - expect((env.DISPATCH as { get: ReturnType }).get).not.toHaveBeenCalled(); - expect(message.setReject).toHaveBeenCalledTimes(1); - expect(String(message.setReject.mock.calls[0][0])).toContain('reserved'); - expect(kv.get).not.toHaveBeenCalled(); - }, - ); - - it('still routes an ordinary slug that merely CONTAINS a reserved word', async () => { - const kv = createMockKv({ - 'noreply-tools': JSON.stringify({ workerName: 'user-worker', projectId: 'proj_1' }), - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com']), - }); - const env = createMockEnv(kv); - const message = createInboundMessage(`noreply-tools+x@${PROD_DOMAIN}`); - await routeInboundMessage(env, message); - expect((env.DISPATCH as { get: ReturnType }).get).toHaveBeenCalledWith( - 'user-worker', - ); - expect(message.setReject).not.toHaveBeenCalled(); - }); - - it('names the configured zone in reject reasons', async () => { - const env = createMockEnv(createMockKv(), { EMAIL_SENDER_DOMAIN: STAGING_DOMAIN }); - const message = createInboundMessage(`nosuchproject@${STAGING_DOMAIN}`); - await routeInboundMessage(env, message); - expect(String(message.setReject.mock.calls[0][0])).toContain(STAGING_DOMAIN); - }); - - it('still routes when EMAIL_SENDER_DOMAIN is unset (inbound never fails closed on it)', async () => { - const kv = routingKv({ workerName: 'user-worker', projectId: 'proj_1' }); - const env = createMockEnv(kv, { EMAIL_SENDER_DOMAIN: undefined }); - const message = createInboundMessage(`acme@${PROD_DOMAIN}`); - await routeInboundMessage(env, message); - expect((env.DISPATCH as { get: ReturnType }).get).toHaveBeenCalled(); - expect(message.setReject).not.toHaveBeenCalled(); - }); -}); - -// --------------------------------------------------------------------------- -// Outbound coverage restored from the original PR, re-aimed at the current -// contracts: the mail domain is configuration (`EMAIL_SENDER_DOMAIN`), the -// slug mirror pins the `from` local-part, and the gate chain runs -// size -> from -> suspend -> allowlist -> quota. -// --------------------------------------------------------------------------- - -/** - * Drain the `raw` argument the handler passed to `new EmailMessage(...)`. - * - * The bytes matter, not just the call count: `bytesToStream(raw)` is built - * INSIDE the fan-out loop precisely because a ReadableStream is one-shot. A - * regression that hoisted one stream out of the loop still records N sends — - * only the delivered bytes show that recipients 2..N got an empty body. - */ async function drainStream(raw: unknown): Promise { if (typeof raw === 'string') { return new TextEncoder().encode(raw); @@ -866,8 +655,7 @@ describe('POST /email/send — request validation', () => { ); expect((await readSend(res)).ok).toBe(true); expect(sender.recipients()).toEqual(['dev@example.com']); - // One recipient, therefore one unit of quota — not three. - expect(kv.store.get(monthKeyFor('proj_1'))).toBe('1'); + expect(kv.store.get(monthKeyFor('proj_1'))).toBeUndefined(); }); it('rejects invalid base64 with 400 MIME_ERROR', async () => { @@ -877,6 +665,16 @@ describe('POST /email/send — request validation', () => { expect((await readSend(res)).error?.code).toBe('MIME_ERROR'); }); + it('rejects over 16 KiB of custom MIME headers before admission or provider send', async () => { + const env = createMockEnv(happyPathKv()); + const raw = mimeFor(DEFAULT_FROM, `X-Large: ${'a'.repeat(16 * 1024)}\r\n\r\nbody`); + const res = await postSend(env, await sendBody({ mimeBase64: mimeBase64(raw) })); + expect(res.status).toBe(413); + expect((await readSend(res)).error?.code).toBe('MIME_ERROR'); + expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); + expect((env.API as { fetch: ReturnType }).fetch).not.toHaveBeenCalled(); + }); + it('rejects a bad project HMAC with 403 before any handler work', async () => { const kv = happyPathKv(); const env = createMockEnv(kv); @@ -941,7 +739,7 @@ describe('POST /email/send — request validation', () => { expect((await readSend(res)).ok).toBe(true); expect(sender.recipients()).toEqual(recipients); - expect(kv.store.get(monthKeyFor('proj_1'))).toBe(String(MAX_RECIPIENTS)); + expect(kv.store.get(monthKeyFor('proj_1'))).toBeUndefined(); }); // `MAX_RECIPIENTS` alone still leaves a 100 x
amplifier, @@ -1014,190 +812,6 @@ describe('POST /email/send — request validation', () => { }); }); -describe('POST /email/send — sender pinning (cross-project tenancy)', () => { - it.each([ - ['bare @domain', `acme@${PROD_DOMAIN}`], - ['+tag@domain', `acme+billing@${PROD_DOMAIN}`], - ['a tag using the full safe charset', `acme+a.b_c=d/e-f@${PROD_DOMAIN}`], - ['mixed case (normalized before the compare)', 'ACME+Tag@MAIL.VOID.CLOUD'], - ])('accepts %s', async (_label, from) => { - const sender = createSender(); - const env = createMockEnv(happyPathKv(), { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from })); - expect((await readSend(res)).ok, `${from} should have been accepted`).toBe(true); - expect(sender.calls).toHaveLength(1); - // The envelope is forwarded verbatim — normalization is for the compare - // only, so CF sees exactly the address the caller submitted. - expect(sender.calls[0].from).toBe(from); - }); - - it("refuses to send as another project's slug", async () => { - // proj_1 is `acme`; proj_2 is `victim`. The account-level send_email - // binding would happily accept either — the slug mirror is the only - // thing standing between the two tenants. - const kv = happyPathKv({ 'email-slug:proj_2': 'victim' }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from: `victim+noreply@${PROD_DOMAIN}` })); - const body = await readSend(res); - expect(body.ok).toBe(false); - expect(body.error?.code).toBe('INVALID_FROM'); - expect(sender.calls).toHaveLength(0); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - }); - - it.each([ - ['a different local part entirely', `spoof@${PROD_DOMAIN}`], - ['the slug as a PREFIX of a longer local part', `acmex@${PROD_DOMAIN}`], - ['the slug with a dotted suffix', `acme.evil@${PROD_DOMAIN}`], - ['the slug with a dashed suffix', `acme-evil@${PROD_DOMAIN}`], - ['an unrelated domain', 'acme@evil.com'], - ['a subdomain of the configured zone', `acme@sub.${PROD_DOMAIN}`], - ['the configured zone as a prefix of a longer domain', `acme@${PROD_DOMAIN}.evil.com`], - ['a `+` tag with a disallowed character', `acme+a%b@${PROD_DOMAIN}`], - ['a second `@`', `acme@${PROD_DOMAIN}@${PROD_DOMAIN}`], - ['an empty local part', `@${PROD_DOMAIN}`], - ['an empty `+` tag', `acme+@${PROD_DOMAIN}`], - ])('rejects %s with INVALID_FROM', async (_label, from) => { - const sender = createSender(); - const env = createMockEnv(happyPathKv(), { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from })); - const body = await readSend(res); - expect(body.ok, `${from} should have been rejected`).toBe(false); - expect(body.error?.code).toBe('INVALID_FROM'); - expect(sender.calls).toHaveLength(0); - }); - - it.each([ - ['carriage return', `acme+x\r\nX-Bcc: attacker@evil.com@${PROD_DOMAIN}`], - ['line feed', `acme+x\nX-Bcc: attacker@evil.com@${PROD_DOMAIN}`], - ['display name with angle brackets', `Foo `], - ['quoted local part', `"ac+me"@${PROD_DOMAIN}`], - ['leading whitespace', ` acme@${PROD_DOMAIN}`], - ['trailing whitespace', `acme@${PROD_DOMAIN} `], - ['null byte in the local part', `acme\x00@${PROD_DOMAIN}`], - ['control byte in the +tag', `acme+\x01abc@${PROD_DOMAIN}`], - ['DEL in the +tag', `acme+abc\x7fdef@${PROD_DOMAIN}`], - ['BEL in the +tag', `acme+\x07@${PROD_DOMAIN}`], - ])('rejects header-injection shaped from (%s)', async (_label, from) => { - const sender = createSender(); - const env = createMockEnv(happyPathKv(), { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from })); - const body = await readSend(res); - expect(body.ok, `${JSON.stringify(from)} should have been rejected`).toBe(false); - expect(body.error?.code).toBe('INVALID_FROM'); - expect(sender.calls).toHaveLength(0); - }); - - it('names the expected slug and the configured zone in the refusal', async () => { - const env = createMockEnv(happyPathKv()); - const res = await postSend(env, await sendBody({ from: `spoof@${PROD_DOMAIN}` })); - const message = (await readSend(res)).error?.message ?? ''; - expect(message).toContain('acme'); - expect(message).toContain(PROD_DOMAIN); - }); - - it('fails closed with 502 when the slug mirror is missing', async () => { - const kv = createMockKv({ 'email-allowlist:proj_1': JSON.stringify(['dev@example.com']) }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(502); - expect((await readSend(res)).error?.code).toBe('UPSTREAM_ERROR'); - expect(sender.calls).toHaveLength(0); - expect(kv.put).not.toHaveBeenCalled(); - }); - - it('fails closed with 502 when the slug mirror is poisoned with a malformed slug', async () => { - // A poisoned slug must surface as an operator-visible error, not as a - // silent permanent denial for every future send by that project. - const kv = happyPathKv({ 'email-slug:proj_1': 'BADSLUG!' }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); - try { - const res = await postSend(env, await sendBody({ from: `badslug!@${PROD_DOMAIN}` })); - expect(res.status).toBe(502); - const body = await readSend(res); - expect(body.error?.code).toBe('UPSTREAM_ERROR'); - expect(body.error?.message).toContain('malformed'); - expect(sender.calls).toHaveLength(0); - expect(kv.put).not.toHaveBeenCalled(); - } finally { - consoleError.mockRestore(); - } - }); - - it('reads the slug mirror without pinning a cacheTtl', async () => { - const kv = happyPathKv(); - await postSend(createMockEnv(kv), await sendBody()); - const call = kv.get.mock.calls.find((c) => c[0] === 'email-slug:proj_1'); - expect(call, 'the slug mirror was never read').toBeDefined(); - expect(call?.[1]).toBeUndefined(); - }); -}); - -describe('POST /email/send — reserved email identities (legacy slug holders)', () => { - // `noreply`, `postmaster`, `abuse`, `bounce` and `security` joined - // `RESERVED_SLUGS` only when email shipped. A project that registered one - // of them BEFORE that still holds the slug and, until the api's hourly - // backfill withholds it, its `email-slug:` mirror — which is all the pin - // above checks. `noreply@` is the platform's own verification - // sender, so such a project could send mail indistinguishable from ours. - /** KV exactly as the mirror stands for a pre-reservation `noreply` project. */ - function legacyKv(slug: string) { - return createMockKv({ - 'email-slug:proj_1': slug, - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com']), - }); - } - - it.each([ - ["the platform's own sender, bare", 'noreply', `noreply@${PROD_DOMAIN}`], - ["the platform's own sender, tagged", 'noreply', `noreply+verify@${PROD_DOMAIN}`], - ['postmaster', 'postmaster', `postmaster@${PROD_DOMAIN}`], - ['abuse', 'abuse', `abuse+x@${PROD_DOMAIN}`], - ['bounce', 'bounce', `bounce@${PROD_DOMAIN}`], - ['security', 'security', `security@${PROD_DOMAIN}`], - ])('refuses %s even though the mirror pins that very slug', async (_label, slug, from) => { - const kv = legacyKv(slug); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from })); - expect(res.status).toBe(403); - const body = await readSend(res); - expect(body.ok).toBe(false); - expect(body.error?.code).toBe('INVALID_FROM'); - expect(body.error?.message).toContain('reserved'); - expect(sender.calls).toHaveLength(0); - // Refused on the mirror alone: no allowlist or quota read, nothing written. - expect(kv.get.mock.calls.map((c) => c[0])).toEqual(['email-slug:proj_1']); - expect(kv.put).not.toHaveBeenCalled(); - }); - - it('is the slug that is refused, not the `from`: a wrong `from` on a reserved slug is refused too', async () => { - const kv = legacyKv('noreply'); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from: `acme@${PROD_DOMAIN}` })); - expect(res.status).toBe(403); - expect((await readSend(res)).error?.code).toBe('INVALID_FROM'); - expect(sender.calls).toHaveLength(0); - }); - - it('leaves an ordinary slug that merely CONTAINS a reserved word untouched', async () => { - const kv = createMockKv({ - 'email-slug:proj_1': 'noreply-tools', - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com']), - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from: `noreply-tools+x@${PROD_DOMAIN}` })); - expect((await readSend(res)).ok).toBe(true); - expect(sender.calls).toHaveLength(1); - }); -}); - describe('POST /email/send — MIME From pin (what the recipient sees)', () => { /** A tenant that owns `acme` and wants to look like `victim`. */ function twoTenantsKv() { @@ -1221,7 +835,7 @@ describe('POST /email/send — MIME From pin (what the recipient sees)', () => { expect(body.error?.code).toBe('INVALID_FROM'); expect(sender.calls).toHaveLength(0); // Refused before the suspension, allowlist and quota reads. - expect(kv.get.mock.calls.map((c) => c[0])).toEqual(['email-slug:proj_1']); + expect(kv.get.mock.calls.map((c) => c[0])).toEqual([]); expect(kv.put).not.toHaveBeenCalled(); }); @@ -1417,9 +1031,9 @@ describe('POST /email/send — MIME From pin (what the recipient sees)', () => { }); describe('the scan keeps nothing per line', () => { - const MAX_MIME_BYTES = 10 * 1024 * 1024; + const MAX_MIME_BYTES = 5 * 1024 * 1024; - /** `From: ` folded over as many `` continuations as fit in 10 MiB. */ + /** `From: ` folded over as many `` continuations as fit in 5 MiB. */ function foldedToTheCap(value: string, fold: string): { raw: Uint8Array; lines: number } { const head = new TextEncoder().encode(`From: ${value}\r\n`); const cont = new TextEncoder().encode(fold); @@ -1433,8 +1047,8 @@ describe('POST /email/send — MIME From pin (what the recipient sees)', () => { } it.each([ - ['CRLF', ' \r\n', 3_495_249], - ['bare LF', ' \n', 5_242_874], + ['CRLF', ' \r\n', 1_747_623], + ['bare LF', ' \n', 2_621_434], ])( 'unfolds a From spread over millions of %s continuations in bounded heap', (_label, fold, expectedLines) => { @@ -1484,7 +1098,7 @@ describe('POST /email/send — MIME From pin (what the recipient sees)', () => { expect(body.error?.code).toBe('INVALID_FROM'); expect(body.error?.message).toContain('does not match the envelope sender'); expect(sender.calls).toHaveLength(0); - expect(kv.get.mock.calls.map((c) => c[0])).toEqual(['email-slug:proj_1']); + expect(kv.get.mock.calls.map((c) => c[0])).toEqual([]); }); it.each([ @@ -1542,346 +1156,6 @@ describe('POST /email/send — MIME From pin (what the recipient sees)', () => { }); }); -describe('POST /email/send — allowlist fails closed', () => { - it.each([ - ['the key is missing entirely', undefined], - ['the value is not JSON at all', 'not json'], - ['the value is a JSON object, not an array', JSON.stringify({ dev: true })], - ['the value is a bare JSON string', JSON.stringify('dev@example.com')], - ['the value is JSON null', 'null'], - ['the value is a JSON number', '42'], - ])('denies every recipient when %s', async (_label, raw) => { - const kv = createMockKv({ - 'email-slug:proj_1': 'acme', - ...(raw === undefined ? {} : { 'email-allowlist:proj_1': raw }), - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(200); - const body = await readSend(res); - expect(body.ok).toBe(false); - expect(body.deliveries).toHaveLength(1); - expect(body.deliveries?.[0].error?.code).toBe('UNVERIFIED_DESTINATION'); - expect(sender.calls).toHaveLength(0); - // A fully-denied batch must not touch either counter. - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - }); - - it('ignores non-string entries but honors the strings beside them', async () => { - const kv = happyPathKv({ - 'email-allowlist:proj_1': JSON.stringify([42, null, 'dev@example.com']), - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - expect((await readSend(res)).ok).toBe(true); - expect(sender.recipients()).toEqual(['dev@example.com']); - }); - - it('matches allowlist entries case-insensitively', async () => { - const kv = happyPathKv({ 'email-allowlist:proj_1': JSON.stringify(['DEV@Example.COM']) }); - const res = await postSend(createMockEnv(kv), await sendBody()); - expect((await readSend(res)).ok).toBe(true); - }); - - it('sends only to the allowed recipients and reports the rest mid-batch', async () => { - const kv = happyPathKv(); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend( - env, - await sendBody({ recipients: ['dev@example.com', 'bob@example.com'] }), - ); - expect(res.status).toBe(200); - const body = await readSend(res); - expect(body.ok).toBe(false); - expect(body.deliveries).toHaveLength(2); - expect(body.deliveries?.find((d) => d.recipient === 'dev@example.com')?.ok).toBe(true); - const bob = body.deliveries?.find((d) => d.recipient === 'bob@example.com'); - expect(bob?.ok).toBe(false); - expect(bob?.error?.code).toBe('UNVERIFIED_DESTINATION'); - expect(sender.recipients()).toEqual(['dev@example.com']); - }); -}); - -describe('POST /email/send — recipient policy', () => { - const policyKv = (policy: unknown, allowlist: Array = ['dev@example.com']) => - createMockKv({ - 'email-slug:proj_1': 'acme', - 'email-allowlist:proj_1': JSON.stringify(allowlist), - 'email-recipient-policy': typeof policy === 'string' ? policy : JSON.stringify(policy), - }); - - it('still delivers to an allowlisted recipient when the policy read rejects', async () => { - const kv = policyKv({ mode: 'any', domains: [] }); - kv.get.mockImplementation(async (key: string) => { - if (key === 'email-recipient-policy') { - throw new Error('policy KV unavailable'); - } - return kv.store.get(key) ?? null; - }); - const error = vi.spyOn(console, 'error').mockImplementation(() => {}); - const sender = createSender(); - const res = await postSend( - createMockEnv(kv, { SEND_EMAIL: sender.binding }), - await sendBody({ recipients: ['dev@example.com'] }), - ); - expect((await readSend(res)).ok).toBe(true); - expect(sender.recipients()).toEqual(['dev@example.com']); - expect(error).toHaveBeenCalledWith( - '[email-policy] recipient policy read failed; enforcing verified:', - expect.any(Error), - ); - }); - - it('under `domains`, reaches a same-domain recipient the allowlist lacks and refuses others', async () => { - const kv = policyKv({ mode: 'domains', domains: ['acme.test'] }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend( - env, - await sendBody({ recipients: ['x@acme.test', 'dev@example.com', 'x@other.test'] }), - ); - const body = await readSend(res); - expect(body.ok).toBe(false); - expect(body.deliveries?.find((d) => d.recipient === 'x@acme.test')?.ok).toBe(true); - expect(body.deliveries?.find((d) => d.recipient === 'dev@example.com')?.ok).toBe(true); - const other = body.deliveries?.find((d) => d.recipient === 'x@other.test'); - expect(other?.ok).toBe(false); - expect(other?.error?.code).toBe('UNVERIFIED_DESTINATION'); - expect(other?.error?.message).toContain("platform's recipient policy"); - expect(sender.recipients().sort()).toEqual(['dev@example.com', 'x@acme.test']); - }); - - it('under `any`, sends to every recipient with an empty allowlist', async () => { - const kv = policyKv({ mode: 'any', domains: [] }, []); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ recipients: ['a@x.test', 'b@y.test'] })); - expect((await readSend(res)).ok).toBe(true); - expect(sender.recipients().sort()).toEqual(['a@x.test', 'b@y.test']); - }); - - it("does not widen `any` to another tenant's address on the platform sender domain", async () => { - const consented = `consented+tag@${PROD_DOMAIN}`; - const refused = `otherproject+tag@${PROD_DOMAIN}`; - const kv = policyKv({ mode: 'any', domains: [] }, [consented]); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend( - env, - await sendBody({ recipients: [refused, consented, 'someone@other.test'] }), - ); - const body = await readSend(res); - expect(body.deliveries?.find((delivery) => delivery.recipient === refused)).toMatchObject({ - ok: false, - error: { code: 'UNVERIFIED_DESTINATION' }, - }); - expect(sender.recipients().sort()).toEqual([consented, 'someone@other.test'].sort()); - }); - - it.each([ - ['malformed JSON', 'not json'], - ['an unknown mode', { mode: 'open', domains: [] }], - ['`domains` with an empty list', { mode: 'domains', domains: [] }], - ['a bare array', ['acme.test']], - ])('falls back to verified-only when the mirror holds %s', async (_label, policy) => { - const kv = policyKv(policy, []); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ recipients: ['x@acme.test'] })); - const body = await readSend(res); - expect(body.ok).toBe(false); - expect(body.deliveries?.[0].error?.code).toBe('UNVERIFIED_DESTINATION'); - expect(body.deliveries?.[0].error?.message).toBe( - "recipient 'x@acme.test' is not a verified destination for this project", - ); - expect(sender.calls).toHaveLength(0); - }); -}); - -describe('POST /email/send — quota', () => { - it('charges both counters by the ALLOWED recipient count and scopes the burst key', async () => { - const kv = happyPathKv({ - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com', 'ops@example.com']), - }); - const env = createMockEnv(kv); - const res = await postSend( - env, - await sendBody({ recipients: ['dev@example.com', 'ops@example.com'] }), - ); - expect((await readSend(res)).ok).toBe(true); - - expect(kv.store.get(monthKeyFor('proj_1'))).toBe('2'); - const monthPuts = putsWithPrefix(kv, 'email-sent:proj_1:'); - expect(monthPuts).toHaveLength(1); - // KV refuses an expirationTtl under 60s; the month bucket rolls on its own. - expect((monthPuts[0][2] as { expirationTtl: number }).expirationTtl).toBeGreaterThanOrEqual(60); - - const burstPuts = putsWithPrefix(kv, 'email-burst:proj_1:'); - expect(burstPuts).toHaveLength(1); - expect(burstPuts[0][1]).toBe('2'); - // Fixed 5-minute TTL on a per-minute bucket — the bucket rolls, the key - // expires, and a stale bucket can never gate a later minute. - expect(burstPuts[0][2]).toEqual({ expirationTtl: 5 * 60 }); - expect(String(burstPuts[0][0])).toMatch(/^email-burst:proj_1:\d{8}T\d{4}$/); - }); - - it('counts ONLY allowed recipients — unverified ones never burn quota', async () => { - // Monthly limit 5 with 4 already spent. One of the three recipients is - // verified, so this must fit. Counting all three would 429. - const kv = happyPathKv({ - 'email-limit:proj_1': '5', - [monthKeyFor('proj_1')]: '4', - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend( - env, - await sendBody({ - recipients: ['dev@example.com', 'bob@example.com', 'carol@example.com'], - }), - ); - expect(res.status).toBe(200); - expect(sender.recipients()).toEqual(['dev@example.com']); - expect(kv.store.get(monthKeyFor('proj_1'))).toBe('5'); - }); - - it('charges quota BEFORE the first send, not after the batch', async () => { - const kv = happyPathKv(); - const observed: Array = []; - const sender = createSender({ - onSend: () => observed.push(kv.store.get(monthKeyFor('proj_1'))), - }); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - await postSend(env, await sendBody()); - // The counter is already advanced when CF is called — a crash mid-batch - // cannot hand back free quota. - expect(observed).toEqual(['1']); - }); - - it('keeps the charge when every send fails upstream', async () => { - const kv = happyPathKv(); - const sender = createSender({ fail: () => new Error('upstream blew up') }); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - expect((await readSend(res)).ok).toBe(false); - expect(kv.store.get(monthKeyFor('proj_1'))).toBe('1'); - }); - - it('denies with 429 when the burst cap would be exceeded, advancing no counter', async () => { - const kv = happyPathKv({ - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com', 'ops@example.com']), - 'email-burst-limit:proj_1': '1', - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend( - env, - await sendBody({ recipients: ['dev@example.com', 'ops@example.com'] }), - ); - expect(res.status).toBe(429); - const body = await readSend(res); - expect(body.error?.code).toBe('QUOTA_EXCEEDED'); - expect(body.error?.message).toContain('burst'); - expect(sender.calls).toHaveLength(0); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - }); - - it('denies with 429 when the monthly cap would be exceeded, advancing no counter', async () => { - const kv = happyPathKv({ - 'email-limit:proj_1': '5', - [monthKeyFor('proj_1')]: '5', - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(429); - const body = await readSend(res); - expect(body.error?.code).toBe('QUOTA_EXCEEDED'); - expect(body.error?.message).toContain('monthly'); - expect(sender.calls).toHaveLength(0); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - }); - - it('checks the burst cap before the monthly cap', async () => { - const kv = happyPathKv({ - 'email-burst-limit:proj_1': '1', - 'email-limit:proj_1': '1', - [monthKeyFor('proj_1')]: '1', - 'email-allowlist:proj_1': JSON.stringify(['dev@example.com', 'ops@example.com']), - }); - const res = await postSend( - createMockEnv(kv), - await sendBody({ recipients: ['dev@example.com', 'ops@example.com'] }), - ); - expect((await readSend(res)).error?.message).toContain('burst'); - }); - - it('defaults to 10/min when no burst limit is configured', async () => { - const recipients = Array.from({ length: 11 }, (_, i) => `r${i}@example.com`); - const kv = happyPathKv({ 'email-allowlist:proj_1': JSON.stringify(recipients) }); - const res = await postSend(createMockEnv(kv), await sendBody({ recipients })); - expect(res.status).toBe(429); - expect((await readSend(res)).error?.message).toContain('10/min'); - }); - - it('defaults to 200/month when no monthly limit is configured', async () => { - const kv = happyPathKv({ [monthKeyFor('proj_1')]: '200' }); - const res = await postSend(createMockEnv(kv), await sendBody()); - expect(res.status).toBe(429); - expect((await readSend(res)).error?.message).toContain('200'); - }); - - it.each([ - ['a non-numeric value', 'abc'], - ['zero', '0'], - ['a negative value', '-5'], - ])('falls back to the default limits when the override is %s', async (_label, raw) => { - const kv = happyPathKv({ - 'email-burst-limit:proj_1': raw, - 'email-limit:proj_1': raw, - }); - const res = await postSend(createMockEnv(kv), await sendBody()); - // A poisoned override must not read as "limit 0" (deny everything) nor as - // NaN (allow everything) — the documented behavior is the default. - expect((await readSend(res)).ok).toBe(true); - expect(kv.store.get(monthKeyFor('proj_1'))).toBe('1'); - }); - - it.each([ - ['NaN', 'NaN'], - ['a non-numeric string', 'abc'], - ['a negative number', '-7'], - ])('reads a %s-poisoned counter as 0 instead of bypassing the gate', async (_label, raw) => { - // `parseInt('NaN', 10)` is NaN, and `NaN > limit` is false — a naive read - // would BYPASS the cap and then write the literal "NaN" back. - const kv = happyPathKv({ [monthKeyFor('proj_1')]: raw }); - const res = await postSend(createMockEnv(kv), await sendBody()); - expect(res.status).toBe(200); - expect(kv.store.get(monthKeyFor('proj_1'))).toBe('1'); - }); - - it('logs and continues when a counter put fails (documented best-effort)', async () => { - const kv = happyPathKv(); - kv.put.mockImplementation(async () => { - throw new Error('kv unavailable'); - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); - try { - const res = await postSend(env, await sendBody()); - expect((await readSend(res)).ok).toBe(true); - expect(sender.calls).toHaveLength(1); - expect(consoleError).toHaveBeenCalled(); - } finally { - consoleError.mockRestore(); - } - }); -}); - describe('POST /email/send — per-recipient fan-out', () => { it('gives every recipient its own message with a FRESH body stream', async () => { // A regression that hoisted `bytesToStream(raw)` out of the loop would @@ -1901,9 +1175,9 @@ describe('POST /email/send — per-recipient fan-out', () => { // One envelope sender for the whole batch; one message per recipient. expect(new Set(sender.calls.map((c) => c.from)).size).toBe(1); expect(body.ids).toEqual([ - { recipient: 'a@example.com', messageId: 'cf-msg-1' }, - { recipient: 'b@example.com', messageId: 'cf-msg-2' }, - { recipient: 'c@example.com', messageId: 'cf-msg-3' }, + { recipient: 'a@example.com', messageId: 'cf-msg-1', state: 'provider_accepted' }, + { recipient: 'b@example.com', messageId: 'cf-msg-2', state: 'provider_accepted' }, + { recipient: 'c@example.com', messageId: 'cf-msg-3', state: 'provider_accepted' }, ]); }); @@ -1913,7 +1187,9 @@ describe('POST /email/send — per-recipient fan-out', () => { const res = await postSend(env, await sendBody()); const body = await readSend(res); expect(body.ok).toBe(true); - expect(body.ids).toEqual([{ recipient: 'dev@example.com', messageId: '' }]); + expect(body.ids).toEqual([ + { recipient: 'dev@example.com', messageId: '', state: 'provider_accepted' }, + ]); }); it('records per-recipient outcomes when one send fails mid-batch', async () => { @@ -1933,240 +1209,12 @@ describe('POST /email/send — per-recipient fan-out', () => { expect(body.deliveries?.find((d) => d.recipient === 'carol@example.com')?.ok).toBe(true); const bob = body.deliveries?.find((d) => d.recipient === 'bob@example.com'); expect(bob?.ok).toBe(false); - expect(bob?.error?.code).toBe('UPSTREAM_ERROR'); + expect(bob?.error?.code).toBe('OUTCOME_UNKNOWN'); // One failure does not abort the batch. expect(sender.calls).toHaveLength(3); }); }); -describe('POST /email/send — upstream error classification', () => { - async function sendWithError(message: string): Promise { - const sender = createSender({ fail: () => new Error(message) }); - const env = createMockEnv(happyPathKv(), { SEND_EMAIL: sender.binding }); - return readSend(await postSend(env, await sendBody())); - } - - it.each([ - ['destination address dev@example.com is not verified'], - ['destination address dev@example.com is not yet verified'], - ['Destination Address dev@example.com Not Verified'], - ])('classifies %s as UNVERIFIED_DESTINATION (non-retryable)', async (message) => { - const body = await sendWithError(message); - expect(body.deliveries?.[0].error?.code).toBe('UNVERIFIED_DESTINATION'); - }); - - it.each([ - [ - 'transient MX error mentioning an unrelated RDNS check', - 'could not deliver to destination MX; reason: domain not yet RDNS-verified', - ], - [ - 'a preamble longer than the leading bound', - `${'x'.repeat(300)} destination address dev@example.com is not verified`, - ], - [ - 'reverse phrasing — verified domain, different destination', - 'sender domain verified; destination address differs from configured allow list', - ], - ['a transient SMTP DSN', '4.7.1 temporary delivery failure; please retry later'], - [ - 'a match dragged in from a later log line', - 'connection reset\ndestination address dev@example.com is not verified', - ], - ])('does NOT classify %s as UNVERIFIED_DESTINATION', async (_label, message) => { - // A false positive here turns a retryable transient failure into a - // permanent "go verify your address" for the developer. - const body = await sendWithError(message); - expect(body.deliveries?.[0].error?.code).toBe('UPSTREAM_ERROR'); - }); - - // Email Service throws a plain `Error` with a string `code` (Cloudflare's - // `E_*` table). These messages deliberately do NOT match the - // destination-verification regex, so a pass can only come from the code. - function bindingError(code: string, message: string): Error { - return Object.assign(new Error(message), { code }); - } - - async function sendWithThrow(thrown: unknown): Promise { - const send = vi.fn(async () => { - throw thrown; - }); - const env = createMockEnv(happyPathKv(), { SEND_EMAIL: { send } }); - return readSend(await postSend(env, await sendBody())); - } - - it.each([ - ['E_RECIPIENT_NOT_ALLOWED', 'UNVERIFIED_DESTINATION'], - ['E_RATE_LIMIT_EXCEEDED', 'QUOTA_EXCEEDED'], - ['E_DAILY_LIMIT_EXCEEDED', 'QUOTA_EXCEEDED'], - ])('classifies a binding throw carrying %s as %s', async (code, expected) => { - const body = await sendWithThrow(bindingError(code, 'Email Service refused the send')); - expect(body.deliveries?.[0].error?.code).toBe(expected); - expect(body.deliveries?.[0].error?.message).toBe('Email Service refused the send'); - }); - - it.each(['E_SENDER_NOT_VERIFIED', 'E_SENDER_DOMAIN_NOT_AVAILABLE'])( - 'keeps %s as UPSTREAM_ERROR (the pinned platform sender is not the tenant to fix) and logs it', - async (code) => { - const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); - try { - const body = await sendWithThrow(bindingError(code, 'Sender domain not verified')); - expect(body.deliveries?.[0].error?.code).toBe('UPSTREAM_ERROR'); - expect(body.deliveries?.[0].error?.message).toBe('Sender domain not verified'); - expect(consoleError).toHaveBeenCalledTimes(1); - const line = String(consoleError.mock.calls[0]?.[0]); - expect(line).toContain(code); - expect(line).toContain('proj_1'); - } finally { - consoleError.mockRestore(); - } - }, - ); - - it('falls back to the message regex when the code is not one it knows', async () => { - const body = await sendWithThrow( - bindingError('E_SOMETHING_NEW', 'destination address dev@example.com is not verified'), - ); - expect(body.deliveries?.[0].error?.code).toBe('UNVERIFIED_DESTINATION'); - }); - - it('classifies a non-Error throw as UPSTREAM_ERROR', async () => { - const body = await sendWithThrow('boom'); - expect(body.deliveries?.[0].ok).toBe(false); - expect(body.deliveries?.[0].error?.code).toBe('UPSTREAM_ERROR'); - expect(body.deliveries?.[0].error?.message).toBe('boom'); - }); -}); - -// --------------------------------------------------------------------------- -// Gate ORDER. Each gate has its own negative test above; these pin the -// SEQUENCE — size -> from -> suspend -> allowlist -> quota. A reordering that -// let an unverified recipient burn quota (or an oversized body reach the -// allowlist read) passes every per-gate test and only fails here. -// --------------------------------------------------------------------------- -describe('POST /email/send — gate order', () => { - /** Was `key` ever read from KV during this request? */ - function readKey(kv: MockKv, key: string): boolean { - return kv.get.mock.calls.some((call) => call[0] === key); - } - - /** KV where every downstream gate would ALSO refuse. */ - function everyGateTrippedKv() { - return createMockKv({ - 'email-slug:proj_1': 'acme', - acme: JSON.stringify({ projectId: 'proj_1', suspended: 'abuse' }), - 'email-suspended:proj_1': '1', - 'email-allowlist:proj_1': JSON.stringify([]), - 'email-burst-limit:proj_1': '1', - 'email-limit:proj_1': '1', - [monthKeyFor('proj_1')]: '99', - }); - } - - it('missing sender configuration short-circuits before any KV work', async () => { - const kv = everyGateTrippedKv(); - const env = createMockEnv(kv, { EMAIL_SENDER_DOMAIN: undefined }); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(502); - expect(kv.get).not.toHaveBeenCalled(); - expect(kv.put).not.toHaveBeenCalled(); - }); - - it('an oversized body is refused before the slug, suspend and allowlist reads', async () => { - const MAX_MIME_BYTES = 10 * 1024 * 1024; - const overBound = Math.ceil((MAX_MIME_BYTES * 4) / 3) + 5; - const kv = everyGateTrippedKv(); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend( - env, - // Deliberately not valid base64 — the pre-decode length guard runs - // before atob(), so an adversary can't force a ~75 MB allocation. - await sendBody({ mimeBase64: 'A'.repeat(overBound) }), - ); - expect(res.status).toBe(413); - expect((await readSend(res)).error?.code).toBe('MIME_ERROR'); - expect(kv.get).not.toHaveBeenCalled(); - expect(kv.put).not.toHaveBeenCalled(); - expect(sender.calls).toHaveLength(0); - }); - - it('a bad `from` is refused before the suspend, allowlist and quota reads', async () => { - const kv = everyGateTrippedKv(); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody({ from: `spoof@${PROD_DOMAIN}` })); - - expect((await readSend(res)).error?.code).toBe('INVALID_FROM'); - expect(readKey(kv, 'email-slug:proj_1'), 'the slug mirror must be read first').toBe(true); - expect(readKey(kv, 'acme')).toBe(false); - expect(readKey(kv, 'email-suspended:proj_1')).toBe(false); - expect(readKey(kv, 'email-allowlist:proj_1')).toBe(false); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - expect(sender.calls).toHaveLength(0); - }); - - it('platform suspension is answered before the allowlist and quota reads', async () => { - const kv = everyGateTrippedKv(); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - - const body = await readSend(res); - expect(body.error?.code).toBe('QUOTA_EXCEEDED'); - expect(body.error?.message).toContain('abuse'); - expect(readKey(kv, 'email-allowlist:proj_1')).toBe(false); - expect(readKey(kv, 'email-burst-limit:proj_1')).toBe(false); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - expect(sender.calls).toHaveLength(0); - }); - - it('the email kill-switch is answered before the allowlist and quota reads', async () => { - const kv = createMockKv({ - 'email-slug:proj_1': 'acme', - 'email-suspended:proj_1': '1', - 'email-allowlist:proj_1': JSON.stringify([]), - 'email-limit:proj_1': '1', - [monthKeyFor('proj_1')]: '99', - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - - const body = await readSend(res); - expect(body.error?.code).toBe('QUOTA_EXCEEDED'); - expect(body.error?.message).toContain('suspended'); - expect(readKey(kv, 'email-allowlist:proj_1')).toBe(false); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - expect(sender.calls).toHaveLength(0); - }); - - it('unverified recipients are answered BEFORE the quota gates and burn nothing', async () => { - // The regression this guards: moving the quota gates ahead of the - // allowlist would let anyone charge a project's monthly cap by naming - // recipients it never verified — and would answer 429 instead of the - // actionable UNVERIFIED_DESTINATION. - const kv = createMockKv({ - 'email-slug:proj_1': 'acme', - 'email-allowlist:proj_1': JSON.stringify([]), - 'email-limit:proj_1': '1', - [monthKeyFor('proj_1')]: '99', - }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const res = await postSend(env, await sendBody()); - - expect(res.status).toBe(200); - const body = await readSend(res); - expect(body.error).toBeUndefined(); - expect(body.deliveries?.[0].error?.code).toBe('UNVERIFIED_DESTINATION'); - expect(readKey(kv, 'email-burst-limit:proj_1')).toBe(false); - expect(readKey(kv, 'email-limit:proj_1')).toBe(false); - expect(putsWithPrefix(kv, 'email-')).toHaveLength(0); - expect(sender.calls).toHaveLength(0); - }); -}); - describe('POST /email/send — sender domain is configuration, never a baked-in default', () => { it.each([ ['unset', undefined], diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2e1045783..735310fd0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -435,7 +435,7 @@ importers: version: 0.3.1(@types/node@26.5.1)(esbuild@0.27.7)(jiti@2.7.0)(sass@1.101.0)(svelte@5.57.0)(terser@5.51.2)(tsx@4.23.0)(typescript@7.0.2)(yaml@2.9.0) wrangler: specifier: 'catalog:' - version: 4.131.0(@cloudflare/workers-types@4.20260702.1)(@types/node@26.5.1) + version: 4.131.0(@cloudflare/workers-types@5.20260910.1)(@types/node@26.5.1) packages/react: dependencies: @@ -875,8 +875,36 @@ importers: specifier: catalog:platform version: 4.130.0(@cloudflare/workers-types@5.20260910.1) + platform/packages/email-gateway: + dependencies: + '@void/platform': + specifier: workspace:* + version: link:../../../packages/platform + '@voidcloud/api': + specifier: workspace:* + version: link:../api + '@voidcloud/proxy': + specifier: workspace:* + version: link:../proxy + devDependencies: + '@cloudflare/workers-types': + specifier: catalog:platform + version: 5.20260910.1 + typescript: + specifier: 'catalog:' + version: 7.0.2 + vite-plus: + specifier: 'catalog:' + version: 0.3.1(@types/node@26.5.1)(esbuild@0.27.7)(jiti@2.7.0)(sass@1.101.0)(svelte@5.57.0)(terser@5.51.2)(tsx@4.23.0)(typescript@7.0.2)(yaml@2.9.0) + wrangler: + specifier: catalog:platform + version: 4.131.0(@cloudflare/workers-types@5.20260910.1)(@types/node@26.5.1) + platform/packages/proxy: dependencies: + '@void/platform': + specifier: workspace:* + version: link:../../../packages/platform '@voidcloud/api': specifier: workspace:* version: link:../api @@ -21654,6 +21682,24 @@ snapshots: - bufferutil - utf-8-validate + wrangler@4.131.0(@cloudflare/workers-types@5.20260910.1)(@types/node@26.5.1): + dependencies: + '@cloudflare/kv-asset-handler': 0.5.0 + '@cloudflare/unenv-preset': 2.16.1(unenv@2.0.0-rc.24)(workerd@1.20260910.1) + blake3-wasm: 2.1.5 + esbuild: 0.27.7 + miniflare: 5.20260910.0-alpha(@types/node@26.5.1) + path-to-regexp: 6.3.0 + unenv: 2.0.0-rc.24 + workerd: 1.20260910.1 + optionalDependencies: + '@cloudflare/workers-types': 5.20260910.1 + fsevents: 2.3.3 + transitivePeerDependencies: + - '@types/node' + - bufferutil + - utf-8-validate + wrap-ansi@10.0.0: dependencies: ansi-styles: 6.2.3 From 4f147f09d31fdd86d8ecca9b9afa25acfc41a8e6 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sat, 19 Sep 2026 01:29:55 +0800 Subject: [PATCH 2/6] fix(email): address design alignment and cleanup reviews --- docs/guide/email.md | 76 +- docs/reference/cli.md | 12 +- packages/platform/src/email-protocol.ts | 11 +- .../platform/test/unit/email-protocol.test.ts | 41 + packages/void/src/cli/cf-oauth.ts | 321 ---- packages/void/src/cli/client.ts | 180 +- packages/void/src/cli/email-args.ts | 29 +- packages/void/src/cli/email.ts | 395 ++--- packages/void/src/cli/help.ts | 17 +- packages/void/src/router/compile.ts | 47 +- packages/void/src/runtime/email/inbound.ts | 160 +- packages/void/test/unit/cf-oauth.test.ts | 377 ---- packages/void/test/unit/cli-help.test.ts | 7 +- .../void/test/unit/email-cli-disallow.test.ts | 12 - .../void/test/unit/email-cli-domain.test.ts | 534 +++--- .../void/test/unit/email-cli-logs.test.ts | 93 +- .../void/test/unit/email-domain-args.test.ts | 34 +- packages/void/test/unit/email-inbound.test.ts | 61 +- .../void/test/unit/email-own-account.test.ts | 9 +- .../meta/design-docs/0078-email-cf-native.md | 12 +- platform/meta/operations.md | 6 + .../packages/api/src/admin/routes/email.tsx | 209 ++- platform/packages/api/src/auth/identities.ts | 1 - platform/packages/api/src/auth/profile.ts | 145 +- platform/packages/api/src/db.ts | 54 +- platform/packages/api/src/email/admission.ts | 16 +- .../packages/api/src/email/cf-customer.ts | 150 +- .../api/src/email/cf-domain-probes.ts | 49 + .../api/src/email/connection-service.ts | 344 +++- .../api/src/email/credential-lease.ts | 311 ---- .../packages/api/src/email/domain-service.ts | 157 +- platform/packages/api/src/email/domains.ts | 277 --- platform/packages/api/src/email/limits.ts | 30 +- .../packages/api/src/email/relay-engine.ts | 996 ----------- .../packages/api/src/email/relay-worker.ts | 3 - platform/packages/api/src/index.ts | 42 - .../packages/api/src/operator/email-routes.ts | 39 +- .../packages/api/src/provisioning/cleanup.ts | 197 +-- .../api/src/provisioning/email-allowlist.ts | 153 -- platform/packages/api/src/reserved-slugs.ts | 9 +- platform/packages/api/src/routes/auth.ts | 9 +- platform/packages/api/src/routes/delete.ts | 13 +- platform/packages/api/src/routes/deploy.ts | 3 +- .../packages/api/src/routes/email-confirm.ts | 2 - platform/packages/api/src/routes/email.ts | 54 +- platform/packages/api/src/routes/projects.ts | 17 +- platform/packages/api/src/schema.ts | 34 +- .../api/test/integration/admin-email.test.ts | 286 +-- .../api/test/integration/api-delete.test.ts | 724 +------- .../integration/api-email-domains.test.ts | 75 +- .../api/test/integration/api-email.test.ts | 453 +---- .../api/test/integration/api-projects.test.ts | 30 - .../auth-email-verification.test.ts | 220 +-- .../test/integration/email-admission.test.ts | 97 + .../integration/email-connections.test.ts | 292 +++ .../test/integration/email-domain-cf-stub.ts | 72 +- .../api/test/integration/scheduled.test.ts | 89 - .../api/test/unit/email-cf-customer.test.ts | 156 +- .../api/test/unit/email-domains.test.ts | 225 --- .../api/test/unit/email-relay-engine.test.ts | 1559 ----------------- platform/packages/email-gateway/src/index.ts | 14 +- .../email-gateway/test/unit/gateway.test.ts | 27 + platform/packages/proxy/src/email-lease.ts | 55 +- platform/packages/proxy/src/email-policy.ts | 140 -- platform/packages/proxy/src/email-relay.ts | 282 --- platform/packages/proxy/src/email-router.ts | 1320 ++------------ platform/packages/proxy/src/email.ts | 291 +-- .../test/unit/email-custom-domain.test.ts | 18 - .../proxy/test/unit/email-policy.test.ts | 159 -- .../proxy/test/unit/email-relay.test.ts | 42 - .../proxy/test/unit/email-router.test.ts | 1453 ++------------- 71 files changed, 2175 insertions(+), 11652 deletions(-) delete mode 100644 packages/void/src/cli/cf-oauth.ts delete mode 100644 packages/void/test/unit/cf-oauth.test.ts create mode 100644 platform/packages/api/src/email/cf-domain-probes.ts delete mode 100644 platform/packages/api/src/email/credential-lease.ts delete mode 100644 platform/packages/api/src/email/domains.ts delete mode 100644 platform/packages/api/src/email/relay-engine.ts delete mode 100644 platform/packages/api/src/provisioning/email-allowlist.ts delete mode 100644 platform/packages/api/test/unit/email-domains.test.ts delete mode 100644 platform/packages/api/test/unit/email-relay-engine.test.ts delete mode 100644 platform/packages/proxy/src/email-policy.ts delete mode 100644 platform/packages/proxy/src/email-relay.ts delete mode 100644 platform/packages/proxy/test/unit/email-policy.test.ts delete mode 100644 platform/packages/proxy/test/unit/email-relay.test.ts diff --git a/docs/guide/email.md b/docs/guide/email.md index 3d78361b4..f60ae7ee1 100644 --- a/docs/guide/email.md +++ b/docs/guide/email.md @@ -19,7 +19,7 @@ const result = await sendEmail({ if (!result.ok) { if ('error' in result) { - // Nothing was sent — the whole call failed before delivery. + // A request-level failure; OUTCOME_UNKNOWN may already have been submitted. console.error(result.error.code, result.error.message); } else { // Some recipients failed. `deliveries` says which. @@ -91,6 +91,12 @@ Setup returns an operation ID. If your connection drops, the platform keeps the Use `void email domain sync ` to reconcile setup and refresh readiness. Sync does not rotate the connection secret. Use `void email domain rotate-secret ` for an explicit rotation; it applies to all domains sharing that zone connection and verifies the deployed secret before completing. If a dashboard or credential step is required, the status names it. Removing a domain disables its assignment; zone resources used by another domain remain in place, and unfinished cleanup stays recorded for reconciliation. +After the last assignment's ingress is deleted, the platform forgets its stored +credential. Revoke a token you no longer use in Cloudflare; Void does not revoke +tokens you created yourself. Re-adding a removed domain requires a scoped token +again. A domain can move to another project only after its removal completes +and the zone connection's manager authorizes the new assignment. + Once inbound is ready, mail to any address on that domain reaches your `email/` handlers. Sending to arbitrary recipients also needs outbound readiness; a domain limited to verified destinations still requires recipient verification. Platform quotas and suspension apply to both shared and custom senders. On an administrator-managed platform, `add` prints the administrator command for new domains. Existing owner-managed connections remain available to their owner. Your administrator may permit shared-sender mail to specific recipient domains or any recipient; destinations on the platform's shared mail domain still require explicit verification. @@ -354,51 +360,49 @@ export default defineEmail(async (message, env, ctx, info) => { Everything taken from the inbound message is best-effort, because the remote sender controls it. A `Message-ID` or `References` value too long for a header line is dropped rather than threaded, and a `References` chain over 8 KiB keeps only its newest ids — the parent's `Message-ID` always ends it. Control characters in the subject become a space, and a subject over 4096 characters, or an ASCII one too long to fold, falls back to a bare `Re:`. None of these fallbacks suppresses the reply; pass `subject` to control it exactly. -On the platform the `from` default is **not** `message.to`. A reply is sent from -your project's own slug on the platform mail zone — `+noreply@` — -built from the `__VOID_PROJECT_SLUG` and `__VOID_EMAIL_DOMAIN` bindings the -platform injects. `replyEmail` throws when the slug is set but the domain is -absent and you omitted `from`, rather than guessing a sender. With no slug at -all — a worker on your own Cloudflare account — the reply is sent from -`message.to`, the address on your own zone the message was delivered to. +On the platform, shared-domain replies default to +`+noreply@`. For mail received at a registered custom domain, +replies default to the address that received the message. `replyEmail` throws +when it cannot determine a sender. Native Cloudflare replies default to `message.to`. ::: warning The platform pins the reply sender -You may override `from`, but only with an address on your own slug. The proxy -accepts a reply sender whose local-part before the first `+` equals the slug the -message was delivered to, on the zone it arrived on. Anything else is **dropped -silently** — `replyEmail` still resolves, and the only trace is in the platform's -log stream, not your project's. - -This is what stops one project replying as another project's address. Note that -`message.to` is the _stripped_ address (`@`), so `from: message.to` -is exactly the shape the pin rejects. +You may override `from` with your project's shared address or an address on +a registered custom domain your project owns. An unauthorized sender is rejected +and recorded in `void email logs`. + +For shared addressing, `message.to` has the project prefix removed. Use the +default sender instead of copying that stripped address into `from`. ::: ::: warning The platform gates the reply recipient -A reply's `to` goes through the same gate as `sendEmail()` and `forward()`: it -must be one of your project's verified destinations — -`void email allow
`, then the recipient's verification click. A reply -to any other address is **dropped silently**: the inbound message is still -accepted, `replyEmail` still resolves, nothing reaches your worker, and the -only trace is in the platform's log stream, not your project's. - -So the ticket example above answers only senders you have allowlisted. An -auto-responder to arbitrary senders needs -[your own Cloudflare account](#your-own-cloudflare-account) -(`--platform cloudflare`), where `reply()` is Cloudflare's own reply-to-sender -and Void adds no allowlist — or a platform whose administrator has widened the -recipient policy for the whole installation (see -[On a platform your administrator runs](#your-own-domain-on-the-platform)), -which lifts this gate for the listed domains; addresses on the platform's own -mail domain always stay verified-recipient-only. +A reply's `to` goes through the platform's recipient policy and the transport's +capability checks. Shared sending defaults to your project's verified +destinations: run `void email allow
` and have the recipient complete +verification. A blocked reply is recorded in `void email logs`; the inbound +message remains accepted. + +Custom-domain sends may reach external recipients when Cloudflare Sending is +enabled. Addresses on the platform's own mail domain always require per-project +consent. Native forwarding and reply operations can have additional Cloudflare +restrictions; check the recorded outcome before assuming a reply was accepted. ::: -Note the asymmetry with `sendEmail`: `sendEmail` returns an error result and -never throws, while `replyEmail` throws when it cannot determine a sender. +In a platform handler, awaiting `replyEmail` or `message.forward` records an +action for execution after the handler finishes. Use `void email logs` to see +its provider outcome. `sendEmail` returns its send result directly. + +`message.forward` requires a native Cloudflare email event. A message relayed +from a customer zone cannot use native forwarding; its forward action is +recorded as `UNSUPPORTED_ACTION` without sending or consuming quota. Replies +remain available through that domain's sending capability. ### Configuring inbound delivery -In production, inbound runs on one shared mail facility. The platform routes `+anything@` to your worker's `email()` export — **there is nothing to configure in the Cloudflare dashboard and no per-project DNS work**. Your handlers are live as soon as the deploy lands. A [registered custom domain](#your-own-domain-on-the-platform) lands on the same facility: once `void email domain add` reports it `active`, mail to any address on the domain reaches your `email/` handlers, with nothing further to configure. +On an email-enabled platform, `+anything@` reaches your +deployed `email/` handlers without per-project DNS setup. A +[registered custom domain](#your-own-domain-on-the-platform) reaches those +handlers once its inbound readiness is `ready`. Use `void email domain status` +to check current provider routing and any remaining setup steps. On your own Cloudflare account there is no shared facility: the deploy derives one Email Routing rule per handler and writes it into `wrangler.jsonc` for you — see [Your own Cloudflare account](#your-own-cloudflare-account). diff --git a/docs/reference/cli.md b/docs/reference/cli.md index d55c38f7c..c1f1f6953 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -620,7 +620,7 @@ void platform email limit [--monthly ] [--burst ] `policy` decides which recipients a project's `+tag@` sender reaches: `verified` (the default) means only that project's verified destinations; `domains` adds every address on the listed domains; `any` lifts the check. Neither widens delivery to addresses on the platform's own mail domain: those stay verified-destination-only, so no project reaches another project's inbox without its consent. Cloudflare still refuses a destination it has not verified until the platform mail domain is onboarded for Email Sending, so under `domains` or `any` such refusals arrive as per-recipient `UNVERIFIED_DESTINATION` results. Custom-domain sends are not affected. -`settings-set --domains admin` tells `void email domain add` to print the administrator's command instead of starting a Cloudflare grant. `limit` overrides the project's monthly and per-minute caps (defaults 200 and 10); a project page in the admin UI shows and clears them. When both caps are given and only one could be written, the result names the applied and failed cap and exits nonzero. +`settings-set --domains admin` tells `void email domain add` to print the administrator's command instead of starting token setup. `limit` overrides the project's monthly and rolling 60-second caps (defaults 200 and 10); a project page in the admin UI shows and clears them. Register and maintain email domains for projects whose owners hold no Cloudflare credential: @@ -629,10 +629,10 @@ void platform email domains [--project ] void platform email domain-add --project [--token-stdin] void platform email domain-status void platform email domain-sync -void platform email domain-remove [--force] +void platform email domain-remove ``` -`domain-add` runs the same setup as `void email domain add` on the platform's own Cloudflare credential, so the zone must be in the platform's account; for a zone elsewhere, pipe a Cloudflare API token for that account on standard input with `--token-stdin --yes`. Name the exact mail domain (`mail.example.com`, or the apex when it receives no mail yet). Enabling Email Routing on a subdomain stays a one-time Cloudflare dashboard step, which `domain-status` reports and self-clears once the MX records appear; after a Workers Paid upgrade, `domain-sync` re-attempts the Email Sending onboarding. A setup or sync that ends with the domain `failed` or its credential revoked or expired is reported as a partial failure and exits nonzero; the result names the failing step, and running `domain-add` again retries it. Rows an administrator adds show `managed_by: admin`; their owners can list and inspect them but are pointed at these commands for `sync` and `remove`. +`domain-add` uses the platform's Cloudflare credential for zones in its account. For another account, pipe a scoped Cloudflare API token on standard input with `--token-stdin --yes`. Name the exact mail domain (`mail.example.com`, or the apex when it receives no mail yet). `domain-status` shows inbound, outbound, and credential-management readiness with the latest operation. A blocked or uncertain operation exits unsuccessfully and can be inspected by its operation ID; use `domain-sync` to reconcile the connection. Domains an administrator adds show `managed_by: admin`; their owners can list and inspect them but use these commands for `sync` and `remove`. #### System {#operator-system} @@ -1478,12 +1478,12 @@ The project owner's email is added automatically when the project is created, so void email disallow
[--project ] ``` -Remove one recipient from the project's destination list. Sends to that address are refused for new sends immediately; previously admitted attempts may finish: the platform updates the project's allowlist as part of the command, and the proxy re-reads it every 60 seconds. No deploy is involved. +Remove one recipient from the project's destination list. New sends to that address are refused immediately; previously admitted attempts may finish. No deploy is involved. ### `void email domain` ``` -void email domain [] [--project ] +void email domain [] [--project ] ``` Send and receive at your own domain on a Cloudflare zone you own, registered to the project. Void platform only — on your own Cloudflare account the mail domain comes from `email.from` instead (see `void email setup`). The walkthrough is [Your own domain on the platform](../guide/email.md#your-own-domain-on-the-platform). @@ -1510,7 +1510,7 @@ Show the recorded inbound, outbound, and management readiness, observation times void email domain list [--project ] ``` -List the project's registered email domains with their status and mode. +List the project's registered email domains and readiness. #### `void email domain sync` diff --git a/packages/platform/src/email-protocol.ts b/packages/platform/src/email-protocol.ts index a7650da61..4e345ad8c 100644 --- a/packages/platform/src/email-protocol.ts +++ b/packages/platform/src/email-protocol.ts @@ -150,6 +150,7 @@ export async function readEmailEnvelope( const value = metadata as Record; const raw = bytes.subarray(4 + metadataLength, total); if ( + raw.byteLength > EMAIL_MAX_INBOUND_BYTES || typeof value.from !== 'string' || value.from.length > 320 || typeof value.to !== 'string' || @@ -206,18 +207,18 @@ async function receiptKey(secret: string, usage: 'sign' | 'verify'): Promise { const payload = encoder.encode(JSON.stringify(claims)); const signature = new Uint8Array( - await crypto.subtle.sign('HMAC', await receiptKey(projectToken, 'sign'), payload), + await crypto.subtle.sign('HMAC', await receiptKey(signingSecret, 'sign'), payload), ); return `${base64url(payload)}.${base64url(signature)}`; } export async function verifyEmailReceipt( token: string, - projectToken: string, + signingSecret: string, expected: Pick, now: number = Date.now(), ): Promise { @@ -237,7 +238,7 @@ export async function verifyEmailReceipt( if ( !(await crypto.subtle.verify( 'HMAC', - await receiptKey(projectToken, 'verify'), + await receiptKey(signingSecret, 'verify'), Uint8Array.from(signature), Uint8Array.from(payload), )) @@ -316,7 +317,7 @@ export function encodeEmailActions( pending = frame(2, action.raw); } total += 5 + metadata.byteLength + (pending?.byteLength ?? 0); - if (total > EMAIL_MAX_RESPONSE_BYTES) { + if (total + 5 > EMAIL_MAX_RESPONSE_BYTES) { throw new Error('email actions too large'); } controller.enqueue(frame(1, metadata)); diff --git a/packages/platform/test/unit/email-protocol.test.ts b/packages/platform/test/unit/email-protocol.test.ts index 1b0a018ff..ae8aef6ca 100644 --- a/packages/platform/test/unit/email-protocol.test.ts +++ b/packages/platform/test/unit/email-protocol.test.ts @@ -1,5 +1,7 @@ import { describe, expect, it } from 'vite-plus/test'; import { + EMAIL_MAX_INBOUND_BYTES, + EMAIL_MAX_RESPONSE_BYTES, encodeEmailActions, readEmailEnvelope, readEmailActions, @@ -82,6 +84,45 @@ describe('bounded email receipt protocol', () => { ).rejects.toThrow('invalid email action frame'); }); + it('enforces the MIME limit independently of unused metadata capacity', async () => { + const metadata = new TextEncoder().encode( + JSON.stringify({ + from: 'sender@example.com', + to: 'recipient@example.com', + headers: {}, + rawSize: EMAIL_MAX_INBOUND_BYTES + 1, + }), + ); + const bytes = new Uint8Array(4 + metadata.byteLength + EMAIL_MAX_INBOUND_BYTES + 1); + new DataView(bytes.buffer).setUint32(0, metadata.byteLength); + bytes.set(metadata, 4); + await expect( + readEmailEnvelope( + new ReadableStream({ + start(controller) { + controller.enqueue(bytes); + controller.close(); + }, + }), + ), + ).rejects.toThrow('invalid email envelope'); + }); + + it('includes the terminal frame in the aggregate action limit', async () => { + const address = { from: 'a@b', to: 'c@d' }; + const metadataBytes = new TextEncoder().encode( + JSON.stringify({ type: 'reply', ...address }), + ).byteLength; + const first = new Uint8Array(5 * 1024 * 1024); + const secondSize = EMAIL_MAX_RESPONSE_BYTES - 5 - 2 * (10 + metadataBytes) - first.byteLength; + const action = (raw: Uint8Array) => ({ type: 'reply' as const, ...address, raw }); + const fitting = [action(first), action(new Uint8Array(secondSize))]; + expect(await readEmailActions(encodeEmailActions(fitting))).toHaveLength(2); + await expect( + readEmailActions(encodeEmailActions([action(first), action(new Uint8Array(secondSize + 1))])), + ).rejects.toThrow('email actions too large'); + }); + it('rejects an oversized tenant response before retaining its chunk', async () => { const oversized = new Uint8Array(8 * 1024 * 1024 + 1); await expect( diff --git a/packages/void/src/cli/cf-oauth.ts b/packages/void/src/cli/cf-oauth.ts deleted file mode 100644 index c572ec4fb..000000000 --- a/packages/void/src/cli/cf-oauth.ts +++ /dev/null @@ -1,321 +0,0 @@ -/** - * The Cloudflare OAuth grant on wrangler's public PKCE client (design doc - * 0078, "The OAuth grant on wrangler's client"; task contract 8) — the - * primary credential grant for `void email domain add`. The customer clicks - * Allow on Cloudflare's hosted consent page, the loopback server below - * receives the code, exchanges it at the token endpoint, and returns the - * grant's refresh token. - * - * The refresh token is held in memory only: the command POSTs it to the - * platform as its first use and drops it. It is never written to disk, the - * keychain, a log line, or an error message. - * - * The client id is wrangler's own public client (no secret), which - * Cloudflare can rotate or revoke any day — so the template-link + paste - * path in `email.ts` is the permanent fallback, not a legacy branch. The - * consent page is Cloudflare's and names Wrangler; it cannot say Void, so - * the warning line is printed here before the browser opens. - */ - -import { randomBytes } from 'node:crypto'; -import { log } from '@clack/prompts'; -import { createCodeChallenge, createCodeVerifier, openBrowser } from './auth.ts'; - -/** wrangler's public PKCE OAuth client id (no secret). Not ours — see the header. */ -export const CF_OAUTH_CLIENT_ID = '54d11594-84e4-41aa-b438-e81b8fa78ee7'; -export const CF_OAUTH_AUTHORIZE_URL = 'https://dash.cloudflare.com/oauth2/auth'; -export const CF_OAUTH_TOKEN_URL = 'https://dash.cloudflare.com/oauth2/token'; -export const CF_OAUTH_REVOKE_URL = 'https://dash.cloudflare.com/oauth2/revoke'; -/** - * The redirect registered on wrangler's client. Fixed port and path: the - * consent flow redirects here and only here, so the loopback server binds - * exactly :8976 and answers exactly /oauth/callback — unlike the platform - * login's random-port /callback in auth.ts, which cannot serve this flow. - */ -export const CF_OAUTH_CALLBACK_PORT = 8976; -export const CF_OAUTH_CALLBACK_PATH = '/oauth/callback'; -export const CF_OAUTH_REDIRECT_URI: string = `http://localhost:${CF_OAUTH_CALLBACK_PORT}${CF_OAUTH_CALLBACK_PATH}`; -/** The scopes the email-domain setup needs; `offline_access` is what yields the refresh token. */ -export const CF_OAUTH_SCOPE = - 'zone:read email_routing:write email_sending:write workers_scripts:write offline_access'; - -export type CfOauthGrant = Readonly<{ - /** The grant's refresh token. Never logged, never persisted locally. */ - refreshToken: string; -}>; - -/** - * Revoke a grant at Cloudflare — RFC 7009 on wrangler's public client, the - * same form wrangler's `logout` posts (a public client authenticates with - * the token itself; no Authorization header). Never throws, never logs the - * token; the boolean is whether Cloudflare CONFIRMED the revocation (200 — - * CF answers 200 even for a bogus token), so `false` means the grant's - * state is unknown and it may still be live: callers that print an outcome - * must not claim a revocation they cannot prove. For when the CLI holds a - * grant it will not hand to the platform: a consent exchange that - * completed after the flow settled (fire-and-forget there — the flow is - * settled), or an add request that provably never persisted one. - */ -export async function revokeCfOauthGrant(refreshToken: string): Promise { - try { - const res = await fetch(CF_OAUTH_REVOKE_URL, { - method: 'POST', - headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, - body: new URLSearchParams({ - token: refreshToken, - token_type_hint: 'refresh_token', - client_id: CF_OAUTH_CLIENT_ID, - }).toString(), - }); - return res.ok; - } catch { - // The grant's state at Cloudflare is unknown either way. - return false; - } -} - -/** The consent URL the browser opens — PKCE S256, state-bound to the loopback server. */ -export function buildCfOauthAuthorizeUrl(params: { state: string; codeChallenge: string }): string { - const url = new URL(CF_OAUTH_AUTHORIZE_URL); - url.searchParams.set('response_type', 'code'); - url.searchParams.set('client_id', CF_OAUTH_CLIENT_ID); - url.searchParams.set('redirect_uri', CF_OAUTH_REDIRECT_URI); - url.searchParams.set('scope', CF_OAUTH_SCOPE); - url.searchParams.set('state', params.state); - url.searchParams.set('code_challenge', params.codeChallenge); - url.searchParams.set('code_challenge_method', 'S256'); - return url.href; -} - -/** - * Exchange the authorization code at Cloudflare's token endpoint. The - * response body is never logged and never copied into an error — it carries - * token material on success, so failure messages name only the HTTP status. - */ -async function exchangeCfOauthCode(code: string, codeVerifier: string): Promise { - const res = await fetch(CF_OAUTH_TOKEN_URL, { - method: 'POST', - headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, - body: new URLSearchParams({ - grant_type: 'authorization_code', - code, - redirect_uri: CF_OAUTH_REDIRECT_URI, - client_id: CF_OAUTH_CLIENT_ID, - code_verifier: codeVerifier, - }).toString(), - }); - if (!res.ok) { - throw new Error(`cf-oauth: Cloudflare's token exchange failed (HTTP ${res.status}).`); - } - let body: unknown; - try { - body = await res.json(); - } catch { - throw new Error("cf-oauth: Cloudflare's token exchange returned an invalid response."); - } - const refreshToken = - body && typeof body === 'object' && 'refresh_token' in body ? body.refresh_token : undefined; - if (typeof refreshToken !== 'string' || refreshToken.length === 0) { - // `offline_access` is on the scope string, so a grant without a refresh - // token is a Cloudflare-side surprise worth naming — the refresh token is - // the one thing the platform stores. - throw new Error("cf-oauth: Cloudflare's answer carried no refresh token."); - } - return { refreshToken }; -} - -/** Same minimal callback page the platform login renders (auth.ts keeps its own copy). */ -function page(title: string, message: string): string { - return ` - -${title} - Void - -

${title}

${message}

`; -} - -/** - * Run the grant: bind the loopback server on :8976, warn about the - * Wrangler-named consent page, open the browser, and resolve with the - * refresh token once the code has been exchanged INSIDE the request handler - * (so the browser only sees the success page after the exchange succeeded). - * - * Rejects on a busy port, a denied consent, a failed exchange, an abort - * (`signal` — the command aborts when Enter switches to the token path), or - * the timeout; the caller falls back to the template-link path on any of - * them. `onUrl` fires with the authorize URL once the server is listening, - * so the command can show it as the manual fallback when the browser fails - * to open. The server is always closed before settling. - */ -export async function runCfOauthGrant(options: { - onUrl?: (url: string) => void; - /** Default 5 minutes. */ - timeoutMs?: number; - signal?: AbortSignal; - /** Injectable for tests; defaults to the real `node:child_process` `execFile`. */ - execFile?: typeof import('node:child_process').execFile; -}): Promise { - const http = await import('node:http'); - const { onUrl, signal } = options; - const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000; - const execFile = options.execFile ?? (await import('node:child_process')).execFile; - - if (signal?.aborted) { - throw new Error('cf-oauth: cancelled.'); - } - - return new Promise((resolve, reject) => { - let settled = false; - - const state = randomBytes(32).toString('hex'); - const codeVerifier = createCodeVerifier(); - const codeChallenge = createCodeChallenge(codeVerifier); - - const onAbort = (): void => fail(new Error('cf-oauth: cancelled.')); - - const fail = (error: Error): void => { - if (settled) { - return; - } - settled = true; - server.close(); - signal?.removeEventListener('abort', onAbort); - reject(error); - }; - - const succeed = (grant: CfOauthGrant): void => { - if (settled) { - return; - } - settled = true; - server.close(); - signal?.removeEventListener('abort', onAbort); - resolve(grant); - }; - - // server.close() stops new connections but leaves the in-flight callback - // socket open — both settled branches below still answer the tab. - const cancelled = (res: import('node:http').ServerResponse): void => { - res.writeHead(200, { 'Content-Type': 'text/html' }); - res.end( - page( - 'Authorization cancelled', - 'This sign-in was cancelled in the terminal. You can close this tab.', - ), - ); - }; - - const server = http.createServer(async (req, res) => { - // This is a one-shot browser callback, so never leave a keep-alive - // connection behind after answering it. `server.close()` stops new - // connections, but an HTTP client may otherwise reuse an existing - // socket and send a later grant's callback to this server after its - // listener has closed. - res.setHeader('Connection', 'close'); - const url = new URL(req.url!, 'http://localhost'); - if (url.pathname !== CF_OAUTH_CALLBACK_PATH) { - res.writeHead(404); - res.end('Not found'); - return; - } - - if (url.searchParams.get('state') !== state) { - res.writeHead(400, { 'Content-Type': 'text/html' }); - res.end(page('Authorization failed', 'Invalid callback. Please try again.')); - return; - } - - // The customer clicked deny, or Cloudflare refused the request itself. - const cfError = url.searchParams.get('error'); - if (cfError) { - const message = - cfError === 'access_denied' - ? 'The Cloudflare consent was denied.' - : `Cloudflare returned an error (${cfError}).`; - res.writeHead(403, { 'Content-Type': 'text/html' }); - res.end(page('Authorization failed', message)); - fail(new Error(`cf-oauth: ${message}`)); - return; - } - - // Reject-but-keep-listening: a stray request without a code (favicon - // aside, everything off-path 404s above) must not settle the flow — the - // genuine callback can still arrive. - const code = url.searchParams.get('code'); - if (!code) { - res.writeHead(400, { 'Content-Type': 'text/html' }); - res.end(page('Authorization failed', 'No authorization code received. Please try again.')); - return; - } - - // Exchange INSIDE the request path so the browser only sees the success - // page once the token exchange succeeded — the same rule the platform - // login keeps. Guard against the timeout racing the in-flight exchange. - let grant: CfOauthGrant; - try { - grant = await exchangeCfOauthCode(code, codeVerifier); - } catch (err) { - if (settled) { - cancelled(res); - return; - } - res.writeHead(400, { 'Content-Type': 'text/html' }); - res.end( - page( - 'Authorization failed', - 'Could not complete the Cloudflare grant. Please try again.', - ), - ); - fail( - err instanceof Error ? err : new Error("cf-oauth: Cloudflare's token exchange failed."), - ); - return; - } - - if (settled) { - // The flow settled (Enter, abort, or the timeout) while the - // exchange was in flight — but Cloudflare still minted the grant, - // and the CLI is the only actor holding it. Revoke rather than - // strand a live user-wide grant with no handle. Fire-and-forget: - // the flow is settled, so this must never throw or stall anything. - void revokeCfOauthGrant(grant.refreshToken); - cancelled(res); - return; - } - res.writeHead(200, { 'Content-Type': 'text/html' }); - res.end(page('Cloudflare connected', 'You can close this tab and return to the terminal.')); - succeed(grant); - }); - - // Close immediately after the callback — don't wait for keep-alive timeout. - server.on('connection', (socket) => socket.unref()); - - server.on('error', (err) => { - // EADDRINUSE: another login (or wrangler's own) holds :8976. The caller - // falls back to the template-link path on any failure here. - const code = (err as NodeJS.ErrnoException).code; - fail( - new Error( - `cf-oauth: could not start the local callback server on port ${CF_OAUTH_CALLBACK_PORT}${code ? ` (${code})` : ''}.`, - ), - ); - }); - - signal?.addEventListener('abort', onAbort, { once: true }); - - server.listen(CF_OAUTH_CALLBACK_PORT, '127.0.0.1', () => { - // The consent page is Cloudflare's hosted page for the wrangler client - // and cannot say Void — say it here, before the browser opens (0078). - log.warn( - "Opening Cloudflare's consent page — it names Wrangler; that is expected (Void borrows wrangler's OAuth client for this one-click grant).", - ); - const authorizeUrl = buildCfOauthAuthorizeUrl({ state, codeChallenge }); - onUrl?.(authorizeUrl); - openBrowser(authorizeUrl, execFile); - }); - - const timeout = setTimeout(() => { - fail(new Error('cf-oauth: the consent timed out.')); - }, timeoutMs); - timeout.unref(); - }); -} diff --git a/packages/void/src/cli/client.ts b/packages/void/src/cli/client.ts index 1c85b181c..db7b60cd9 100644 --- a/packages/void/src/cli/client.ts +++ b/packages/void/src/cli/client.ts @@ -237,20 +237,17 @@ export type EmailLogEntry = { timestamp: number; direction: 'sent' | 'received'; operationId: string; - receiptId?: string | null; - actionId?: string; - recipient?: string | null; + receiptId: string | null; + recipient: string | null; status: string; - transport?: string; - providerReference?: string | null; - errorCode?: string | null; - policyVersion?: number | null; + transport: string; + providerReference: string | null; + errorCode: string | null; + policyVersion: number | null; }; export type EmailLogsResponse = { logs: Array; - pending?: boolean; - note?: string; }; export type EmailDestinationResponse = { @@ -285,58 +282,22 @@ export type EmailSettingsResponse = { recipientPolicy?: { mode: 'verified' | 'domains' | 'any'; domains: Array }; }; -/** - * The public shape of an `email_domains` row (design doc 0078, contract 1) — - * metadata only. The api's serializer never carries the credential, the - * relay secret, or any ciphertext, so this type can never accidentally - * contain one. - */ export type EmailDomainResponse = { id: string; domain: string; - mode: 'apex' | 'subdomain' | null; - status: - | 'pending' - | 'ready' - | 'disabled' - | 'drifted' - | 'active' - | 'token_revoked' - | 'token_expired' - | 'failed'; - /** `platform` rows run on the platform's own credential — an administrator's row. */ - credential_kind: 'oauth_grant' | 'api_token' | 'platform'; - /** Who registered the row; owners may read an `admin` row but not sync or remove it. */ - managed_by?: 'owner' | 'admin'; - relay_worker_name: string | null; + projectId: string; + managed_by: 'owner' | 'admin'; + status: EmailReadiness['inbound']['status']; + connectionId: string; + account_id: string; + zone_id: string; + relay_worker_name: string; relay_version: number | null; - /** Metadata from GET /user/tokens/verify (api_token rows) — safe to print. */ - token_id: string | null; - token_expires_on: string | null; - /** - * The add attempt that last wrote the credential (null when an older CLI - * wrote it). Optional: apis predating attempt identity omit the key - * entirely, and `in`-operator detection on the raw row is how the add - * reconcile tells that apart from a stamped null. - */ + operationId: string | null; + operationStatus?: EmailOperationResponse['status'] | null; attemptId?: string | null; - operationId?: string; - operationStatus?: EmailOperationResponse['status']; - readiness?: EmailReadiness; - setup_state: { - /** Orchestration step that left the row 'failed'. */ - failed_step?: string; - /** Steps still owed by the human (the routing-subdomain dashboard form). */ - remaining_steps?: Array; - } | null; - /** - * Present on add/sync outcomes that failed a step. The api guarantees the - * text names the failing step or CF error — never credential material — so - * the CLI prints it verbatim. - */ - error?: string; - created_at: string; - updated_at: string; + readiness: EmailReadiness; + error?: string | null; }; export type EmailReadiness = { @@ -367,48 +328,15 @@ export type EmailOperationResponse = { error?: string; }; -/** The zone catch-all outcome of a sync — absent when the row has no zone_id. */ -export type EmailDomainSyncCatchAll = - | 'ensured' - | 'already_set' - | 'foreign_conflict' - | 'probe_failed'; - -/** POST .../email/domains/:domain/sync adds the catch-all outcome at the top level. */ -export type EmailDomainSyncResponse = EmailDomainResponse & { - catch_all?: EmailDomainSyncCatchAll; -}; - -/** GET /email/domains/:domain adds a live credential probe and the relay-drift read. */ -export type EmailDomainStatusResponse = EmailDomainResponse & { - credential_status: 'active' | 'expired' | 'revoked' | 'probe_failed'; - current_relay_version: number; - relay_drift: boolean; - relay_missing: boolean | null; - /** Live read of the zone's catch-all rule relative to this domain's relay. */ - catch_all: 'points_here' | 'points_elsewhere' | 'missing' | 'disabled' | 'unknown'; - /** true when the zone's catch-all no longer points at this relay — `domain sync` re-points it. */ - catch_all_drift: boolean; -}; - -/** A Cloudflare-side cleanup step the email-domain delete orchestration can fail. */ -export type RemoveEmailDomainFailedStep = 'catch_all' | 'delete_relay' | 'revoke_grant'; +export type EmailDomainStatusResponse = EmailDomainResponse; +export type EmailDomainSyncResponse = EmailDomainResponse; export type RemoveEmailDomainResponse = { - operationId?: string; + operationId: string; operationStatus?: EmailOperationResponse['status']; - error?: string; + error?: string | null; ok: boolean; - /** - * false = the row was KEPT for retry: a Cloudflare-side step failed and - * the remove was not forced, so the credential stays for the retry. - * true = the platform row, the stored credential and the relay secret - * are gone. - */ removed: boolean; - /** true when `?force=1` dropped the row despite Cloudflare-side failures. */ - forced?: true; - failed_steps?: Array; }; export type DomainResponse = { @@ -1720,13 +1648,7 @@ export class PlatformClient { return res.json(); } - /** - * Installation email settings the CLI reads before acting. A platform - * predating the route answers a bare 404, which reads as the defaults — - * owners register their own domains there. The route's own 404 (the - * project is gone) is a real error: acting on it would open a browser and - * mint a grant for nothing. - */ + /** Installation email settings the CLI reads before starting a credential flow. */ async getEmailSettings(projectId: string): Promise { const res = await this.request(`${this.baseUrl}/projects/${projectId}/email/settings`, { headers: { @@ -1734,13 +1656,6 @@ export class PlatformClient { }, }); - if (res.status === 404) { - const body = await res.text(); - if (parsePlatformErrorBody(body)?.error === 'project not found') { - throw new PlatformApiError('Failed to read email settings', res.status, body); - } - return { domains: { management: 'self-serve' } }; - } if (!res.ok) { await throwPlatformApiError('Failed to read email settings', res); } @@ -1762,13 +1677,7 @@ export class PlatformClient { return res.json(); } - /** - * `domain add` sends the credential exactly once — the OAuth grant's - * refresh token xor a pasted API token (the api enforces exactly one). It - * is the only call that ever carries it: the platform stores it encrypted - * per project, and every later step (`status`, `sync`, `remove`) addresses - * the row by domain. The caller must not log the input. - */ + /** Submit a scoped token once; later operations address the domain without it. */ async addEmailDomain( projectId: string, input: { domain: string; apiToken?: string; attemptId?: string }, @@ -1810,11 +1719,19 @@ export class PlatformClient { return res.json(); } - /** Reconciles the shared zone connection without rotating its secret. */ - async rotateEmailDomainSecret(projectId: string, domain: string): Promise { + /** Rotates the shared zone connection secret. */ + async rotateEmailDomainSecret( + projectId: string, + domain: string, + attemptId: string, + ): Promise { const res = await this.request( `${this.baseUrl}/projects/${projectId}/email/domains/${encodeURIComponent(domain)}/rotate-secret`, - { method: 'POST', headers: { ...this.authHeaders } }, + { + method: 'POST', + headers: { 'Content-Type': 'application/json', ...this.authHeaders }, + body: JSON.stringify({ attemptId }), + }, ); if (!res.ok) { await throwPlatformApiError('Failed to rotate email connection secret', res); @@ -1840,29 +1757,16 @@ export class PlatformClient { return res.json(); } - /** - * `force` appends `?force=1`: the api drops the row even when a - * Cloudflare-side cleanup step fails (and answers `forced: true` + - * `failed_steps`). Without it a CF-side failure keeps the row for retry - * (`removed: false`). - */ - async removeEmailDomain( - projectId: string, - domain: string, - force?: boolean, - ): Promise { - const url = new URL( + async removeEmailDomain(projectId: string, domain: string): Promise { + const res = await this.request( `${this.baseUrl}/projects/${projectId}/email/domains/${encodeURIComponent(domain)}`, - ); - if (force) { - url.searchParams.set('force', '1'); - } - const res = await this.request(url, { - method: 'DELETE', - headers: { - ...this.authHeaders, + { + method: 'DELETE', + headers: { + ...this.authHeaders, + }, }, - }); + ); if (!res.ok) { await throwPlatformApiError('Failed to remove email domain', res); diff --git a/packages/void/src/cli/email-args.ts b/packages/void/src/cli/email-args.ts index fe7a8ae7a..2329bf248 100644 --- a/packages/void/src/cli/email-args.ts +++ b/packages/void/src/cli/email-args.ts @@ -65,12 +65,6 @@ export interface EmailArgs { * "[change with --subdomain]"). */ subdomain?: string; - /** - * `--force` on `domain remove`: drop the platform row even when a - * Cloudflare-side cleanup step fails (the api answers `forced: true` and - * names the failed steps for manual cleanup). - */ - force?: boolean; projectSlug?: string; limit?: number; address?: string; @@ -122,7 +116,6 @@ export function parseEmailArgs(args: Array): EmailArgs { const platformValues: Array = []; const backendValues: Array = []; const subdomainValues: Array = []; - let forceCount = 0; const positional: Array = []; const rest = args.slice(1); @@ -175,23 +168,11 @@ export function parseEmailArgs(args: Array): EmailArgs { } subdomainValues.push(value); i = next; - } else if (rest[i] === '--force' || rest[i]?.startsWith('--force=')) { - // A boolean: `--force=yes` is a positional's worth of confusion, not a value. - if (rest[i] !== '--force') { - throw new Error('email: --force takes no value.'); - } - forceCount++; } else { positional.push(rest[i]); } } - // Same repeated-flag rule as --project/--subdomain. - if (forceCount > 1) { - throw new Error('email: --force can only be specified once.'); - } - const force = forceCount > 0 ? true : undefined; - // Same rule as `void deploy`: `--project` at most once. if (projectValues.length > 1) { throw new Error('email: --project can only be specified once.'); @@ -241,14 +222,11 @@ export function parseEmailArgs(args: Array): EmailArgs { 'email: --platform cloudflare applies to `void email status` and `void email setup` only (`domain` is a Void platform command).', ); } - return parseEmailDomainArgs(positional, { projectSlug, limit, platform, subdomain, force }); + return parseEmailDomainArgs(positional, { projectSlug, limit, platform, subdomain }); } if (subdomain !== undefined) { throw new Error('email: --subdomain applies to `void email domain add` only.'); } - if (force !== undefined) { - throw new Error('email: --force applies to `void email domain remove` only.'); - } // `void email allow|disallow` takes exactly one address. Silently // dropping extras (the previous behavior, which kept only the first) @@ -306,7 +284,6 @@ function parseEmailDomainArgs( limit?: number; platform?: EmailArgs['platform']; subdomain?: string; - force?: boolean; }, ): EmailArgs { const verb = positional[0]; @@ -318,9 +295,6 @@ function parseEmailDomainArgs( if (flags.subdomain !== undefined && verb !== 'add') { throw new Error('email: --subdomain applies to `void email domain add` only.'); } - if (flags.force !== undefined && verb !== 'remove') { - throw new Error('email: --force applies to `void email domain remove` only.'); - } const domain = positional[1]; if (verb === 'list') { if (domain !== undefined) { @@ -342,7 +316,6 @@ function parseEmailDomainArgs( domainVerb: verb as EmailDomainVerb, domain, subdomain: flags.subdomain, - force: flags.force, projectSlug: flags.projectSlug, limit: flags.limit, platform: flags.platform, diff --git a/packages/void/src/cli/email.ts b/packages/void/src/cli/email.ts index 0079704bc..c6fc72a9a 100644 --- a/packages/void/src/cli/email.ts +++ b/packages/void/src/cli/email.ts @@ -5,12 +5,7 @@ import { readConfig } from '../config.ts'; import { readProjectPaths } from '../project-paths.ts'; import { scanEmailHandlersSync } from '../router/email.ts'; import { getToken, openBrowser } from './auth.ts'; -import { - PlatformApiError, - PlatformClient, - type EmailDomainResponse, - type EmailDomainStatusResponse, -} from './client.ts'; +import { PlatformApiError, PlatformClient, type EmailDomainResponse } from './client.ts'; import { createDeployWranglerRunner, deriveWorkerName, @@ -133,10 +128,6 @@ async function emailDestinations(client: PlatformClient, projectId: string): Pro note(lines.join('\n'), 'Email Destinations'); } -/** - * `void email allow
` — exported for the unit test; the command - * entry (`runEmailCommand`) resolves the client and project first. - */ export async function emailAllow( client: Pick, projectId: string, @@ -175,16 +166,6 @@ function freshLinkHint(address: string): string { return `For a fresh link, remove the address from every project that lists it (\`void email disallow ${address}\`), then \`void email allow ${address}\` — Cloudflare mails a new link only when it registers the address anew.`; } -/** - * `void email disallow
` — exported for the unit test; the command - * entry (`runEmailCommand`) resolves the client and project first. - * - * No deploy is involved: the api tightens the proxy's `email-allowlist` - * KV mirror inside the DELETE (and answers 503 if that write fails), and - * the proxy re-reads the mirror with a 60s `cacheTtl` on both the send - * path and inbound forward/reply — so the address is refused once that - * per-colo cache turns over. - */ export async function emailDisallow( client: Pick, projectId: string, @@ -202,28 +183,12 @@ export async function emailDisallow( ); } -/** - * `void email logs` — exported for the unit test; the command entry - * (`runEmailCommand`) resolves the client and project first. - */ export async function emailLogs( client: Pick, projectId: string, limit?: number, ): Promise { const result = await client.getEmailLogs(projectId, limit); - if (result.pending) { - log.info(result.note ?? 'Persistent log storage is not yet wired up.'); - // The proxy's own send/receive records are the platform worker's console - // output, which a project's credentials cannot read — so nothing points - // at them. The one thing a user CAN read today is their own worker's - // console output: the email handler is invoked over RPC on the same - // tailed script as every HTTP request, so it lands in `void project logs`. - log.info( - 'Email activity logs are not available yet. Console output from your email handler appears in `void project logs`.', - ); - return; - } if (result.logs.length === 0) { log.info('No email activity recorded.'); return; @@ -517,18 +482,6 @@ type EmailDomainCredential = { kind: 'api_token'; apiToken: string }; const ADD_RECONCILE_ATTEMPTS = 15; const ADD_RECONCILE_INTERVAL_MS = 1000; -/** - * `void email domain add ` — exported for the unit test; the command - * entry resolves the client and project first. - * - * The flow: render the MX decision → scoped API token → - * the template-link + clipboard fallback (Enter switches to the masked paste - * at any point) → POST the credential once → render the resulting row. A - * failed add leaves the platform row 'failed' and re-running add replaces - * the credential — the api's replace path, not anything here. On an - * administrator-managed platform, only a row the owner registered before - * the switch continues into that renewal flow. - */ export async function emailDomainAdd( client: Pick< PlatformClient, @@ -636,7 +589,7 @@ export async function emailDomainAdd( // A renewal keeps its stored target: Email Routing itself put MX on the // apex it serves, so the MX decision would retarget it. if (renewal !== undefined) { - log.info(`Renewing ${renewal} — the stored credential is replaced; rules and the relay stay.`); + log.info(`Updating ${renewal} with a scoped credential; the platform will reconcile setup.`); } else { await decideTarget(); } @@ -845,231 +798,80 @@ export async function emailDomainAdd( 'Token stored encrypted on the platform for this zone connection — nothing is kept on this machine.', ); printEmailDomainOutcome(row); - if ( - row.status === 'failed' || - row.status === 'token_revoked' || - row.status === 'token_expired' || - row.operationStatus === 'blocked' || - row.operationStatus === 'unknown' - ) { + if (row.operationStatus === 'blocked' || row.operationStatus === 'unknown') { return exit(1); } } -/** An administrator's row runs on the platform's own credential; the owner never held one. */ -function emailCredentialLabel(row: Pick) { - const kind = - row.credential_kind === 'oauth_grant' - ? 'OAuth grant' - : row.credential_kind === 'platform' - ? 'platform credential' - : 'API token'; - return row.managed_by === 'admin' ? `${kind} · managed by the administrator` : kind; -} - function emailDomainStatusText(status: EmailDomainResponse['status']): string { - if (status === 'active' || status === 'ready') { - return pc.green('active'); + if (status === 'ready') { + return pc.green('ready'); } if (status === 'pending') { return pc.yellow('pending'); } - return pc.red(status === 'failed' ? 'failed' : status.replace('_', ' ')); + return status === 'disabled' ? pc.yellow('disabled') : pc.red(status); } -/** - * The dashboard path for the one remaining human step. The row does not - * carry the zone name, so a subdomain row strips its first label — the zone - * the walk almost always lands on (`mail.acme.com` → `acme.com`). - */ -function routingSubdomainInstruction(domain: string, mode: EmailDomainResponse['mode']): string { - const zoneGuess = mode === 'subdomain' ? domain.split('.').slice(1).join('.') : domain; - return `add ${domain} in the Cloudflare dashboard — Email Routing → ${zoneGuess} → Settings → Subdomains`; -} - -/** - * The shared result render for add and sync: the row as a block, then the - * one guidance line the status calls for. `error` is printed verbatim — the - * api guarantees it names a step or a CF error, never credential material. - */ -function printEmailDomainOutcome(row: EmailDomainResponse): void { - if (row.readiness) { - const lines = [ - `Domain: ${row.domain}`, - ...Object.entries(row.readiness).map( - ([name, value]) => - `${name.padEnd(12)} ${value.status}${value.reason ? ' — ' + value.reason : ''}${value.observedAt ? ' (' + value.observedAt + ')' : ''}`, - ), - ]; - if (row.operationId) { - lines.push( - `Operation: ${row.operationId}${row.operationStatus ? ' · ' + row.operationStatus : ''}`, - ); - } - note(lines.join('\n'), 'Email Domain'); - if (row.error) { - log.error(row.error); - } - if (row.readiness.inbound.status !== 'ready') { - log.info(`Run void email domain sync ${row.domain} to reconcile setup.`); - } - return; - } - if (row.status === 'failed') { - const step = row.setup_state?.failed_step; - log.error( - `email: ${row.domain} failed${step ? ` at ${step.replaceAll('_', ' ')}` : ''}${row.error ? ` — ${row.error}` : ''}`, - ); - log.info( - `Fix the step above, then re-run \`void email domain add ${row.domain}\` — adding again replaces the credential and retries.`, - ); - return; - } - +function printEmailDomainOutcome(row: EmailDomainResponse, projectRef?: string): void { const lines = [ `Domain: ${row.domain}`, - `Status: ${emailDomainStatusText(row.status)}`, - `Mode: ${row.mode ?? '—'}`, - `Credential: ${emailCredentialLabel(row)}`, + `Managed by: ${row.managed_by === 'admin' ? 'administrator' : 'project owner'}`, + ...Object.entries(row.readiness).map( + ([name, value]) => + `${name.padEnd(12)} ${value.status}${value.reason ? ' — ' + value.reason : ''}${value.observedAt ? ' (' + value.observedAt + ')' : ''}`, + ), ]; - if (row.relay_worker_name) { + if (row.operationId) { lines.push( - `Relay: ${row.relay_worker_name}${row.relay_version !== null ? ` v${row.relay_version}` : ''}`, + `Operation: ${row.operationId}${row.operationStatus ? ' · ' + row.operationStatus : ''}`, ); } - if (row.token_expires_on) { - lines.push(`Token TTL: expires ${row.token_expires_on}`); - } note(lines.join('\n'), 'Email Domain'); - - const remaining = row.setup_state?.remaining_steps ?? []; - if (row.status === 'pending' && remaining.includes('routing_subdomain')) { - log.warn(`One step only you can do: ${routingSubdomainInstruction(row.domain, row.mode)}.`); - log.info(`Then run \`void email domain status ${row.domain}\` to poll.`); - return; - } - if (row.status === 'pending') { - log.info(`Run \`void email domain status ${row.domain}\` to poll.`); - return; + if (row.error) { + log.error(row.error); } - if (row.status === 'token_revoked' || row.status === 'token_expired') { + if (row.operationStatus === 'unknown') { log.warn( - `The stored credential was ${row.status === 'token_revoked' ? 'revoked at Cloudflare' : 'left to expire'} — re-run \`void email domain add ${row.domain}\` with a fresh API token. Rules and the relay stay.`, + `Operation ${row.operationId} has an unknown outcome; inspect its status before retrying.`, ); return; } - if (remaining.includes('sending_onboarding')) { + if ( + row.readiness.management.status === 'expired' || + row.readiness.management.status === 'revoked' + ) { log.info( - `Inbound is live. Sending to arbitrary recipients needs Workers Paid — until then sendEmail() works to verified destinations only. After upgrading, run \`void email domain sync ${row.domain}\` to finish onboarding.`, + row.managed_by === 'admin' + ? `Ask your administrator to run \`void platform email domain-add ${row.domain} --project ${projectRef ?? row.projectId}\` with a renewed credential.` + : `Run \`void email domain add ${row.domain}\` with a new scoped API token.`, + ); + } else if ( + row.readiness.inbound.status === 'pending' || + row.readiness.inbound.status === 'drifted' + ) { + log.info( + row.managed_by === 'admin' + ? `Ask your administrator to run \`void platform email domain-sync ${row.domain}\` to reconcile setup.` + : `Run \`void email domain sync ${row.domain}\` to reconcile setup.`, ); } - log.success( - `${row.domain} is live — send with \`sendEmail({ from: 'you@${row.domain}', … })\`; inbound mail to any address on ${row.domain} reaches your email/ handlers.`, - ); } -/** - * `void email domain status ` — exported for the unit test. Re-probes - * the credential and the relay on every call (the api does it), so this is - * also the drift report: it never fights the customer's edits, it names them. - */ export async function emailDomainStatus( client: Pick, projectId: string, rawDomain: string, ): Promise { const domain = normalizeEmailDomainInput(rawDomain); - const row: EmailDomainStatusResponse = await client.getEmailDomain(projectId, domain); - if (row.readiness) { - printEmailDomainOutcome(row); - return; - } - const adminRow = row.managed_by === 'admin'; - - const lines = [ - `Domain: ${row.domain}`, - `Status: ${emailDomainStatusText(row.status)}`, - `Mode: ${row.mode ?? '—'}`, - ]; - const credential = - row.credential_status === 'probe_failed' - ? `${emailCredentialLabel(row)} · probe failed (stored view shown)` - : `${emailCredentialLabel(row)} · ${row.credential_status}`; - lines.push(`Credential: ${credential}`); - if (row.token_id) { - lines.push( - `Token: id ${row.token_id}${row.token_expires_on ? ` · expires ${row.token_expires_on}` : ''}`, - ); - } - if (row.relay_worker_name) { - let relay = `Relay: ${row.relay_worker_name}${row.relay_version !== null ? ` v${row.relay_version}` : ''}`; - if (row.relay_missing === true) { - relay += ' · missing from the account'; - } else if (row.relay_drift) { - relay += ` · drifted (current is v${row.current_relay_version})`; - } - lines.push(relay); - } - if (row.setup_state?.failed_step) { - lines.push(`Failed step: ${row.setup_state.failed_step.replaceAll('_', ' ')}`); - } - lines.push(`Catch-all: ${row.catch_all}`); - note(lines.join('\n'), 'Email Domain'); - - if (row.error) { - log.error(`email: ${row.error}`); - } - const failedAdminRow = adminRow && row.status === 'failed'; - if (failedAdminRow) { - const slug = (await client.getEmailSettings(projectId)).domains.projectSlug ?? projectId; - log.warn( - `Ask your administrator to re-run the setup: \`void platform email domain-add ${row.domain} --project ${slug}${row.credential_kind === 'api_token' ? ' --token-stdin' : ''}\` — adding again retries the failed step; rules stay.`, - ); - } - const remaining = row.setup_state?.remaining_steps ?? []; - if (remaining.includes('routing_subdomain')) { - log.warn( - adminRow - ? `One step for your administrator, in the platform's Cloudflare account: ${routingSubdomainInstruction(row.domain, row.mode)}.` - : `One step only you can do: ${routingSubdomainInstruction(row.domain, row.mode)}.`, - ); - } - if (remaining.includes('sending_onboarding')) { - log.info( - adminRow - ? `Sending to arbitrary recipients needs Workers Paid on the platform's Cloudflare account — inbound works; sendEmail() to verified destinations only. After the upgrade, ask your administrator to run \`void platform email domain-sync ${row.domain}\`.` - : `Sending to arbitrary recipients needs Workers Paid — inbound works; sendEmail() to verified destinations only. After upgrading, run \`void email domain sync ${row.domain}\`.`, - ); - } - if (!failedAdminRow && (row.relay_missing === true || row.relay_drift)) { - log.info( - adminRow - ? `Ask your administrator to run \`void platform email domain-sync ${row.domain}\` to redeploy the relay in place.` - : `Run \`void email domain sync ${row.domain}\` to redeploy the relay in place.`, - ); - } - if (!failedAdminRow && row.catch_all_drift) { - log.info( - adminRow - ? `Catch-all drifted — ask your administrator to run \`void platform email domain-sync ${row.domain}\` to re-point it.` - : `Catch-all drifted — run \`void email domain sync ${row.domain}\` to re-point it.`, - ); - } - if (row.status === 'token_revoked' || row.status === 'token_expired') { - if (adminRow) { - const slug = (await client.getEmailSettings(projectId)).domains.projectSlug ?? projectId; - log.warn( - `Ask your administrator to re-add it: \`void platform email domain-add ${row.domain} --project ${slug} --token-stdin\` — adding again replaces the credential, rules stay.`, - ); - } else { - log.warn( - `Re-run \`void email domain add ${row.domain}\` with a fresh scoped API token — adding again replaces the credential, rules stay.`, - ); - } - } + const row = await client.getEmailDomain(projectId, domain); + const projectRef = + row.managed_by === 'admin' + ? ((await client.getEmailSettings(projectId)).domains.projectSlug ?? projectId) + : undefined; + printEmailDomainOutcome(row, projectRef); } -/** `void email domain list` — exported for the unit test. */ export async function emailDomainList( client: Pick, projectId: string, @@ -1084,12 +886,11 @@ export async function emailDomainList( const width = Math.max(...rows.map((row) => row.domain.length)); const lines = rows.map( (row) => - ` ${row.domain.padEnd(width)} ${emailDomainStatusText(row.status)} ${row.mode ?? '—'}`, + ` ${row.domain.padEnd(width)} ${emailDomainStatusText(row.status)} ${row.managed_by === 'admin' ? 'administrator' : 'project owner'}`, ); note(lines.join('\n'), 'Email Domains'); } -/** `void email domain sync ` — exported for the unit test. */ export async function emailDomainSync( client: Pick, projectId: string, @@ -1097,32 +898,64 @@ export async function emailDomainSync( ): Promise { const domain = normalizeEmailDomainInput(rawDomain); const row = await client.syncEmailDomain(projectId, domain); - if (row.catch_all === 'foreign_conflict') { - log.warn( - "Catch-all: the zone's catch-all points at a different worker and was not overwritten.", - ); - } else if (row.catch_all) { - log.info(`Catch-all: ${row.catch_all.replaceAll('_', ' ')}`); - } printEmailDomainOutcome(row); - if ( - row.status === 'failed' || - row.operationStatus === 'blocked' || - row.operationStatus === 'unknown' - ) { + if (row.operationStatus !== 'completed') { throw new Error( - `email: reconciliation ${row.operationStatus ?? row.status}; inspect operation ${row.operationId ?? row.domain}`, + `email: reconciliation ${row.operationStatus ?? 'pending'}; inspect operation ${row.operationId ?? row.domain}`, ); } } /** Rotation applies to every domain sharing this zone connection. */ export async function emailDomainRotateSecret( - client: Pick, + client: Pick, projectId: string, rawDomain: string, + deps: { sleep?: (ms: number) => Promise } = {}, ): Promise { - const row = await client.rotateEmailDomainSecret(projectId, normalizeEmailDomainInput(rawDomain)); + const domain = normalizeEmailDomainInput(rawDomain); + const attemptId = crypto.randomUUID(); + let row: EmailDomainResponse; + try { + row = await client.rotateEmailDomainSecret(projectId, domain, attemptId); + } catch (error) { + if (error instanceof PlatformApiError && [400, 403, 404, 409].includes(error.status)) { + throw error; + } + const sleep = + deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms))); + for (let attempt = 0; attempt < ADD_RECONCILE_ATTEMPTS; attempt++) { + if (attempt > 0) { + await sleep(ADD_RECONCILE_INTERVAL_MS); + } + let operation; + try { + operation = await client.getEmailOperation(projectId, attemptId); + } catch { + continue; + } + note( + [ + `Operation: ${operation.operationId}`, + `Status: ${operation.status}`, + `Inbound: ${operation.readiness.inbound.status}`, + `Outbound: ${operation.readiness.outbound.status}`, + `Credential: ${operation.readiness.management.status}`, + ].join('\n'), + 'Email Secret Rotation', + ); + if (operation.status !== 'completed') { + throw new Error( + `email: secret rotation ${operation.status}; inspect operation ${operation.operationId}`, + ); + } + log.success('Zone ingress secret rotated and verified on the deployed Worker.'); + return; + } + throw new Error( + `email: secret rotation outcome is unknown (operation key ${attemptId}); inspect \`void email domain status ${domain}\` before starting another rotation.`, + ); + } printEmailDomainOutcome(row); if (row.operationStatus !== 'completed') { throw new Error( @@ -1132,56 +965,24 @@ export async function emailDomainRotateSecret( log.success('Zone ingress secret rotated and verified on the deployed Worker.'); } -/** `void email domain remove ` — exported for the unit test. */ export async function emailDomainRemove( client: Pick, projectId: string, rawDomain: string, - options: { force?: boolean; exit?: (code: number) => never } = {}, + options: { exit?: (code: number) => never } = {}, ): Promise { const domain = normalizeEmailDomainInput(rawDomain); - const result = await client.removeEmailDomain(projectId, domain, options.force); - - if (result.operationId) { - log.info(`Operation: ${result.operationId} · ${result.operationStatus ?? 'pending'}`); - if (!result.removed) { - log.error( - result.error ?? - 'Email cleanup is not complete. Its operation and resources remain recorded for reconciliation.', - ); - (options.exit ?? ((code: number): never => process.exit(code)))(1); - } - log.success(`Removed ${domain}. Zone resources still used by other domains were retained.`); - return; - } - if (!result.removed) { - // Kept for retry: a Cloudflare-side step failed without --force, so the - // row (and the stored credential the retry needs) stays. - const steps = result.failed_steps?.length ? result.failed_steps.join(', ') : 'unknown'; - log.error(`email: could not remove ${domain} — failed Cloudflare-side steps: ${steps}.`); - log.info( - `The registration was kept — retry \`void email domain remove ${domain}\` once the Cloudflare-side problem is fixed, or re-run with --force to drop the row anyway.`, + const result = await client.removeEmailDomain(projectId, domain); + log.info(`Operation: ${result.operationId} · ${result.operationStatus ?? 'pending'}`); + if (!result.removed || result.operationStatus !== 'completed') { + log.error( + result.error ?? + 'Email cleanup is not complete. Its operation and resources remain recorded for reconciliation.', ); (options.exit ?? ((code: number): never => process.exit(code)))(1); + return; } - - log.success( - `Removed ${domain} — the platform row, the stored credential and the relay secret are gone.`, - ); - const failed = result.failed_steps ?? []; - if ( - failed.length > 0 && - (result.forced === true || failed.some((step) => step !== 'revoke_grant')) - ) { - log.warn( - `Cloudflare-side cleanup failed for: ${failed.join(', ')} — delete the relay worker and reset the catch-all in the zone's Email Routing settings yourself.`, - ); - } else if (failed.length > 0) { - // Only the grant revoke failed: the rules and relay are already gone. - log.info( - 'Note: the Cloudflare grant could not be revoked (already invalid or Cloudflare unreachable) — no mail impact.', - ); - } + log.success(`Removed ${domain}. Zone resources still used by other domains were retained.`); } async function runEmailDomainCommand( @@ -1201,7 +1002,7 @@ async function runEmailDomainCommand( case 'rotate-secret': return emailDomainRotateSecret(client, projectId, args.domain!); case 'remove': - return emailDomainRemove(client, projectId, args.domain!, { force: args.force }); + return emailDomainRemove(client, projectId, args.domain!); } } diff --git a/packages/void/src/cli/help.ts b/packages/void/src/cli/help.ts index f3b2d25f7..1d4115d31 100644 --- a/packages/void/src/cli/help.ts +++ b/packages/void/src/cli/help.ts @@ -719,19 +719,10 @@ const HELP_TREE: HelpTree = { 'Reconcile the zone connection and refresh readiness.', 'void email domain sync [options]', ), - // Not `withProjectOption`: `remove` has a flag of its own (`--force`), - // same shape as the `email logs` page above. - remove: { - summary: 'Disable the domain assignment and reconcile shared resources.', - usage: ['void email domain remove [options]'], - options: [ - { - command: '--force', - description: 'Retain cleanup intent when provider work cannot be completed', - }, - { command: '--project ', description: 'Project name override' }, - ], - }, + remove: withProjectOption( + 'Disable the domain assignment and reconcile shared resources.', + 'void email domain remove [options]', + ), }, }, // Mode B (design doc 0078): both read the local project + your wrangler session, diff --git a/packages/void/src/router/compile.ts b/packages/void/src/router/compile.ts index 698398354..ab92a1664 100644 --- a/packages/void/src/router/compile.ts +++ b/packages/void/src/router/compile.ts @@ -2627,7 +2627,7 @@ export interface WorkerEntryOptions { runtimeEnvPath?: string; /** * Path to the `void/email` runtime, used for `createMessageProxy` in the - * generated `email()` handler. Defaults to a sibling-of-`runtimeEnvPath` + * generated email handlers. Defaults to a sibling-of-`runtimeEnvPath` * derivation, which covers both bare specifiers (`void/_env` -> `void/email`) * and resolved file paths. */ @@ -2641,10 +2641,7 @@ export interface WorkerEntryOptions { * and SSR apps leave this disabled so intentional 404s stay 404. */ serveSpaFallback?: boolean; - /** - * Emit the `email()` RPC method and the inbound dispatch glue. The route - * table must export `__emailHandler` when this is set. - */ + /** Emit native email and authenticated receipt handlers. Requires `__emailHandler`. */ hasEmail?: boolean; live?: boolean | { bindingName?: string; className?: string }; /** @@ -2884,17 +2881,9 @@ ${envValidateCall}${isrDeploymentStamp} const userEnv = __filterInternalBinding return withRuntimeEnv(env, () => scheduled(controller, userEnv, ctx)); }`; - // `ForwardableEmailMessage` is not in workerd's RPC BaseType allowlist, so the - // platform router serializes the message to an `EmailEnvelope`, this worker's - // `email()` method rebuilds a proxy through `createMessageProxy`, runs the user - // handler, and returns the recorded `EmailAction[]` for the router to enact. - // - // On the developer's own account Cloudflare calls `email()` with the real - // message and ignores the return value, so the actions would be lost: the - // message is accepted, then silently discarded. The same proxy runs the - // handler there (the native message satisfies the envelope shape, and the - // proxy makes `raw` replayable), and `enactEmailActions` replays what was - // recorded on the real message before returning. + // Both the authenticated receipt endpoint and native Cloudflare email event + // run the same handler. Native events replay recorded actions on the real + // message; receipts return bounded action frames to the platform. const emailImport = hasEmail ? ', __emailHandler' : ''; const emailRuntimePath = runtimeEmailPath ?? deriveEmailRuntimePath(runtimeEnvPath); const emailProxyImport = hasEmail @@ -2906,14 +2895,9 @@ ${envValidateCall}${isrDeploymentStamp} const userEnv = __filterInternalBinding // the generated `__emailHandler`, which routes on the wire address // (`__voidPlatformTo`) and strips the `+` prefix iff a slug is set. // - // Except on the relay lane: an envelope carrying `viaDomain` arrived via - // POST /email/relay from a customer zone (design doc 0078, "Custom domains - // on Cloudflare") and its recipient carries no `+` prefix — the - // dispatcher runs in no-prefix mode (Mode B item 4), so `support+T-42@acme.com` - // reaches `email/support+[ticket].ts` with the tag intact. Provisioning - // injects `__VOID_PROJECT_SLUG` unconditionally, so the slug must be - // suppressed HERE: left applied, the strip would take everything up to the - // first `+` and dispatch the bare tag to `_default` or a wrong `[user]`. + // Verified custom-domain receipts carry `viaDomain` and have no project + // prefix. Suppress the slug there so tags such as `support+T-42@acme.com` + // reach the matching handler intact. const emailHandler = hasEmail ? remotePath ? `async function handleEmail(envelope, env, ctx) { @@ -2970,18 +2954,21 @@ ${envValidateCall} const userEnv = __filterInternalBindings(env); }` : ''; - // The default export is a `WorkerEntrypoint` subclass. A plain default object - // only exposes `.fetch()` through a Workers-for-Platforms dispatch stub, so - // `email()` would be unreachable; class methods on a `WorkerEntrypoint` - // subclass become RPC provider methods on that stub. `fetch()` stays - // HTTP-compatible inside the class. + // The default export remains a WorkerEntrypoint for platform fetch dispatch. + // Its email method accepts only native events on direct Cloudflare deploys; + // platform mail enters through the authenticated receipt fetch endpoint. const entryImport = `import { WorkerEntrypoint } from "cloudflare:workers";\n`; const fetchDeclaration = `const __voidFetch = ${fetchHandler};`; const queueMethodBody = hasQueues ? ` async queue(batch) { return __voidQueue(batch, this.env, this.ctx); }\n` : ''; const emailMethodBody = hasEmail - ? ` async email(envelope) { return handleEmail(envelope, this.env, this.ctx); }\n` + ? ` async email(message) { + if (this.env.__VOID_EMAIL_DEPLOYMENT_ID || !__isForwardableEmailMessage(message)) { + throw new TypeError("Native email event required"); + } + await handleEmail(message, this.env, this.ctx); + }\n` : ''; const entryClass = `export default class extends WorkerEntrypoint { async fetch(request) { return __voidFetch(request, this.env, this.ctx); } diff --git a/packages/void/src/runtime/email/inbound.ts b/packages/void/src/runtime/email/inbound.ts index 5c8c46753..1f83852ec 100644 --- a/packages/void/src/runtime/email/inbound.ts +++ b/packages/void/src/runtime/email/inbound.ts @@ -1,12 +1,6 @@ -// `ForwardableEmailMessage` is not in workerd's RPC BaseType allowlist, so the -// platform router serializes it into an `EmailEnvelope` and the worker returns -// `EmailAction[]` describing what the handler decided. The router enacts the -// actions on the real message. -// -// On the developer's own Cloudflare account there is no router: Cloudflare -// calls the worker's `email()` with the real message. The same proxy runs the -// handler, and `enactEmailActions` replays the recorded actions on the native -// message, whose return value Cloudflare ignores. +// Managed delivery uses bounded HTTP envelopes and recorded action responses. +// Native Cloudflare email events use the same proxy, then enact its actions on +// the original message before returning. import type { Email as PostalMimeEmail } from 'postal-mime'; import { getRawRuntimeEnv } from '../env-raw.ts'; @@ -18,72 +12,25 @@ import type { Address, Attachment } from './types.ts'; // the default reply `from` address. const VALID_SLUG = /^[a-z0-9](?:[a-z0-9-]{0,54}[a-z0-9])?$/; -/** - * Guardrails on what one handler may queue. - * - * These are NOT the security boundary. Recording happens inside the tenant's - * own worker, and on the platform a Workers-for-Platforms tenant can ship any - * `WorkerEntrypoint` whose `email()` returns any array at all, bypassing this - * file entirely — so the load-bearing caps are the matching ones in the - * platform router (`MAX_ACTIONS` / `MAX_ACTION_ADDRESS_LENGTH` in - * `email-router.ts`). What these buy is a fast, precise failure at the call - * that went wrong, instead of a whole action list silently dropped at the - * router with only a platform-side log to show for it. - */ +// SDK limits give handlers early errors. The gateway independently validates +// untrusted tenant responses before admitting any action. const MAX_ACTIONS = 100; const MAX_ACTION_ADDRESS_LENGTH = 320; const MAX_ACTION_METADATA_BYTES = 8 * 1024; -/** - * Bounds on one forward's header bag: how many, and how long a name or a - * value may be. Restated from the router's `MAX_FORWARD_HEADERS` / - * `MAX_FORWARD_HEADER_LENGTH` (`email-router.ts` — the platform depends on - * the framework, never the reverse, so the numbers cannot be imported; a - * proxy-side test pins them equal). The router drops the WHOLE action list - * on a violation, so a bag that passed here and failed there was a handler - * whose test reported the forward and whose managed deployment silently - * performed no actions. Exported for that parity test only. - */ +/** Bounds on a forward's headers, shared with the handler test harness. */ export const MAX_FORWARD_HEADERS: number = 32; export const MAX_FORWARD_HEADER_LENGTH: number = 1024; -/** - * Cap on a reject reason, restated from the router's - * `MAX_REJECT_REASON_LENGTH` in `email-router.ts` for the same reason as - * above, and pinned by the same test. See `normalizeRejectReason`. - */ +/** Maximum normalized SMTP rejection reason length. */ export const MAX_REJECT_REASON_LENGTH: number = 1000; -/** - * The router's ADMISSION bounds — what it refuses BEFORE the handler runs - * (`MAX_INBOUND_BYTES` / `MAX_INBOUND_HEADERS` in `email-router.ts`, - * restated for the same reason as above and pinned by the same test). - * `routeInbound` rejects a message over either one and never dispatches it, - * so a handler's behaviour on such a message is unreachable after a managed - * deploy; the test harness applies both before it invokes the handler. - * - * `MAX_INBOUND_BYTES` is NOT `MAX_MESSAGE_BYTES`, though the numbers agree - * today. That one is Cloudflare's cap on an OUTBOUND message (and the - * `parseEmail` guard); this one is the router's own heap headroom on an - * inbound one, set well under Cloudflare's ~25 MB inbound ceiling, and the - * two can move independently. - */ +/** Inbound admission limits also applied by the handler test harness. */ export const MAX_INBOUND_BYTES: number = 10 * 1024 * 1024; export const MAX_INBOUND_HEADERS: number = 1024; -/** - * Cumulative reply-byte budget for ONE dispatch. - * - * `MAX_MESSAGE_BYTES` bounds a single `reply()` call, not the queue: N replies - * at the cap is N x 10 MiB of `Uint8Array` riding one RPC response. workerd - * caps a serialized RPC payload at 32 MiB, so the queue that clears our - * per-reply check still fails at the boundary — opaquely. The router cannot - * tell that failure from any other dispatch error, so the whole message comes - * back to the sender as a generic "project handler error" reject with nothing - * in it a handler author could act on. Two full-size replies is already well - * past any legitimate use, and failing here names the exact call that - * overran. - */ +// The protocol encoder additionally counts framing and metadata toward its +// total response budget. const MAX_REPLY_BYTES = 5 * 1024 * 1024; const MAX_REPLY_BYTES_TOTAL = 8 * 1024 * 1024; @@ -217,41 +164,25 @@ interface RawCache { } const proxyRawCache = new WeakMap(); -/** - * Serialized inbound email message — sent from the platform router to the - * user worker over RPC. Every field is in workerd's RPC `BaseType` - * allowlist (string, plain object, ReadableStream, number). - */ +/** Inbound message decoded from the authenticated gateway request. */ export interface EmailEnvelope { from: string; to: string; - /** Headers serialized as a plain object so they cross RPC. */ + /** Decoded header metadata. */ headers: Record; /** - * Raw RFC 5322 bytes. Pre-buffered by the router so it's replayable on the - * receiving side (`parseEmail` consumes the stream once; if the handler - * also calls `parseEmail` directly, the platform tee'd a fresh stream per - * delivery). + * Raw RFC 5322 bytes. The message proxy caches them for repeated reads. */ raw: ReadableStream | Uint8Array; rawSize: number; /** - * The registered custom domain this message arrived on, set only by the - * platform's relay lane (`POST /email/relay` — design doc 0078, "Custom - * domains on Cloudflare"). Undefined on the platform mail zone. A relayed - * recipient carries no `+` prefix, so the generated dispatcher runs - * in no-prefix mode for it (Mode B item 4) and `replyEmail` defaults - * `from` to the address that received it, on this domain. + * Exact custom domain selected by the gateway. Custom-domain recipients + * have no project-slug prefix; replies default to the received address. */ viaDomain?: string; } -/** - * What the user handler decided to do with a message. Returned from the - * worker's `email(envelope)` RPC method as an array (handlers may chain - * multiple actions, e.g. forward then reply); the router enacts each on the - * real `ForwardableEmailMessage` in order. - */ +/** Handler intents, validated and admitted by the gateway before delivery. */ export type EmailAction = | { type: 'reject'; reason: string } | { type: 'forward'; to: string; headers?: Record } @@ -472,7 +403,7 @@ function bytesToReadableStream(bytes: Uint8Array): ReadableStream { * accept a native `EmailMessage` from `cloudflare:email`: that class exposes * only `from` and `to` (workers-types declares nothing else, and the body * has no public accessor), so its bytes cannot be recorded here, and nothing - * could carry them over RPC to the platform router. The reply MIME bytes are + * could encode them for the gateway. The reply MIME bytes are * buffered before being recorded so the action is fully self-contained. * * When `opts.slug` is provided, `message.to` is rewritten to remove the @@ -574,17 +505,8 @@ export function createMessageProxy( return; // already rejected; ignore second reject } rejected = true; - // Deliberately NOT bounded by MAX_ACTIONS. The purge below makes this - // the one call that SHRINKS the queue, so it can never be what overruns - // it — and throwing out of "refuse this mail" would cost the handler its - // reject and hand the message back to the sender as a dispatch error, - // which is strictly worse than whatever the oversized queue was. - // Walk back through the queue and drop any prior forward/reply: CF - // (and the platform router) treats setReject as terminal — preceding - // actions in this dispatch never execute. Without this purge the - // action queue lies (records a forward the router never enacts), - // which corrupts the audit trail. Warn so handler authors notice - // the misuse. + // Reject is terminal and replaces queued deliveries, so it must remain + // available even when the action queue is full. let dropped = 0; for (let i = actions.length - 1; i >= 0; i--) { const a = actions[i]; @@ -614,16 +536,7 @@ export function createMessageProxy( if (to.length > MAX_ACTION_ADDRESS_LENGTH) { throw addressTooLong('to', to.length); } - // Shape, after the length bound above so the scan is over at most 320 - // characters. `forward(rcptTo)` takes a bare address — Cloudflare's - // "verified destination address" — so no display name is parsed; the - // rule is the one `sendEmail` applies to its `to` AND the one the - // platform router drops on (`email-validator`, on both sides), so a - // handler's forward refuses exactly what an outbound send refuses and - // records nothing the router would lose. Left to replay, a malformed - // address in a LATER forward was refused by Cloudflare only after - // earlier forwards and replies had fired (the platform router - // validates the whole list first and drops just that forward). + // Validate the bare address before recording any delivery intent. validateAddressParts('to', to); // Accept both `Headers` (matches CF's runtime signature) and a plain // `Record`. `Headers.entries()` lowercases keys per @@ -634,15 +547,8 @@ export function createMessageProxy( if (fwdHeaders instanceof Headers) { headersObj = Object.fromEntries(fwdHeaders.entries()); } else if (fwdHeaders) { - // A `Headers` instance has already validated its names and values; - // a record has not. Every consumer replays the record through - // `new Headers()` — `enactEmailActions` on a native message, the - // platform router before its own replay — so run that constructor - // here and fail in the handler's own call. Left to replay, a CRLF - // or NUL in a LATER forward surfaced only after earlier forwards and - // replies had fired, leaving Cloudflare a failed invocation for a - // message that was partly delivered. The record itself is what is - // stored: preserving name casing is why this form exists. + // Validate now to avoid partial delivery during native replay. Keep + // the record itself so caller-provided header casing is preserved. try { void new Headers(fwdHeaders); } catch (e) { @@ -1294,8 +1200,8 @@ export async function buildReplyMessage( /** * Send a threading-aware reply to an inbound message. Builds the reply MIME * (correct `In-Reply-To` / `References` / `Subject: Re: …`) and records a - * reply intent on the message proxy. The platform router enacts the reply - * via the real `ForwardableEmailMessage.reply()` once the handler returns. + * reply intent on the message proxy. Delivery follows handler completion and, + * on the platform, authoritative admission. * * The threading headers are best-effort, since the inbound values they are * built from are remote-sender controlled: an id no header line can carry @@ -1315,10 +1221,8 @@ export async function replyEmail( } /** - * Whether `value` is a real `ForwardableEmailMessage` — one Cloudflare - * delivered to this worker's `email()` directly — rather than an - * `EmailEnvelope` from the platform router. Functions do not survive RPC, - * so their presence is the discriminator. + * Recognize native email operations. This structural check is not an + * authentication boundary; managed entrypoints require receipt authentication. */ export function isForwardableEmailMessage(value: unknown): value is ForwardableEmailMessage { if (typeof value !== 'object' || value === null) { @@ -1340,16 +1244,8 @@ export function isForwardableEmailMessage(value: unknown): value is ForwardableE * duck-typed object — so `cloudflare:email` is loaded here, and only when * a reply was recorded. * - * The `new Headers()` below is the one step this loop constructs from - * handler input, and it cannot fail on a recorded action: the proxy's - * `forward()` already ran the record through that constructor, so a bad - * record failed inside the handler, before any replay. (`EmailMessage` - * construction neither validates nor reads its stream — measured under - * workerd.) A reject's reason reaches the native `setReject()` as the proxy - * recorded it — already sliced and stripped the way the platform router - * would (`normalizeRejectReason`), so the SMTP reply is the same in both - * deployments. What Cloudflare itself refuses at `forward()` / `reply()` - * still throws out of the loop, as any native call would. + * The proxy already validated forward headers and normalized reject reasons. + * Provider refusals still propagate to the native event caller. */ export async function enactEmailActions( message: ForwardableEmailMessage, diff --git a/packages/void/test/unit/cf-oauth.test.ts b/packages/void/test/unit/cf-oauth.test.ts deleted file mode 100644 index a18e0e2ac..000000000 --- a/packages/void/test/unit/cf-oauth.test.ts +++ /dev/null @@ -1,377 +0,0 @@ -import { createHash } from 'node:crypto'; -import { log } from '@clack/prompts'; -import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; -import { - CF_OAUTH_CALLBACK_PATH, - CF_OAUTH_CALLBACK_PORT, - CF_OAUTH_CLIENT_ID, - CF_OAUTH_REDIRECT_URI, - CF_OAUTH_REVOKE_URL, - CF_OAUTH_SCOPE, - CF_OAUTH_TOKEN_URL, - revokeCfOauthGrant, - runCfOauthGrant, -} from '../../src/cli/cf-oauth.ts'; - -/** - * The PKCE grant on wrangler's public client (contract 8) against a mocked - * loopback/token endpoint — no real network: the loopback server on :8976 is - * real (the platform login tests do the same on a random port), and - * Cloudflare's token endpoint is a fetch stub. Token values are inert - * placeholders and are never printed. - */ - -const mockExecFile = vi.fn(); -const originalFetch = globalThis.fetch.bind(globalThis); - -function fetchLoopback(input: RequestInfo | URL, init?: RequestInit): Promise { - // Each grant binds the same port. Do not reuse a keep-alive connection to - // an earlier grant's server, which still holds that grant's state. - const request = new Request(input, init); - request.headers.set('Connection', 'close'); - return originalFetch(request); -} - -const AUTH_CODE = 'cf-auth-code-placeholder'; -const REFRESH_SENTINEL = 'cf-refresh-token-placeholder'; - -let tokenExchangeBodies: Array; -let tokenEndpointResponse: () => Response | Promise; - -function codeChallengeFor(verifier: string): string { - return createHash('sha256') - .update(verifier) - .digest('base64') - .replaceAll('+', '-') - .replaceAll('/', '_') - .replaceAll('=', ''); -} - -vi.mock('node:child_process', () => ({ - execFile: (...args: Array) => mockExecFile(...args), -})); - -beforeEach(() => { - mockExecFile.mockReset(); - tokenExchangeBodies = []; - tokenEndpointResponse = () => - Response.json({ - access_token: 'cf-access-token-placeholder', - refresh_token: REFRESH_SENTINEL, - expires_in: 3600, - }); - vi.spyOn(log, 'warn').mockImplementation(() => {}); - - vi.stubGlobal('fetch', async (input: RequestInfo | URL, init?: RequestInit) => { - const url = - input instanceof Request ? input.url : input instanceof URL ? input.href : input.toString(); - if (url.startsWith('http://localhost:') || url.startsWith('http://127.0.0.1:')) { - return fetchLoopback(input, init); - } - if (url === CF_OAUTH_TOKEN_URL) { - tokenExchangeBodies.push(new URLSearchParams(init?.body?.toString() ?? '')); - return tokenEndpointResponse(); - } - throw new Error(`unexpected network call in test: ${url}`); - }); -}); - -afterEach(() => { - vi.unstubAllGlobals(); - vi.restoreAllMocks(); -}); - -async function startGrant(): Promise<{ url: URL; grant: Promise }> { - let ready!: (url: URL) => void; - const urlPromise = new Promise((resolve) => { - ready = resolve; - }); - const grant = runCfOauthGrant({ - timeoutMs: 5000, - onUrl: (url) => ready(new URL(url)), - }); - return { url: await urlPromise, grant }; -} - -function callbackUrl(): URL { - return new URL(CF_OAUTH_REDIRECT_URI); -} - -describe('runCfOauthGrant', () => { - it('runs the full PKCE flow and resolves the grant refresh token', async () => { - const { url, grant } = await startGrant(); - - // The authorize URL is Cloudflare's consent endpoint with the pinned - // contract-8 parameters — wrangler's client, the fixed loopback - // redirect, the email scope set, and an S256 challenge. - expect(url.origin + url.pathname).toBe('https://dash.cloudflare.com/oauth2/auth'); - expect(url.searchParams.get('response_type')).toBe('code'); - expect(url.searchParams.get('client_id')).toBe(CF_OAUTH_CLIENT_ID); - expect(url.searchParams.get('redirect_uri')).toBe(CF_OAUTH_REDIRECT_URI); - expect(url.searchParams.get('scope')).toBe(CF_OAUTH_SCOPE); - expect(url.searchParams.get('code_challenge_method')).toBe('S256'); - expect(url.searchParams.get('code_challenge')).toEqual(expect.any(String)); - const state = url.searchParams.get('state'); - expect(state).toEqual(expect.any(String)); - - // The Wrangler-named consent page warning is printed before opening. - expect(vi.mocked(log.warn)).toHaveBeenCalledWith(expect.stringContaining('names Wrangler')); - - const callback = callbackUrl(); - callback.searchParams.set('state', state!); - callback.searchParams.set('code', AUTH_CODE); - const pageResponse = await fetch(callback); - expect(pageResponse.status).toBe(200); - expect(await pageResponse.text()).toContain('Cloudflare connected'); - - await expect(grant).resolves.toEqual({ refreshToken: REFRESH_SENTINEL }); - - // The exchange is form-encoded against the token endpoint with the code, - // the pinned redirect and client, and the verifier behind the challenge. - expect(tokenExchangeBodies).toHaveLength(1); - const body = tokenExchangeBodies[0]!; - expect(body.get('grant_type')).toBe('authorization_code'); - expect(body.get('code')).toBe(AUTH_CODE); - expect(body.get('redirect_uri')).toBe(CF_OAUTH_REDIRECT_URI); - expect(body.get('client_id')).toBe(CF_OAUTH_CLIENT_ID); - const verifier = body.get('code_verifier'); - expect(verifier).toEqual(expect.any(String)); - expect(codeChallengeFor(verifier!)).toBe(url.searchParams.get('code_challenge')); - - // The browser was asked to open the consent URL, via argv (never a shell). - expect(mockExecFile).toHaveBeenCalled(); - }); - - it('rejects a mismatched state but keeps listening for the real callback', async () => { - const { url, grant } = await startGrant(); - const state = url.searchParams.get('state')!; - - const attack = callbackUrl(); - attack.searchParams.set('state', 'attacker-state'); - attack.searchParams.set('code', AUTH_CODE); - expect((await fetch(attack)).status).toBe(400); - expect(tokenExchangeBodies).toHaveLength(0); - - const valid = callbackUrl(); - valid.searchParams.set('state', state); - valid.searchParams.set('code', AUTH_CODE); - expect((await fetch(valid)).status).toBe(200); - await expect(grant).resolves.toEqual({ refreshToken: REFRESH_SENTINEL }); - }); - - it('rejects when the customer denies the consent', async () => { - const { url, grant } = await startGrant(); - const rejection = expect(grant).rejects.toThrow(/consent was denied/); - - const denied = callbackUrl(); - denied.searchParams.set('state', url.searchParams.get('state')!); - denied.searchParams.set('error', 'access_denied'); - const pageResponse = await fetch(denied); - expect(pageResponse.status).toBe(403); - expect(await pageResponse.text()).toContain('consent was denied'); - - await rejection; - expect(tokenExchangeBodies).toHaveLength(0); - }); - - it('rejects when the token exchange fails, without echoing the response body', async () => { - const canary = 'body-canary-never-in-errors'; - tokenEndpointResponse = () => new Response(canary, { status: 400 }); - const { url, grant } = await startGrant(); - const rejection = expect(grant).rejects.toThrow(/HTTP 400/); - - const callback = callbackUrl(); - callback.searchParams.set('state', url.searchParams.get('state')!); - callback.searchParams.set('code', AUTH_CODE); - const pageResponse = await fetch(callback); - // The exchange runs inside the request handler, so a failure renders the - // failure page, never the success page. - expect(pageResponse.status).toBe(400); - expect(await pageResponse.text()).toContain('Could not complete'); - - const error = await grant.catch((err: unknown) => err); - expect(error).toBeInstanceOf(Error); - expect((error as Error).message).not.toContain(canary); - await rejection; - }); - - it('rejects when the answer carries no refresh token', async () => { - tokenEndpointResponse = () => Response.json({ access_token: 'cf-access-token-placeholder' }); - const { url, grant } = await startGrant(); - const rejection = expect(grant).rejects.toThrow(/no refresh token/); - - const callback = callbackUrl(); - callback.searchParams.set('state', url.searchParams.get('state')!); - callback.searchParams.set('code', AUTH_CODE); - await fetch(callback); - await rejection; - }); - - it('rejects when the callback port is already in use', async () => { - const http = await import('node:http'); - const blocker = http.createServer((_req, res) => res.end('busy')); - await new Promise((resolve) => - blocker.listen(CF_OAUTH_CALLBACK_PORT, '127.0.0.1', resolve), - ); - try { - await expect(runCfOauthGrant({ timeoutMs: 5000 })).rejects.toThrow( - new RegExp(`could not start the local callback server on port ${CF_OAUTH_CALLBACK_PORT}`), - ); - // No browser, no consent warning — nothing opened. - expect(mockExecFile).not.toHaveBeenCalled(); - } finally { - await new Promise((resolve) => blocker.close(resolve)); - } - }); - - it('rejects on abort (Enter switching to the token path) and closes the server', async () => { - const controller = new AbortController(); - const { url, grant } = await (async () => { - let ready!: (url: URL) => void; - const urlPromise = new Promise((resolve) => { - ready = resolve; - }); - const grantPromise = runCfOauthGrant({ - timeoutMs: 5000, - signal: controller.signal, - onUrl: (url) => ready(new URL(url)), - }); - return { url: await urlPromise, grant: grantPromise }; - })(); - expect(url).toBeInstanceOf(URL); - - controller.abort(); - await expect(grant).rejects.toThrow(/cancelled/); - - // The port is free again immediately — the next grant can bind it. - const { url: secondUrl, grant: secondGrant } = await startGrant(); - const callback = callbackUrl(); - callback.searchParams.set('state', secondUrl.searchParams.get('state')!); - callback.searchParams.set('code', AUTH_CODE); - expect((await fetch(callback)).status).toBe(200); - await expect(secondGrant).resolves.toEqual({ refreshToken: REFRESH_SENTINEL }); - }); - - it('revokes the minted grant when the exchange resolves after the flow settled', async () => { - const controller = new AbortController(); - const revokeBodies: Array = []; - let resolveExchange!: (response: Response) => void; - tokenEndpointResponse = () => - new Promise((resolve) => { - resolveExchange = resolve; - }); - // The default stub throws on the revoke endpoint — re-stub with a branch - // that captures it. - vi.stubGlobal('fetch', async (input: RequestInfo | URL, init?: RequestInit) => { - const url = - input instanceof Request ? input.url : input instanceof URL ? input.href : input.toString(); - if (url.startsWith('http://localhost:') || url.startsWith('http://127.0.0.1:')) { - return fetchLoopback(input, init); - } - if (url === CF_OAUTH_TOKEN_URL) { - tokenExchangeBodies.push(new URLSearchParams(init?.body?.toString() ?? '')); - return tokenEndpointResponse(); - } - if (url === CF_OAUTH_REVOKE_URL) { - revokeBodies.push(new URLSearchParams(init?.body?.toString() ?? '')); - return new Response(null, { status: 200 }); - } - throw new Error(`unexpected network call in test: ${url}`); - }); - - let ready!: (url: URL) => void; - const urlPromise = new Promise((resolve) => { - ready = resolve; - }); - const grant = runCfOauthGrant({ - timeoutMs: 5000, - signal: controller.signal, - onUrl: (url) => ready(new URL(url)), - }); - const url = await urlPromise; - const rejection = expect(grant).rejects.toThrow(/cancelled/); - - // Fire the valid callback; the exchange hangs inside the handler. - const callback = callbackUrl(); - callback.searchParams.set('state', url.searchParams.get('state')!); - callback.searchParams.set('code', AUTH_CODE); - const pagePromise = fetch(callback); - await vi.waitFor(() => expect(tokenExchangeBodies).toHaveLength(1)); - - // Enter switching to the token path settles the flow mid-exchange. - controller.abort(); - await rejection; - - // The exchange then completes: Cloudflare minted the grant and the CLI is - // the only actor holding it — it must be revoked, not stranded. - resolveExchange( - Response.json({ - access_token: 'cf-access-token-placeholder', - refresh_token: REFRESH_SENTINEL, - expires_in: 3600, - }), - ); - const pageResponse = await pagePromise; - expect(pageResponse.status).toBe(200); - expect(await pageResponse.text()).toContain('cancelled'); - - await vi.waitFor(() => expect(revokeBodies).toHaveLength(1)); - expect(revokeBodies[0]!.get('token')).toBe(REFRESH_SENTINEL); - expect(revokeBodies[0]!.get('token_type_hint')).toBe('refresh_token'); - expect(revokeBodies[0]!.get('client_id')).toBe(CF_OAUTH_CLIENT_ID); - }); - - it(`listens on the pinned ${CF_OAUTH_CALLBACK_PORT}${CF_OAUTH_CALLBACK_PATH} and 404s everything else`, async () => { - const { url, grant } = await startGrant(); - const rejection = expect(grant).rejects.toThrow(); // settled below via deny - - expect(new URL(CF_OAUTH_REDIRECT_URI).pathname).toBe(CF_OAUTH_CALLBACK_PATH); - const off = new URL(CF_OAUTH_REDIRECT_URI); - off.pathname = '/favicon.ico'; - expect((await fetch(off)).status).toBe(404); - - const denied = new URL(CF_OAUTH_REDIRECT_URI); - denied.searchParams.set('state', url.searchParams.get('state')!); - denied.searchParams.set('error', 'access_denied'); - await fetch(denied); - await rejection; - }); -}); - -describe('revokeCfOauthGrant', () => { - it('posts the RFC 7009 form and reports true on a 2xx', async () => { - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => new Response(null, { status: 200 }), - ); - vi.stubGlobal('fetch', fetchSpy); - - await expect(revokeCfOauthGrant(REFRESH_SENTINEL)).resolves.toBe(true); - - expect(fetchSpy).toHaveBeenCalledTimes(1); - const [url, init] = fetchSpy.mock.calls[0]!; - expect(String(url)).toBe(CF_OAUTH_REVOKE_URL); - const form = new URLSearchParams(String(init?.body)); - expect(form.get('token')).toBe(REFRESH_SENTINEL); - expect(form.get('token_type_hint')).toBe('refresh_token'); - expect(form.get('client_id')).toBe(CF_OAUTH_CLIENT_ID); - }); - - it('reports false on a non-2xx answer — the grant may still be live', async () => { - const fetchSpy = vi.fn( - async (_input: RequestInfo | URL, _init?: RequestInit) => - new Response('nope', { status: 500 }), - ); - vi.stubGlobal('fetch', fetchSpy); - - await expect(revokeCfOauthGrant(REFRESH_SENTINEL)).resolves.toBe(false); - }); - - it('reports false on a network failure, never throwing', async () => { - const fetchSpy = vi.fn(async () => { - throw new TypeError('fetch failed'); - }); - vi.stubGlobal('fetch', fetchSpy); - - await expect(revokeCfOauthGrant(REFRESH_SENTINEL)).resolves.toBe(false); - }); -}); diff --git a/packages/void/test/unit/cli-help.test.ts b/packages/void/test/unit/cli-help.test.ts index d19380a43..19f349179 100644 --- a/packages/void/test/unit/cli-help.test.ts +++ b/packages/void/test/unit/cli-help.test.ts @@ -201,13 +201,8 @@ describe('rendered help advertises the flags the parser honours', () => { 'void email domain add [options]', ); - // `remove` is the one domain verb with a flag of its own. - expect(parseEmailArgs(['domain', 'remove', 'acme.com', '--force'])).toMatchObject({ - domainVerb: 'remove', - force: true, - }); const removePage = render(['email', 'domain', 'remove']); - expect(removePage).toContain('--force'); + expect(removePage).not.toContain('--force'); expect(removePage).toContain('--project '); }); }); diff --git a/packages/void/test/unit/email-cli-disallow.test.ts b/packages/void/test/unit/email-cli-disallow.test.ts index 216f761dd..b74ee3337 100644 --- a/packages/void/test/unit/email-cli-disallow.test.ts +++ b/packages/void/test/unit/email-cli-disallow.test.ts @@ -3,16 +3,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test' import type { PlatformClient } from '../../src/cli/client.ts'; import { emailDisallow } from '../../src/cli/email.ts'; -/** - * What `void email disallow
` prints on success. The one contract - * under test: the line must not tell the user a deploy is needed. The api - * tightens the proxy's `email-allowlist:` KV mirror inside the - * DELETE (503 if that write fails) and the proxy re-reads the mirror with a - * 60s `cacheTtl` on both the send path and inbound forward/reply, so the - * revocation lands on its own within about a minute — no deploy touches - * the allowlist. - */ - type Destination = Awaited>[number]; const ADDRESS = 'owner@example.com'; @@ -64,8 +54,6 @@ describe('void email disallow', () => { expect(text).toBe( `Removed ${ADDRESS}. New sends to it are refused immediately; already admitted attempts may finish.`, ); - // The api tightens the KV allowlist in the DELETE and the proxy's - // cacheTtl bounds convergence; nothing about a revoke waits for a deploy. expect(text).not.toMatch(/deploy/); }); diff --git a/packages/void/test/unit/email-cli-domain.test.ts b/packages/void/test/unit/email-cli-domain.test.ts index 000bc4498..4fe4bcca7 100644 --- a/packages/void/test/unit/email-cli-domain.test.ts +++ b/packages/void/test/unit/email-cli-domain.test.ts @@ -4,7 +4,6 @@ import { PlatformApiError, PlatformClient, type EmailDomainResponse, - type EmailDomainStatusResponse, type RemoveEmailDomainResponse, } from '../../src/cli/client.ts'; import { @@ -78,29 +77,20 @@ function domainRow(overrides: Partial = {}): EmailDomainRes return { id: 'edom_1', domain: 'acme.com', - mode: 'apex', - status: 'active', - credential_kind: 'oauth_grant', - relay_worker_name: 'void-email-relay', + projectId: 'prj_1', + status: 'ready', + managed_by: 'owner', + connectionId: 'conn_1', + account_id: 'account_1', + zone_id: 'zone_1', + relay_worker_name: 'void-email-ingress', relay_version: 1, - token_id: null, - token_expires_on: null, - setup_state: null, - created_at: '2026-09-16T00:00:00Z', - updated_at: '2026-09-16T00:00:00Z', - ...overrides, - }; -} - -function statusRow(overrides: Partial = {}): EmailDomainStatusResponse { - return { - ...domainRow(), - credential_status: 'active', - current_relay_version: 1, - relay_drift: false, - relay_missing: false, - catch_all: 'points_here', - catch_all_drift: false, + operationId: null, + readiness: { + inbound: { status: 'ready', reason: null, observedAt: null }, + outbound: { status: 'verified_only', reason: null, observedAt: null }, + management: { status: 'healthy', reason: null, observedAt: null }, + }, ...overrides, }; } @@ -227,10 +217,10 @@ describe('PlatformClient.getEmailSettings', () => { }); }); - it('treats a platform without the route as self-serve, but a missing project as an error', async () => { - await expect(clientWith(404, '404 Not Found').getEmailSettings('prj_1')).resolves.toEqual({ - domains: { management: 'self-serve' }, - }); + it('does not start a credential flow when the settings route is unavailable', async () => { + await expect(clientWith(404, '404 Not Found').getEmailSettings('prj_1')).rejects.toThrow( + PlatformApiError, + ); await expect( clientWith(404, JSON.stringify({ error: 'project not found' })).getEmailSettings('prj_gone'), ).rejects.toThrow(PlatformApiError); @@ -259,8 +249,8 @@ describe('emailDomainAdd', () => { } function client() { return { - addEmailDomain: vi.fn(async () => domainRow({ credential_kind: 'api_token' })), - getEmailDomain: vi.fn(async () => statusRow()), + addEmailDomain: vi.fn(async () => domainRow()), + getEmailDomain: vi.fn(async () => domainRow()), getEmailOperation: vi.fn(async () => ({ operationId: 'op_1', attemptId: ATTEMPT_ID, @@ -477,7 +467,7 @@ describe('emailDomainAdd', () => { const api = client(); api.addEmailDomain.mockResolvedValue( domainRow({ - status: 'failed', + status: 'drifted', operationId: 'op_1', operationStatus: 'blocked', error: 'catch-all conflict', @@ -491,219 +481,133 @@ describe('emailDomainAdd', () => { }); describe('emailDomainStatus', () => { - it('renders the row, the live credential probe and the relay state', async () => { - const getEmailDomain = vi.fn(async () => - statusRow({ token_id: 'cf-token-id', token_expires_on: '2026-12-31T00:00:00Z' }), - ); + it('shows the recorded readiness and gives an owner the correct reconciliation command', async () => { const getEmailSettings = vi.fn(selfServeSettings); - await emailDomainStatus({ getEmailDomain, getEmailSettings }, 'prj_1', 'acme.com'); - - const block = notedBlocks(); - expect(block).toContain('Domain: acme.com'); - expect(block).toContain('Mode: apex'); - expect(block).toContain('Credential: OAuth grant · active'); - expect(block).toContain('Token: id cf-token-id · expires 2026-12-31T00:00:00Z'); - expect(block).toContain('Relay: void-email-relay v1'); - expect(getEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com'); - expect(getEmailSettings).not.toHaveBeenCalled(); - }); - - it('points at sync when the relay drifted or went missing', async () => { await emailDomainStatus( { getEmailDomain: vi.fn(async () => - statusRow({ relay_drift: true, current_relay_version: 2 }), + domainRow({ + status: 'pending', + operationId: 'eop_1', + operationStatus: 'blocked', + readiness: { + inbound: { + status: 'pending', + reason: 'Enable Email Routing for mail.acme.com', + observedAt: '2026-09-17T00:00:00Z', + }, + outbound: { status: 'verified_only' }, + management: { status: 'healthy' }, + }, + }), ), - getEmailSettings: selfServeSettings, + getEmailSettings, }, 'prj_1', 'acme.com', ); - expect(notedBlocks()).toContain('drifted (current is v2)'); + expect(notedBlocks()).toContain('Operation: eop_1 · blocked'); + expect(notedBlocks()).toContain('Enable Email Routing for mail.acme.com'); + expect(notedBlocks()).toContain('outbound verified_only'); expect(printed(infoSpy)).toContain('void email domain sync acme.com'); - - await emailDomainStatus( - { - getEmailDomain: vi.fn(async () => statusRow({ relay_missing: true })), - getEmailSettings: selfServeSettings, - }, - 'prj_1', - 'acme.com', - ); - expect(notedBlocks()).toContain('missing from the account'); + expect(getEmailSettings).not.toHaveBeenCalled(); }); - it('names the renewal path for a revoked or expired credential', async () => { + it('sends an administrator-managed pending assignment to the operator', async () => { + const getEmailSettings = vi.fn(async () => ({ + domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, + })); await emailDomainStatus( { getEmailDomain: vi.fn(async () => - statusRow({ status: 'token_revoked', credential_status: 'revoked' }), + domainRow({ + managed_by: 'admin', + status: 'pending', + readiness: { + inbound: { status: 'pending' }, + outbound: { status: 'verified_only' }, + management: { status: 'healthy' }, + }, + }), ), - getEmailSettings: selfServeSettings, + getEmailSettings, }, 'prj_1', 'acme.com', ); - expect(printed(warnSpy)).toContain('Re-run `void email domain add acme.com`'); - expect(printed(warnSpy)).toContain('adding again replaces the credential, rules stay'); + expect(notedBlocks()).toContain('Managed by: administrator'); + expect(printed(infoSpy)).toContain('void platform email domain-sync acme.com'); + expect(printed(infoSpy)).not.toContain('Run `void email domain sync'); + expect(getEmailSettings).toHaveBeenCalledWith('prj_1'); }); - it('prints the api error verbatim and the remaining human step', async () => { + it('names credential renewal and the project for an administrator-managed route', async () => { await emailDomainStatus( { getEmailDomain: vi.fn(async () => - statusRow({ - status: 'pending', - mode: 'subdomain', - domain: 'mail.acme.com', - error: 'probe text safe to print', - setup_state: { remaining_steps: ['routing_subdomain'] }, + domainRow({ + managed_by: 'admin', + readiness: { + inbound: { status: 'ready' }, + outbound: { status: 'blocked' }, + management: { status: 'revoked', reason: 'token revoked' }, + }, }), ), - getEmailSettings: selfServeSettings, - }, - 'prj_1', - 'mail.acme.com', - ); - expect(printed(errorSpy)).toContain('email: probe text safe to print'); - expect(printed(warnSpy)).toContain('Email Routing → acme.com → Settings → Subdomains'); - }); - - it('renders the catch-all state, and the sync hint only when it drifted', async () => { - await emailDomainStatus( - { - getEmailDomain: vi.fn(async () => statusRow({ catch_all: 'points_here' })), - getEmailSettings: selfServeSettings, + getEmailSettings: vi.fn(async () => ({ + domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, + })), }, 'prj_1', 'acme.com', ); - expect(notedBlocks()).toContain('Catch-all: points_here'); - expect(printed(infoSpy)).not.toContain('re-point it'); - - await emailDomainStatus( - { - getEmailDomain: vi.fn(async () => - statusRow({ catch_all: 'points_elsewhere', catch_all_drift: true }), - ), - getEmailSettings: selfServeSettings, - }, - 'prj_1', - 'acme.com', + expect(notedBlocks()).toContain('management revoked — token revoked'); + expect(printed(infoSpy)).toContain( + 'void platform email domain-add acme.com --project hr-portal', ); - expect(notedBlocks()).toContain('Catch-all: points_elsewhere'); - expect(printed(infoSpy)).toContain('run `void email domain sync acme.com` to re-point it'); }); - it('points administrator-managed setup and drift remediation at the administrator', async () => { - await emailDomainStatus( - { - getEmailDomain: vi.fn(async () => - statusRow({ - managed_by: 'admin', - status: 'pending', - mode: 'subdomain', - domain: 'mail.acme.com', - relay_drift: true, - catch_all: 'points_elsewhere', - catch_all_drift: true, - setup_state: { remaining_steps: ['routing_subdomain'] }, - }), - ), - getEmailSettings: selfServeSettings, - }, - 'prj_1', - 'mail.acme.com', - ); - - expect(printed(warnSpy)).toContain( - "One step for your administrator, in the platform's Cloudflare account", - ); - expect(printed(infoSpy)).toContain('void platform email domain-sync mail.acme.com'); - expect(printed(infoSpy)).not.toContain('void email domain sync'); - }); - - it.each([ - ['platform credential', 'platform' as const, false], - ['pasted API token', 'api_token' as const, true], - ])( - 'points failed administrator setup using a %s at domain-add', - async (_label, kind, tokenStdin) => { - const getEmailSettings = vi.fn(async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - })); - await emailDomainStatus( - { - getEmailDomain: vi.fn(async () => - statusRow({ - managed_by: 'admin', - credential_kind: kind, - status: 'failed', - relay_worker_name: null, - relay_version: null, - relay_drift: true, - catch_all_drift: true, - setup_state: { failed_step: 'zone_lookup' }, - }), - ), - getEmailSettings, - }, - 'prj_1', - 'acme.com', - ); - - const output = printed(warnSpy) + printed(infoSpy); - expect(output).toContain('void platform email domain-add acme.com --project hr-portal'); - expect(output.includes('--token-stdin')).toBe(tokenStdin); - expect(output).not.toContain('domain-sync'); - expect(getEmailSettings).toHaveBeenCalledTimes(1); - }, - ); - - it('points an expired administrator API token at platform domain-add with the project slug', async () => { - const getEmailSettings = vi.fn(async () => ({ - domains: { management: 'admin' as const, projectSlug: 'hr-portal' }, - })); + it('does not invite reconciliation of an operation with an unknown provider outcome', async () => { await emailDomainStatus( { getEmailDomain: vi.fn(async () => - statusRow({ - managed_by: 'admin', - credential_kind: 'api_token', - status: 'token_expired', - credential_status: 'expired', + domainRow({ + status: 'drifted', + operationId: 'eop_unknown', + operationStatus: 'unknown', + readiness: { + inbound: { status: 'drifted' }, + outbound: { status: 'verified_only' }, + management: { status: 'refresh_unknown' }, + }, }), ), - getEmailSettings, + getEmailSettings: vi.fn(selfServeSettings), }, 'prj_1', 'acme.com', ); - - expect(printed(warnSpy)).toContain( - 'void platform email domain-add acme.com --project hr-portal --token-stdin', - ); - expect(getEmailSettings).toHaveBeenCalledWith('prj_1'); + expect(printed(warnSpy)).toContain('eop_unknown'); + expect(printed(infoSpy)).not.toContain('domain sync'); }); }); describe('emailDomainList', () => { it('reports the empty state with the add hint', async () => { await emailDomainList({ listEmailDomains: vi.fn(async () => []) }, 'prj_1'); - expect(printed(infoSpy)).toContain('No email domains.'); expect(printed(infoSpy)).toContain('void email domain add '); }); - it('renders one line per domain with status and mode', async () => { + it('lists actual assignment status and management, without a retired mode column', async () => { await emailDomainList( { listEmailDomains: vi.fn(async () => [ - domainRow({ domain: 'acme.com', status: 'active', mode: 'apex' }), + domainRow(), domainRow({ id: 'edom_2', domain: 'mail.example.org', status: 'pending', - mode: 'subdomain', + managed_by: 'admin', }), ]), }, @@ -711,183 +615,175 @@ describe('emailDomainList', () => { ); const block = notedBlocks(); expect(block).toContain('acme.com'); + expect(block).toContain('ready'); expect(block).toContain('mail.example.org'); - expect(block).toContain('subdomain'); + expect(block).toContain('administrator'); + expect(block).not.toContain(' —'); }); }); describe('emailDomainSync', () => { - it('renders reconciliation without claiming automatic secret rotation', async () => { - const syncEmailDomain = vi.fn(async () => domainRow({ relay_version: 2 })); - await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); - expect(printed(successSpy)).not.toContain('rotated secret'); - expect(notedBlocks()).toContain('acme.com'); - expect(syncEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com'); - }); - - it('renders a failed sync with the failed step', async () => { + it('renders the current readiness and operation without claiming secret rotation', async () => { const syncEmailDomain = vi.fn(async () => - domainRow({ - status: 'failed', - relay_version: null, - setup_state: { failed_step: 'deploy_relay' }, - error: 'PUT script failed', - }), + domainRow({ operationId: 'eop_sync', operationStatus: 'completed' }), ); - await expect(emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com')).rejects.toThrow( - 'reconciliation', - ); - expect(printed(errorSpy)).toContain('failed at deploy relay'); - expect(printed(errorSpy)).toContain('PUT script failed'); - expect(printed(successSpy)).not.toContain('Relay redeployed'); - }); - - it('prints the catch-all outcome when the response carries one', async () => { - const syncEmailDomain = vi.fn(async () => ({ ...domainRow(), catch_all: 'ensured' as const })); - await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); - expect(printed(infoSpy)).toContain('Catch-all: ensured'); - expect(printed(warnSpy)).not.toContain('NOT overwritten'); - }); - - it('warns instead of claiming the catch-all when it points at a different worker', async () => { - const syncEmailDomain = vi.fn(async () => ({ - ...domainRow(), - catch_all: 'foreign_conflict' as const, - })); await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); - expect(printed(warnSpy)).toContain("the zone's catch-all points at a different worker"); - expect(printed(warnSpy)).toContain('not overwritten'); - expect(printed(infoSpy)).not.toContain('Catch-all:'); + expect(notedBlocks()).toContain('eop_sync · completed'); + expect(notedBlocks()).toContain('outbound verified_only'); + expect(printed(successSpy)).not.toContain('rotated secret'); }); - it('prints no catch-all line when the response omits it (a row with no zone_id)', async () => { - const syncEmailDomain = vi.fn(async () => domainRow()); - await emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com'); - expect(printed(infoSpy) + printed(warnSpy)).not.toContain('Catch-all'); - }); + it.each(['pending', 'running', 'blocked', 'unknown'] as const)( + 'exits unsuccessfully for a %s operation while retaining its ID', + async (operationStatus) => { + const syncEmailDomain = vi.fn(async () => + domainRow({ operationId: 'eop_sync', operationStatus, error: 'provider step unresolved' }), + ); + await expect(emailDomainSync({ syncEmailDomain }, 'prj_1', 'acme.com')).rejects.toThrow( + 'eop_sync', + ); + expect(printed(errorSpy)).toContain('provider step unresolved'); + }, + ); }); describe('emailDomainRemove', () => { - function removeClient(body: RemoveEmailDomainResponse): Pick< - PlatformClient, - 'removeEmailDomain' - > & { - removeEmailDomain: ReturnType; - } { + function removeClient(body: RemoveEmailDomainResponse) { return { removeEmailDomain: vi.fn(async () => body) }; } - it('renders a clean removal with no warnings', async () => { - const client = removeClient({ ok: true, removed: true }); - await emailDomainRemove(client, 'prj_1', 'acme.com'); - expect(client.removeEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com', undefined); - expect(printed(successSpy)).toContain( - 'Removed acme.com — the platform row, the stored credential and the relay secret are gone.', - ); - expect(printed(warnSpy)).toBe(''); - expect(printed(errorSpy)).toBe(''); - }); - - it('passes --force through to the api', async () => { - const client = removeClient({ ok: true, removed: true }); - await emailDomainRemove(client, 'prj_1', 'acme.com', { force: true }); - expect(client.removeEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com', true); - }); - - it('kept for retry: names the failed steps, points at retry and --force, exits 1', async () => { - const client = removeClient({ - ok: false, - removed: false, - failed_steps: ['catch_all', 'delete_relay'], - }); - const exit = exitSpy(); - await expect(emailDomainRemove(client, 'prj_1', 'acme.com', { exit })).rejects.toThrow( - 'exit 1', - ); - expect(printed(errorSpy)).toContain('failed Cloudflare-side steps: catch_all, delete_relay'); - expect(printed(infoSpy)).toContain('The registration was kept'); - expect(printed(infoSpy)).toContain('retry `void email domain remove acme.com`'); - expect(printed(infoSpy)).toContain('re-run with --force to drop the row anyway'); - expect(exit).toHaveBeenCalledWith(1); - }); - - it('forced: success plus a warning naming the failed steps and the manual cleanup', async () => { + it('reports completion and retained shared zone resources', async () => { const client = removeClient({ ok: true, removed: true, - forced: true, - failed_steps: ['delete_relay', 'catch_all'], + operationId: 'eop_remove', + operationStatus: 'completed', }); - await emailDomainRemove(client, 'prj_1', 'acme.com', { force: true }); - expect(printed(successSpy)).toContain('Removed acme.com'); - expect(printed(warnSpy)).toContain('delete_relay, catch_all'); - expect(printed(warnSpy)).toContain('delete the relay worker and reset the catch-all'); - expect(printed(warnSpy)).toContain("the zone's Email Routing settings"); - }); - - it('a grant-revoke failure alone is a one-line note, not a warning', async () => { - const client = removeClient({ ok: true, removed: true, failed_steps: ['revoke_grant'] }); await emailDomainRemove(client, 'prj_1', 'acme.com'); - expect(printed(successSpy)).toContain('Removed acme.com'); - expect(printed(infoSpy)).toContain('the Cloudflare grant could not be revoked'); - expect(printed(infoSpy)).toContain('no mail impact'); - expect(printed(warnSpy)).toBe(''); - }); + expect(client.removeEmailDomain).toHaveBeenCalledWith('prj_1', 'acme.com'); + expect(printed(infoSpy)).toContain('eop_remove · completed'); + expect(printed(successSpy)).toContain( + 'Zone resources still used by other domains were retained', + ); + }); + + it.each(['blocked', 'unknown', 'running'] as const)( + 'returns a nonzero result for %s cleanup and never claims removal', + async (operationStatus) => { + const client = removeClient({ + ok: false, + removed: false, + operationId: 'eop_remove', + operationStatus, + error: 'cleanup still recorded', + }); + const exit = exitSpy(); + await expect(emailDomainRemove(client, 'prj_1', 'acme.com', { exit })).rejects.toThrow( + 'exit 1', + ); + expect(printed(infoSpy)).toContain(`eop_remove · ${operationStatus}`); + expect(printed(errorSpy)).toContain('cleanup still recorded'); + expect(printed(successSpy)).toBe(''); + }, + ); }); describe('PlatformClient.removeEmailDomain', () => { - const apiUrl = 'https://api.test'; - let originalFetch: typeof globalThis.fetch | undefined; - - beforeEach(() => { - originalFetch = globalThis.fetch; - }); - - afterEach(() => { - if (originalFetch) { - globalThis.fetch = originalFetch; - } - }); - - it('DELETEs the domain URL, appending ?force=1 only when forced', async () => { + it('DELETEs only the exact domain path', async () => { const fetchMock = vi.fn( async (_input: RequestInfo | URL, _init?: RequestInit) => - new Response(JSON.stringify({ ok: true, removed: true }), { - status: 200, - headers: { 'content-type': 'application/json' }, - }), + new Response( + JSON.stringify({ + ok: true, + removed: true, + operationId: 'eop_remove', + operationStatus: 'completed', + }), + { status: 200, headers: { 'content-type': 'application/json' } }, + ), ); - globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch; - const client = new PlatformClient('tok', { apiUrl }); - + vi.stubGlobal('fetch', fetchMock); + const client = new PlatformClient('tok', { apiUrl: 'https://api.test' }); await client.removeEmailDomain('prj_1', 'acme.com'); - const [plainUrl, plainInit] = fetchMock.mock.calls[0]!; - expect(String(plainUrl)).toBe(`${apiUrl}/projects/prj_1/email/domains/acme.com`); - expect(plainInit?.method).toBe('DELETE'); - - await client.removeEmailDomain('prj_1', 'acme.com', true); - const [forceUrl, forceInit] = fetchMock.mock.calls[1]!; - expect(String(forceUrl)).toBe(`${apiUrl}/projects/prj_1/email/domains/acme.com?force=1`); - expect(forceInit?.method).toBe('DELETE'); + const [url, init] = fetchMock.mock.calls[0]!; + expect(String(url)).toBe('https://api.test/projects/prj_1/email/domains/acme.com'); + expect(init?.method).toBe('DELETE'); }); }); describe('emailDomainRotateSecret', () => { - it('prints completion only after the deployed generation is confirmed', async () => { + it('reports completion only after the deployed generation was verified', async () => { + const attemptId = '11111111-2222-4333-8444-555555555555'; + vi.spyOn(crypto, 'randomUUID').mockReturnValue(attemptId); const rotateEmailDomainSecret = vi.fn(async () => domainRow({ operationId: 'eop_rotate', operationStatus: 'completed' }), ); - await emailDomainRotateSecret({ rotateEmailDomainSecret }, 'prj_1', 'acme.com'); - expect(rotateEmailDomainSecret).toHaveBeenCalledWith('prj_1', 'acme.com'); + await emailDomainRotateSecret( + { rotateEmailDomainSecret, getEmailOperation: vi.fn() }, + 'prj_1', + 'acme.com', + ); + expect(rotateEmailDomainSecret).toHaveBeenCalledWith('prj_1', 'acme.com', attemptId); expect(printed(successSpy)).toContain('verified on the deployed Worker'); }); - it('surfaces an uncertain rotation instead of reporting success', async () => { + + it('reports an uncertain rotation without claiming success', async () => { const rotateEmailDomainSecret = vi.fn(async () => domainRow({ operationId: 'eop_rotate', operationStatus: 'unknown' }), ); await expect( - emailDomainRotateSecret({ rotateEmailDomainSecret }, 'prj_1', 'acme.com'), + emailDomainRotateSecret( + { rotateEmailDomainSecret, getEmailOperation: vi.fn() }, + 'prj_1', + 'acme.com', + ), ).rejects.toThrow('eop_rotate'); expect(printed(successSpy)).not.toContain('secret rotated'); }); + + it('recovers a lost response by the exact rotation key before reporting success', async () => { + const attemptId = '11111111-2222-4333-8444-555555555555'; + vi.spyOn(crypto, 'randomUUID').mockReturnValue(attemptId); + const rotateEmailDomainSecret = vi.fn(async () => { + throw new Error('connection reset'); + }); + const getEmailOperation = vi.fn(async () => ({ + operationId: 'eop_rotate', + attemptId, + status: 'completed' as const, + domain: 'acme.com', + readiness: domainRow().readiness, + })); + await emailDomainRotateSecret( + { rotateEmailDomainSecret, getEmailOperation }, + 'prj_1', + 'acme.com', + { sleep: vi.fn(async () => {}) }, + ); + expect(rotateEmailDomainSecret).toHaveBeenCalledWith('prj_1', 'acme.com', attemptId); + expect(getEmailOperation).toHaveBeenCalledWith('prj_1', attemptId); + expect(notedBlocks()).toContain('eop_rotate'); + expect(printed(successSpy)).toContain('verified on the deployed Worker'); + }); +}); + +describe('PlatformClient.rotateEmailDomainSecret', () => { + it('submits an idempotency key with the rotation request', async () => { + const fetchMock = vi.fn( + async (_input: RequestInfo | URL, _init?: RequestInit) => + new Response(JSON.stringify(domainRow()), { + status: 200, + headers: { 'content-type': 'application/json' }, + }), + ); + vi.stubGlobal('fetch', fetchMock); + const client = new PlatformClient('tok', { apiUrl: 'https://api.test' }); + await client.rotateEmailDomainSecret('prj_1', 'acme.com', 'attempt_1'); + const [url, init] = fetchMock.mock.calls[0]!; + expect(String(url)).toBe( + 'https://api.test/projects/prj_1/email/domains/acme.com/rotate-secret', + ); + expect(init?.method).toBe('POST'); + expect(JSON.parse(String(init?.body))).toEqual({ attemptId: 'attempt_1' }); + }); }); diff --git a/packages/void/test/unit/email-cli-logs.test.ts b/packages/void/test/unit/email-cli-logs.test.ts index 990c3a225..0d000848c 100644 --- a/packages/void/test/unit/email-cli-logs.test.ts +++ b/packages/void/test/unit/email-cli-logs.test.ts @@ -1,65 +1,70 @@ -import { log } from '@clack/prompts'; +import { log, note } from '@clack/prompts'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; import type { EmailLogsResponse, PlatformClient } from '../../src/cli/client.ts'; import { emailLogs } from '../../src/cli/email.ts'; -/** - * What `void email logs` prints while the api still answers - * `{ logs: [], pending: true }`. The one contract under test: the command - * never points a hosted-project user at Wrangler. The proxy's send/receive - * records are the PLATFORM worker's console output, which a project's own - * Cloudflare credentials cannot tail — so the only truthful pointer is the - * user's own worker log (`void project logs`), where the email handler's - * console output lands like any other invocation. - */ - function client(body: EmailLogsResponse): Pick { return { getEmailLogs: vi.fn(async () => body) }; } -type LogSpy = ReturnType; - -let infoSpy: LogSpy; +vi.mock('@clack/prompts', async (importOriginal) => { + const actual = await importOriginal(); + return { ...actual, note: vi.fn() }; +}); beforeEach(() => { - infoSpy = vi.spyOn(log, 'info').mockImplementation(() => {}); + vi.spyOn(log, 'info').mockImplementation(() => {}); + vi.mocked(note).mockClear(); }); afterEach(() => { vi.restoreAllMocks(); }); -function printed(spy: LogSpy): string { - return (spy.mock.calls as Array>).map((call) => String(call[0])).join('\n'); -} - describe('void email logs', () => { - it('prints the api note and points at `void project logs` while storage is pending', async () => { - const note = 'Persistent log storage lands when Analytics Engine queries are wired.'; - const c = client({ logs: [], pending: true, note }); - - await emailLogs(c, 'prj_1', 25); - - expect(c.getEmailLogs).toHaveBeenCalledWith('prj_1', 25); - const text = printed(infoSpy); - expect(text).toContain(note); - expect(text).toContain('Email activity logs are not available yet.'); - expect(text).toContain('`void project logs`'); + it('reports an empty project ledger', async () => { + const api = client({ logs: [] }); + await emailLogs(api, 'prj_1', 25); + expect(api.getEmailLogs).toHaveBeenCalledWith('prj_1', 25); + expect(log.info).toHaveBeenCalledWith('No email activity recorded.'); }); - it('never sends a hosted-project user to Wrangler', async () => { - // The proxy is Void's worker: `wrangler tail` under the user's own - // credentials cannot reach it, and the CLI policy forbids the pointer. - await emailLogs(client({ logs: [], pending: true }), 'prj_1'); - - const text = printed(infoSpy); - expect(text).not.toMatch(/wrangler/i); - expect(text).not.toContain('proxy worker'); - }); - - it('falls back to a generic pending line when the api sends no note', async () => { - await emailLogs(client({ logs: [], pending: true }), 'prj_1'); - - expect(printed(infoSpy)).toContain('Persistent log storage is not yet wired up.'); + it('renders sent and received ledger entries with recipient outcomes', async () => { + const api = client({ + logs: [ + { + timestamp: Date.parse('2026-09-19T00:00:00Z'), + direction: 'sent', + operationId: 'eact_1', + receiptId: null, + recipient: 'owner@example.com', + status: 'provider_accepted', + transport: 'send_raw', + providerReference: 'cf_1', + errorCode: null, + policyVersion: 1, + }, + { + timestamp: Date.parse('2026-09-18T23:00:00Z'), + direction: 'received', + operationId: 'ercpt_1', + receiptId: 'ercpt_1', + recipient: null, + status: 'actions_rejected', + transport: 'email_event', + providerReference: null, + errorCode: 'INVALID_ACTIONS', + policyVersion: null, + }, + ], + }); + await emailLogs(api, 'prj_1'); + const rendered = vi.mocked(note).mock.calls[0]?.[0]; + expect(rendered).toContain( + '2026-09-19T00:00:00.000Z → eact_1 owner@example.com provider_accepted', + ); + expect(rendered).toContain( + '2026-09-18T23:00:00.000Z ← ercpt_1 — actions_rejected (INVALID_ACTIONS)', + ); }); }); diff --git a/packages/void/test/unit/email-domain-args.test.ts b/packages/void/test/unit/email-domain-args.test.ts index 66d97bc9c..4a17526cf 100644 --- a/packages/void/test/unit/email-domain-args.test.ts +++ b/packages/void/test/unit/email-domain-args.test.ts @@ -111,37 +111,9 @@ describe('parseEmailArgs — domain group', () => { ); }); - it('parses --force on domain remove only', () => { - expect(parseEmailArgs(['domain', 'remove', 'acme.com', '--force'])).toMatchObject({ - domainVerb: 'remove', - domain: 'acme.com', - force: true, - }); - // Off by default, on every verb. - expect(parseEmailArgs(['domain', 'remove', 'acme.com'])).toMatchObject({ - domainVerb: 'remove', - force: undefined, - }); - for (const args of [ - ['domain', 'add', 'acme.com', '--force'], - ['domain', 'status', 'acme.com', '--force'], - ['domain', 'sync', 'acme.com', '--force'], - ['domain', 'list', '--force'], - ['usage', '--force'], - ['disallow', 'a@x.dev', '--force'], - ]) { - expect(() => parseEmailArgs(args)).toThrow( - 'email: --force applies to `void email domain remove` only.', - ); - } - }); - - it('rejects --force with a value or repeated', () => { - expect(() => parseEmailArgs(['domain', 'remove', 'acme.com', '--force=yes'])).toThrow( - 'email: --force takes no value.', - ); - expect(() => parseEmailArgs(['domain', 'remove', 'acme.com', '--force', '--force'])).toThrow( - 'email: --force can only be specified once.', + it('rejects the removed force option instead of silently ignoring it', () => { + expect(() => parseEmailArgs(['domain', 'remove', 'acme.com', '--force'])).toThrow( + /takes exactly one domain argument/, ); }); diff --git a/packages/void/test/unit/email-inbound.test.ts b/packages/void/test/unit/email-inbound.test.ts index ae8cdc837..d82ac53de 100644 --- a/packages/void/test/unit/email-inbound.test.ts +++ b/packages/void/test/unit/email-inbound.test.ts @@ -16,6 +16,7 @@ import { buildReplyMessage, createMessageProxy, defineEmail, + isForwardableEmailMessage, MAX_INBOUND_BYTES, MAX_INBOUND_HEADERS, parseEmail, @@ -650,10 +651,8 @@ describe('generated __emailHandler dispatch (behavioural)', () => { expect(seen).toEqual([{ ticket: 'T-42' }]); }); - it('runs a relayed (viaDomain) recipient in no-prefix mode even when a slug is passed', async () => { - // The relay lane of "Custom domains on Cloudflare" (design doc 0078): - // the platform router proves the domain's relay secret and sets - // `viaDomain`; the recipient carries no `+` prefix. A platform + it('runs a verified custom-domain recipient in no-prefix mode even when a slug is passed', async () => { + // A verified receipt carries `viaDomain` and no `+` prefix. A platform // deployment still injects `__VOID_PROJECT_SLUG`, and the generated // handleEmail suppresses it for this lane — and createMessageProxy // itself ignores a slug passed alongside viaDomain, so a slug equal to @@ -890,12 +889,16 @@ describe('generated __emailHandler dispatch (behavioural)', () => { }); describe('compileWorkerEntry (email)', () => { - it('adds email export and import when hasEmail is true', () => { + it('emits the native event gate and authenticated receipt path when hasEmail is true', () => { const code = compileWorkerEntry({ hasEmail: true }); expect(code).toContain(', __emailHandler'); + expect(code).toContain('async email(message)'); expect(code).toContain( - 'async email(envelope) { return handleEmail(envelope, this.env, this.ctx); }', + 'this.env.__VOID_EMAIL_DEPLOYMENT_ID || !__isForwardableEmailMessage(message)', ); + expect(code).not.toContain('async email(envelope)'); + expect(code).toContain('return __handleEmailReceipt(request, env, ctx)'); + expect(code).toContain('await __readEmailEnvelope(request.body)'); expect(code).toContain('async function handleEmail'); expect(code).toContain('from "void/_email-protocol"'); expect(code).not.toContain('from "@void/platform/email-protocol"'); @@ -910,9 +913,37 @@ describe('compileWorkerEntry (email)', () => { it('co-exists with queue export when both present', () => { const code = compileWorkerEntry({ hasQueues: true, hasEmail: true }); expect(code).toContain('async queue(batch) { return __voidQueue(batch, this.env, this.ctx); }'); - expect(code).toContain( - 'async email(envelope) { return handleEmail(envelope, this.env, this.ctx); }', + expect(code).toContain('async email(message)'); + }); + + it('rejects envelope RPC and managed calls but accepts a native email event', async () => { + const code = compileWorkerEntry({ hasEmail: true }); + const method = code.match(/ {2}async email\(message\) \{[\s\S]*?\n {2}\}/)?.[0]; + expect(method).toBeDefined(); + const handleEmail = vi.fn(async () => [{ type: 'reject', reason: 'test' }]); + // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func + const entryEmail = new Function( + '__isForwardableEmailMessage', + 'handleEmail', + `return ({${method}}).email;`, + )(isForwardableEmailMessage, handleEmail) as ( + this: { env: Record; ctx: object }, + message: unknown, + ) => Promise; + const envelope = { from: 'sender@example.com', to: 'app@example.com', raw: new Uint8Array() }; + await expect(entryEmail.call({ env: {}, ctx: {} }, envelope)).rejects.toThrow( + 'Native email event required', ); + expect(handleEmail).not.toHaveBeenCalled(); + + const native = { ...envelope, setReject() {}, async forward() {}, async reply() {} }; + await expect( + entryEmail.call({ env: { __VOID_EMAIL_DEPLOYMENT_ID: 'deploy_1' }, ctx: {} }, native), + ).rejects.toThrow('Native email event required'); + expect(handleEmail).not.toHaveBeenCalled(); + await expect(entryEmail.call({ env: {}, ctx: {} }, native)).resolves.toBeUndefined(); + expect(handleEmail).toHaveBeenCalledOnce(); + expect(handleEmail).toHaveBeenCalledWith(native, {}, {}); }); }); @@ -2820,15 +2851,9 @@ describe('buildReplyMessage', () => { }); // --------------------------------------------------------------------------- -// End-to-end: replicates what the worker entry codegen does at runtime. -// The codegen emits a `email(envelope)` method on a WorkerEntrypoint subclass -// that: -// 1. Builds a proxy via createMessageProxy(envelope) -// 2. Runs the dispatcher (which delegates to the matching user handler) -// 3. Returns getActions() to the platform router -// This test stitches the same pieces together and asserts the contract, -// without compiling and evaluating the actual generated code (which would -// need virtual:void-routes + cloudflare:workers). +// The verified receipt path builds a proxy, runs the matching handler, and +// encodes the recorded actions for the platform. This exercises those pieces +// without evaluating the generated Worker module. // --------------------------------------------------------------------------- describe('end-to-end: envelope → handler → action queue', () => { @@ -2868,7 +2893,7 @@ describe('end-to-end: envelope → handler → action queue', () => { return getActions(); } - it('records a setReject action and returns it as the RPC result', async () => { + it('records a setReject action for the receipt response', async () => { const handler = defineEmail(async (message) => { message.setReject('not allowed'); }); diff --git a/packages/void/test/unit/email-own-account.test.ts b/packages/void/test/unit/email-own-account.test.ts index 945ac37fe..5c5855682 100644 --- a/packages/void/test/unit/email-own-account.test.ts +++ b/packages/void/test/unit/email-own-account.test.ts @@ -673,7 +673,7 @@ describe('generated handleEmail on a native ForwardableEmailMessage', () => { expect((outcome as MimeError).message).toBe('forward: 33 headers, over the 32-header limit.'); }); - it('still returns the actions as data for a platform envelope, enacting nothing', async () => { + it('returns actions for an authenticated receipt envelope without native enaction', async () => { const handleEmail = buildHandleEmail(async (message) => { message.setReject('spam'); }); @@ -693,16 +693,15 @@ describe('generated handleEmail on a native ForwardableEmailMessage', () => { }); /** - * The relay lane (design doc 0078, "Custom domains on Cloudflare"): the - * envelope arrives over the platform router's `/email/relay` RPC with - * `viaDomain` set and a recipient that carries NO `+` prefix, while + * A verified custom-domain receipt carries `viaDomain` and a recipient + * without a `+` prefix, while * provisioning still injects `__VOID_PROJECT_SLUG` unconditionally. The * generated `handleEmail` must suppress the slug so the dispatcher runs in * no-prefix mode (Mode B item 4) — left applied, the strip would take * everything up to the first `+` and `support+T-42@acme.com` would dispatch * as `T-42` to `_default` or a wrong `[user]` param. */ -describe('generated handleEmail on a relayed envelope (viaDomain)', () => { +describe('generated handleEmail on a verified custom-domain receipt', () => { function relayEnvelope(to = 'support+T-42@acme.com') { return { from: 'sender@example.com', diff --git a/platform/meta/design-docs/0078-email-cf-native.md b/platform/meta/design-docs/0078-email-cf-native.md index 500ae05ea..fc551c0b4 100644 --- a/platform/meta/design-docs/0078-email-cf-native.md +++ b/platform/meta/design-docs/0078-email-cf-native.md @@ -358,10 +358,14 @@ Removal first commits the domain's disabled state, preventing new admission, the drains already admitted actions. Remove its assignment without modifying a sibling project's route. Retain tombstones and operation records until cleanup is resolved. Only the connection manager may remove the last connection: detach its catch-all -if it is still owned, then delete the ingress, then revoke an unreferenced grant. +if it is still owned, then delete the ingress and forget its stored credential. +Scoped API tokens are created by the user and may also be used elsewhere; the +user revokes an unused token in Cloudflare. Void does not require token-management +permissions or claim to revoke it remotely. Do not delete the Worker while an owned rule still targets it. Provider cleanup failure leaves a retryable cleanup operation, including after project teardown. -Force removal acknowledges orphaned resources; it cannot silently erase that record. +Removal never discards an unresolved cleanup record; its operation remains visible +until the provider resources have been reconciled. ## Bounded tenant execution @@ -496,8 +500,6 @@ publisher and scheduled repair publish the latest committed value. Missed or out-of-order cache updates may affect display freshness but not authorization. Do not claim a global 60-second security boundary: Cloudflare documents visibility delays of [60 seconds or more](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency). -Legacy senders relying on cached authorization must be drained before the new -policy guarantee is enabled. ## Observable delivery and retry semantics @@ -554,7 +556,7 @@ sequenceDiagram G->>P: Execute admitted attempts P-->>G: Accepted, refused or unknown G->>A: Persist outcomes - G-->>I: Receipt result with action summary + G-->>I: Receipt result and ID; action outcomes remain queryable Note over I,A: Handler completion and action delivery are distinct ``` diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 941ca2888..49fb46c6b 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -123,6 +123,12 @@ Customer connections deploy one ingress Worker in the customer's account and zon Deploy the outbound proxy, API, and gateway before enabling inbound routing. The gateway must expose the new bounded email protocol, and tenant apps with handlers must be rebuilt and redeployed with its deployment metadata. The proxy no longer accepts inbound `/email/relay` requests or native email events. +Development installations using the previous email implementation need explicit +cleanup before setup: inspect their old relay Workers and credentials, detach +only catch-all rules still targeting those Workers, delete the obsolete Workers, +and revoke unused test grants in Cloudflare. Preserve unrelated rules and MX +records. The new reconciler does not migrate old `email_domains` records. + Inspect all three readiness states and the operation ID with `void email domain status `. Use `sync` to reconcile recoverable steps and `rotate-secret` for explicit ingress-secret rotation. An uncertain provider write remains blocked until its outcome can be proved; neither a timeout nor a missing cache entry authorizes another write. Never erase the operation to force a retry. PostgreSQL is authoritative for consent, policy, suspension, and recipient-attempt quotas. Cache publication retries independently. `void email logs` exposes receipt and action metadata: provider acceptance is not proof of delivery, and an unknown result must not be retried with a new idempotency key. Removing one domain or project must preserve sibling routes and unresolved cleanup records. diff --git a/platform/packages/api/src/admin/routes/email.tsx b/platform/packages/api/src/admin/routes/email.tsx index 24a1c1a15..27ecde81e 100644 --- a/platform/packages/api/src/admin/routes/email.tsx +++ b/platform/packages/api/src/admin/routes/email.tsx @@ -1,4 +1,4 @@ -import { asc, eq, gte, inArray, sql } from 'drizzle-orm'; +import { asc, desc, eq, gte, inArray, sql } from 'drizzle-orm'; import { Hono, type Context } from 'hono'; import { getPlatformCapabilities } from '../../capabilities.ts'; import { @@ -15,8 +15,8 @@ import { import { setProjectEmailLimits, setProjectEmailSuspended } from '../../email/admission.ts'; import { emailDomainRoutes, + emailOperations, emailZoneConnections, - emailCredentials, } from '../../email/connection-schema.ts'; import { addEmailDomainForProject, @@ -26,10 +26,7 @@ import { import { DEFAULT_EMAIL_BURST_LIMIT as DEFAULT_BURST_LIMIT, DEFAULT_EMAIL_MONTHLY_LIMIT as DEFAULT_MONTHLY_LIMIT, - emailBurstLimitKey as burstLimitKey, - emailMonthlyLimitKey as monthlyLimitKey, - emailSuspendKey as suspendKey, - parseEmailLimit as parseLimit, + parseEmailLimitInput, } from '../../email/limits.ts'; import { getEmailDomainManagement, @@ -40,10 +37,6 @@ import type { ApiEnv } from '../../env.ts'; import { executeAuditedMutation, operatorAuditIntent } from '../../operator/audit.ts'; import { OperatorError } from '../../operator/common.ts'; import { setOperatorEmailPolicy, setOperatorEmailSettings } from '../../operator/email-routes.ts'; -import { - syncProjectAllowlistKv, - syncProjectAllowlistKvBestEffort, -} from '../../provisioning/email-allowlist.ts'; import { deleteDestination } from '../../provisioning/email-routing.ts'; import { renderOperationError } from '../operation-error.tsx'; import { EmailSettingsPage } from '../views/email-settings.tsx'; @@ -62,22 +55,7 @@ app.use('*', async (context, next) => { await next(); }); -/** - * Email control plane for operators: installation-wide settings at `/`, - * one project's usage, caps, kill switch, destinations and domains at - * `/:projectId`. - * - * Every number on the project page is read straight out of `ROUTING` KV, - * which is where the proxy worker (`packages/proxy/src/email.ts`) keeps the - * counters and reads the caps from. The keys and defaults come from - * `email/limits.ts`, the one spelling the api's writers share with the - * proxy's readers — nothing at build time catches a drift. - * - * The destination and custom-domain rows are Postgres. The proxy's only - * view of a custom domain is the `email-domain:` ROUTING mirror, so the - * revoke below clears that key before the row. - */ -const sentKey = (projectId: string, month: string) => `email-sent:${projectId}:${month}`; +/** Operator email settings and project usage from the email ledger. */ const recvKey = (projectId: string, month: string) => `email-recv:${projectId}:${month}`; /** The admin layout has no utility classes, so secondary text is inline. */ @@ -170,37 +148,57 @@ app.get('/:projectId', async (context) => { .select({ route: emailDomainRoutes, connection: emailZoneConnections, - credential: emailCredentials, }) .from(emailDomainRoutes) .innerJoin(emailZoneConnections, eq(emailDomainRoutes.connection_id, emailZoneConnections.id)) - .leftJoin(emailCredentials, eq(emailZoneConnections.credential_id, emailCredentials.id)) .where(eq(emailDomainRoutes.project_id, projectId)) .orderBy(asc(emailDomainRoutes.created_at)), ]); const sent = sentRows[0]?.count ?? 0; const received = receivedRows[0]?.count ?? 0; + const latestOperations = domainRows.length + ? await context + .get('db') + .select({ + id: emailOperations.id, + routeId: emailOperations.route_id, + connectionId: emailOperations.connection_id, + status: emailOperations.status, + }) + .from(emailOperations) + .where( + inArray( + emailOperations.connection_id, + domainRows.map(({ connection }) => connection.id), + ), + ) + .orderBy(desc(emailOperations.created_at)) + : []; - // Distinguish an override from the default so an operator can see at a - // glance whether someone bumped a cap during a past incident — the - // override keys are write-only otherwise. + // Distinguish an override from the default in the project controls row. const control = controls[0]; const monthlyLimit = control && control.monthly_limit !== DEFAULT_MONTHLY_LIMIT ? control.monthly_limit : undefined; const burstLimit = control && control.burst_limit !== DEFAULT_BURST_LIMIT ? control.burst_limit : undefined; const isSuspended = Boolean(control?.suspended_at); - const domains = domainRows.map(({ route, connection, credential }) => ({ + const domains = domainRows.map(({ route, connection }) => ({ id: route.id, domain: route.domain, - status: route.inbound_status, + inbound: route.inbound_status, + inboundReason: route.inbound_reason, + outbound: route.outbound_status, + outboundReason: route.outbound_reason, + management: connection.management_status, + managementReason: connection.management_reason, managed_by: route.managed_by, - credential_kind: credential?.kind ?? 'platform', - mode: route.addressing, relay_worker_name: connection.ingress_worker_name, relay_version: connection.ingress_version, - token_id: credential?.token_id ?? null, - token_expires_on: credential?.expires_on ?? null, + operation: latestOperations.find( + (operation) => + operation.routeId === route.id || + (operation.routeId === null && operation.connectionId === connection.id), + ), })); const senderDomain = context.env.EMAIL_SENDER_DOMAIN; const tz = (context.req.raw.cf?.timezone as string | undefined) ?? undefined; @@ -392,13 +390,13 @@ app.get('/:projectId', async (context) => { Domain - Status + Inbound + Outbound + Management Managed by - Mode - Relay worker + Ingress worker v - Token ID - Token expires + Latest operation @@ -407,18 +405,34 @@ app.get('/:projectId', async (context) => { {domain.domain} - {domain.status} + + {domain.inbound} + + {domain.inboundReason && — {domain.inboundReason}} + + + + {domain.outbound} + + {domain.outboundReason && — {domain.outboundReason}} - {domain.managed_by} - {domain.credential_kind === 'platform' ? ' (platform credential)' : ''} + + {domain.management} + + {domain.managementReason && — {domain.managementReason}} - {domain.mode ?? '-'} + {domain.managed_by} {domain.relay_worker_name ?? '-'} {domain.relay_version ?? '-'} - {domain.token_id ?? '-'} - {domain.token_expires_on ? formatDateTime(domain.token_expires_on, tz) : '-'} + {domain.operation ? ( + <> + {domain.operation.id} ({domain.operation.status}) + + ) : ( + '-' + )}
{ if (!destination) { return context.html('

Destination not found

', 404); } - // Tighten the KV mirror BEFORE anything destructive runs. Same inversion as - // the user-facing revoke in `routes/email.ts`: the row is what a retry - // re-derives the mirror from, so deleting it first leaves a failed KV write - // with nothing to repair from and the revoked address keeps receiving mail. - // The sync must EXCLUDE this row — it is still `verified` in Postgres here, - // so a plain re-sync would write the address straight back. - if (destination.status === 'verified') { - try { - await syncProjectAllowlistKv(context.get('db'), context.env.ROUTING, projectId, { - excludeDestinationId: destination.id, - }); - } catch (error) { - console.error('[admin-email] allowlist tighten failed; keeping destination row', { - projectId, - destinationId, - error, - }); - return context.html('

Failed to update send allowlist. Try again.

', 503); - } - } - + await deleteEmailDestination(context.get('db'), destination.id); // The Cloudflare destination address is account-level, so deleting it would // revoke the address for every project that shares it. Only the last // referencing project may remove it upstream. @@ -594,7 +588,7 @@ app.post('/:projectId/destinations/:destId/delete', async (context) => { context.get('db'), destination.cf_destination_id, ); - if (references <= 1) { + if (references === 0) { try { await deleteDestination( context.env.CF_ACCOUNT_ID, @@ -602,9 +596,7 @@ app.post('/:projectId/destinations/:destId/delete', async (context) => { destination.cf_destination_id, ); } catch (error) { - // Best effort: a stranded CF address is inert (the per-project - // allowlist below is what the proxy enforces), and failing the - // operator's revoke on it would leave the row in place instead. + // Best effort: the committed SQL revocation already denies sends. console.error('[admin-email] CF deleteDestination failed', { projectId, destinationId, @@ -613,11 +605,6 @@ app.post('/:projectId/destinations/:destId/delete', async (context) => { } } } - await deleteEmailDestination(context.get('db'), destination.id); - // Re-derive after the delete: the tighten above works from a snapshot that - // a concurrent confirm click can make stale. Same shape and same reasoning - // as the owner-facing revoke in `routes/email.ts`. - await syncProjectAllowlistKvBestEffort(context.get('db'), context.env.ROUTING, projectId); return context.redirect(`/admin/email/${projectId}`); }); @@ -637,12 +624,32 @@ app.post('/:projectId/domains/:domain/revoke', async (context) => { context, project, context.req.param('domain'), - false, 'admin', ); if (!result.ok) { return context.html('

Email domain removal failed

', result.status as 400); } + const outcome = (await result.json()) as { + operationId?: string; + operationStatus?: string; + error?: string; + }; + if (outcome.operationStatus !== 'completed') { + return context.html( + +

Email domain removal {outcome.operationStatus ?? 'pending'}

+

+ {outcome.error ?? + 'The operation has not completed. Check the domain status before retrying.'} +

+

+ Operation ID: {outcome.operationId ?? 'unavailable'} +

+ Back to email settings +
, + outcome.operationStatus === 'blocked' || outcome.operationStatus === 'unknown' ? 409 : 202, + ); + } return context.redirect(`/admin/email/${projectId}`); }); @@ -661,13 +668,33 @@ app.post('/:projectId/domains/:domain/rotate-secret', async (context) => { if (!result.ok) { return context.html('

Email ingress rotation failed

', result.status as 400); } + const outcome = (await result.json()) as { + operationId?: string; + operationStatus?: string; + error?: string; + }; + if (outcome.operationStatus !== 'completed') { + return context.html( + +

Email ingress rotation {outcome.operationStatus ?? 'pending'}

+

+ {outcome.error ?? + 'The operation has not completed. Check the domain status before retrying.'} +

+

+ Operation ID: {outcome.operationId ?? 'unavailable'} +

+ Back to email settings +
, + outcome.operationStatus === 'blocked' || outcome.operationStatus === 'unknown' ? 409 : 202, + ); + } return context.redirect(`/admin/email/${projectId}`); }); /** - * Shared body of the two limit forms. A blank submission deletes the override - * key, which is how an operator hands a project back to the platform default - * after an incident — the proxy falls back to its own default on a missing key. + * Shared body of the two limit forms. A blank submission clears the SQL + * override so the project uses the platform default. */ async function setLimit( context: Context, @@ -686,7 +713,7 @@ async function setLimit( await setProjectEmailLimits(context.get('db'), projectId, { [kind]: null }); return context.redirect(`/admin/email/${projectId}`); } - const limit = parseLimit(raw); + const limit = parseEmailLimitInput(raw); if (limit === undefined) { return context.html('

Invalid limit

Expected a positive integer, or blank.

', 400); } @@ -694,29 +721,21 @@ async function setLimit( return context.redirect(`/admin/email/${projectId}`); } -/** Domain rows reuse the shared status palette: active reads as success, anything dead as failed. */ +/** Domain readiness uses the shared status palette. */ function domainStatusColor(status: string): string { - if (status === 'active') { + if (status === 'ready' || status === 'healthy') { return STATUS_COLORS.success; } - if (status === 'pending') { + if (status === 'pending' || status === 'verified_only' || status === 'probe_failed') { return STATUS_COLORS.pending; } return STATUS_COLORS.failed; } -/** UTC `YYYY-MM`, matching `monthBucket` in `packages/proxy/src/email.ts`. */ +/** UTC `YYYY-MM` for the current usage window. */ function monthBucket(): string { const now = new Date(); return `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`; } -function parseCounter(raw: string | null): number { - if (!raw) { - return 0; - } - const n = parseInt(raw, 10); - return Number.isFinite(n) && n >= 0 ? n : 0; -} - export default app; diff --git a/platform/packages/api/src/auth/identities.ts b/platform/packages/api/src/auth/identities.ts index ea51bab10..226b6fd11 100644 --- a/platform/packages/api/src/auth/identities.ts +++ b/platform/packages/api/src/auth/identities.ts @@ -214,7 +214,6 @@ export async function resolvePlatformLogin( ) { await updateUserRevokingInheritedDestinations( db, - env.ROUTING, result.user.id, identity.login, result.user.email, diff --git a/platform/packages/api/src/auth/profile.ts b/platform/packages/api/src/auth/profile.ts index 2edbbd27d..e0c452979 100644 --- a/platform/packages/api/src/auth/profile.ts +++ b/platform/packages/api/src/auth/profile.ts @@ -1,150 +1,29 @@ import { updateUser, revokeOwnerVerifiedDestinationsForUserChange, type Db } from '../db.ts'; import { lockEmailPolicy } from '../email/admission.ts'; -import { - syncProjectAllowlistKv, - syncProjectAllowlistKvBestEffort, -} from '../provisioning/email-allowlist.ts'; /** - * A mirror tighten inside `updateUserRevokingInheritedDestinations` failed. - * Thrown from inside the transaction so drizzle rolls it back, then caught - * by name outside it so the sign-in can go on; any other error from the same - * transaction keeps propagating. - */ -class AllowlistTightenError extends Error { - constructor( - readonly projectId: string, - cause: unknown, - ) { - super(`allowlist tighten failed for project=${projectId}`, { cause }); - this.name = 'AllowlistTightenError'; - } -} - -/** - * Write the provider's current login/email back to `users`, and when the - * email actually changed, retire the owner-inherited destinations that the - * OLD address was granted. - * - * This runs on EVERY login for the user's primary provider and writes back - * whatever the provider currently reports, so `users.email` is a mutable - * field, not a signup-time constant. Two places mint destination rows that - * are verified purely on "this address IS the project owner's" — the - * Option C owner branch in `routes/email.ts` and `autoAddOwnerDestination` in - * `routes/projects.ts`. Once the owner's address changes, that claim is stale: - * the old mailbox may have been handed to someone else, while the row stays - * `verified` and stays in the project's `email-allowlist:` mirror, - * which is the ONLY per-project send boundary the proxy enforces. So demote - * those rows and re-derive each affected project's mirror from the remaining - * verified rows. - * - * The email write, the demotion and the mirror tighten commit TOGETHER, in - * that order, with the tighten INSIDE the transaction. The only retry this - * path has is the next login, and it retries only while the stored address - * still differs from the provider's — so anything committed ahead of a - * failed step is permanent. A demotion that fails after `users.email` is - * committed is never retried (every later login compares equal); a mirror - * write that fails after the demotion is committed is never retried either, - * and nothing else re-derives the key on its own: the listing repairs a - * differing mirror (`projectAllowlistKvDiffers`) only when the owner lists, - * and until then the proxy keeps authorizing the old address from the stale - * key. Tightening BEFORE the commit inverts that: a lost write rolls the - * whole change back, `users.email` still reads the old address, and the next - * login retries the (idempotent, old-snapshot-keyed) demotion and the - * tighten. The mirror can then only ever be AHEAD of Postgres in the - * tightening direction — a rolled-back login leaves the key without the old - * address next to rows still `verified` — which the proxy reads as deny and - * the listing re-widens to match the rows. `activate-domain.ts` and the - * rollback route write routing KV under their project lock the same way; the - * deploy go-live path writes routing only AFTER its commit because there a - * write ahead of the row would widen. The tighten reads the verified rows - * through the transaction so it sees the uncommitted demotion; a pool read - * would write the old address straight back. - * - * Interleavings. `L` is this transaction. `I` is an owner-audited Option C - * write (`tryCreateEmailDestination`, `promoteEmailDestinationWithOwnerAudit`): - * it locks the owner's `users` row `FOR SHARE`, so it waits on the - * `FOR NO KEY UPDATE` the email write takes. `G` is a listing repair or a - * confirm click: no lock, best-effort re-derive. - * - * I commits before L locks L demotes I's row; L's tighten (transaction - * view) excludes it. I's own post-commit widen - * can still land after L's — the residual. - * I waits, L commits I re-reads the rotated address, writes nothing. - * I waits, L rolls back I re-reads the unchanged address and writes a - * `verified` row keyed on it; the next login - * demotes that one too. - * G derives between L's G sees a tight key next to still-`verified` - * tighten and L's commit rows and writes the old address back; the - * best-effort re-derive after the commit undoes - * it, as the DELETE route re-derives after its - * row delete. - * two logins, same change The second waits on the row lock, demotes - * nothing, tightens to the same value. - * - * Residual, shared with the DELETE route: KV has no compare-and-swap, so a - * writer that derived its mirror while the row was still `verified` can land - * its put after BOTH of L's, and that grant lasts until the project's next - * mirror write. Serializing the mirror writers is the project-level lock - * class from design doc 0067, deliberately not taken here. - * - * A failure of the email write or the demotion surfaces as a failed sign-in, - * exactly as a failure of the plain `updateUser` write always has. A failed - * tighten (its row read or its KV write) does not: nothing is committed, the - * sign-in proceeds on the stored address, and the retry is the next login — - * failing an OAuth callback over a KV blip would buy nothing the rollback - * has not already bought. + * Refresh the primary provider's profile and revoke consent inherited from + * the owner's previous address when that address changes. Admission reads + * these SQL rows under the same policy lock, so the profile update and + * revocation must commit together. */ export async function updateUserRevokingInheritedDestinations( db: Db, - kv: KVNamespace, userId: string, login: string, previousEmail: string | null, nextEmail: string | null, ): Promise { - // Only a real address-to-address change revokes. A first-ever email (no - // previous) grants nothing to revoke, and a provider that stops reporting - // one is a data gap, not a reassignment. + // A missing address is a data gap, not evidence of reassignment. if (!previousEmail || !nextEmail || previousEmail.toLowerCase() === nextEmail.toLowerCase()) { await updateUser(db, userId, login, nextEmail); return; } - let projectIds: Array; - try { - projectIds = await db.transaction(async (tx) => { - await lockEmailPolicy(tx); - const txDb = tx as unknown as Db; - await updateUser(txDb, userId, login, nextEmail); - const affected = await revokeOwnerVerifiedDestinationsForUserChange( - txDb, - userId, - previousEmail, - ); - for (const projectId of affected) { - try { - await syncProjectAllowlistKv(txDb, kv, projectId); - } catch (err) { - throw new AllowlistTightenError(projectId, err); - } - } - return affected; - }); - } catch (err) { - if (!(err instanceof AllowlistTightenError)) { - throw err; - } - console.error( - `[auth] allowlist tighten failed for project=${err.projectId}; keeping the stored email for user=${userId} so the next login retries:`, - err.cause, - ); - return; - } - // Undo a re-widen by a listing or confirm click that derived its mirror - // between the tighten and the commit (see the table above). Best-effort: - // the tighten already committed the boundary, so there is nothing left for - // a failure here to strand. - for (const projectId of projectIds) { - await syncProjectAllowlistKvBestEffort(db, kv, projectId); - } + + await db.transaction(async (tx) => { + await lockEmailPolicy(tx); + const txDb = tx as unknown as Db; + await updateUser(txDb, userId, login, nextEmail); + await revokeOwnerVerifiedDestinationsForUserChange(txDb, userId, previousEmail); + }); } diff --git a/platform/packages/api/src/db.ts b/platform/packages/api/src/db.ts index d8cec75f6..2ccf79e72 100644 --- a/platform/packages/api/src/db.ts +++ b/platform/packages/api/src/db.ts @@ -408,38 +408,9 @@ export async function countUserDeploymentsToday(db: Db, userId: string): Promise // --- Projects --- -export async function createProject( - db: Db, - userId: string, - slug: string, - routing?: KVNamespace, -): Promise { +export async function createProject(db: Db, userId: string, slug: string): Promise { const id = generateId('proj'); const [row] = await db.insert(projects).values({ id, user_id: userId, slug }).returning(); - // Mirror projectId -> slug into KV so the email proxy can validate that - // outbound `from` addresses belong to the calling project (the - // account-level send_email binding has no per-project constraint, so - // this mapping is the only thing preventing cross-project sender - // spoofing). Slug is immutable today — written once at create-time. - // - // INVARIANT: project slugs are immutable. If a slug-rename feature - // ever ships, every code path that mutates `projects.slug` MUST also - // (1) update `email-slug:` in ROUTING KV (this key), AND - // (2) validate no `+...` send is in flight before the - // rename completes (otherwise an in-flight outbound POST could - // slip through with the old slug, then the proxy maps it back - // and the new owner of that slug appears to send mail). - // TODO: revisit if/when project rename ships. - if (routing) { - try { - await routing.put(`email-slug:${id}`, slug); - } catch (err) { - // Don't fail project creation on a transient KV blip. The proxy - // will refuse sends with `project slug unknown` until this - // converges, and the hourly cron backfill re-writes the mirror. - console.error(`[createProject] failed to write email-slug:${id}:`, err); - } - } return row; } @@ -1804,25 +1775,17 @@ export async function createEmailDestination( * also clear the audit columns so the row no longer claims to be * owner-verified by a stale identity. * - * Returns the list of distinct project ids whose rows were touched, so - * the caller can sync each project's allowlist KV (verified rows we - * just demoted must drop out of `email-allowlist:` so the - * proxy stops accepting sends to them). - * * Called from the OAuth callback in `routes/auth.ts`, which re-reads the * provider's current email on every login and writes it straight back * via `updateUser` — so the stored address really does change under us. - * The caller runs this in the SAME transaction as that `updateUser`, and - * tightens each returned project's mirror inside it too, before the commit: - * the change is detected by comparing the stored address with the - * provider's, so a demotion — or a mirror write — committed separately and - * then lost would never be retried. + * The caller runs this in the same transaction as `updateUser` so consent + * and the owner's current address change together. */ export async function revokeOwnerVerifiedDestinationsForUserChange( db: Db, userId: string, oldEmail: string, -): Promise> { +): Promise { const lowered = oldEmail.toLowerCase(); // The caller holds the policy lock in its surrounding profile transaction. // Lock affected projects before changing consent so admission cannot read @@ -1844,7 +1807,7 @@ export async function revokeOwnerVerifiedDestinationsForUserChange( .where(eq(projects.id, projectId)) .for('update'); } - const updated = await db + await db .update(emailDestinations) .set({ status: 'pending', @@ -1857,8 +1820,7 @@ export async function revokeOwnerVerifiedDestinationsForUserChange( // against CF's account-level list — and nothing deleted the address // on CF's side, so CF still reports it verified. A row left as 'cf' // therefore drops straight back into that filter and the very next - // `void email destinations` re-promotes it to 'verified' and - // re-mirrors the address into `email-allowlist:`, undoing + // `void email destinations` re-promotes it to 'verified', undoing // this revoke entirely. 'platform' is also the correct state on the // merits: the account-level CF flag is exactly the consent we just // decided we can no longer inherit, so the only thing that may @@ -1876,9 +1838,7 @@ export async function revokeOwnerVerifiedDestinationsForUserChange( sql`lower(${emailDestinations.verified_by_email_snapshot}) = ${lowered}`, eq(emailDestinations.verification_source, 'cf'), ), - ) - .returning({ project_id: emailDestinations.project_id }); - return Array.from(new Set(updated.map((r) => r.project_id))); + ); } export async function getEmailDestinationsByProjectId( diff --git a/platform/packages/api/src/email/admission.ts b/platform/packages/api/src/email/admission.ts index 4d1171156..68a9d0675 100644 --- a/platform/packages/api/src/email/admission.ts +++ b/platform/packages/api/src/email/admission.ts @@ -360,6 +360,8 @@ export async function admitEmailAction( errorCode = 'SUSPENDED'; } else if (!senderAllowed) { errorCode = 'INVALID_FROM'; + } else if (input.kind === 'forward' && input.transport === 'send_raw') { + errorCode = 'UNSUPPORTED_ACTION'; } else if (!allowed) { errorCode = 'UNVERIFIED_DESTINATION'; } else if (burstUsed >= controls.burst_limit || monthUsed >= controls.monthly_limit) { @@ -779,7 +781,8 @@ export async function claimRelayedEmailReceipt( ) { throw new EmailAdmissionError('CONFLICT', 'relay invocation content conflict'); } - return existing.status === 'delivery_completed' && existing.final_reject !== null + return (existing.status === 'delivery_completed' || existing.status === 'actions_rejected') && + existing.final_reject !== null ? { state: 'completed', reject: existing.final_reject } : { state: 'in_progress' }; }); @@ -802,18 +805,21 @@ export async function completeRelayedEmailReceipt( ) { throw new EmailAdmissionError('CONFLICT', 'relay receipt mismatch'); } - if (existing.status === 'delivery_completed') { + if (existing.final_reject !== null) { if (existing.final_reject !== input.reject) { throw new EmailAdmissionError('CONFLICT', 'relay outcome conflict'); } return; } - if (existing.status !== 'handler_completed') { + if (existing.status !== 'handler_completed' && existing.status !== 'actions_rejected') { throw new EmailAdmissionError('INVALID_STATE', 'relay handler has not completed'); } await tx .update(emailReceipts) - .set({ status: 'delivery_completed', final_reject: input.reject }) + .set({ + status: existing.status === 'actions_rejected' ? 'actions_rejected' : 'delivery_completed', + final_reject: input.reject, + }) .where(eq(emailReceipts.id, input.receiptId)); }); } @@ -890,7 +896,7 @@ export async function getProjectEmailLogs(db: Db, projectId: string, limit = 50) status: receipt.status, transport: 'email_event', providerReference: null, - errorCode: null, + errorCode: receipt.status === 'actions_rejected' ? 'INVALID_ACTIONS' : null, policyVersion: null, })), ] diff --git a/platform/packages/api/src/email/cf-customer.ts b/platform/packages/api/src/email/cf-customer.ts index 53a89a195..4c47c0f2c 100644 --- a/platform/packages/api/src/email/cf-customer.ts +++ b/platform/packages/api/src/email/cf-customer.ts @@ -1,21 +1,4 @@ -/** - * Customer-Cloudflare API client — the calls the api makes INTO the - * customer's own Cloudflare account/zone with the credential they granted - * (an OAuth grant's refreshed access token, or a pasted API token on the - * fallback path). Design doc 0078, "Custom domains on Cloudflare". - * - * Follows cfFetch (../provisioning/cloudflare-api.ts): Bearer auth, the v4 - * `{ success, errors, result }` envelope, and CloudflareApiError carrying - * the HTTP status so callers branch on the wire code. Two deviations: - * - A FormData body (the relay script upload) must not carry a hand-set - * Content-Type — fetch fills in the multipart boundary, same handling - * as the WfP upload in routes/deploy.ts. - * - relayScriptExists reads the raw script GET, which answers the worker - * source or a bare 404 — not a v4 envelope. - * - * The credential is only ever sent as the Authorization header. It is - * never logged, embedded in an error message, or returned. - */ +/** Customer Cloudflare API client for email routing and sending. */ import { CloudflareApiError } from '../provisioning/cloudflare-api.ts'; import { @@ -28,12 +11,6 @@ import { export const CF_CUSTOMER_API_BASE = 'https://api.cloudflare.com/client/v4'; -// wrangler's public PKCE OAuth client (design doc 0078, "The OAuth grant -// on wrangler's client") — the refresh chain the api owns per domain row. -export const CF_EMAIL_OAUTH_CLIENT_ID = '54d11594-84e4-41aa-b438-e81b8fa78ee7'; -const CF_OAUTH_TOKEN_URL = 'https://dash.cloudflare.com/oauth2/token'; -const CF_OAUTH_REVOKE_URL = 'https://dash.cloudflare.com/oauth2/revoke'; - type CfCustomerResult = Readonly<{ success: boolean; errors: ReadonlyArray<{ code: number; message: string }>; @@ -51,6 +28,7 @@ export async function cfCustomerFetch( ): Promise { const response = await fetch(url, { ...init, + signal: init?.signal ?? AbortSignal.timeout(15_000), headers: { Authorization: `Bearer ${credential}`, ...(init?.body instanceof FormData ? {} : { 'Content-Type': 'application/json' }), @@ -85,13 +63,10 @@ export type RelayScriptUpload = Readonly<{ /** Module-syntax worker source (RELAY_SOURCE). */ source: string; compatibilityDate: string; - gatewayOrigin?: string; - accountId?: string; - zoneId?: string; - ingressName?: string; - /** Pre-release call sites still pass these while migration is in progress. */ - proxyOrigin?: string; - emailDomain?: string; + gatewayOrigin: string; + accountId: string; + zoneId: string; + ingressName: string; }>; export type SendRawMessage = Readonly<{ @@ -247,7 +222,7 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { relayScriptExists: async (accountId, scriptName) => { const response = await fetch( `${CF_CUSTOMER_API_BASE}/accounts/${accountId}/workers/scripts/${scriptName}`, - { headers: { Authorization: `Bearer ${credential}` } }, + { headers: { Authorization: `Bearer ${credential}` }, signal: AbortSignal.timeout(15_000) }, ); if (response.status === 404) { return false; @@ -272,14 +247,14 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { { type: 'plain_text', name: RELAY_GATEWAY_ORIGIN_BINDING, - text: upload.gatewayOrigin ?? upload.proxyOrigin, + text: upload.gatewayOrigin, }, - { type: 'plain_text', name: RELAY_ACCOUNT_BINDING, text: upload.accountId ?? accountId }, - { type: 'plain_text', name: RELAY_ZONE_BINDING, text: upload.zoneId ?? '' }, + { type: 'plain_text', name: RELAY_ACCOUNT_BINDING, text: upload.accountId }, + { type: 'plain_text', name: RELAY_ZONE_BINDING, text: upload.zoneId }, { type: 'plain_text', name: RELAY_INGRESS_BINDING, - text: upload.ingressName ?? scriptName, + text: upload.ingressName, }, ], }; @@ -438,106 +413,3 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { }), }; } - -/** - * OAuth token-endpoint failure. `code` is the RFC 6749 error string - * ('invalid_grant' & co) — the only piece callers branch on. The message - * deliberately carries just the code and HTTP status: never the - * description, never any token material. - */ -export class OAuthGrantError extends Error { - readonly code: string; - readonly status: number; - constructor(code: string, status: number) { - super(`Cloudflare OAuth grant failed: ${code} (HTTP ${status})`); - this.name = 'OAuthGrantError'; - this.code = code; - this.status = status; - } -} - -export type OauthGrantTokens = Readonly<{ - accessToken: string; - /** The ROTATED refresh token — single-use, so persist it atomically with the lease. */ - refreshToken: string; - expiresIn?: number; -}>; - -/** - * One round of the OAuth refresh chain on wrangler's public client - * (contract 4): form-encoded POST to dash.cloudflare.com/oauth2/token. - * Refresh tokens rotate on every use; a missing replacement in the answer - * fails loudly rather than silently persisting a now-dead token. - */ -export async function refreshOauthGrant(refreshToken: string): Promise { - const response = await fetch(CF_OAUTH_TOKEN_URL, { - method: 'POST', - headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, - body: new URLSearchParams({ - grant_type: 'refresh_token', - client_id: CF_EMAIL_OAUTH_CLIENT_ID, - refresh_token: refreshToken, - }).toString(), - }); - let json: { - access_token?: string; - refresh_token?: string; - expires_in?: number; - error?: string; - } | null = null; - try { - json = await response.json(); - } catch { - // Non-JSON error body (an HTML error page, a truncated response) — - // classified below as unknown_error with the HTTP status. - } - if (!response.ok) { - throw new OAuthGrantError(json?.error ?? 'unknown_error', response.status); - } - if (!json?.access_token || !json.refresh_token) { - throw new OAuthGrantError('invalid_response', response.status); - } - return { - accessToken: json.access_token, - refreshToken: json.refresh_token, - ...(json.expires_in === undefined ? {} : { expiresIn: json.expires_in }), - }; -} - -/** - * RFC 7009 revocation of the grant's refresh token on wrangler's public - * client — the logout half of contract 4, mirroring wrangler's - * `workers-auth` logout byte-for-byte: form-encoded POST carrying - * client_id + token_type_hint + token, and NO Authorization header (a - * public client authenticates with the token itself). - * - * THROWS on a network failure or a non-2xx status: CF answers 200 whether - * the token was live or already dead (probed 2026-09-17), so a failure - * leaves the grant's state genuinely unknown — and `removeEmailDomain` - * records `revoke_grant` in failed_steps only when its dep throws. The - * response body is ignored. The token is never logged or interpolated - * into anything. - */ -export async function revokeOauthGrant(refreshToken: string): Promise { - let response: Response; - try { - response = await fetch(CF_OAUTH_REVOKE_URL, { - method: 'POST', - headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, - body: new URLSearchParams({ - client_id: CF_EMAIL_OAUTH_CLIENT_ID, - token_type_hint: 'refresh_token', - token: refreshToken, - }).toString(), - }); - } catch (err) { - // Network-level failure. A fetch TypeError carries no request body, so - // the token cannot leak through it. - console.error('Cloudflare OAuth grant revocation request failed', err); - throw err; - } - if (!response.ok) { - console.error(`Cloudflare OAuth grant revocation failed with HTTP ${response.status}`); - throw new Error(`Cloudflare OAuth grant revocation failed with HTTP ${response.status}`); - } -} diff --git a/platform/packages/api/src/email/cf-domain-probes.ts b/platform/packages/api/src/email/cf-domain-probes.ts new file mode 100644 index 000000000..e2a6b7ff5 --- /dev/null +++ b/platform/packages/api/src/email/cf-domain-probes.ts @@ -0,0 +1,49 @@ +import type { CfCustomerClient, CfCustomerZone } from './cf-customer.ts'; + +/** Look up public MX exchange names, without priority and trailing dot. */ +export async function lookupMxOverDns(domain: string): Promise> { + const response = await fetch( + `https://cloudflare-dns.com/dns-query?name=${encodeURIComponent(domain)}&type=MX`, + { headers: { accept: 'application/dns-json' }, signal: AbortSignal.timeout(15_000) }, + ); + if (!response.ok) { + throw new Error(`public DNS MX lookup failed with HTTP ${response.status}`); + } + const json = (await response.json()) as { + Answer?: ReadonlyArray<{ type: number; data: string }>; + }; + return (json.Answer ?? []) + .filter((answer) => answer.type === 15) + .map((answer) => answer.data.trim().split(/\s+/).slice(1).join(' ').replace(/\.$/, '')); +} + +/** Confirm Cloudflare Email Sending onboarded the exact domain. */ +export async function sendingOnboardedReadback( + client: CfCustomerClient, + zoneId: string, + domain: string, +): Promise { + try { + const subdomains = await client.listSendingSubdomains(zoneId); + return subdomains.some( + (subdomain) => subdomain.enabled && subdomain.name.toLowerCase() === domain.toLowerCase(), + ); + } catch { + return false; + } +} + +/** Find the deepest visible Cloudflare zone containing a domain. */ +export async function findZoneForEmailDomain( + client: CfCustomerClient, + domain: string, +): Promise { + const labels = domain.split('.'); + for (let start = 0; start <= labels.length - 2; start++) { + const zone = await client.findZone(labels.slice(start).join('.')); + if (zone) { + return zone; + } + } + return null; +} diff --git a/platform/packages/api/src/email/connection-service.ts b/platform/packages/api/src/email/connection-service.ts index 45abb25ca..8cb15e4f3 100644 --- a/platform/packages/api/src/email/connection-service.ts +++ b/platform/packages/api/src/email/connection-service.ts @@ -7,6 +7,11 @@ import { projects } from '../schema.ts'; import { emailUnresolvedAttempts } from './admission-schema.ts'; import { disableEmailDomainRouteAndDrainTx } from './admission.ts'; import { createCfCustomerClient } from './cf-customer.ts'; +import { + findZoneForEmailDomain, + lookupMxOverDns, + sendingOnboardedReadback, +} from './cf-domain-probes.ts'; import { emailCacheOutbox, emailCredentials, @@ -16,11 +21,6 @@ import { emailZoneConnections, } from './connection-schema.ts'; import { isValidEmailDomain, normalizeEmailDomain } from './domain-name.ts'; -import { - findZoneForEmailDomain, - lookupMxOverDns, - sendingOnboardedReadback, -} from './relay-engine.ts'; import { RELAY_COMPATIBILITY_DATE, RELAY_SOURCE, RELAY_VERSION } from './relay-worker.ts'; type Bindings = ApiEnv['Bindings']; @@ -402,6 +402,69 @@ export async function credentialFor( }); } +async function forgetUnusedEmailCredential( + tx: DbOrTx, + connectionId: string, + removingRouteId: string, +): Promise { + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connectionId)) + .for('update') + .limit(1) + )[0]; + if (!connection?.credential_id) { + return; + } + const sibling = ( + await tx + .select({ id: emailDomainRoutes.id }) + .from(emailDomainRoutes) + .where( + and( + eq(emailDomainRoutes.connection_id, connectionId), + ne(emailDomainRoutes.id, removingRouteId), + ne(emailDomainRoutes.desired_state, 'removed'), + ), + ) + .limit(1) + )[0]; + if (sibling) { + return; + } + await tx + .update(emailZoneConnections) + .set({ + credential_id: null, + management_status: 'revoked', + management_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connectionId)); + await tx.delete(emailCredentials).where(eq(emailCredentials.id, connection.credential_id)); +} + +export async function inspectEmailInboundRoute( + client: ReturnType, + connection: Pick, + domain: string, +): Promise { + const [catchall, rules] = await Promise.all([ + client.getCatchAll(connection.zone_id), + client.listRoutingRules(connection.zone_id), + ]); + if (!catchall?.enabled || catchall.workerName !== connection.ingress_worker_name) { + return 'zone catch-all does not point to this ingress'; + } + return rules.some( + (rule) => rule.enabled && rule.addresses.some((address) => address.endsWith(`@${domain}`)), + ) + ? `enabled explicit Cloudflare email rules conflict with ${domain}` + : null; +} + export async function readConnectionSecret( env: Bindings, connection: typeof emailZoneConnections.$inferSelect, @@ -547,7 +610,8 @@ export async function requestEmailDomainAdd( ) .limit(1) )[0]; - if (!existingConnection) { + const existingAssignment = await resolveEmailDomain(db, domain); + if (!existingAssignment) { const preflight = await Promise.all([ lookupMxOverDns(domain), client.getCatchAll(zone.id), @@ -559,7 +623,11 @@ export async function requestEmailDomainAdd( 409, ); } - if (preflight[1]?.enabled && preflight[1].workerName !== ingressName(installationId, zone.id)) { + if ( + preflight[1]?.enabled && + preflight[1].workerName !== + (existingConnection?.ingress_worker_name ?? ingressName(installationId, zone.id)) + ) { throw new EmailOperationError( 'an unrelated catch-all already owns this Cloudflare zone', 409, @@ -611,10 +679,42 @@ export async function requestEmailDomainAdd( .select() .from(emailDomainRoutes) .where(eq(emailDomainRoutes.domain, domain)) + .for('update') .limit(1) )[0]; - if (existingRoute && existingRoute.project_id !== input.projectId) { - throw new EmailOperationError('email domain is assigned to another project', 409); + const transfer = !!existingRoute && existingRoute.project_id !== input.projectId; + if (transfer) { + if (existingRoute.desired_state !== 'removed' || existingRoute.addressing !== 'custom') { + throw new EmailOperationError('email domain is assigned to another project', 409); + } + const lastRemoval = ( + await tx + .select({ status: emailOperations.status }) + .from(emailOperations) + .where( + and( + eq(emailOperations.route_id, existingRoute.id), + eq(emailOperations.kind, 'remove'), + ), + ) + .orderBy(desc(emailOperations.created_at), desc(emailOperations.id)) + .limit(1) + )[0]; + if (lastRemoval?.status !== 'completed') { + throw new EmailOperationError('previous email domain cleanup is unresolved', 409); + } + const [unresolved] = await tx + .select({ n: count() }) + .from(emailUnresolvedAttempts) + .where( + and( + eq(emailUnresolvedAttempts.project_id, existingRoute.project_id!), + eq(emailUnresolvedAttempts.sender_domain, domain), + ), + ); + if ((unresolved?.n ?? 0) > 0) { + throw new EmailOperationError('previous email domain sends are unresolved', 409); + } } let connection = ( await tx @@ -634,6 +734,9 @@ export async function requestEmailDomainAdd( if (connection && !canManageConnection(actor, connection)) { throw new EmailOperationError('zone connection requires its manager approval', 403); } + if (existingRoute && existingRoute.connection_id !== connection?.id) { + throw new EmailOperationError('email domain belongs to a different Cloudflare zone', 409); + } if (connection) { const unresolved = ( await tx @@ -662,29 +765,45 @@ export async function requestEmailDomainAdd( 403, ); } - if (!connection.credential_id) { - throw new EmailOperationError('connection credential missing', 503); - } - const replacement = input.token - ? await encryptPlatformCredential( - env, - installationId, - connection.credential_id, - input.token, - ) - : null; - await tx - .update(emailCredentials) - .set({ + if (connection.credential_id) { + const replacement = input.token + ? await encryptPlatformCredential( + env, + installationId, + connection.credential_id, + input.token, + ) + : null; + await tx + .update(emailCredentials) + .set({ + kind: input.token ? 'api_token' : 'platform', + ciphertext: replacement?.ciphertext ?? null, + iv: replacement?.iv ?? null, + key_version: replacement?.keyVersion ?? null, + status: 'healthy', + generation: sql`${emailCredentials.generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailCredentials.id, connection.credential_id)); + } else { + await tx.insert(emailCredentials).values({ + id: credentialId, + installation_id: installationId, + managed_by: actor.kind, + manager_user_id: actor.kind === 'owner' ? actor.userId : null, kind: input.token ? 'api_token' : 'platform', - ciphertext: replacement?.ciphertext ?? null, - iv: replacement?.iv ?? null, - key_version: replacement?.keyVersion ?? null, - status: 'healthy', - generation: sql`${emailCredentials.generation} + 1`, - updated_at: sql`now()`, - }) - .where(eq(emailCredentials.id, connection.credential_id)); + account_id: zone.account.id, + zone_id: zone.id, + ciphertext: encryptedToken?.ciphertext ?? null, + iv: encryptedToken?.iv ?? null, + key_version: encryptedToken?.keyVersion ?? null, + }); + await tx + .update(emailZoneConnections) + .set({ credential_id: credentialId }) + .where(eq(emailZoneConnections.id, connection.id)); + } const generation = connection.desired_generation + 1; await tx .update(emailZoneConnections) @@ -695,9 +814,31 @@ export async function requestEmailDomainAdd( updated_at: sql`now()`, }) .where(eq(emailZoneConnections.id, connection.id)); + const reactivating = existingRoute.desired_state !== 'active'; await tx .update(emailDomainRoutes) - .set({ desired_state: 'active', updated_at: sql`now()` }) + .set({ + desired_state: 'active', + ...(reactivating + ? { + desired_generation: sql`${emailDomainRoutes.desired_generation} + 1`, + inbound_status: 'pending' as const, + inbound_reason: null, + inbound_observed_at: null, + outbound_status: 'pending' as const, + outbound_reason: null, + outbound_observed_at: null, + } + : {}), + ...(transfer + ? { + project_id: input.projectId, + assigned_by_user_id: actor.userId, + created_at: sql`now()`, + } + : {}), + updated_at: sql`now()`, + }) .where(eq(emailDomainRoutes.id, existingRoute.id)); await tx.insert(emailOperations).values({ id: operationId, @@ -712,15 +853,16 @@ export async function requestEmailDomainAdd( request_digest: requestDigest, desired_generation: generation, }); - for (let i = 0; i < SYNC_STEPS.length; i++) { + const steps = connection.inbound_status === 'disabled' ? SETUP_STEPS : SYNC_STEPS; + for (let i = 0; i < steps.length; i++) { await tx.insert(emailOperationSteps).values({ id: generateId('estep'), operation_id: operationId, ordinal: i, - kind: SYNC_STEPS[i], + kind: steps[i], resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, request_digest: await digest({ - kind: SYNC_STEPS[i], + kind: steps[i], connectionId: connection.id, generation, }), @@ -765,6 +907,28 @@ export async function requestEmailDomainAdd( .where(eq(emailZoneConnections.id, connectionId)) .limit(1) )[0]!; + } else if (!connection.credential_id) { + await tx.insert(emailCredentials).values({ + id: credentialId, + installation_id: installationId, + managed_by: actor.kind, + manager_user_id: actor.kind === 'owner' ? actor.userId : null, + kind: input.token ? 'api_token' : 'platform', + account_id: zone.account.id, + zone_id: zone.id, + ciphertext: encryptedToken?.ciphertext ?? null, + iv: encryptedToken?.iv ?? null, + key_version: encryptedToken?.keyVersion ?? null, + }); + await tx + .update(emailZoneConnections) + .set({ + credential_id: credentialId, + management_status: 'healthy', + management_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connection.id)); } else if (input.token) { // A sibling assignment supplies the manager's current zone token. // The connection, rather than either project, owns its ciphertext. @@ -812,7 +976,8 @@ export async function requestEmailDomainAdd( request_digest: requestDigest, desired_generation: connection.desired_generation, }); - const steps = created ? SETUP_STEPS : SIBLING_STEPS; + const steps = + created || connection.inbound_status === 'disabled' ? SETUP_STEPS : SIBLING_STEPS; for (let i = 0; i < steps.length; i++) { await tx.insert(emailOperationSteps).values({ id: generateId('estep'), @@ -1046,10 +1211,18 @@ export async function getEmailOperation(db: DbOrTx, projectId: string, key: stri const rows = await db .select({ operation: emailOperations, route: emailDomainRoutes }) .from(emailOperations) - .innerJoin(emailDomainRoutes, eq(emailOperations.route_id, emailDomainRoutes.id)) + .innerJoin( + emailDomainRoutes, + sql`( + ${emailOperations.route_id} = ${emailDomainRoutes.id} + OR (${emailOperations.kind} = 'rotate_secret' + AND ${emailOperations.connection_id} = ${emailDomainRoutes.connection_id}) + )`, + ) .where( and( eq(emailDomainRoutes.project_id, projectId), + sql`(${emailOperations.kind} = 'rotate_secret' OR ${emailOperations.created_at} >= ${emailDomainRoutes.created_at})`, sql`(${emailOperations.id} = ${key} OR ${emailOperations.idempotency_key} = ${key})`, ), ) @@ -1123,6 +1296,25 @@ export async function requestEmailSecretRotation( if (!canManageConnection(actor, connection)) { throw new EmailOperationError('only the connection manager can rotate ingress', 403); } + const replay = ( + await tx + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, actorScope), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (replay) { + if (replay.request_digest !== requestDigest) { + throw new EmailOperationError('email operation key conflict'); + } + return replay.id; + } if (isSharedGatewayConnection(env, connection)) { throw new EmailOperationError( 'the installation gateway secret is managed by platform deployment, not zone rotation', @@ -1243,6 +1435,9 @@ async function requestExistingOperation( if (!route) { throw new EmailOperationError('email domain not available', 404); } + if (kind === 'sync' && route.desired_state !== 'active') { + throw new EmailOperationError('email domain must be active before reconciliation', 409); + } const connection = ( await tx .select() @@ -1269,6 +1464,25 @@ async function requestExistingOperation( 403, ); } + const replay = ( + await tx + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.installation_id, installationId), + eq(emailOperations.actor_scope, actorScope), + eq(emailOperations.idempotency_key, key), + ), + ) + .limit(1) + )[0]; + if (replay) { + if (replay.request_digest !== requestDigest) { + throw new EmailOperationError('email operation key conflict'); + } + return replay.id; + } const existingRemoval = kind === 'remove' ? ( @@ -1526,6 +1740,17 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri ) .returning({ id: emailOperationSteps.id }); if (updated.length) { + if ( + claim.step.kind === 'ingress_delete' && + outcome.deleted === true && + claim.op.route_id + ) { + await tx + .update(emailZoneConnections) + .set({ inbound_status: 'disabled', inbound_observed_at: sql`now()` }) + .where(eq(emailZoneConnections.id, current.id)); + await forgetUnusedEmailCredential(tx, current.id, claim.op.route_id); + } await tx .update(emailOperations) .set({ @@ -1742,9 +1967,22 @@ async function executeEmailStep( return { workerName: connection.ingress_worker_name }; } if (kind === 'inbound_probe') { - const current = await client.getCatchAll(connection.zone_id); - if (!current?.enabled || current.workerName !== connection.ingress_worker_name) { - throw new EmailOperationError('zone catch-all does not point to this ingress'); + if (!route) { + throw new EmailOperationError('email route is unavailable'); + } + const issue = await inspectEmailInboundRoute(client, connection, route.domain); + if (issue) { + await db + .update(emailDomainRoutes) + .set({ + inbound_status: 'drifted', + inbound_reason: issue, + inbound_observed_at: sql`now()`, + }) + .where( + and(eq(emailDomainRoutes.id, route.id), eq(emailDomainRoutes.desired_state, 'active')), + ); + throw new EmailOperationError(issue); } await db.transaction(async (tx) => { await tx @@ -1830,10 +2068,6 @@ async function executeEmailStep( throw new EmailOperationError('owned catch-all still targets ingress'); } await client.deleteRelayScript(connection.account_id, connection.ingress_worker_name); - await db - .update(emailZoneConnections) - .set({ inbound_status: 'disabled', inbound_observed_at: sql`now()` }) - .where(eq(emailZoneConnections.id, connection.id)); return { deleted: true }; } throw new EmailOperationError(`unsupported email step: ${kind}`); @@ -1966,7 +2200,20 @@ export async function reconcileUnknownEmailOperation( outcome = await probeDeployedRelay(client, env, connection, op.kind === 'rotate_secret'); } else if (step.kind === 'gateway_probe') { outcome = await probeGatewayAcceptance(env, connection, op.kind === 'rotate_secret'); - } else if (step.kind === 'catchall_ensure' || step.kind === 'inbound_probe') { + } else if (step.kind === 'inbound_probe') { + const route = op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null; + if (route && !(await inspectEmailInboundRoute(client, connection, route.domain))) { + outcome = { ready: true }; + } + } else if (step.kind === 'catchall_ensure') { const catchall = await client.getCatchAll(connection.zone_id); if (catchall?.enabled && catchall.workerName === connection.ingress_worker_name) { outcome = { workerName: connection.ingress_worker_name }; @@ -2058,6 +2305,13 @@ export async function reconcileUnknownEmailOperation( .set({ outbound_status: 'ready', outbound_reason: null, outbound_observed_at: sql`now()` }) .where(eq(emailDomainRoutes.id, op.route_id)); } + if (step.kind === 'ingress_delete' && outcome.deleted === true && op.route_id) { + await tx + .update(emailZoneConnections) + .set({ inbound_status: 'disabled', inbound_observed_at: sql`now()` }) + .where(eq(emailZoneConnections.id, connection.id)); + await forgetUnusedEmailCredential(tx, connection.id, op.route_id); + } await tx .update(emailOperations) .set({ status: 'pending', failure_code: null, failure_detail: null, updated_at: sql`now()` }) diff --git a/platform/packages/api/src/email/credential-lease.ts b/platform/packages/api/src/email/credential-lease.ts deleted file mode 100644 index 613cec98f..000000000 --- a/platform/packages/api/src/email/credential-lease.ts +++ /dev/null @@ -1,311 +0,0 @@ -/** - * Credential lease + OAuth refresh chain for `email_domains` (design doc - * 0078, contract 4). The proxy never holds a domain's stored credential — - * it leases a short-lived one from the api (`POST - * /internal/email/domain-credential`, routes/internal-email.ts): - * - * api_token → the stored token itself, decrypted (it is long-lived; - * the proxy caches it ≤ 45 min). - * oauth_grant → a fresh access token from ONE refresh round-trip. - * - * Grant refresh tokens are single-use and rotate, so the refresh chain is - * SERIALIZED PER ROW: a `SELECT … FOR UPDATE` on the domain row (the same - * row-level pattern the deploy/build claims use in db.ts) held across the - * token-endpoint call, with the rotated refresh token re-encrypted and - * persisted in the SAME transaction. Revocations take the same lock so they - * always target the live chain head (`revokeOauthGrantSerialized`), and the - * relay-secret rotation serializes on it too (`withEmailDomainRowLock`). - * There is no access-token cache on the - * api side — every lease refreshes. `invalid_grant` marks the row - * `token_revoked` inside the transaction, before the error travels. - * - * Credential material is never logged or interpolated into errors; the - * lease leaves this module only as the lease route's response body. - */ - -import { eq, sql } from 'drizzle-orm'; -import type { Db, DbOrTx, Tx } from '../db.ts'; -import type { ApiEnv } from '../env.ts'; -import { emailDomains } from '../schema.ts'; -import { OAuthGrantError, refreshOauthGrant, revokeOauthGrant } from './cf-customer.ts'; -import type { OauthGrantTokens } from './cf-customer.ts'; -import { decryptEmailDomainToken, encryptEmailDomainToken } from './domains.ts'; -import type { EmailDomain, PlatformCredentialBindings } from './domains.ts'; - -export type EmailDomainLease = - | Readonly<{ kind: 'api_token'; token: string }> - | Readonly<{ kind: 'oauth_grant'; accessToken: string }>; - -export type EmailDomainLeaseOutcome = - | Readonly<{ ok: true; lease: EmailDomainLease }> - | Readonly<{ ok: false; status: 'token_revoked' | 'failed'; error: string }>; - -/** - * The row's stored credential kind changed under the caller — a - * concurrent `domain add` (replace) committed a different credential - * before the row lock was acquired. Thrown by the serialized helpers - * INSTEAD of operating on the wrong credential: submitting a fresh API - * token to the grant endpoint would answer invalid_grant, and the - * refresh's token_revoked flip would then disable the replacement. - * Nothing is written; the caller re-reads the row and retries (or fails - * the operation as transient). - */ -export class EmailDomainCredentialChangedError extends Error { - constructor(rowId: string) { - super(`email_domains row ${rowId} changed credential kind mid-operation`); - this.name = 'EmailDomainCredentialChangedError'; - } -} - -type SecretBindings = Pick< - ApiEnv['Bindings'], - 'PROJECT_SECRET_KEYS_JSON' | 'PROJECT_SECRET_ACTIVE_KEY_VERSION' ->; - -function errorMessage(err: unknown): string { - return err instanceof Error ? err.message : String(err); -} - -/** - * One refresh round-trip under the row lock. Returns the fresh tokens with - * the rotated refresh token already persisted (re-encrypted under the - * row's fixed AAD name) in the same transaction that held the lock. - * - * Throws OAuthGrantError on a token-endpoint failure — `invalid_grant` - * included, with the row already marked `token_revoked`. That flip runs - * only against a row confirmed `oauth_grant` under this lock: a - * credential kind changed by a concurrent replace throws - * EmailDomainCredentialChangedError instead, with nothing written. - * Callers that run - * the relay engine hand this in as `deps.refreshGrant`; the engine maps - * `invalid_grant` to the same `token_revoked` outcome, so the persisted - * status and the engine's result agree. The relay engine's own - * `rotated_refresh_token` passthrough must NOT be re-persisted by those - * callers: this function already wrote it under the lock, and a blind - * second write could overwrite a NEWER rotation a concurrent lease - * committed in between (killing the chain — see contract 4). - */ -export async function refreshOauthGrantSerialized( - db: DbOrTx, - env: SecretBindings, - rowId: string, -): Promise { - // `invalid_grant` must COMMIT its status flip — an error thrown from the - // callback rolls the transaction back, so the revocation outcome travels - // out of the transaction and is thrown only after the commit. - const outcome = await db.transaction( - async ( - tx, - ): Promise< - { ok: true; tokens: OauthGrantTokens } | { ok: false; revoked: OAuthGrantError } - > => { - const rows = await tx - .select({ - id: emailDomains.id, - project_id: emailDomains.project_id, - domain: emailDomains.domain, - credential_kind: emailDomains.credential_kind, - token_ciphertext: emailDomains.token_ciphertext, - token_iv: emailDomains.token_iv, - token_key_version: emailDomains.token_key_version, - }) - .from(emailDomains) - .where(eq(emailDomains.id, rowId)) - .for('update') - .limit(1); - const row = rows[0]; - if (!row) { - throw new Error(`email_domains row ${rowId} vanished mid-refresh`); - } - if (row.credential_kind !== 'oauth_grant') { - // A replace committed a different credential before this lock. - // Decrypting it as a grant would submit an API token to the token - // endpoint, and the invalid_grant answer would mark the FRESH - // credential revoked. Thrown inside the transaction: nothing is - // written. - throw new EmailDomainCredentialChangedError(rowId); - } - - const refreshToken = await decryptEmailDomainToken(env, row.project_id, row.domain, { - credential_kind: row.credential_kind, - token_ciphertext: row.token_ciphertext, - token_iv: row.token_iv, - token_key_version: row.token_key_version, - }); - - let tokens: OauthGrantTokens; - try { - tokens = await refreshOauthGrant(refreshToken); - } catch (err) { - if (err instanceof OAuthGrantError && err.code === 'invalid_grant') { - await tx - .update(emailDomains) - .set({ status: 'token_revoked', updated_at: sql`now()` }) - .where(eq(emailDomains.id, rowId)); - return { ok: false, revoked: err }; - } - // Transient failure — the transaction rolls back with nothing - // written; the row keeps its current status and credential. - throw err; - } - - const rotated = await encryptEmailDomainToken( - env, - row.project_id, - row.domain, - tokens.refreshToken, - ); - await tx - .update(emailDomains) - .set({ - token_ciphertext: rotated.ciphertext, - token_iv: rotated.iv, - token_key_version: rotated.keyVersion, - updated_at: sql`now()`, - }) - .where(eq(emailDomains.id, rowId)); - return { ok: true, tokens }; - }, - ); - if (!outcome.ok) { - throw outcome.revoked; - } - return outcome.tokens; -} - -/** - * Revoke the row's CURRENT chain head under the same per-row lock the - * refresh uses. A revocation must target the live head: a token captured - * earlier may already be consumed by an interleaved lease refresh, and CF - * answers 200 whether the presented token was live or dead — so only a - * capture under the lock makes the 200 mean the chain is dead. The lock is - * held across the revocation call, exactly like the refresh. A gone row - * (teardown's cascade won) has nothing left to revoke; a row whose - * credential kind changed under the caller (a replace committed first) - * throws EmailDomainCredentialChangedError rather than submitting the - * replacement credential. Throws on a network or non-2xx failure — the - * caller decides what that means (failed_steps, a 502, …). No status flip - * here: the caller owns the row's fate. - */ -export async function revokeOauthGrantSerialized( - db: DbOrTx, - env: SecretBindings, - rowId: string, -): Promise { - await db.transaction(async (tx) => { - const rows = await tx - .select({ - id: emailDomains.id, - project_id: emailDomains.project_id, - domain: emailDomains.domain, - credential_kind: emailDomains.credential_kind, - token_ciphertext: emailDomains.token_ciphertext, - token_iv: emailDomains.token_iv, - token_key_version: emailDomains.token_key_version, - }) - .from(emailDomains) - .where(eq(emailDomains.id, rowId)) - .for('update') - .limit(1); - const row = rows[0]; - if (!row) { - return; - } - if (row.credential_kind !== 'oauth_grant') { - // A replace committed a different credential before this lock: - // revoking must not submit the NEW credential to the grant - // endpoint, whose answers-200-for-anything semantics would read as - // success to the caller. - throw new EmailDomainCredentialChangedError(rowId); - } - const head = await decryptEmailDomainToken(env, row.project_id, row.domain, { - credential_kind: row.credential_kind, - token_ciphertext: row.token_ciphertext, - token_iv: row.token_iv, - token_key_version: row.token_key_version, - }); - await revokeOauthGrant(head); - }); -} - -/** - * The per-row lock behind the refresh chain, generalized: `fn` runs inside - * a transaction holding `SELECT … FOR UPDATE` on the domain row. The relay - * secret rotation (sync) is serialized this way — two overlapping syncs - * would otherwise interleave the worker secret PUT and the row/mirror - * persist, leaving the worker holding a secret the row no longer knows. - * The lock is held across the CF calls, exactly like the refresh holds it - * across the token round-trip; the KV mirror write stays AFTER the commit - * (KV is not transactional). - */ -export async function withEmailDomainRowLock( - db: Db, - rowId: string, - fn: (tx: Tx) => Promise, -): Promise { - return db.transaction(async (tx) => { - await tx - .select({ id: emailDomains.id }) - .from(emailDomains) - .where(eq(emailDomains.id, rowId)) - .for('update') - .limit(1); - return fn(tx); - }); -} - -/** - * Lease a send credential for one domain row. The caller (the internal - * lease route) has already authenticated the request and checked the row - * is `active`. `token_revoked` outcomes are persisted here; the caller owns - * the ROUTING KV mirror update that must follow. - */ -export async function leaseEmailDomainCredential( - db: Db, - env: SecretBindings & Partial, - row: EmailDomain, -): Promise { - // The caller's row snapshot is unlocked; a replace can commit between - // its read and the refresh's lock. One re-read converges on what the - // row NOW holds — a second mid-lease change fails as transient. - let current = row; - for (let attempt = 0; ; attempt++) { - // An api_token row leases its stored token; a platform row leases the - // runtime token the same seam resolves. Both are long-lived and travel - // to the proxy as `api_token` — it never needs to tell them apart. - if (current.credential_kind === 'api_token' || current.credential_kind === 'platform') { - let token: string; - try { - token = await decryptEmailDomainToken(env, current.project_id, current.domain, current); - } catch (err) { - return { ok: false, status: 'failed', error: errorMessage(err) }; - } - return { ok: true, lease: { kind: 'api_token', token } }; - } - try { - const tokens = await refreshOauthGrantSerialized(db, env, current.id); - return { ok: true, lease: { kind: 'oauth_grant', accessToken: tokens.accessToken } }; - } catch (err) { - if (err instanceof EmailDomainCredentialChangedError && attempt === 0) { - const fresh = await db - .select() - .from(emailDomains) - .where(eq(emailDomains.id, current.id)) - .limit(1); - if (fresh[0]) { - current = fresh[0]; - continue; - } - return { ok: false, status: 'failed', error: 'email domain row vanished mid-lease' }; - } - if (err instanceof OAuthGrantError && err.code === 'invalid_grant') { - return { - ok: false, - status: 'token_revoked', - error: 'the Cloudflare OAuth grant was revoked', - }; - } - return { ok: false, status: 'failed', error: errorMessage(err) }; - } - } -} diff --git a/platform/packages/api/src/email/domain-service.ts b/platform/packages/api/src/email/domain-service.ts index 40099cbaf..46d887ead 100644 --- a/platform/packages/api/src/email/domain-service.ts +++ b/platform/packages/api/src/email/domain-service.ts @@ -3,13 +3,16 @@ * provider request. */ import { and, eq, sql } from 'drizzle-orm'; import type { Context } from 'hono'; -import type { Db, DbOrTx } from '../db.ts'; +import type { Db } from '../db.ts'; import type { ApiEnv } from '../env.ts'; import type { Project } from '../types.ts'; +import { createCfCustomerClient } from './cf-customer.ts'; import { emailDomainRoutes, emailOperations, emailZoneConnections } from './connection-schema.ts'; import { EmailOperationError, + credentialFor, getEmailOperation, + inspectEmailInboundRoute, requestEmailDomainAdd, requestEmailDomainRemove, requestEmailDomainSync, @@ -23,8 +26,6 @@ import { getEmailDomainManagement } from './settings.ts'; export const MAX_CREDENTIAL_LENGTH = 2048; export type EmailDomainAddInput = Readonly<{ domain: string; - mode?: unknown; - refreshToken?: string; apiToken?: string; attemptId?: unknown; managedBy: 'owner' | 'admin'; @@ -37,43 +38,6 @@ export function adminEmailDomainCommand( const base = `void platform email domain-${verb} ${domain}`; return verb === 'add' && slug ? `${base} --project ${slug}` : base; } -export function proxyOriginForEmail(env: ApiEnv['Bindings']): string { - const origin = - env.PROXY_URL ?? - (env.PLATFORM_ENV === 'staging' - ? 'https://proxy.staging.void.cloud' - : 'https://proxy.void.cloud'); - return origin.replace(/\/+$/, ''); -} -export function emailDomainMirrorKey(domain: string): string { - return `email-domain:${domain}`; -} -export async function revokeRejectedGrant(): Promise { - /* OAuth grants are no longer accepted for platform email. */ -} - -export async function getEmailDomainRow(db: Db, projectId: string, domain: string) { - return ( - ( - await db - .select() - .from(emailDomainRoutes) - .where( - and( - eq(emailDomainRoutes.project_id, projectId), - eq(emailDomainRoutes.domain, normalizeEmailDomain(domain)), - ), - ) - .limit(1) - )[0] ?? null - ); -} -export async function getEmailDomainRowById(db: DbOrTx, id: string) { - return ( - (await db.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.id, id)).limit(1))[0] ?? - null - ); -} export async function getEmailDomainRowByDomain(db: Db, domain: string) { return ( ( @@ -121,20 +85,6 @@ export function serializeEmailRoute( }, }; } -export function serializeEmailDomain( - route: typeof emailDomainRoutes.$inferSelect, - connection?: typeof emailZoneConnections.$inferSelect, -) { - return connection - ? serializeEmailRoute(route, connection) - : { - id: route.id, - domain: route.domain, - project_id: route.project_id, - managed_by: route.managed_by, - status: route.inbound_status, - }; -} function serviceError(context: Context, error: unknown): Response { if (error instanceof EmailOperationError) { return context.json({ error: error.message }, error.status as 400); @@ -165,15 +115,6 @@ export async function addEmailDomainForProject( input: EmailDomainAddInput, ): Promise { try { - if (input.refreshToken) { - return context.json( - { - error: - 'Cloudflare OAuth grants are not accepted for platform email domains; use a scoped API token', - }, - 400, - ); - } if (project.status === 'deleting') { return context.json({ error: 'Project is being deleted' }, 409); } @@ -219,10 +160,89 @@ export async function getEmailDomainStatusForProject( project: Project, rawDomain: string, ): Promise { - const resolved = await resolveEmailDomain(context.get('db'), rawDomain); + const db = context.get('db'); + let resolved = await resolveEmailDomain(db, rawDomain); if (!resolved || resolved.route.project_id !== project.id) { return context.json({ error: 'email domain not found' }, 404); } + const snapshot = resolved; + if (snapshot.route.desired_state === 'active') { + let managementReason: string | null = null; + let inboundIssue: string | null = null; + let outbound: 'ready' | 'verified_only' | 'blocked' = 'blocked'; + let outboundReason: string | null = null; + try { + const client = createCfCustomerClient( + await credentialFor(context.env, db, snapshot.connection), + ); + inboundIssue = await inspectEmailInboundRoute( + client, + snapshot.connection, + snapshot.route.domain, + ); + try { + const senders = await client.listSendingSubdomains(snapshot.connection.zone_id); + outbound = senders.some( + (sender) => sender.enabled && sender.name.toLowerCase() === snapshot.route.domain, + ) + ? 'ready' + : 'verified_only'; + outboundReason = + outbound === 'verified_only' ? 'Cloudflare Sending is not enabled for this domain' : null; + } catch { + outboundReason = 'Cloudflare Sending status could not be verified'; + } + } catch { + managementReason = + 'Cloudflare routing status could not be verified; check the connection credential'; + } + await db.transaction(async (tx) => { + const updated = await tx + .update(emailZoneConnections) + .set({ + management_status: managementReason ? 'probe_failed' : 'healthy', + management_reason: managementReason, + management_observed_at: sql`now()`, + }) + .where( + and( + eq(emailZoneConnections.id, snapshot.connection.id), + eq(emailZoneConnections.desired_generation, snapshot.connection.desired_generation), + ), + ) + .returning({ id: emailZoneConnections.id }); + // A failed credential probe does not revoke independently authenticated ingress. + if (updated.length && !managementReason) { + // Routing reads cannot replace the setup operation's ingress identity proof. + const revalidateInbound = + snapshot.connection.inbound_status === 'ready' && + (snapshot.route.inbound_status === 'ready' || + snapshot.route.inbound_status === 'drifted'); + await tx + .update(emailDomainRoutes) + .set({ + ...(revalidateInbound + ? { + inbound_status: inboundIssue ? ('drifted' as const) : ('ready' as const), + inbound_reason: inboundIssue, + inbound_observed_at: sql`now()`, + } + : {}), + outbound_status: outbound, + outbound_reason: outboundReason, + outbound_observed_at: sql`now()`, + }) + .where( + and( + eq(emailDomainRoutes.id, snapshot.route.id), + eq(emailDomainRoutes.desired_generation, snapshot.route.desired_generation), + eq(emailDomainRoutes.desired_state, 'active'), + ), + ); + } + }); + resolved = (await resolveEmailDomain(db, rawDomain))!; + } const op = ( await context .get('db') @@ -310,7 +330,6 @@ export async function removeEmailDomainForProject( context: Context, project: Project, rawDomain: string, - force: boolean, actor: 'owner' | 'admin', ): Promise { try { @@ -339,7 +358,6 @@ export async function removeEmailDomainForProject( operationId, operationStatus: op?.status, error: op?.failure_detail, - forced: force && op?.status !== 'completed', }); } catch (error) { return serviceError(context, error); @@ -354,8 +372,11 @@ export async function getEmailOperationForProject( if (!found) { return context.json({ error: 'email operation not found' }, 404); } - const status = await getEmailDomainStatusForProject(context, project, found.route.domain); - const domain = (await status.json()) as Record; + const resolved = await resolveEmailDomain(context.get('db'), found.route.domain); + if (!resolved) { + return context.json({ error: 'email domain not found' }, 404); + } + const domain = serializeEmailRoute(resolved.route, resolved.connection); return context.json({ operationId: found.operation.id, attemptId: found.operation.idempotency_key, diff --git a/platform/packages/api/src/email/domains.ts b/platform/packages/api/src/email/domains.ts deleted file mode 100644 index a810a945a..000000000 --- a/platform/packages/api/src/email/domains.ts +++ /dev/null @@ -1,277 +0,0 @@ -/** - * Row helpers for `email_domains` — custom sender/recipient domains on the - * customer's own Cloudflare zone (design doc 0078, "Custom domains on - * Cloudflare"). - * - * Two secrets per row, both encrypted with `encryptProjectSecret` under the - * project's envelope key. A project secret's AAD is `${projectId}:${name}` - * and the names are FIXED per row, so each ciphertext is bound to the - * project AND the domain: - * - `email-domain-token:` — the customer's credential: the OAuth - * grant's refresh token, or the pasted API token on the fallback path. - * Only the api decrypts it (probes, relay deploys, the OAuth refresh - * chain); the proxy leases short-lived credentials from the api instead - * of holding it. - * - `email-domain-relay:` — the relay secret, a random 32-byte - * base64url string generated here at add time. The relay worker - * presents it as a bearer on every POST /email/relay; ROUTING KV only - * ever holds its sha256, so the mirror proves knowledge without - * carrying anything reusable. - * - * Neither plaintext is ever logged, returned from an API route, or written - * to a manifest; the one worker the relay secret reaches is the relay - * itself, deployed into the customer's account with only its own domain's - * secret. - */ - -import { eq, sql, type InferSelectModel } from 'drizzle-orm'; -import type { Db, DbOrTx } from '../db.ts'; -import type { ApiEnv } from '../env.ts'; -import { decryptProjectSecret, encryptProjectSecret } from '../project-secrets.ts'; -import { emailDomains } from '../schema.ts'; - -export type EmailDomain = InferSelectModel; - -type EmailDomainSecretBindings = Pick< - ApiEnv['Bindings'], - 'PROJECT_SECRET_KEYS_JSON' | 'PROJECT_SECRET_ACTIVE_KEY_VERSION' ->; - -const encoder = new TextEncoder(); - -/** - * The JSON mirrored to ROUTING KV at `email-domain:` on every - * email_domains create/update. The proxy has no database access — this - * mirror is its ONLY view of the row, so the shape is a wire contract: - * `status` must be 'active' before the proxy trusts anything else in it, - * and `relaySecretSha256` is what a presented relay secret's sha256 is - * constant-time compared against. - */ -export type EmailDomainMirror = { - projectId: string; - status: EmailDomain['status']; - relaySecretSha256: string; - relayWorkerName: string | null; - accountId: string | null; - zoneId: string | null; - mode: EmailDomain['mode']; -}; - -function emailDomainTokenAadName(domain: string): string { - return `email-domain-token:${domain}`; -} - -function emailDomainRelayAadName(domain: string): string { - return `email-domain-relay:${domain}`; -} - -/** - * The one place this key is spelled — writer, clearer, and the tests share - * it, so a rename cannot leave the proxy reading a key nobody writes. - */ -function emailDomainMirrorKey(domain: string): string { - return `email-domain:${domain}`; -} - -/** - * Encrypt the customer's credential (grant refresh token or pasted API - * token) for storage in the row's `token_*` triple. - */ -export function encryptEmailDomainToken( - env: EmailDomainSecretBindings, - projectId: string, - domain: string, - token: string, -): Promise<{ ciphertext: string; iv: string; keyVersion: string }> { - return encryptProjectSecret(env, projectId, emailDomainTokenAadName(domain), token); -} - -export type PlatformCredentialBindings = Pick; - -/** - * The one place a row's credential is resolved. `platform` rows (an - * administrator's, design doc 0078 "Administrator-managed domains") hold - * no credential and resolve to the platform's own runtime token, which is - * never written to the row, a mirror or a log; every other kind decrypts - * the stored triple. - */ -export async function decryptEmailDomainToken( - env: EmailDomainSecretBindings & Partial, - projectId: string, - domain: string, - row: Pick, -): Promise { - if (row.credential_kind === 'platform') { - if (!env.CF_API_TOKEN) { - throw new Error('platform credential unavailable: CF_API_TOKEN is not configured'); - } - return env.CF_API_TOKEN; - } - if (row.token_ciphertext === null || row.token_iv === null || row.token_key_version === null) { - throw new Error('email_domains row is missing its stored credential'); - } - return decryptProjectSecret(env, projectId, { - name: emailDomainTokenAadName(domain), - ciphertext: row.token_ciphertext, - iv: row.token_iv, - key_version: row.token_key_version, - }); -} - -/** - * Encrypt the relay secret for storage in the row's `relay_*` triple. The - * plaintext is also handed to the relay worker as the `VOID_RELAY_SECRET` - * worker secret at deploy/rotation time. - */ -export function encryptEmailDomainRelaySecret( - env: EmailDomainSecretBindings, - projectId: string, - domain: string, - relaySecret: string, -): Promise<{ ciphertext: string; iv: string; keyVersion: string }> { - return encryptProjectSecret(env, projectId, emailDomainRelayAadName(domain), relaySecret); -} - -export function decryptEmailDomainRelaySecret( - env: EmailDomainSecretBindings, - projectId: string, - domain: string, - row: Pick, -): Promise { - return decryptProjectSecret(env, projectId, { - name: emailDomainRelayAadName(domain), - ciphertext: row.relay_ciphertext, - iv: row.relay_iv, - key_version: row.relay_key_version, - }); -} - -/** - * Generate a domain's relay secret: 32 random bytes, base64url without - * padding (43 chars). Generated at add time and rotated on `sync` — - * rotation is overwrite, never read-compare (worker secrets are - * write-only). - */ -export function generateEmailRelaySecret(): string { - const bytes = crypto.getRandomValues(new Uint8Array(32)); - let binary = ''; - for (const byte of bytes) { - binary += String.fromCharCode(byte); - } - return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); -} - -/** - * sha256 of a relay secret as lowercase hex — the only form of the secret - * that reaches ROUTING KV. The proxy hashes the presented bearer the same - * way and constant-time compares. - */ -export async function hashEmailRelaySecret(secret: string): Promise { - const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(secret))); - let hex = ''; - for (const byte of digest) { - hex += byte.toString(16).padStart(2, '0'); - } - return hex; -} - -/** - * Write `email-domain:` in ROUTING KV from the row, on every - * create/update. The payload carries the sha256 of the relay secret, never - * the secret itself. KV failures propagate: strict-vs-best-effort is the - * call site's choice, same as the email-allowlist mirror. - */ -export async function writeEmailDomainMirror( - kv: KVNamespace, - row: Pick< - EmailDomain, - 'domain' | 'project_id' | 'status' | 'relay_worker_name' | 'account_id' | 'zone_id' | 'mode' - >, - relaySecretSha256: string, -): Promise { - const mirror: EmailDomainMirror = { - projectId: row.project_id, - status: row.status, - relaySecretSha256, - relayWorkerName: row.relay_worker_name, - accountId: row.account_id, - zoneId: row.zone_id, - mode: row.mode, - }; - await kv.put(emailDomainMirrorKey(row.domain), JSON.stringify(mirror)); -} - -/** - * Delete `email-domain:` from ROUTING KV, on row delete and on - * project delete (one call per domain the project held). - */ -export async function clearEmailDomainMirror(kv: KVNamespace, domain: string): Promise { - await kv.delete(emailDomainMirrorKey(domain)); -} - -/** The row vanished mid-setup — project teardown's cascade beat the checkpoint write. */ -export class EmailDomainRowGoneError extends Error { - constructor() { - super('email_domains row vanished mid-setup'); - this.name = 'EmailDomainRowGoneError'; - } -} - -/** - * Mid-setup progress write, fired ONCE after the relay deploy + secret PUT - * and BEFORE the catch-all write. Its real job is racing: the partial - * unique index on emailDomains (one live row per zone) makes a concurrent - * loser throw 23505 HERE, before it ever writes its catch-all rule — - * closing the last-write-wins window structurally. (The relay-name - * index's loser now throws EARLIER, at the engine's pre-upload - * claimRelayName; on a fresh setup this write's relay_worker_name and - * account_id are same-value no-ops.) Status, setup_state, relay_version, - * and the credential columns stay untouched; the final apply owns those. - */ -export async function applyEmailDomainDeployCheckpoint( - db: DbOrTx, - rowId: string, - progress: Readonly<{ - zone_id: string | null; - account_id: string | null; - mode: 'apex' | 'subdomain' | null; - relay_worker_name: string; - }>, -): Promise { - const updated = await db - .update(emailDomains) - .set({ - zone_id: progress.zone_id, - account_id: progress.account_id, - ...(progress.mode === null ? {} : { mode: progress.mode }), - relay_worker_name: progress.relay_worker_name, - updated_at: sql`now()`, - }) - .where(eq(emailDomains.id, rowId)) - .returning(); - const row = updated[0]; - if (!row) { - throw new EmailDomainRowGoneError(); - } - return row; -} - -/** - * The DELETE route's keep-row marker: when CF-side cleanup fails the row - * is KEPT so the owner can retry (or force), and this records which steps - * failed. The status GET suppresses mirror repair while - * `failed_step === 'remove'`. - */ -export async function markEmailDomainRemovalFailed( - db: DbOrTx, - rowId: string, - failedSteps: ReadonlyArray, -): Promise { - await db - .update(emailDomains) - .set({ - setup_state: sql`jsonb_set(jsonb_set(coalesce(${emailDomains.setup_state}, '{}'::jsonb), '{failed_step}', '"remove"'), '{removal_failed_steps}', ${JSON.stringify([...failedSteps])}::jsonb)`, - updated_at: sql`now()`, - }) - .where(eq(emailDomains.id, rowId)); -} diff --git a/platform/packages/api/src/email/limits.ts b/platform/packages/api/src/email/limits.ts index 02096849d..b4cfb248c 100644 --- a/platform/packages/api/src/email/limits.ts +++ b/platform/packages/api/src/email/limits.ts @@ -1,36 +1,12 @@ -/** - * Per-project outbound caps and the kill switch live in ROUTING KV, where - * the proxy (`packages/proxy/src/email.ts`) reads them on every send. The - * keys and defaults below are the same contract written from both ends — - * nothing at build time catches a drift, so they are spelled once here for - * the api's writers (admin UI, operator API). - */ -export const emailSuspendKey = (projectId: string) => `email-suspended:${projectId}`; -export const emailMonthlyLimitKey = (projectId: string) => `email-limit:${projectId}`; -export const emailBurstLimitKey = (projectId: string) => `email-burst-limit:${projectId}`; - -/** Mirrors `getMonthlyLimit` in `packages/proxy/src/email.ts`. */ +/** Default monthly outbound recipient-attempt cap. */ export const DEFAULT_EMAIL_MONTHLY_LIMIT = 200; -/** Mirrors `getBurstLimit` in `packages/proxy/src/email.ts`. */ +/** Default per-minute outbound recipient-attempt cap. */ export const DEFAULT_EMAIL_BURST_LIMIT = 10; /** Highest override either writer accepts; bounds a typo, not a plan. */ export const MAX_EMAIL_LIMIT = 1_000_000; -/** - * Undefined means "no usable override" — either the key is absent or it - * holds a value the proxy would itself reject, in which case the proxy is - * already serving the default and every reader must say so too. - */ -export function parseEmailLimit(raw: string | null | undefined): number | undefined { - if (!raw) { - return undefined; - } - const n = parseInt(raw, 10); - return Number.isFinite(n) && n > 0 ? n : undefined; -} - -/** Strict form of `parseEmailLimit` for operator input: digits only, within the cap. */ +/** Parse a positive integer limit within the supported cap. */ export function parseEmailLimitInput(raw: string): number | undefined { if (!/^[1-9]\d*$/.test(raw)) { return undefined; diff --git a/platform/packages/api/src/email/relay-engine.ts b/platform/packages/api/src/email/relay-engine.ts deleted file mode 100644 index 0a11c1a2c..000000000 --- a/platform/packages/api/src/email/relay-engine.ts +++ /dev/null @@ -1,996 +0,0 @@ -/** - * Relay engine — the add / sync / remove orchestration for one - * `email_domains` row against the customer's Cloudflare account (design - * doc 0078, "The flow", and task contract 7). Pure-ish: every function - * takes the row plus an injectable customer-CF client and RETURNS the row - * fields to persist. The caller (the domains routes) owns the DB write, - * the ROUTING KV mirror, and all encryptProjectSecret work. - * - * Step order for setup: verify credential (api_token → /user/tokens/verify, - * oauth_grant → one refresh round-trip) → zone lookup (GET /zones?name=, - * walking the labels up to the registrable zone; also yields account_id) → - * MX check over public DNS (decides apex vs subdomain) → enable routing - * (POST routing/dns; empty body for apex, { name } for a subdomain) → - * onboard sending → claim the relay name → deploy relay + secret → - * catch-all → active. - * - * Setup is re-runnable — re-adding a `failed` row re-executes it against - * the row's recorded progress: a recorded mode skips the MX check (the - * first attempt's enable_routing put OUR MX on the domain, so a fresh - * lookup would fail on records we created), a recorded relay name - * redeploys in place (a name-walk would orphan the first relay under a - * fresh '-2'), and an 'already done' 400/409 from enable_routing / - * onboard_sending is believed ONLY when a read-back of the actual zone - * state confirms it — never on the status code alone. The catch-all is - * never written blind: it is zone-scoped with no domain parameter, so one - * PUT can hijack another domain's (or another tool's) inbound. Setup - * reads it first and refuses to overwrite an enabled rule it does not - * own; remove resets it only when it still names this row's relay. - * - * A persistProgress dep makes setup deliberately NON-total: the - * checkpoint fires once after the relay deploy and before the catch-all - * write, and its throw PROPAGATES so the route can abort setup when the - * mid-setup row persist fails. Dep-free calls keep today's totality — - * every failure still lands in the returned row fields. - * - * A claimRelayName dep reserves the walked relay name on the caller's own - * row BEFORE any CF upload (the route implements it as an UPDATE inside - * its serialized transaction): two setups racing one customer account - * serialize on the (account_id, relay_worker_name) unique index, so the - * loser's walk advances past the contested name instead of overwriting - * the winner's worker — first-to-claim, never last-write-wins. The dep - * is REQUIRED when the row carries no relay_worker_name: the walk throws - * without it rather than falling back to a CF-only probe, which would - * silently re-open that race. - * - * Failure rules: - * - Every orchestration failure leaves status 'failed' with - * setup_state.failed_step naming the step. Fields learned before the - * failure (zone_id, account_id, mode, …) are still returned so the row - * records how far it got. - * - A subdomain routing POST that fails is NOT a failure: that endpoint - * has no guaranteed token path (probe 8), so the dashboard form stays - * as the documented human step. It lands in - * setup_state.remaining_steps and the row stays 'pending'. - * - A dead credential maps to its own status: 'token_expired' / - * 'token_revoked' (contract 4's invalid_grant mapping included), never - * a bare 'failed'. - * - rotated_refresh_token is returned on EVERY outcome once a refresh - * happened — grant refresh tokens are single-use, so dropping the - * rotated value would kill the chain. The caller re-encrypts it into - * the token_* triple in the same transaction as the row update. - * - * `error` is for logs only and is never secret material: CF/OAuth error - * text names the failing field or grant code, not the credential values. - */ - -import { CloudflareApiError } from '../provisioning/cloudflare-api.ts'; -import type { EmailDomainSetupState } from '../schema.ts'; -import { OAuthGrantError, createCfCustomerClient, refreshOauthGrant } from './cf-customer.ts'; -import type { - CfCustomerClient, - CfCustomerZone, - CfTokenVerification, - OauthGrantTokens, -} from './cf-customer.ts'; -import { generateEmailRelaySecret } from './domains.ts'; -import type { EmailDomain } from './domains.ts'; -import { RELAY_COMPATIBILITY_DATE, RELAY_SOURCE, RELAY_VERSION } from './relay-worker.ts'; - -/** Base name for the relay worker; collisions within the account gain '-2', '-3'… */ -export const RELAY_WORKER_BASE_NAME = 'void-email-relay'; - -/** Human step recorded when the subdomain routing POST is refused. */ -export const ROUTING_SUBDOMAIN_STEP = 'routing_subdomain'; - -/** - * Plan step recorded when Email Sending onboarding is refused for - * entitlement (CF error codes 2036/10105 — Workers Free). Unlike - * routing_subdomain it is NOT inbound-blocking: Email Routing works on - * Free, so the relay and catch-all still deploy and the row can go - * active with this step recorded. Only the outbound lane (send_raw) - * stays refused until a plan upgrade; a sync re-attempts the onboarding - * POST, and the status GET self-clears the step on a confirming - * read-back. - */ -export const SENDING_ONBOARDING_STEP = 'sending_onboarding'; - -/** CF's entitlement refusal for Email Sending on a Workers Free account. */ -function isSendingEntitlementRefusal(err: unknown): boolean { - return ( - err instanceof CloudflareApiError && (err.codes.includes(2036) || err.codes.includes(10105)) - ); -} - -const MAX_RELAY_NAME_SUFFIX = 50; - -export type RelayEngineDeps = Readonly<{ - /** Builds a client bound to one credential; the oauth_grant path is called with the refreshed access token. */ - createClient?: (credential: string) => CfCustomerClient; - /** One refresh round-trip; defaults to the real OAuth token endpoint. */ - refreshGrant?: (refreshToken: string) => Promise; - /** - * RFC 7009 grant revocation (remove path only). Takes no token: the - * closure revokes the row's LIVE chain head (the serialized helper) — a - * token captured earlier may already be consumed by an interleaved - * refresh, and CF answers 200 for a consumed token either way. - * Deliberately has NO default: a caller that leaves its row alive must - * not revoke, so the engine revokes only when the caller explicitly - * supplies this. - */ - revokeGrant?: () => Promise; - /** Public-DNS MX lookup; defaults to DNS-over-HTTPS against cloudflare-dns.com. */ - lookupMx?: (domain: string) => Promise>; - /** Relay secret generator (sync rotation); defaults to generateEmailRelaySecret. */ - generateRelaySecret?: () => string; - /** - * Relay-name reservation for setup's name-walk: claims - * (accountId, candidate) on the caller's OWN row, inside the caller's - * serialized transaction (the route implements it with the same - * savepoint machinery as the deploy checkpoint). 'taken' means another - * row holds the name — the walk advances to the next suffix. Blocking - * semantics come from the (account_id, relay_worker_name) partial - * unique index: a concurrent claim waits on the winner's uncommitted - * UPDATE, then either proceeds (winner rolled back) or reports taken - * (winner committed) — one-directional, so no deadlock. REQUIRED - * whenever the row carries no relay_worker_name: the walk throws - * without it rather than probing CF alone, which would silently - * re-open the last-write-wins relay race. Never called on an in-place - * redeploy (the row already holds a name). - */ - claimRelayName?: (accountId: string, candidate: string) => Promise<'claimed' | 'taken'>; - /** - * Mid-setup progress checkpoint (setup only), fired ONCE right after - * the relay deploy + secret PUT succeed and BEFORE the catch-all write, - * with the seeded/learned zone/account/mode and the deployed relay - * name. Skipped on an in-place redeploy — a row that already carries - * relay_worker_name already knows. A throw PROPAGATES: with this dep - * supplied, setup is deliberately no longer total (the route relies on - * the throw to abort before the catch-all write); dep-free calls keep - * today's totality. - */ - persistProgress?: ( - progress: Readonly<{ - zone_id: string | null; - account_id: string | null; - mode: 'apex' | 'subdomain' | null; - relay_worker_name: string; - }>, - ) => Promise; -}>; - -export type EmailDomainSetupInput = Readonly<{ - /** - * domain + credential_kind always; mode + relay_worker_name + zone_id + - * account_id only on a re-run of a row that already got that far. They - * make the re-run idempotent (the header's re-runnable paragraph) AND - * they are seeded into the returned progress, so a re-run that fails - * EARLY (a dead credential) never erases what the row already learned — - * the next retry still skips the MX check and still knows its relay. - */ - row: Pick & - Partial>; - /** Decrypted credential: the pasted API token, the grant's refresh token, or the platform's runtime token. */ - credential: string; - /** Decrypted relay secret, handed to the relay worker as VOID_RELAY_SECRET. */ - relaySecret: string; - /** Baked into the relay as the VOID_PROXY_ORIGIN plain-text var. */ - proxyOrigin: string; - /** - * A `platform` row may only register a zone in the platform's own - * Cloudflare account: the runtime token must never be pointed at a - * customer zone. Setup fails at zone_lookup, before any write, when the - * zone's account differs. - */ - requireAccountId?: string; -}>; - -export type EmailDomainSyncInput = Readonly<{ - row: Pick & - // zone_id drives the catch-all ensure; absent/null → the ensure is - // skipped entirely (older callers pass no zone). - Partial> & { - /** - * The row's recorded remaining steps. When sending_onboarding is - * among them (a Workers Free refusal at setup), sync RE-ATTEMPTS - * the onboarding POST after the catch-all ensure — the post-plan- - * upgrade completion path — and reports it in cleared_steps. - */ - setup_remaining_steps?: ReadonlyArray; - }; - credential: string; - proxyOrigin: string; -}>; - -export type EmailDomainRemoveInput = Readonly<{ - row: Pick; - credential: string; - /** - * Conflict-compensation repoint target — the relay worker of the row - * that WON this zone. When set AND ≠ this row's own relay name, an - * owned catch-all is REPOINTED at the winner instead of reset, so the - * zone's inbound keeps working. Absent (or naming this row's own - * relay) → the plain reset path. - */ - repoint_catch_all_to?: string; -}>; - -/** The row-field update the caller persists; snake_case matches the drizzle columns. */ -export type EmailDomainSetupResult = Readonly<{ - status: EmailDomain['status']; - zone_id: string | null; - account_id: string | null; - mode: EmailDomain['mode']; - relay_worker_name: string | null; - relay_version: number | null; - token_id: string | null; - token_expires_on: string | null; - setup_state: EmailDomainSetupState | null; - rotated_refresh_token?: string; - error?: string; -}>; - -export type EmailDomainSyncResult = Readonly<{ - status: EmailDomain['status']; - relay_version: number | null; - setup_state: EmailDomainSetupState | null; - /** - * The catch-all ensure outcome — present only when the row carries a - * zone_id AND the redeploy succeeded: - * - 'ensured' — a missing, disabled, or non-worker rule was - * (re-)pointed at this row's relay; - * - 'already_set' — the enabled rule already named this row's relay; - * - 'foreign_conflict' — an ENABLED rule names a DIFFERENT worker: - * reported, never overwritten (the drift doctrine: report, don't - * fight); - * - 'probe_failed' — the ownership read or the write failed; - * non-fatal, the redeploy/rotation still succeeded. - */ - catch_all?: 'ensured' | 'already_set' | 'foreign_conflict' | 'probe_failed'; - /** - * Remaining steps the sync itself completed (the sending-onboarding - * retry) — the caller subtracts them from the row's recorded - * remaining_steps instead of carrying them verbatim. - */ - cleared_steps?: ReadonlyArray; - /** Fresh relay secret — the caller re-encrypts it into relay_* and sha256s it into the mirror. */ - new_relay_secret?: string; - rotated_refresh_token?: string; - error?: string; -}>; - -export type EmailDomainRemoveResult = Readonly<{ - /** CF-side steps that failed. Removal of the row and mirror key proceeds regardless. */ - failed_steps: ReadonlyArray; -}>; - -function errorMessage(err: unknown): string { - return err instanceof Error ? err.message : String(err); -} - -const defaultCreateClient = (credential: string): CfCustomerClient => - createCfCustomerClient(credential); - -/** - * Default MX check: DNS-over-HTTPS against cloudflare-dns.com's JSON API. - * Returns the MX exchange hostnames (priority and trailing dot stripped). - * Public DNS — no credential involved. - */ -export async function lookupMxOverDns(domain: string): Promise> { - const response = await fetch( - `https://cloudflare-dns.com/dns-query?name=${encodeURIComponent(domain)}&type=MX`, - { headers: { accept: 'application/dns-json' } }, - ); - if (!response.ok) { - throw new Error(`public DNS MX lookup failed with HTTP ${response.status}`); - } - const json = (await response.json()) as { - Answer?: ReadonlyArray<{ type: number; data: string }>; - }; - return (json.Answer ?? []) - .filter((answer) => answer.type === 15) - .map((answer) => answer.data.trim().split(/\s+/).slice(1).join(' ').replace(/\.$/, '')); -} - -/** - * The enable_routing idempotency read-back: GET email/routing's `enabled` - * (a required boolean in the API schema). False on any failure or - * unparseable shape — the caller then surfaces the original POST error. - */ -async function routingEnabledReadback(client: CfCustomerClient, zoneId: string): Promise { - try { - const settings = await client.getRoutingSettings(zoneId); - return ( - settings !== null && - typeof settings === 'object' && - (settings as { enabled?: unknown }).enabled === true - ); - } catch { - return false; - } -} - -/** - * The onboard_sending idempotency read-back: the sending-subdomain list - * carries an entry named for the email domain with `enabled` true. False - * on any failure — fail-closed, like routingEnabledReadback. Whether the - * ZONE APEX itself appears in this list is unpinned (probe 8), so an - * apex re-run whose onboard actually succeeded may still fail with the - * original CF error; the message names the step either way. - */ -export async function sendingOnboardedReadback( - client: CfCustomerClient, - zoneId: string, - domain: string, -): Promise { - try { - const subdomains = await client.listSendingSubdomains(zoneId); - return subdomains.some( - (subdomain) => subdomain.enabled && subdomain.name.toLowerCase() === domain.toLowerCase(), - ); - } catch { - return false; - } -} - -/** - * The status route's self-clear probe for the routing-subdomain human - * step: the dashboard form's observable effect is public MX records - * naming Cloudflare's inbound exchanges (route1..3.mx.cloudflare.net). - * False on lookup failure — a pending row simply stays pending and the - * next status poll retries. - */ -export async function domainHasRoutingMx(domain: string): Promise { - try { - const mx = await lookupMxOverDns(domain); - return mx.some((exchange) => exchange.toLowerCase().endsWith('.mx.cloudflare.net')); - } catch { - return false; - } -} - -/** - * The zone is the deepest suffix of the email domain that exists as a zone - * in an account the credential can see (mail.acme.com → acme.com, or the - * subdomain itself on an Enterprise subdomain setup). Errors propagate. - */ -export async function findZoneForEmailDomain( - client: CfCustomerClient, - domain: string, -): Promise { - const labels = domain.split('.'); - for (let start = 0; start <= labels.length - 2; start++) { - const zone = await client.findZone(labels.slice(start).join('.')); - if (zone) { - return zone; - } - } - return null; -} - -type CredentialResolution = - | Readonly<{ - ok: true; - client: CfCustomerClient; - token_id: string | null; - token_expires_on: string | null; - rotated_refresh_token?: string; - }> - | Readonly<{ ok: false; status: 'failed' | 'token_revoked' | 'token_expired'; error: string }>; - -/** - * Setup step 1. api_token rows verify via GET /user/tokens/verify (which - * also yields token_id/expires_on for `status` output); oauth_grant rows - * verify by running one refresh round-trip and continuing on the fresh - * access token. `platform` rows carry the runtime token, which is not a - * user token: there is nothing to verify up front, and the first - * authenticated step (zone_lookup) fails the row with Cloudflare's own - * message when a permission is missing. - */ -async function resolveCredential( - credentialKind: EmailDomain['credential_kind'], - credential: string, - deps: RelayEngineDeps, -): Promise { - const createClient = deps.createClient ?? defaultCreateClient; - if (credentialKind === 'platform') { - return { ok: true, client: createClient(credential), token_id: null, token_expires_on: null }; - } - if (credentialKind === 'api_token') { - const client = createClient(credential); - let verification: CfTokenVerification; - try { - verification = await client.verifyToken(); - } catch (err) { - return { ok: false, status: 'failed', error: errorMessage(err) }; - } - if (verification.status === 'expired') { - return { ok: false, status: 'token_expired', error: 'the Cloudflare API token is expired' }; - } - if (verification.status !== 'active') { - return { - ok: false, - status: 'token_revoked', - error: `the Cloudflare API token is ${verification.status}, not active`, - }; - } - return { - ok: true, - client, - token_id: verification.id, - token_expires_on: verification.expires_on ?? null, - }; - } - let tokens: OauthGrantTokens; - try { - tokens = await (deps.refreshGrant ?? refreshOauthGrant)(credential); - } catch (err) { - if (err instanceof OAuthGrantError && err.code === 'invalid_grant') { - return { - ok: false, - status: 'token_revoked', - error: 'the Cloudflare OAuth grant was revoked', - }; - } - return { ok: false, status: 'failed', error: errorMessage(err) }; - } - return { - ok: true, - client: createClient(tokens.accessToken), - token_id: null, - token_expires_on: null, - rotated_refresh_token: tokens.refreshToken, - }; -} - -export async function setupEmailDomain( - input: EmailDomainSetupInput, - deps: RelayEngineDeps = {}, -): Promise { - const lookupMx = deps.lookupMx ?? lookupMxOverDns; - // Seed from the row on a re-run: a failure before the step that re-learns - // a value must still return the recorded one, or a dead-credential retry - // would erase the row's progress (see the input contract). - const progress = { - zone_id: input.row.zone_id ?? null, - account_id: input.row.account_id ?? null, - mode: input.row.mode ?? null, - relay_worker_name: input.row.relay_worker_name ?? null, - token_id: null as string | null, - token_expires_on: null as string | null, - }; - const remainingSteps: Array = []; - - // Step 1: verify the credential. - const resolved = await resolveCredential(input.row.credential_kind, input.credential, deps); - // Carried on every outcome — grant refresh tokens are single-use, so a - // failure after a successful refresh must still return the rotated value - // for the caller to persist (see the header). - const rotatedRefreshToken: string | undefined = resolved.ok - ? resolved.rotated_refresh_token - : undefined; - - const failWith = ( - status: 'failed' | 'token_revoked' | 'token_expired', - step: string, - message: string, - ): EmailDomainSetupResult => ({ - status, - ...progress, - relay_version: null, - setup_state: { - failed_step: step, - ...(remainingSteps.length > 0 ? { remaining_steps: remainingSteps } : {}), - }, - ...(rotatedRefreshToken === undefined ? {} : { rotated_refresh_token: rotatedRefreshToken }), - error: message, - }); - const fail = (step: string, err: unknown): EmailDomainSetupResult => - failWith('failed', step, errorMessage(err)); - - if (!resolved.ok) { - return failWith(resolved.status, 'verify_credential', resolved.error); - } - progress.token_id = resolved.token_id; - progress.token_expires_on = resolved.token_expires_on; - const client = resolved.client; - - // Step 2: zone lookup. Also yields account_id. - let zone: CfCustomerZone | null; - try { - zone = await findZoneForEmailDomain(client, input.row.domain); - } catch (err) { - return fail('zone_lookup', err); - } - if (!zone) { - return failWith( - 'failed', - 'zone_lookup', - `no Cloudflare zone found for ${input.row.domain} in an account this credential can see`, - ); - } - if (input.requireAccountId !== undefined && zone.account.id !== input.requireAccountId) { - return failWith( - 'failed', - 'zone_lookup', - `zone for ${input.row.domain} is in Cloudflare account ${zone.account.id}, not the platform's account ${input.requireAccountId}; register it with --token-stdin and a token for that account`, - ); - } - progress.zone_id = zone.id; - progress.account_id = zone.account.id; - - // Step 3: MX check over public DNS. A domain already carrying MX has a - // mail setup Email Routing would fight — apex or subdomain alike. Only - // an MX-empty zone apex takes the apex path; anything else must be a - // subdomain (the CLI proposes mail. up front). Skipped on a - // re-run: the first attempt's enable_routing put OUR MX on the domain, - // and the recorded mode stands. - if (input.row.mode) { - progress.mode = input.row.mode; - } else { - let mx: ReadonlyArray; - try { - mx = await lookupMx(input.row.domain); - } catch (err) { - return fail('mx_check', err); - } - if (mx.length > 0) { - return failWith( - 'failed', - 'mx_check', - `${input.row.domain} already carries MX (${mx.join(', ')}) — add a subdomain such as mail.${zone.name} instead`, - ); - } - progress.mode = - input.row.domain.toLowerCase() === zone.name.toLowerCase() ? 'apex' : 'subdomain'; - } - - // Step 4: enable Email Routing. - if (progress.mode === 'apex') { - try { - await client.enableRouting(zone.id); - } catch (err) { - // A re-run re-POSTs over the first attempt's success. A 400/409 is - // 'already enabled' ONLY when the settings read-back agrees — - // anything else is the original error (fail-closed). - if ( - !( - err instanceof CloudflareApiError && - (err.status === 400 || err.status === 409) && - (await routingEnabledReadback(client, zone.id)) - ) - ) { - return fail('enable_routing', err); - } - } - } else { - try { - await client.enableRouting(zone.id, input.row.domain); - } catch { - // No guaranteed token path (probe 8) — the dashboard form is the - // documented fallback. Record the human step and finish the rest. - remainingSteps.push(ROUTING_SUBDOMAIN_STEP); - } - } - - // Step 5: onboard sending (cf-bounce MX, SPF, DKIM, DMARC). Same - // re-run read-back as step 4, through the sending-subdomain list. An - // ENTITLEMENT refusal (Workers Free) is not fatal: Email Routing needs - // no paid plan, so the inbound lane deploys anyway and the step is - // recorded for a post-upgrade sync — only the outbound lane (send_raw) - // stays refused at CF until then. - try { - await client.onboardSending(zone.id, input.row.domain); - } catch (err) { - if (isSendingEntitlementRefusal(err)) { - remainingSteps.push(SENDING_ONBOARDING_STEP); - } else if ( - !( - err instanceof CloudflareApiError && - (err.status === 400 || err.status === 409) && - (await sendingOnboardedReadback(client, zone.id, input.row.domain)) - ) - ) { - return fail('onboard_sending', err); - } - } - - // Step 6: pick a free relay name — or reuse the recorded one, since a - // re-run redeploys IN PLACE (the name-walk would take a fresh '-2' and - // orphan the first relay; renaming detaches routing rules). A walked - // name is CLAIMED on the row via the claimRelayName dep BEFORE the - // upload, so two setups racing one account can't both deploy the same - // name (see claimFreeRelayName). The name lands in progress the moment - // it is chosen, BEFORE the fallible writes: a failed upload or secret - // PUT then still records it on the row, so a retry redeploys in place - // and a remove can find the worker — an unrecorded upload would leak - // it and walk the next retry to '-2'. - let relayWorkerName: string; - try { - relayWorkerName = - input.row.relay_worker_name ?? - (await claimFreeRelayName(client, zone.account.id, deps.claimRelayName)); - } catch (err) { - return fail('deploy_relay', err); - } - progress.relay_worker_name = relayWorkerName; - try { - await client.putRelayScript(zone.account.id, relayWorkerName, { - source: RELAY_SOURCE, - compatibilityDate: RELAY_COMPATIBILITY_DATE, - proxyOrigin: input.proxyOrigin, - emailDomain: input.row.domain, - }); - await client.putRelaySecret(zone.account.id, relayWorkerName, input.relaySecret); - } catch (err) { - return fail('deploy_relay', err); - } - - // Checkpoint: let the caller persist the mid-setup progress BEFORE the - // catch-all write, so a failed row persist aborts setup here rather - // than after a zone-scoped rule was written. Fresh deploys only — an - // in-place redeploy means the row already carries the relay name. A dep - // throw PROPAGATES by design (see RelayEngineDeps.persistProgress). - if (deps.persistProgress && !input.row.relay_worker_name) { - await deps.persistProgress({ - zone_id: progress.zone_id, - account_id: progress.account_id, - mode: progress.mode, - relay_worker_name: relayWorkerName, - }); - } - - // Step 7: point the zone's catch-all at the relay — but only after an - // ownership read. The catch-all is zone-scoped with no domain - // parameter: a blind PUT can hijack another domain's (or another - // tool's) inbound. An enabled rule naming anything but our relay is a - // conflict; one already naming our relay is a re-run — nothing to write. - let catchAllAlreadyOurs = false; - try { - const existing = await client.getCatchAll(zone.id); - if (existing && existing.enabled) { - if (existing.workerName === relayWorkerName) { - catchAllAlreadyOurs = true; - } else { - return failWith( - 'failed', - 'catch_all', - existing.workerName === null - ? `the zone catch-all for ${zone.name} is enabled with a non-worker action — disable it in the Cloudflare dashboard first` - : `the zone catch-all for ${zone.name} already routes to worker '${existing.workerName}' — one zone routes one email domain; remove the other domain first`, - ); - } - } - } catch (err) { - return fail('catch_all', err); - } - if (!catchAllAlreadyOurs) { - try { - await client.setCatchAll(zone.id, relayWorkerName); - } catch (err) { - return fail('catch_all', err); - } - } - - return { - // Only an inbound-blocking step holds the row at 'pending': a lone - // sending_onboarding step leaves inbound live (the proxy gates on the - // mirror's active status), with outbound refused at CF until a plan - // upgrade and a sync complete it. - status: remainingSteps.includes(ROUTING_SUBDOMAIN_STEP) ? 'pending' : 'active', - ...progress, - relay_version: RELAY_VERSION, - setup_state: remainingSteps.length > 0 ? { remaining_steps: remainingSteps } : null, - ...(rotatedRefreshToken === undefined ? {} : { rotated_refresh_token: rotatedRefreshToken }), - }; -} - -/** - * Setup step 6's name-walk: the base name, then '-2', '-3'… on collision - * within the account (a second registered domain of the same customer). - * Each candidate is CF-probed first — a physically occupied name (an - * orphan, or a worker the customer created out-of-band) is skipped - * without spending a claim — then CLAIMED via the claimRelayName dep - * BEFORE any upload: two setups racing one account serialize on the - * (account_id, relay_worker_name) unique index, so a concurrent claim - * either blocks past the winner's commit and 23505s ('taken' — the walk - * advances) or proceeds past its rollback. First-to-claim wins; the - * loser's walk never writes the contested worker. The dep is REQUIRED — - * a CF-only walk would re-open exactly that race. The caller records the - * chosen name before any fallible write; the name is stable once chosen - * — renaming a worker detaches every routing rule pointing at it, so - * sync redeploys in place and never re-walks. - */ -async function claimFreeRelayName( - client: CfCustomerClient, - accountId: string, - claimRelayName: RelayEngineDeps['claimRelayName'], -): Promise { - if (!claimRelayName) { - throw new Error( - 'the claimRelayName dep is required when setup walks relay names (the row carries none)', - ); - } - for (let suffix = 1; suffix <= MAX_RELAY_NAME_SUFFIX; suffix++) { - const candidate = suffix === 1 ? RELAY_WORKER_BASE_NAME : `${RELAY_WORKER_BASE_NAME}-${suffix}`; - if (await client.relayScriptExists(accountId, candidate)) { - continue; - } - if ((await claimRelayName(accountId, candidate)) === 'claimed') { - return candidate; - } - } - throw new Error( - `no free relay worker name in this account (${RELAY_WORKER_BASE_NAME}-1..${MAX_RELAY_NAME_SUFFIX} all taken)`, - ); -} - -/** - * `void email domain sync`: redeploy the relay in place at the current - * RELAY_VERSION and rotate its secret. Rotation is overwrite, never - * read-compare (worker secrets are write-only). The caller re-encrypts the - * new secret and updates the KV mirror's sha256; inbound is rejected - * between the secret PUT and the mirror update, so sync re-mirrors - * immediately after. - * - * When the row carries a zone_id, sync also ENSURES the zone catch-all - * after a successful redeploy: a missing, disabled, or non-worker rule is - * (re-)pointed at this row's relay ('ensured'), and an enabled rule - * already naming it is left alone ('already_set'). An ENABLED rule naming - * a DIFFERENT worker is reported ('foreign_conflict'), never overwritten - * — the drift doctrine is report, don't fight. A failed probe or write - * lands in 'probe_failed', non-fatal: the redeploy and rotation already - * succeeded and must still report success. - * - * When the caller passes a row whose remaining steps include - * sending_onboarding (a Workers Free entitlement refusal at setup), sync - * also RE-ATTEMPTS the onboarding POST — the completion path after a - * plan upgrade — and reports it in cleared_steps; a repeated refusal or - * any other failure keeps the step, non-fatally. - */ -export async function syncEmailDomain( - input: EmailDomainSyncInput, - deps: RelayEngineDeps = {}, -): Promise { - const { account_id, relay_worker_name } = input.row; - if (!account_id || !relay_worker_name) { - return { - status: 'failed', - relay_version: null, - setup_state: { failed_step: 'deploy_relay' }, - error: 'relay worker was never deployed — run the full setup first', - }; - } - const resolved = await resolveCredential(input.row.credential_kind, input.credential, deps); - if (!resolved.ok) { - return { - status: resolved.status, - relay_version: null, - setup_state: { failed_step: 'verify_credential' }, - error: resolved.error, - }; - } - const newRelaySecret = (deps.generateRelaySecret ?? generateEmailRelaySecret)(); - try { - await resolved.client.putRelayScript(account_id, relay_worker_name, { - source: RELAY_SOURCE, - compatibilityDate: RELAY_COMPATIBILITY_DATE, - proxyOrigin: input.proxyOrigin, - emailDomain: input.row.domain, - }); - await resolved.client.putRelaySecret(account_id, relay_worker_name, newRelaySecret); - } catch (err) { - return { - status: 'failed', - relay_version: null, - setup_state: { failed_step: 'deploy_relay' }, - ...(resolved.rotated_refresh_token === undefined - ? {} - : { rotated_refresh_token: resolved.rotated_refresh_token }), - error: errorMessage(err), - }; - } - // Catch-all ensure (the header's drift doctrine). A probe or write - // failure is non-fatal: the redeploy/rotation above already succeeded. - let catchAll: EmailDomainSyncResult['catch_all']; - if (input.row.zone_id) { - try { - const existing = await resolved.client.getCatchAll(input.row.zone_id); - if (existing !== null && existing.enabled) { - if (existing.workerName === relay_worker_name) { - catchAll = 'already_set'; - } else if (existing.workerName !== null) { - // An enabled rule naming another worker — never overwrite it. - catchAll = 'foreign_conflict'; - } - } - if (catchAll === undefined) { - // Absent, disabled, or enabled with a non-worker action. - await resolved.client.setCatchAll(input.row.zone_id, relay_worker_name); - catchAll = 'ensured'; - } - } catch { - catchAll = 'probe_failed'; - } - } - // Sending-onboarding retry — only when setup recorded the step (a - // Workers Free entitlement refusal). A success, or a confirming - // read-back behind a 400/409, clears the step; a repeated entitlement - // refusal or any other error keeps it, non-fatally — the redeploy and - // rotation already succeeded and outbound stays refused at CF. - let clearedSteps: ReadonlyArray | undefined; - if (input.row.zone_id && input.row.setup_remaining_steps?.includes(SENDING_ONBOARDING_STEP)) { - try { - await resolved.client.onboardSending(input.row.zone_id, input.row.domain); - clearedSteps = [SENDING_ONBOARDING_STEP]; - } catch (err) { - if ( - err instanceof CloudflareApiError && - (err.status === 400 || err.status === 409) && - (await sendingOnboardedReadback(resolved.client, input.row.zone_id, input.row.domain)) - ) { - clearedSteps = [SENDING_ONBOARDING_STEP]; - } - } - } - return { - status: 'active', - relay_version: RELAY_VERSION, - setup_state: null, - ...(catchAll === undefined ? {} : { catch_all: catchAll }), - ...(clearedSteps === undefined ? {} : { cleared_steps: clearedSteps }), - new_relay_secret: newRelaySecret, - ...(resolved.rotated_refresh_token === undefined - ? {} - : { rotated_refresh_token: resolved.rotated_refresh_token }), - }; -} - -/** - * `void email domain remove`: best-effort CF cleanup — DELETE the relay - * script, then reset the zone catch-all (wrangler's drop-and-disable - * shape). Never throws: a revoked credential strands the relay and the - * rule in the customer's account, and neither may strand the row or the - * mirror key, which the caller deletes unconditionally. - * - * The catch-all reset is CONDITIONAL and runs BEFORE the relay delete: - * the rule is zone-scoped, so it is only reset when the ownership read - * shows it still naming this row's relay — a rule pointing at another - * worker (the customer repointed it, or a pre-fix second domain claimed - * it) is left alone, and a row whose relay never deployed never wrote a - * rule in the first place. If the ownership read or the reset fails, the - * relay is NOT deleted either: an enabled catch-all must never be left - * pointing at a deleted worker (the zone would bounce with no retry - * handle once the caller deletes the row and mirror), so the rule and - * its relay stay a consistent pair and both steps report failed. - * - * `repoint_catch_all_to` (conflict compensation): when the caller knows - * the relay of the row that WON this zone, an owned catch-all is - * REPOINTED at the winner instead of reset — the zone's inbound keeps - * working rather than going dark. The winner's existence is checked - * before AND after the PUT, so a winner deleted mid-compensation falls - * back to the reset and the window is bounded to one CF round-trip. A - * target that is absent, missing at CF, or names this row's own relay - * takes the plain reset path, and any repoint-path failure reports - * 'catch_all' and keeps the consistent pair, exactly like a reset - * failure. - * - * `revokeGrant` dep (oauth_grant rows only): the grant is revoked as the - * LAST step, after the CF cleanup attempts. The dep takes no token — it - * revokes the row's LIVE chain head (callers pass the serialized helper): - * a token captured earlier, the rotated one included, may already be - * consumed by a lease refresh interleaved with the cleanup calls, and CF - * answers 200 for a consumed token whether or not the grant survived. A - * transient refresh failure revokes too (the stored token may still be - * live and the row holding it is about to disappear); an invalid_grant - * failure skips the revoke (CF already killed the grant). A revoke - * rejection appends 'revoke_grant' to failed_steps and never throws. - * api_token rows never revoke. The conflict-compensation caller - * deliberately passes NO revokeGrant dep: it leaves its own row alive, - * and revoking would brick the credential that row still owns. - */ -export async function removeEmailDomain( - input: EmailDomainRemoveInput, - deps: RelayEngineDeps = {}, -): Promise { - const failedSteps: Array = []; - let credential = input.credential; - let grantRefreshed = false; - if (input.row.credential_kind === 'oauth_grant') { - try { - const tokens = await (deps.refreshGrant ?? refreshOauthGrant)(input.credential); - credential = tokens.accessToken; - grantRefreshed = true; - } catch (err) { - failedSteps.push('delete_relay', 'catch_all'); - // invalid_grant means CF already killed the grant — nothing left to - // revoke. Any other (transient) failure leaves the stored refresh - // token possibly live: revoke it now, before the row holding it is - // deleted. - if (deps.revokeGrant && !(err instanceof OAuthGrantError && err.code === 'invalid_grant')) { - try { - await deps.revokeGrant(); - } catch { - failedSteps.push('revoke_grant'); - } - } - return { failed_steps: failedSteps }; - } - } - const client = (deps.createClient ?? defaultCreateClient)(credential); - // Detach first, delete second (the header's consistent-pair rule). - let detachFailed = false; - if (input.row.zone_id && input.row.relay_worker_name) { - let catchAllIsOurs = false; - try { - const existing = await client.getCatchAll(input.row.zone_id); - catchAllIsOurs = - existing !== null && - existing.enabled && - existing.workerName === input.row.relay_worker_name; - } catch { - // Ownership unreadable — leave the rule untouched and report it. - detachFailed = true; - } - if (catchAllIsOurs) { - // Conflict compensation: with a winning relay named, REPOINT the - // owned rule at the winner instead of resetting it. The winner's - // existence is checked before AND after the PUT — a winner deleted - // mid-compensation falls back to the reset, bounding the window to - // one CF round-trip. Any failure here keeps the rule-and-relay - // pair consistent, exactly like a reset failure. - const repointTarget = - input.repoint_catch_all_to !== undefined && - input.repoint_catch_all_to !== input.row.relay_worker_name - ? input.repoint_catch_all_to - : null; - const repointAccountId = input.row.account_id; - try { - if ( - repointTarget !== null && - repointAccountId !== null && - (await client.relayScriptExists(repointAccountId, repointTarget)) - ) { - await client.setCatchAll(input.row.zone_id, repointTarget); - if (!(await client.relayScriptExists(repointAccountId, repointTarget))) { - // The winner vanished under the PUT — fall back to the reset. - await client.resetCatchAll(input.row.zone_id); - } - } else { - await client.resetCatchAll(input.row.zone_id); - } - } catch { - detachFailed = true; - } - } - if (detachFailed) { - failedSteps.push('catch_all'); - } - } - if (input.row.account_id && input.row.relay_worker_name) { - if (detachFailed) { - // Not attempted, deliberately: the enabled rule keeps its worker. - failedSteps.push('delete_relay'); - } else { - try { - await client.deleteRelayScript(input.row.account_id, input.row.relay_worker_name); - } catch { - failedSteps.push('delete_relay'); - } - } - } - // Grant revocation is the LAST step, after the CF cleanup attempts. The - // dep revokes the row's live chain head — NOT the token this run - // rotated: a lease refresh interleaved with the cleanup calls above - // would already have consumed it, and revoking a consumed token answers - // 200 while the newer grant lives on. A rejection is reported, never - // thrown: the row removal proceeds regardless. - if (grantRefreshed && deps.revokeGrant) { - try { - await deps.revokeGrant(); - } catch { - failedSteps.push('revoke_grant'); - } - } - return { failed_steps: failedSteps }; -} diff --git a/platform/packages/api/src/email/relay-worker.ts b/platform/packages/api/src/email/relay-worker.ts index 060ee5abd..079251d0e 100644 --- a/platform/packages/api/src/email/relay-worker.ts +++ b/platform/packages/api/src/email/relay-worker.ts @@ -28,9 +28,6 @@ export const RELAY_GATEWAY_ORIGIN_BINDING = 'VOID_EMAIL_GATEWAY_ORIGIN'; export const RELAY_ACCOUNT_BINDING = 'VOID_EMAIL_ACCOUNT'; export const RELAY_ZONE_BINDING = 'VOID_EMAIL_ZONE'; export const RELAY_INGRESS_BINDING = 'VOID_EMAIL_INGRESS'; -// Legacy exports keep older pre-release fixtures compiling. -export const RELAY_PROXY_ORIGIN_BINDING = RELAY_GATEWAY_ORIGIN_BINDING; -export const RELAY_EMAIL_DOMAIN_BINDING = RELAY_ZONE_BINDING; /** * Module-syntax Worker source. POST /email/ingress on the configured gateway diff --git a/platform/packages/api/src/index.ts b/platform/packages/api/src/index.ts index 20a7bbb5e..bbf92ac85 100644 --- a/platform/packages/api/src/index.ts +++ b/platform/packages/api/src/index.ts @@ -75,7 +75,6 @@ import { deleteCustomHostname, getCustomHostname, } from './provisioning/cloudflare-api.ts'; -import { isReservedEmailSlug } from './reserved-slugs.ts'; import { oidcRoutes } from './routes/auth-oidc.ts'; import auth from './routes/auth.ts'; import deleteRoute from './routes/delete.ts'; @@ -852,47 +851,6 @@ async function processUserRollover( user: { id: string; plan: string; billing_cycle_start: string; suspended_reason: string | null }, userProjects: ReadonlyArray<{ id: string; slug: string }>, ): Promise { - // Backfill the `email-slug:` mirror. It is written - // best-effort at createProject time, so a transient KV blip during - // create would leave a project permanently unsendable (the proxy's - // /email/send answers 502 'project slug unknown' without it). - // Re-write it idempotently on every hourly pass so a missing — or - // stale, after a project rename — mirror heals with no operator - // action. In its own try/catch, ahead of the routing-JSON backfill - // below: that block throws out on a malformed routing entry every - // pass, so sharing its try/catch would hold the mirror hostage to one - // bad entry (and vice versa) — neither may block the other, and - // neither may block rollover/unsuspension. - // - // A project whose slug is an email identity (`EMAIL_RESERVED_SLUGS`: - // `noreply`, `postmaster`, …) gets NO mirror. Those slugs were reserved - // only when email shipped, so a project registered earlier can still - // hold one, and the create-time check never sees it; the mirror is what - // authorizes `/email/send`, so withholding it keeps the proxy's answer - // at 502 for that project. A mirror written before the slug was - // reserved is deleted here — this pass is the migration — and the - // proxy refuses the slug on its own as well, for the hour until it is. - try { - for (const project of userProjects) { - const emailSlugKey = `email-slug:${project.id}`; - const existingSlug = await env.ROUTING.get(emailSlugKey); - if (isReservedEmailSlug(project.slug)) { - if (existingSlug !== null) { - await env.ROUTING.delete(emailSlugKey); - console.warn( - `[backfill] removed email-slug mirror for project ${project.id}: "${project.slug}" is a reserved email identity`, - ); - } - continue; - } - if (existingSlug !== project.slug) { - await env.ROUTING.put(emailSlugKey, project.slug); - } - } - } catch (err) { - console.error(`[backfill] email-slug backfill failed for user ${user.id}:`, err); - } - // Backfill userId into old KV routing entries (all plans, before early return). // Wrapped in try/catch so a malformed KV entry doesn't block rollover/unsuspension. try { diff --git a/platform/packages/api/src/operator/email-routes.ts b/platform/packages/api/src/operator/email-routes.ts index 36821f859..2b0814ea9 100644 --- a/platform/packages/api/src/operator/email-routes.ts +++ b/platform/packages/api/src/operator/email-routes.ts @@ -5,6 +5,7 @@ import { capabilityMiddleware } from '../capabilities.ts'; import { getProject, getProjectBySlug, type Db } from '../db.ts'; import { emailProjectControls } from '../email/admission-schema.ts'; import { setProjectEmailLimits } from '../email/admission.ts'; +import { lookupMxOverDns } from '../email/cf-domain-probes.ts'; import { emailDomainRoutes, emailZoneConnections } from '../email/connection-schema.ts'; import { MAX_DOMAIN_LENGTH, @@ -20,14 +21,7 @@ import { serializeEmailRoute, syncEmailDomainForProject, } from '../email/domain-service.ts'; -import { - emailBurstLimitKey, - emailMonthlyLimitKey, - parseEmailLimit, - parseEmailLimitInput, - MAX_EMAIL_LIMIT, -} from '../email/limits.ts'; -import { lookupMxOverDns } from '../email/relay-engine.ts'; +import { parseEmailLimitInput, MAX_EMAIL_LIMIT } from '../email/limits.ts'; import { EmailSettingsError, getEmailDomainManagement, @@ -421,24 +415,21 @@ export async function syncOperatorEmailDomain( export async function removeOperatorEmailDomain( context: Context, rawDomain: string, - force: boolean, dryRunRequested = false, ) { const { domain, row, project } = await requireDomainRow(context.get('db'), rawDomain); const action = 'email.domain.remove'; - const target = { domain, projectId: project.id, slug: project.slug, force }; + const target = { domain, projectId: project.id, slug: project.slug }; if (dryRunRequested) { return preview(action, target, { status: row.inbound_status, managed_by: row.managed_by, connection_id: row.connection_id, - effect: force - ? 'Disables the assignment and records any unresolved provider cleanup for manual recovery.' - : 'Disables this assignment; shared ingress remains while sibling domains use it.', + effect: 'Disables this assignment; shared ingress remains while sibling domains use it.', }); } return operatorResult( - await removeEmailDomainForProject(context, project, domain, force, 'admin'), + await removeEmailDomainForProject(context, project, domain, 'admin'), action, target, ); @@ -448,6 +439,7 @@ export async function rotateOperatorEmailIngressSecret( context: Context, rawDomain: string, dryRunRequested = false, + attemptId?: string, ) { const { domain, row, project } = await requireDomainRow(context.get('db'), rawDomain); const action = 'email.domain.rotate-secret', @@ -459,7 +451,7 @@ export async function rotateOperatorEmailIngressSecret( }); } return operatorResult( - await rotateEmailIngressSecretForProject(context, project, domain, 'admin'), + await rotateEmailIngressSecretForProject(context, project, domain, 'admin', attemptId), action, target, ); @@ -494,20 +486,17 @@ emailOperatorRoutes.post('/email/domains/:domain/sync', async (context) => { emailOperatorRoutes.post('/email/domains/:domain/rotate-secret', async (context) => { const body = await readBody(context); return context.json( - await rotateOperatorEmailIngressSecret(context, context.req.param('domain'), dryRun(body)), + await rotateOperatorEmailIngressSecret( + context, + context.req.param('domain'), + dryRun(body), + body.attemptId === undefined ? undefined : stringField(body, 'attemptId', { maxLength: 128 }), + ), ); }); emailOperatorRoutes.post('/email/domains/:domain/remove', async (context) => { const body = await readBody(context); - if (body.force !== undefined && typeof body.force !== 'boolean') { - throw new OperatorError(400, 'force must be a boolean.', 'invalid_argument'); - } return context.json( - await removeOperatorEmailDomain( - context, - context.req.param('domain'), - body.force === true, - dryRun(body), - ), + await removeOperatorEmailDomain(context, context.req.param('domain'), dryRun(body)), ); }); diff --git a/platform/packages/api/src/provisioning/cleanup.ts b/platform/packages/api/src/provisioning/cleanup.ts index 4eabb3200..831b82ff0 100644 --- a/platform/packages/api/src/provisioning/cleanup.ts +++ b/platform/packages/api/src/provisioning/cleanup.ts @@ -19,13 +19,6 @@ import { import { drainProjectEmailAdmissions } from '../email/admission.ts'; import { emailDomainRoutes } from '../email/connection-schema.ts'; import { requestEmailDomainRemove, runEmailOperation } from '../email/connection-service.ts'; -import { - refreshOauthGrantSerialized, - revokeOauthGrantSerialized, -} from '../email/credential-lease.ts'; -import { clearEmailDomainMirror, decryptEmailDomainToken } from '../email/domains.ts'; -import type { EmailDomain } from '../email/domains.ts'; -import { removeEmailDomain } from '../email/relay-engine.ts'; import type { ApiEnv } from '../env.ts'; import { cancelContainerBuildDos } from '../github/cancel-builds.ts'; import { @@ -33,11 +26,7 @@ import { getProjectDeploymentWorkerName, getProjectQueueName, } from '../naming.ts'; -import { - deployments as deploymentsTable, - emailDomains, - projects as projectsTable, -} from '../schema.ts'; +import { deployments as deploymentsTable, projects as projectsTable } from '../schema.ts'; import type { Build, DeployManifest, Project, Resource } from '../types.ts'; import { deleteCustomHostname, @@ -478,8 +467,6 @@ async function cleanupRaceWindowResourceOrphans( * 2. Run critical CF cleanup (container apps + per-deploy container * orphan recovery). Throws on non-404 failure; the caller should surface * a 5xx and the DB row remains, allowing retry. Then revoke the proxy's - * email send authorization for the project (the `email-slug:` and - * `email-allowlist:` KV mirrors) — same contract: throws, row remains. * 3. Run best-effort CF cleanup (D1, KV, R2, queues, hyperdrive, custom * hostnames, routing entries, deployment workers). Failures become * warnings. @@ -518,17 +505,8 @@ export async function teardownProject( } await cleanupCriticalResources(context, projectId, project); - // Legacy KV mirrors are display/routing hints. Database admission and - // exact route state are the authority, so a KV outage cannot block teardown. - await revokeProjectEmailSendAuthorization( - context.get('db'), - context.env.ROUTING, - projectId, - ).catch((error) => { - console.warn('[email] legacy mirror cleanup deferred', projectId, error); - }); // Customer-side cleanup is durable and may continue after project deletion. - await cleanupProjectEmailDomains(context, projectId); + await cleanupProjectEmailAssignments(context, projectId); const { warnings: bestEffortWarnings, cleanedCfIds } = await cleanupBestEffortResources( context, projectId, @@ -563,8 +541,7 @@ export async function teardownProject( /** * Best-effort teardown of the Cloudflare Email Routing destinations this - * project is the last holder of. (The project's email KV mirrors are NOT - * best-effort — see `revokeProjectEmailSendAuthorization`.) + * project is the last holder of. * * CF destinations are ACCOUNT-level: one address added for project A is a * valid `send_email` recipient for every worker in the account. The @@ -619,94 +596,8 @@ async function cleanupProjectEmailDestinations( * The project row is left in place (status `deleting`) so the caller can * answer with a retryable 5xx; the next teardown attempt repeats the deletes. */ -export class EmailSendRevocationError extends Error { - constructor(key: string, cause: unknown) { - super(`failed to delete ${key}`, { cause }); - this.name = 'EmailSendRevocationError'; - } -} - -/** - * Delete the KV mirrors that authorize `/email/send` and `/email/relay` for - * this project, and FAIL the teardown if any delete (or the domain - * enumeration) does. - * - * `__VOID_PROXY_TOKEN` is an HMAC of the project id that never expires, and - * the tenant's own worker code can read it, so after teardown the proxy's - * KV reads are the only thing standing between a retained token and the - * shared `send_email` binding: `email-slug:` absent is a 502 and - * `email-allowlist:` absent denies every recipient, while a - * missing ROUTING blob (`cleanupBestEffortResources` deletes it, also - * best-effort) is deliberately read as "not suspended". The same holds on - * the inbound lane: a registered domain's relay secret never expires - * either, and the `email-domain:` mirror is what `/email/relay` - * proves it against — a mirror that outlives the project keeps the dead - * tenant's domain relayable (rejected only later, at slug resolution). - * Once `deleteProjectCascade` has run there is no row to retry from — - * the FK cascade takes the `email_domains` rows with it — and nothing - * sweeps these keys, so a delete that was swallowed here would leave the - * dead project sendable and relayable for as long as the mirrors stayed - * behind. Failing closed keeps the row — the retry handle — exactly as the - * destination revoke paths keep theirs when the mirror write fails. - * - * The slug mirror goes first: it is the stronger gate (a 502 whatever the - * allowlist says), so if a later delete is the one that fails the send path - * is already closed while the row waits for the retry. The domain rows must - * be read here, before the cascade: afterwards the set of mirrors to clear - * is unrecoverable. - */ -async function revokeProjectEmailSendAuthorization( - db: Db, - kv: KVNamespace, - projectId: string, -): Promise { - for (const key of [`email-slug:${projectId}`, `email-allowlist:${projectId}`]) { - try { - await kv.delete(key); - } catch (err) { - console.error(`[cleanup] KV delete failed for ${key}:`, err); - throw new EmailSendRevocationError(key, err); - } - } - let domains: Array<{ domain: string }>; - try { - domains = await db - .select({ domain: emailDomains.domain }) - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)); - } catch (err) { - console.error(`[cleanup] email domain lookup failed for project=${projectId}:`, err); - throw new EmailSendRevocationError(`email-domain:* (project ${projectId})`, err); - } - for (const { domain } of domains) { - try { - await clearEmailDomainMirror(kv, domain); - } catch (err) { - console.error(`[cleanup] KV delete failed for email-domain:${domain}:`, err); - throw new EmailSendRevocationError(`email-domain:${domain}`, err); - } - } -} - -/** - * Best-effort teardown of the CUSTOMER-side state each `email_domains` row - * created: the relay worker in the customer's account, and the zone - * catch-all naming it (removeEmailDomain owns the conditional-reset rule). - * Runs after the KV mirrors are revoked, so a relay that strands here is - * already denied by the proxy, and before the cascade, which destroys the - * rows read here. - * - * The grant refresh goes through the row's serialized chain: refresh - * tokens are single-use, and a teardown that crashes before the cascade - * must leave the row's credential live for the retry. A row that never - * deployed a relay has no CF-side relay or rule to clean, so api_token - * rows are skipped — but an oauth_grant row still owns a live - * customer-side grant, and that grant must be revoked even when the - * relay never deployed. Never throws: a project delete must not 5xx on - * the customer's CF account being unreachable or the grant being - * revoked. - */ -async function cleanupProjectEmailDomains( +/** Disable project email assignments and record durable provider cleanup. */ +async function cleanupProjectEmailAssignments( context: Context, projectId: string, ): Promise { @@ -743,82 +634,4 @@ async function cleanupProjectEmailDomains( ); } } - let rows: Array< - Pick< - EmailDomain, - | 'id' - | 'domain' - | 'credential_kind' - | 'zone_id' - | 'account_id' - | 'relay_worker_name' - | 'token_ciphertext' - | 'token_iv' - | 'token_key_version' - > - > = []; - try { - rows = await db - .select({ - id: emailDomains.id, - domain: emailDomains.domain, - credential_kind: emailDomains.credential_kind, - zone_id: emailDomains.zone_id, - account_id: emailDomains.account_id, - relay_worker_name: emailDomains.relay_worker_name, - token_ciphertext: emailDomains.token_ciphertext, - token_iv: emailDomains.token_iv, - token_key_version: emailDomains.token_key_version, - }) - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)); - } catch (err) { - console.error(`[cleanup] email domain lookup failed for project=${projectId}:`, err); - } - for (const row of rows) { - // A relay-less api_token row has no customer-side state at all. A - // relay-less OAUTH row still owns a live grant: run the teardown so - // removeEmailDomain's last step revokes it. - if (!row.relay_worker_name && row.credential_kind !== 'oauth_grant') { - continue; - } - try { - const credential = await decryptEmailDomainToken(context.env, projectId, row.domain, row); - const { failed_steps } = await removeEmailDomain( - { - row: { - credential_kind: row.credential_kind, - account_id: row.account_id, - relay_worker_name: row.relay_worker_name, - zone_id: row.zone_id, - }, - credential, - }, - { - // The row is cascade-deleted either way, but the customer's - // Cloudflare grant must not outlive the project — revoke it for - // oauth_grant rows. Refresh rotations must persist through the - // row's serialized chain while it still exists. - refreshGrant: () => refreshOauthGrantSerialized(db, context.env, row.id), - ...(row.credential_kind === 'oauth_grant' - ? { revokeGrant: () => revokeOauthGrantSerialized(db, context.env, row.id) } - : {}), - }, - ); - if (failed_steps.length > 0) { - // Teardown proceeds regardless — the cascade owns the row, and the - // residue is visible in the customer's own Cloudflare account. - console.warn('[email] teardown left CF-side residue', { - projectId, - domain: row.domain, - failed_steps, - }); - } - } catch (err) { - console.error( - `[cleanup] email domain CF cleanup failed for project=${projectId} domain=${row.domain}:`, - err, - ); - } - } } diff --git a/platform/packages/api/src/provisioning/email-allowlist.ts b/platform/packages/api/src/provisioning/email-allowlist.ts deleted file mode 100644 index dc99e80a6..000000000 --- a/platform/packages/api/src/provisioning/email-allowlist.ts +++ /dev/null @@ -1,153 +0,0 @@ -/** - * KV mirror of per-project verified email destinations. - * - * The proxy worker (`packages/proxy/src/email.ts`) reads - * `email-allowlist:` from `ROUTING` KV on every send to enforce - * per-project allowlists at the binding layer. Postgres - * (`email_destinations`) is the source of truth; KV is a denormalized - * read-cache. Every destinations CRUD calls this helper. - * - * On empty (no verified destinations), the key is deleted rather than set - * to `[]` — the proxy's read treats missing/empty identically and the - * delete saves a KV slot. - */ - -import { getVerifiedEmailDestinationsByProjectId, type Db } from '../db.ts'; - -/** - * The one place this key is spelled. The writer below and the drift check at - * the bottom of the file share it, so a rename cannot leave the reader - * comparing a key the writer no longer writes. - */ -function allowlistKey(projectId: string): string { - return `email-allowlist:${projectId}`; -} - -/** - * Rewrite `email-allowlist:` from the verified rows in Postgres. - * - * `excludeDestinationId` drops one row from the write. A revoke has to - * TIGHTEN the mirror before it deletes the row (the row is what a retry - * re-derives the mirror from), and at that point - * `getVerifiedEmailDestinationsByProjectId` still returns the row being - * revoked — without the exclusion the sync would write the revoked address - * straight back. - */ -export async function syncProjectAllowlistKv( - db: Db, - kv: KVNamespace, - projectId: string, - options?: { excludeDestinationId?: string }, -): Promise { - const rows = await getVerifiedEmailDestinationsByProjectId(db, projectId); - const excludeId = options?.excludeDestinationId; - const addresses = rows.filter((r) => r.id !== excludeId).map((r) => r.address.toLowerCase()); - const key = allowlistKey(projectId); - if (addresses.length === 0) { - await kv.delete(key); - return; - } - await kv.put(key, JSON.stringify(addresses)); -} - -/** - * Best-effort wrapper that swallows errors. Use from sites where a KV - * blip mustn't fail the user-facing operation (e.g. CRUD endpoints - * already returned 201 to the user). Logs failures so a sweep job can - * pick up stragglers. - */ -export async function syncProjectAllowlistKvBestEffort( - db: Db, - kv: KVNamespace, - projectId: string, -): Promise { - try { - await syncProjectAllowlistKv(db, kv, projectId); - } catch (err) { - console.error(`[email-allowlist] KV sync failed for project=${projectId}:`, err); - } -} - -/** - * Does `email-allowlist:` differ from what - * {@link syncProjectAllowlistKv} would write right now? - * - * Every write to this mirror is best-effort: - * `syncProjectAllowlistKvBestEffort` swallows a KV failure that happens - * AFTER Postgres already committed `verified`, and NOTHING else re-derives - * the key — the confirm route early-returns on an already-verified row, the - * hourly `scheduled()` backfill touches only `email-slug:`, and no deploy - * hook calls the sync. A single lost write therefore strands the project - * silently: the proxy reads a missing key as deny-all, so the owner sees - * `verified` in `void email destinations` while every send comes back as an - * unverified destination. This is what lets the destinations listing repair - * it — read, compare, write only on a difference. - * - * The comparison is order- and duplicate-insensitive. The proxy loads the - * value into a `Set`, so a row-order change is not drift and must not make - * every listing write. A value that is PRESENT but unusable (not JSON, not - * an array of strings) IS drift: rewriting it is the only thing that clears - * it. A MISSING key is not — the writer deletes the key to say "no verified - * destinations". - * - * A KV READ failure reports "no difference". The caller's next step on a - * difference is a write, and answering "differs" on a blip would turn a - * read-only listing into a write storm for the length of a KV incident. - */ -export async function projectAllowlistKvDiffers( - db: Db, - kv: KVNamespace, - projectId: string, -): Promise { - let raw: string | null; - try { - raw = await kv.get(allowlistKey(projectId)); - } catch (err) { - console.error(`[email-allowlist] KV read failed for project=${projectId}:`, err); - return false; - } - - const mirrored = parseMirror(raw); - if (mirrored === null) { - return true; - } - const rows = await getVerifiedEmailDestinationsByProjectId(db, projectId); - const expected = new Set(rows.map((r) => r.address.toLowerCase())); - if (mirrored.size !== expected.size) { - return true; - } - for (const address of expected) { - if (!mirrored.has(address)) { - return true; - } - } - return false; -} - -/** - * The addresses the mirror currently grants, parsed the way the proxy's - * `readAllowlist` parses them. `null` means the key holds something that is - * not a mirror at all. - */ -function parseMirror(raw: string | null): Set | null { - if (raw === null) { - return new Set(); - } - let parsed: unknown; - try { - parsed = JSON.parse(raw); - } catch { - return null; - } - if (!Array.isArray(parsed)) { - return null; - } - const out = new Set(); - for (const value of parsed) { - if (typeof value !== 'string') { - return null; - } - out.add(value.toLowerCase()); - } - return out; -} diff --git a/platform/packages/api/src/reserved-slugs.ts b/platform/packages/api/src/reserved-slugs.ts index 55a2de108..5f3b800ae 100644 --- a/platform/packages/api/src/reserved-slugs.ts +++ b/platform/packages/api/src/reserved-slugs.ts @@ -15,9 +15,8 @@ * project can claim one. These five were reserved only when email shipped, * though, and the create-time check cannot reach a project registered * before that — so every consumer on the email path also refuses the slug - * outright: the hourly `email-slug:` backfill writes no mirror for it (and - * removes one written earlier), the proxy refuses `/email/send` for it, and - * the inbound router rejects mail addressed to it. Kept in its own module + * outright: the proxy refuses `/email/send` for it, and the inbound router + * rejects mail addressed to it. Kept in its own module * so the proxy (`@voidcloud/api/reserved-slugs`) shares one list with the * api rather than carrying a copy that can drift. * @@ -37,8 +36,8 @@ export const EMAIL_RESERVED_SLUGS: ReadonlySet = new Set([ /** * True when `slug` may not send or receive mail on the platform domain. * Callers pass a slug that is already lowercase: the api validates the - * shape at create time, the proxy's `SLUG_RE` re-validates the KV mirror, - * and the inbound router lowercases the recipient before splitting it. + * shape at create time, and the inbound router lowercases the recipient + * before splitting it. */ export function isReservedEmailSlug(slug: string): boolean { return EMAIL_RESERVED_SLUGS.has(slug); diff --git a/platform/packages/api/src/routes/auth.ts b/platform/packages/api/src/routes/auth.ts index 0c93a2303..f197b08de 100644 --- a/platform/packages/api/src/routes/auth.ts +++ b/platform/packages/api/src/routes/auth.ts @@ -363,14 +363,7 @@ app.get('/callback', async (context) => { // Only overwrite stored email when the new one is verified; // a transient /user/emails failure must not wipe the existing email. if (emailVerified) { - await updateUserRevokingInheritedDestinations( - db, - context.env.ROUTING, - user.id, - login, - user.email, - email, - ); + await updateUserRevokingInheritedDestinations(db, user.id, login, user.email, email); } else { await updateUser(db, user.id, login, user.email); } diff --git a/platform/packages/api/src/routes/delete.ts b/platform/packages/api/src/routes/delete.ts index 3bec42cc9..6cd543167 100644 --- a/platform/packages/api/src/routes/delete.ts +++ b/platform/packages/api/src/routes/delete.ts @@ -1,11 +1,7 @@ import { Hono } from 'hono'; import { getProject } from '../db.ts'; import type { ApiEnv } from '../env.ts'; -import { - EmailSendRevocationError, - ProjectOperationInProgressError, - teardownProject, -} from '../provisioning/cleanup.ts'; +import { ProjectOperationInProgressError, teardownProject } from '../provisioning/cleanup.ts'; const app = new Hono(); @@ -25,9 +21,7 @@ app.delete('/:id', async (context) => { // `resources` rows + per-deploy container orphan recovery by deterministic // name — fatal on failure), best-effort CF cleanup (D1, KV, R2, queues, // hyperdrive, custom hostnames, routing entries — warnings), and the DB - // cascade. Critical-cleanup failure throws and surfaces as a 5xx. So does a - // failed revocation of the project's email send authorization (its KV - // mirrors): the row stays, and the 503 asks for the retry that finishes it. + // cascade. Critical-cleanup failure throws and surfaces as a 5xx. let warnings: ReadonlyArray; try { ({ warnings } = await teardownProject(context, projectId, project)); @@ -35,9 +29,6 @@ app.delete('/:id', async (context) => { if (error instanceof ProjectOperationInProgressError) { return context.json({ error: error.message }, 409); } - if (error instanceof EmailSendRevocationError) { - return context.json({ error: 'failed to revoke email send authorization; try again' }, 503); - } throw error; } diff --git a/platform/packages/api/src/routes/deploy.ts b/platform/packages/api/src/routes/deploy.ts index 49f4140b9..398711b84 100644 --- a/platform/packages/api/src/routes/deploy.ts +++ b/platform/packages/api/src/routes/deploy.ts @@ -4114,8 +4114,7 @@ async function handleManifestOnlyDeploy(context: Context): Promise` KV mirror. See + // the per-project verified-destination policy through SQL admission. See // `meta/design-docs/0078-email-cf-native.md` and `packages/proxy/src/email.ts`. const allBindings = [ ...plainTextBindings, diff --git a/platform/packages/api/src/routes/email-confirm.ts b/platform/packages/api/src/routes/email-confirm.ts index 4ad518035..d6c2dda79 100644 --- a/platform/packages/api/src/routes/email-confirm.ts +++ b/platform/packages/api/src/routes/email-confirm.ts @@ -18,7 +18,6 @@ import { verifyConfirmToken } from '../auth/confirm-token.ts'; import { getEmailDestinationById, getProject, updateEmailDestinationStatus } from '../db.ts'; import { escapeHtml } from '../email.ts'; import type { ApiEnv } from '../env.ts'; -import { syncProjectAllowlistKvBestEffort } from '../provisioning/email-allowlist.ts'; const app = new Hono(); @@ -80,7 +79,6 @@ app.get('/destinations/confirm', async (context) => { // (whatever the row was created with) stays put. undefined, ); - await syncProjectAllowlistKvBestEffort(context.get('db'), context.env.ROUTING, row.project_id); return context.html(successPage(slug, row.address, false)); }); diff --git a/platform/packages/api/src/routes/email.ts b/platform/packages/api/src/routes/email.ts index 86e02c066..36d56cd37 100644 --- a/platform/packages/api/src/routes/email.ts +++ b/platform/packages/api/src/routes/email.ts @@ -37,10 +37,6 @@ import { } from '../email/settings.ts'; import type { ApiEnv } from '../env.ts'; import { isForeignKeyViolation, isUniqueViolation } from '../pg-errors.ts'; -import { - projectAllowlistKvDiffers, - syncProjectAllowlistKvBestEffort, -} from '../provisioning/email-allowlist.ts'; import { addDestination, deleteDestination, @@ -154,7 +150,6 @@ const app = new Hono() const pending = rows.filter( (r) => r.status === 'pending' && r.verification_source !== 'platform', ); - let anyFlipped = false; if (pending.length > 0) { try { const cfRows = await listDestinations(context.env.CF_ACCOUNT_ID, context.env.CF_API_TOKEN); @@ -228,35 +223,12 @@ const app = new Hono() row.status = 'verified'; row.cf_destination_id = cf.tag; row.verified_at = cf.verified; - anyFlipped = true; } } catch (err) { console.error('[email] destinations refresh failed:', err); // Non-fatal — we still return the cached view. } } - // Push any newly-verified address into the proxy's allowlist KV, and - // repair the mirror whenever it has drifted from the verified rows. - // - // The repair is not belt-and-braces. Every write to this mirror is - // best-effort, and nothing else re-derives the key: the confirm route - // early-returns on an already-verified row, the hourly `scheduled()` - // backfill in `index.ts` touches only `email-slug:`, and no deploy hook - // calls the sync. One swallowed KV failure after Postgres committed - // `verified` therefore leaves the owner looking at a `verified` listing - // while the proxy — which reads a missing key as deny-all — rejects every - // send as an unverified destination, with no user-visible cause. So THIS - // listing is the repair: the same read-compare-write self-heal shape as - // the `email-slug:` backfill. Cost is one KV read (skipped entirely when - // a flip already forces the write); the write happens only on a real - // difference, never on every listing. - if ( - anyFlipped || - (await projectAllowlistKvDiffers(context.get('db'), context.env.ROUTING, projectId)) - ) { - await syncProjectAllowlistKvBestEffort(context.get('db'), context.env.ROUTING, projectId); - } - return context.json(rows.map(serializeDestination)); }) @@ -414,9 +386,6 @@ const app = new Hono() return context.json({ error: 'destination concurrently modified, try again' }, 409); } const { row } = inserted; - if (row.status === 'verified') { - await syncProjectAllowlistKvBestEffort(context.get('db'), context.env.ROUTING, projectId); - } return context.json(serializeDestination(row), 201); } @@ -531,7 +500,7 @@ const app = new Hono() return context.json({ error: 'destination not found' }, 404); } - // Admission observes this committed revocation regardless of KV publication. + // Admission observes this committed revocation. await deleteEmailDestination(context.get('db'), dest.id); if ( dest.cf_destination_id && @@ -547,17 +516,12 @@ const app = new Hono() console.error('[email] destination provider cleanup failed:', error); } } - await syncProjectAllowlistKvBestEffort(context.get('db'), context.env.ROUTING, projectId); return context.json({ ok: true }); }) // ------------------------------------------------------------------------- - // Custom email domains on the customer's own Cloudflare zone (design doc - // 0078, "Custom domains on Cloudflare"). The add/sync/remove orchestration - // lives in src/email/relay-engine.ts (contract 7); these routes own the - // owner guard, the `email_domains` row, both encrypted triples, and the - // ROUTING KV mirror the proxy reads (contract 2). Neither the credential - // nor the relay secret is ever returned — serializers carry metadata only. + // Custom email domain routes. The connection service runs durable + // operations; these routes apply the owner guard and map responses. // ------------------------------------------------------------------------- // Installation settings the CLI needs before it acts: who manages email @@ -578,7 +542,7 @@ const app = new Hono() getEmailDomainManagement(db), getEmailRecipientPolicy(db), ]); - // Same best-effort repair the destinations listing does for its mirror. + // Republish a drifted recipient-policy mirror for the proxy's local gate. await repairEmailRecipientPolicyMirror(db, context.env.ROUTING); return context.json({ domains: { management, projectSlug: project.slug }, @@ -617,7 +581,6 @@ const app = new Hono() const projectId = context.req.param('id'); let body: { domain?: unknown; - mode?: unknown; refreshToken?: unknown; apiToken?: unknown; attemptId?: unknown; @@ -643,7 +606,6 @@ const app = new Hono() } return addEmailDomainForProject(context, project, { domain: typeof body.domain === 'string' ? body.domain : '', - mode: body.mode, apiToken: typeof body.apiToken === 'string' ? body.apiToken : undefined, attemptId: body.attemptId, managedBy: 'owner', @@ -731,13 +693,7 @@ const app = new Hono() if (project.user_id !== context.get('user').id) { return context.json({ error: 'forbidden' }, 403); } - return removeEmailDomainForProject( - context, - project, - context.req.param('domain'), - context.req.query('force') === '1', - 'owner', - ); + return removeEmailDomainForProject(context, project, context.req.param('domain'), 'owner'); }); function parseCounter(raw: string | null): number { diff --git a/platform/packages/api/src/routes/projects.ts b/platform/packages/api/src/routes/projects.ts index 85c14daef..94f01dddf 100644 --- a/platform/packages/api/src/routes/projects.ts +++ b/platform/packages/api/src/routes/projects.ts @@ -64,7 +64,6 @@ import { restoreQueueConsumer, snapshotQueueConsumer, } from '../provisioning/cloudflare-api.ts'; -import { syncProjectAllowlistKvBestEffort } from '../provisioning/email-allowlist.ts'; import { addDestination, listDestinations, @@ -639,14 +638,7 @@ const app = new Hono() const userId = context.get('user').id; try { - // ROUTING carries the `email-slug:` mirror the email proxy - // reads to pin a project's outbound `from` to its own slug. - const project = await createProject( - context.get('db'), - userId, - body.slug, - context.env.ROUTING, - ); + const project = await createProject(context.get('db'), userId, body.slug); // Pre-seed the owner's own address as a destination so mail to // themselves works from the first deploy. CF sends them a verification // link; the row stays `pending` until they click it. @@ -675,7 +667,6 @@ const app = new Hono() context.env.CF_ACCOUNT_ID, context.env.CF_API_TOKEN, context.get('db'), - context.env.ROUTING, project.id, address, userId, @@ -3180,7 +3171,6 @@ async function autoAddOwnerDestination( accountId: string, apiToken: string, db: Db, - kv: KVNamespace, projectId: string, address: string, ownerUserId: string, @@ -3244,11 +3234,6 @@ async function autoAddOwnerDestination( // means they can re-add it. throw new Error('owner destination row vanished between insert and read-back'); } - // Already verified on a prior project — push it into the allowlist mirror - // now so the proxy accepts the first send without a manual refresh. - if (status === 'verified') { - await syncProjectAllowlistKvBestEffort(db, kv, projectId); - } } catch (err) { console.error('[projects] auto-add owner email destination failed:', err); if (allocatedTag) { diff --git a/platform/packages/api/src/schema.ts b/platform/packages/api/src/schema.ts index 37c837deb..3a7172148 100644 --- a/platform/packages/api/src/schema.ts +++ b/platform/packages/api/src/schema.ts @@ -562,44 +562,20 @@ export const emailDestinations = pgTable( ); // --------------------------------------------------------------------------- -// email_domains -// Per-project custom email domains on the customer's own Cloudflare zone -// (design doc 0078, "Custom domains on Cloudflare"). The customer grants a -// scoped credential once — an OAuth grant refresh token, or a pasted API -// token on the fallback path — and the platform configures the zone, deploys -// a relay worker into the customer's account for inbound, and sends outbound -// through CF's REST send_raw with a leased credential. -// -// Two encrypted values per row, each an AES-GCM ciphertext/iv/key_version -// triple from `encryptProjectSecret` under a FIXED AAD name per row -// (`email-domain-token:` / `email-domain-relay:` — the AAD is -// `${projectId}:${name}`, so each ciphertext is bound to project AND domain): -// - token_* — the grant refresh token OR the pasted API token. Only the -// api decrypts it (probes, relay deploys, the OAuth refresh chain); the -// proxy leases short-lived credentials from the api instead of holding it. -// - relay_* — the relay secret (random 32 bytes, base64url, generated by -// the api at add time). Only its sha256 hex is mirrored to ROUTING KV; -// the plaintext is never logged, returned, or written to a manifest. -// -// Lifecycle columns are nullable because EVERY orchestration failure leaves -// the row 'failed' with `setup_state` naming the failed step, no matter how -// early: `zone_id`/`account_id` are known only after the zone lookup, -// `mode` after the public-DNS MX check, and `relay_worker_name`/ -// `relay_version` only once the relay is deployed (its name gains a '-2', -// '-3'… suffix on collision within the account). `token_id`/ -// `token_expires_on` come from GET /user/tokens/verify and stay null on the -// oauth_grant path. `relay_worker_name` never changes after deploy — -// renaming a worker detaches every routing rule that points at it. +// email_domains is retained for generated-schema compatibility with the +// published platform runtime rollback contract. New email routes do not use it. // --------------------------------------------------------------------------- export type EmailDomainSetupState = Readonly<{ /** Orchestration step that left the row 'failed' (e.g. 'zone_lookup'). */ failed_step?: string; /** Steps still owed by the human (e.g. the routing-subdomain dashboard form). */ remaining_steps?: ReadonlyArray; - /** CF steps a remove failed on ('catch_all', 'delete_relay', 'revoke_grant'); the row is KEPT for retry/force. */ + /** Historical removal failures. */ removal_failed_steps?: ReadonlyArray; }>; +// Retained for database rollback to published platform runtimes. The current +// email implementation uses emailDomainRoutes and never reads this table. export const emailDomains = pgTable( 'email_domains', { diff --git a/platform/packages/api/test/integration/admin-email.test.ts b/platform/packages/api/test/integration/admin-email.test.ts index 088772f1e..c517057b5 100644 --- a/platform/packages/api/test/integration/admin-email.test.ts +++ b/platform/packages/api/test/integration/admin-email.test.ts @@ -14,16 +14,8 @@ import type { Db } from '../../src/db.ts'; import { emailProjectControls } from '../../src/email/admission-schema.ts'; import { setProjectEmailLimits, setProjectEmailSuspended } from '../../src/email/admission.ts'; import { emailDomainRoutes, emailZoneConnections } from '../../src/email/connection-schema.ts'; -import { refreshOauthGrantSerialized } from '../../src/email/credential-lease.ts'; -import { - encryptEmailDomainRelaySecret, - encryptEmailDomainToken, - hashEmailRelaySecret, - writeEmailDomainMirror, - type EmailDomain, -} from '../../src/email/domains.ts'; import { app } from '../../src/index.ts'; -import { emailDomains, operatorEvents, platformSettings } from '../../src/schema.ts'; +import { operatorEvents, platformSettings } from '../../src/schema.ts'; import { stubCustomerCf, callsByTag } from './email-domain-cf-stub.ts'; import { setupEnv, @@ -111,33 +103,6 @@ function recordCfCalls(): Array { return calls; } -/** - * Fail this project's allowlist mirror write (both branches — the `put` and - * the delete-on-empty), leaving every other KV op intact. Restored by the - * file-level `vi.restoreAllMocks()`. - */ -function breakAllowlistWrites(projectId: string): void { - const key = `email-allowlist:${projectId}`; - const originalPut = env.ROUTING.put.bind(env.ROUTING); - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( - k: string, - value: string | ArrayBuffer | ArrayBufferView | ReadableStream, - options?: KVNamespacePutOptions, - ) => { - if (k === key) { - throw new Error('forced allowlist KV failure for test'); - } - return originalPut(k, value as never, options as never); - }) as typeof env.ROUTING.put); - vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - if (k === key) { - throw new Error('forced allowlist KV failure for test'); - } - return originalDelete(k as never); - }) as typeof env.ROUTING.delete); -} - /** UTC `YYYY-MM`, the bucket `admin/routes/email.tsx` and the proxy both use. */ function monthBucket(): string { const now = new Date(); @@ -436,7 +401,7 @@ describe('POST /admin/email/:projectId/limit', () => { }); describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { - test('removes the row, drops the CF address, and re-syncs the allowlist', async () => { + test('removes the row and drops an unreferenced CF address', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); const destination = await createEmailDestination( env.db, @@ -445,7 +410,6 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { 'cf-tag-ops', 'verified', ); - await env.ROUTING.put(`email-allowlist:${projectId}`, JSON.stringify(['ops@example.com'])); const cfCalls = recordCfCalls(); const res = await post( @@ -457,9 +421,7 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { expect(cfCalls).toEqual([ 'DELETE https://api.cloudflare.com/client/v4/accounts/test-account-id/email/routing/addresses/cf-tag-ops', ]); - // Last verified row gone, so the proxy's allowlist key is removed rather - // than left holding an address the project may no longer send to. - expect(await env.ROUTING.get(`email-allowlist:${projectId}`)).toBeNull(); + expect(await getEmailDestinationsByProjectId(env.db, projectId)).toEqual([]); }); test('leaves the CF address alone while another project still references it', async () => { @@ -490,84 +452,6 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { expect(cfCalls).toEqual([]); }); - test('tightens the mirror while the revoked row is still present', async () => { - // Same ordering contract as the user-facing revoke in `routes/email.ts`. - // The mirror is what the proxy enforces and the row is what a retry - // re-derives it from, so the write lands FIRST and must already exclude - // the row being revoked — it is still `verified` at that instant. - const { adminJwt, projectId } = await seedAdminAndProject(); - await createEmailDestination(env.db, projectId, 'keep@example.com', 'cf-tag-keep', 'verified'); - const doomed = await createEmailDestination( - env.db, - projectId, - 'gone@example.com', - 'cf-tag-gone', - 'verified', - ); - - const observed: Array<{ written: Array; rowIds: Array }> = []; - const originalPut = env.ROUTING.put.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( - k: string, - value: string | ArrayBuffer | ArrayBufferView | ReadableStream, - options?: KVNamespacePutOptions, - ) => { - await originalPut(k, value as never, options as never); - if (k === `email-allowlist:${projectId}`) { - const rows = await getEmailDestinationsByProjectId(env.db, projectId); - observed.push({ - written: JSON.parse(String(value)) as Array, - rowIds: rows.map((r) => r.id).sort(), - }); - } - }) as typeof env.ROUTING.put); - - const res = await post(`/admin/email/${projectId}/destinations/${doomed.id}/delete`, adminJwt); - - expect(res.status).toBe(302); - // Two writes: the tighten with both rows still present, then the - // re-derive after the delete (a confirm click can promote a row between - // the snapshot and the delete; deriving afterwards cannot include it). - expect(observed).toHaveLength(2); - expect(observed[0]?.written).toEqual(['keep@example.com']); - // Both rows still there at the moment of the first write. - expect(observed[0]?.rowIds).toContain(doomed.id); - expect(observed[1]?.written).toEqual(['keep@example.com']); - expect(observed[1]?.rowIds).not.toContain(doomed.id); - expect(await env.ROUTING.get(`email-allowlist:${projectId}`)).toBe( - JSON.stringify(['keep@example.com']), - ); - }); - - test('keeps the row and fails the revoke when the mirror write fails', async () => { - const { adminJwt, projectId } = await seedAdminAndProject(); - const destination = await createEmailDestination( - env.db, - projectId, - 'gone@example.com', - 'cf-tag-gone', - 'verified', - ); - await env.ROUTING.put(`email-allowlist:${projectId}`, JSON.stringify(['gone@example.com'])); - breakAllowlistWrites(projectId); - const cfCalls = recordCfCalls(); - - const res = await post( - `/admin/email/${projectId}/destinations/${destination.id}/delete`, - adminJwt, - ); - - // Nothing destructive ran, so the operator can just click again. Dropping - // the row first and swallowing the KV error would strand the revoked - // address in the allowlist with no row left to re-derive it from. - expect(res.status).toBe(503); - expect(await getEmailDestinationsByProjectId(env.db, projectId)).toHaveLength(1); - expect(await env.ROUTING.get(`email-allowlist:${projectId}`)).toBe( - JSON.stringify(['gone@example.com']), - ); - expect(cfCalls).toEqual([]); - }); - test('404s for a destination that belongs to another project', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); const sibling = await createTestProject(env.db, (await createTestUser(env.db)).id); @@ -590,170 +474,6 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { }); }); -// --------------------------------------------------------------------------- -// Custom email domains (design doc 0078). The admin page lists the project's -// email_domains rows; the revoke route clears the ROUTING mirror, best-effort -// deletes the relay + catch-all in the customer's account via the relay -// engine, then drops the row. All credential-shaped strings are dummy -// stand-ins, and no assertion may contain one — the page and the error -// bodies must never render them. -// --------------------------------------------------------------------------- - -// Dummy stand-ins — never real token/secret material. -const CUSTOMER_TOKEN = 'cf-customer-token-dummy'; -const GRANT_REFRESH_TOKEN = 'cf-grant-refresh-dummy'; -const RELAY_SECRET = 'admin-relay-secret-dummy'; - -/** - * Seed an email_domains row directly (no orchestration), always with its - * ROUTING mirror — the revoke's first job is clearing that key. `deployed: - * false` seeds a row whose setup failed before the relay deploy, so there is - * nothing in the customer account to clean up. Domains must be unique per - * test: ROUTING is file-scoped here and the mirror key is domain-scoped. - */ -async function seedEmailDomain( - projectId: string, - domain: string, - options: { - status?: EmailDomain['status']; - deployed?: boolean; - credentialKind?: EmailDomain['credential_kind']; - } = {}, -): Promise { - const deployed = options.deployed ?? true; - const credentialKind = options.credentialKind ?? 'api_token'; - // The stored credential is the pasted API token, or the grant's refresh - // token on the oauth_grant path. - const tokenEnc = await encryptEmailDomainToken( - env, - projectId, - domain, - credentialKind === 'oauth_grant' ? GRANT_REFRESH_TOKEN : CUSTOMER_TOKEN, - ); - const relayEnc = await encryptEmailDomainRelaySecret(env, projectId, domain, RELAY_SECRET); - await env.db.insert(emailDomains).values({ - id: `edom_admin_${domain.replace(/[^a-z0-9]/g, '')}`, - project_id: projectId, - domain, - zone_id: deployed ? 'zone_customer_1' : null, - account_id: deployed ? 'acct_customer_1' : null, - mode: deployed ? 'apex' : null, - status: options.status ?? 'active', - credential_kind: credentialKind, - token_ciphertext: tokenEnc.ciphertext, - token_iv: tokenEnc.iv, - token_key_version: tokenEnc.keyVersion, - relay_ciphertext: relayEnc.ciphertext, - relay_iv: relayEnc.iv, - relay_key_version: relayEnc.keyVersion, - relay_worker_name: deployed ? 'void-email-relay' : null, - relay_version: deployed ? 1 : null, - token_id: deployed ? 'tok_dummy' : null, - token_expires_on: null, - setup_state: deployed ? null : { failed_step: 'zone_lookup' }, - }); - const row = (await domainRow(projectId, domain))!; - await writeEmailDomainMirror(env.ROUTING, row, await hashEmailRelaySecret(RELAY_SECRET)); - return row; -} - -async function domainRow(projectId: string, domain: string): Promise { - const rows = await env.db - .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, projectId)); - return rows.find((row) => row.domain === domain); -} - -/** - * Record the customer-account CF calls the relay engine makes (method, url, - * parsed JSON body) and answer each with a success envelope. The remove path - * DELETEs the relay script and resets the catch-all — but only after an - * ownership read, so the catch-all GET answers with a rule naming this - * row's relay. The OAuth grant revoke (dash.cloudflare.com — NOT - * api.cloudflare.com) is tagged `oauthRevoke` so a test can assert it fired. - */ -function recordCustomerCfCalls(): Array<{ - method: string; - url: string; - body?: unknown; - tag?: 'oauthRevoke' | 'oauthToken'; -}> { - const calls: Array<{ - method: string; - url: string; - body?: unknown; - tag?: 'oauthRevoke' | 'oauthToken'; - }> = []; - vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => { - const url = typeof input === 'string' ? input : (input as Request).url; - let body: unknown; - if (typeof init?.body === 'string') { - try { - body = JSON.parse(init.body) as unknown; - } catch { - body = init.body; - } - } - const method = init?.method ?? 'GET'; - const isTokenEndpoint = url.startsWith('https://dash.cloudflare.com/oauth2/token'); - calls.push({ - method, - url, - body, - ...(isTokenEndpoint ? { tag: 'oauthToken' as const } : {}), - ...(url.startsWith('https://dash.cloudflare.com/oauth2/revoke') - ? { tag: 'oauthRevoke' as const } - : {}), - }); - if (isTokenEndpoint) { - // Grant refresh tokens rotate on every use; the caller persists this - // replacement and revokes the chain HEAD, not the presented token. - return Response.json({ - access_token: 'cf-access-dummy-1', - refresh_token: 'cf-rotated-refresh-dummy-1', - expires_in: 3600, - }); - } - if (method === 'GET' && url.includes('/email/routing/rules/catch_all')) { - return Response.json({ - success: true, - errors: [], - result: { - enabled: true, - matchers: [{ type: 'all' }], - actions: [{ type: 'worker', value: ['void-email-relay'] }], - }, - }); - } - return Response.json({ success: true, errors: [], result: {} }); - }); - return calls; -} - -/** Every CF call fails — the revoke must still complete (cleanup is best-effort). */ -function failCustomerCfCalls(): Array { - const calls: Array = []; - vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => { - const url = typeof input === 'string' ? input : (input as Request).url; - calls.push(`${init?.method ?? 'GET'} ${url}`); - return Response.json({ success: false, errors: [{ message: 'boom' }] }, { status: 500 }); - }); - return calls; -} - -/** Fail one domain's mirror-key delete, leaving every other KV op intact. */ -function breakMirrorDelete(domain: string): void { - const key = `email-domain:${domain}`; - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - if (k === key) { - throw new Error('forced mirror KV failure for test'); - } - return originalDelete(k as never); - }) as typeof env.ROUTING.delete); -} - describe('admin email domain controls', () => { test('registers, rotates and removes an exact route without exposing credential material', async () => { const { adminJwt, projectId, slug } = await seedAdminAndProject(); diff --git a/platform/packages/api/test/integration/api-delete.test.ts b/platform/packages/api/test/integration/api-delete.test.ts index a5956bfb4..ef635ea46 100644 --- a/platform/packages/api/test/integration/api-delete.test.ts +++ b/platform/packages/api/test/integration/api-delete.test.ts @@ -11,17 +11,8 @@ import { } from 'vite-plus/test'; import { createBuild } from '../../src/db.ts'; import * as db from '../../src/db.ts'; -import { encryptEmailDomainToken } from '../../src/email/domains.ts'; -import { RELAY_WORKER_BASE_NAME } from '../../src/email/relay-engine.ts'; import app from '../../src/index.ts'; -import { - resources, - projects, - deployments, - builds, - emailDestinations, - emailDomains, -} from '../../src/schema.ts'; +import { resources, projects, deployments, builds, emailDestinations } from '../../src/schema.ts'; import { setupEnv, teardownEnv, @@ -588,7 +579,6 @@ describe('DELETE /projects/:id — CF email destination cleanup', () => { const emailCalls = captureEmailRoutingCalls(); await addEmailDestination(project.id, 'owner@example.com', 'cf-tag-solo'); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['owner@example.com'])); const res = await app.fetch( new Request(`http://localhost/projects/${project.id}`, { @@ -608,10 +598,6 @@ describe('DELETE /projects/:id — CF email destination cleanup', () => { url: expect.stringContaining('/email/routing/addresses/cf-tag-solo') as unknown as string, }, ]); - - // Proxy read-caches for the dead project are dropped too. - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); - expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBeNull(); }); it('leaves a destination another project still references on the account', async () => { @@ -677,713 +663,7 @@ describe('DELETE /projects/:id — CF email destination cleanup', () => { }); // --------------------------------------------------------------------------- -// Email authorization now reads the project and email control rows in PG. -// These legacy KV keys are display hints and cannot authorize a deleted -// project, so their cleanup is best effort. -// --------------------------------------------------------------------------- - -describe('DELETE /projects/:id — email send authorization outlives nothing', () => { - it('deletes the project even when obsolete email mirrors cannot be deleted', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-kv-down'); - mockCfApi(); - await env.ROUTING.put(`email-slug:${project.id}`, project.slug); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['owner@example.com'])); - await env.ROUTING.put( - project.slug, - JSON.stringify({ workerName: 'user-mail-kv-down', projectId: project.id }), - ); - - // KV refuses ONLY the two email mirror deletes. Every other delete — - // the routing entry included — goes through, which is the exact - // permutation that used to leave the stale mirrors authorizing sends - // for a project whose routing entry (and row) were already gone. - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - const failing = vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - if (k === `email-slug:${project.id}` || k === `email-allowlist:${project.id}`) { - throw new Error('forced KV failure for test'); - } - return originalDelete(k as never); - }) as typeof env.ROUTING.delete); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - const [kept] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(kept).toBeUndefined(); - expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBe(project.slug); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).not.toBeNull(); - - failing.mockRestore(); - expect(await env.ROUTING.get(project.slug)).toBeNull(); - }); - - it('revokes the slug mirror before the allowlist mirror', async () => { - // The slug mirror is the stronger gate — without it the proxy answers - // 502 whatever the allowlist says — so it goes first: if the second - // delete is the one that fails, the send path is already closed while - // the row waits for the retry. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-slug-first'); - mockCfApi(); - await env.ROUTING.put(`email-slug:${project.id}`, project.slug); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['owner@example.com'])); - - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - if (k === `email-allowlist:${project.id}`) { - throw new Error('forced KV failure for test'); - } - return originalDelete(k as never); - }) as typeof env.ROUTING.delete); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBeNull(); - const [kept] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(kept).toBeUndefined(); - }); -}); - -// --------------------------------------------------------------------------- -// Legacy domain KV hints are no longer used for inbound authorization. -// --------------------------------------------------------------------------- - -describe('DELETE /projects/:id — email domain mirrors outlive nothing', () => { - async function seedDomainMirror(projectId: string, domain: string): Promise { - await env.db.insert(emailDomains).values({ - id: `edom_${domain.replace(/[^a-z0-9]/g, '')}`, - project_id: projectId, - domain, - status: 'active', - credential_kind: 'api_token', - token_ciphertext: 'dummy-ct', - token_iv: 'dummy-iv', - token_key_version: 'v1', - relay_ciphertext: 'dummy-ct', - relay_iv: 'dummy-iv', - relay_key_version: 'v1', - }); - await env.ROUTING.put( - `email-domain:${domain}`, - JSON.stringify({ - projectId, - status: 'active', - relaySecretSha256: '00'.repeat(32), - relayWorkerName: 'void-email-relay', - accountId: 'acct_1', - zoneId: 'zone_1', - mode: 'apex', - }), - ); - } - - it('clears the email-domain mirror of every registered domain before the cascade', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-domain-mirror'); - mockCfApi(); - await seedDomainMirror(project.id, 'acme.com'); - await seedDomainMirror(project.id, 'mail.acme.example'); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme.com')).toBeNull(); - expect(await env.ROUTING.get('email-domain:mail.acme.example')).toBeNull(); - }); - - it('deletes the project when an obsolete domain mirror cannot be deleted', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-domain-kv-down'); - mockCfApi(); - await seedDomainMirror(project.id, 'acme.com'); - - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - const failing = vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - if (k === 'email-domain:acme.com') { - throw new Error('forced KV failure for test'); - } - return originalDelete(k as never); - }) as typeof env.ROUTING.delete); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - const [kept] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(kept).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme.com')).not.toBeNull(); - const [domainRow] = await env.db - .select() - .from(emailDomains) - .where(eq(emailDomains.project_id, project.id)); - expect(domainRow).toBeUndefined(); - - failing.mockRestore(); - expect(await env.ROUTING.get('email-domain:acme.com')).not.toBeNull(); - }); -}); - -// --------------------------------------------------------------------------- -// The customer-side half of email domain teardown. The KV mirrors above are -// revoked fail-closed; the relay worker and the zone catch-all live in the -// CUSTOMER's Cloudflare account, so `cleanupProjectEmailDomains` removes them -// best-effort (a stranded relay is already denied by the proxy) and never -// throws. These tests pin the `removeEmailDomain` contract teardown relies -// on: ownership read -> conditional drop-and-disable reset -> relay DELETE, -// a failed read skips the DELETE (the rule and its relay stay a consistent -// pair), and a row whose relay never deployed gets no customer call at all. -// --------------------------------------------------------------------------- - -type CustomerEmailCleanupCall = { - tag: 'catchAllGet' | 'catchAll' | 'scriptDelete' | 'oauthToken' | 'oauthRevoke'; - method: string; - url: string; - body?: unknown; - /** OAuth endpoint form fields (dash.cloudflare.com) — dummy fixtures only. */ - form?: Record; - /** The bearer the customer-account call carried — dummy fixtures only. */ - authorization?: string | null; -}; - -/** - * Wrap the fetch stub `mockCfApi()` installed so the CUSTOMER-account email - * endpoints (the zone catch-all rule GET/PUT, the relay script DELETE) and - * the OAuth grant endpoints (dash.cloudflare.com oauth2/token + oauth2/revoke - * — a DIFFERENT host than api.cloudflare.com) are recorded and answered here - * — the platform-wide mock does not know them. Same tag names and response - * shapes as `stubCustomerCf` in api-email-domains.test.ts, kept local: only - * teardown's remove contract is under test. - */ -function captureCustomerEmailCleanup( - config: { - /** The zone's current catch-all; absent → 404 (no rule). */ - catchAllRule?: { enabled: boolean; workerName: string | null }; - failOn?: Partial>; - } = {}, -): Array { - const calls: Array = []; - const fail = (tag: CustomerEmailCleanupCall['tag']): Response | null => { - const failure = config.failOn?.[tag]; - return failure ? cfError(failure.message, failure.status) : null; - }; - const readForm = (init?: RequestInit): Record => { - const form: Record = {}; - if (typeof init?.body === 'string') { - for (const [key, value] of new URLSearchParams(init.body)) { - form[key] = value; - } - } - return form; - }; - const inner = globalThis.fetch; - vi.stubGlobal('fetch', async (input: RequestInfo | URL, init?: RequestInit) => { - const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url; - const method = init?.method ?? 'GET'; - const authorization = new Headers(init?.headers).get('Authorization'); - - if (url.startsWith('https://dash.cloudflare.com/oauth2/token')) { - calls.push({ tag: 'oauthToken', method, url, form: readForm(init) }); - const failure = fail('oauthToken'); - if (failure) { - return failure; - } - // Grant refresh tokens rotate on every use; the caller persists this - // replacement and revokes the chain HEAD, not the presented token. - return Response.json({ - access_token: 'cf-access-dummy-1', - refresh_token: 'cf-rotated-refresh-dummy-1', - expires_in: 3600, - }); - } - if (url.startsWith('https://dash.cloudflare.com/oauth2/revoke')) { - calls.push({ tag: 'oauthRevoke', method, url, form: readForm(init) }); - // RFC 7009 answers 200 whether the token was revoked or already - // invalid; the body is ignored. - return fail('oauthRevoke') ?? new Response(null, { status: 200 }); - } - - if (url.includes('/email/routing/rules/catch_all') && method === 'GET') { - calls.push({ tag: 'catchAllGet', method, url, authorization }); - const failure = fail('catchAllGet'); - if (failure) { - return failure; - } - if (!config.catchAllRule) { - return cfError('rule not found', 404); - } - return cfSuccess({ - enabled: config.catchAllRule.enabled, - matchers: [{ type: 'all' }], - actions: - config.catchAllRule.workerName === null - ? [{ type: 'drop', value: [] }] - : [{ type: 'worker', value: [config.catchAllRule.workerName] }], - }); - } - if (url.includes('/email/routing/rules/catch_all') && method === 'PUT') { - const body = typeof init?.body === 'string' ? JSON.parse(init.body) : undefined; - calls.push({ tag: 'catchAll', method, url, body, authorization }); - return fail('catchAll') ?? cfSuccess({}); - } - if (/\/accounts\/[^/]+\/workers\/scripts\/[^/?#]+$/.test(new URL(url).pathname)) { - if (method === 'DELETE') { - calls.push({ tag: 'scriptDelete', method, url, authorization }); - return fail('scriptDelete') ?? cfSuccess({}); - } - } - return inner(input, init); - }); - return calls; -} - -describe('DELETE /projects/:id — customer-side email domain cleanup', () => { - // The CUSTOMER's zone/account — deliberately distinct from the platform's - // CF_ACCOUNT_ID/CF_ZONE_ID so a teardown that billed the platform account - // would not match these stubs. - const CUSTOMER_ZONE_ID = 'zone_customer_1'; - const CUSTOMER_ACCOUNT_ID = 'acct_customer_1'; - const DOMAIN_API_TOKEN = 'cf-api-token-dummy'; - const DOMAIN_REFRESH_TOKEN = 'cf-refresh-token-dummy'; - - async function seedCustomerEmailDomain( - projectId: string, - domain: string, - options: { - status?: 'active' | 'failed'; - relayWorkerName?: string | null; - credentialKind?: 'api_token' | 'oauth_grant' | 'platform'; - accountId?: string; - } = {}, - ): Promise { - const status = options.status ?? 'active'; - const relayWorkerName = - options.relayWorkerName === undefined ? RELAY_WORKER_BASE_NAME : options.relayWorkerName; - const credentialKind = options.credentialKind ?? 'api_token'; - const accountId = options.accountId ?? CUSTOMER_ACCOUNT_ID; - // The token triple must really decrypt — teardown decrypts it to build - // the customer CF client (the grant's refresh token on the oauth_grant - // path). A platform row stores none: teardown resolves it to the - // runtime token. The relay triple is never read on this path (dummy - // stand-ins, as in seedDomainMirror above). - const tokenEnc = - credentialKind === 'platform' - ? null - : await encryptEmailDomainToken( - env, - projectId, - domain, - credentialKind === 'oauth_grant' ? DOMAIN_REFRESH_TOKEN : DOMAIN_API_TOKEN, - ); - await env.db.insert(emailDomains).values({ - id: `edom_${domain.replace(/[^a-z0-9]/g, '')}`, - project_id: projectId, - domain, - zone_id: CUSTOMER_ZONE_ID, - account_id: accountId, - mode: 'apex', - status, - credential_kind: credentialKind, - managed_by: credentialKind === 'platform' ? 'admin' : 'owner', - token_ciphertext: tokenEnc?.ciphertext ?? null, - token_iv: tokenEnc?.iv ?? null, - token_key_version: tokenEnc?.keyVersion ?? null, - relay_ciphertext: 'dummy-ct', - relay_iv: 'dummy-iv', - relay_key_version: 'v1', - relay_worker_name: relayWorkerName, - }); - await env.ROUTING.put( - `email-domain:${domain}`, - JSON.stringify({ - projectId, - status, - relaySecretSha256: '00'.repeat(32), - relayWorkerName, - accountId, - zoneId: CUSTOMER_ZONE_ID, - mode: 'apex', - }), - ); - } - - it('deletes the customer-side relay and catch-all for each registered email domain', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-cleanup'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - await seedCustomerEmailDomain(project.id, 'acme-relay.example'); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - - // removeEmailDomain's order: ownership read, conditional drop-and-disable - // reset, relay DELETE — all against the customer zone/account. - expect(customerCalls.map((call) => call.tag)).toEqual([ - 'catchAllGet', - 'catchAll', - 'scriptDelete', - ]); - expect(customerCalls[0]!.url).toContain( - `/zones/${CUSTOMER_ZONE_ID}/email/routing/rules/catch_all`, - ); - expect(customerCalls[1]!.url).toContain( - `/zones/${CUSTOMER_ZONE_ID}/email/routing/rules/catch_all`, - ); - expect(customerCalls[1]!.body).toEqual({ - matchers: [{ type: 'all' }], - actions: [{ type: 'drop' }], - enabled: false, - }); - expect(customerCalls[2]!.url).toContain( - `/accounts/${CUSTOMER_ACCOUNT_ID}/workers/scripts/${RELAY_WORKER_BASE_NAME}`, - ); - // api_token rows never touch the OAuth endpoints — there is no grant to - // refresh or revoke (the exact tag list above already pins this). - expect(customerCalls.some((call) => call.tag === 'oauthRevoke')).toBe(false); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay.example')).toBeNull(); - }); - - it('cleans up an administrator-managed platform row with the runtime token', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-platform'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - await seedCustomerEmailDomain(project.id, 'acme-platform.example', { - credentialKind: 'platform', - accountId: env.CF_ACCOUNT_ID, - }); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - expect(customerCalls.map((call) => call.tag)).toEqual([ - 'catchAllGet', - 'catchAll', - 'scriptDelete', - ]); - expect(customerCalls[2]!.url).toContain( - `/accounts/${env.CF_ACCOUNT_ID}/workers/scripts/${RELAY_WORKER_BASE_NAME}`, - ); - for (const call of customerCalls) { - expect(call.authorization).toBe(`Bearer ${env.CF_API_TOKEN}`); - } - expect(await env.ROUTING.get('email-domain:acme-platform.example')).toBeNull(); - expect(await env.db.select().from(projects).where(eq(projects.id, project.id))).toHaveLength(0); - }); - - it('still tears the project down when the runtime token is gone, leaving the relay for manual cleanup', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-platform-lost'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - await seedCustomerEmailDomain(project.id, 'acme-platform-lost.example', { - credentialKind: 'platform', - accountId: env.CF_ACCOUNT_ID, - }); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - { ...env, CF_API_TOKEN: '' }, - ); - expect(res.status).toBe(200); - // No credential, no customer-side call — but the mirror is gone and the - // project is deleted; the relay is the operator's to remove by hand. - expect(customerCalls).toEqual([]); - expect(await env.ROUTING.get('email-domain:acme-platform-lost.example')).toBeNull(); - expect(await env.db.select().from(projects).where(eq(projects.id, project.id))).toHaveLength(0); - }); - - it('revokes the OAuth grant during teardown for an oauth_grant domain', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-oauth'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - await seedCustomerEmailDomain(project.id, 'acme-relay-oauth.example', { - credentialKind: 'oauth_grant', - }); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - - // removeEmailDomain's oauth order: the serialized refresh FIRST (its - // rotation persists through the row's chain while the row still exists), - // then the customer-side cleanup, then the grant revoke LAST — against - // the ROTATED refresh token, the live chain head. - expect(customerCalls.map((call) => call.tag)).toEqual([ - 'oauthToken', - 'catchAllGet', - 'catchAll', - 'scriptDelete', - 'oauthRevoke', - ]); - expect(customerCalls[4]!.form).toMatchObject({ - token_type_hint: 'refresh_token', - token: 'cf-rotated-refresh-dummy-1', - }); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay-oauth.example')).toBeNull(); - }); - - it('still deletes the project when the grant revoke fails — revoke_grant lands in failed_steps', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-revoke-down'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { oauthRevoke: { message: 'boom', status: 500 } }, - }); - await seedCustomerEmailDomain(project.id, 'acme-relay-revoke-down.example', { - credentialKind: 'oauth_grant', - }); - // revokeOauthGrant THROWS on the 500 (a silent return would make the - // engine's revoke_grant failed_step unreachable); the warn spy catches - // the residue report, the error spy silences the helper's own log. - const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); - vi.spyOn(console, 'error').mockImplementation(() => {}); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - // Best-effort: the customer-side cleanup all ran; only the terminal - // revoke failed, and teardown proceeds regardless. - expect(res.status).toBe(200); - expect(customerCalls.map((call) => call.tag)).toEqual([ - 'oauthToken', - 'catchAllGet', - 'catchAll', - 'scriptDelete', - 'oauthRevoke', - ]); - // The revoke targeted the ROTATED chain head, as on the happy path. - expect(customerCalls[4]!.form).toMatchObject({ - token_type_hint: 'refresh_token', - token: 'cf-rotated-refresh-dummy-1', - }); - expect( - warnSpy.mock.calls.some( - (call) => - String(call[0]).includes('teardown left CF-side residue') && - JSON.stringify(call[1]).includes('revoke_grant'), - ), - ).toBe(true); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay-revoke-down.example')).toBeNull(); - }); - - it('still deletes the project when the grant refresh fails transiently — and revokes the stored token', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-oauth-down'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { oauthToken: { message: 'boom', status: 500 } }, - }); - await seedCustomerEmailDomain(project.id, 'acme-relay-oauth-down.example', { - credentialKind: 'oauth_grant', - }); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - // Best-effort: the failed refresh strands the relay and catch-all - // (failed_steps — logged, never surfaced), so deletion proceeds; the - // mirrors are already gone and the proxy denies the stranded relay. - expect(res.status).toBe(200); - - // A transient refresh failure still revokes the ORIGINAL stored - // credential: it may still be live, and the row holding it is about to - // disappear. No customer-zone call is attempted without an access token. - expect(customerCalls.map((call) => call.tag)).toEqual(['oauthToken', 'oauthRevoke']); - expect(customerCalls[1]!.form).toMatchObject({ - token_type_hint: 'refresh_token', - token: DOMAIN_REFRESH_TOKEN, - }); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay-oauth-down.example')).toBeNull(); - }); - - it('still deletes the project when customer-side email cleanup fails', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-cf-down'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { catchAllGet: { message: 'boom', status: 500 } }, - }); - await seedCustomerEmailDomain(project.id, 'acme-relay-down.example'); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - // Best-effort: the failure is logged, not surfaced — the mirrors are - // already gone, so the stranded relay is denied by the proxy. - expect(res.status).toBe(200); - - // The ownership read failed, so the consistent-pair rule skipped both - // the reset and the relay DELETE: an enabled catch-all must never be - // left pointing at a deleted worker. - expect(customerCalls.map((call) => call.tag)).toEqual(['catchAllGet']); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay-down.example')).toBeNull(); - }); - - it('does not touch the customer account for a domain that never deployed a relay', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-never-deployed'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - // A row that failed before the relay deploy has no customer-side state: - // null relay_worker_name is the skip key (zone/account may be known). - await seedCustomerEmailDomain(project.id, 'acme-relay-never.example', { - status: 'failed', - relayWorkerName: null, - }); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - expect(customerCalls).toEqual([]); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay-never.example')).toBeNull(); - }); - - it('still revokes the grant for an oauth_grant domain whose relay never deployed', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'mail-relay-never-oauth'); - mockCfApi(); - const customerCalls = captureCustomerEmailCleanup({ - catchAllRule: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - // A relay-less OAUTH row has no relay or rule to clean, but it owns a - // live customer-side grant — skipping it wholesale would orphan that - // grant with no platform handle once the cascade takes the row. - await seedCustomerEmailDomain(project.id, 'acme-relay-never-oauth.example', { - status: 'failed', - relayWorkerName: null, - credentialKind: 'oauth_grant', - }); - - const res = await app.fetch( - new Request(`http://localhost/projects/${project.id}`, { - method: 'DELETE', - headers: { Authorization: `Bearer ${user.jwt}` }, - }), - env, - ); - expect(res.status).toBe(200); - - // Refresh (chain head persisted), no zone/account calls without a - // relay, then the revoke LAST against the rotated head. - expect(customerCalls.map((call) => call.tag)).toEqual(['oauthToken', 'oauthRevoke']); - expect(customerCalls[1]!.form).toMatchObject({ - token_type_hint: 'refresh_token', - token: 'cf-rotated-refresh-dummy-1', - }); - - const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); - expect(dbProject).toBeUndefined(); - expect(await env.ROUTING.get('email-domain:acme-relay-never-oauth.example')).toBeNull(); - }); -}); - -// --------------------------------------------------------------------------- -// The other side of the same ordering problem: a destination POST that LOSES -// the race to teardown. -// -// The POST route's `status === 'deleting'` guard is an unlocked read, so the -// cascade can commit while the route is out at Cloudflare registering the -// address. The CF destination is account-level and already created by then, -// and `email_destinations` rows are the only thing that maps one back to a -// project — the cascade removed them all, teardown's cleanup already ran off -// the rows that existed, and there is no sweep. So the route has to hand the -// address back itself. -// -// NOT fixed here: the unlocked guard itself. That is the pre-existing -// orphan-on-concurrent-create class from design doc 0067, which three sibling -// provisioning routes ship with today. +// A destination created while project teardown commits must be discarded. // --------------------------------------------------------------------------- describe('POST /projects/:id/email/destinations — losing the teardown race', () => { diff --git a/platform/packages/api/test/integration/api-email-domains.test.ts b/platform/packages/api/test/integration/api-email-domains.test.ts index 2944e98c6..b32174f2e 100644 --- a/platform/packages/api/test/integration/api-email-domains.test.ts +++ b/platform/packages/api/test/integration/api-email-domains.test.ts @@ -10,7 +10,11 @@ import { vi, } from 'vite-plus/test'; import { hmacSignState } from '../../src/auth/hmac.ts'; -import { emailCredentials, emailOperations } from '../../src/email/connection-schema.ts'; +import { + emailCredentials, + emailDomainRoutes, + emailOperations, +} from '../../src/email/connection-schema.ts'; import app from '../../src/index.ts'; import { stubCustomerCf } from './email-domain-cf-stub.ts'; import { @@ -59,6 +63,53 @@ afterEach(() => { }); describe('project email domain authority', () => { + it('refreshes readiness from provider reads and preserves inbound state when the credential probe fails', async () => { + const owner = await createTestUser(env.db, 'readiness-owner'); + const project = await createTestProject(env.db, owner.id, 'readiness-mail'); + const routingRules: Array<{ enabled: boolean; addresses: Array }> = []; + const failures: { routingRulesGet?: { message: string; status: number } } = {}; + const stub = stubCustomerCf({ zones, routingRules, failOn: failures }); + expect( + ( + await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'status.example.com', + apiToken: token, + }) + ).status, + ).toBe(200); + const checkpoint = stub.calls.length; + routingRules.push({ enabled: true, addresses: ['support@status.example.com'] }); + const drifted = await call(project.id, owner.jwt, 'GET', '/domains/status.example.com'); + expect(await drifted.json()).toMatchObject({ + readiness: { + inbound: { status: 'drifted', reason: expect.stringContaining('explicit Cloudflare') }, + management: { status: 'healthy' }, + }, + }); + failures.routingRulesGet = { status: 403, message: 'permission revoked' }; + const unavailable = await call(project.id, owner.jwt, 'GET', '/domains/status.example.com'); + expect(await unavailable.json()).toMatchObject({ + readiness: { + inbound: { status: 'drifted' }, + management: { status: 'probe_failed' }, + }, + }); + delete failures.routingRulesGet; + routingRules.length = 0; + await env.db + .update(emailDomainRoutes) + .set({ inbound_status: 'pending', inbound_reason: 'waiting for setup proof' }) + .where(eq(emailDomainRoutes.project_id, project.id)); + const pending = await call(project.id, owner.jwt, 'GET', '/domains/status.example.com'); + expect(await pending.json()).toMatchObject({ + readiness: { + inbound: { status: 'pending', reason: 'waiting for setup proof' }, + management: { status: 'healthy' }, + }, + }); + expect(stub.calls.slice(checkpoint).every((call) => call.method === 'GET')).toBe(true); + }); + it('rejects unauthenticated, foreign-owner, malformed and OAuth requests before Cloudflare writes', async () => { const owner = await createTestUser(env.db, 'domain-owner'), other = await createTestUser(env.db, 'domain-other'); @@ -133,6 +184,28 @@ describe('project email domain authority', () => { }); expect(conflict.status).toBe(409); expect(await env.db.select().from(emailOperations)).toHaveLength(1); + const rotation = await call( + project.id, + owner.jwt, + 'POST', + '/domains/mail.example.com/rotate-secret', + { + attemptId: 'stable-rotation', + }, + ); + expect(rotation.status).toBe(200); + const rotated = (await rotation.json()) as { operationId: string }; + const recoveredRotation = await call( + project.id, + owner.jwt, + 'GET', + '/operations/stable-rotation', + ); + expect(recoveredRotation.status).toBe(200); + expect(await recoveredRotation.json()).toMatchObject({ + operationId: rotated.operationId, + status: 'completed', + }); }); it('leases only an exact active route for the signed owning project', async () => { diff --git a/platform/packages/api/test/integration/api-email.test.ts b/platform/packages/api/test/integration/api-email.test.ts index e0ec179a8..01b565ac1 100644 --- a/platform/packages/api/test/integration/api-email.test.ts +++ b/platform/packages/api/test/integration/api-email.test.ts @@ -51,7 +51,6 @@ import { PLATFORM_INTERNAL_EMAIL_SENTINEL, } from '../../src/email/send-verification.ts'; import app from '../../src/index.ts'; -import { syncProjectAllowlistKvBestEffort } from '../../src/provisioning/email-allowlist.ts'; import { emailDestinations, platformSettings, projects, users } from '../../src/schema.ts'; import { cfError, @@ -149,19 +148,13 @@ async function setUserEmail(userId: string, email: string): Promise { return email; } -async function readAllowlist(projectId: string): Promise> { - const raw = await env.ROUTING.get(`email-allowlist:${projectId}`); - if (!raw) { - return []; - } - const parsed = JSON.parse(raw as string) as unknown; - return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === 'string') : []; +async function readVerifiedDestinations(projectId: string): Promise> { + return (await rowsFor(projectId)) + .filter((row) => row.status === 'verified') + .map((row) => row.address); } -/** - * Two verified rows plus the matching mirror, the shape a live project has - * once both recipients confirmed. - */ +/** Two verified rows, the shape a live project has once both recipients confirmed. */ async function seedVerifiedPair(projectId: string): Promise { await env.db.insert(emailDestinations).values([ { @@ -181,67 +174,6 @@ async function seedVerifiedPair(projectId: string): Promise { verified_at: '2026-04-29T00:00:00Z', }, ]); - await env.ROUTING.put( - `email-allowlist:${projectId}`, - JSON.stringify(['keep@example.com', 'gone@example.com']), - ); -} - -/** - * Fail this project's allowlist mirror write (both branches — the `put` and - * the delete-on-empty), leaving every other KV op intact. Restored by the - * file-level `vi.restoreAllMocks()`. - */ -function breakAllowlistWrites(projectId: string): void { - const key = `email-allowlist:${projectId}`; - const originalPut = env.ROUTING.put.bind(env.ROUTING); - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( - k: string, - value: string | ArrayBuffer | ArrayBufferView | ReadableStream, - options?: KVNamespacePutOptions, - ) => { - if (k === key) { - throw new Error('forced allowlist KV failure for test'); - } - return originalPut(k, value as never, options as never); - }) as typeof env.ROUTING.put); - vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - if (k === key) { - throw new Error('forced allowlist KV failure for test'); - } - return originalDelete(k as never); - }) as typeof env.ROUTING.delete); -} - -/** - * Call `observe` with the addresses this project's mirror was just set to - * (`null` when the key was cleared), still INSIDE the awaited KV call — so an - * observer can read what the database looked like at that instant. - */ -function observeAllowlistWrites( - projectId: string, - observe: (written: Array | null) => Promise, -): void { - const key = `email-allowlist:${projectId}`; - const originalPut = env.ROUTING.put.bind(env.ROUTING); - const originalDelete = env.ROUTING.delete.bind(env.ROUTING); - vi.spyOn(env.ROUTING, 'put').mockImplementation((async ( - k: string, - value: string | ArrayBuffer | ArrayBufferView | ReadableStream, - options?: KVNamespacePutOptions, - ) => { - await originalPut(k, value as never, options as never); - if (k === key) { - await observe(JSON.parse(String(value)) as Array); - } - }) as typeof env.ROUTING.put); - vi.spyOn(env.ROUTING, 'delete').mockImplementation((async (k: string) => { - await originalDelete(k as never); - if (k === key) { - await observe(null); - } - }) as typeof env.ROUTING.delete); } /** A CF list row for `address`, verified at `verified` (null = still pending). */ @@ -681,7 +613,7 @@ describe('GET /projects/:id/email/destinations', () => { const list = (await res.json()) as Array<{ status: string; verification_source: string }>; expect(list[0]?.status).toBe('pending'); expect(list[0]?.verification_source).toBe('platform'); - expect(await readAllowlist(project.id)).toEqual([]); + expect(await readVerifiedDestinations(project.id)).toEqual([]); }); }); @@ -802,7 +734,7 @@ describe('GET refresh against a recreated Cloudflare destination', () => { expect(listedB.status).toBe(200); const bodyB = (await listedB.json()) as Array<{ status: string }>; expect(bodyB[0]?.status).toBe('verified'); - expect(await readAllowlist(projectB.id)).toEqual(['alice@example.com']); + expect(await readVerifiedDestinations(projectB.id)).toEqual(['alice@example.com']); // A registered T1, which nobody clicked: it stays pending, off the // allowlist, and says why once. @@ -812,7 +744,7 @@ describe('GET refresh against a recreated Cloudflare destination', () => { expect(bodyA).toHaveLength(1); expect(bodyA[0]?.status).toBe('pending'); expect(bodyA[0]?.verification_source).toBe('cf'); - expect(await readAllowlist(projectA.id)).toEqual([]); + expect(await readVerifiedDestinations(projectA.id)).toEqual([]); const persisted = (await rowsFor(projectA.id))[0]; expect(persisted?.status).toBe('pending'); expect(persisted?.cf_destination_id).toBe(tagT1); @@ -846,7 +778,7 @@ describe('GET refresh against a recreated Cloudflare destination', () => { const bodyA = (await listedA.json()) as Array<{ status: string; verification_source: string }>; expect(bodyA[0]?.status).toBe('verified'); expect(bodyA[0]?.verification_source).toBe('cf'); - expect(await readAllowlist(projectA.id)).toEqual(['owner@example.com']); + expect(await readVerifiedDestinations(projectA.id)).toEqual(['owner@example.com']); const persisted = (await rowsFor(projectA.id))[0]; expect(persisted?.status).toBe('verified'); expect(persisted?.cf_destination_id).toBe(tagT2); @@ -902,7 +834,7 @@ describe('GET refresh against a recreated Cloudflare destination', () => { const listed = await listDestinations(projectA.id, owner.jwt, emailEnv()); expect(listed.status).toBe(200); expect(((await listed.json()) as Array<{ status: string }>)[0]?.status).toBe('pending'); - expect(await readAllowlist(projectA.id)).toEqual([]); + expect(await readVerifiedDestinations(projectA.id)).toEqual([]); }); }); @@ -1037,305 +969,6 @@ describe('DELETE /projects/:id/email/destinations/:destId', () => { }); }); -// --------------------------------------------------------------------------- -// email-allowlist KV mirror -// -// The proxy reads `email-allowlist:` from ROUTING KV on every send. -// Postgres is the source of truth; KV is a denormalized read-cache that every -// destinations CRUD re-syncs. -// --------------------------------------------------------------------------- - -describe('email-allowlist KV sync', () => { - it('writes the address when CF reports it verified AND it matches the project owner', async () => { - // Option C — owner-relaxed reuse. Same human, same consent. - const user = await createTestUser(env.db); - await setUserEmail(user.id, 'verified@example.com'); - const project = await createTestProject(env.db, user.id); - mockCfApi(cfAlreadyVerified('cf-recovered-tag', 'verified@example.com')); - - const res = await addDestination(project.id, user.jwt, 'verified@example.com', emailEnv()); - expect(res.status).toBe(201); - expect(await readAllowlist(project.id)).toEqual(['verified@example.com']); - - const rows = await rowsFor(project.id); - expect(rows[0]?.status).toBe('verified'); - expect(rows[0]?.verification_source).toBe('cf'); - }); - - it('does NOT write a pending (unverified) destination', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - mockCfApi(); // default: `verified: null` - - const res = await addDestination(project.id, user.jwt, 'pending@example.com'); - expect(res.status).toBe(201); - expect(await readAllowlist(project.id)).toEqual([]); - }); - - it('flips KV when the GET refresh observes CF verification', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - - mockCfApi(); - const created = await addDestination(project.id, user.jwt, 'flip@example.com'); - expect(created.status).toBe(201); - expect(await readAllowlist(project.id)).toEqual([]); - - mockCfApi({ - listEmailDestinations: () => - cfSuccess([cfRow('cf-tag-flip@example.com', 'flip@example.com', '2026-04-29T00:00:00Z')]), - }); - const refresh = await listDestinations(project.id, user.jwt); - expect(refresh.status).toBe(200); - - expect(await readAllowlist(project.id)).toEqual(['flip@example.com']); - }); - - it('deletes the key when the last verified destination goes away', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.insert(emailDestinations).values({ - id: 'edst_v1', - project_id: project.id, - address: 'doomed@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-doomed', - verified_at: '2026-04-29T00:00:00Z', - }); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['doomed@example.com'])); - - mockCfApi(); - const res = await removeDestination(project.id, 'edst_v1', user.jwt); - expect(res.status).toBe(200); - // Deleted, not left as an empty array. - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); - }); - - it('keeps the other verified addresses after deleting one', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.insert(emailDestinations).values([ - { - id: 'edst_v1', - project_id: project.id, - address: 'keep@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-keep', - verified_at: '2026-04-29T00:00:00Z', - }, - { - id: 'edst_v2', - project_id: project.id, - address: 'gone@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-gone', - verified_at: '2026-04-29T00:00:00Z', - }, - ]); - await env.ROUTING.put( - `email-allowlist:${project.id}`, - JSON.stringify(['keep@example.com', 'gone@example.com']), - ); - - mockCfApi(); - const res = await removeDestination(project.id, 'edst_v2', user.jwt); - expect(res.status).toBe(200); - expect(await readAllowlist(project.id)).toEqual(['keep@example.com']); - }); - - it('repairs a mirror a swallowed write left empty, on the next listing', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - // Exactly the state a confirm-click leaves behind when its best-effort KV - // write threw: the row says verified, the mirror the proxy enforces is - // empty. - await env.db.insert(emailDestinations).values({ - id: 'edst_v1', - project_id: project.id, - address: 'stranded@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-stranded', - verified_at: '2026-04-29T00:00:00Z', - verification_source: 'platform', - }); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); - - mockCfApi(); - const res = await listDestinations(project.id, user.jwt); - expect(res.status).toBe(200); - - expect(await readAllowlist(project.id)).toEqual(['stranded@example.com']); - }); - - it('drops an address the mirror still grants but no verified row backs', async () => { - // The other direction of the same drift: a stale ALLOW is worse than a - // stale deny, so the compare must be two-way. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.insert(emailDestinations).values({ - id: 'edst_v1', - project_id: project.id, - address: 'keep@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-keep', - verified_at: '2026-04-29T00:00:00Z', - }); - await env.ROUTING.put( - `email-allowlist:${project.id}`, - JSON.stringify(['keep@example.com', 'revoked@example.com']), - ); - - mockCfApi(); - expect((await listDestinations(project.id, user.jwt)).status).toBe(200); - - expect(await readAllowlist(project.id)).toEqual(['keep@example.com']); - }); - - it('does NOT write the mirror on a listing that finds it already correct', async () => { - // The repair costs one KV READ per listing. Writing unconditionally would - // put a KV write on a read endpoint, and row ORDER must not count as - // drift — the proxy loads the value into a Set. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await seedVerifiedPair(project.id); - await env.ROUTING.put( - `email-allowlist:${project.id}`, - JSON.stringify(['gone@example.com', 'keep@example.com']), - ); - - const writes: Array | null> = []; - observeAllowlistWrites(project.id, async (written) => { - writes.push(written); - }); - - mockCfApi(); - expect((await listDestinations(project.id, user.jwt)).status).toBe(200); - expect((await listDestinations(project.id, user.jwt)).status).toBe(200); - - expect(writes).toEqual([]); - expect((await readAllowlist(project.id)).sort()).toEqual([ - 'gone@example.com', - 'keep@example.com', - ]); - }); - - it('repairs the mirror after a confirm click whose KV write really failed', async () => { - // Same repair, driven through the real path rather than a seeded state: - // the recipient clicks, Postgres commits `verified`, the mirror write - // throws and is swallowed, and the next listing is the only thing left - // that can re-derive the key. - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id); - await env.db.insert(emailDestinations).values({ - id: 'edst_confirm', - project_id: project.id, - address: 'clicker@example.com', - status: 'pending', - cf_destination_id: 'cf-tag-shared', - verified_at: null, - verification_source: 'platform', - }); - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken( - { - v: 1, - pid: project.id, - did: 'edst_confirm', - addr: 'clicker@example.com', - iat: now, - exp: now + 24 * 60 * 60, - }, - env.JWT_SECRET, - ); - - breakAllowlistWrites(project.id); - const confirmed = await app.fetch( - new Request(`http://localhost/email/destinations/confirm?token=${encodeURIComponent(token)}`), - env, - ); - // The click succeeded and the row is verified — the KV failure was - // swallowed, which is the whole problem. - expect(confirmed.status).toBe(200); - expect((await rowsFor(project.id))[0]?.status).toBe('verified'); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); - - // KV comes back. Nothing retries on its own; the listing is the repair. - vi.restoreAllMocks(); - mockCfApi(); - expect((await listDestinations(project.id, user.jwt)).status).toBe(200); - - expect(await readAllowlist(project.id)).toEqual(['clicker@example.com']); - }); - - // ------------------------------------------------------------------------- - // Revoke racing a confirmation click. - // - // The revoke snapshots the row ONCE. A platform-pending row is not in the - // mirror, so a revoke that snapshots `pending` has nothing to tighten before - // the delete. The confirm click can land in between: it flips the row and - // derives the mirror FROM the verified rows, which now include this one. - // The delete then drops the row, and the mirror still grants an address no - // row backs. Nothing in the revoke used to look at the mirror again after - // the delete, so the grant outlived the row until the next listing. - // ------------------------------------------------------------------------- - - async function seedRevokeVsConfirm(): Promise<{ - projectId: string; - jwt: string; - token: string; - }> { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'project-a'); - const sibling = await createTestProject(env.db, user.id, 'project-b'); - // The account-level Cloudflare address is SHARED with a sibling project, - // which is the case where the stale grant delivers: the revoke sees two - // referencing projects, skips the upstream delete, and Cloudflare keeps - // the address verified. (A sole-reference revoke removes the Cloudflare - // address, and the send binding refuses the recipient regardless of the - // mirror.) - await env.db.insert(emailDestinations).values([ - { - id: 'edst_pend', - project_id: project.id, - address: 'shared@example.com', - status: 'pending', - cf_destination_id: 'cf-tag-shared', - verified_at: null, - verification_source: 'platform', - }, - { - id: 'edst_sibling', - project_id: sibling.id, - address: 'shared@example.com', - status: 'verified', - cf_destination_id: 'cf-tag-shared', - verified_at: '2026-04-29T00:00:00Z', - verification_source: 'cf', - }, - ]); - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken( - { - v: 1, - pid: project.id, - did: 'edst_pend', - addr: 'shared@example.com', - iat: now, - exp: now + 24 * 60 * 60, - }, - env.JWT_SECRET, - ); - return { projectId: project.id, jwt: user.jwt, token }; - } - - async function confirmClick(token: string): Promise { - return app.fetch( - new Request(`http://localhost/email/destinations/confirm?token=${encodeURIComponent(token)}`), - env, - ); - } -}); - describe('per-project verification (Option C + Option B)', () => { it("Option C: the owner's own CF-verified address is inherited, with no platform email", async () => { const user = await createTestUser(env.db); @@ -1350,7 +983,7 @@ describe('per-project verification (Option C + Option B)', () => { expect(body.status).toBe('verified'); expect(body.verification_source).toBe('cf'); - expect(await readAllowlist(project.id)).toEqual(['owner@example.com']); + expect(await readVerifiedDestinations(project.id)).toEqual(['owner@example.com']); // No platform-side confirmation mail — that is the Option B path only. expect(proxySends(fetchMock)).toHaveLength(0); }); @@ -1390,8 +1023,8 @@ describe('per-project verification (Option C + Option B)', () => { expect(body.verification_source).toBe('platform'); expect(body.platformVerificationPending).toBe(true); - // Still pending, so the proxy must refuse sends to it. - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); + // Still pending, so SQL admission must refuse sends to it. + expect(await readVerifiedDestinations(project.id)).toEqual([]); const sends = proxySends(fetchMock); expect(sends).toHaveLength(1); @@ -1464,7 +1097,7 @@ describe('per-project verification (Option C + Option B)', () => { expect(rows).toHaveLength(1); expect(rows[0]!.status).toBe('pending'); expect(rows[0]!.verification_source).toBe('platform'); - expect(await readAllowlist(project.id)).toEqual([]); + expect(await readVerifiedDestinations(project.id)).toEqual([]); }); it("owner's own address already on the account and still PENDING: adopted, and reported as no send", async () => { @@ -1666,9 +1299,8 @@ describe('per-project verification (Option C + Option B)', () => { const res = await addDestination(project.id, user.jwt, 'shared@example.com', env); expect(res.status).toBe(500); - // Nothing was mailed, and nothing was allow-listed. + // Nothing was mailed, and the row remains pending. expect(proxySends(fetchMock)).toHaveLength(0); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); // But the row was already committed before the sender was resolved, so // the misconfigured environment leaves behind a platform-pending row // with no link in anyone's inbox. Once the var is set, a repeat POST is @@ -1722,7 +1354,7 @@ describe('POST /projects — owner destination auto-add', () => { ); } - it("inherits CF's verification for the owner's own address and primes the allowlist", async () => { + it("inherits CF's verification for the owner's own address", async () => { // A second-or-later project for the same owner: CF already has the // address, so the row starts verified with `verification_source='cf'` // and the audit columns naming whose consent was inherited. @@ -1744,7 +1376,7 @@ describe('POST /projects — owner destination auto-add', () => { verified_by_user_id: user.id, verified_by_email_snapshot: 'owner@example.com', }); - expect(await readAllowlist(project.id)).toEqual(['owner@example.com']); + expect(await readVerifiedDestinations(project.id)).toEqual(['owner@example.com']); }); it('leaves a fresh CF registration pending, with nothing allow-listed and no consent attributed', async () => { @@ -1765,7 +1397,7 @@ describe('POST /projects — owner destination auto-add', () => { verification_source: 'cf', }); expect(rows[0]?.verified_by_user_id).toBeNull(); - expect(await readAllowlist(project.id)).toEqual([]); + expect(await readVerifiedDestinations(project.id)).toEqual([]); }); it('registers nothing when the environment has no platform mail domain', async () => { @@ -1845,12 +1477,7 @@ describe('revokeOwnerVerifiedDestinationsForUserChange', () => { }, ]); - const affected = await revokeOwnerVerifiedDestinationsForUserChange( - env.db, - user.id, - 'owner@example.com', - ); - expect([...affected].sort()).toEqual([projectA.id, projectB.id].sort()); + await revokeOwnerVerifiedDestinationsForUserChange(env.db, user.id, 'owner@example.com'); const after = await env.db.select().from(emailDestinations); const byId = new Map(after.map((r) => [r.id, r])); @@ -1883,12 +1510,7 @@ describe('revokeOwnerVerifiedDestinationsForUserChange', () => { verified_by_email_snapshot: 'MixedCase@Example.com', }); - const affected = await revokeOwnerVerifiedDestinationsForUserChange( - env.db, - user.id, - 'mixedcase@example.com', - ); - expect(affected).toEqual([project.id]); + await revokeOwnerVerifiedDestinationsForUserChange(env.db, user.id, 'mixedcase@example.com'); const [row] = await env.db .select() @@ -1903,8 +1525,7 @@ describe('revokeOwnerVerifiedDestinationsForUserChange', () => { // refreshes every row that is `pending` and NOT 'platform'-sourced against // exactly that list — so demoting `status` alone leaves the row sitting in // the refresh filter, and the owner's very next `void email destinations` - // silently re-promotes it AND re-mirrors the address into the allowlist, - // undoing the revoke. Re-sourcing the row to 'platform' is the half that + // silently re-promotes it, undoing the revoke. Re-sourcing the row to 'platform' is the half that // makes it stick; this test fails without it. const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'rev-sticky'); @@ -1919,17 +1540,8 @@ describe('revokeOwnerVerifiedDestinationsForUserChange', () => { verified_by_user_id: user.id, verified_by_email_snapshot: 'owner@example.com', }); - await env.ROUTING.put(`email-allowlist:${project.id}`, JSON.stringify(['owner@example.com'])); - - const affected = await revokeOwnerVerifiedDestinationsForUserChange( - env.db, - user.id, - 'owner@example.com', - ); - expect(affected).toEqual([project.id]); - // The caller syncs the mirror; do what `routes/auth.ts` does. - await syncProjectAllowlistKvBestEffort(env.db, env.ROUTING, project.id); - expect(await readAllowlist(project.id)).toEqual([]); + await revokeOwnerVerifiedDestinationsForUserChange(env.db, user.id, 'owner@example.com'); + expect(await readVerifiedDestinations(project.id)).toEqual([]); // CF is unchanged — the address is still verified on the account. mockCfApi({ @@ -1950,8 +1562,8 @@ describe('revokeOwnerVerifiedDestinationsForUserChange', () => { expect(row?.status).toBe('pending'); expect(row?.verification_source).toBe('platform'); expect(row?.verified_at).toBeNull(); - // And the listing's mirror self-heal did not put the address back. - expect(await readAllowlist(project.id)).toEqual([]); + // The listing did not re-verify the address. + expect(await readVerifiedDestinations(project.id)).toEqual([]); }); }); @@ -2004,7 +1616,7 @@ describe('GET /email/destinations/confirm', () => { ); } - it('flips the row to verified, syncs KV, and renders the success page', async () => { + it('flips the row to verified and renders the success page', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); const did = await seedPlatformPending('shared@example.com', project); @@ -2025,7 +1637,7 @@ describe('GET /email/destinations/confirm', () => { // Audit trail: the recipient clicked OUR link, not CF's. expect(row?.verification_source).toBe('platform'); - expect(await readAllowlist(project.id)).toEqual(['shared@example.com']); + expect(await readVerifiedDestinations(project.id)).toEqual(['shared@example.com']); }); it('sets no-store and no-referrer on the success page', async () => { @@ -2144,7 +1756,7 @@ describe('GET /email/destinations/confirm', () => { .from(emailDestinations) .where(eq(emailDestinations.id, didInB)); expect(row?.status).toBe('pending'); - expect(await readAllowlist(projectB.id)).toEqual([]); + expect(await readVerifiedDestinations(projectB.id)).toEqual([]); }); it('is idempotent on an already-verified row', async () => { @@ -2195,7 +1807,7 @@ describe('GET /email/destinations/confirm', () => { const rows = await rowsFor(project.id); expect(rows[0]?.status).toBe('verified'); expect(rows[0]?.verification_source).toBe('platform'); - expect(await readAllowlist(project.id)).toEqual(['shared@example.com']); + expect(await readVerifiedDestinations(project.id)).toEqual(['shared@example.com']); }); }); @@ -2542,7 +2154,10 @@ describe('email platform capability', () => { // Not even the add rate-limit counter is charged. expect(kvPut).not.toHaveBeenCalled(); expect((await rowsFor(project.id)).map((row) => row.id).sort()).toEqual(['edst_v1', 'edst_v2']); - expect(await readAllowlist(project.id)).toEqual(['keep@example.com', 'gone@example.com']); + expect(await readVerifiedDestinations(project.id)).toEqual([ + 'keep@example.com', + 'gone@example.com', + ]); }); it('answers 501 on the public confirm link and leaves the row pending', async () => { @@ -2579,7 +2194,7 @@ describe('email platform capability', () => { const [row] = await rowsFor(project.id); expect(row).toMatchObject({ id: 'edst_gate', status: 'pending', verified_at: null }); - expect(await readAllowlist(project.id)).toEqual([]); + expect(await readVerifiedDestinations(project.id)).toEqual([]); }); it('does not gate sibling routers mounted at /projects', async () => { diff --git a/platform/packages/api/test/integration/api-projects.test.ts b/platform/packages/api/test/integration/api-projects.test.ts index d6dd7e3eb..dcd09e844 100644 --- a/platform/packages/api/test/integration/api-projects.test.ts +++ b/platform/packages/api/test/integration/api-projects.test.ts @@ -3003,12 +3003,6 @@ describe('POST /projects — owner email destination auto-add', () => { verified_by_user_id: user.id, }); expect(row.verified_at).toContain('2026-01-01'); - - // Verified on arrival, so the proxy's allowlist mirror is primed now - // rather than waiting for a refresh. - expect(JSON.parse((await env.ROUTING.get(`email-allowlist:${project.id}`))!)).toEqual([ - ownerEmail, - ]); }); it('still creates the project when CF Email Routing is down', async () => { @@ -3337,8 +3331,6 @@ describe('POST /projects — owner email destination auto-add', () => { .from(emailDestinations) .where(eq(emailDestinations.project_id, project.id)), ).toHaveLength(0); - // No row landed, so nothing to mirror for the new project either. - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); expect(calls.filter((call) => call.method === 'DELETE')).toEqual([]); const [survivor] = await env.db @@ -3425,26 +3417,4 @@ describe('POST /projects — owner email destination auto-add', () => { expect(calls).toEqual([]); expect(await res.json()).not.toHaveProperty('owner_email_destination'); }); - - // The project-slug mirror the email proxy reads to pin a project's outbound - // `from` to its own slug. Written at create time; without it the proxy - // refuses every send with `project slug unknown`. - it('writes the email-slug KV mirror for the new project', async () => { - const user = await createTestUser(env.db); - const ownerEmail = await withEmail(user.id, 'owner@example.com'); - mockCfApi(); - stubEmailRouting(() => - Response.json({ - success: true, - errors: [], - messages: [], - result: { tag: 'cf-tag-slug', email: ownerEmail, verified: null }, - }), - ); - - const res = await createProjectAs(user, 'slug-mirror-app', emailEnv()); - expect(res.status).toBe(201); - const project = (await res.json()) as { id: string }; - expect(await env.ROUTING.get(`email-slug:${project.id}`)).toBe('slug-mirror-app'); - }); }); diff --git a/platform/packages/api/test/integration/auth-email-verification.test.ts b/platform/packages/api/test/integration/auth-email-verification.test.ts index e1b39e1c1..09ec64ce3 100644 --- a/platform/packages/api/test/integration/auth-email-verification.test.ts +++ b/platform/packages/api/test/integration/auth-email-verification.test.ts @@ -514,11 +514,6 @@ describe('email verification gating on account linking', () => { verification_source: 'platform', }, ]); - await env.ROUTING.put( - `email-allowlist:${project.id}`, - JSON.stringify(['old-owner@example.com', 'teammate@example.com']), - ); - const state = await buildSignedState('github'); await seedOAuthNonce(env.db, 'test-nonce'); // Same GitHub identity, DIFFERENT verified primary email. @@ -568,12 +563,6 @@ describe('email verification gating on account linking', () => { expect(revoked?.verified_by_email_snapshot).toBeNull(); expect(byId.get('edst_third_party')?.status).toBe('verified'); - - // The proxy's per-project send boundary dropped the stale address. - const mirror = JSON.parse( - (await env.ROUTING.get(`email-allowlist:${project.id}`))!, - ) as Array; - expect(mirror).toEqual(['teammate@example.com']); }); it('leaves owner-inherited destinations alone when the primary email is unchanged', async () => { @@ -626,8 +615,7 @@ describe('email verification gating on account linking', () => { }); describe('owner email change survives a transient failure', () => { - // Shared fixture: one owner-inherited row (Option C / autoAddOwnerDestination - // shape) plus one per-recipient row, mirror already in sync. + // Shared fixture: owner-inherited consent plus independent recipient consent. async function seedRotatingOwner(providerId: string, login: string) { const existing = await createTestUser(env.db, login, 'github', providerId); await env.db @@ -657,10 +645,6 @@ describe('email verification gating on account linking', () => { verification_source: 'platform', }, ]); - await env.ROUTING.put( - `email-allowlist:${project.id}`, - JSON.stringify(['old-owner@example.com', 'teammate@example.com']), - ); return { existing, project }; } @@ -685,18 +669,16 @@ describe('email verification gating on account linking', () => { ); } - async function readState(userId: string, projectId: string, inheritedId: string) { + async function readState(userId: string, inheritedId: string) { const [user] = await env.db.select().from(users).where(eq(users.id, userId)); const [row] = await env.db .select() .from(emailDestinations) .where(eq(emailDestinations.id, inheritedId)); - const raw = await env.ROUTING.get(`email-allowlist:${projectId}`); return { email: user!.email, status: row!.status, source: row!.verification_source, - mirror: raw === null ? null : (JSON.parse(raw) as Array), }; } @@ -708,7 +690,7 @@ describe('email verification gating on account linking', () => { // retries. Before this, `users.email` was committed first and the // demotion error swallowed — every later login saw // `previousEmail === email` and the stale grant survived forever. - const { existing, project } = await seedRotatingOwner('919191', 'blip-user'); + const { existing } = await seedRotatingOwner('919191', 'blip-user'); const inheritedId = 'edst_inherited_919191'; const revokeSpy = vi @@ -723,78 +705,24 @@ describe('email verification gating on account linking', () => { // ...and NOTHING of the change is committed: the email still reads the // old address, so the stale grant is not sitting next to a rotated // `users.email` that would hide it from every later comparison. - const afterFirst = await readState(existing.id, project.id, inheritedId); + const afterFirst = await readState(existing.id, inheritedId); expect(afterFirst.email).toBe('old-owner@example.com'); expect(afterFirst.status).toBe('verified'); expect(afterFirst.source).toBe('cf'); - expect(afterFirst.mirror).toEqual(['old-owner@example.com', 'teammate@example.com']); // Second login, same new email — the retry. const second = await loginWithNewEmail('919191', 'blip-user'); expect(second.status).toBe(302); expect(revokeSpy).toHaveBeenCalledTimes(2); - const afterSecond = await readState(existing.id, project.id, inheritedId); + const afterSecond = await readState(existing.id, inheritedId); expect(afterSecond.email).toBe('new-owner@example.com'); expect(afterSecond.status).toBe('pending'); expect(afterSecond.source).toBe('platform'); - expect(afterSecond.mirror).toEqual(['teammate@example.com']); }); - it('rolls the whole change back when the mirror tighten fails, and the next login retries it', async () => { - // The mirror write is the LAST step before the commit, not a best-effort - // step after it. Before this, the email and the demotion were committed - // first and a lost mirror write was swallowed: the proxy kept - // authorizing the old address from `email-allowlist:`, every - // later login compared equal and skipped the revoke, and nothing else - // re-derived the key until the owner happened to list destinations. - const { existing, project } = await seedRotatingOwner('929292', 'kv-blip-user'); - const inheritedId = 'edst_inherited_929292'; - - const putSpy = vi.spyOn(env.ROUTING, 'put').mockRejectedValueOnce(new Error('kv blip')); - - const first = await loginWithNewEmail('929292', 'kv-blip-user'); - // A KV blip is not a failed sign-in... - expect(first.status).toBe(302); - expect(putSpy).toHaveBeenCalledTimes(1); - - // ...but NOTHING of the change is committed: the stored address is - // still the old one, so the next login sees the difference again. - const afterFirst = await readState(existing.id, project.id, inheritedId); - expect(afterFirst.email).toBe('old-owner@example.com'); - expect(afterFirst.status).toBe('verified'); - expect(afterFirst.source).toBe('cf'); - expect(afterFirst.mirror).toEqual(['old-owner@example.com', 'teammate@example.com']); - - // The tighten reads the verified rows THROUGH the transaction, so it - // sees the uncommitted demotion. Under PGlite `db` and `tx` share one - // session and a pool read would pass this suite while writing the old - // address straight back in production, so pin the handle, not the value. - const readSpy = vi.spyOn(dbModule, 'getVerifiedEmailDestinationsByProjectId'); - - // Second login, same new email — the retry, with KV healthy. - const second = await loginWithNewEmail('929292', 'kv-blip-user'); - expect(second.status).toBe(302); - // First read: the in-transaction tighten, on the tx handle. Second: the - // post-commit re-derive, on the pool. - expect(readSpy).toHaveBeenCalledTimes(2); - expect(readSpy.mock.calls[0]![0]).not.toBe(env.db); - expect(readSpy.mock.calls[1]![0]).toBe(env.db); - - const afterSecond = await readState(existing.id, project.id, inheritedId); - expect(afterSecond.email).toBe('new-owner@example.com'); - expect(afterSecond.status).toBe('pending'); - expect(afterSecond.source).toBe('platform'); - expect(afterSecond.mirror).toEqual(['teammate@example.com']); - }); - - it('leaves a key tightened by a rolled-back login deny-only, never wider than the rows', async () => { - // Two affected projects, and the SECOND tighten fails. The first key is - // already written when the transaction rolls back, so it is ahead of - // Postgres — in the tightening direction only: the proxy denies the old - // address there until the listing re-widens the key to match the rows - // that are still `verified`, and the next login retries both. - const { existing, project: first } = await seedRotatingOwner('929393', 'kv-partial-user'); + it('revokes owner-inherited consent across projects while retaining recipient consent', async () => { + const { existing, project: first } = await seedRotatingOwner('929393', 'multi-project-user'); const second = await createTestProject(env.db, existing.id, 'owner-rotate-929393-b'); await env.db.insert(emailDestinations).values({ id: 'edst_inherited_929393_b', @@ -807,119 +735,32 @@ describe('email verification gating on account linking', () => { verified_by_user_id: existing.id, verified_by_email_snapshot: 'old-owner@example.com', }); - await env.ROUTING.put( - `email-allowlist:${second.id}`, - JSON.stringify(['old-owner@example.com']), - ); - - const realPut = env.ROUTING.put.bind(env.ROUTING); - const realDelete = env.ROUTING.delete.bind(env.ROUTING); - const writes: Array = []; - vi.spyOn(env.ROUTING, 'put').mockImplementation(async (key, value, options) => { - writes.push(key); - if (writes.length === 2) { - throw new Error('kv blip'); - } - return realPut(key, value, options as never); - }); - // The second project's only verified row is the one being demoted, so - // its tighten is a delete, not a put. - vi.spyOn(env.ROUTING, 'delete').mockImplementation(async (key) => { - writes.push(key as string); - if (writes.length === 2) { - throw new Error('kv blip'); - } - return realDelete(key); - }); - - const login1 = await loginWithNewEmail('929393', 'kv-partial-user'); - expect(login1.status).toBe(302); - expect(writes).toHaveLength(2); - const [tightenedKey, failedKey] = writes as [string, string]; - const tightened = tightenedKey.endsWith(first.id) ? first : second; - const untouched = tightened === first ? second : first; - expect(failedKey).toBe(`email-allowlist:${untouched.id}`); - // Nothing committed... + const login = await loginWithNewEmail('929393', 'multi-project-user'); + expect(login.status).toBe(302); const [user] = await env.db.select().from(users).where(eq(users.id, existing.id)); - expect(user!.email).toBe('old-owner@example.com'); - const rows = await env.db + expect(user?.email).toBe('new-owner@example.com'); + const destinations = await env.db .select() .from(emailDestinations) .where(eq(emailDestinations.verified_by_user_id, existing.id)); - expect(rows.map((r) => r.status)).toEqual(['verified', 'verified']); - // ...the untouched key is exactly as it was... - const untouchedMirror = await env.ROUTING.get(`email-allowlist:${untouched.id}`); - expect(JSON.parse(untouchedMirror!)).toContain('old-owner@example.com'); - // ...and the tightened key is missing the old address — deny, not grant. - const tightenedMirror = await env.ROUTING.get(`email-allowlist:${tightened.id}`); - expect( - tightenedMirror === null || !JSON.parse(tightenedMirror).includes('old-owner@example.com'), - ).toBe(true); - - // The listing repairs the tightened key back to the rows Postgres still - // holds — the rollback means the owner's address has NOT changed yet. - vi.mocked(env.ROUTING.put).mockImplementation(realPut as never); - vi.mocked(env.ROUTING.delete).mockImplementation(realDelete as never); - const list = await app.fetch( - new Request(`http://localhost/projects/${tightened.id}/email/destinations`, { - headers: { Authorization: `Bearer ${existing.jwt}` }, - }), - env, - executionCtx, + expect(destinations).toHaveLength(0); + const firstRows = await env.db + .select() + .from(emailDestinations) + .where(eq(emailDestinations.project_id, first.id)); + expect(firstRows.find((row) => row.address === 'old-owner@example.com')?.status).toBe( + 'pending', ); - expect(list.status).toBe(200); - expect(JSON.parse((await env.ROUTING.get(`email-allowlist:${tightened.id}`))!)).toContain( - 'old-owner@example.com', + expect(firstRows.find((row) => row.address === 'teammate@example.com')?.status).toBe( + 'verified', ); - - // The next login retries the whole change. - const login2 = await loginWithNewEmail('929393', 'kv-partial-user'); - expect(login2.status).toBe(302); - const [after] = await env.db.select().from(users).where(eq(users.id, existing.id)); - expect(after!.email).toBe('new-owner@example.com'); - expect(JSON.parse((await env.ROUTING.get(`email-allowlist:${first.id}`))!)).toEqual([ - 'teammate@example.com', - ]); - expect(await env.ROUTING.get(`email-allowlist:${second.id}`)).toBeNull(); - }); - - it('undoes a re-widen that lands between the tighten and the commit', async () => { - // A listing repair (or a confirm click) that derives its mirror while - // the demotion is still uncommitted sees `verified` rows next to a key - // the tighten already narrowed, and writes the old address back. That - // interleaving needs a second Postgres session, which PGlite does not - // have, so model its effect at the seam: the moment the tighten's put - // lands, overwrite the key with the wide value. The best-effort - // re-derive after the commit must undo it. - const { existing, project } = await seedRotatingOwner('929494', 'kv-rewiden-user'); - const inheritedId = 'edst_inherited_929494'; - const key = `email-allowlist:${project.id}`; - - const realPut = env.ROUTING.put.bind(env.ROUTING); - const values: Array = []; - vi.spyOn(env.ROUTING, 'put').mockImplementation(async (k, value, options) => { - values.push(value as string); - await realPut(k, value, options as never); - if (values.length === 1) { - await realPut(k, JSON.stringify(['old-owner@example.com', 'teammate@example.com'])); - } - }); - - const res = await loginWithNewEmail('929494', 'kv-rewiden-user'); - expect(res.status).toBe(302); - // In-transaction tighten, then the post-commit re-derive. - expect(values).toEqual([ - JSON.stringify(['teammate@example.com']), - JSON.stringify(['teammate@example.com']), - ]); - const after = readState(existing.id, project.id, inheritedId); - expect(await after).toMatchObject({ - email: 'new-owner@example.com', - status: 'pending', - mirror: ['teammate@example.com'], - }); - expect(await env.ROUTING.get(key)).toBe(JSON.stringify(['teammate@example.com'])); + const [secondRow] = await env.db + .select() + .from(emailDestinations) + .where(eq(emailDestinations.project_id, second.id)); + expect(secondRow?.status).toBe('pending'); + expect(secondRow?.verification_source).toBe('platform'); }); }); @@ -929,9 +770,9 @@ describe('email verification gating on account linking', () => { // The demotion above runs `UPDATE users` + the revoke in one transaction, // but it can only demote rows that EXIST when it runs. A login that // changes the address while the auto-add is parked at Cloudflare commits - // first and finds nothing; the auto-add then inserts the OLD address as - // `verified`, attributed to the OLD identity, and mirrors it into the - // allowlist. Every later login compares equal and never looks again. + // first and finds nothing; the auto-add must not insert the OLD address as + // `verified`, attributed to the OLD identity. Every later login compares + // equal and never revisits that grant. // // Interleaves at the Cloudflare stub: the projects route awaits the stub, // and the stub drives the real `/auth/callback` before answering. Both @@ -1041,7 +882,6 @@ describe('email verification gating on account linking', () => { .from(emailDestinations) .where(eq(emailDestinations.project_id, project.id)); expect(rows.filter((r) => r.status === 'verified')).toEqual([]); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); // Nothing references the tag any more, so the add released it — the // same rollback every other post-allocation failure takes. expect(calls.filter((c) => c.method === 'DELETE').map((c) => c.url)).toEqual([ @@ -1139,7 +979,6 @@ describe('email verification gating on account linking', () => { .from(emailDestinations) .where(eq(emailDestinations.project_id, project.id)); expect(rows).toEqual([]); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); expect(calls.filter((c) => c.method === 'DELETE').map((c) => c.url)).toEqual([ expect.stringContaining('/email/routing/addresses/cf-tag-racing-manual'), ]); @@ -1242,7 +1081,6 @@ describe('email verification gating on account linking', () => { verified_by_user_id: null, verified_by_email_snapshot: null, }); - expect(await env.ROUTING.get(`email-allowlist:${project.id}`)).toBeNull(); }); }); }); diff --git a/platform/packages/api/test/integration/email-admission.test.ts b/platform/packages/api/test/integration/email-admission.test.ts index b475c0fb1..88c81ce0d 100644 --- a/platform/packages/api/test/integration/email-admission.test.ts +++ b/platform/packages/api/test/integration/email-admission.test.ts @@ -16,6 +16,11 @@ import { setProjectEmailSuspended, transitionEmailRecipients, } from '../../src/email/admission.ts'; +import { + emailCredentials, + emailDomainRoutes, + emailZoneConnections, +} from '../../src/email/connection-schema.ts'; import { setEmailRecipientPolicy } from '../../src/email/settings.ts'; import { emailDestinations, projects } from '../../src/schema.ts'; import { @@ -70,6 +75,98 @@ function input(projectId: string, key: string, recipients = ['one@example.com']) } describe('authoritative email admission', () => { + it('records unsupported relayed forwarding without charging and retains native verified forwarding', async () => { + const project = await fixture(); + await env.db.insert(emailCredentials).values({ + id: 'cred', + installation_id: 'installation', + managed_by: 'admin', + kind: 'platform', + account_id: 'account', + zone_id: 'zone', + }); + await env.db.insert(emailZoneConnections).values({ + id: 'connection', + installation_id: 'installation', + account_id: 'account', + zone_id: 'zone', + zone_name: 'example.com', + managed_by: 'admin', + credential_id: 'cred', + ingress_worker_name: 'gateway', + secret_ciphertext: 'ciphertext', + secret_iv: 'iv', + secret_key_version: 'key', + management_status: 'healthy', + }); + await env.db.insert(emailDomainRoutes).values({ + id: 'route', + domain: 'example.com', + connection_id: 'connection', + project_id: project.id, + addressing: 'custom', + managed_by: 'admin', + inbound_status: 'ready', + outbound_status: 'ready', + }); + const receiptId = 'f'.repeat(64); + await recordEmailReceipt(env.db, { + receiptId, + projectId: project.id, + status: 'handler_completed', + }); + const forward = { + ...input(project.id, 'relay-forward'), + kind: 'forward' as const, + from: 'support@example.com', + receiptId, + }; + const unsupported = await admitEmailAction(env.db, { ...forward, transport: 'send_raw' }); + expect(unsupported.recipients).toMatchObject([ + { state: 'rejected', errorCode: 'UNSUPPORTED_ACTION' }, + ]); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(0); + const native = await admitEmailAction(env.db, { + ...forward, + key: 'native-forward', + transport: 'native_forward', + recipients: ['one@example.com', 'unverified@example.net'], + }); + expect(native.recipients).toEqual( + expect.arrayContaining([ + expect.objectContaining({ recipient: 'one@example.com', state: 'reserved' }), + expect.objectContaining({ + recipient: 'unverified@example.net', + state: 'rejected', + errorCode: 'UNVERIFIED_DESTINATION', + }), + ]), + ); + }); + + it('keeps invalid handler actions visible when completing and replaying a receipt', async () => { + const project = await fixture(); + const identity = { + receiptId: 'c'.repeat(64), + payloadDigest: 'd'.repeat(64), + projectId: project.id, + }; + await claimRelayedEmailReceipt(env.db, identity); + await recordEmailReceipt(env.db, { ...identity, status: 'actions_rejected' }); + await completeRelayedEmailReceipt(env.db, { ...identity, reject: false }); + expect(await claimRelayedEmailReceipt(env.db, identity)).toEqual({ + state: 'completed', + reject: false, + }); + expect((await getProjectEmailLogs(env.db, project.id)).logs).toEqual([ + expect.objectContaining({ + receiptId: identity.receiptId, + status: 'actions_rejected', + errorCode: 'INVALID_ACTIONS', + }), + ]); + }); + it('claims a relay invocation once and replays its completed outcome without rerunning it', async () => { const project = await fixture(); const identity = { diff --git a/platform/packages/api/test/integration/email-connections.test.ts b/platform/packages/api/test/integration/email-connections.test.ts index cfd195b71..26c5c959a 100644 --- a/platform/packages/api/test/integration/email-connections.test.ts +++ b/platform/packages/api/test/integration/email-connections.test.ts @@ -12,6 +12,8 @@ import { import { emailUnresolvedAttempts } from '../../src/email/admission-schema.ts'; import { disableEmailDomainRouteAndDrain } from '../../src/email/admission.ts'; import { + emailCacheOutbox, + emailCredentials, emailDomainRoutes, emailOperationSteps, emailOperations, @@ -19,6 +21,8 @@ import { } from '../../src/email/connection-schema.ts'; import { ensureSharedEmailConnection, + flushEmailCacheOutbox, + getEmailOperation, reconcilePendingEmailOperations, requestEmailDomainAdd, requestEmailDomainRemove, @@ -67,6 +71,73 @@ afterEach(() => { }); describe('durable zone email connections', () => { + it('checks MX and explicit routing conflicts for new assignments on an existing zone', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'sibling-preflight'); + const routingRules: Array<{ enabled: boolean; addresses: Array }> = []; + const stub = stubCustomerCf({ + zones, + routingRules, + mx: { 'occupied.example.com': ['mx.other.test'] }, + }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'first.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const writes = stub.calls.filter((call) => call.method !== 'GET').length; + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'occupied.example.com', + actor, + token: TOKEN, + }), + ).rejects.toThrow('already has MX'); + routingRules.push({ enabled: true, addresses: ['owner@second.example.com'] }); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'second.example.com', + actor, + token: TOKEN, + }), + ).rejects.toThrow('explicit Cloudflare email rules conflict'); + expect(stub.calls.filter((call) => call.method !== 'GET')).toHaveLength(writes); + expect(await env.db.select().from(emailDomainRoutes)).toHaveLength(1); + }); + + it('returns the same operation for concurrent rotation and sync requests with the same key', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'operation-replay'); + stubCustomerCf({ zones }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'replay.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const { connection } = (await resolveEmailDomain(env.db, 'replay.example.com'))!; + const rotations = await Promise.all( + Array.from({ length: 3 }, () => + requestEmailSecretRotation(env.db, bindings(), connection.id, actor, 'same-rotation'), + ), + ); + expect(new Set(rotations).size).toBe(1); + await runEmailOperation(env.db, bindings(), rotations[0]); + const syncs = await Promise.all( + Array.from({ length: 3 }, () => + requestEmailDomainSync(env.db, bindings(), add.routeId, actor, 'same-sync'), + ), + ); + expect(new Set(syncs).size).toBe(1); + }); + it('persists removal behind an unknown setup and resumes after project deletion', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'remove-unknown'); @@ -204,6 +275,224 @@ describe('durable zone email connections', () => { ); }); + it('re-adds a removed last route with a new credential, deployed secret, and cache version', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'readd-mail'); + const stub = stubCustomerCf({ zones }); + const actor = { kind: 'owner' as const, userId: user.id }; + const first = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'readd.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), first.operationId); + const original = (await resolveEmailDomain(env.db, 'readd.example.com'))!; + const removed = await requestEmailDomainRemove(env.db, bindings(), first.routeId, actor); + await runEmailOperation(env.db, bindings(), removed); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + expect( + (await resolveEmailDomain(env.db, 'readd.example.com'))?.connection.credential_id, + ).toBeNull(); + expect(await env.db.select().from(emailCredentials)).toHaveLength(0); + await expect(requestEmailDomainSync(env.db, bindings(), first.routeId, actor)).rejects.toThrow( + 'must be active', + ); + await flushEmailCacheOutbox(env.db, env.ROUTING); + const cacheBase = `email-cache:route:${first.routeId}`; + const removedVersion = Number(await env.ROUTING.get(`${cacheBase}:latest`)); + expect(JSON.parse((await env.ROUTING.get(`${cacheBase}:v${removedVersion}`))!).status).toBe( + 'removed', + ); + + const readded = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'readd.example.com', + actor, + token: TOKEN, + }); + expect(readded.routeId).toBe(first.routeId); + const pending = (await resolveEmailDomain(env.db, 'readd.example.com'))!; + expect(pending.route.desired_generation).toBeGreaterThan(removedVersion); + expect(pending.route.inbound_status).toBe('pending'); + expect(pending.route.outbound_status).toBe('pending'); + expect(pending.connection.credential_id).not.toBeNull(); + await runEmailOperation(env.db, bindings(), readded.operationId); + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, readded.operationId)) + )[0]?.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(2); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + expect((await resolveEmailDomain(env.db, 'readd.example.com'))?.route.inbound_status).toBe( + 'ready', + ); + await flushEmailCacheOutbox(env.db, env.ROUTING); + const activeVersion = Number(await env.ROUTING.get(`${cacheBase}:latest`)); + expect(activeVersion).toBeGreaterThan(removedVersion); + expect(JSON.parse((await env.ROUTING.get(`${cacheBase}:v${activeVersion}`))!).status).toBe( + 'active', + ); + expect(original.connection.id).toBe(pending.connection.id); + expect(await env.db.select().from(emailCacheOutbox)).toHaveLength(3); + }); + + it('retains the credential after an uncertain ingress delete until readback proves cleanup', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'unknown-delete'); + const existingScripts: Array = []; + const failures: { scriptDelete?: { message: string; status: number } } = {}; + const stub = stubCustomerCf({ zones, existingScripts, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'unknown-delete.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const connection = (await resolveEmailDomain(env.db, 'unknown-delete.example.com'))!.connection; + existingScripts.push(connection.ingress_worker_name); + const remove = await requestEmailDomainRemove(env.db, bindings(), add.routeId, actor); + failures.scriptDelete = { message: 'response lost', status: 504 }; + await runEmailOperation(env.db, bindings(), remove); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] + ?.status, + ).toBe('unknown'); + expect( + (await resolveEmailDomain(env.db, 'unknown-delete.example.com'))?.connection.credential_id, + ).not.toBeNull(); + await reconcilePendingEmailOperations(env.db, bindings()); + expect( + (await resolveEmailDomain(env.db, 'unknown-delete.example.com'))?.connection.credential_id, + ).not.toBeNull(); + existingScripts.length = 0; + delete failures.scriptDelete; + await reconcilePendingEmailOperations(env.db, bindings()); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] + ?.status, + ).toBe('completed'); + expect( + (await resolveEmailDomain(env.db, 'unknown-delete.example.com'))?.connection.credential_id, + ).toBeNull(); + expect(await env.db.select().from(emailCredentials)).toHaveLength(0); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + }); + + it('transfers only a completed removed assignment and never exposes old operation history', async () => { + const manager = await createTestUser(env.db, 'transfer-manager'); + const stranger = await createTestUser(env.db, 'transfer-stranger'); + const source = await createTestProject(env.db, manager.id, 'transfer-source'); + const target = await createTestProject(env.db, manager.id, 'transfer-target'); + const foreign = await createTestProject(env.db, stranger.id, 'transfer-foreign'); + stubCustomerCf({ zones }); + const actor = { kind: 'owner' as const, userId: manager.id }; + const first = await requestEmailDomainAdd(env.db, bindings(), { + projectId: source.id, + domain: 'transfer.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), first.operationId); + await flushEmailCacheOutbox(env.db, env.ROUTING); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: target.id, + domain: 'transfer.example.com', + actor, + token: TOKEN, + }), + ).rejects.toThrow('assigned to another project'); + const removed = await requestEmailDomainRemove(env.db, bindings(), first.routeId, actor); + await runEmailOperation(env.db, bindings(), removed); + await flushEmailCacheOutbox(env.db, env.ROUTING); + const oldHint = await env.ROUTING.get(`email-cache:route:${first.routeId}:latest`); + expect(oldHint).not.toBeNull(); + expect( + JSON.parse((await env.ROUTING.get(`email-cache:route:${first.routeId}:v${oldHint}`))!).status, + ).toBe('removed'); + expect( + await resolveEmailIngress(env.db, { + installationId: 'void-hosted', + accountId: 'customer-account', + zoneId: 'zone-example', + ingressName: (await resolveEmailDomain(env.db, 'transfer.example.com'))!.connection + .ingress_worker_name, + recipient: 'hello@transfer.example.com', + }), + ).toBeNull(); + await env.db.insert(emailUnresolvedAttempts).values({ + id: 'transfer-unresolved', + project_id: source.id, + sender_domain: 'transfer.example.com', + started_at: new Date().toISOString(), + }); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: target.id, + domain: 'transfer.example.com', + actor, + token: TOKEN, + }), + ).rejects.toThrow('sends are unresolved'); + await env.db + .delete(emailUnresolvedAttempts) + .where(eq(emailUnresolvedAttempts.id, 'transfer-unresolved')); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: foreign.id, + domain: 'transfer.example.com', + actor: { kind: 'owner', userId: stranger.id }, + token: TOKEN, + }), + ).rejects.toThrow('manager approval'); + + const transfer = await requestEmailDomainAdd(env.db, bindings(), { + projectId: target.id, + domain: 'transfer.example.com', + actor, + token: TOKEN, + }); + expect(transfer.routeId).toBe(first.routeId); + expect((await resolveEmailDomain(env.db, 'transfer.example.com'))?.route.project_id).toBe( + target.id, + ); + expect(await getEmailOperation(env.db, target.id, first.operationId)).toBeNull(); + expect(await getEmailOperation(env.db, source.id, transfer.operationId)).toBeNull(); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, first.operationId)) + )[0], + ).toBeTruthy(); + await runEmailOperation(env.db, bindings(), transfer.operationId); + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, transfer.operationId)) + )[0]?.status, + ).toBe('completed'); + const live = await resolveEmailIngress(env.db, { + installationId: 'void-hosted', + accountId: 'customer-account', + zoneId: 'zone-example', + ingressName: (await resolveEmailDomain(env.db, 'transfer.example.com'))!.connection + .ingress_worker_name, + recipient: 'hello@transfer.example.com', + }); + expect(live?.route.project_id).toBe(target.id); + await flushEmailCacheOutbox(env.db, env.ROUTING); + const newHint = await env.ROUTING.get(`email-cache:route:${first.routeId}:latest`); + expect(Number(newHint)).toBeGreaterThan(Number(oldHint)); + }); + it('serializes two sibling removals behind an unresolved connection write', async () => { const user = await createTestUser(env.db); const aProject = await createTestProject(env.db, user.id, 'queued-a'); @@ -307,6 +596,9 @@ describe('durable zone email connections', () => { 'ready', ); expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + expect( + (await resolveEmailDomain(env.db, 'support.example.com'))?.connection.credential_id, + ).not.toBeNull(); }); it('commits step intent before provider writes and fences an ambiguous result', async () => { diff --git a/platform/packages/api/test/integration/email-domain-cf-stub.ts b/platform/packages/api/test/integration/email-domain-cf-stub.ts index 4f13a5fe8..3f8b963ab 100644 --- a/platform/packages/api/test/integration/email-domain-cf-stub.ts +++ b/platform/packages/api/test/integration/email-domain-cf-stub.ts @@ -1,9 +1,8 @@ import { vi } from 'vite-plus/test'; -import { hashEmailRelaySecret } from '../../src/email/domains.ts'; import { cfError, cfSuccess } from './helpers.ts'; // --------------------------------------------------------------------------- -// Customer-side CF/OAuth/DNS fetch stub +// Customer-side Cloudflare and DNS fetch stub // --------------------------------------------------------------------------- export type StubFailTag = @@ -24,9 +23,7 @@ export type StubFailTag = | 'catchAllGet' | 'routingRulesGet' | 'routingSettingsGet' - | 'scriptDelete' - | 'oauthToken' - | 'oauthRevoke'; + | 'scriptDelete'; export type RecordedCall = { tag: StubFailTag; @@ -34,8 +31,6 @@ export type RecordedCall = { url: string; /** Parsed JSON body for string bodies; parsed metadata for the script PUT. */ body?: unknown; - /** OAuth token-endpoint form fields, minus nothing — dummy fixtures only. */ - form?: Record; /** Secrets PUT shape: name/type/text shape — never the text itself. */ secret?: { name: string; type: string; textShape: string }; }; @@ -56,16 +51,15 @@ export function stubCustomerCf( catchAllRule?: { enabled: boolean; workerName: string | null } | null; /** GET email/routing's result; default { enabled: true }. */ routingSettings?: Record; + routingRules?: Array<{ enabled: boolean; addresses: Array }>; /** GET sending/subdomains entries; default []. */ sendingSubdomains?: ReadonlyArray<{ name: string; enabled: boolean }>; failOn?: Partial>; /** Side-effect hook fired right after a call is recorded (mid-request seams). */ on?: Partial void | Promise>>; - oauth?: 'rotate' | 'invalid_grant' | 'server_error'; } = {}, ) { const calls: Array = []; - let oauthRound = 0; const fail = (tag: StubFailTag): Response | null => { const failure = config.failOn?.[tag]; return failure ? cfError(failure.message, failure.status, failure.code) : null; @@ -100,49 +94,6 @@ export function stubCustomerCf( typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url; const method = init?.method ?? 'GET'; - if (url.startsWith('https://dash.cloudflare.com/oauth2/token')) { - const form: Record = {}; - if (typeof init?.body === 'string') { - for (const [key, value] of new URLSearchParams(init.body)) { - form[key] = value; - } - } - await record({ tag: 'oauthToken', method, url, form }); - const failure = fail('oauthToken'); - if (failure) { - return failure; - } - if (config.oauth === 'invalid_grant') { - return Response.json({ error: 'invalid_grant' }, { status: 400 }); - } - if (config.oauth === 'server_error') { - return Response.json({ error: 'temporarily_unavailable' }, { status: 503 }); - } - // Chain off the incoming token so the rotation survives stub resets: - // a presented `cf-rotated-refresh-dummy-N` rotates to N+1, anything - // else (the originally posted grant) starts at 1. - const roundMatch = /^cf-rotated-refresh-dummy-(\d+)$/.exec(form.refresh_token ?? ''); - oauthRound = roundMatch ? Number(roundMatch[1]) + 1 : 1; - return Response.json({ - access_token: `cf-access-dummy-${oauthRound}`, - refresh_token: `cf-rotated-refresh-dummy-${oauthRound}`, - expires_in: 3600, - }); - } - - if (url.startsWith('https://dash.cloudflare.com/oauth2/revoke')) { - const form: Record = {}; - if (typeof init?.body === 'string') { - for (const [key, value] of new URLSearchParams(init.body)) { - form[key] = value; - } - } - await record({ tag: 'oauthRevoke', method, url, form }); - // RFC 7009 answers 200 whether the token was revoked or already - // invalid; the body is ignored. - return fail('oauthRevoke') ?? new Response(null, { status: 200 }); - } - if (url.startsWith('https://cloudflare-dns.com/dns-query')) { await record({ tag: 'mxLookup', method, url }); const failure = fail('mxLookup'); @@ -308,7 +259,15 @@ export function stubCustomerCf( if (/\/zones\/[^/]+\/email\/routing\/rules\?/.test(path) && method === 'GET') { await record({ tag: 'routingRulesGet', method, url }); - return fail('routingRulesGet') ?? cfSuccess([]); + return ( + fail('routingRulesGet') ?? + cfSuccess( + (config.routingRules ?? []).map((rule) => ({ + enabled: rule.enabled, + matchers: rule.addresses.map((value) => ({ type: 'literal', field: 'to', value })), + })), + ) + ); } const catchAllMatch = /\/zones\/([^/]+)\/email\/routing\/rules\/catch_all$/.exec(path); @@ -358,7 +317,7 @@ export function stubCustomerCf( // The worker's CURRENT secret, tracked by sha256 only — the same // form the ROUTING mirror stores — so a test can prove worker, row // and mirror carry ONE secret without the value ever being recorded. - secretHashes.set(secretsMatch[1]!, await hashEmailRelaySecret(text)); + secretHashes.set(secretsMatch[1]!, await sha256Hex(text)); relaySecrets.set(secretsMatch[1]!, text); await record({ tag: 'secretPut', @@ -421,3 +380,8 @@ export function sleep(ms: number): Promise { export function tags(calls: Array): Array { return calls.map((call) => call.tag); } + +async function sha256Hex(value: string): Promise { + const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value)); + return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join(''); +} diff --git a/platform/packages/api/test/integration/scheduled.test.ts b/platform/packages/api/test/integration/scheduled.test.ts index b9d2541a3..6acef4dd5 100644 --- a/platform/packages/api/test/integration/scheduled.test.ts +++ b/platform/packages/api/test/integration/scheduled.test.ts @@ -145,95 +145,6 @@ describe('scheduled()', () => { expect(routing.userId).toBe(id); }); - it('backfills a missing email-slug mirror for a legacy project', async () => { - const { id } = await createTestUser(env.db, 'emailslug', 'github', undefined, 'free'); - // createTestProject inserts the DB row only — no `email-slug:` mirror, - // exactly like a project created before the mirror existed. - const proj = await createTestProject(env.db, id); - await env.ROUTING.put(proj.slug, JSON.stringify({ worker: 'test', projectId: proj.id })); - expect(await env.ROUTING.get(`email-slug:${proj.id}`)).toBeNull(); - - await scheduled(mockController, makeBindings(env), mockCtx); - - expect(await env.ROUTING.get(`email-slug:${proj.id}`)).toBe(proj.slug); - }); - - it('still backfills the email-slug mirror when a sibling routing entry is malformed JSON', async () => { - const { id } = await createTestUser(env.db, 'emailslugbad', 'github', undefined, 'free'); - const bad = await createTestProject(env.db, id); - const good = await createTestProject(env.db, id); - // The routing-JSON backfill throws on this entry every hourly pass. That - // must not hold the email-slug mirror hostage for the rest of the user's - // projects — nor for this one, whose mirror does not depend on the entry. - await env.ROUTING.put(bad.slug, '{not json'); - await env.ROUTING.put(good.slug, JSON.stringify({ worker: 'test', projectId: good.id })); - - await expect(scheduled(mockController, makeBindings(env), mockCtx)).resolves.toBeUndefined(); - - expect(await env.ROUTING.get(`email-slug:${bad.id}`)).toBe(bad.slug); - expect(await env.ROUTING.get(`email-slug:${good.id}`)).toBe(good.slug); - }); - - /** The email-slug backfill's own warnings — other hourly steps warn too. */ - function backfillWarnings(spy: { - mock: { calls: ReadonlyArray> }; - }): Array { - return spy.mock.calls - .map((call) => String(call[0])) - .filter((line) => line.startsWith('[backfill] removed email-slug mirror')); - } - - // `noreply`, `postmaster`, `abuse`, `bounce` and `security` were reserved - // only when email shipped. A project that registered one before that - // still holds it (`createTestProject` inserts the row directly, exactly - // like the pre-reservation create path did), and the mirror is what - // authorizes `/email/send` for it — so the backfill must never write one, - // and must remove one written before the slug was reserved. - it('writes no email-slug mirror for a legacy project holding a reserved email slug', async () => { - const { id } = await createTestUser(env.db, 'reservedslug', 'github', undefined, 'free'); - const legacy = await createTestProject(env.db, id, 'noreply'); - const sibling = await createTestProject(env.db, id); - await env.ROUTING.put(legacy.slug, JSON.stringify({ worker: 'test', projectId: legacy.id })); - await env.ROUTING.put(sibling.slug, JSON.stringify({ worker: 'test', projectId: sibling.id })); - const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {}); - try { - await scheduled(mockController, makeBindings(env), mockCtx); - } finally { - consoleWarn.mockRestore(); - } - - expect(await env.ROUTING.get(`email-slug:${legacy.id}`)).toBeNull(); - // Withholding is silent: there was nothing to remove. - expect(backfillWarnings(consoleWarn)).toEqual([]); - // The sibling in the same user's loop is unaffected. - expect(await env.ROUTING.get(`email-slug:${sibling.id}`)).toBe(sibling.slug); - }); - - it('removes an email-slug mirror written before the slug was reserved', async () => { - const { id } = await createTestUser(env.db, 'reservedmirror', 'github', undefined, 'free'); - const legacy = await createTestProject(env.db, id, 'postmaster'); - // Written by createProject back when `postmaster` was claimable. - await env.ROUTING.put(`email-slug:${legacy.id}`, legacy.slug); - await env.ROUTING.put(legacy.slug, JSON.stringify({ worker: 'test', projectId: legacy.id })); - const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {}); - try { - await scheduled(mockController, makeBindings(env), mockCtx); - // Logged once, on the pass that removes it … - const warnings = backfillWarnings(consoleWarn); - expect(warnings).toHaveLength(1); - expect(warnings[0]).toContain(legacy.id); - expect(await env.ROUTING.get(`email-slug:${legacy.id}`)).toBeNull(); - - // … and not again on the next pass, which has nothing to remove. - consoleWarn.mockClear(); - await scheduled(mockController, makeBindings(env), mockCtx); - expect(backfillWarnings(consoleWarn)).toEqual([]); - expect(await env.ROUTING.get(`email-slug:${legacy.id}`)).toBeNull(); - } finally { - consoleWarn.mockRestore(); - } - }); - it('does not overwrite existing userId in routing entries', async () => { const { id } = await createTestUser(env.db, 'existing', 'github', undefined, 'free'); const proj = await createTestProject(env.db, id); diff --git a/platform/packages/api/test/unit/email-cf-customer.test.ts b/platform/packages/api/test/unit/email-cf-customer.test.ts index 20faf304b..540997971 100644 --- a/platform/packages/api/test/unit/email-cf-customer.test.ts +++ b/platform/packages/api/test/unit/email-cf-customer.test.ts @@ -1,12 +1,5 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vite-plus/test'; -import { - CF_CUSTOMER_API_BASE, - CF_EMAIL_OAUTH_CLIENT_ID, - OAuthGrantError, - createCfCustomerClient, - refreshOauthGrant, - revokeOauthGrant, -} from '../../src/email/cf-customer.ts'; +import { CF_CUSTOMER_API_BASE, createCfCustomerClient } from '../../src/email/cf-customer.ts'; import { CloudflareApiError } from '../../src/provisioning/cloudflare-api.ts'; // Dummy stand-ins — never real token material, per the no-secrets rule. @@ -203,8 +196,10 @@ describe('cf-customer client', () => { await client.putRelayScript(ACCOUNT, RELAY, { source: 'export default {};\n', compatibilityDate: '2026-09-01', - proxyOrigin: 'https://proxy.example.test', - emailDomain: 'acme.com', + gatewayOrigin: 'https://gateway.example.test', + accountId: ACCOUNT, + zoneId: ZONE, + ingressName: RELAY, }); const { url, init } = lastCall(fetchMock); @@ -225,10 +220,10 @@ describe('cf-customer client', () => { { type: 'plain_text', name: 'VOID_EMAIL_GATEWAY_ORIGIN', - text: 'https://proxy.example.test', + text: 'https://gateway.example.test', }, { type: 'plain_text', name: 'VOID_EMAIL_ACCOUNT', text: ACCOUNT }, - { type: 'plain_text', name: 'VOID_EMAIL_ZONE', text: '' }, + { type: 'plain_text', name: 'VOID_EMAIL_ZONE', text: ZONE }, { type: 'plain_text', name: 'VOID_EMAIL_INGRESS', text: RELAY }, ], }); @@ -430,140 +425,3 @@ describe('cf-customer client', () => { }); }); }); - -describe('refreshOauthGrant', () => { - let fetchMock: ReturnType; - - beforeEach(() => { - fetchMock = vi.fn(); - vi.stubGlobal('fetch', fetchMock); - }); - - afterEach(() => { - vi.unstubAllGlobals(); - }); - - it("POSTs the form-encoded refresh grant to wrangler's client", async () => { - fetchMock.mockResolvedValueOnce( - Response.json({ - access_token: 'cf-access-dummy', - refresh_token: 'cf-rotated-dummy', - expires_in: 3600, - }), - ); - - const tokens = await refreshOauthGrant('cf-refresh-dummy'); - - const { url, init } = lastCall(fetchMock); - expect(url).toBe('https://dash.cloudflare.com/oauth2/token'); - expect(init.method).toBe('POST'); - expect(init.headers).toEqual({ 'Content-Type': 'application/x-www-form-urlencoded' }); - const params = new URLSearchParams(init.body as string); - expect(params.get('grant_type')).toBe('refresh_token'); - expect(params.get('client_id')).toBe(CF_EMAIL_OAUTH_CLIENT_ID); - expect(params.get('refresh_token')).toBe('cf-refresh-dummy'); - expect(tokens).toEqual({ - accessToken: 'cf-access-dummy', - refreshToken: 'cf-rotated-dummy', - expiresIn: 3600, - }); - }); - - it('throws OAuthGrantError with the upstream code, never token material', async () => { - fetchMock.mockResolvedValueOnce( - Response.json( - { error: 'invalid_grant', error_description: 'refresh token unknown' }, - { status: 400 }, - ), - ); - - const error = await refreshOauthGrant('cf-refresh-dummy').catch((err: unknown) => err); - expect(error).toBeInstanceOf(OAuthGrantError); - expect((error as OAuthGrantError).code).toBe('invalid_grant'); - expect((error as OAuthGrantError).status).toBe(400); - expect((error as OAuthGrantError).message).not.toContain('cf-refresh-dummy'); - }); - - it('fails loudly when the answer carries no rotated refresh token', async () => { - fetchMock.mockResolvedValueOnce(Response.json({ access_token: 'cf-access-dummy' })); - - const error = await refreshOauthGrant('cf-refresh-dummy').catch((err: unknown) => err); - expect(error).toBeInstanceOf(OAuthGrantError); - expect((error as OAuthGrantError).code).toBe('invalid_response'); - }); - - it('classifies a non-JSON error body as unknown_error with the HTTP status', async () => { - fetchMock.mockResolvedValueOnce(new Response('bad gateway', { status: 502 })); - - const error = await refreshOauthGrant('cf-refresh-dummy').catch((err: unknown) => err); - expect(error).toBeInstanceOf(OAuthGrantError); - expect((error as OAuthGrantError).code).toBe('unknown_error'); - expect((error as OAuthGrantError).status).toBe(502); - }); -}); - -describe('revokeOauthGrant', () => { - let fetchMock: ReturnType; - - beforeEach(() => { - fetchMock = vi.fn(); - vi.stubGlobal('fetch', fetchMock); - }); - - afterEach(() => { - vi.unstubAllGlobals(); - vi.restoreAllMocks(); - }); - - // console.error output must never carry the token — render every logged - // argument (Errors included) before searching for it. - function loggedText(errorSpy: { mock: { calls: Array> } }): string { - return errorSpy.mock.calls - .flat() - .map((arg) => (arg instanceof Error ? `${arg.name}: ${arg.message}` : String(arg))) - .join(' '); - } - - it("POSTs the form-encoded revocation to wrangler's client, with no Authorization header", async () => { - const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); - fetchMock.mockResolvedValueOnce(new Response(null, { status: 200 })); - - await expect(revokeOauthGrant('cf-refresh-dummy')).resolves.toBeUndefined(); - - const { url, init } = lastCall(fetchMock); - expect(url).toBe('https://dash.cloudflare.com/oauth2/revoke'); - expect(init.method).toBe('POST'); - // A public client authenticates with the token itself — no bearer. - expect(init.headers).toEqual({ 'Content-Type': 'application/x-www-form-urlencoded' }); - const params = new URLSearchParams(init.body as string); - expect(params.get('client_id')).toBe(CF_EMAIL_OAUTH_CLIENT_ID); - expect(params.get('token_type_hint')).toBe('refresh_token'); - expect(params.get('token')).toBe('cf-refresh-dummy'); - // A 2xx is silent (RFC 7009: revoked-or-invalid both answer 200). - expect(errorSpy).not.toHaveBeenCalled(); - }); - - it('throws on a non-2xx, logging an error that never carries the token', async () => { - const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); - for (const status of [400, 500]) { - fetchMock.mockResolvedValueOnce(new Response('boom', { status })); - await expect(revokeOauthGrant('cf-refresh-dummy')).rejects.toThrow(`HTTP ${status}`); - } - - expect(errorSpy).toHaveBeenCalledTimes(2); - const logged = loggedText(errorSpy); - expect(logged).toContain('400'); - expect(logged).toContain('500'); - expect(logged).not.toContain('cf-refresh-dummy'); - }); - - it('rethrows a network rejection, logging an error that never carries the token', async () => { - const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); - fetchMock.mockRejectedValueOnce(new TypeError('fetch failed')); - - await expect(revokeOauthGrant('cf-refresh-dummy')).rejects.toThrow('fetch failed'); - - expect(errorSpy).toHaveBeenCalledTimes(1); - expect(loggedText(errorSpy)).not.toContain('cf-refresh-dummy'); - }); -}); diff --git a/platform/packages/api/test/unit/email-domains.test.ts b/platform/packages/api/test/unit/email-domains.test.ts deleted file mode 100644 index 95303fe5d..000000000 --- a/platform/packages/api/test/unit/email-domains.test.ts +++ /dev/null @@ -1,225 +0,0 @@ -import { describe, expect, it } from 'vite-plus/test'; -import { - clearEmailDomainMirror, - decryptEmailDomainRelaySecret, - decryptEmailDomainToken, - encryptEmailDomainRelaySecret, - encryptEmailDomainToken, - generateEmailRelaySecret, - hashEmailRelaySecret, - writeEmailDomainMirror, -} from '../../src/email/domains.ts'; - -// 32-byte AES-GCM key, same shape as the integration helpers' key config. -const keyBytes = new Uint8Array(32).fill(7); -let keyBinary = ''; -for (const byte of keyBytes) { - keyBinary += String.fromCharCode(byte); -} -const env = { - PROJECT_SECRET_ACTIVE_KEY_VERSION: '1', - PROJECT_SECRET_KEYS_JSON: JSON.stringify({ '1': btoa(keyBinary) }), -}; - -function createKv(): { store: Map; kv: KVNamespace } { - const store = new Map(); - const kv = { - get: async (key: string) => store.get(key) ?? null, - put: async (key: string, value: string) => { - store.set(key, value); - }, - delete: async (key: string) => { - store.delete(key); - }, - } as unknown as KVNamespace; - return { store, kv }; -} - -describe('email domain credential encryption', () => { - it('round-trips the customer token under its fixed AAD name', async () => { - const encrypted = await encryptEmailDomainToken(env, 'proj_1', 'acme.com', 'token-plaintext'); - const decrypted = await decryptEmailDomainToken(env, 'proj_1', 'acme.com', { - credential_kind: 'api_token', - token_ciphertext: encrypted.ciphertext, - token_iv: encrypted.iv, - token_key_version: encrypted.keyVersion, - }); - expect(decrypted).toBe('token-plaintext'); - }); - - it('round-trips the relay secret under its fixed AAD name', async () => { - const encrypted = await encryptEmailDomainRelaySecret( - env, - 'proj_1', - 'acme.com', - 'relay-secret', - ); - const decrypted = await decryptEmailDomainRelaySecret(env, 'proj_1', 'acme.com', { - relay_ciphertext: encrypted.ciphertext, - relay_iv: encrypted.iv, - relay_key_version: encrypted.keyVersion, - }); - expect(decrypted).toBe('relay-secret'); - }); - - it('refuses to decrypt token ciphertext under the relay AAD name', async () => { - // The two AAD names are distinct per row, so the token and relay - // ciphertexts are not interchangeable even within one domain. - const encrypted = await encryptEmailDomainToken(env, 'proj_1', 'acme.com', 'token-plaintext'); - await expect( - decryptEmailDomainRelaySecret(env, 'proj_1', 'acme.com', { - relay_ciphertext: encrypted.ciphertext, - relay_iv: encrypted.iv, - relay_key_version: encrypted.keyVersion, - }), - ).rejects.toThrow('Failed to decrypt project secret'); - }); - - it('binds the ciphertext to the project and the domain', async () => { - const encrypted = await encryptEmailDomainToken(env, 'proj_1', 'acme.com', 'token-plaintext'); - const row = { - credential_kind: 'api_token' as const, - token_ciphertext: encrypted.ciphertext, - token_iv: encrypted.iv, - token_key_version: encrypted.keyVersion, - }; - await expect(decryptEmailDomainToken(env, 'proj_2', 'acme.com', row)).rejects.toThrow( - 'Failed to decrypt project secret', - ); - await expect(decryptEmailDomainToken(env, 'proj_1', 'other.com', row)).rejects.toThrow( - 'Failed to decrypt project secret', - ); - }); - - it("resolves a platform row to the runtime token without touching the row's triple", async () => { - const row = { - credential_kind: 'platform' as const, - token_ciphertext: null, - token_iv: null, - token_key_version: null, - }; - await expect( - decryptEmailDomainToken({ ...env, CF_API_TOKEN: 'runtime-token' }, 'proj_1', 'acme.com', row), - ).resolves.toBe('runtime-token'); - await expect(decryptEmailDomainToken(env, 'proj_1', 'acme.com', row)).rejects.toThrow( - 'CF_API_TOKEN is not configured', - ); - }); - - it('refuses a stored-credential row whose triple is missing', async () => { - await expect( - decryptEmailDomainToken(env, 'proj_1', 'acme.com', { - credential_kind: 'api_token', - token_ciphertext: null, - token_iv: null, - token_key_version: null, - }), - ).rejects.toThrow('missing its stored credential'); - }); -}); - -describe('generateEmailRelaySecret', () => { - it('returns 32 random bytes as unpadded base64url', () => { - const secret = generateEmailRelaySecret(); - expect(secret).toMatch(/^[A-Za-z0-9_-]{43}$/); - }); - - it('generates a fresh secret per call', () => { - expect(generateEmailRelaySecret()).not.toBe(generateEmailRelaySecret()); - }); -}); - -describe('hashEmailRelaySecret', () => { - it('is sha256 as lowercase hex (NIST vector)', async () => { - await expect(hashEmailRelaySecret('abc')).resolves.toBe( - 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad', - ); - }); - - it('produces 64 lowercase hex chars for a generated secret', async () => { - const hex = await hashEmailRelaySecret(generateEmailRelaySecret()); - expect(hex).toMatch(/^[0-9a-f]{64}$/); - }); -}); - -describe('email domain ROUTING KV mirror', () => { - it('writes the wire payload to email-domain:', async () => { - const { store, kv } = createKv(); - const relaySecretSha256 = await hashEmailRelaySecret('relay-secret'); - await writeEmailDomainMirror( - kv, - { - domain: 'acme.com', - project_id: 'proj_1', - status: 'active', - relay_worker_name: 'void-email-relay', - account_id: 'acc_1', - zone_id: 'zone_1', - mode: 'apex', - }, - relaySecretSha256, - ); - - const raw = store.get('email-domain:acme.com'); - expect(raw).toBeDefined(); - expect(JSON.parse(raw!)).toEqual({ - projectId: 'proj_1', - status: 'active', - relaySecretSha256, - relayWorkerName: 'void-email-relay', - accountId: 'acc_1', - zoneId: 'zone_1', - mode: 'apex', - }); - }); - - it('mirrors only the sha256 — never the secret or the token', async () => { - const { store, kv } = createKv(); - const relaySecret = generateEmailRelaySecret(); - await writeEmailDomainMirror( - kv, - { - domain: 'acme.com', - project_id: 'proj_1', - status: 'pending', - relay_worker_name: null, - account_id: null, - zone_id: null, - mode: 'subdomain', - }, - await hashEmailRelaySecret(relaySecret), - ); - - const raw = store.get('email-domain:acme.com')!; - expect(raw).not.toContain(relaySecret); - // Pending rows mirror explicit nulls; the proxy gates on `status` alone. - expect(JSON.parse(raw)).toEqual({ - projectId: 'proj_1', - status: 'pending', - relaySecretSha256: await hashEmailRelaySecret(relaySecret), - relayWorkerName: null, - accountId: null, - zoneId: null, - mode: 'subdomain', - }); - }); - - it('clears the key on delete', async () => { - const { store, kv } = createKv(); - await writeEmailDomainMirror( - kv, - { - domain: 'acme.com', - project_id: 'proj_1', - status: 'active', - relay_worker_name: 'void-email-relay', - account_id: 'acc_1', - zone_id: 'zone_1', - mode: 'apex', - }, - await hashEmailRelaySecret('relay-secret'), - ); - await clearEmailDomainMirror(kv, 'acme.com'); - expect(store.has('email-domain:acme.com')).toBe(false); - }); -}); diff --git a/platform/packages/api/test/unit/email-relay-engine.test.ts b/platform/packages/api/test/unit/email-relay-engine.test.ts deleted file mode 100644 index 15a1f6baf..000000000 --- a/platform/packages/api/test/unit/email-relay-engine.test.ts +++ /dev/null @@ -1,1559 +0,0 @@ -import { describe, it, expect, vi } from 'vite-plus/test'; -import { OAuthGrantError } from '../../src/email/cf-customer.ts'; -import type { - CfCatchAllRule, - CfCustomerClient, - CfSendingSubdomain, -} from '../../src/email/cf-customer.ts'; -import { - RELAY_WORKER_BASE_NAME, - removeEmailDomain, - setupEmailDomain, - syncEmailDomain, -} from '../../src/email/relay-engine.ts'; -import type { RelayEngineDeps } from '../../src/email/relay-engine.ts'; -import { - RELAY_COMPATIBILITY_DATE, - RELAY_SOURCE, - RELAY_VERSION, -} from '../../src/email/relay-worker.ts'; -import { CloudflareApiError } from '../../src/provisioning/cloudflare-api.ts'; - -// Dummy stand-ins — never real token/secret material. -const CREDENTIAL = 'cf-credential-dummy'; -const RELAY_SECRET = 'relay-secret-dummy'; -const PROXY_ORIGIN = 'https://proxy.example.test'; - -type ZoneFixture = { id: string; name: string; accountId: string }; - -type FakeClientConfig = Readonly<{ - zones?: Record; - verifyStatus?: string; - scriptNamesTaken?: ReadonlyArray; - /** The zone's current catch-all rule; absent/null → 404 (no rule). */ - catchAll?: CfCatchAllRule | null; - /** GET email/routing's raw result; default { enabled: true }. */ - routingSettings?: unknown; - /** The sending-subdomain list; default []. */ - sendingSubdomains?: ReadonlyArray; - failOn?: Partial>; -}>; - -type RecordedCall = { method: string; args: ReadonlyArray }; - -function makeFakeClient(config: FakeClientConfig = {}): { - client: CfCustomerClient; - calls: Array; -} { - const calls: Array = []; - const maybeThrow = (method: string) => { - const error = config.failOn?.[method]; - if (error) { - throw error; - } - }; - const record = - (method: string) => - (...args: ReadonlyArray) => { - calls.push({ method, args }); - maybeThrow(method); - }; - const client: CfCustomerClient = { - verifyToken: async () => { - record('verifyToken')(); - return { id: 'tok_1', status: config.verifyStatus ?? 'active', expires_on: null }; - }, - findZone: async (name: string) => { - record('findZone')(name); - const zone = config.zones?.[name]; - return zone ? { id: zone.id, name: zone.name, account: { id: zone.accountId } } : null; - }, - enableRouting: async (zoneId: string, name?: string) => record('enableRouting')(zoneId, name), - onboardSending: async (zoneId: string, name: string) => record('onboardSending')(zoneId, name), - listSendingSubdomains: async (zoneId: string) => { - record('listSendingSubdomains')(zoneId); - return config.sendingSubdomains ?? []; - }, - listRoutingRules: async (zoneId: string) => { - record('listRoutingRules')(zoneId); - return []; - }, - relayScriptExists: async (accountId: string, scriptName: string) => { - record('relayScriptExists')(accountId, scriptName); - return config.scriptNamesTaken?.includes(scriptName) ?? false; - }, - putRelayScript: async (accountId: string, scriptName: string, upload: unknown) => - record('putRelayScript')(accountId, scriptName, upload), - putRelaySecret: async (accountId: string, scriptName: string, secret: string) => - record('putRelaySecret')(accountId, scriptName, secret), - getWorkersSubdomain: async (accountId: string) => { - record('getWorkersSubdomain')(accountId); - return 'example'; - }, - getScriptSubdomainEnabled: async (accountId: string, scriptName: string) => { - record('getScriptSubdomainEnabled')(accountId, scriptName); - return true; - }, - enableScriptSubdomain: async (accountId: string, scriptName: string) => - record('enableScriptSubdomain')(accountId, scriptName), - setCatchAll: async (zoneId: string, relayWorkerName: string) => - record('setCatchAll')(zoneId, relayWorkerName), - getCatchAll: async (zoneId: string) => { - record('getCatchAll')(zoneId); - return config.catchAll ?? null; - }, - getRoutingSettings: async (zoneId: string) => { - record('getRoutingSettings')(zoneId); - return config.routingSettings ?? { enabled: true }; - }, - resetCatchAll: async (zoneId: string) => record('resetCatchAll')(zoneId), - deleteRelayScript: async (accountId: string, scriptName: string) => - record('deleteRelayScript')(accountId, scriptName), - sendRaw: async () => { - throw new Error('sendRaw is the proxy-side send path — the engine never calls it'); - }, - }; - return { client, calls }; -} - -function methods(calls: Array): Array { - return calls.map((call) => call.method); -} - -function depsFor( - client: CfCustomerClient, - extra?: Partial & { seenCredentials?: Array }, -): RelayEngineDeps { - return { - createClient: (credential: string) => { - extra?.seenCredentials?.push(credential); - return client; - }, - lookupMx: async () => [], - // The name-walk's DB reservation — required whenever the row carries - // no relay name. Tests that exercise 'taken' pass their own. - claimRelayName: async () => 'claimed', - ...extra, - }; -} - -const ZONE: ZoneFixture = { id: 'zone_1', name: 'acme.com', accountId: 'acct_1' }; - -function setupInput(domain = 'acme.com') { - return { - row: { domain, credential_kind: 'api_token' as const }, - credential: CREDENTIAL, - relaySecret: RELAY_SECRET, - proxyOrigin: PROXY_ORIGIN, - }; -} - -describe('setupEmailDomain', () => { - it('runs the contract-7 step order for an apex domain and returns the active row fields', async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result).toEqual({ - status: 'active', - zone_id: 'zone_1', - account_id: 'acct_1', - mode: 'apex', - relay_worker_name: RELAY_WORKER_BASE_NAME, - relay_version: RELAY_VERSION, - token_id: 'tok_1', - token_expires_on: null, - setup_state: null, - }); - expect(methods(calls)).toEqual([ - 'verifyToken', - 'findZone', - 'enableRouting', - 'onboardSending', - 'relayScriptExists', - 'putRelayScript', - 'putRelaySecret', - 'getCatchAll', - 'setCatchAll', - ]); - // Apex enable: empty body (no name argument). - expect(calls[2].args).toEqual(['zone_1', undefined]); - expect(calls[5].args).toEqual([ - 'acct_1', - RELAY_WORKER_BASE_NAME, - { - source: RELAY_SOURCE, - compatibilityDate: RELAY_COMPATIBILITY_DATE, - proxyOrigin: PROXY_ORIGIN, - emailDomain: 'acme.com', - }, - ]); - expect(calls[6].args).toEqual(['acct_1', RELAY_WORKER_BASE_NAME, RELAY_SECRET]); - // The ownership read precedes the write. - expect(calls[7].args).toEqual(['zone_1']); - expect(calls[8].args).toEqual(['zone_1', RELAY_WORKER_BASE_NAME]); - }); - - it("runs a platform row on the runtime token with no user-token verify, pinned to the platform's account", async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - const seenCredentials: Array = []; - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { domain: 'acme.com', credential_kind: 'platform' }, - credential: 'runtime-token-dummy', - requireAccountId: 'acct_1', - }, - depsFor(client, { seenCredentials }), - ); - - expect(result.status).toBe('active'); - expect(result.token_id).toBeNull(); - expect(result.token_expires_on).toBeNull(); - expect(seenCredentials).toEqual(['runtime-token-dummy']); - expect(methods(calls)[0]).toBe('findZone'); - expect(methods(calls)).not.toContain('verifyToken'); - }); - - it('fails at zone_lookup, before any write, when the zone is outside the required account', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': { ...ZONE, accountId: 'acct_customer' } }, - }); - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { domain: 'acme.com', credential_kind: 'platform' }, - requireAccountId: 'acct_platform', - }, - depsFor(client), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'zone_lookup' }); - expect(result.error).toContain('acct_customer'); - expect(result.error).toContain('acct_platform'); - expect(result.error).toContain('--token-stdin'); - expect(result.zone_id).toBeNull(); - expect(result.account_id).toBeNull(); - expect(methods(calls)).toEqual(['findZone']); - }); - - it('leaves an unpinned row free to register a zone in any account', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': { ...ZONE, accountId: 'acct_customer' } }, - }); - const result = await setupEmailDomain(setupInput(), depsFor(client)); - expect(result.status).toBe('active'); - expect(result.account_id).toBe('acct_customer'); - }); - - it('walks the labels up to the registrable zone and takes the subdomain path', async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain(setupInput('mail.acme.com'), depsFor(client)); - - expect(result.status).toBe('active'); - expect(result.mode).toBe('subdomain'); - expect(calls.filter((c) => c.method === 'findZone').map((c) => c.args[0])).toEqual([ - 'mail.acme.com', - 'acme.com', - ]); - // Subdomain enable: POST routing/dns with { name }. - expect(calls.find((c) => c.method === 'enableRouting')?.args).toEqual([ - 'zone_1', - 'mail.acme.com', - ]); - }); - - it('fails at verify_credential when the token is not active', async () => { - const { client, calls } = makeFakeClient({ verifyStatus: 'disabled' }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('token_revoked'); - expect(result.setup_state).toEqual({ failed_step: 'verify_credential' }); - expect(methods(calls)).toEqual(['verifyToken']); - }); - - it('maps an expired token to token_expired', async () => { - const { client } = makeFakeClient({ verifyStatus: 'expired' }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('token_expired'); - expect(result.setup_state).toEqual({ failed_step: 'verify_credential' }); - }); - - it('fails at zone_lookup when no suffix of the domain is a visible zone', async () => { - const { client, calls } = makeFakeClient({ zones: {} }); - - const result = await setupEmailDomain(setupInput('mail.acme.com'), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'zone_lookup' }); - expect(result.error).toContain('mail.acme.com'); - expect(calls.filter((c) => c.method === 'findZone').map((c) => c.args[0])).toEqual([ - 'mail.acme.com', - 'acme.com', - ]); - expect(methods(calls)).not.toContain('enableRouting'); - }); - - it('fails at mx_check when the domain already carries MX, naming the exchanges', async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain(setupInput(), { - ...depsFor(client), - lookupMx: async () => ['aspmx.l.google.com'], - }); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'mx_check' }); - expect(result.error).toContain('aspmx.l.google.com'); - expect(result.error).toContain('mail.acme.com'); - // Partial progress is still returned for the row. - expect(result.zone_id).toBe('zone_1'); - expect(result.account_id).toBe('acct_1'); - expect(methods(calls)).not.toContain('enableRouting'); - }); - - it('fails hard when the apex routing POST fails', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { enableRouting: new CloudflareApiError('Cloudflare API error: forbidden', 403) }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'enable_routing' }); - expect(result.error).toContain('forbidden'); - expect(methods(calls)).not.toContain('onboardSending'); - }); - - it('records the human dashboard step when the subdomain routing POST fails, and finishes the rest', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { enableRouting: new CloudflareApiError('Cloudflare API error: forbidden', 403) }, - }); - - const result = await setupEmailDomain(setupInput('mail.acme.com'), depsFor(client)); - - expect(result.status).toBe('pending'); - expect(result.setup_state).toEqual({ remaining_steps: ['routing_subdomain'] }); - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - // Everything after the refused POST still ran. - expect(methods(calls)).toEqual([ - 'verifyToken', - 'findZone', - 'findZone', - 'enableRouting', - 'onboardSending', - 'relayScriptExists', - 'putRelayScript', - 'putRelaySecret', - 'getCatchAll', - 'setCatchAll', - ]); - }); - - it('keeps the recorded human step on setup_state when a later step fails', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { - enableRouting: new CloudflareApiError('Cloudflare API error: forbidden', 403), - onboardSending: new CloudflareApiError('Cloudflare API error: no sending scope', 403), - }, - }); - - const result = await setupEmailDomain(setupInput('mail.acme.com'), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ - failed_step: 'onboard_sending', - remaining_steps: ['routing_subdomain'], - }); - }); - - it('continues past a Workers Free sending-onboarding refusal — inbound deploys, the step is recorded', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { - onboardSending: new CloudflareApiError( - 'Cloudflare API error: account is not entitled to Email Sending', - 403, - [10105], - ), - }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - // Email Routing needs no paid plan, so the relay and catch-all still - // deploy and the row goes ACTIVE — only the outbound lane stays - // refused at CF until a plan upgrade. - expect(result.status).toBe('active'); - expect(result.setup_state).toEqual({ remaining_steps: ['sending_onboarding'] }); - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(methods(calls)).toEqual([ - 'verifyToken', - 'findZone', - 'enableRouting', - 'onboardSending', - 'relayScriptExists', - 'putRelayScript', - 'putRelaySecret', - 'getCatchAll', - 'setCatchAll', - ]); - }); - - it('holds the row pending when a Free-plan refusal combines with the routing-subdomain step', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { - enableRouting: new CloudflareApiError('Cloudflare API error: forbidden', 403), - onboardSending: new CloudflareApiError( - 'Cloudflare API error: account is not entitled to Email Sending', - 400, - [2036], - ), - }, - }); - - const result = await setupEmailDomain(setupInput('mail.acme.com'), depsFor(client)); - - // routing_subdomain is inbound-blocking; sending_onboarding is not. - expect(result.status).toBe('pending'); - expect(result.setup_state).toEqual({ - remaining_steps: ['routing_subdomain', 'sending_onboarding'], - }); - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - }); - - it('fails at deploy_relay when the secret PUT fails, after the script upload succeeded — and records the relay name', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { putRelaySecret: new CloudflareApiError('Cloudflare API error: quota', 400) }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - // The upload already happened, so the chosen name is recorded even on - // the failure: a retry redeploys in place instead of leaking this - // worker and walking to '-2', and a remove can find it. - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(result.relay_version).toBeNull(); - }); - - it('fails at deploy_relay with no relay name when every name is taken', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - scriptNamesTaken: Array.from({ length: 50 }, (_, i) => - i === 0 ? RELAY_WORKER_BASE_NAME : `${RELAY_WORKER_BASE_NAME}-${i + 1}`, - ), - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - // Nothing was uploaded, so there is no name to record. - expect(result.relay_worker_name).toBeNull(); - expect(result.relay_version).toBeNull(); - }); - - it('fails at catch_all when the catch-all PUT fails', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { setCatchAll: new CloudflareApiError('Cloudflare API error: rules quota', 400) }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'catch_all' }); - // The relay did get deployed — the row keeps its name for repair. - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - }); - - it('suffixes the relay name on collision within the account', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - scriptNamesTaken: [RELAY_WORKER_BASE_NAME, `${RELAY_WORKER_BASE_NAME}-2`], - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('active'); - expect(result.relay_worker_name).toBe(`${RELAY_WORKER_BASE_NAME}-3`); - expect(calls.filter((c) => c.method === 'relayScriptExists').map((c) => c.args[1])).toEqual([ - RELAY_WORKER_BASE_NAME, - `${RELAY_WORKER_BASE_NAME}-2`, - `${RELAY_WORKER_BASE_NAME}-3`, - ]); - expect(calls.find((c) => c.method === 'setCatchAll')?.args).toEqual([ - 'zone_1', - `${RELAY_WORKER_BASE_NAME}-3`, - ]); - }); - - it('walks past a CF-free name the claim reports taken, and never uploads to it', async () => { - // CF shows only the base name physically present; another ROW holds - // '-2' in the db — the claim is what skips it, not the CF probe. - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - scriptNamesTaken: [RELAY_WORKER_BASE_NAME], - }); - const claimed: Array = []; - - const result = await setupEmailDomain( - setupInput(), - depsFor(client, { - claimRelayName: async (_accountId, candidate) => { - claimed.push(candidate); - return candidate === `${RELAY_WORKER_BASE_NAME}-2` ? 'taken' : 'claimed'; - }, - }), - ); - - expect(result.status).toBe('active'); - expect(result.relay_worker_name).toBe(`${RELAY_WORKER_BASE_NAME}-3`); - // The base name was CF-taken, so its claim was never spent. - expect(claimed).toEqual([`${RELAY_WORKER_BASE_NAME}-2`, `${RELAY_WORKER_BASE_NAME}-3`]); - // The contested name was never written. - for (const method of ['putRelayScript', 'putRelaySecret'] as const) { - expect(calls.filter((c) => c.method === method).map((c) => c.args[1])).toEqual([ - `${RELAY_WORKER_BASE_NAME}-3`, - ]); - } - }); - - it('fails at deploy_relay when every CF-free name is claim-taken', async () => { - const { client } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain( - setupInput(), - depsFor(client, { claimRelayName: async () => 'taken' }), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - // Nothing was uploaded, so there is no name to record. - expect(result.relay_worker_name).toBeNull(); - }); - - it('fails at deploy_relay when the walk runs without the claimRelayName dep', async () => { - // The dep is REQUIRED on the walk: a CF-only probe would silently - // re-open the last-write-wins relay race, so the walk refuses loudly. - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain(setupInput(), { - ...depsFor(client), - claimRelayName: undefined, - }); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - expect(result.error).toContain('claimRelayName'); - // The refusal precedes even the CF probe — nothing was walked or written. - expect(methods(calls)).not.toContain('relayScriptExists'); - expect(methods(calls)).not.toContain('putRelayScript'); - }); - - it('verifies an oauth_grant with one refresh round-trip and returns the rotated refresh token', async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - const seenCredentials: Array = []; - const refreshed: Array = []; - - const result = await setupEmailDomain( - { ...setupInput(), row: { domain: 'acme.com', credential_kind: 'oauth_grant' } }, - depsFor(client, { - seenCredentials, - refreshGrant: async (refreshToken: string) => { - refreshed.push(refreshToken); - return { accessToken: 'cf-access-dummy', refreshToken: 'cf-rotated-dummy' }; - }, - }), - ); - - expect(result.status).toBe('active'); - expect(result.rotated_refresh_token).toBe('cf-rotated-dummy'); - // The grant path has no /user/tokens/verify — token_id stays null. - expect(result.token_id).toBeNull(); - expect(methods(calls)).not.toContain('verifyToken'); - // Every customer call rode the fresh access token, never the refresh token. - expect(seenCredentials).toEqual(['cf-access-dummy']); - expect(refreshed).toEqual([CREDENTIAL]); - }); - - it('maps invalid_grant to token_revoked and still runs no customer calls', async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain( - { ...setupInput(), row: { domain: 'acme.com', credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => { - throw new OAuthGrantError('invalid_grant', 400); - }, - }), - ); - - expect(result.status).toBe('token_revoked'); - expect(result.setup_state).toEqual({ failed_step: 'verify_credential' }); - expect(calls).toEqual([]); - }); - - it('maps a transient OAuth failure to failed, not token_revoked', async () => { - const { client } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - const result = await setupEmailDomain( - { ...setupInput(), row: { domain: 'acme.com', credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => { - throw new OAuthGrantError('temporarily_unavailable', 503); - }, - }), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'verify_credential' }); - }); - - it('returns the rotated refresh token even when a later step fails', async () => { - // Single-use rotation: dropping the rotated value would kill the chain. - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { setCatchAll: new CloudflareApiError('Cloudflare API error: quota', 400) }, - }); - - const result = await setupEmailDomain( - { ...setupInput(), row: { domain: 'acme.com', credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => ({ - accessToken: 'cf-access-dummy', - refreshToken: 'cf-rotated-dummy', - }), - }), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'catch_all' }); - expect(result.rotated_refresh_token).toBe('cf-rotated-dummy'); - }); - - it('fails at catch_all when the zone catch-all already routes to another worker', async () => { - // The catch-all is zone-scoped with no domain parameter: overwriting - // it would hijack the other worker's (possibly another Void domain's) - // inbound. - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - catchAll: { enabled: true, workerName: 'someone-elses-worker' }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'catch_all' }); - expect(result.error).toContain('someone-elses-worker'); - // The relay still deployed — the row keeps its name for repair — but - // the conflicting rule was never overwritten. - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('fails at catch_all when the zone catch-all is enabled with a non-worker action', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - catchAll: { enabled: true, workerName: null }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'catch_all' }); - expect(result.error).toContain('non-worker'); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('overwrites a disabled catch-all, whatever it names', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - catchAll: { enabled: false, workerName: 'someone-elses-worker' }, - }); - - const result = await setupEmailDomain(setupInput(), depsFor(client)); - - expect(result.status).toBe('active'); - expect(calls.find((c) => c.method === 'setCatchAll')?.args).toEqual([ - 'zone_1', - RELAY_WORKER_BASE_NAME, - ]); - }); - - it('re-runs against recorded progress: no MX check, in-place relay, already-done 4xx believed on read-back', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - routingSettings: { enabled: true, status: 'ready' }, - sendingSubdomains: [{ name: 'acme.com', enabled: true }], - failOn: { - enableRouting: new CloudflareApiError('Cloudflare API error: already enabled', 400), - onboardSending: new CloudflareApiError('Cloudflare API error: already exists', 409), - }, - }); - const lookupMx = vi.fn(async (): Promise> => { - throw new Error('the MX check must be skipped on a re-run — our own MX is there now'); - }); - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { - domain: 'acme.com', - credential_kind: 'api_token', - mode: 'apex', - relay_worker_name: RELAY_WORKER_BASE_NAME, - }, - }, - depsFor(client, { lookupMx }), - ); - - expect(result.status).toBe('active'); - expect(lookupMx).not.toHaveBeenCalled(); - // In-place redeploy: no name-walk, the recorded name is reused. - expect(methods(calls)).not.toContain('relayScriptExists'); - expect(calls.find((c) => c.method === 'putRelayScript')?.args[1]).toBe(RELAY_WORKER_BASE_NAME); - // Both 4xx were tolerated only after their read-backs confirmed. - expect(methods(calls)).toContain('getRoutingSettings'); - expect(methods(calls)).toContain('listSendingSubdomains'); - expect(methods(calls)).toContain('setCatchAll'); - }); - - it('fails at enable_routing when a 400 is not confirmed by the settings read-back', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - routingSettings: { enabled: false, status: 'unconfigured' }, - failOn: { - enableRouting: new CloudflareApiError('Cloudflare API error: bad request', 400), - }, - }); - - const result = await setupEmailDomain( - { ...setupInput(), row: { domain: 'acme.com', credential_kind: 'api_token', mode: 'apex' } }, - depsFor(client), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'enable_routing' }); - expect(result.error).toContain('bad request'); - }); - - it('fails at onboard_sending when a 409 is not confirmed by the subdomain read-back', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { - onboardSending: new CloudflareApiError('Cloudflare API error: conflict', 409), - }, - }); - - const result = await setupEmailDomain( - { ...setupInput(), row: { domain: 'acme.com', credential_kind: 'api_token', mode: 'apex' } }, - depsFor(client), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'onboard_sending' }); - expect(result.error).toContain('conflict'); - }); - - it('skips the catch-all write on a re-run whose rule already names the relay', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { - domain: 'acme.com', - credential_kind: 'api_token', - mode: 'apex', - relay_worker_name: RELAY_WORKER_BASE_NAME, - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(methods(calls)).toContain('getCatchAll'); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('a re-run that fails at verify_credential still returns the recorded progress', async () => { - const { client, calls } = makeFakeClient({ verifyStatus: 'disabled' }); - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { - domain: 'acme.com', - credential_kind: 'api_token', - mode: 'apex', - relay_worker_name: RELAY_WORKER_BASE_NAME, - zone_id: 'zone_1', - account_id: 'acct_1', - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('token_revoked'); - expect(result.setup_state).toEqual({ failed_step: 'verify_credential' }); - // The early failure must not erase what the row already learned. - expect(result.zone_id).toBe('zone_1'); - expect(result.account_id).toBe('acct_1'); - expect(result.mode).toBe('apex'); - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(methods(calls)).toEqual(['verifyToken']); - }); - - it('a re-run that fails at deploy_relay still returns the recorded relay name', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { putRelayScript: new CloudflareApiError('Cloudflare API error: 503', 503) }, - }); - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { - domain: 'acme.com', - credential_kind: 'api_token', - mode: 'apex', - relay_worker_name: RELAY_WORKER_BASE_NAME, - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - // The recorded name survives the failed in-place redeploy, along with - // the zone/account the lookup re-learned. - expect(result.relay_worker_name).toBe(RELAY_WORKER_BASE_NAME); - expect(result.zone_id).toBe('zone_1'); - expect(result.account_id).toBe('acct_1'); - // In-place redeploy: no name-walk. - expect(methods(calls)).not.toContain('relayScriptExists'); - expect(calls.find((c) => c.method === 'putRelayScript')?.args[1]).toBe(RELAY_WORKER_BASE_NAME); - }); - - it('checkpoints the learned progress once, after the secret PUT and before the catch-all read', async () => { - const { client, calls } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - scriptNamesTaken: [RELAY_WORKER_BASE_NAME], - }); - const persisted: Array = []; - - const result = await setupEmailDomain( - setupInput(), - depsFor(client, { - persistProgress: async (progress) => { - // Fires after the relay deploy + secret PUT, before the catch-all. - expect(methods(calls)).toEqual([ - 'verifyToken', - 'findZone', - 'enableRouting', - 'onboardSending', - 'relayScriptExists', - 'relayScriptExists', - 'putRelayScript', - 'putRelaySecret', - ]); - persisted.push(progress); - }, - }), - ); - - expect(result.status).toBe('active'); - // The walked name and the learned zone/account/mode. - expect(persisted).toEqual([ - { - zone_id: 'zone_1', - account_id: 'acct_1', - mode: 'apex', - relay_worker_name: `${RELAY_WORKER_BASE_NAME}-2`, - }, - ]); - // The catch-all read/write followed the checkpoint. - expect(methods(calls).slice(-2)).toEqual(['getCatchAll', 'setCatchAll']); - }); - - it('skips the checkpoint on an in-place redeploy — the row already knows', async () => { - const { client } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - const persistProgress = vi.fn(async () => {}); - - const result = await setupEmailDomain( - { - ...setupInput(), - row: { - domain: 'acme.com', - credential_kind: 'api_token', - mode: 'apex', - relay_worker_name: RELAY_WORKER_BASE_NAME, - }, - }, - depsFor(client, { persistProgress }), - ); - - expect(result.status).toBe('active'); - expect(persistProgress).not.toHaveBeenCalled(); - }); - - it('propagates a persistProgress throw and never touches the catch-all', async () => { - const { client, calls } = makeFakeClient({ zones: { 'acme.com': ZONE } }); - - await expect( - setupEmailDomain( - setupInput(), - depsFor(client, { - persistProgress: async () => { - throw new Error('db write failed'); - }, - }), - ), - ).rejects.toThrow('db write failed'); - - // The deploy succeeded, but no catch-all call happened after the throw. - expect(methods(calls)).toContain('putRelaySecret'); - expect(methods(calls)).not.toContain('getCatchAll'); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('never fires the checkpoint when the deploy itself fails', async () => { - const { client } = makeFakeClient({ - zones: { 'acme.com': ZONE }, - failOn: { putRelaySecret: new CloudflareApiError('Cloudflare API error: quota', 400) }, - }); - const persistProgress = vi.fn(async () => {}); - - const result = await setupEmailDomain(setupInput(), depsFor(client, { persistProgress })); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - expect(persistProgress).not.toHaveBeenCalled(); - }); -}); - -describe('syncEmailDomain', () => { - const syncInput = { - row: { - domain: 'acme.com', - credential_kind: 'api_token' as const, - account_id: 'acct_1', - relay_worker_name: RELAY_WORKER_BASE_NAME, - }, - credential: CREDENTIAL, - proxyOrigin: PROXY_ORIGIN, - }; - - it('redeploys in place at RELAY_VERSION and rotates the secret — no zone, MX, or rule calls', async () => { - const { client, calls } = makeFakeClient(); - - const result = await syncEmailDomain(syncInput, { - ...depsFor(client), - generateRelaySecret: () => 'relay-secret-rotated-dummy', - }); - - expect(result).toEqual({ - status: 'active', - relay_version: RELAY_VERSION, - setup_state: null, - new_relay_secret: 'relay-secret-rotated-dummy', - }); - expect(methods(calls)).toEqual(['verifyToken', 'putRelayScript', 'putRelaySecret']); - expect(calls[1].args[1]).toBe(RELAY_WORKER_BASE_NAME); - expect(calls[2].args).toEqual(['acct_1', RELAY_WORKER_BASE_NAME, 'relay-secret-rotated-dummy']); - }); - - it('fails without CF calls when the relay was never deployed', async () => { - const { client, calls } = makeFakeClient(); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, relay_worker_name: null } }, - depsFor(client), - ); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - expect(calls).toEqual([]); - }); - - it('fails at deploy_relay when the redeploy fails, without returning a new secret', async () => { - const { client } = makeFakeClient({ - failOn: { putRelayScript: new CloudflareApiError('Cloudflare API error: 503', 503) }, - }); - - const result = await syncEmailDomain(syncInput, depsFor(client)); - - expect(result.status).toBe('failed'); - expect(result.setup_state).toEqual({ failed_step: 'deploy_relay' }); - expect(result.new_relay_secret).toBeUndefined(); - }); - - it('ensures a missing catch-all after the redeploy, reporting ensured', async () => { - const { client, calls } = makeFakeClient(); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, zone_id: 'zone_1' } }, - { ...depsFor(client), generateRelaySecret: () => 'relay-secret-rotated-dummy' }, - ); - - expect(result).toEqual({ - status: 'active', - relay_version: RELAY_VERSION, - setup_state: null, - catch_all: 'ensured', - new_relay_secret: 'relay-secret-rotated-dummy', - }); - // The ensure runs after the redeploy + secret PUT. - expect(methods(calls)).toEqual([ - 'verifyToken', - 'putRelayScript', - 'putRelaySecret', - 'getCatchAll', - 'setCatchAll', - ]); - expect(calls.at(-1)?.args).toEqual(['zone_1', RELAY_WORKER_BASE_NAME]); - }); - - it('re-points a disabled catch-all at the relay', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: false, workerName: 'someone-elses-worker' }, - }); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, zone_id: 'zone_1' } }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.catch_all).toBe('ensured'); - expect(calls.find((c) => c.method === 'setCatchAll')?.args).toEqual([ - 'zone_1', - RELAY_WORKER_BASE_NAME, - ]); - }); - - it('leaves an enabled catch-all already naming the relay untouched', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, zone_id: 'zone_1' } }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.catch_all).toBe('already_set'); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('never overwrites an enabled catch-all naming a different worker — report, do not fight', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: 'someone-elses-worker' }, - }); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, zone_id: 'zone_1' } }, - depsFor(client), - ); - - // The redeploy/rotation still succeeded — only the conflict is reported. - expect(result.status).toBe('active'); - expect(result.catch_all).toBe('foreign_conflict'); - expect(result.new_relay_secret).toBeDefined(); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('reports probe_failed when the ownership read throws, and still succeeds', async () => { - const { client } = makeFakeClient({ - failOn: { getCatchAll: new CloudflareApiError('Cloudflare API error: 500', 500) }, - }); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, zone_id: 'zone_1' } }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.catch_all).toBe('probe_failed'); - expect(result.new_relay_secret).toBeDefined(); - }); - - it('re-attempts a pending sending onboarding after the catch-all ensure, reporting it cleared', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await syncEmailDomain( - { - ...syncInput, - row: { - ...syncInput.row, - zone_id: 'zone_1', - setup_remaining_steps: ['sending_onboarding'], - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.cleared_steps).toEqual(['sending_onboarding']); - // The retry runs after the redeploy, rotation, and catch-all ensure. - expect(methods(calls)).toEqual([ - 'verifyToken', - 'putRelayScript', - 'putRelaySecret', - 'getCatchAll', - 'onboardSending', - ]); - }); - - it('keeps the step when the onboarding retry is refused again, without failing the sync', async () => { - const { client } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { - onboardSending: new CloudflareApiError( - 'Cloudflare API error: account is not entitled to Email Sending', - 403, - [10105], - ), - }, - }); - - const result = await syncEmailDomain( - { - ...syncInput, - row: { - ...syncInput.row, - zone_id: 'zone_1', - setup_remaining_steps: ['sending_onboarding'], - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.catch_all).toBe('already_set'); - expect(result.cleared_steps).toBeUndefined(); - expect(result.new_relay_secret).toBeDefined(); - }); - - it('clears the step on a confirming read-back behind a 409', async () => { - const { client } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - sendingSubdomains: [{ name: 'acme.com', enabled: true }], - failOn: { - onboardSending: new CloudflareApiError('Cloudflare API error: already onboarded', 409), - }, - }); - - const result = await syncEmailDomain( - { - ...syncInput, - row: { - ...syncInput.row, - zone_id: 'zone_1', - setup_remaining_steps: ['sending_onboarding'], - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.cleared_steps).toEqual(['sending_onboarding']); - }); - - it('makes no sending-onboarding call when the row carries no such step', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await syncEmailDomain( - { - ...syncInput, - row: { - ...syncInput.row, - zone_id: 'zone_1', - setup_remaining_steps: ['routing_subdomain'], - }, - }, - depsFor(client), - ); - - expect(result.status).toBe('active'); - expect(result.cleared_steps).toBeUndefined(); - expect(methods(calls)).not.toContain('onboardSending'); - }); - - it('makes no catch-all calls when the row carries no zone_id, and omits the field', async () => { - const { client, calls } = makeFakeClient(); - - const result = await syncEmailDomain( - { ...syncInput, row: { ...syncInput.row, zone_id: null } }, - { ...depsFor(client), generateRelaySecret: () => 'relay-secret-rotated-dummy' }, - ); - - expect(result).toEqual({ - status: 'active', - relay_version: RELAY_VERSION, - setup_state: null, - new_relay_secret: 'relay-secret-rotated-dummy', - }); - expect(methods(calls)).toEqual(['verifyToken', 'putRelayScript', 'putRelaySecret']); - }); -}); - -describe('removeEmailDomain', () => { - const removeInput = { - row: { - credential_kind: 'api_token' as const, - account_id: 'acct_1', - relay_worker_name: RELAY_WORKER_BASE_NAME, - zone_id: 'zone_1', - }, - credential: CREDENTIAL, - }; - - it('resets the catch-all it still owns, then deletes the relay script — best-effort, no verify round-trip', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await removeEmailDomain(removeInput, depsFor(client)); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual(['getCatchAll', 'resetCatchAll', 'deleteRelayScript']); - expect(calls[0].args).toEqual(['zone_1']); - expect(calls[1].args).toEqual(['zone_1']); - expect(calls[2].args).toEqual(['acct_1', RELAY_WORKER_BASE_NAME]); - }); - - it('reports delete_relay when the relay delete fails after the catch-all reset ran', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { deleteRelayScript: new CloudflareApiError('Cloudflare API error: 500', 500) }, - }); - - const result = await removeEmailDomain(removeInput, depsFor(client)); - - expect(result.failed_steps).toEqual(['delete_relay']); - expect(methods(calls)).toEqual(['getCatchAll', 'resetCatchAll', 'deleteRelayScript']); - }); - - it('refreshes an oauth_grant for cleanup and reports both steps failed when the grant is dead', async () => { - const { client, calls } = makeFakeClient(); - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => { - throw new OAuthGrantError('invalid_grant', 400); - }, - }), - ); - - expect(result.failed_steps).toEqual(['delete_relay', 'catch_all']); - expect(calls).toEqual([]); - }); - - it('skips CF calls the row never reached', async () => { - const { client, calls } = makeFakeClient(); - - const result = await removeEmailDomain( - { - ...removeInput, - row: { ...removeInput.row, account_id: null, relay_worker_name: null, zone_id: null }, - }, - depsFor(client), - ); - - expect(result.failed_steps).toEqual([]); - expect(calls).toEqual([]); - }); - - it('leaves a catch-all naming another worker untouched', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: 'someone-elses-worker' }, - }); - - const result = await removeEmailDomain(removeInput, depsFor(client)); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual(['getCatchAll', 'deleteRelayScript']); - }); - - it('leaves a disabled catch-all untouched even when it names our relay', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: false, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await removeEmailDomain(removeInput, depsFor(client)); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual(['getCatchAll', 'deleteRelayScript']); - }); - - it('keeps rule and relay as a pair when the ownership read fails', async () => { - const { client, calls } = makeFakeClient({ - failOn: { getCatchAll: new CloudflareApiError('Cloudflare API error: 500', 500) }, - }); - - const result = await removeEmailDomain(removeInput, depsFor(client)); - - // The delete is never attempted: an enabled catch-all must not be left - // pointing at a deleted worker, so both steps report failed. - expect(result.failed_steps).toEqual(['catch_all', 'delete_relay']); - expect(methods(calls)).toEqual(['getCatchAll']); - }); - - it('keeps the relay when the catch-all reset fails — the enabled rule never points at a deleted worker', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - failOn: { resetCatchAll: new CloudflareApiError('Cloudflare API error: 500', 500) }, - }); - - const result = await removeEmailDomain(removeInput, depsFor(client)); - - expect(result.failed_steps).toEqual(['catch_all', 'delete_relay']); - expect(methods(calls)).toEqual(['getCatchAll', 'resetCatchAll']); - }); - - it('never reads the catch-all when the relay never deployed, even with a known zone', async () => { - const { client, calls } = makeFakeClient(); - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, relay_worker_name: null } }, - depsFor(client), - ); - - expect(result.failed_steps).toEqual([]); - expect(calls).toEqual([]); - }); - - it('repoints an owned catch-all at the winning relay when the target exists, re-checking after the PUT', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - scriptNamesTaken: ['winning-relay'], - }); - - const result = await removeEmailDomain( - { ...removeInput, repoint_catch_all_to: 'winning-relay' }, - depsFor(client), - ); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual([ - 'getCatchAll', - 'relayScriptExists', - 'setCatchAll', - // Post-check: the winner may have been deleted mid-compensation. - 'relayScriptExists', - 'deleteRelayScript', - ]); - expect(calls.filter((c) => c.method === 'relayScriptExists').map((c) => c.args)).toEqual([ - ['acct_1', 'winning-relay'], - ['acct_1', 'winning-relay'], - ]); - expect(calls.find((c) => c.method === 'setCatchAll')?.args).toEqual([ - 'zone_1', - 'winning-relay', - ]); - expect(methods(calls)).not.toContain('resetCatchAll'); - }); - - it('falls back to the reset when the repoint target does not exist', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await removeEmailDomain( - { ...removeInput, repoint_catch_all_to: 'winning-relay' }, - depsFor(client), - ); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual([ - 'getCatchAll', - 'relayScriptExists', - 'resetCatchAll', - 'deleteRelayScript', - ]); - expect(methods(calls)).not.toContain('setCatchAll'); - }); - - it('keeps the rule-and-relay pair when the repoint PUT fails', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - scriptNamesTaken: ['winning-relay'], - failOn: { setCatchAll: new CloudflareApiError('Cloudflare API error: 500', 500) }, - }); - - const result = await removeEmailDomain( - { ...removeInput, repoint_catch_all_to: 'winning-relay' }, - depsFor(client), - ); - - expect(result.failed_steps).toEqual(['catch_all', 'delete_relay']); - expect(methods(calls)).toEqual(['getCatchAll', 'relayScriptExists', 'setCatchAll']); - expect(methods(calls)).not.toContain('deleteRelayScript'); - }); - - it('takes the plain reset path when the repoint target names the row’s own relay', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await removeEmailDomain( - { ...removeInput, repoint_catch_all_to: RELAY_WORKER_BASE_NAME }, - depsFor(client), - ); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual(['getCatchAll', 'resetCatchAll', 'deleteRelayScript']); - expect(methods(calls)).not.toContain('relayScriptExists'); - }); - - it('revokes the grant after the CF cleanup when the refresh succeeded', async () => { - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const refreshed: Array = []; - let revoked = 0; - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async (refreshToken: string) => { - refreshed.push(refreshToken); - // The refresh precedes every customer call. - expect(calls).toEqual([]); - return { accessToken: 'cf-access-dummy', refreshToken: 'cf-rotated-dummy' }; - }, - // Zero-arg: the dep revokes the row's LIVE chain head; which token - // that is belongs to the serialized helper, not the engine. - revokeGrant: async () => { - revoked += 1; - // Revocation is the LAST step — the CF cleanup already ran. - expect(methods(calls)).toEqual(['getCatchAll', 'resetCatchAll', 'deleteRelayScript']); - }, - }), - ); - - expect(result.failed_steps).toEqual([]); - expect(refreshed).toEqual([CREDENTIAL]); - expect(revoked).toBe(1); - }); - - it("appends 'revoke_grant' to failed_steps when the revocation rejects, without throwing", async () => { - const { client } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => ({ - accessToken: 'cf-access-dummy', - refreshToken: 'cf-rotated-dummy', - }), - revokeGrant: async () => { - throw new Error('network down'); - }, - }), - ); - - expect(result.failed_steps).toEqual(['revoke_grant']); - }); - - it('skips the revocation when the refresh fails with invalid_grant — the grant is already dead', async () => { - const { client, calls } = makeFakeClient(); - const revokeGrant = vi.fn(async () => {}); - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => { - throw new OAuthGrantError('invalid_grant', 400); - }, - revokeGrant, - }), - ); - - expect(result.failed_steps).toEqual(['delete_relay', 'catch_all']); - expect(revokeGrant).not.toHaveBeenCalled(); - expect(calls).toEqual([]); - }); - - it('revokes when the refresh fails transiently — the stored token may still be live', async () => { - const { client, calls } = makeFakeClient(); - let revoked = 0; - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => { - throw new OAuthGrantError('temporarily_unavailable', 503); - }, - revokeGrant: async () => { - revoked += 1; - }, - }), - ); - - // The early-return shape is unchanged. - expect(result.failed_steps).toEqual(['delete_relay', 'catch_all']); - expect(revoked).toBe(1); - expect(calls).toEqual([]); - }); - - it('never revokes an api_token row, even with the dep', async () => { - const { client } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - const revokeGrant = vi.fn(async () => {}); - - const result = await removeEmailDomain(removeInput, depsFor(client, { revokeGrant })); - - expect(result.failed_steps).toEqual([]); - expect(revokeGrant).not.toHaveBeenCalled(); - }); - - it('runs the oauth cleanup without any revocation when no revokeGrant dep is supplied', async () => { - // Deliberate: the conflict-compensation caller leaves its row alive, - // so it passes no dep and the credential keeps working. - const { client, calls } = makeFakeClient({ - catchAll: { enabled: true, workerName: RELAY_WORKER_BASE_NAME }, - }); - - const result = await removeEmailDomain( - { ...removeInput, row: { ...removeInput.row, credential_kind: 'oauth_grant' } }, - depsFor(client, { - refreshGrant: async () => ({ - accessToken: 'cf-access-dummy', - refreshToken: 'cf-rotated-dummy', - }), - }), - ); - - expect(result.failed_steps).toEqual([]); - expect(methods(calls)).toEqual(['getCatchAll', 'resetCatchAll', 'deleteRelayScript']); - }); -}); diff --git a/platform/packages/email-gateway/src/index.ts b/platform/packages/email-gateway/src/index.ts index e08bbe976..7f4bfa8ff 100644 --- a/platform/packages/email-gateway/src/index.ts +++ b/platform/packages/email-gateway/src/index.ts @@ -92,11 +92,11 @@ async function resolveIngress( } const contentLength = Number(response.headers.get('content-length')); if (Number.isFinite(contentLength) && contentLength > 4096) { - return null; + throw new Error('invalid email routing response'); } const reader = response.body?.getReader(); if (!reader) { - return null; + throw new Error('invalid email routing response'); } const chunks: Array = []; let total = 0; @@ -105,7 +105,7 @@ async function resolveIngress( while (true) { const remaining = deadline - Date.now(); if (remaining <= 0) { - return null; + throw new Error('email routing response timeout'); } let timer: ReturnType | undefined; const chunk = await Promise.race([ @@ -123,7 +123,7 @@ async function resolveIngress( } total += chunk.value.byteLength; if (total > 4096) { - return null; + throw new Error('invalid email routing response'); } chunks.push(chunk.value); } @@ -142,10 +142,10 @@ async function resolveIngress( try { route = JSON.parse(text); } catch { - return null; + throw new Error('invalid email routing response'); } if (!route || typeof route !== 'object') { - return null; + throw new Error('invalid email routing response'); } const value = route as Partial; if ( @@ -157,7 +157,7 @@ async function resolveIngress( typeof value.domain !== 'string' || (value.addressing !== 'shared' && value.addressing !== 'custom') ) { - return null; + throw new Error('invalid email routing response'); } return value as Route; } diff --git a/platform/packages/email-gateway/test/unit/gateway.test.ts b/platform/packages/email-gateway/test/unit/gateway.test.ts index 9c5a41396..da2747117 100644 --- a/platform/packages/email-gateway/test/unit/gateway.test.ts +++ b/platform/packages/email-gateway/test/unit/gateway.test.ts @@ -152,6 +152,33 @@ describe('dedicated email gateway', () => { ); expect(message.setReject).not.toHaveBeenCalled(); }); + + it.each([ + () => new Response(null), + () => new Response('{'), + () => Response.json({ projectId: 'project-1' }), + () => new Response('x'.repeat(4097)), + () => new Response('{}', { headers: { 'content-length': '4097' } }), + ])( + 'does not turn a malformed authority response into a permanent rejection', + async (response) => { + const environment = env(async () => response()); + expect((await gateway.fetch(request(new Uint8Array()), environment, context)).status).toBe( + 503, + ); + const message = { + from: 'sender@example.net', + to: 'support@example.com', + setReject: vi.fn(), + } as unknown as ForwardableEmailMessage; + await expect(gateway.email(message, environment, context)).rejects.toThrow( + 'temporarily unavailable', + ); + expect(message.setReject).not.toHaveBeenCalled(); + expect(router.routeInbound).not.toHaveBeenCalled(); + expect(router.routeRelayed).not.toHaveBeenCalled(); + }, + ); it('authenticates ingress before consuming MIME bytes', async () => { const pulled = vi.fn(() => { throw new Error('body must stay unread'); diff --git a/platform/packages/proxy/src/email-lease.ts b/platform/packages/proxy/src/email-lease.ts index 70ce88abc..4c7040b83 100644 --- a/platform/packages/proxy/src/email-lease.ts +++ b/platform/packages/proxy/src/email-lease.ts @@ -1,58 +1,17 @@ -/** - * Credential lease client for custom sender domains (design doc 0078, - * "Custom domains on Cloudflare"). - * - * The proxy never decrypts a domain's stored credential — the OAuth grant's - * refresh token or the pasted API token lives encrypted on the api's - * `email_domains` row and only the api reads it. When a send's from-domain - * is a registered custom domain, the proxy LEASES a short-lived credential - * from the api instead: - * - * POST {API}/internal/email/domain-credential { domain } - * → { kind: 'api_token', token } | { kind: 'oauth_grant', accessToken } - * - * The call uses the platform-internal auth pattern the proxy already uses - * to call the api (`resolve.ts`, the revalidation bridge): an HMAC under - * JWT_SECRET in the `x-void-internal` header. The signed value is the - * domain — the one value both sides of this call already hold. - * - * The api owns the OAuth refresh chain (serialized per row, the rotated - * refresh token persisted atomically with it) and returns a fresh access - * token on every lease — there is no access-token cache on the api side. - * The proxy requests a fresh lease for every provider submission so a - * revoked or rotated credential cannot be reused from an isolate cache. - * - * A leased credential is a customer secret: it is never logged, never - * interpolated into an error message, and never leaves this module except - * as the `Authorization: Bearer` value of the send_raw call. - */ +/** Lease a customer API token from the platform for a custom-domain send. */ import type { Env } from './types.ts'; -export type EmailDomainLease = - | { kind: 'api_token'; token: string; accountId: string } - | { kind: 'oauth_grant'; accessToken: string; accountId: string }; - -/** @internal Exposed for testing only. */ -export function clearEmailDomainLeaseCache(): void {} - -/** - * Drop one cached lease. Called when Cloudflare refused the credential - * (401/403 from send_raw) so the next send re-leases instead of replaying a - * credential the api may already have marked revoked. - */ -export function dropEmailDomainLease(_domain: string): void {} +export type EmailDomainLease = { kind: 'api_token'; token: string; accountId: string }; /** The bearer value for the send_raw Authorization header. */ export function leaseBearer(lease: EmailDomainLease): string { - return lease.kind === 'api_token' ? lease.token : lease.accessToken; + return lease.token; } /** * Lease a send credential for a registered domain from the api. Returns - * null on any failure — the caller maps that to a retryable UPSTREAM_ERROR; - * the api owns the row's status transitions (`token_revoked`, …) on real - * credential failures, via its own refresh path. + * null on any failure; the caller maps that to a retryable upstream error. */ export async function leaseEmailDomainCredential( env: Pick, @@ -105,12 +64,6 @@ function parseLease(data: unknown): EmailDomainLease | null { const token = (data as { token?: unknown }).token; return typeof token === 'string' && token.length > 0 ? { kind, token, accountId } : null; } - if (kind === 'oauth_grant') { - const accessToken = (data as { accessToken?: unknown }).accessToken; - return typeof accessToken === 'string' && accessToken.length > 0 - ? { kind, accessToken, accountId } - : null; - } return null; } diff --git a/platform/packages/proxy/src/email-policy.ts b/platform/packages/proxy/src/email-policy.ts deleted file mode 100644 index 4016cb29a..000000000 --- a/platform/packages/proxy/src/email-policy.ts +++ /dev/null @@ -1,140 +0,0 @@ -/** - * The shared-sender recipient gate (design doc 0078, "Recipient policy"). - * - * Two KV reads decide whether a recipient may be mailed from a project's - * `+tag@` address: the project's verified - * destinations (`email-allowlist:`) and one installation-wide - * policy (`email-recipient-policy`), both mirrored by the api. The policy - * can only widen the allowlist; an absent or unreadable policy mirror is the - * default `verified` mode, so a failed publish never loosens the gate. - * - * The custom-domain lane does not use this gate at all (the customer's own - * Email Sending onboarding lifts Cloudflare's destination check there). - */ - -export type RecipientPolicyMode = 'verified' | 'domains' | 'any'; - -export type RecipientPolicy = Readonly<{ - mode: RecipientPolicyMode; - /** Lowercased recipient domains; only populated for `domains`. */ - domains: ReadonlySet; -}>; - -export const RECIPIENT_POLICY_KEY = 'email-recipient-policy'; - -/** Mirrors the api's `MAX_POLICY_DOMAINS`; a longer list is not the api's. */ -const MAX_POLICY_DOMAINS = 100; - -export const VERIFIED_ONLY: RecipientPolicy = Object.freeze({ - mode: 'verified', - domains: new Set(), -}); - -/** - * Reads `email-recipient-policy`. `cacheTtl` bounds per-colo convergence at - * ~60s, like the allowlist. Anything that is not `{ mode, domains[] }` with - * a known mode reads as `verified`. An unreadable mirror — a rejected read - * included — is `verified`. - */ -export async function readRecipientPolicy(kv: KVNamespace): Promise { - let raw: string | null; - try { - raw = await kv.get(RECIPIENT_POLICY_KEY, { cacheTtl: 60 }); - } catch (err) { - console.error('[email-policy] recipient policy read failed; enforcing verified:', err); - return VERIFIED_ONLY; - } - if (!raw) { - return VERIFIED_ONLY; - } - let parsed: unknown; - try { - parsed = JSON.parse(raw); - } catch { - return VERIFIED_ONLY; - } - if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { - return VERIFIED_ONLY; - } - const { mode, domains } = parsed as { mode?: unknown; domains?: unknown }; - // The api writes exactly `{ mode: 'any', domains: [] }` or - // `{ mode: 'domains', domains: [1..100 non-empty lowercase strings] }`. - // Anything else is not the api's mirror and must not widen the gate. - if (!Array.isArray(domains) || domains.length > MAX_POLICY_DOMAINS) { - return VERIFIED_ONLY; - } - if (mode === 'any') { - return domains.length === 0 ? { mode: 'any', domains: new Set() } : VERIFIED_ONLY; - } - if (mode === 'domains') { - if (domains.length === 0 || !domains.every((d) => typeof d === 'string' && d !== '')) { - return VERIFIED_ONLY; - } - return { mode: 'domains', domains: new Set(domains.map((d) => d.toLowerCase())) }; - } - return VERIFIED_ONLY; -} - -/** - * Reads `email-allowlist:` — a JSON array of lowercased verified - * addresses the api writes on every destination CRUD, on the platform - * confirmation click, and as the repair for a stale key. A missing key reads - * as empty, so a brand-new project has every recipient refused. - */ -export async function readAllowlist(kv: KVNamespace, projectId: string): Promise> { - const raw = await kv.get(`email-allowlist:${projectId}`, { cacheTtl: 60 }); - if (!raw) { - return new Set(); - } - try { - const arr = JSON.parse(raw) as unknown; - if (!Array.isArray(arr)) { - return new Set(); - } - const out = new Set(); - for (const v of arr) { - if (typeof v === 'string') { - out.add(v.toLowerCase()); - } - } - return out; - } catch { - return new Set(); - } -} - -/** - * `recipient` is already lowercased by the caller. `platformDomains` are the - * installation's own mail domains — `EMAIL_SENDER_DOMAIN` and, on inbound, - * the domain Cloudflare accepted the message on. The policy never widens - * delivery to addresses on them, so one tenant cannot use `any` or a listed - * platform domain to mail another tenant's `+tag@` inbox — or form a - * reply loop with it — without that recipient's own consent. - */ -export function recipientAllowed( - policy: RecipientPolicy, - allowlist: ReadonlySet, - recipient: string, - platformDomains: ReadonlyArray = [], -): boolean { - if (allowlist.has(recipient)) { - return true; - } - const at = recipient.lastIndexOf('@'); - const domain = at > 0 ? recipient.slice(at + 1) : ''; - if (domain !== '' && platformDomains.some((d) => d.toLowerCase() === domain)) { - return false; - } - if (policy.mode === 'any') { - return true; - } - return policy.mode === 'domains' && domain !== '' && policy.domains.has(domain); -} - -/** The per-recipient `UNVERIFIED_DESTINATION` message for a refused recipient. */ -export function recipientRefusalMessage(policy: RecipientPolicy, recipient: string): string { - const base = `recipient '${recipient}' is not a verified destination for this project`; - return policy.mode === 'domains' - ? `${base} and its domain is not in the platform's recipient policy` - : base; -} diff --git a/platform/packages/proxy/src/email-relay.ts b/platform/packages/proxy/src/email-relay.ts deleted file mode 100644 index 6261e22dd..000000000 --- a/platform/packages/proxy/src/email-relay.ts +++ /dev/null @@ -1,282 +0,0 @@ -/** - * POST /email/relay — the inbound hop for custom sender domains (design doc - * 0078, "Custom domains on Cloudflare"). - * - * A relay worker deployed into the CUSTOMER's Cloudflare account (one per - * registered domain) receives the zone's catch-all mail and streams the raw - * MIME here, with the envelope in headers: - * - * POST /email/relay - * Authorization: Bearer - * X-Void-Email-Domain / X-Void-Email-From / X-Void-Email-To - * - * - * Auth happens in the global auth middleware in `index.ts` (header and - * content-length bounds BEFORE any crypto, then the mirror lookup, the - * constant-time secret compare, the `active` status check, and - * `context.set('projectId', …)`). This handler reads the body, builds the - * `EmailEnvelope` from the header envelope + body, and runs the second half - * of `routeInbound` — `routeRelayed` in `email-router.ts` — for the - * mirror's project. - * - * The relay worker answers any non-2xx with `message.setReject` and a - * generic reason, so this endpoint's response is one bit: 200 accepted, - * anything else rejected. Failure detail stays in proxy logs; the response - * body never carries it. - */ - -import { Hono } from 'hono'; -import { MAX_INBOUND_HEADERS, routeRelayed } from './email-router.ts'; -import type { EmailEnvelope } from './email-router.ts'; -import { MAX_MIME_BYTES } from './email.ts'; -import type { ProxyEnv } from './types.ts'; - -const app = new Hono(); - -app.post('/relay', async (context) => { - // Set by the auth branch; the envelope headers were presence- and - // length-checked there. Read them here rather than trusting the body — - // the relay derives them from the CF envelope, and the MIME's own From:/ - // To: headers are the sender's bytes. - const projectId = context.get('projectId'); - const from = context.req.header('X-Void-Email-From') ?? ''; - const to = context.req.header('X-Void-Email-To') ?? ''; - // The auth branch proved the declared domain header equals the envelope - // recipient's domain; attribute on the envelope, never on the claim. - const domain = to.slice(to.lastIndexOf('@') + 1).toLowerCase(); - - const body = context.req.raw.body; - if (!body) { - return context.json({ error: 'mime body required' }, 400); - } - // The middleware checked the DECLARED content-length; a declared length - // can lie, so the read is bounded again here. - const raw = await readMimeBody(body); - if (raw === null) { - return context.json({ error: 'mime too large' }, 413); - } - const headers = parseRelayedHeaders(raw); - if (headers === null) { - return context.json({ error: 'too many headers' }, 413); - } - - const envelope: EmailEnvelope = { - from, - to, - headers, - raw, - rawSize: raw.byteLength, - viaDomain: domain, - }; - - // Hono's `context.executionCtx` throws when the worker was invoked - // without one (unit tests call `app.fetch(request, env)`). Fall back to a - // collector whose promises are flushed before the response, so tests - // observe the same log-recv effects production defers. - const pending: Array> = []; - let ctx: ExecutionContext = { - waitUntil(p: Promise) { - pending.push(p); - }, - passThroughOnException() {}, - } as unknown as ExecutionContext; - try { - ctx = context.executionCtx as unknown as ExecutionContext; - } catch { - // No ExecutionContext on this invocation — keep the collector. - } - - const outcome = await routeRelayed(context.env, ctx, { projectId, domain, envelope }); - if (pending.length > 0) { - await Promise.allSettled(pending); - } - if (outcome.reject) { - return context.json({ error: 'message rejected' }, 403); - } - return context.json({ ok: true }); -}); - -/** - * Bounded read of the request body — the same accumulation pattern as - * `readStreamToBytes` in `email-router.ts`, against the outbound MIME cap - * (the contract's "existing MIME size cap"), returning null instead of - * throwing so the caller answers a plain 413. - */ -async function readMimeBody(stream: ReadableStream): Promise { - const reader = stream.getReader(); - const chunks: Array = []; - let total = 0; - for (;;) { - const { value, done } = await reader.read(); - if (done) { - break; - } - total += value.byteLength; - if (total > MAX_MIME_BYTES) { - // Cancel so the peer stops sending; the size refusal is already - // decided. - try { - await reader.cancel(); - } catch { - // Cancellation is best-effort. - } - return null; - } - chunks.push(value); - } - const out = new Uint8Array(total); - let offset = 0; - for (const c of chunks) { - out.set(c, offset); - offset += c.byteLength; - } - return out; -} - -const LF = 0x0a; -const CR = 0x0d; - -/** - * RFC 7230 tchar — the only names `new Headers()` accepts. A line whose - * name fails this is skipped WITH its continuations. - */ -const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9a-z]+$/; - -/** - * Rebuild the envelope's header bag from the raw MIME header block — the - * relay carries no parsed headers, and the platform lane's `buildEnvelope` - * equivalent for this lane has to read the same bytes the tenant will. - * - * The block ends at the first empty line. Continuation lines (leading WSP) - * unfold onto the header they extend; a name repeated folds with `", "`, - * matching how workerd's `Headers` presents a duplicated header on the - * platform lane. `Object.fromEntries` defines each name as an OWN data - * property for the same reason `buildEnvelope` uses it: a `__proto__` - * header must never touch the prototype chain. - * - * The tenant worker rebuilds a `Headers` from this record inside - * `createMessageProxy`, and a throw there fails dispatch — so any name that - * is not a tchar token, and any value `new Headers()` would refuse (NUL, - * CR, LF, DEL and the other C0/C1 controls, or a code point above the - * ByteString ceiling), is SKIPPED rather than passed through. The raw MIME - * stays authoritative: `parseEmail` in the tenant sees everything. - * - * Returns null when the block holds more DISTINCT names than - * `MAX_INBOUND_HEADERS` — the same refusal the platform lane makes. - */ -/** - * Cap TOTAL header pieces (distinct names + repeat occurrences + folds). - * `MAX_INBOUND_HEADERS` alone bounds only new map keys: one valid name - * repeated hundreds of thousands of times inside the MIME cap would still - * allocate and join an unbounded number of pieces here, in the shared - * proxy isolate. The count is charged per piece — the allocation unit — - * so repeats and folds hit the same wall as distinct names. - */ -const MAX_INBOUND_HEADER_LINES = 4096; - -function parseRelayedHeaders(raw: Uint8Array): Record | null { - const block = new TextDecoder().decode(raw.subarray(0, headerBlockEnd(raw))); - // Pieces per name, each pushed with its join separator — `", "` for a - // repeat occurrence, `" "` for a fold — and joined ONCE at the end; - // concatenating the accumulated value per line is quadratic CPU on a - // block of repeated same-name headers. - const folded = new Map>(); - // Total pieces across all names — the allocation unit the cap charges. - let totalPieces = 0; - // The name the current continuation line extends, or null when the - // previous line was skipped. - let current: string | null = null; - let pos = 0; - while (pos < block.length) { - let nl = block.indexOf('\n', pos); - if (nl === -1) { - nl = block.length; - } - let line = block.slice(pos, nl); - pos = nl + 1; - if (line.endsWith('\r')) { - line = line.slice(0, -1); - } - if (line === '') { - break; - } - if (line.startsWith(' ') || line.startsWith('\t')) { - if (current !== null && headerValueSafe(line)) { - totalPieces += 1; - if (totalPieces > MAX_INBOUND_HEADER_LINES) { - return null; - } - const pieces = folded.get(current) ?? []; - pieces.push(` ${line.trim()}`); - folded.set(current, pieces); - } - continue; - } - const colon = line.indexOf(':'); - if (colon === -1) { - current = null; - continue; - } - const name = line.slice(0, colon).trim().toLowerCase(); - const value = line.slice(colon + 1).trim(); - if (!HEADER_NAME_RE.test(name) || !headerValueSafe(value)) { - current = null; - continue; - } - const pieces = folded.get(name); - totalPieces += 1; - if (totalPieces > MAX_INBOUND_HEADER_LINES) { - return null; - } - if (pieces !== undefined) { - pieces.push(`, ${value}`); - } else { - if (folded.size >= MAX_INBOUND_HEADERS) { - return null; - } - folded.set(name, [value]); - } - current = name; - } - return Object.fromEntries( - Array.from(folded, ([name, pieces]): [string, string] => [name, pieces.join('')]), - ); -} - -/** Byte offset where the header block ends (the first empty line). */ -function headerBlockEnd(raw: Uint8Array): number { - let lineStart = 0; - while (lineStart < raw.length) { - const lf = raw.indexOf(LF, lineStart); - const lineEnd = lf === -1 ? raw.length : lf; - let contentEnd = lineEnd; - if (contentEnd > lineStart && raw[contentEnd - 1] === CR) { - contentEnd--; - } - if (contentEnd === lineStart) { - return lineStart; - } - lineStart = lf === -1 ? raw.length : lf + 1; - } - return raw.length; -} - -/** - * True when `new Headers()` accepts the value: HTAB, visible ASCII, and - * Latin-1 (the ByteString range) are legal; every other control and any - * code point above 0xff is not. - */ -function headerValueSafe(value: string): boolean { - for (let i = 0; i < value.length; i++) { - const code = value.charCodeAt(i); - if (code === 0x09) { - continue; - } - if (code < 0x20 || code === 0x7f || code > 0xff) { - return false; - } - } - return true; -} - -export { app as emailRelay }; diff --git a/platform/packages/proxy/src/email-router.ts b/platform/packages/proxy/src/email-router.ts index 4075b1578..96f445363 100644 --- a/platform/packages/proxy/src/email-router.ts +++ b/platform/packages/proxy/src/email-router.ts @@ -1,26 +1,4 @@ -/** - * Inbound email router for the platform mail zone. - * - * Bound as the catch-all CF Email Routing rule on the zone named by the - * `EMAIL_SENDER_DOMAIN` var (`mail.void.cloud` in production, - * `mail.staging.void.cloud` in staging). Every inbound message hits this - * worker; we parse `+` from the - * recipient local-part, look up the project's worker name in `ROUTING` KV, - * serialize the message into an `EmailEnvelope` (RPC-safe), and dispatch - * into the user worker via the WfP namespace stub's `email(envelope)` RPC - * method. The user worker returns an `EmailAction[]` describing what its - * handler decided; we enact each action on the real - * `ForwardableEmailMessage`. - * - * Why an envelope/action contract instead of passing the real message? - * `ForwardableEmailMessage` is not in workerd's RPC `BaseType` allowlist - * (see types/defines/rpc.d.ts) and isn't `JSG_SERIALIZABLE` (see - * src/workerd/jsg/ser.c++:241-330). Calling `stub.email(realMessage)` - * throws `DataCloneError` before any bytes are sent. The envelope shape - * uses only RPC-safe primitives (string, plain object, ReadableStream - * , number) so marshaling succeeds. Async metering log fires - * via ctx.waitUntil after the handler returns. - */ +/** Inbound email actions after the gateway resolves an authoritative route. */ import { isReservedEmailSlug } from '@voidcloud/api/reserved-slugs'; import { EmailMessage } from 'cloudflare:email'; @@ -33,17 +11,9 @@ import { recordEmailReceipt, startEmailAttempt, } from './email-admission.ts'; -import { dropEmailDomainLease, leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; -import { - VERIFIED_ONLY, - readAllowlist, - readRecipientPolicy, - recipientAllowed, - type RecipientPolicy, -} from './email-policy.ts'; +import { leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; import { MAX_MIME_BYTES, - readEmailDomainMirror, readMimeFromAddrSpec, readSenderDomain, readSendRawAddressList, @@ -56,56 +26,12 @@ import type { Env } from './types.ts'; // oxlint-disable-next-line no-control-regex const CONTROL_CHARS_RE = new RegExp('[\\u0000-\\u001f\\u007f]+', 'g'); -/** - * Strip CR/LF/NUL/control chars before logging or sending to remote MTAs. - * - * Slice FIRST, then replace. Several inputs here arrive over RPC from the - * tenant worker (a reject reason, a non-object action, an unknown action - * type) and are bounded by nothing but the 32 MiB transport cap. A global - * regex replace materializes one part per match, so a control-heavy string - * costs far more than one copy: measured, a 30 MB `\0a\0a…` reason is - * ~1 GB of transient heap and 800+ ms, and a 4 MB one already exhausts a - * 128 MB heap — the shared proxy isolate's ceiling — before any outbound - * gate has run. Slicing first bounds the replace to `maxLen` code units. - * - * The result is therefore at most `maxLen` chars and may be SHORTER: a run of - * controls inside the window collapses to one space and the window is not - * refilled from beyond `maxLen`. Every caller renders a log line or a DSN - * reason, where a shorter window loses nothing that matters. Slicing at a - * UTF-16 index can split a surrogate pair either way — the old order sliced - * at the same kind of boundary after replacing — so this does not change - * that class of edge. - */ +/** Bound log and rejection text before stripping control characters. */ function sanitize(value: string, maxLen: number): string { return value.slice(0, maxLen).replace(CONTROL_CHARS_RE, ' '); } -/** - * Render a tenant-supplied value of UNKNOWN type for a log line, without - * ever coercing its contents. - * - * `sanitize(String(value), n)` is bounded only when `value` is already a - * string. Everything else the RPC transport can carry is an amplifier or a - * CPU sink that runs to completion before the slice: `String()` of a typed - * array or an Array joins every element with commas (measured: a 30 MB - * `Uint8Array` is a 107M-char string, +385 MB of heap, ~580 ms, and an OOM - * under the 128 MB isolate ceiling; a nested array flattens recursively - * to the same), and `String()` of a BigInt is a decimal conversion that is - * superlinear in its size (measured: 4 MiB is 1.9 s, 32 MiB is 20 s of CPU - * — the whole RPC cap, spent ahead of every outbound gate). Both reach here - * from any hand-built entrypoint, as an action, an action's `type`, or an - * address that failed validation. - * - * So: a string is sliced then stripped; a number, boolean, `undefined` or - * `null` renders as itself (all a few chars); and anything else — bigint, - * function, symbol, any object — renders as its KIND only. The object tag - * comes from `Object.prototype.toString`, which reads nothing a tenant can - * set: it consults only `Symbol.toStringTag`, and symbol-keyed properties do - * not cross RPC (structured clone drops them). `constructor.name` would - * not be safe — `constructor` is an ordinary string key the tenant can send - * with any value. The tag is sliced anyway so a local caller cannot make it - * long either. - */ +/** Render unknown tenant values by kind without coercing large arrays or objects. */ function describeUntrusted(value: unknown, maxLen: number): string { switch (typeof value) { case 'string': @@ -122,50 +48,17 @@ function describeUntrusted(value: unknown, maxLen: number): string { } } -interface RoutingEntry { - workerName?: string; - projectId?: string; - version?: string; - /** - * Per-project dispatch limits (`{ cpuMs?, subRequests? }`), written by the - * api worker and applied by `packages/dispatch` on every HTTP request. - * Inbound mail dispatches into the same tenant worker, so it has to pass - * the same limits — otherwise anyone who can send mail to a project's - * address runs that tenant's worker at the namespace default. - */ - limits?: Record; - /** - * Platform-wide suspension marker, written by `applyRoutingSuspension` in - * the api worker and answered with a 429 by `packages/dispatch`. Inbound - * mail honors it too: running a suspended tenant's code on platform CPU is - * exactly what suspension exists to stop. - */ - suspended?: string; - // Other routing fields exist on this KV value (used by HTTP dispatch); - // we only care about these here. -} - export interface AuthoritativeEmailRoute { projectId: string; workerName: string; deploymentId: string; slug: string; addressing: 'shared' | 'custom'; - domain?: string; + domain: string; limits?: Record; } -/** - * Mirrors `void/email`'s EmailEnvelope. RPC-safe primitives only. - * - * `raw` is a `Uint8Array` (not a `ReadableStream`) because we pre-buffer - * the message body in `buildEnvelope`. The framework-side `EmailEnvelope` - * type accepts both shapes for forward-compat, but every value we send - * over the wire today is a Uint8Array. Both forms ARE in workerd's RPC - * `BaseType` allowlist, so either marshals; the buffered form survives - * being read more than once on the user worker (parseEmail consumes the - * stream, and we want the receiving framework to be free to replay). - */ +/** Bounded envelope passed through the gateway's tenant dispatch protocol. */ interface EmailEnvelope { from: string; to: string; @@ -173,16 +66,13 @@ interface EmailEnvelope { raw: Uint8Array; rawSize: number; /** - * The registered custom domain this message arrived on, set only on the - * relay lane (`/email/relay` — design doc 0078, "Custom domains on - * Cloudflare"). Undefined on the platform mail zone. The framework's - * dispatcher runs in no-prefix mode for a relayed envelope (Mode B item - * 4): the recipient carries no `+` prefix to strip. + * The registered custom domain this message arrived on. Its recipient + * carries no shared-domain project prefix to strip. */ viaDomain?: string; } -/** Exported for the relay lane (`email-relay.ts`), which builds its own. */ +/** Shared with the dedicated gateway. */ export type { EmailEnvelope }; /** Mirrors `void/email`'s EmailAction. */ @@ -191,157 +81,32 @@ type EmailAction = | { type: 'forward'; to: string; headers?: Record } | { type: 'reply'; from: string; to: string; raw: Uint8Array }; -interface EmailEntrypointStub { - /** - * Standard CF handler-named RPC method on the user worker's - * WorkerEntrypoint subclass. Receives an envelope (RPC-safe primitives) - * and returns the action queue the framework's dispatcher recorded. - */ - email?(envelope: EmailEnvelope): Promise | undefined>; - fetch?(req: Request | string, init?: RequestInit): Promise; -} - -/** - * Cap inbound bytes well below CF's ~25 MB ceiling. The envelope is buffered - * here AND copied again across RPC into the user worker, so two of these have - * to fit in the proxy isolate's heap. 10 MB is generous for normal mail and - * keeps headroom for everything else the isolate is doing. - * - * The framework's test harness (`createInboundTestHarness`) restates this - * and `MAX_INBOUND_HEADERS` and refuses a synthetic message the way this - * router does, before the handler runs, so a test cannot pass a handler - * against a message the router never dispatches; exported so the router - * test pins the pairs equal. - */ +/** Keep buffered messages within the shared proxy isolate budget. */ export const MAX_INBOUND_BYTES = 10 * 1024 * 1024; -/** - * Cap the number of DISTINCT header names on an inbound message. - * - * `MAX_INBOUND_BYTES` bounds the header bag's BYTES (headers are part of - * `raw`) but not its COUNT, and count is what `buildEnvelope` pays for: - * `Object.fromEntries` defines one own property per distinct name on a - * dictionary-mode object, ~75–110 B of V8 heap each (measured; the range - * is the table's doubling cycle), against a wire minimum of 7 bytes per - * line (`abcd:\r\n`). The byte cap therefore admits ~1.5M distinct names, - * and materializing those is a hard OOM under the 128 MB isolate ceiling - * (measured: 1.5M keys is 158 MB retained and ~580 ms in Node, ~1.2 s of - * CPU in workerd; 1.3M still fits, at 82 MB) — in the SHARED proxy isolate, - * ahead of dispatch, from any remote sender who fills a message with short - * headers. The same bag is then walked again by the RPC serializer and - * copied into a `Headers` by the tenant's `createMessageProxy`, so the cap - * here bounds both of those too. - * - * Real mail carries well under 100 distinct names. workerd's `Headers` - * folds repeated names (`Received`, `DKIM-Signature`, `ARC-*`) into ONE - * entry each, so hop count does not raise the number. 1024 is 10x that, - * and the amplified cost at 1024 (~140 KB) is noise next to the raw buffer. - * - * Checked by walking `message.headers` and stopping at the cap, BEFORE the - * body is buffered and before `Object.fromEntries` builds anything. In - * workerd, `entries()` snapshots the whole bag once into a `kj::Array` - * (`Headers::getDisplayedHeaders`, C++ memory the V8 heap limit does not - * see; there is no `size`) — work `fromEntries` was paying anyway. The - * early stop is what keeps the V8-side cost of an over-cap message to - * `MAX_INBOUND_HEADERS + 1` pairs. - */ +/** Bound distinct header names before building the envelope object. */ export const MAX_INBOUND_HEADERS = 1024; export const MAX_INBOUND_HEADER_BYTES = 128 * 1024; -/** - * Cap user-supplied reject reasons — surfaced to remote MTAs and our logs. - * The framework's `createMessageProxy` restates this figure and applies the - * same slice-and-strip when the reason is recorded, so a native - * (own-account) replay carries the string this router would; exported so - * the router test pins the two equal. - */ +/** Limit handler rejection text exposed to remote MTAs and logs. */ export const MAX_REJECT_REASON_LENGTH = 1000; -/** - * Cap the number of actions one dispatch may return. - * - * The list arrives over RPC from a tenant worker and is walked here, in the - * SHARED proxy isolate, before `checkOutboundGate` has looked at a single - * entry — so an unbounded list is per-entry validation work (address regex, - * `new Headers()`, `sanitize()` on every drop log) that is never metered and, - * because the drop path just `continue`s, endlessly repeatable by anyone who - * can send mail to the project's address. The framework caps the queue at the - * same number, but that cap lives inside the tenant's own worker: a - * Workers-for-Platforms tenant can ship any `WorkerEntrypoint` whose `email()` - * returns any array at all, so the framework-side cap is a developer-experience - * guardrail and THIS one is the boundary. Same belt-and-suspenders split as - * `MAX_RECIPIENTS` on the outbound path in `email.ts`. - * - * Checked against the RAW list BEFORE the loop allocates, for the same reason - * `MAX_RECIPIENTS` is checked before normalization: the loop is what costs. - * - * Matches the outbound `MAX_RECIPIENTS` deliberately. An inbound forward or - * reply IS the outbound fan-out primitive — same per-project allowlist, same - * burst and monthly counters — so the two paths must not offer different - * ceilings on the same capability. - */ +/** Bound tenant action validation work per inbound delivery. */ const MAX_ACTIONS = 100; -/** - * Cap a single address inside an action (`forward.to`, `reply.from`, - * `reply.to`). `MAX_ACTIONS` alone still leaves a 100 x
- * amplifier: every address is scanned by `isValidEmailAddress` and, on the - * drop path, copied twice more by `sanitize()`. Checked BEFORE the scan for - * exactly that reason. RFC 5321 caps a forward-path at 256 octets, so 320 is - * generous for anything deliverable — and it is the outbound - * `MAX_RECIPIENT_LENGTH` value, for the reason given above. - */ +/** Maximum action address length before syntax validation. */ const MAX_ACTION_ADDRESS_LENGTH = 320; -/** - * Bound a forward's header bag. `new Headers(...)` lowercases and copies - * every name and validates every value, so an unbounded bag is the same - * unmetered work as an unbounded address list — and it survives RPC as a - * plain object, so nothing upstream has looked at its size. The framework's - * `createMessageProxy` restates both figures and refuses the bag at the - * handler's own call, so a test does not report a forward this router would - * drop; exported so the router test pins the pairs equal. - */ +/** Bound forward header construction. */ export const MAX_FORWARD_HEADERS = 32; export const MAX_FORWARD_HEADER_LENGTH = 1024; -/** - * Cap one reply's MIME bytes: `MAX_MIME_BYTES`, the `/email/send` bound in - * `email.ts`, which is itself the twin of the framework's - * `MAX_MESSAGE_BYTES` in `runtime/email/mime.ts` — the CF ceiling the - * design doc records as ~10 MB base64-inflated. - * - * The framework checks this inside `reply()`, but that runs in the tenant's - * own worker: a hand-written Workers-for-Platforms entrypoint returns any - * `Uint8Array` the 32 MiB RPC transport carries, and until this check the - * router's only bound on `reply.raw` was `instanceof Uint8Array` — it then - * scanned the whole value for `From:` and streamed it into - * `message.reply()`, where CF's own limit fails it late and opaquely (the - * failure is logged here and the reply silently never goes out). Checked - * BEFORE `readMimeFromAddrSpec`, whose scan is linear in `raw`. - */ +/** Limit one reply MIME payload. */ const MAX_REPLY_BYTES = 5 * 1024 * 1024; -/** - * Cumulative reply-byte budget for ONE delivery. Twin of the framework's - * `MAX_REPLY_BYTES_TOTAL` in `runtime/email/inbound.ts`, same figure and - * same rule: a reply that would overrun the budget is refused and NOT - * charged, so a later, smaller reply that fits the remainder still goes. - * Only the offending reply is dropped — like every other per-reply refusal - * here (bad address, sender pin, MIME From) and unlike an invalid forward - * header bag, which drops the whole list because partially enacting an - * injection attempt is the worse failure. An oversized reply is a resource - * bound, and the in-budget replies cost no more than a compliant list. - */ +/** Limit total reply MIME bytes in one delivery. */ const MAX_REPLY_BYTES_TOTAL = 8 * 1024 * 1024; -// workerd's RPC layer throws TypeError with messages like -// "The RPC receiver does not implement the method 'X'". Match a couple of -// shapes to survive minor wording shifts in workerd. Lessons.md notes this -// is the only signal distinguishing pre-WorkerEntrypoint deploys from -// genuine handler errors. -const RPC_METHOD_MISSING = /does not implement the method|receiver does not.*method/i; - class InboundTooLargeError extends Error { constructor(public readonly size: number) { super(`inbound message exceeds ${MAX_INBOUND_BYTES} bytes (got ${size})`); @@ -363,71 +128,17 @@ class InboundHeadersTooLargeError extends Error { } } -/** - * The address rule for `forward.to`, `reply.from` and `reply.to`: - * `email-validator`, the SAME package the framework's `validateAddressParts` - * applies when a handler's `forward(to)` or hand-built `reply()` records the - * action (`packages/void/src/runtime/email/mime.ts`). One rule on both sides - * means nothing the framework records is dropped here for its shape — a drop - * here happens after the actions before it have fired, and a handler's test - * harness has already reported the action as a success. The hand-written - * regex this replaces had drifted from the framework's by one character at - * a time (the dot in the domain, `:`, the control range), and both still - * admitted `a..b@example.com`, which no dot-atom allows. - * - * The package refuses everything the regex did — whitespace, quotes, - * parens, brackets, every C0 control and DEL, a second `@` — and also a - * quoted or non-ASCII local part, a dot-less domain, a malformed dot-atom - * (leading, trailing or doubled dots), a TLD that does not start with a - * letter or is one character, more than 254 characters, a local part over - * 64, or a label over 63. CF does strict validation on forward/reply too; - * failing fast here keeps address fragments away from `EmailMessage` and - * the SMTP layers downstream. - * - * Length FIRST: the package scans the whole string, so testing it on an - * unbounded address is the work `MAX_ACTION_ADDRESS_LENGTH` exists to stop. - * Guarding here covers `forward.to`, `reply.from` and `reply.to` at every - * call site. - * - * Exported for the router test only: the framework's `validateAddressParts` - * is the record-time twin of this rule, and the test pins that the two - * `package.json`s stay on the same rule — every address one side accepts, - * the other accepts, with zero divergences. - */ +/** Use the same address validator as the framework after a length guard. */ export function isValidEmailAddress(s: unknown): s is string { return typeof s === 'string' && s.length <= MAX_ACTION_ADDRESS_LENGTH && isValidEmailSyntax(s); } -/** - * Render a rejected address for a log line. The value is whatever failed - * `isValidEmailAddress`, so it need not be a string at all — a typed array - * or an Array as `to` used to be joined whole by `String()` before the - * slice. `describeUntrusted` renders a string within - * `MAX_ACTION_ADDRESS_LENGTH` code units and anything else by kind. - */ +/** Render invalid addresses without coercing untrusted objects. */ function logAddress(value: unknown): string { return describeUntrusted(value, MAX_ACTION_ADDRESS_LENGTH); } -/** - * True when a forward's header bag is within bounds. Logs and returns false - * otherwise, which DROPS THE WHOLE LIST at the call site — the same response - * `new Headers()` throwing already gets, and for the same reason: an - * over-sized bag on one forward says the handler is hostile, and partially - * enacting the rest of its list is the worse failure mode. - * - * SHAPE FIRST, before anything enumerates. The declared type is a record, - * but the value crossed RPC from the tenant, so it can be a string, a - * `String`, an Array or a typed array — each has one indexed own property - * PER ELEMENT, and `Object.entries` / `Object.keys` / `for…in` all - * materialize the whole key set before a count can be read (V8 builds the - * for-in enum cache up front; `break` does not help). Measured ~100 B per - * element: a 1.5 MiB string is an OOM in a 128 MB isolate, from a payload - * 20x below the RPC cap. The old `new Headers()` threw in - * O(1); this keeps that. workerd RPC only delivers `Object.prototype` - * objects (it refuses to serialize a null-prototype one), so a plain-object - * test is exact; null is accepted too for callers that never crossed RPC. - */ +/** Reject oversized or malformed header bags before constructing Headers. */ function forwardHeadersWithinBounds(headers: unknown): headers is Record { if (typeof headers !== 'object' || headers === null) { console.error('[email-router] action list dropped: forward headers is not a plain object'); @@ -438,9 +149,7 @@ function forwardHeadersWithinBounds(headers: unknown): headers is Record MAX_FORWARD_HEADERS) { console.error( @@ -450,21 +159,14 @@ function forwardHeadersWithinBounds(headers: unknown): headers is Record)[name]; - // The NAME is bounded too: `new Headers()` accepts an arbitrarily long - // token, so an unbounded name is the same amplifier as an unbounded value. + // Headers accepts long names, so cap them explicitly. if (name.length > MAX_FORWARD_HEADER_LENGTH) { console.error( `[email-router] action list dropped: forward header name exceeds ${MAX_FORWARD_HEADER_LENGTH} characters`, ); return false; } - // A non-string value evades the length check below, and `new Headers()` - // does not throw on it: workerd RPC delivers Arrays, typed arrays, and - // numbers verbatim, and `new Headers({ x: })` coerces the value - // with `String()` — an Array joins to one comma-separated string ~30x - // its wire size (measured: a Date-filled Array OOMs the 128 MB isolate - // from a ~4 MiB RPC payload). The declared type is `Record`; anything else is refused before it reaches `new Headers()`. + // Reject values that Headers would coerce to strings. if (typeof value !== 'string') { console.error( `[email-router] action list dropped: forward header "${sanitize(name, 64)}" value is not a string`, @@ -481,74 +183,15 @@ function forwardHeadersWithinBounds(headers: unknown): headers is Record; + customDomain: boolean; } -/** - * True when `from` is a sender this project is allowed to speak as: - * `@` or `+@` on the received domain, - * case-insensitively — or any address on a custom domain whose - * `email-domain:` mirror is `active` and maps to the receiving - * project (the registered-domain shape). - * - * A BARE `@` is refused. The framework strips the `+` - * prefix from `message.to` before a handler sees it, so a handler that - * hand-rolls `from: message.to` produces that shape and CF accepts it - * today — refusing it is a deliberate, breaking narrowing. It has to be: - * a bare local-part is indistinguishable from another tenant's slug and - * from the reserved `noreply`, so permitting the shape would re-open the - * impersonation this pin closes. `replyEmail`'s default - * (`+noreply@`) and the wire form `+@` - * both keep working, and the un-stripped recipient stays available to - * handlers on `message.__voidPlatformTo`. - */ -async function isPermittedReplySender(from: string, pin: ReplySenderPin): Promise { - // The address is forwarded VERBATIM to `EmailMessage`, so the comparison - // has to run on bytes that cannot change under case folding. U+212A - // KELVIN SIGN lowercases to 'k' and U+0130 to 'i', so a non-ASCII - // local-part can satisfy a lowercased compare and still reach the shared - // envelope sender intact. Same guard, same reason, as `email.ts`. +/** Check the envelope shape before authoritative admission checks sender ownership. */ +function isPermittedReplySender(from: string, pin: ReplySenderPin): boolean { if (!/^[\x21-\x7e]+$/.test(from)) { return false; } @@ -558,143 +201,28 @@ async function isPermittedReplySender(from: string, pin: ReplySenderPin): Promis return false; } const fromDomain = lower.slice(at + 1); - if (fromDomain === pin.domain) { - if (pin.customDomain) { - return true; - } - // Split on the first '+' exactly as the recipient is split in - // `routeInbound`, so the sender's slug is read the same way the routed - // slug was. - const localPrefix = lower.slice(0, at).split('+')[0] ?? ''; - if (localPrefix.length > 0 && localPrefix === pin.slug) { - return true; - } - if (pin.authoritative) { - return false; - } - } - if (pin.authoritative) { + if (fromDomain !== pin.domain) { return true; - } // PostgreSQL admission checks exact sender ownership. - return isRegisteredDomainSender(fromDomain, pin); -} - -/** - * The registered-domain shape: true when the `email-domain:` - * mirror is `active` and names the receiving project. Fails closed on a KV - * error — `validateActions` has no try/catch, and a throw here would - * escape `routeInbound` and retry the delivery instead of dropping the - * reply. - */ -async function isRegisteredDomainSender(fromDomain: string, pin: ReplySenderPin): Promise { - if (!pin.projectId) { - return false; } - const cached = pin.registeredDomains.get(fromDomain); - if (cached !== undefined) { - return cached; - } - const mirror = await readEmailDomainMirror(pin.kv, fromDomain, { cacheTtl: 60 }).catch( - () => null, - ); - const registered = - mirror !== null && mirror.projectId === pin.projectId && mirror.status === 'active'; - pin.registeredDomains.set(fromDomain, registered); - return registered; -} - -function readCounter(raw: string | null): number { - // Mirror packages/proxy/src/email.ts. NaN-poison defense. - if (!raw) { - return 0; - } - const n = parseInt(raw, 10); - return Number.isFinite(n) && n >= 0 ? n : 0; -} - -function monthBucket(now: Date): string { - return `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`; -} - -function minuteBucket(now: Date): string { - return `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, '0')}${String( - now.getUTCDate(), - ).padStart(2, '0')}T${String(now.getUTCHours()).padStart(2, '0')}${String( - now.getUTCMinutes(), - ).padStart(2, '0')}`; -} - -function monthTtlSeconds(now: Date): number { - const endOfMonth = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0); - const seconds = Math.ceil((endOfMonth - now.getTime()) / 1000) + 60 * 60; - return Math.max(60, seconds); -} - -async function getBurstLimit(kv: KVNamespace, projectId: string): Promise { - const raw = await kv.get(`email-burst-limit:${projectId}`, { cacheTtl: 60 }); - if (raw) { - const n = parseInt(raw, 10); - if (Number.isFinite(n) && n > 0) { - return n; - } - } - return 10; -} - -async function getMonthlyLimit(kv: KVNamespace, projectId: string): Promise { - const raw = await kv.get(`email-limit:${projectId}`, { cacheTtl: 60 }); - if (raw) { - const n = parseInt(raw, 10); - if (Number.isFinite(n) && n > 0) { - return n; - } + if (pin.customDomain) { + return true; } - return 200; + return lower.slice(0, at).split('+')[0] === pin.slug; } -/** - * Per-message context derived ONCE in `routeInbound` and threaded through - * `enactActions` so each forward/reply gets the same project guards as - * `/email/send` (allowlist, suspend kill-switch, burst, monthly quotas). - * - * The counters are mutated as actions are enacted so a message that - * forwards to two addresses charges quota for two — matching the - * outbound semantics. - */ interface OutboundGate { - receiptId?: string; - /** undefined when routing has no projectId; gate is then closed. */ - projectId: string | undefined; - /** Relay lane (custom-domain sends): the recipient allowlist does not gate; quotas still apply. */ - skipAllowlist: boolean; - allowlist: Set; - /** The installation's recipient policy (email-policy.ts); `VERIFIED_ONLY` when the allowlist is skipped. */ - policy: RecipientPolicy; - /** The platform mail domains — the policy never widens delivery to them. */ - platformDomains: ReadonlyArray; - burstKey: string; - burstLimit: number; - burstCurrent: number; - monthKey: string; - monthLimit: number; - monthCurrent: number; - /** Once true, we've hit a quota and refuse any further forward/reply. */ - quotaExhausted: boolean; + projectId: string; + receiptId: string; + transport: 'native' | 'relay'; } export async function routeInbound( message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext, - authoritative?: AuthoritativeEmailRoute, + authoritative: AuthoritativeEmailRoute, ): Promise { - // Every reject reason is prefixed with the zone this router serves, so a - // bounce tells the remote MTA which platform environment refused it. The - // zone is configuration (`EMAIL_SENDER_DOMAIN`), not a constant — see - // `readSenderDomain`. Unlike the outbound send path, a missing value is - // NOT fatal here: nothing about inbound routing depends on the domain, so - // failing closed would drop legitimate mail over a cosmetic var. Fall back - // to a neutral label instead. + // The sender domain labels bounces, but is not needed to route inbound mail. const label = readSenderDomain(env) ?? 'void email'; const to = String(message.to ?? '').toLowerCase(); @@ -713,154 +241,41 @@ export async function routeInbound( return; } - // `noreply@`, `postmaster@`, `abuse@`, … are the domain's own addresses, - // not a tenant's: the bounces and replies to the platform's verification - // mail come back to `noreply@`. `RESERVED_SLUGS` keeps a NEW - // project from claiming one, but the routing blob below is keyed by slug - // and a project registered before those were reserved still has one — it - // would receive that mail. Refused before the KV read so no routing - // entry, whatever its origin, can hand a reserved mailbox to a worker. - // The reject matches what an unclaimed slug gets today: there is no - // platform mailbox behind these addresses either. - if (authoritative?.addressing !== 'custom' && isReservedEmailSlug(slug)) { + // Shared platform addresses remain reserved even when a route exists. + if (authoritative.addressing !== 'custom' && isReservedEmailSlug(slug)) { message.setReject(`${label}: "${sanitize(slug, 64)}" is a reserved platform address`); return; } - let routing: RoutingEntry; - let workerName: string; - if (authoritative) { - if ( - !authoritative.projectId || - !authoritative.workerName || - (authoritative.domain && authoritative.domain.toLowerCase() !== receivedDomain) || - (authoritative.addressing === 'shared' && authoritative.slug.toLowerCase() !== slug) - ) { - message.setReject(`${label}: authoritative route mismatch`); - return; - } - workerName = authoritative.workerName; - routing = { - projectId: authoritative.projectId, - workerName, - version: authoritative.deploymentId, - limits: authoritative.limits, - }; - } else { - // Look up project routing — same KV the HTTP dispatcher uses. - const routingJson = await env.ROUTING.get(slug); - if (!routingJson) { - message.setReject(`${label}: no project found for slug "${sanitize(slug, 64)}"`); - return; - } - - let parsedRouting: unknown; - try { - parsedRouting = JSON.parse(routingJson); - } catch { - message.setReject(`${label}: routing data corrupt`); - return; - } - // `JSON.parse` also succeeds on `null`, on a bare number and on a string, - // none of which carry a suspension marker to read. Every producer of this - // value writes a `JSON.stringify`d object, so there is no legitimate writer - // of a non-object entry — treat one as corrupt rather than reaching for - // `.suspended` on it. Reading it as "not suspended" would disable the - // platform-wide gate for exactly the project whose entry got corrupted, - // which is the same reason the outbound path fails closed on `corrupt`. - if (typeof parsedRouting !== 'object' || parsedRouting === null) { - message.setReject(`${label}: routing data corrupt`); - return; - } - routing = parsedRouting as RoutingEntry; - - // Platform-wide suspension — the marker `packages/dispatch` answers with a - // 429. Checked BEFORE dispatch (and before the email-only kill-switch) so - // a suspended tenant's code never runs on platform CPU, and so a project - // suspended for abuse loses inbound and outbound mail at the same moment - // it loses HTTP. - if (routing.suspended) { - // The marker is declared `string`, but it arrives from KV — a non-string - // value would crash `sanitize`, which turns a suspended project into an - // unhandled handler error instead of a clean refusal. - const reason = typeof routing.suspended === 'string' ? routing.suspended : 'suspended'; - message.setReject( - `${label}: project "${sanitize(slug, 64)}" is suspended (${sanitize(reason, 64)})`, - ); - return; - } - - workerName = routing.workerName ?? ''; - if (!workerName) { - // Static-only deploys (KV/R2 path) don't have a worker — nothing to - // dispatch inbound mail to. - message.setReject(`${label}: project "${sanitize(slug, 64)}" has no worker (static deploy)`); - return; - } - // Declared `string`, but it arrives from KV like `suspended` does. Every - // failure handler below renders the name through `sanitize`, which throws - // on a non-string — a worker that cannot be reached would then surface as - // an unhandled handler error instead of a reject. `buildRoutingJson` only - // ever writes a string, so anything else is corrupt data, refused the same - // way as a non-object blob. - if (typeof workerName !== 'string') { - message.setReject(`${label}: routing data corrupt`); - return; - } - - // `projectId` arrives from KV the same way. The email-only kill-switch - // below is keyed `email-suspended:`, and a template literal - // coerces whatever is there — a number, an object, an empty string — into - // a key that names no real project, so the lookup misses and a suspended - // tenant keeps receiving mail. Every failure handler after dispatch also - // renders the id through `sanitize`, which throws on a non-string. Every - // writer of a worker routing has put a string id in the blob since the - // first one (`buildRoutingJson` types it, and there is no static-deploy - // reading for a missing id the way there is for a missing `workerName`), - // so absent, empty or mistyped is corrupt data and is refused the same - // way — the suspension state cannot be read, so the message must not run. - if (typeof routing.projectId !== 'string' || routing.projectId === '') { - message.setReject(`${label}: routing data corrupt`); - return; - } - - // Email-only suspend kill-switch — the narrower control, set by the admin - // UI to stop mail without taking the whole project offline. Gates inbound - // as well as outbound so a suspended project doesn't keep accepting + - // dispatching mail (which costs CPU and storage on the user worker). - // No cacheTtl: this is an abuse-response control; we eat the extra KV - // get per inbound message so a suspend takes effect immediately - // (subject only to KV's ~near-instant per-colo consistency). - if (await env.ROUTING.get(`email-suspended:${routing.projectId}`)) { - message.setReject(`${label}: project "${sanitize(slug, 64)}" inbound is suspended`); - return; - } + if ( + !authoritative.projectId || + !authoritative.workerName || + !authoritative.deploymentId || + authoritative.domain?.toLowerCase() !== receivedDomain || + (authoritative.addressing === 'shared' && authoritative.slug.toLowerCase() !== slug) + ) { + message.setReject(`${label}: authoritative route mismatch`); + return; } + const workerName = authoritative.workerName; + const projectId = authoritative.projectId; - let stub: EmailEntrypointStub; + let stub: Fetcher; try { // Pass the project's dispatch limits, exactly as the HTTP router does in // `packages/dispatch`. Without them, anyone who can send mail to a // project's address runs that tenant's worker at the namespace default // instead of the CPU/sub-request ceiling the project is configured for. - stub = (routing.limits - ? env.DISPATCH.get(workerName, {}, { limits: routing.limits }) - : env.DISPATCH.get(workerName)) as unknown as EmailEntrypointStub; + stub = ( + authoritative.limits + ? env.DISPATCH.get(workerName, {}, { limits: authoritative.limits }) + : env.DISPATCH.get(workerName) + ) as Fetcher; } catch (e) { console.error(`[email-router] DISPATCH.get(${sanitize(workerName, 320)}) failed:`, e); - if (authoritative) { - throw new Error('email worker temporarily unavailable'); - } - message.setReject(`${label}: project worker unavailable`); - return; + throw new Error('email worker temporarily unavailable'); } - // Note: we can't pre-check `typeof stub.email === 'function'` — RPC stub - // proxies report 'function' for every property access. The actual - // existence check happens at call time, where workerd throws - // `TypeError: The RPC receiver does not implement the method "..."` if - // the user worker doesn't expose it. We catch that below. - // Early size guard — `rawSize` is set by CF before the body streams. // Reject before buffering so a flood of oversized messages can't OOM the // isolate. We still enforce the cap during streaming below in case @@ -870,14 +285,11 @@ export async function routeInbound( return; } - // Serialize to an envelope. Headers go as a plain object (RPC-safe); - // raw is pre-buffered to a Uint8Array so the user worker can re-read it - // (parseEmail consumes the stream — buffering also lets us replay if - // multiple downstream consumers need it). + // Buffer the body and headers into the bounded tenant envelope. let envelope: EmailEnvelope; try { envelope = await buildEnvelope(message); - if (authoritative?.addressing === 'custom') { + if (authoritative.addressing === 'custom') { envelope.viaDomain = receivedDomain; } } catch (e) { @@ -898,98 +310,42 @@ export async function routeInbound( return; } - // Build the outbound gate context BEFORE dispatch so every forward/reply - // recorded by the user handler runs through the same per-project guards - // as `/email/send` (HIGH H1). CF Email Routing destinations are - // account-wide, so without a per-project allowlist any tenant could - // weaponize inbound mail to fan out to addresses verified by another - // project — nullifying the architectural premise that the platform's - // per-project allowlist is the security boundary. - const gate: OutboundGate = { - projectId: routing.projectId, - skipAllowlist: false, - allowlist: new Set(), - policy: VERIFIED_ONLY, - platformDomains: [], - burstKey: '', - burstLimit: 0, - burstCurrent: 0, - monthKey: '', - monthLimit: 0, - monthCurrent: 0, - quotaExhausted: false, - }; + const receiptId = crypto.randomUUID(); + const gate: OutboundGate = { projectId, receiptId, transport: 'native' }; let actions: Array; - const receiptId = crypto.randomUUID(); try { - await recordEmailReceipt(env, receiptId, routing.projectId!, 'received'); + await recordEmailReceipt(env, receiptId, projectId, 'received'); } catch { - if (authoritative) { - throw new Error('email admission temporarily unavailable'); - } - message.setReject(`${label}: email admission unavailable`); - return; + throw new Error('email admission temporarily unavailable'); } try { - const result = await dispatchBoundedEmailToTenant(stub as Fetcher, env, { - projectId: routing.projectId!, - deploymentId: routing.version ?? '', + const result = await dispatchBoundedEmailToTenant(stub, env, { + projectId, + deploymentId: authoritative.deploymentId, envelope, receiptId, }); actions = result.actions; } catch (e) { - await recordEmailReceipt(env, receiptId, routing.projectId!, 'handler_failed').catch(() => {}); - // The thrown value is the tenant's: a handler can throw an Error with any - // message, or any value that crosses RPC. Only a bounded prefix is - // inspected — workerd's own "does not implement" text is well under 320 - // characters — because `receiver does not.*method` backtracks - // quadratically on a long message (measured: 1 MB = 21 s of CPU), and a - // non-Error throw is described by kind, never coerced whole. + await recordEmailReceipt(env, receiptId, projectId, 'handler_failed').catch(() => {}); const msg = e instanceof Error ? e.message.slice(0, 320) : describeUntrusted(e, 320); - if (RPC_METHOD_MISSING.test(msg)) { - console.error( - `[email-router] ${sanitize(workerName, 320)} has no .email() (needs redeploy):`, - sanitize(msg, 320), - ); - message.setReject(`${label}: project has no email handler`); - // We log the dispatch attempt asynchronously even on rejects. - ctx.waitUntil( - logRecv(env, routing.projectId, message, [{ type: 'reject', reason: 'no-handler' }]), - ); - return; - } console.error(`[email-router] dispatch to ${sanitize(workerName, 320)} failed:`, msg); - if (authoritative) { - throw new Error('email handler execution unresolved'); - } - message.setReject(`${label}: project handler error`); - ctx.waitUntil( - logRecv(env, routing.projectId, message, [{ type: 'reject', reason: 'dispatch-error' }]), - ); - return; + throw new Error('email handler execution unresolved'); } try { - await recordEmailReceipt(env, receiptId, routing.projectId!, 'handler_completed'); + await recordEmailReceipt(env, receiptId, projectId, 'handler_completed'); } catch { console.error('[email-router] handler completed but receipt status could not be saved'); - message.setReject(`${label}: email admission unavailable`); return; } - gate.receiptId = receiptId; try { await enactActions(env, message, actions, gate, { - receiptId, - authoritative: !!authoritative, - customDomain: authoritative?.addressing === 'custom', - slug: authoritative?.slug ?? slug, + customDomain: authoritative.addressing === 'custom', + slug: authoritative.slug.toLowerCase(), domain: receivedDomain, - projectId: routing.projectId, - kv: env.ROUTING, - registeredDomains: new Map(), }); } catch { console.error('[email-router] action execution unresolved', receiptId); @@ -999,36 +355,16 @@ export async function routeInbound( // Async log to the metering pipeline. Best-effort. Logged after every // dispatch — including reject-only outcomes — so operators have a // complete audit trail. - ctx.waitUntil(logRecv(env, routing.projectId, message, actions)); + ctx.waitUntil(logRecv(env, projectId, message, actions)); } -/** - * The outcome the `/email/relay` HTTP handler maps onto its response. The - * relay worker answers any non-2xx with `message.setReject`, so every - * refusal below — unrouteable project, suspension, dispatch failure, - * handler reject — collapses to this one bit; the specific reason stays in - * proxy logs and never crosses back to the MTA. - */ +/** The gateway response to a relayed inbound message. */ export interface RelayRouteOutcome { reject: boolean; temporary?: boolean; } -/** - * The relay lane of inbound routing (design doc 0078, "Custom domains on - * Cloudflare"). The message arrived via POST /email/relay from the relay - * worker in the CUSTOMER's account — the index.ts auth branch has already - * proved the relay secret against the domain's mirror and resolved the - * project — so this is the second half of `routeInbound`: the same - * suspension gates, dispatch limits, envelope dispatch, action enaction and - * delivery log, but keyed by the mirror's project instead of a slug parsed - * from the recipient, and enacted on a synthetic message instead of a real - * `ForwardableEmailMessage`. - * - * The framework dispatcher runs in no-prefix mode for the relayed envelope - * (the recipient carries no `+` prefix; see `viaDomain` on the - * envelope). - */ +/** Dispatch a relayed message using the route resolved by the gateway. */ export async function routeRelayed( env: Env, ctx: ExecutionContext, @@ -1036,104 +372,34 @@ export async function routeRelayed( projectId: string; domain: string; envelope: EmailEnvelope; - authoritative?: AuthoritativeEmailRoute; - receiptId?: string; + authoritative: AuthoritativeEmailRoute; + receiptId: string; }, ): Promise { - const { projectId, domain, envelope, authoritative } = input; + const { projectId, domain, envelope, authoritative, receiptId } = input; - let slug: string | null; - let routing: RoutingEntry; - let workerName: string; - if (authoritative) { - if (authoritative.projectId !== projectId || !authoritative.workerName || !authoritative.slug) { - return { reject: true }; - } - slug = authoritative.slug; - workerName = authoritative.workerName; - routing = { - projectId, - workerName, - version: authoritative.deploymentId, - limits: authoritative.limits, - }; - } else { - // The platform lane resolves routing by the slug parsed from the - // recipient; a relayed recipient carries no slug, so resolve the - // project's slug via the `email-slug:` mirror the api writes - // on project create, then read the same routing blob by slug. - slug = await env.ROUTING.get(`email-slug:${projectId}`); - if (!slug) { - console.error(`[email-relay] no slug mirror for project ${sanitize(projectId, 64)}`); - return { reject: true }; - } - const routingJson = await env.ROUTING.get(slug); - if (!routingJson) { - console.error( - `[email-relay] no routing entry for slug ${sanitize(slug, 64)} (project ${sanitize(projectId, 64)})`, - ); - return { reject: true }; - } - let parsedRouting: unknown; - try { - parsedRouting = JSON.parse(routingJson); - } catch { - console.error(`[email-relay] routing data corrupt for slug ${sanitize(slug, 64)}`); - return { reject: true }; - } - // Same corrupt-data rule as the platform lane: every writer of this blob - // emits a `JSON.stringify`d object, so a non-object parse has no - // legitimate writer. - if (typeof parsedRouting !== 'object' || parsedRouting === null) { - console.error(`[email-relay] routing data corrupt for slug ${sanitize(slug, 64)}`); - return { reject: true }; - } - routing = parsedRouting as RoutingEntry; - - // The mirror's projectId is the authenticated identity (the relay secret - // proved it); the routing blob's is data. A disagreement is corrupt data - // — fail closed rather than dispatch one project's mail into another's - // worker. - if (routing.projectId !== projectId) { - console.error( - `[email-relay] routing blob names another project for slug ${sanitize(slug, 64)}`, - ); - return { reject: true }; - } - - // Platform-wide suspension, then the email-only kill-switch — the same - // gates as the platform lane, so a suspended project loses relayed - // inbound at the same moment it loses everything else. - if (routing.suspended) { - console.error(`[email-relay] project ${sanitize(projectId, 64)} is suspended`); - return { reject: true }; - } - workerName = routing.workerName ?? ''; - if (!workerName || typeof workerName !== 'string') { - // Static-only deploys have no worker to dispatch to; a truthy - // non-string is KV-corrupt data. Same refusal either way. - console.error( - `[email-relay] project ${sanitize(projectId, 64)} has no worker (static deploy)`, - ); - return { reject: true }; - } - // No cacheTtl, as on the platform lane: an abuse-response control where - // convergence latency is the whole point. - if (await env.ROUTING.get(`email-suspended:${projectId}`)) { - console.error(`[email-relay] project ${sanitize(projectId, 64)} inbound is suspended`); - return { reject: true }; - } + if ( + authoritative.projectId !== projectId || + !authoritative.workerName || + !authoritative.slug || + authoritative.domain?.toLowerCase() !== domain + ) { + return { reject: true }; } + const slug = authoritative.slug; + const workerName = authoritative.workerName; - let stub: EmailEntrypointStub; + let stub: Fetcher; try { // Same per-project dispatch limits pass-through as the platform lane. - stub = (routing.limits - ? env.DISPATCH.get(workerName, {}, { limits: routing.limits }) - : env.DISPATCH.get(workerName)) as unknown as EmailEntrypointStub; + stub = ( + authoritative.limits + ? env.DISPATCH.get(workerName, {}, { limits: authoritative.limits }) + : env.DISPATCH.get(workerName) + ) as Fetcher; } catch (e) { console.error(`[email-relay] DISPATCH.get(${sanitize(workerName, 320)}) failed:`, e); - return { reject: true, ...(authoritative ? { temporary: true } : {}) }; + return { reject: true, temporary: true }; } // Built before dispatch so the dispatch-failure paths can log the @@ -1142,62 +408,29 @@ export async function routeRelayed( // (the customer account's send_raw with the domain's leased credential). const relayed = createRelayedMessage(env, envelope, { domain, projectId }); - // Unlike the platform lane, the recipient allowlist does not gate these - // actions (design doc 0078, "What changes in the existing rules"): the - // send leaves through the customer's own account, credential, DKIM and - // quota — the reputation at stake is theirs. The burst cap and the kill - // switch still apply. const gate: OutboundGate = { - projectId: projectId, - skipAllowlist: authoritative?.addressing === 'custom' || !authoritative, - allowlist: new Set(), - policy: VERIFIED_ONLY, - platformDomains: [], - burstKey: '', - burstLimit: 0, - burstCurrent: 0, - monthKey: '', - monthLimit: 0, - monthCurrent: 0, - quotaExhausted: false, + projectId, + receiptId, + transport: 'relay', }; let actions: Array; - const receiptId = input.receiptId ?? crypto.randomUUID(); try { - if (!input.receiptId) { - await recordEmailReceipt(env, receiptId, projectId, 'received'); - } - } catch { - return { reject: true, ...(authoritative ? { temporary: true } : {}) }; - } - try { - const result = await dispatchBoundedEmailToTenant(stub as Fetcher, env, { + const result = await dispatchBoundedEmailToTenant(stub, env, { projectId, - deploymentId: routing.version ?? '', + deploymentId: authoritative.deploymentId, envelope, receiptId, }); actions = result.actions; } catch (e) { await recordEmailReceipt(env, receiptId, projectId, 'handler_failed').catch(() => {}); - // Same bounded classification as the platform lane. const msg = e instanceof Error ? e.message.slice(0, 320) : describeUntrusted(e, 320); - if (RPC_METHOD_MISSING.test(msg)) { - console.error( - `[email-relay] ${sanitize(workerName, 320)} has no .email() (needs redeploy):`, - sanitize(msg, 320), - ); - ctx.waitUntil( - logRecv(env, projectId, relayed.message, [{ type: 'reject', reason: 'no-handler' }]), - ); - return { reject: true }; - } console.error(`[email-relay] dispatch to ${sanitize(workerName, 320)} failed:`, msg); ctx.waitUntil( logRecv(env, projectId, relayed.message, [{ type: 'reject', reason: 'dispatch-error' }]), ); - return { reject: true, ...(authoritative ? { temporary: true } : {}) }; + return { reject: true, temporary: true }; } try { @@ -1207,29 +440,11 @@ export async function routeRelayed( return { reject: false }; } - // A relayed forward resubmits the inbound MIME through send_raw. Validate - // every action's transport budget before any earlier action can send. - if ( - envelope.raw.byteLength > MAX_REPLY_BYTES && - actions.some((action) => action.type === 'forward') - ) { - console.error( - '[email-relay] action list dropped: forwarded message exceeds outbound MIME limit', - ); - return { reject: false }; - } - - gate.receiptId = receiptId; try { await enactActions(env, relayed.message, actions, gate, { - receiptId, - authoritative: !!authoritative, - customDomain: authoritative?.addressing === 'custom', + customDomain: authoritative.addressing === 'custom', slug: slug.toLowerCase(), domain, - projectId, - kv: env.ROUTING, - registeredDomains: new Map(), }); } catch { console.error('[email-relay] action execution unresolved', receiptId); @@ -1241,32 +456,7 @@ export async function routeRelayed( return { reject: relayed.rejectedReason() !== null }; } -/** - * A `ForwardableEmailMessage` stand-in for a relayed message. The relay - * lane holds no CF email event — the message arrived over HTTP — so the - * methods enact differently than on the platform lane: - * - * - `setReject` is recorded; the `/email/relay` handler answers non-2xx - * and the relay worker rejects at the SMTP layer with a generic reason. - * - `forward` sends the original MIME bytes, and `__voidRelayReply` (called - * by `enactSanitized` in place of a native `message.reply`) sends the - * recorded reply bytes — both through the CUSTOMER's Cloudflare account - * as REST `send_raw` bearing the domain's leased credential (design doc - * 0078, "Inbound identity": the reply leaves from the customer-domain - * address that received the message, over the REST path). The platform's - * own `send_email` binding cannot carry either: Email Service rejects a - * sender outside the sending account's verified zones, which a - * customer-domain reply — and a forward from the original external - * sender — both are under the PLATFORM's account, so they failed there - * after `/email/relay` had already answered 2xx. The same verified-zone - * rule bars that external sender under the CUSTOMER account too, so a - * forward's send_raw `from` is the envelope recipient (the registered- - * domain address that received the mail); the MIME goes byte-identical - * and the real `From:` header is what the destination sees and replies - * to. A forward's header overrides cannot be merged into the raw MIME - * here and are dropped. - * Every action has already passed `enactActions`' per-project gates. - */ +/** A message stand-in for relayed replies; forwarding requires a native event. */ function createRelayedMessage( env: Env, envelope: EmailEnvelope, @@ -1274,24 +464,11 @@ function createRelayedMessage( ): { message: ForwardableEmailMessage; rejectedReason: () => string | null } { let reason: string | null = null; - // One REST send for both action kinds. Throws on any failure — the enact - // loop's per-action try/catch logs it and the message stays accepted, - // exactly as a failed native forward/reply does on the platform lane. + // Relayed replies use the customer account's Email Sending API. async function sendRaw(from: string, to: string, raw: Uint8Array): Promise { - // The send goes through the account that owns the FROM domain: a - // forward's substituted MAIL FROM is the envelope recipient (on the - // receiving domain), but a reply's from may sit on ANY active domain - // registered to the project (isPermittedReplySender) — and two domains - // of one project can live in different customer accounts. Email - // Service rejects a sender outside the sending account's verified - // zones, so keying the mirror + lease off the receiving domain would - // submit a cross-account reply under the wrong credential and have CF - // reject it. + // The account is selected by the reply sender's verified domain. const senderDomain = from.slice(from.indexOf('@') + 1).toLowerCase(); - // Re-read the mirror at send time (uncached, like the relay auth - // branch): the account id comes from it, and a row revoked or - // re-registered to another project between the auth and this send must - // not push mail into the account the mirror named then. + // A fresh lease checks project ownership at send time. const lease = await leaseEmailDomainCredential(env, senderDomain, relay.projectId); if (!lease) { throw new Error('could not lease the domain credential'); @@ -1316,14 +493,8 @@ function createRelayedMessage( } catch { throw new Error('email sending request failed'); } - // A refused credential evicts the cached lease so the next action - // re-leases. CF's error body is never echoed or logged — it is not ours - // to surface. - if (res.status === 401 || res.status === 403) { - dropEmailDomainLease(senderDomain); - } if (!res.ok) { - throw new Error(`email sending API returned ${res.status}`); + throw new DefinitiveEmailActionError(`email sending API returned ${res.status}`); } let data: unknown = null; try { @@ -1334,17 +505,17 @@ function createRelayedMessage( const success = typeof data === 'object' && data !== null && (data as { success?: unknown }).success === true; if (!success) { - throw new Error('email sending API refused the message'); + throw new DefinitiveEmailActionError('email sending API refused the message'); } // success:true with the one recipient on a failure list is NOT sent — // the same per-recipient read the outbound fork makes. const result = (data as { result?: SendRawResult | null }).result; const target = to.toLowerCase(); if (readSendRawAddressList(result?.permanent_bounces).has(target)) { - throw new Error('recipient permanently bounced'); + throw new DefinitiveEmailActionError('recipient permanently bounced'); } if (readSendRawAddressList(result?.suppressed_recipients).has(target)) { - throw new Error('recipient is on the suppression list'); + throw new DefinitiveEmailActionError('recipient is on the suppression list'); } } @@ -1357,13 +528,8 @@ function createRelayedMessage( setReject(r: string) { reason = r; }, - async forward(to: string, _headers?: Headers) { - // send_raw rejects a MAIL FROM outside the account's verified - // zones, which the original external sender is — submit the - // envelope recipient (the registered-domain address that received - // the mail). The MIME bytes are untouched, so the real From: - // header is what the destination sees and replies to. - await sendRaw(envelope.to, to, envelope.raw); + async forward(_to: string, _headers?: Headers) { + throw new DefinitiveEmailActionError('relayed forward requires a native email event'); }, // The reply channel `enactSanitized` prefers when present. A native // reply needs both the CF email event this lane never had and a genuine @@ -1388,100 +554,6 @@ function envelopeRawStream(bytes: Uint8Array): ReadableStream { }); } -/** - * Read the per-project allowlist + burst/monthly counters once, up-front, - * so `enactActions` can apply the same gates `/email/send` uses without - * reissuing KV reads inside the loop. The counter values mutate as - * actions enact; we write the totals back at the end via - * `commitGateCounters`. `skipAllowlist` (relay lane) skips the allowlist - * read entirely — custom-domain sends are not allowlist-gated. - */ -async function loadOutboundGate( - env: Env, - projectId: string | undefined, - opts?: { skipAllowlist?: boolean; receivedDomain?: string }, -): Promise { - const skipAllowlist = opts?.skipAllowlist ?? false; - if (!projectId) { - // No projectId on the routing entry → can't authorize anything. - return { - projectId: undefined, - skipAllowlist, - allowlist: new Set(), - policy: VERIFIED_ONLY, - platformDomains: [], - burstKey: '', - burstLimit: 0, - burstCurrent: 0, - monthKey: '', - monthLimit: 0, - monthCurrent: 0, - quotaExhausted: true, - }; - } - const now = new Date(); - const burstKey = `email-burst:${projectId}:${minuteBucket(now)}`; - const monthKey = `email-sent:${projectId}:${monthBucket(now)}`; - const [allowlist, policy, burstLimit, monthLimit, burstRaw, monthRaw] = await Promise.all([ - skipAllowlist ? new Set() : readAllowlist(env.ROUTING, projectId), - skipAllowlist ? VERIFIED_ONLY : readRecipientPolicy(env.ROUTING), - getBurstLimit(env.ROUTING, projectId), - getMonthlyLimit(env.ROUTING, projectId), - env.ROUTING.get(burstKey), - env.ROUTING.get(monthKey), - ]); - return { - projectId, - skipAllowlist, - allowlist, - policy, - platformDomains: [ - ...new Set( - [readSenderDomain(env), opts?.receivedDomain].flatMap((domain) => - domain ? [domain.toLowerCase()] : [], - ), - ), - ], - burstKey, - burstLimit, - burstCurrent: readCounter(burstRaw), - monthKey, - monthLimit, - monthCurrent: readCounter(monthRaw), - quotaExhausted: false, - }; -} - -/** - * Persist the post-mutation counters back to KV. Wrapped in per-key - * try/catch — a failed put logs and continues; the design accepts - * overshoot when KV is flaky (mirrors `/email/send`). - */ -async function commitGateCounters(env: Env, gate: OutboundGate): Promise { - if (!gate.projectId) { - return; - } - const now = new Date(); - await Promise.all([ - env.ROUTING.put(gate.monthKey, String(gate.monthCurrent), { - expirationTtl: monthTtlSeconds(now), - }).catch((e) => { - console.error( - `[email-router] monthly counter put failed for ${sanitize(gate.projectId ?? '', 64)}:`, - e, - ); - }), - env.ROUTING.put(gate.burstKey, String(gate.burstCurrent), { - expirationTtl: 5 * 60, - }).catch((e) => { - console.error( - `[email-router] burst counter put failed for ${sanitize(gate.projectId ?? '', 64)}:`, - e, - ); - }), - ]); -} - async function logRecv( env: Env, projectId: string | undefined, @@ -1537,13 +609,8 @@ async function buildEnvelope(message: ForwardableEmailMessage): Promise = Object.fromEntries(entries); return { from: String(message.from ?? ''), @@ -1598,19 +665,17 @@ type SanitizedAction = | { type: 'forward'; to: string; headers?: Headers } | { type: 'reply'; from: string; to: string; raw: Uint8Array }; +class DefinitiveEmailActionError extends Error {} + /** * Two-phase action enaction. * * **Phase A — validation (this fn).** Walk the action array, validate * each action shape end-to-end, including header construction (via * `new Headers(...)`, which throws on CRLF / NUL / unsafe chars). - * Build a sanitized list. Drop INVALID actions, but if header - * construction throws on any forward/reply we DROP THE ENTIRE LIST - * (return `null`) — the message is still accepted by CF, but no - * side effects fire. Rationale: header validation throwing implies - * the user handler tried to inject SMTP headers; partially enacting - * the rest of the list (e.g. firing a reply) is a worse failure mode - * than dropping it all and logging. + * Build a sanitized list. Any invalid action drops the entire list before + * side effects fire. The message remains accepted by Cloudflare, while the + * receipt records that its actions were rejected. * * **Phase B — enaction (`enactSanitized`).** Walks the validated list, * performs side effects. Each forward/reply still has its own @@ -1624,10 +689,7 @@ async function validateActions( actions: Array, replySender: ReplySenderPin, ): Promise | null> { - // Before the loop allocates anything. `out` is not even built yet: the - // per-entry work below (address regex, `new Headers()`, `sanitize()` on - // every drop log) is what an over-long list is buying, and it is bought in - // the shared proxy isolate ahead of any quota gate. + // Bound validation work before walking tenant actions. if (actions.length > MAX_ACTIONS) { console.error( `[email-router] action list dropped: ${actions.length} actions returned (max ${MAX_ACTIONS})`, @@ -1642,7 +704,7 @@ async function validateActions( // Never `String(action)` here: a string is bounded by `sanitize`, but a // BigInt's decimal conversion is not — see `describeUntrusted`. console.error(`[email-router] dropping non-object action: ${describeUntrusted(action, 320)}`); - continue; + return null; } if (action.type === 'reject') { // CRLF / control chars in the reason would inject into the SMTP DSN @@ -1661,7 +723,7 @@ async function validateActions( console.error( `[email-router] forward dropped: invalid "to" address ${logAddress(action.to)}`, ); - continue; + return null; } let headers: Headers | undefined; if (action.headers) { @@ -1671,11 +733,7 @@ async function validateActions( try { headers = new Headers(action.headers); } catch (e) { - // Header construction throws on CRLF / NUL / unsafe chars. We - // can't safely partial-enact: a forward earlier in the list - // may already have fired by the time we reach the bad headers - // (under the old single-pass impl). Pre-validate the entire - // list and drop everything if any header construction throws. + // Reject the list before any action can have side effects. console.error( `[email-router] action list dropped: forward headers invalid:`, e instanceof Error ? sanitize(e.message, 320) : sanitize(String(e), 320), @@ -1689,17 +747,14 @@ async function validateActions( console.error( `[email-router] reply dropped: invalid address (from=${logAddress(action.from)} to=${logAddress(action.to)})`, ); - continue; + return null; } - // Sender pin (F1). The recipient is gated later by - // `checkOutboundGate`; this gates who we are allowed to BE. Dropped - // here rather than at enaction so an impersonating reply never - // reaches the quota counters. + // Check who the reply claims to be before asking the API to admit it. if (!(await isPermittedReplySender(action.from, replySender))) { console.error( `[email-router] reply dropped: sender not owned by project "${sanitize(replySender.slug, 64)}" (from=${logAddress(action.from)})`, ); - continue; + return null; } // The envelope is pinned; now pin what the recipient will SEE. The // bytes are the tenant's, and `new EmailMessage(from, to, raw)` never @@ -1712,30 +767,30 @@ async function validateActions( console.error( `[email-router] reply dropped: raw is not a Uint8Array (from=${logAddress(action.from)})`, ); - continue; + return null; } // Size before the scan below, which is linear in `raw`. Both bounds // mirror the framework's `reply()`; see the constants for why the - // proxy re-checks them and why an overrun drops only this reply. + // proxy re-checks them. An overrun rejects the entire action batch. const replyBytes = action.raw.byteLength; if (replyBytes > MAX_REPLY_BYTES) { console.error( `[email-router] reply dropped: raw is ${replyBytes} bytes (max ${MAX_REPLY_BYTES}) (from=${logAddress(action.from)})`, ); - continue; + return null; } if (replyBytesUsed + replyBytes > MAX_REPLY_BYTES_TOTAL) { console.error( `[email-router] reply dropped: cumulative reply bytes ${replyBytesUsed + replyBytes} exceed this delivery's budget of ${MAX_REPLY_BYTES_TOTAL} (from=${logAddress(action.from)})`, ); - continue; + return null; } const mimeFrom = readMimeFromAddrSpec(action.raw); if (!mimeFrom.ok || mimeFrom.addrSpec.toLowerCase() !== action.from.toLowerCase()) { console.error( `[email-router] reply dropped: MIME From is not the envelope sender (from=${logAddress(action.from)}, ${mimeFrom.ok ? 'header names another address' : mimeFrom.reason})`, ); - continue; + return null; } replyBytesUsed += replyBytes; out.push({ type: 'reply', from: action.from, to: action.to, raw: action.raw }); @@ -1747,44 +802,13 @@ async function validateActions( console.warn( `[email-router] dropping unknown action type: ${describeUntrusted((action as { type?: unknown }).type, 320)}`, ); + return null; } } return out; } -/** - * Enact each sanitized action on the real ForwardableEmailMessage. - * - * Contract for forward/reply (HIGH H1 — per-project gating): - * Every forward/reply MUST go through the same per-project guards as - * `/email/send`: - * - `gate.allowlist` — recipient lowercased must be in the project's - * verified-destinations allowlist. - * - Burst counter: `gate.burstCurrent + 1 > gate.burstLimit` blocks. - * - Monthly counter: `gate.monthCurrent + 1 > gate.monthLimit` blocks. - * - * CF Email Routing destinations are account-wide. Without these gates, - * inbound mail becomes a fan-out primitive against any tenant's verified - * addresses (not just the receiving project's). The platform's - * per-project allowlist is the security boundary; CF's account-wide - * verified flag is NOT a substitute. See lessons.md - * "Per-project consent on shared third-party verification flags". - * - * Those gates cover the RECIPIENT. The `reply` SENDER is pinned one phase - * earlier, in `validateActions` via `isPermittedReplySender`, so a reply - * impersonating another tenant (or the platform's reserved `noreply`) is - * dropped before it can reach these counters. - * - * Suspend kill-switch is enforced upstream (in `routeInbound` before - * dispatch); a suspended project's inbound mail never reaches this fn, - * so the suspend check happens once and not per-action. - * - * Quota exhaustion DOES NOT change message acceptance. The inbound - * message stays accepted by CF; we just stop firing further forward/reply - * actions and log. Hard rejecting on quota would silently drop legitimate - * inbound mail under a noisy outbound-action handler — worse than letting - * the action drop on the floor with a logged warning. - */ +/** Validate actions, then ask the API to admit each outbound attempt. */ async function enactActions( env: Env, message: ForwardableEmailMessage, @@ -1794,9 +818,10 @@ async function enactActions( ): Promise { const sanitized = await validateActions(actions, replySender); if (sanitized === null) { - // Header construction failed mid-validation — drop the whole list - // (already logged in validateActions). Don't even attempt to commit - // counters since no side effects fired. + // The handler ran, but none of its invalid actions was enacted. + await recordEmailReceipt(env, gate.receiptId, gate.projectId, 'actions_rejected').catch(() => { + console.error('[email-router] could not record rejected actions'); + }); return; } await enactSanitized(env, message, sanitized, gate); @@ -1839,12 +864,10 @@ async function enactSanitized( from, recipients: [to], transport: - action.type === 'forward' - ? gate.skipAllowlist - ? 'send_raw' - : 'native_forward' - : gate.skipAllowlist - ? 'send_raw' + gate.transport === 'relay' + ? 'send_raw' + : action.type === 'forward' + ? 'native_forward' : 'native_reply', receiptId: gate.receiptId, }); @@ -1891,61 +914,26 @@ async function enactSanitized( } catch { console.error('[email-router] provider accepted action but outcome ledger write failed'); } - } catch { + } catch (error) { + const definitive = error instanceof DefinitiveEmailActionError; try { - await finishEmailAttempt(env, admission.operationId, [to], 'outcome_unknown', { - errorCode: 'OUTCOME_UNKNOWN', - }); + await finishEmailAttempt( + env, + admission.operationId, + [to], + definitive ? 'failed' : 'outcome_unknown', + { + errorCode: definitive ? 'UPSTREAM_ERROR' : 'OUTCOME_UNKNOWN', + }, + ); } catch { /* attempt_started remains visible for operator reconciliation */ } - console.error('[email-router] action provider outcome unknown'); + console.error( + definitive + ? '[email-router] action provider refused' + : '[email-router] action provider outcome unknown', + ); } } } - -/** - * Allowlist + quota check for a single forward/reply target. Mutates - * `gate.quotaExhausted` once a quota is hit so we don't keep - * re-evaluating cap math for the rest of the action list. - * - * Returns `false` (and logs) when the action should be dropped. - */ -function checkOutboundGate(gate: OutboundGate, target: string, kind: 'forward' | 'reply'): boolean { - if (gate.quotaExhausted) { - console.error( - `[email-router] ${kind} dropped: project quota exhausted (target=${sanitize(target, 320)})`, - ); - return false; - } - if (!gate.projectId) { - // No projectId on routing → no per-project guard available. Refuse - // rather than fall back to "trust CF's account-wide flag", which is - // exactly the security boundary HIGH H1 closes. - console.error( - `[email-router] ${kind} dropped: no projectId on routing entry (target=${sanitize(target, 320)})`, - ); - return false; - } - const lowered = target.toLowerCase(); - if ( - !gate.skipAllowlist && - !recipientAllowed(gate.policy, gate.allowlist, lowered, gate.platformDomains) - ) { - console.error( - `[email-router] ${kind} dropped: recipient not in project allowlist or recipient policy (target=${sanitize(target, 320)})`, - ); - return false; - } - if (gate.burstCurrent + 1 > gate.burstLimit) { - console.error(`[email-router] ${kind} dropped: burst limit ${gate.burstLimit}/min exceeded`); - gate.quotaExhausted = true; - return false; - } - if (gate.monthCurrent + 1 > gate.monthLimit) { - console.error(`[email-router] ${kind} dropped: monthly limit ${gate.monthLimit} exceeded`); - gate.quotaExhausted = true; - return false; - } - return true; -} diff --git a/platform/packages/proxy/src/email.ts b/platform/packages/proxy/src/email.ts index db836280e..f14d62739 100644 --- a/platform/packages/proxy/src/email.ts +++ b/platform/packages/proxy/src/email.ts @@ -9,13 +9,7 @@ import { finishEmailAttempt, startEmailAttempt, } from './email-admission.ts'; -import { dropEmailDomainLease, leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; -import { - readAllowlist, - readRecipientPolicy, - recipientAllowed, - recipientRefusalMessage, -} from './email-policy.ts'; +import { leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; import type { Env, ProxyEnv } from './types.ts'; const app = new Hono(); @@ -192,20 +186,6 @@ export function strictFromRe(domain: string): RegExp { return re; } -/** - * Valid project slug shape. The api worker writes `email-slug:` - * KV mirror entries; we read them and pin the `from` local-part against - * the value. A poisoned KV (corrupted write, attacker-controlled bypass - * of the api worker) returning e.g. `BADSLUG!` would then be accepted as - * the source-of-truth slug and let `from: badslug!@` through — and - * crucially, the strict-from regex above doesn't allow `!` in the - * local-part, so the comparison would silently fail every future request - * for that project without anyone noticing the bad data. Validate the slug - * shape on read so a bad value surfaces as UPSTREAM_ERROR with a clear - * message instead. - */ -const SLUG_RE = /^[a-z0-9._-]+$/; - /** * Strip CR/LF/NUL/control chars before logging or surfacing to remote MTAs. * @@ -522,78 +502,6 @@ function singleMailboxAddrSpec(value: string): string | null { return /^[\x21-\x7e]+$/.test(addrSpec) ? addrSpec : null; } -/** - * Platform-wide suspension marker. - * - * `routing.suspended` is written into a project's routing blob by - * `applyRoutingSuspension` / `setProjectsRoutingSuspension` in the api - * worker and enforced with a 429 by `packages/dispatch`. Email is the other - * tenant-facing egress path, so it has to honor the same marker: without - * this check a project suspended for abuse keeps sending through the - * platform's own account-level `send_email` binding. The narrower - * `email-suspended:` switch below stays as the email-only - * kill-switch. - * - * No `cacheTtl`, for the same reason as `email-suspended:` — this is an - * abuse-response control where convergence latency is the whole point. - * - * A MISSING routing blob is NOT read as a suspension. The marker is only - * ever written INTO an existing entry, so a project with no routing entry - * has nothing suspended; failing closed on absence would instead break every - * send made before the first routing write. - * - * An UNPARSEABLE blob is a different case and is reported as `corrupt` so - * the caller can fail closed. Every producer of this value - * (`api/src/routing.ts`, `api/src/routes/deploy.ts`, `api/src/index.ts`) - * writes a `JSON.stringify`d object, so there is no legitimate writer of a - * malformed entry and therefore no false positive to trade against. Reading a parse - * failure as "not suspended" would silently disable the platform-wide - * suspension gate for exactly the project whose entry got corrupted. - */ -type RoutingSuspension = - | { kind: 'absent' } - | { kind: 'clear' } - | { kind: 'suspended'; reason: string } - | { kind: 'corrupt' }; - -async function readRoutingSuspension(kv: KVNamespace, slug: string): Promise { - const raw = await kv.get(slug); - if (!raw) { - return { kind: 'absent' }; - } - let parsed: unknown; - try { - parsed = JSON.parse(raw); - } catch { - return { kind: 'corrupt' }; - } - // `JSON.parse('null')` and friends parse cleanly but carry no marker to - // read, and no producer emits them either — treat them as corrupt rather - // than reaching for `.suspended` on a non-object. - if (typeof parsed !== 'object' || parsed === null) { - return { kind: 'corrupt' }; - } - // The marker is read by TRUTHINESS, the same test the two sibling readers - // apply — `packages/dispatch` (`if (routing.suspended)` → 429) and the - // inbound router in `email-router.ts` (truthy → reject). A falsy present - // value (`null`, `false`, `''`, `0`) is "not suspended" to both of them, so - // it is `clear` here too: no writer emits one today (an unsuspend DELETES - // the key), but a future clear that stamps `suspended: null` must not - // brick every send. A TRUTHY value that is not a string has no writer - // either — every producer stamps a non-empty reason string — yet both - // siblings refuse on it, so it is `corrupt` rather than `clear`: the send - // path must not be the one gate that reads a marker the edge and inbound - // paths are blocking on as an open door. - const suspended = (parsed as { suspended?: unknown }).suspended; - if (!suspended) { - return { kind: 'clear' }; - } - if (typeof suspended !== 'string') { - return { kind: 'corrupt' }; - } - return { kind: 'suspended', reason: suspended }; -} - /** * Outbound email send. The framework runtime POSTs: * @@ -610,15 +518,11 @@ async function readRoutingSuspension(kv: KVNamespace, slug: string): Promise` KV) - * 4. Runs burst + monthly outbound quota gates against the *allowed* - * recipient count (denied-by-allowlist sends don't burn quota) - * 5. Calls `env.SEND_EMAIL.send()` per allowed recipient - * 6. Returns a `SendEmailResult`-shaped JSON the framework passes through + * 3. Admits the send against the SQL recipient policy and quota ledger + * 4. Calls `env.SEND_EMAIL.send()` per admitted recipient + * 5. Returns per-recipient outcomes to the framework * - * Quotas + allowlists live exclusively in the proxy. The user worker does - * not have a `send_email` binding. + * The user worker does not have a `send_email` binding. */ app.post('/send', async (context) => { const projectId = context.get('projectId'); @@ -811,13 +715,7 @@ app.post('/send', async (context) => { ); } - // Custom sender domains (design doc 0078, "Custom domains on - // Cloudflare"): a `from` whose domain is NOT the platform sender domain - // belongs to a registered `email_domains` row, not to the shared zone. - // The slug pin and strict regex below only make sense ON `senderDomain`, - // so the paths fork here — after the size and structure gates that apply - // to both. A `from` with no usable domain part falls through to the - // shared-path guards, which refuse it. + // A sender outside the shared platform domain uses the custom-domain path. const fromAt = from.indexOf('@'); const fromDomain = fromAt === -1 ? '' : from.slice(fromAt + 1).toLowerCase(); if (fromDomain !== '' && fromDomain !== senderDomain) { @@ -884,8 +782,7 @@ app.post('/send', async (context) => { // A mismatch here is a request the framework never produces — `buildMime` // renders `From:` from the same `from.email` it posts as the envelope — so // it is refused outright rather than reported per recipient. Runs before - // the suspension and allowlist reads for the same reason as the slug pin: - // no KV work for a request that can never be authorized. The refusal may + // the admission call for the same reason as the slug pin. The refusal may // echo `from`: it is at most `MAX_SENDER_LENGTH` printable-ASCII bytes by // now. const mimeFrom = readMimeFromAddrSpec(raw); @@ -1038,11 +935,10 @@ app.post('/send', async (context) => { } } - // Inline log (analytics-engine wiring TODO). + // Record the per-recipient outcome. logSend(projectId, requestId, deliveries); - // If any recipient failed (allowlist miss OR upstream error), surface as - // a mid-batch failure so callers can retry per-recipient. + // Return each outcome; an unknown provider result must be inspected before retry. const anyFailed = deliveries.some((d) => !d.ok); if (anyFailed) { return context.json({ ok: false, operationId: admission.operationId, deliveries }, 200); @@ -1059,8 +955,7 @@ app.post('/send', async (context) => { }); // ----------------------------------------------------------------------------- -// Custom sender domains — a `/send` fork for `from` domains registered to -// the project (design doc 0078, "Custom domains on Cloudflare"). +// Custom sender domains. // ----------------------------------------------------------------------------- /** @@ -1090,26 +985,7 @@ export function readSendRawAddressList(value: unknown): Set { return out; } -/** - * Custom-domain outbound send. Reached from `/send` when the from-address - * domain is not the platform sender domain. - * - * Authorization is the domain mirror, not the slug pin: the api mirrors - * every `email_domains` row to `email-domain:` in ROUTING KV, and - * the send proceeds only when that mirror maps the domain to the CALLING - * project and the row is `active`. The message then leaves through the - * CUSTOMER's Cloudflare account — `POST - * /accounts/{accountId}/email/sending/send_raw` bearing a credential leased - * from the api (`email-lease.ts`) — so DKIM alignment and the daily quota - * are the customer's own. - * - * The platform's abuse and quota controls apply unchanged and run BEFORE - * the external call: platform-wide routing suspension, the email-only - * kill-switch, and the burst + monthly counters. The one shared-path gate - * deliberately absent is the verified-destination allowlist (decision 6): - * the customer's own Email Sending onboarding lifts Cloudflare's - * verified-destination gate, and the reputation at stake is theirs. - */ +/** Send through the customer's Cloudflare account after project-bound admission. */ async function sendViaCustomDomain( context: Context, projectId: string, @@ -1135,15 +1011,7 @@ async function sendViaCustomDomain( } const fromLower = from.toLowerCase(); - // PostgreSQL domain ownership is checked by the project-bound lease and - // again by admission. A stale ROUTING mirror cannot authorize or deny send. - - // Pin what the recipient will SEE, exactly as the shared path does: the - // MIME `From:` must be the envelope sender. The mirror already bounds the - // domain to this project; this keeps the header from naming a different - // mailbox on it. Runs before the suspension and quota reads for the same - // reason as the shared path's pin: no KV work for a request that can - // never be authorized. + // The MIME From address must match the envelope sender before admission. const mimeFrom = readMimeFromAddrSpec(raw); if (!mimeFrom.ok || mimeFrom.addrSpec.toLowerCase() !== fromLower) { const detail = mimeFrom.ok @@ -1315,12 +1183,8 @@ async function sendViaCustomDomain( } if (cfRes) { if (!cfRes.ok) { - // A refused credential (401/403) evicts the cached lease so the next - // send re-leases; the api marks the row on its own probe path. CF's - // error body is never echoed or logged — it is not ours to surface. - if (cfRes.status === 401 || cfRes.status === 403) { - dropEmailDomainLease(fromDomain); - } + // A fresh credential is leased for every attempt. Provider error + // bodies are not echoed or logged. failure = { code: cfRes.status === 429 ? 'QUOTA_EXCEEDED' : 'UPSTREAM_ERROR', message: `email sending API returned ${cfRes.status}`, @@ -1565,88 +1429,6 @@ function logSend(projectId: string, requestId: string, deliveries: Array` (design doc 0078, "Custom domains on - * Cloudflare"). Written on every row create/update, deleted on row delete; - * the proxy has no database access, so this mirror is its ONLY view of a - * registered custom domain. `relaySecretSha256` is the sha256 (hex) of the - * domain's relay secret — the secret itself never reaches KV. - * - * Read by the `/email/relay` auth branch (index.ts), by the custom-domain - * `/send` fork, and by the reply-sender pin (email-router.ts). The shape is - * a wire contract with the api (`api/src/email/domains.ts`). - */ -export interface EmailDomainMirror { - projectId: string; - status: string; - relaySecretSha256: string; - relayWorkerName: string | null; - accountId: string | null; - zoneId: string | null; - mode: string | null; -} - -/** - * Read the mirror for `domain` (already lowercased by the caller). Returns - * null on absence AND on a malformed entry — the proxy trusts only the - * fields it validates, and a poisoned KV value fails closed like a missing - * one. `cacheTtl` follows the allowlist pattern (~60s per-colo - * convergence); the relay auth branch reads WITHOUT it so a revoked or - * rotated secret stops working at KV speed. - */ -export async function readEmailDomainMirror( - kv: KVNamespace, - domain: string, - options?: { cacheTtl?: number }, -): Promise { - const raw = await kv.get(`email-domain:${domain}`, options); - if (!raw) { - return null; - } - let parsed: unknown; - try { - parsed = JSON.parse(raw); - } catch { - return null; - } - if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) { - return null; - } - const entry = parsed as Record; - if ( - typeof entry.projectId !== 'string' || - entry.projectId === '' || - typeof entry.status !== 'string' || - typeof entry.relaySecretSha256 !== 'string' - ) { - return null; - } - return { - projectId: entry.projectId, - status: entry.status, - relaySecretSha256: entry.relaySecretSha256, - relayWorkerName: typeof entry.relayWorkerName === 'string' ? entry.relayWorkerName : null, - accountId: typeof entry.accountId === 'string' ? entry.accountId : null, - zoneId: typeof entry.zoneId === 'string' ? entry.zoneId : null, - mode: typeof entry.mode === 'string' ? entry.mode : null, - }; -} - -/** - * Defends against poisoned KV values: `parseInt('NaN'|'abc',10)` returns - * NaN, which would (a) make `NaN > limit` false → bypass and (b) write - * literal `"NaN"` back if used in arithmetic. Always coerces to a finite - * non-negative integer, falling back to 0. - */ -function readCounter(raw: string | null): number { - if (!raw) { - return 0; - } - const n = parseInt(raw, 10); - return Number.isFinite(n) && n >= 0 ? n : 0; -} - function base64Decode(b64: string): Uint8Array { // workerd `atob` is fast for body-sized payloads; fall back to manual // decode only when needed. @@ -1658,51 +1440,6 @@ function base64Decode(b64: string): Uint8Array { return out; } -function monthBucket(now: Date): string { - return `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`; -} - -function minuteBucket(now: Date): string { - return `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, '0')}${String( - now.getUTCDate(), - ).padStart(2, '0')}T${String(now.getUTCHours()).padStart(2, '0')}${String( - now.getUTCMinutes(), - ).padStart(2, '0')}`; -} - -/** - * Seconds until shortly after the end of the current UTC month (1 hour - * buffer absorbs late writes around the boundary). KV requires - * `expirationTtl >= 60`. - */ -function monthTtlSeconds(now: Date): number { - const endOfMonth = Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0, 0); - const seconds = Math.ceil((endOfMonth - now.getTime()) / 1000) + 60 * 60; - return Math.max(60, seconds); -} - -async function getBurstLimit(kv: KVNamespace, projectId: string): Promise { - const raw = await kv.get(`email-burst-limit:${projectId}`, { cacheTtl: 60 }); - if (raw) { - const n = parseInt(raw, 10); - if (Number.isFinite(n) && n > 0) { - return n; - } - } - return 10; -} - -async function getMonthlyLimit(kv: KVNamespace, projectId: string): Promise { - const raw = await kv.get(`email-limit:${projectId}`, { cacheTtl: 60 }); - if (raw) { - const n = parseInt(raw, 10); - if (Number.isFinite(n) && n > 0) { - return n; - } - } - return 200; -} - /** * Platform-internal send endpoint. Used by the api worker to dispatch * destination-verification emails: when project A adds an address that diff --git a/platform/packages/proxy/test/unit/email-custom-domain.test.ts b/platform/packages/proxy/test/unit/email-custom-domain.test.ts index 6678b7238..9fae1c37e 100644 --- a/platform/packages/proxy/test/unit/email-custom-domain.test.ts +++ b/platform/packages/proxy/test/unit/email-custom-domain.test.ts @@ -31,7 +31,6 @@ vi.mock('cloudflare:email', () => ({ })); const worker = (await import('../../src/index.ts')).default; -const { clearEmailDomainLeaseCache } = await import('../../src/email-lease.ts'); const JWT_SECRET = 'test-secret-key'; const PROD_DOMAIN = 'mail.void.cloud'; @@ -266,7 +265,6 @@ function kvKeysMatching(kv: MockKv, prefix: string): Array { beforeEach(() => { // The lease cache is module-level — isolate every test from its neighbours. - clearEmailDomainLeaseCache(); vi.spyOn(console, 'error').mockImplementation(() => {}); vi.spyOn(console, 'warn').mockImplementation(() => {}); vi.spyOn(console, 'log').mockImplementation(() => {}); @@ -330,22 +328,6 @@ describe('POST /email/send — custom sender domain', () => { expect(kvKeysMatching(kv, 'email-burst:proj_1:')).toHaveLength(0); }); - it('sends with an oauth_grant lease (accessToken) as the Bearer', async () => { - const kv = customDomainKv(); - const { env, apiFetch } = createMockEnv(kv); - const normalFetch = apiFetch.getMockImplementation()!; - apiFetch.mockImplementation(async (url, init) => - String(url).endsWith('/domain-credential') - ? Response.json({ kind: 'oauth_grant', accessToken: LEASED, accountId: 'acct_customer' }) - : normalFetch(url, init), - ); - const calls = stubCloudflare(); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(200); - const sendHeaders = new Headers(calls[0]?.init.headers); - expect(sendHeaders.get('authorization')).toBe(`Bearer ${LEASED}`); - }); - it('re-leases the domain for each send', async () => { const kv = customDomainKv(); const { env, apiFetch } = createMockEnv(kv); diff --git a/platform/packages/proxy/test/unit/email-policy.test.ts b/platform/packages/proxy/test/unit/email-policy.test.ts deleted file mode 100644 index abce87f02..000000000 --- a/platform/packages/proxy/test/unit/email-policy.test.ts +++ /dev/null @@ -1,159 +0,0 @@ -import { describe, expect, it, vi } from 'vite-plus/test'; -import { - RECIPIENT_POLICY_KEY, - VERIFIED_ONLY, - readAllowlist, - readRecipientPolicy, - recipientAllowed, - recipientRefusalMessage, - type RecipientPolicy, -} from '../../src/email-policy.ts'; - -function kvWith(entries: Record): KVNamespace { - const store = new Map(Object.entries(entries)); - return { - get: async (key: string) => store.get(key) ?? null, - } as unknown as KVNamespace; -} - -const allowlist = new Set(['dev@example.com']); -const domainsPolicy: RecipientPolicy = { mode: 'domains', domains: new Set(['acme.test']) }; -const anyPolicy: RecipientPolicy = { mode: 'any', domains: new Set() }; - -describe('recipientAllowed', () => { - it.each([ - // mode, allowlisted, same-domain, other → expected - ['verified', VERIFIED_ONLY, [true, false, false]], - ['domains', domainsPolicy, [true, true, false]], - ['any', anyPolicy, [true, true, true]], - ] as const)('%s mode decision table', (_mode, policy, expected) => { - expect([ - recipientAllowed(policy, allowlist, 'dev@example.com'), - recipientAllowed(policy, allowlist, 'someone@acme.test'), - recipientAllowed(policy, allowlist, 'someone@other.test'), - ]).toEqual([...expected]); - }); - - it("never widens delivery to the platform's own mail domain — allowlist only there", () => { - const platform = 'mail.example.test'; - for (const policy of [anyPolicy, { mode: 'domains', domains: new Set([platform]) } as const]) { - expect(recipientAllowed(policy, new Set(), `other+tag@${platform}`, [platform])).toBe(false); - // Platform domains are compared case-insensitively on their side. - expect( - recipientAllowed(policy, new Set(), `other+tag@${platform}`, ['MAIL.Example.TEST']), - ).toBe(false); - expect( - recipientAllowed(policy, new Set([`other+tag@${platform}`]), `other+tag@${platform}`, [ - platform, - ]), - ).toBe(true); - } - // Other domains are unaffected by the platform-domain rule. - expect(recipientAllowed(anyPolicy, new Set(), 'x@elsewhere.test', [platform])).toBe(true); - expect(recipientAllowed(anyPolicy, new Set(), `x@${platform}`)).toBe(true); - }); - - it('matches the recipient domain after the LAST @ only', () => { - expect(recipientAllowed(domainsPolicy, new Set(), 'a@b@acme.test')).toBe(true); - expect(recipientAllowed(domainsPolicy, new Set(), 'acme.test')).toBe(false); - expect(recipientAllowed(domainsPolicy, new Set(), '@acme.test')).toBe(false); - expect(recipientAllowed(domainsPolicy, new Set(), 'x@sub.acme.test')).toBe(false); - }); -}); - -describe('recipientRefusalMessage', () => { - it('names the policy only under `domains`', () => { - expect(recipientRefusalMessage(VERIFIED_ONLY, 'x@y.test')).toBe( - "recipient 'x@y.test' is not a verified destination for this project", - ); - expect(recipientRefusalMessage(domainsPolicy, 'x@y.test')).toBe( - "recipient 'x@y.test' is not a verified destination for this project and its domain is not in the platform's recipient policy", - ); - }); -}); - -describe('readRecipientPolicy', () => { - it('reads a `domains` policy and lowercases its entries', async () => { - const policy = await readRecipientPolicy( - kvWith({ - [RECIPIENT_POLICY_KEY]: JSON.stringify({ mode: 'domains', domains: ['Acme.TEST'] }), - }), - ); - expect(policy.mode).toBe('domains'); - expect([...policy.domains]).toEqual(['acme.test']); - }); - - it('reads `any`', async () => { - const policy = await readRecipientPolicy( - kvWith({ [RECIPIENT_POLICY_KEY]: JSON.stringify({ mode: 'any', domains: [] }) }), - ); - expect(policy.mode).toBe('any'); - }); - - it('falls back to verified-only when the KV read rejects', async () => { - const error = vi.spyOn(console, 'error').mockImplementation(() => {}); - const kv = { - get: async () => { - throw new Error('kv unavailable'); - }, - } as unknown as KVNamespace; - await expect(readRecipientPolicy(kv)).resolves.toBe(VERIFIED_ONLY); - expect(error).toHaveBeenCalledWith( - '[email-policy] recipient policy read failed; enforcing verified:', - expect.any(Error), - ); - error.mockRestore(); - }); - - it.each([ - ['absent', undefined], - ['malformed JSON', '{nope'], - ['a JSON array', JSON.stringify(['acme.test'])], - ['null', 'null'], - ['an unknown mode', JSON.stringify({ mode: 'open', domains: [] })], - ['`any` without a list', JSON.stringify({ mode: 'any' })], - ['`any` with a non-array list', JSON.stringify({ mode: 'any', domains: 'corrupt' })], - ['`any` with a non-empty list', JSON.stringify({ mode: 'any', domains: ['acme.test'] })], - ['`domains` without a list', JSON.stringify({ mode: 'domains' })], - ['`domains` with an empty list', JSON.stringify({ mode: 'domains', domains: [] })], - ['`domains` with only non-strings', JSON.stringify({ mode: 'domains', domains: [1, null] })], - [ - '`domains` with a non-string beside a valid entry', - JSON.stringify({ mode: 'domains', domains: ['acme.test', 42] }), - ], - [ - '`domains` over the api cap', - JSON.stringify({ - mode: 'domains', - domains: Array.from({ length: 101 }, (_, i) => `d${i}.test`), - }), - ], - ])('falls back to verified-only when the mirror is %s', async (_label, raw) => { - const policy = await readRecipientPolicy( - kvWith(raw === undefined ? {} : { [RECIPIENT_POLICY_KEY]: raw }), - ); - expect(policy).toBe(VERIFIED_ONLY); - }); -}); - -describe('readAllowlist', () => { - it('lowercases string entries and skips the rest', async () => { - const set = await readAllowlist( - kvWith({ 'email-allowlist:p1': JSON.stringify(['Dev@Example.com', 42, null]) }), - 'p1', - ); - expect([...set]).toEqual(['dev@example.com']); - }); - - it.each([ - ['absent', undefined], - ['not JSON', 'nope'], - ['not an array', JSON.stringify({ dev: true })], - ])('reads as empty when the key is %s', async (_label, raw) => { - const set = await readAllowlist( - kvWith(raw === undefined ? {} : { 'email-allowlist:p1': raw }), - 'p1', - ); - expect(set.size).toBe(0); - }); -}); diff --git a/platform/packages/proxy/test/unit/email-relay.test.ts b/platform/packages/proxy/test/unit/email-relay.test.ts deleted file mode 100644 index 1f8c69c4b..000000000 --- a/platform/packages/proxy/test/unit/email-relay.test.ts +++ /dev/null @@ -1,42 +0,0 @@ -import { describe, expect, it, vi } from 'vite-plus/test'; - -vi.mock('cloudflare:email', () => ({ - EmailMessage: class MockEmailMessage {}, -})); - -const worker = (await import('../../src/index.ts')).default; - -describe('retired proxy email relay endpoint', () => { - it('rejects before reading MIME or invoking a tenant', async () => { - const dispatch = vi.fn(); - const read = vi.fn(); - const body = new ReadableStream( - { - pull(controller) { - read(); - controller.enqueue(new TextEncoder().encode('From: sender@example.com\r\n\r\nsecret')); - controller.close(); - }, - }, - { highWaterMark: 0 }, - ); - const env = { - JWT_SECRET: 'test-secret', - ROUTING: { get: vi.fn(async () => null) }, - DISPATCH: { get: dispatch }, - }; - const response = await worker.fetch( - new Request('https://proxy.void.cloud/email/relay', { - method: 'POST', - body, - duplex: 'half', - headers: { 'content-type': 'message/rfc822' }, - } as RequestInit), - env as never, - {} as ExecutionContext, - ); - expect(response.status).toBe(404); - expect(read).not.toHaveBeenCalled(); - expect(dispatch).not.toHaveBeenCalled(); - }); -}); diff --git a/platform/packages/proxy/test/unit/email-router.test.ts b/platform/packages/proxy/test/unit/email-router.test.ts index fef72b170..e0802ae5f 100644 --- a/platform/packages/proxy/test/unit/email-router.test.ts +++ b/platform/packages/proxy/test/unit/email-router.test.ts @@ -1,30 +1,4 @@ -/** - * Tests for the proxy worker's inbound email router (`email-router.ts`). - * - * Bound as the catch-all CF Email Routing rule on the zone named by the - * `EMAIL_SENDER_DOMAIN` var (`mail.void.cloud` in production, - * `mail.staging.void.cloud` in staging). The router parses `+` - * from the recipient, looks up the project's worker name in `ROUTING` KV, - * dispatches into the user worker via the WfP namespace stub's - * `email(envelope)` RPC method, and enacts the returned action queue on the - * real `ForwardableEmailMessage`. - * - * These tests cover the seams the neighbouring `email.test.ts` doesn't: - * slug parsing, KV lookup misses / corruption, platform suspension, the - * email-only suspend kill-switch, per-project dispatch limits, size caps, - * dispatch error classification, action enaction (terminal-reject, - * declaration-order enaction, address validation, header injection guards), - * the per-project allowlist + quota gate on forward/reply (HIGH H1), and - * the two-phase validate/enact split (HIGH H2). - * - * Patterns mirror `email.test.ts`: in-memory KV mock, vi.fn'd dispatch - * stub, fake `ForwardableEmailMessage`. We never spin up a real worker — - * we exercise `routeInbound` directly with synthetic message objects. - * - * Time is frozen (`toFake: ['Date']` only — real timers still run) so the - * minute/month quota buckets are deterministic instead of racing a bucket - * rollover between seeding KV and reading it back. - */ +/** Inbound router validation and action execution with gateway-resolved routes. */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; // This suite exercises router validation against a fake tenant. The gateway @@ -43,30 +17,36 @@ vi.mock('../../../email-gateway/src/tenant-dispatch.ts', () => ({ return { actions, receiptId: input.receiptId }; }, })); -// The framework's own proxy — the record-time twin of this router's bounds. -// The platform depends on the framework, never the reverse, so the router -// cannot import its numbers; this test is where the two are pinned equal. import { - createMessageProxy, - MAX_FORWARD_HEADER_LENGTH as FRAMEWORK_MAX_FORWARD_HEADER_LENGTH, - MAX_FORWARD_HEADERS as FRAMEWORK_MAX_FORWARD_HEADERS, - MAX_INBOUND_BYTES as FRAMEWORK_MAX_INBOUND_BYTES, - MAX_INBOUND_HEADERS as FRAMEWORK_MAX_INBOUND_HEADERS, - MAX_REJECT_REASON_LENGTH as FRAMEWORK_MAX_REJECT_REASON_LENGTH, -} from '../../../../../packages/void/src/runtime/email/inbound.ts'; -import { validateAddressParts } from '../../../../../packages/void/src/runtime/email/mime.ts'; -import { createInboundTestHarness } from '../../../../../packages/void/src/runtime/email/testing.ts'; -import { - isValidEmailAddress, - MAX_FORWARD_HEADER_LENGTH, - MAX_FORWARD_HEADERS, MAX_INBOUND_BYTES, MAX_INBOUND_HEADERS, - MAX_REJECT_REASON_LENGTH, - routeInbound, + routeInbound as routeInboundWithRoute, + routeRelayed, } from '../../src/email-router.ts'; import type { Env } from '../../src/types.ts'; +async function routeInbound( + message: ForwardableEmailMessage, + env: Env, + ctx: ExecutionContext, + route?: Parameters[3], +) { + const to = String(message.to).toLowerCase(); + return routeInboundWithRoute( + message, + env, + ctx, + route ?? { + projectId: 'p_test', + workerName: 'user-worker', + deploymentId: 'v1', + slug: to.split('@')[0]!.split('+')[0]!, + addressing: 'shared', + domain: to.split('@')[1]!, + }, + ); +} + // ----------------------------------------------------------------------- // Fixtures // ----------------------------------------------------------------------- @@ -312,6 +292,18 @@ function makeEnv(options: MakeEnvOptions = {}) { return Response.json({ ok: true }); } if (path.endsWith('/admit')) { + if (body.kind === 'forward' && body.transport === 'send_raw') { + return Response.json({ + operationId: 'unsupported_forward', + replay: false, + recipients: (body.recipients as Array).map((recipient) => ({ + recipient, + state: 'rejected', + errorCode: 'UNSUPPORTED_ACTION', + providerReference: null, + })), + }); + } const key = body.key as string; const previous = actions.get(key); if (previous) { @@ -347,7 +339,16 @@ function makeEnv(options: MakeEnvOptions = {}) { SEND_EMAIL: { send: vi.fn() }, ...(senderDomain === null ? {} : { EMAIL_SENDER_DOMAIN: senderDomain }), } as unknown as Env; - return { env, kv, emailFn, dispatchGet }; + return { env, kv, emailFn, dispatchGet, apiFetch }; +} + +function apiBodies( + apiFetch: ReturnType, + suffix: string, +): Array> { + return apiFetch.mock.calls + .filter(([url]) => new URL(String(url)).pathname.endsWith(suffix)) + .map(([, init]) => JSON.parse(String((init as RequestInit).body)) as Record); } /** Routing + allowlist seed for the happy outbound-gate path. */ @@ -388,10 +389,10 @@ afterEach(() => { }); // ----------------------------------------------------------------------- -// Slug parsing + KV lookup +// Shared-address parsing // ----------------------------------------------------------------------- -describe('routeInbound — slug parsing + KV lookup', () => { +describe('routeInbound — shared-address parsing', () => { it('rejects when recipient has no slug (bare +tag@…)', async () => { const { env, dispatchGet } = makeEnv(); const { message, rejectCalls } = createFakeMessage({ to: `+orphan@${PROD_DOMAIN}` }); @@ -402,185 +403,6 @@ describe('routeInbound — slug parsing + KV lookup', () => { expect(dispatchGet).not.toHaveBeenCalled(); }); - it('rejects when slug is missing in ROUTING KV', async () => { - const { env, dispatchGet } = makeEnv(); - const { message, rejectCalls } = createFakeMessage({ to: `unknown+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('no project found'); - expect(rejectCalls[0]).toContain('unknown'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - it('rejects when routing JSON is corrupt', async () => { - const { env } = makeEnv({ kvSeed: { myslug: '{this is not json' } }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('routing data corrupt'); - }); - - // `JSON.parse` succeeds on `null`, on a bare number and on a string, none of - // which carry a suspension marker to read. Reaching for `.suspended` on - // `null` throws out of the handler, and a non-string marker crashes the - // reject formatter. Both are the same defect as the outbound `corrupt` - // case: the suspension state is unknown, so the message must be refused. - it('rejects a routing blob that parses to null', async () => { - const { env, dispatchGet } = makeEnv({ kvSeed: { myslug: 'null' } }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('routing data corrupt'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - it('rejects a routing blob that parses to a non-object', async () => { - const { env, dispatchGet } = makeEnv({ kvSeed: { myslug: '42' } }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('routing data corrupt'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - it('rejects a non-string suspension marker instead of crashing the formatter', async () => { - const { env, dispatchGet } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ workerName: 'w_test', projectId: 'p_test', suspended: 1 }), - }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('suspended'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - it('rejects when routing.workerName is missing (static deploy)', async () => { - const { env, dispatchGet } = makeEnv({ - kvSeed: { myslug: JSON.stringify({ projectId: 'p_test' }) }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('no worker (static deploy)'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - // `workerName` is declared `string` but arrives from KV, exactly like - // `suspended` above. A truthy non-string passed the `!workerName` check and - // reached `DISPATCH.get`; every failure handler after that point renders - // the name through `sanitize`, whose `.slice`/`.replace` throw on a - // non-string — so a worker that could not be reached surfaced as an - // unhandled handler error instead of a reject. No producer writes a - // non-string name (`buildRoutingJson` types it), so it is corrupt data. - it.each([ - ['a number', 42], - ['an object', {}], - ['a boolean', true], - ['an array', ['user-worker']], - ])('rejects a routing blob whose workerName is %s as corrupt', async (_kind, workerName) => { - const { env, dispatchGet } = makeEnv({ - kvSeed: { myslug: JSON.stringify({ workerName, projectId: 'p_test' }) }, - // The realistic failure: a stub for a name no worker has throws at - // call time, and the catch block is what used to crash. - emailThrow: new Error('Worker not found'), - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await expect(routeInbound(message, env, ctx)).resolves.toBeUndefined(); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('routing data corrupt'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - it('an empty-string workerName still reads as a static deploy', async () => { - const { env, dispatchGet } = makeEnv({ - kvSeed: { myslug: JSON.stringify({ workerName: '', projectId: 'p_test' }) }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('no worker (static deploy)'); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - // `projectId` is the other KV-sourced field the router keys a control on. - // The email-only kill-switch is `email-suspended:`, built with a - // template literal: `42` becomes `email-suspended:42`, `{}` becomes - // `email-suspended:[object Object]`, `''` becomes `email-suspended:` — keys - // no writer has ever set — so the lookup missed and a project suspended - // under its real id kept receiving mail. A number also reaches `sanitize` - // from the gate-load and counter-put failure handlers, where `.slice` - // throws inside a catch. Every worker routing has carried a string id since - // the first writer, so absent / null / empty / mistyped is corrupt data: - // the suspension state cannot be read, and the message must not run. - it.each([ - ['a number', 42], - ['an object', {}], - ['a boolean', true], - ['an array', ['p_test']], - ['an empty string', ''], - ['null', null], - ['absent', undefined], - ])('rejects a routing blob whose projectId is %s as corrupt', async (_kind, projectId) => { - const { env, kv, emailFn, dispatchGet } = makeEnv({ - kvSeed: { - // `JSON.stringify` drops an `undefined` value, so that row seeds a - // blob with no `projectId` key at all. - myslug: JSON.stringify({ workerName: 'user-worker', projectId }), - // The real project IS suspended under its real id. Before the guard - // the coerced key missed this row and the message was dispatched. - 'email-suspended:p_test': '2026-04-29T00:00:00Z', - }, - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, rejectCalls, forwardCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx, waited } = createCtx(); - await expect(routeInbound(message, env, ctx)).resolves.toBeUndefined(); - expect(rejectCalls).toEqual([`${PROD_DOMAIN}: routing data corrupt`]); - // No suspension lookup was even attempted on a key built from the bad - // value — the guard sits in front of it. - const suspensionLookups = kv.get.mock.calls - .map((call) => call[0]) - .filter((key) => key.startsWith('email-suspended:')); - expect(suspensionLookups).toEqual([]); - expect(dispatchGet).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(0); - // Refused before dispatch, so nothing is scheduled for log-recv either. - expect(waited).toHaveLength(0); - }); - - it('a string projectId reaches the email-only suspension lookup', async () => { - const { env, kv, emailFn, dispatchGet } = makeEnv({ - kvSeed: { - myslug: DEFAULT_ROUTING, - 'email-suspended:p_test': '2026-04-29T00:00:00Z', - }, - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, rejectCalls, forwardCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(kv.get).toHaveBeenCalledWith('email-suspended:p_test'); - expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project "myslug" inbound is suspended`]); - expect(dispatchGet).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(0); - }); - it('routes a tag-less recipient (whole local-part is the slug)', async () => { const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); @@ -593,7 +415,7 @@ describe('routeInbound — slug parsing + KV lookup', () => { expect(envelope.to).toBe(`myslug@${PROD_DOMAIN}`); }); - it('uppercase recipients are lowercased before the slug lookup', async () => { + it('uppercase recipients are lowercased before dispatch', async () => { const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `MySlug+Tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); @@ -604,257 +426,54 @@ describe('routeInbound — slug parsing + KV lookup', () => { }); // ----------------------------------------------------------------------- -// The mail zone is CONFIGURATION, not a baked-in constant. -// -// Re-land contract change: `EMAIL_SENDER_DOMAIN` names the zone. The -// inbound router uses it only as the bounce LABEL, and deliberately does -// NOT fail closed when it's absent — nothing about routing depends on the -// domain, so dropping legitimate mail over a cosmetic var would be worse. -// ----------------------------------------------------------------------- - -describe('routeInbound — sender domain is configuration, not a constant', () => { - it('prefixes reject reasons with the configured production zone', async () => { - const { env } = makeEnv({ senderDomain: PROD_DOMAIN }); - const { message, rejectCalls } = createFakeMessage({ to: `unknown@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls[0]).toMatch(new RegExp(`^${PROD_DOMAIN.replace(/\./g, '\\.')}: `)); - }); - - it('prefixes reject reasons with the configured staging zone', async () => { - const { env } = makeEnv({ senderDomain: STAGING_DOMAIN }); - const { message, rejectCalls } = createFakeMessage({ to: `unknown@${STAGING_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls[0]).toMatch(new RegExp(`^${STAGING_DOMAIN.replace(/\./g, '\\.')}: `)); - // No baked-in production domain leaks into a staging bounce. - expect(rejectCalls[0]).not.toContain(`${PROD_DOMAIN}:`); - }); - - it('falls back to a neutral label when the var is missing — and still routes', async () => { - const { env, emailFn } = makeEnv({ - senderDomain: null, - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [], - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - // Deliberately NOT fail-closed: inbound routing doesn't depend on the - // zone name, so a missing var must not drop legitimate mail. - expect(rejectCalls).toHaveLength(0); - expect(emailFn).toHaveBeenCalledTimes(1); - }); - - it('uses the neutral label (never a baked-in domain) in bounces when unset', async () => { - const { env } = makeEnv({ senderDomain: null }); - const { message, rejectCalls } = createFakeMessage({ to: `unknown@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls[0]).toMatch(/^void email: /); - expect(rejectCalls[0]).not.toContain(PROD_DOMAIN); - }); - - it('treats a blank sender domain as unset', async () => { - const { env } = makeEnv({ senderDomain: ' ' }); - const { message, rejectCalls } = createFakeMessage({ to: `unknown@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls[0]).toMatch(/^void email: /); - }); -}); - -// ----------------------------------------------------------------------- -// Platform suspension (`routing.suspended`) — NEW in the re-land. -// -// The same marker `applyRoutingSuspension` writes and `packages/dispatch` -// answers with a 429. Running a suspended tenant's code on platform CPU -// is exactly what suspension exists to stop, so inbound mail must honour -// it too — and it is a SEPARATE control from `email-suspended:`. +// Gateway-resolved routing and delivery limits. // ----------------------------------------------------------------------- -describe('routeInbound — platform suspension via routing.suspended', () => { - const SUSPENDED_ROUTING = JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', - suspended: 'abuse', - }); - - it('rejects and never dispatches when routing.suspended is set', async () => { - const { env, emailFn, dispatchGet } = makeEnv({ - kvSeed: { myslug: SUSPENDED_ROUTING }, - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, rejectCalls, forwardCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('is suspended'); - expect(rejectCalls[0]).toContain('abuse'); - // The tenant's worker must not be resolved at all, let alone run. - expect(dispatchGet).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(0); - }); - - it('platform suspension alone is enough — no email-suspended key needed', async () => { - const { env, kv, dispatchGet } = makeEnv({ kvSeed: { myslug: SUSPENDED_ROUTING } }); +describe('routeInbound — authoritative routing', () => { + it('rejects a route for another domain before dispatch', async () => { + const { env, dispatchGet } = makeEnv(); const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(kv.store.has('email-suspended:p_test')).toBe(false); - expect(rejectCalls).toHaveLength(1); - expect(dispatchGet).not.toHaveBeenCalled(); - }); - - it('email-only suspension alone is enough — no routing.suspended needed', async () => { - const { env, emailFn, dispatchGet } = makeEnv({ - kvSeed: { - myslug: DEFAULT_ROUTING, - 'email-suspended:p_test': '2026-04-29T00:00:00Z', - }, + await routeInbound(message, env, ctx, { + projectId: 'p_test', + workerName: 'user-worker', + deploymentId: 'v1', + slug: 'myslug', + addressing: 'shared', + domain: 'other.example.com', }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('inbound is suspended'); + expect(rejectCalls[0]).toContain('authoritative route mismatch'); expect(dispatchGet).not.toHaveBeenCalled(); - expect(emailFn).not.toHaveBeenCalled(); - }); - - it('platform suspension takes precedence when BOTH switches are set', async () => { - const { env } = makeEnv({ - kvSeed: { - myslug: SUSPENDED_ROUTING, - 'email-suspended:p_test': '1', - }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - // The platform-suspension bounce, not the email-only one. - expect(rejectCalls[0]).toContain('abuse'); - expect(rejectCalls[0]).not.toContain('inbound is suspended'); - }); - - it('platform suspension outranks the static-deploy check', async () => { - const { env } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ projectId: 'p_test', suspended: 'abuse' }), - }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls[0]).toContain('is suspended'); - expect(rejectCalls[0]).not.toContain('static deploy'); - }); - - it('sanitizes a control-char suspension reason before it reaches the MTA', async () => { - const { env } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', - suspended: 'abuse\r\nX-Inject: y\x00', - }), - }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - // oxlint-disable-next-line no-control-regex - expect(rejectCalls[0]).not.toMatch(new RegExp('[\\r\\n\\u0000]')); - }); - - it('a falsy/absent suspended field does not block routing', async () => { - const { env, emailFn } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ workerName: 'user-worker', projectId: 'p_test', suspended: '' }), - }, - emailReturn: [], - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(0); - expect(emailFn).toHaveBeenCalledTimes(1); }); -}); - -// ----------------------------------------------------------------------- -// Per-project dispatch limits — NEW in the re-land. -// -// Inbound mail dispatches into the same tenant worker as HTTP, so it has -// to pass the same `{ limits }` `packages/dispatch` passes. Without it, -// anyone who can send mail to a project's address runs that tenant's -// worker at the namespace default instead of its configured ceiling. -// ----------------------------------------------------------------------- -describe('routeInbound — per-project dispatch limits', () => { - it('passes routing.limits through to DISPATCH.get as the third argument', async () => { - const limits = { cpuMs: 1234, subRequests: 60 }; - const { env, emailFn, dispatchGet } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ workerName: 'user-worker', projectId: 'p_test', limits }), - }, - emailReturn: [], - }); - const { message } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); + it('passes the resolved route limits to tenant dispatch', async () => { + const { env, dispatchGet } = makeEnv({ emailReturn: [] }); + const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(dispatchGet).toHaveBeenCalledTimes(1); - const call = dispatchGet.mock.calls[0] as [string, unknown, unknown]; - expect(call[0]).toBe('user-worker'); - expect(call[1]).toEqual({}); - // The point of the case: the limits object itself, not just that a - // dispatch happened. - expect(call[2]).toEqual({ limits }); - expect(emailFn).toHaveBeenCalledTimes(1); - }); - - it('does not fabricate a limits object when routing carries none', async () => { - const { env, emailFn, dispatchGet } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [], + const limits = { cpuMs: 1000 }; + await routeInbound(message, env, ctx, { + projectId: 'p_test', + workerName: 'user-worker', + deploymentId: 'v1', + slug: 'myslug', + addressing: 'shared', + domain: PROD_DOMAIN, + limits, }); - const { message } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(dispatchGet).toHaveBeenCalledTimes(1); - // Exactly one argument — no `{ limits: undefined }` handed to the - // namespace, which is not the same thing as "no limits". - expect(dispatchGet.mock.calls[0]).toEqual(['user-worker']); - expect(emailFn).toHaveBeenCalledTimes(1); + expect(dispatchGet).toHaveBeenCalledWith('user-worker', {}, { limits }); }); - it('a suspended project never reaches DISPATCH.get, limits or not', async () => { - const { env, dispatchGet } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', - limits: { cpuMs: 50 }, - suspended: 'abuse', - }), - }, - }); + it('leaves a failed tenant dispatch unresolved for the gateway', async () => { + const { env } = makeEnv({ emailThrow: new Error('boom') }); const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(dispatchGet).not.toHaveBeenCalled(); + const { ctx, waited } = createCtx(); + await expect(routeInbound(message, env, ctx)).rejects.toThrow( + 'email handler execution unresolved', + ); + expect(waited).toHaveLength(0); }); }); -// ----------------------------------------------------------------------- -// Size guards -// ----------------------------------------------------------------------- - describe('routeInbound — message size guards', () => { it('rejects messages exceeding rawSize > 10MB before streaming', async () => { const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING } }); @@ -979,146 +598,32 @@ describe('routeInbound — inbound header count cap', () => { // Dispatch result handling // ----------------------------------------------------------------------- -describe('routeInbound — dispatch result handling', () => { - it('rejects an undefined action response', async () => { - const { env, emailFn } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: undefined, +describe('routeInbound — action enaction', () => { + it('drops the WHOLE list when a tenant returns more than 100 actions', async () => { + // The tenant worker is not trusted to have capped its own queue: on WfP + // it can ship any WorkerEntrypoint whose email() returns any array. The + // list is walked HERE, in the shared proxy isolate, before any quota gate + // has charged for it — so the count is checked before the loop. + const { env, kv } = makeEnv({ + kvSeed: withAllowlist(['admin@example.com']), + emailReturn: Array.from({ length: 101 }, () => ({ + type: 'forward', + to: 'admin@example.com', + })), }); - const { message, rejectCalls, forwardCalls, replyCalls } = createFakeMessage({ + const { message, forwardCalls, replyCalls, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}`, }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - expect(emailFn).toHaveBeenCalled(); - expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project handler error`]); expect(forwardCalls).toHaveLength(0); expect(replyCalls).toHaveLength(0); - }); - - it('rejects a null action response', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: null, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project handler error`]); - }); - - it('rejects a non-array action response', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: { actions: [] }, - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toEqual([`${PROD_DOMAIN}: project handler error`]); - }); - - it('classifies workerd "does not implement the method" as no-handler reject', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailThrow: new TypeError('The RPC receiver does not implement the method "email"'), - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('no email handler'); - }); - - it('inspects only a bounded prefix of a thrown message: a 1 MB one classifies in milliseconds', async () => { - // `receiver does not.*method` backtracks quadratically when the message - // repeats the prefix without the suffix — 1 MB was 21 s of CPU on the - // whole string. The prefix keeps workerd's own text recognizable. - const filler = 'receiver does not '.repeat(60_000); - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailThrow: new Error(filler), - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const t0 = performance.now(); - await routeInbound(message, env, ctx); - expect(performance.now() - t0).toBeLessThan(500); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('project handler error'); - }); - - it('never coerces a non-Error throw whole: a 30 MB Uint8Array is described by kind', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailThrow: new Uint8Array(30 * 1024 * 1024), - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - const before = process.memoryUsage().heapUsed; - const t0 = performance.now(); - await routeInbound(message, env, ctx); - expect(performance.now() - t0).toBeLessThan(500); - expect(process.memoryUsage().heapUsed - before).toBeLessThan(64 * 1024 * 1024); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('project handler error'); - }); - - it('classifies other dispatch errors as project handler error', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailThrow: new Error('something else'), - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('project handler error'); - }); - - it('rejects when DISPATCH.get itself throws', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - dispatchGetThrow: new Error('namespace unavailable'), - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toHaveLength(1); - expect(rejectCalls[0]).toContain('worker unavailable'); - }); -}); - -// ----------------------------------------------------------------------- -// Action enaction -// ----------------------------------------------------------------------- - -describe('routeInbound — action enaction', () => { - it('drops the WHOLE list when a tenant returns more than 100 actions', async () => { - // The tenant worker is not trusted to have capped its own queue: on WfP - // it can ship any WorkerEntrypoint whose email() returns any array. The - // list is walked HERE, in the shared proxy isolate, before any quota gate - // has charged for it — so the count is checked before the loop. - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: Array.from({ length: 101 }, () => ({ - type: 'forward', - to: 'admin@example.com', - })), - }); - const { message, forwardCalls, replyCalls, rejectCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(replyCalls).toHaveLength(0); - // Dropping the list is not a bounce — CF still accepted the message. - expect(rejectCalls).toHaveLength(0); - // Nothing was charged: the list never reached the gate. - expect(kv.writes.filter((w) => w.key.startsWith('email-sent:'))).toHaveLength(0); - expect(kv.writes.filter((w) => w.key.startsWith('email-burst:'))).toHaveLength(0); - expect(errorSpy).toHaveBeenCalled(); + // Dropping the list is not a bounce — CF still accepted the message. + expect(rejectCalls).toHaveLength(0); + // Nothing was charged: the list never reached the gate. + expect(kv.writes.filter((w) => w.key.startsWith('email-sent:'))).toHaveLength(0); + expect(kv.writes.filter((w) => w.key.startsWith('email-burst:'))).toHaveLength(0); + expect(errorSpy).toHaveBeenCalled(); }); it('enacts a list of exactly 100 actions', async () => { @@ -1141,127 +646,6 @@ describe('routeInbound — action enaction', () => { expect(forwardCalls).toHaveLength(100); }); - it('drops a forward whose `to` is a megabyte long', async () => { - // The address matches VALID_ADDRESS_RE and is IN the allowlist, so - // nothing downstream would have stopped it: the only thing standing - // between a 1 MiB string and the address regex is the length check. - const hugeTo = `${'a'.repeat(1024 * 1024)}@example.com`; - const { env } = makeEnv({ - kvSeed: withAllowlist([hugeTo, 'admin@example.com']), - emailReturn: [{ type: 'forward', to: hugeTo }], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalled(); - }); - - it('drops the WHOLE list when a forward carries too many headers', async () => { - // Same response as header construction throwing: an oversized bag says - // the handler is hostile, and partially enacting its list is worse. - const headers: Record = {}; - for (let i = 0; i < 33; i++) { - headers[`X-Void-${i}`] = 'v'; - } - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'ops@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com', headers }, - { type: 'forward', to: 'ops@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalled(); - }); - - it('drops the WHOLE list when a forward header value is over-long', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'forward', - to: 'admin@example.com', - headers: { 'X-Void-Tag': 'v'.repeat(1025) }, - }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalled(); - }); - - it('drops the WHOLE list when forward headers is not a plain object, before enumerating it', async () => { - // A tenant can return anything as `headers`. `Object.entries` walks one - // own property PER ELEMENT of a string, a `String`, an Array or a typed - // array (~100 B each — measured OOM at a 1.5 MiB string under a 128 MB - // heap), and `for…in` / `Object.keys` are no better: V8 builds the whole - // key set before the first iteration. The old `new Headers(x)` threw in - // O(1) on every one of these shapes, so the shape check has to be what - // stops them, and it has to fire BEFORE the count — the count is what - // enumerates. The log line pins which branch fired. - const shapes: Array<[string, unknown]> = [ - ['string', 'a'.repeat(64)], - ['String wrapper', new String('a'.repeat(64))], - ['array of pairs', [['X-Void-Tag', 'v']]], - ['typed array', new Uint8Array(64)], - ]; - for (const [label, headers] of shapes) { - errorSpy.mockClear(); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'ops@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com', headers }, - { type: 'forward', to: 'ops@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls, label).toHaveLength(0); - expect(errorSpy, label).toHaveBeenCalledWith( - expect.stringContaining('forward headers is not a plain object'), - ); - } - }); - - it('drops the WHOLE list when a forward header VALUE is not a string', async () => { - // The bag is a plain object (passes the shape check), but a VALUE crossed - // RPC as an Array / typed array / number. `typeof value === 'string'` - // skipped the length bound, and `new Headers({ x: })` does NOT - // throw — it coerces with `String()`, joining an Array into one giant - // comma-separated value ~30x its wire size (a Date-filled Array OOMs a - // 128 MB isolate from a ~4 MiB RPC payload). So an RPC-sized nested value - // evaded the 1024-char bound entirely. Every value must be a string. - const shapes: Array<[string, unknown]> = [ - ['array of strings', new Array(8).fill('a')], - ['nested array', [new Array(4).fill('a')]], - ['typed array', new Uint8Array(8).fill(255)], - ['number', 12345], - ]; - for (const [label, value] of shapes) { - errorSpy.mockClear(); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com', headers: { 'X-Void-Tag': value } }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls, label).toHaveLength(0); - expect(errorSpy, label).toHaveBeenCalledWith( - expect.stringContaining('value is not a string'), - ); - } - }); - it('reject is terminal: forward and reply after a reject do NOT fire', async () => { const { env } = makeEnv({ kvSeed: withAllowlist(), @@ -1349,26 +733,8 @@ describe('routeInbound — action enaction', () => { ]); }); - it('a reject after a successful forward preserves the earlier submission', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com' }, - { type: 'reject', reason: 'done' }, - ], - }); - const { message, forwardCalls, rejectCalls, order } = createFakeMessage({ - to: `myslug@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(order).toEqual(['forward:admin@example.com', 'reject:done']); - expect(forwardCalls).toHaveLength(1); - expect(rejectCalls).toEqual(['done']); - }); - - it('forward with invalid `to` is dropped with console.error', async () => { - const { env } = makeEnv({ + it('rejects a whole action list with an invalid forward address', async () => { + const { env, apiFetch } = makeEnv({ kvSeed: withAllowlist(), emailReturn: [ { type: 'forward', to: 'not-an-email' }, @@ -1380,10 +746,9 @@ describe('routeInbound — action enaction', () => { const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - // Only the valid one fires. - expect(forwardCalls).toHaveLength(1); - expect(forwardCalls[0]?.to).toBe('admin@example.com'); + expect(forwardCalls).toHaveLength(0); expect(errorSpy).toHaveBeenCalled(); + expect(apiBodies(apiFetch, '/receipts').at(-1)?.status).toBe('actions_rejected'); }); it('reply with invalid from/to is dropped with console.error', async () => { @@ -1432,40 +797,6 @@ describe('routeInbound — action enaction', () => { expect(rejectCalls[0]).not.toMatch(new RegExp('[\\r\\n\\u0000]')); }); - it('unknown action types are warned about and skipped, list continues', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { type: 'quarantine', to: 'admin@example.com' }, - { type: 'forward', to: 'admin@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(warnSpy).toHaveBeenCalled(); - expect(forwardCalls).toHaveLength(1); - }); - - it('non-object entries are dropped without aborting the list', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [null, 'reject', { type: 'forward', to: 'admin@example.com' }], - }); - const { message, forwardCalls, rejectCalls } = createFakeMessage({ - to: `myslug@${PROD_DOMAIN}`, - }); - const { ctx, waited } = createCtx(); - await routeInbound(message, env, ctx); - // `logRecv` currently throws on this input (see the log-recv describe - // block below). Swallow it here so the enaction assertions aren't - // masked by an unhandled rejection. - await Promise.allSettled(waited); - expect(rejectCalls).toHaveLength(0); - expect(forwardCalls).toHaveLength(1); - expect(errorSpy).toHaveBeenCalled(); - }); - it('a throwing forward is logged and does not abort the list', async () => { const { env } = makeEnv({ kvSeed: withAllowlist(), @@ -1522,94 +853,6 @@ describe('routeInbound — action enaction', () => { // the WHOLE list first, and any header failure drops everything. // ----------------------------------------------------------------------- -describe('routeInbound — header construction safety (HIGH H2)', () => { - it('drops the entire action list when forward headers contain CRLF (cannot partial-enact)', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - // First action: a forward with malformed headers — should drop - // the whole list. CRLF in a header VALUE is what `new Headers()` - // throws on. - { - type: 'forward', - to: 'admin@example.com', - headers: { 'X-Foo': 'a\r\nInjected: y' }, - }, - // Second action: a reply that would otherwise fire — must NOT - // fire because validation aborted the whole list. - { - type: 'reply', - from: `myslug+support@${PROD_DOMAIN}`, - to: 'admin@example.com', - raw: new Uint8Array(), - }, - ], - }); - const { message, forwardCalls, replyCalls } = createFakeMessage({ - to: `myslug+tag@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(replyCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalled(); - }); - - it('a VALID action DECLARED BEFORE the bad headers also does not fire', async () => { - // This is the case that distinguishes two-phase from single-pass: a - // single-pass enactor would already have forwarded to admin@ before - // reaching the poisoned headers. - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'ops@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com' }, - { - type: 'forward', - to: 'ops@example.com', - headers: { 'X-Foo': 'a\r\nInjected: y' }, - }, - ], - }); - const { message, forwardCalls, replyCalls, rejectCalls, order } = createFakeMessage({ - to: `myslug@${PROD_DOMAIN}`, - }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(order).toEqual([]); - expect(forwardCalls).toHaveLength(0); - expect(replyCalls).toHaveLength(0); - // The message is still ACCEPTED by CF — dropping the list is not a bounce. - expect(rejectCalls).toHaveLength(0); - // Phase A has no side effects: no quota was charged and no counter - // was written back. - expect(kv.writes.filter((w) => w.key.startsWith('email-sent:'))).toHaveLength(0); - expect(kv.writes.filter((w) => w.key.startsWith('email-burst:'))).toHaveLength(0); - }); - - it('valid forward headers are constructed once and handed to forward()', async () => { - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [ - { - type: 'forward', - to: 'admin@example.com', - headers: { 'X-Void-Tag': 'support' }, - }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+support@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(1); - expect(forwardCalls[0]?.headers).toBeInstanceOf(Headers); - expect(forwardCalls[0]?.headers?.get('X-Void-Tag')).toBe('support'); - }); -}); - -// ----------------------------------------------------------------------- -// Prototype pollution guard -// ----------------------------------------------------------------------- - describe('routeInbound — envelope header bag (prototype pollution guard)', () => { it('survives a __proto__ header in the inbound message', async () => { // Inject a __proto__-named header on the inbound side. The router @@ -1689,38 +932,7 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { await Promise.all(waited); }); - it('schedules log-recv even when the dispatch threw (no-handler reject path)', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailThrow: new TypeError('The RPC receiver does not implement the method "email"'), - }); - const { message } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx, waited } = createCtx(); - await routeInbound(message, env, ctx); - expect(waited).toHaveLength(1); - await Promise.all(waited); - }); - - it('schedules log-recv on the generic dispatch-error reject path', async () => { - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailThrow: new Error('boom'), - }); - const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx, waited } = createCtx(); - await routeInbound(message, env, ctx); - expect(waited).toHaveLength(1); - await Promise.all(waited); - }); - - // FINDING (pre-existing, also present in pr117): `logRecv` reads - // `a.type` straight off the RAW action array, while `validateActions` - // defends against non-object entries. A user worker that returns an - // array containing `null` therefore crashes the metering log inside - // `ctx.waitUntil` — the recv counter is never written and the audit - // line for that delivery is silently lost (as an UNHANDLED rejection, - // outside logRecv's own try/catch). Expressed as the correct - // expectation; this test fails until logRecv guards the entry. + // Invalid action data must not prevent inbound delivery from being logged. it('logs the inbound delivery even when the action list carries a non-object entry', async () => { const { env } = makeEnv({ kvSeed: withAllowlist(['admin@example.com']), @@ -1733,23 +945,6 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { await Promise.allSettled(waited); expect(logSpy).toHaveBeenCalled(); }); - - it('does NOT log-recv for messages rejected before dispatch (suspended)', async () => { - const { env, kv } = makeEnv({ - kvSeed: { - myslug: JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', - suspended: 'abuse', - }), - }, - }); - const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); - const { ctx, waited } = createCtx(); - await routeInbound(message, env, ctx); - expect(waited).toHaveLength(0); - expect(kv.store.get(RECV_KEY)).toBeUndefined(); - }); }); // Recipient consent and atomic quotas are covered by the API admission integration tests. @@ -1757,7 +952,7 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { describe('routeInbound — authoritative native custom domain', () => { it('dispatches the full custom recipient without KV and enacts native forward and reply', async () => { const from = 'support@custom.example.com'; - const { env, kv, emailFn, dispatchGet } = makeEnv({ + const { env, kv, emailFn, dispatchGet, apiFetch } = makeEnv({ emailReturn: [ { type: 'forward', to: 'admin@example.com' }, { type: 'reply', from, to: 'sender@example.com', raw: replyRaw(from) }, @@ -1786,6 +981,66 @@ describe('routeInbound — authoritative native custom domain', () => { expect(forwardCalls).toHaveLength(1); expect(replyCalls).toHaveLength(1); expect(rejectCalls).toHaveLength(0); + expect(apiBodies(apiFetch, '/admit').map((body) => body.transport)).toEqual([ + 'native_forward', + 'native_reply', + ]); + }); +}); + +describe('routeInbound — receipt checkpoint', () => { + it('does not bounce accepted mail when handler completion cannot be recorded', async () => { + const { env, apiFetch } = makeEnv({ emailReturn: [] }); + const normalFetch = apiFetch.getMockImplementation()!; + apiFetch.mockImplementation(async (url, init) => { + if ( + String(url).endsWith('/receipts') && + JSON.parse(String(init?.body)).status === 'handler_completed' + ) { + return Response.json({ error: 'unavailable' }, { status: 503 }); + } + return normalFetch(url, init); + }); + const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); + const { ctx } = createCtx(); + await routeInbound(message, env, ctx); + expect(rejectCalls).toEqual([]); + }); +}); + +describe('routeRelayed — unsupported forward', () => { + it('records an unsupported action without resending inbound MIME', async () => { + const { env, apiFetch } = makeEnv({ + emailReturn: [{ type: 'forward', to: 'admin@example.com' }], + }); + const fetchSpy = vi.spyOn(globalThis, 'fetch'); + const { ctx } = createCtx(); + const outcome = await routeRelayed(env, ctx, { + projectId: 'p_test', + domain: 'custom.example.com', + receiptId: 'receipt_1', + envelope: { + from: 'sender@example.com', + to: 'support@custom.example.com', + headers: {}, + raw: new TextEncoder().encode('From: sender@example.com\r\n\r\nbody'), + rawSize: 42, + }, + authoritative: { + projectId: 'p_test', + workerName: 'user-worker', + deploymentId: 'v1', + slug: 'myslug', + addressing: 'custom', + domain: 'custom.example.com', + }, + }); + expect(outcome.reject).toBe(false); + expect(apiBodies(apiFetch, '/admit')[0]?.transport).toBe('send_raw'); + expect(apiBodies(apiFetch, '/admit')[0]?.kind).toBe('forward'); + expect(apiBodies(apiFetch, '/start')).toEqual([]); + expect(fetchSpy).not.toHaveBeenCalled(); + fetchSpy.mockRestore(); }); }); @@ -1837,11 +1092,7 @@ describe('routeInbound — reply size limits', () => { expect(replyCalls[0]?.from).toBe(SENDER); }); - it('drops a reply that exceeds the 8 MiB cumulative budget and accepts a later smaller reply', async () => { - // The overrunning reply is dropped and NOT charged, exactly as the - // framework's `reply()` throws before advancing `replyBytesUsed`: a - // later reply that fits the remaining budget (3 + 3 + 2 = 8 MiB) still - // goes. + it('rejects a whole list that exceeds the 8 MiB cumulative reply budget', async () => { const { env } = makeEnv({ kvSeed: withAllowlist(['admin@example.com']), emailReturn: [ @@ -1854,7 +1105,7 @@ describe('routeInbound — reply size limits', () => { const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); - expect(replyCalls).toHaveLength(3); + expect(replyCalls).toHaveLength(0); expect(errorSpy).toHaveBeenCalledTimes(1); expect(errorSpy).toHaveBeenCalledWith( expect.stringContaining( @@ -1863,369 +1114,3 @@ describe('routeInbound — reply size limits', () => { ); }); }); - -// ----------------------------------------------------------------------- -// Framework ↔ router parity for the record-time bounds. -// -// The framework's `createMessageProxy` restates `MAX_FORWARD_HEADERS`, -// `MAX_FORWARD_HEADER_LENGTH` and `MAX_REJECT_REASON_LENGTH` and applies -// them where the action is RECORDED — in the handler's own call — so the -// test harness (which builds its message with that proxy) and a native -// own-account replay answer what this router answers. A number that -// drifted on one side would reopen the gap: a forward the harness reports -// and this router drops, or a reject reason that is clean here and injects -// into the SMTP reply natively. The numbers are pinned equal, and the -// agreement is pinned at the bound in both directions: the largest bag the -// proxy records is enacted here, one past it is refused there and dropped -// here, and a reason the proxy has normalized passes through this router -// unchanged. -// -// The harness also restates this router's ADMISSION — `MAX_INBOUND_BYTES` -// and `MAX_INBOUND_HEADERS` — and refuses a synthetic message before the -// handler runs, as `routeInbound` refuses the real one before dispatch. A -// number that drifted there would let a test invoke a handler on a message -// this router bounces. Pinned equal, and pinned in behaviour: the same -// bytes, one past each cap, draw the same reject string from both sides -// with the handler never called. -// ----------------------------------------------------------------------- - -describe('framework ↔ router bound parity', () => { - const ENVELOPE = { - from: 'sender@example.com', - to: 'tag@example.com', - headers: {}, - raw: new TextEncoder().encode('Subject: hi\r\n\r\nbody\r\n'), - rawSize: 21, - }; - - it('restates the same numbers', () => { - // Guarded on type: an export missing on either side reads `undefined`, - // and `undefined === undefined` is not parity. - for (const [framework, router] of [ - [FRAMEWORK_MAX_FORWARD_HEADERS, MAX_FORWARD_HEADERS], - [FRAMEWORK_MAX_FORWARD_HEADER_LENGTH, MAX_FORWARD_HEADER_LENGTH], - [FRAMEWORK_MAX_REJECT_REASON_LENGTH, MAX_REJECT_REASON_LENGTH], - [FRAMEWORK_MAX_INBOUND_BYTES, MAX_INBOUND_BYTES], - [FRAMEWORK_MAX_INBOUND_HEADERS, MAX_INBOUND_HEADERS], - ]) { - expect(router).toBeTypeOf('number'); - expect(framework).toBe(router); - } - }); - - it('enacts the maximum forward header count within the action metadata budget', async () => { - const bag: Record = {}; - for (let i = 0; i < MAX_FORWARD_HEADERS; i++) { - const suffix = String(i).padStart(2, '0'); - bag[`X-Forward-${suffix}`] = 'v'.repeat(200); - } - const proxy = createMessageProxy(ENVELOPE); - await proxy.message.forward('admin@example.com', bag as unknown as Headers); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: proxy.getActions(), - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(1); - expect([...forwardCalls[0]!.headers!.keys()]).toHaveLength(MAX_FORWARD_HEADERS); - expect(errorSpy).not.toHaveBeenCalled(); - }); - - it.each([ - [ - 'one header too many', - (() => { - const bag: Record = {}; - for (let i = 0; i <= MAX_FORWARD_HEADERS; i++) { - bag[`X-Void-${i}`] = 'v'; - } - return bag; - })(), - ], - ['a name one character too long', { [`X${'a'.repeat(MAX_FORWARD_HEADER_LENGTH)}`]: 'v' }], - ['a value one character too long', { 'X-Void-Tag': 'v'.repeat(MAX_FORWARD_HEADER_LENGTH + 1) }], - ])( - 'refuses a bag with %s at the framework call, and drops the same raw list here', - async (_label, bag) => { - // Both sides, same input: the framework fails the handler's call (so - // the list never exists), and a hand-built entrypoint that returns the - // list anyway loses the WHOLE list here. - const proxy = createMessageProxy(ENVELOPE); - await expect( - proxy.message.forward('admin@example.com', bag as unknown as Headers), - ).rejects.toThrow(/^forward: /); - expect(proxy.getActions()).toEqual([]); - const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'ops@example.com']), - emailReturn: [ - { type: 'forward', to: 'admin@example.com', headers: bag }, - { type: 'forward', to: 'ops@example.com' }, - ], - }); - const { message, forwardCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(forwardCalls).toHaveLength(0); - expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('action list dropped')); - }, - ); - - it.each([ - ['a control-heavy reason past the cap', 'line\r\n'.repeat(300)], - ['a multi-megabyte reason ending in CRLF and NUL', `${'x'.repeat(5 * 1024 * 1024)}\r\n\x00`], - ['an empty reason', ''], - ['a controls-only reason', '\r\n'], - ])('sends the reject reason the framework recorded for %s unchanged', async (_label, reason) => { - // What the proxy records is already this router's `sanitize` output, so - // the router's own pass is the identity on it — the native replay and - // the managed one hand the remote MTA the same string. - const proxy = createMessageProxy(ENVELOPE); - proxy.message.setReject(reason); - const [recorded] = proxy.getActions(); - expect(recorded!.type).toBe('reject'); - const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, - emailReturn: [recorded], - }); - const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(rejectCalls).toEqual([(recorded as { reason: string }).reason]); - expect(rejectCalls[0]!.length).toBeLessThanOrEqual(MAX_REJECT_REASON_LENGTH); - }); - - describe('admission', () => { - // One message, one past each cap, delivered to the same wire address on - // both sides. The router's fake carries the raw's own header lines as - // its `Headers`, which is the bag Cloudflare builds from the wire; its - // `rawSize` is the byte length, as Cloudflare sets it. - const WIRE_TO = `myslug+tag@${PROD_DOMAIN}`; - - function headerLinesOf(raw: Uint8Array): Array<[string, string]> { - const text = new TextDecoder().decode(raw); - const block = text.slice(0, text.indexOf('\r\n\r\n')); - return block.split('\r\n').map((line) => { - const colon = line.indexOf(':'); - return [line.slice(0, colon), line.slice(colon + 1).trim()]; - }); - } - - function oversized(): Uint8Array { - const head = new TextEncoder().encode(`From: u@x.dev\r\nTo: ${WIRE_TO}\r\n\r\n`); - const raw = new Uint8Array(MAX_INBOUND_BYTES + 1); - raw.set(head, 0); - raw.fill(0x61, head.byteLength); - return raw; - } - - function overHeaders(): Uint8Array { - const lines = ['From: u@x.dev', `To: ${WIRE_TO}`]; - for (let i = lines.length; i <= MAX_INBOUND_HEADERS; i++) { - lines.push(`h${i.toString(36)}: v`); - } - return new TextEncoder().encode(`${lines.join('\r\n')}\r\n\r\nbody\r\n`); - } - - it.each([ - [ - 'one byte over the size cap', - oversized, - `${PROD_DOMAIN}: message too large (max ${MAX_INBOUND_BYTES} bytes)`, - ], - [ - 'one distinct header over the cap', - overHeaders, - `${PROD_DOMAIN}: too many headers (max ${MAX_INBOUND_HEADERS})`, - ], - ])( - 'refuses a message %s with the same reason on both sides, handler never called', - async (_label, build, reason) => { - const raw = build(); - - const handler = vi.fn(async (message: ForwardableEmailMessage) => { - await message.forward('admin@example.com'); - }); - const harness = createInboundTestHarness({ routes: { _default: handler } }); - await harness.deliver({ from: 'u@x.dev', to: WIRE_TO, raw }); - expect(handler).not.toHaveBeenCalled(); - expect(harness.rejects).toEqual([reason]); - - const { env, emailFn } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), - emailReturn: [{ type: 'forward', to: 'admin@example.com' }], - }); - const { message, rejectCalls, forwardCalls } = createFakeMessage({ - to: WIRE_TO, - rawBytes: raw, - rawSize: raw.byteLength, - }); - for (const [name, value] of headerLinesOf(raw)) { - message.headers.append(name, value); - } - const { ctx } = createCtx(); - await routeInbound(message, env, ctx); - expect(emailFn).not.toHaveBeenCalled(); - expect(forwardCalls).toEqual([]); - expect(rejectCalls).toEqual([reason]); - }, - ); - }); - - describe('address rule', () => { - // The framework's `validateAddressParts` is what `forward(to)` and a - // hand-built `reply({ from, to })` record through; `isValidEmailAddress` - // is what this router drops on. Anything the framework records and the - // router drops is an action a handler's test reported as a success and - // the managed deployment silently lost — after the actions before it - // had fired. Both sides now call the same package (`email-validator`), - // so the rule is: framework-accepts ⇔ router-accepts, for every entry - // below, with ZERO divergences either way. This test is the pin that - // the two `package.json`s stay on the same rule; the old "one known - // divergence" (the dot in the domain) is gone because both refuse it. - const frameworkAccepts = (address: string): boolean => { - try { - validateAddressParts('to', address); - return true; - } catch { - return false; - } - }; - - // Every C0 control and DEL, each inside the local part. - const controls = Array.from({ length: 0x21 }, (_, i) => (i === 0x20 ? 0x7f : i)).map( - (code) => `a${String.fromCharCode(code)}b@example.com`, - ); - // Every RFC 5322 §3.2.3 special (`.` and `@` aside — `.` is dot-atom - // punctuation and `@` has its own exactly-one rule), in the local part - // and in the domain. - const specials = [...'()<>[]:;\\,"'].flatMap((ch) => [ - `a${ch}b@example.com`, - `a@b${ch}c.example.com`, - ]); - // `a@` plus 252 characters of labels: the longest path RFC 5321 makes - // every receiver accept, and the package's 254 total. - const domain252 = `${'b'.repeat(63)}.${'c'.repeat(63)}.${'d'.repeat(63)}.${'e'.repeat(60)}`; - const deliverable = [ - 'ops@example.com', - 'ops+T-42@example.com', - 'first.last@sub.example.com', - `${'a'.repeat(64)}@example.com`, - `a@${domain252}`, - 'a@xn--bcher-kva.example', - 'a@b.c1', - "a!#$%&'*+-/=?^_`{|}~@example.com", - ]; - // The router's 320 work bound, with a dot in the domain; both sides - // refuse both on the package's 254 total (the labels are also over 63). - const at320 = `${'a'.repeat(64)}@${'b'.repeat(251)}.dev`; - const at321 = `${'a'.repeat(64)}@${'b'.repeat(252)}.dev`; - // Dot-atom shapes BOTH sides used to accept — no divergence, one shared - // hole an MTA refused after the handler's test reported a success. - const malformedDotAtom = [ - 'a..b@example.com', - '.a@example.com', - 'a.@example.com', - 'a@example..com', - 'a@.example.com', - 'a@example.com.', - ]; - // The framework used to accept these and the router refused them (the - // dot), or both accepted them (non-ASCII, the TLD shapes); both refuse - // them now. - const newlyRefused = [ - 'user@localhost', - 'x@y', - 'a@example', - 'jöhn@example.com', - 'ünicode@example.com', - 'a@exämple.com', - 'a@b.c', - 'a@b.1c', - '`a@x.com', - ]; - const corpus: Array = [ - ...deliverable, - // One `@`, and something on both sides of it. - 'not-an-address', - 'a@b@example.com', - '@example.com', - 'user@', - '@', - '', - // Quoting, display names, list separators. - '"a b"@example.com', - '"a@b"@example.com', - 'Ops ', - 'a@example.com,b@example.com', - 'a@example.com;b@example.com', - // Whitespace: the ASCII kinds and the non-ASCII one `\s` also matches. - 'a b@example.com', - 'a\tb@example.com', - 'a\vb@example.com', - 'a\fb@example.com', - 'a\u00a0b@example.com', - ' ops@example.com', - 'ops@example.com ', - ...controls, - ...specials, - ...malformedDotAtom, - ...newlyRefused, - at320, - at321, - `${'a'.repeat(65)}@example.com`, - `a@${'b'.repeat(253)}`, - `a@${'b'.repeat(64)}.dev`, - // The package quirk, from the other side: a backtick AFTER the first - // character is fine. - 'a`b@x.com', - ]; - - it('accepts and refuses exactly what the framework does — zero divergences', () => { - expect(at320).toHaveLength(320); - expect(at321).toHaveLength(321); - expect(deliverable[4]).toHaveLength(254); - const divergent = corpus.filter((a) => frameworkAccepts(a) !== isValidEmailAddress(a)); - expect( - divergent, - `framework and router disagree on: ${JSON.stringify(divergent[0])}`, - ).toEqual([]); - // Not vacuous: both sides accept every deliverable shape, and both - // refuse the 320-character address, every special, every control, - // every malformed dot-atom and every newly refused shape. - expect(deliverable.every((a) => frameworkAccepts(a) && isValidEmailAddress(a))).toBe(true); - expect(frameworkAccepts('a`b@x.com') && isValidEmailAddress('a`b@x.com')).toBe(true); - expect(isValidEmailAddress(at320)).toBe(false); - expect(frameworkAccepts(at320)).toBe(false); - expect( - [...controls, ...specials, ...malformedDotAtom, ...newlyRefused].some( - (a) => frameworkAccepts(a) || isValidEmailAddress(a), - ), - ).toBe(false); - }); - - it('drops a malformed dot-atom the framework also refuses', () => { - // The thread this closes: `a..b@example.com` was accepted by BOTH the - // hand-written framework rule and this router's regex. - for (const address of malformedDotAtom) { - expect(isValidEmailAddress(address), `router refuses ${address}`).toBe(false); - expect(frameworkAccepts(address), `framework refuses ${address}`).toBe(false); - } - }); - - it('refuses the dot-less domain on both sides now, not as a divergence', () => { - for (const address of ['user@localhost', 'x@y', 'a@example']) { - expect(frameworkAccepts(address), `framework refuses ${address}`).toBe(false); - expect(isValidEmailAddress(address), `router refuses ${address}`).toBe(false); - } - }); - - it('is length-first: a non-string or an over-long value never reaches the package', () => { - expect(isValidEmailAddress(undefined)).toBe(false); - expect(isValidEmailAddress(42)).toBe(false); - expect(isValidEmailAddress(['ops@example.com'])).toBe(false); - expect(isValidEmailAddress(`ops@${'b'.repeat(400)}.dev`)).toBe(false); - }); - }); -}); From 5909aaacdd8b621294bd6cac5b3553342b63828d Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sat, 19 Sep 2026 11:11:12 +0800 Subject: [PATCH 3/6] fix(email): harden authority recovery and lifecycle boundaries --- docs/guide/platform-administration.md | 23 ++ docs/reference/cli.md | 10 + packages/platform/src/email-protocol.ts | 19 +- packages/platform/src/installer.ts | 3 + packages/platform/src/worker-config.ts | 5 +- .../platform/test/unit/email-protocol.test.ts | 22 ++ .../platform/test/unit/worker-config.test.ts | 2 + packages/void/src/cli/email.ts | 2 +- packages/void/src/cli/help.ts | 6 +- packages/void/src/cli/operator-args.ts | 22 +- packages/void/src/cli/platform-args.ts | 2 +- packages/void/src/cli/platform-installer.ts | 41 ++- packages/void/src/runtime/email.ts | 23 +- .../void/test/unit/email-cli-domain.test.ts | 31 +- packages/void/test/unit/operator-cli.test.ts | 66 ++++ .../void/test/unit/platform-installer.test.ts | 58 ++- .../void/test/unit/platform-runtime.test.ts | 3 + .../meta/design-docs/0078-email-cf-native.md | 14 + .../api/drizzle/0047_email_gateway.sql | 16 +- .../api/drizzle/meta/0047_snapshot.json | 97 +++++ .../packages/api/src/admin/routes/email.tsx | 45 +-- platform/packages/api/src/db.ts | 295 ++++++++-------- platform/packages/api/src/email/admission.ts | 94 ++++- .../api/src/email/cf-domain-probes.ts | 17 +- .../api/src/email/connection-service.ts | 17 +- .../packages/api/src/email/domain-service.ts | 9 +- .../api/src/email/ingress-resolution.ts | 16 +- platform/packages/api/src/email/settings.ts | 24 -- platform/packages/api/src/index.ts | 5 + platform/packages/api/src/operator/audit.ts | 7 + .../packages/api/src/operator/email-routes.ts | 125 ++++++- .../packages/api/src/provisioning/cleanup.ts | 64 +--- .../provisioning/email-destination-cleanup.ts | 129 +++++++ .../api/src/provisioning/email-routing.ts | 31 +- .../packages/api/src/routes/email-confirm.ts | 5 +- platform/packages/api/src/routes/email.ts | 117 ++---- platform/packages/api/src/routes/projects.ts | 2 +- platform/packages/api/src/schema.ts | 55 ++- .../api/test/integration/admin-email.test.ts | 56 ++- .../api/test/integration/api-delete.test.ts | 57 ++- .../integration/api-email-domains.test.ts | 56 ++- .../api/test/integration/api-email.test.ts | 162 ++++++++- .../auth-email-verification.test.ts | 30 +- .../test/integration/email-admission.test.ts | 152 +++++++- .../integration/email-connections.test.ts | 168 ++++++++- .../test/integration/email-domain-cf-stub.ts | 17 +- .../packages/api/test/integration/helpers.ts | 1 + .../test/integration/operator-email.test.ts | 158 +++++---- .../api/test/unit/email-routing.test.ts | 14 + .../api/test/unit/email-settings.test.ts | 69 ---- platform/packages/email-gateway/src/index.ts | 14 +- .../email-gateway/test/unit/gateway.test.ts | 37 ++ platform/packages/proxy/src/email-router.ts | 162 +++++---- platform/packages/proxy/src/email.ts | 334 +++++++++--------- .../test/unit/email-custom-domain.test.ts | 226 ++++++------ .../proxy/test/unit/email-router.test.ts | 251 +++++++------ 56 files changed, 2390 insertions(+), 1096 deletions(-) create mode 100644 platform/packages/api/src/provisioning/email-destination-cleanup.ts create mode 100644 platform/packages/api/test/unit/email-routing.test.ts diff --git a/docs/guide/platform-administration.md b/docs/guide/platform-administration.md index 94e6a2df8..3c102c197 100644 --- a/docs/guide/platform-administration.md +++ b/docs/guide/platform-administration.md @@ -229,6 +229,29 @@ void platform email limit hr-portal --monthly 2000 --burst 30 The project's page in the admin UI shows the current values and clears an override. +### Recovering an interrupted send + +If a sender stops after beginning a provider call, its unresolved attempt blocks +removal of the project or sender domain. Inspect the attempt ID and start time: + +```sh +void platform email attempts --project hr-portal +``` + +First confirm that the original execution has ended through your Worker logs or +incident records. Once the attempt is at least 24 hours old, resolve it with an +audit reason that contains no recipient address or message content: + +```sh +void platform email attempt-resolve --ended --reason "Original Worker execution ended; provider outcome could not be verified" --plan +void platform email attempt-resolve --ended --reason "Original Worker execution ended; provider outcome could not be verified" +``` + +This records the send as `outcome_unknown` and releases its cleanup fence. The +attempt remains charged and is never retried. If its 30-day delivery record has +expired, only its recipient-free fence is removed. Do not resolve an attempt +while its original execution may still be active. + ### Registering email domains for projects Your users may hold no Cloudflare account. Tell the platform that administrators register email domains, so `void email domain add` prints the command to ask you for instead of opening a token-creation page: diff --git a/docs/reference/cli.md b/docs/reference/cli.md index c1f1f6953..c7d279300 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -616,12 +616,22 @@ void platform email policy-set [--domains void platform email limit [--monthly ] [--burst ] +void platform email attempts [--project ] [--page ] [--limit ] +void platform email attempt-resolve --ended --reason ``` `policy` decides which recipients a project's `+tag@` sender reaches: `verified` (the default) means only that project's verified destinations; `domains` adds every address on the listed domains; `any` lifts the check. Neither widens delivery to addresses on the platform's own mail domain: those stay verified-destination-only, so no project reaches another project's inbox without its consent. Cloudflare still refuses a destination it has not verified until the platform mail domain is onboarded for Email Sending, so under `domains` or `any` such refusals arrive as per-recipient `UNVERIFIED_DESTINATION` results. Custom-domain sends are not affected. `settings-set --domains admin` tells `void email domain add` to print the administrator's command instead of starting token setup. `limit` overrides the project's monthly and rolling 60-second caps (defaults 200 and 10); a project page in the admin UI shows and clears them. +`attempts` lists interrupted provider calls and their earliest resolution time. Once +the original Worker execution has ended and the attempt is at least 24 hours old, +`attempt-resolve` records `outcome_unknown`, retains its quota charge, and releases +the project/domain cleanup fence. `--ended` is your attestation that the call is no +longer active; `--reason` is stored in the operator audit log. Keep recipient +addresses and message content out of the reason. The send is never retried. Use +`--plan` to preview and `--yes` to apply without a prompt. + Register and maintain email domains for projects whose owners hold no Cloudflare credential: ```sh diff --git a/packages/platform/src/email-protocol.ts b/packages/platform/src/email-protocol.ts index 4e345ad8c..fd572a26b 100644 --- a/packages/platform/src/email-protocol.ts +++ b/packages/platform/src/email-protocol.ts @@ -99,7 +99,8 @@ export async function readEmailEnvelope( throw new Error('missing email envelope'); } const reader = stream.getReader(); - const bytes = new Uint8Array(4 + EMAIL_MAX_INBOUND_HEADER_BYTES + EMAIL_MAX_INBOUND_BYTES); + const limit = 4 + EMAIL_MAX_INBOUND_HEADER_BYTES + EMAIL_MAX_INBOUND_BYTES; + let bytes = new Uint8Array(1024); let total = 0; const deadline = Date.now() + deadlineMs; try { @@ -122,11 +123,21 @@ export async function readEmailEnvelope( if (chunk.done) { break; } - total += chunk.value.byteLength; - if (total > bytes.byteLength) { + const nextTotal = total + chunk.value.byteLength; + if (nextTotal > limit) { throw new Error('email envelope too large'); } - bytes.set(chunk.value, total - chunk.value.byteLength); + if (nextTotal > bytes.byteLength) { + let capacity = bytes.byteLength; + while (capacity < nextTotal) { + capacity = Math.min(limit, capacity * 2); + } + const grown = new Uint8Array(capacity); + grown.set(bytes.subarray(0, total)); + bytes = grown; + } + bytes.set(chunk.value, total); + total = nextTotal; } } catch (error) { await reader.cancel().catch(() => {}); diff --git a/packages/platform/src/installer.ts b/packages/platform/src/installer.ts index fbb543af6..dc2348cd2 100644 --- a/packages/platform/src/installer.ts +++ b/packages/platform/src/installer.ts @@ -94,6 +94,9 @@ export function parsePlatformRuntimeManifest(value: unknown): PlatformRuntimeMan if (root.emailProtocolVersion === 1 && artifactsValue.emailGateway === undefined) { throw new Error('Email protocol version 1 requires an emailGateway runtime artifact.'); } + if (artifactsValue.emailGateway !== undefined && root.emailProtocolVersion !== 1) { + throw new Error('An emailGateway runtime artifact requires email protocol version 1.'); + } const artifactNames = [ 'api', 'dispatch', diff --git a/packages/platform/src/worker-config.ts b/packages/platform/src/worker-config.ts index 8b72ff158..58eacc186 100644 --- a/packages/platform/src/worker-config.ts +++ b/packages/platform/src/worker-config.ts @@ -88,7 +88,9 @@ export function createPlatformWorkerConfigs(input: { // bindings here would make API/proxy bootstrap depend on each other existing. const fetchWorkersDev = Boolean(deployment.application.workersDev) || - [apiUrl, proxyUrl].some((url) => new URL(url).hostname.endsWith('.workers.dev')); + [apiUrl, proxyUrl, ...(deployment.capabilities.email ? [emailGatewayUrl] : [])].some((url) => + new URL(url).hostname.endsWith('.workers.dev'), + ); const api: Record = { ...common, @@ -213,6 +215,7 @@ export function createPlatformWorkerConfigs(input: { vars: { PLATFORM_CAPABILITIES: JSON.stringify(deployment.capabilities), PLATFORM_INSTALLATION_ID: installationId, + PLATFORM_VERSION: platformVersion, PLATFORM_TRAFFIC_STATE: trafficState, ...sharedEmailIngress, ...senderDomain, diff --git a/packages/platform/test/unit/email-protocol.test.ts b/packages/platform/test/unit/email-protocol.test.ts index ae8aef6ca..8ab0065d3 100644 --- a/packages/platform/test/unit/email-protocol.test.ts +++ b/packages/platform/test/unit/email-protocol.test.ts @@ -3,6 +3,7 @@ import { EMAIL_MAX_INBOUND_BYTES, EMAIL_MAX_RESPONSE_BYTES, encodeEmailActions, + encodeEmailEnvelope, readEmailEnvelope, readEmailActions, signEmailReceipt, @@ -55,6 +56,27 @@ describe('bounded email receipt protocol', () => { ]); }); + it('reads a small envelope split across the length prefix, metadata and MIME', async () => { + const raw = new TextEncoder().encode('From: sender@example.com\r\n\r\nhello'); + const envelope = { + from: 'sender@example.com', + to: 'support@example.com', + headers: { from: 'sender@example.com' }, + raw, + rawSize: raw.byteLength, + }; + const encoded = encodeEmailEnvelope(envelope); + const stream = new ReadableStream({ + start(controller) { + for (let offset = 0; offset < encoded.byteLength; offset += 3) { + controller.enqueue(encoded.subarray(offset, offset + 3)); + } + controller.close(); + }, + }); + expect(await readEmailEnvelope(stream)).toEqual(envelope); + }); + it('rejects a truncated tail instead of returning a partial action batch', async () => { const encoded = encodeEmailActions([{ type: 'forward', to: 'user@example.com' }]); const reader = encoded.getReader(); diff --git a/packages/platform/test/unit/worker-config.test.ts b/packages/platform/test/unit/worker-config.test.ts index c815d48bc..e09d30847 100644 --- a/packages/platform/test/unit/worker-config.test.ts +++ b/packages/platform/test/unit/worker-config.test.ts @@ -44,10 +44,12 @@ describe('platform usage queue bindings', () => { }; expect(configs.api.vars).toMatchObject(expected); expect(configs.emailGateway.vars).toMatchObject(expected); + expect(configs.emailGateway.vars).toHaveProperty('PLATFORM_VERSION', '1.0.0'); expect(configs.api.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); expect(configs.proxy.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); expect(configs.emailGateway.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); expect(configs.emailGateway).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]); + expect(configs.api.compatibility_flags).toContain('global_fetch_strictly_public'); expect(configs.api.vars).toHaveProperty( 'EMAIL_GATEWAY_ORIGIN', 'https://email-gateway.account.workers.dev', diff --git a/packages/void/src/cli/email.ts b/packages/void/src/cli/email.ts index c6fc72a9a..92f6441f0 100644 --- a/packages/void/src/cli/email.ts +++ b/packages/void/src/cli/email.ts @@ -798,7 +798,7 @@ export async function emailDomainAdd( 'Token stored encrypted on the platform for this zone connection — nothing is kept on this machine.', ); printEmailDomainOutcome(row); - if (row.operationStatus === 'blocked' || row.operationStatus === 'unknown') { + if (row.operationStatus !== 'completed') { return exit(1); } } diff --git a/packages/void/src/cli/help.ts b/packages/void/src/cli/help.ts index 1d4115d31..06c0d2ef3 100644 --- a/packages/void/src/cli/help.ts +++ b/packages/void/src/cli/help.ts @@ -72,7 +72,7 @@ function operatorHelpTree(): HelpTree { }, ] : []), - ...(['list', 'events', 'logs'].includes(entry.action) + ...(['list', 'events', 'logs', 'attempts'].includes(entry.action) ? [ { command: '--limit ', @@ -95,7 +95,9 @@ function operatorHelpTree(): HelpTree { description: flag === 'follow' ? 'Poll new logs until interrupted or the build ends' - : 'Read a full API session from stdin for explicit operator session exchange', + : flag === 'ended' + ? 'Attest that the original provider execution has ended' + : 'Read a full API session from stdin for explicit operator session exchange', })), ], }, diff --git a/packages/void/src/cli/operator-args.ts b/packages/void/src/cli/operator-args.ts index ea55844d3..184e9152c 100644 --- a/packages/void/src/cli/operator-args.ts +++ b/packages/void/src/cli/operator-args.ts @@ -305,6 +305,23 @@ export const operatorCommands: Array = [ values: { monthly: 'Messages per month', burst: 'Messages per minute' }, method: 'POST', }, + { + group: 'email', + action: 'attempts', + description: 'List unresolved email send attempts awaiting operator reconciliation', + path: '/email/attempts', + values: { project: 'Project id or slug' }, + }, + { + group: 'email', + action: 'attempt-resolve', + description: 'Resolve a stopped send as outcome unknown and release its cleanup fence', + path: '/email/attempts/:id/resolve', + positional: ['id'], + values: { reason: 'Audit reason without recipient or message content' }, + booleans: ['ended'], + method: 'POST', + }, { group: 'email', action: 'domains', @@ -415,7 +432,7 @@ export function parseOperatorArgs(args: Array): OperatorArgs { const positional: Array = []; const values: Record = {}; const flags = new Set(); - const booleanFlags = new Set(['json', 'plan', 'yes', 'follow', 'token-stdin', 'force']); + const booleanFlags = new Set(['json', 'plan', 'yes', 'follow', 'token-stdin', 'force', 'ended']); for (let index = 0; index < args.length; index++) { const arg = args[index]!; if (!arg.startsWith('-')) { @@ -491,7 +508,8 @@ export function parseOperatorArgs(args: Array): OperatorArgs { `platform: Usage: ${command.usage?.[identitySignupEntry ? 1 : 0]?.replace(/ \[options\]$/, '') ?? `void platform ${group} ${action}${command.positional?.map((name) => ` <${name}>`).join('') ?? ''}`}.`, ); } - const paged = action === 'list' || action === 'events' || action === 'logs'; + const paged = + action === 'list' || action === 'events' || action === 'logs' || action === 'attempts'; const allowed = new Set([ 'connection', ...(command.method ? ['timeout'] : []), diff --git a/packages/void/src/cli/platform-args.ts b/packages/void/src/cli/platform-args.ts index 0e8817927..cc6b8746c 100644 --- a/packages/void/src/cli/platform-args.ts +++ b/packages/void/src/cli/platform-args.ts @@ -10,7 +10,7 @@ export const platformSubcommands: Array = [ }, ...operatorGroups.map((name) => ({ name, - hint: 'Operator commands', + hint: name === 'email' ? 'Domains, policy, limits, and send recovery' : 'Operator commands', description: `Administer platform ${name}`, })), { name: 'list', description: 'List installed and connected platforms' }, diff --git a/packages/void/src/cli/platform-installer.ts b/packages/void/src/cli/platform-installer.ts index f68243dd0..9642ca862 100644 --- a/packages/void/src/cli/platform-installer.ts +++ b/packages/void/src/cli/platform-installer.ts @@ -1912,6 +1912,9 @@ export async function installPlatform( await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); } dependencies.onProgress?.('Verifying platform health'); + const emailGatewayUrl = hasEmailGatewayArtifact + ? `https://${plan.deployment.resources.emailGatewayWorker}.${plan.workersSubdomain}.workers.dev` + : undefined; if (plan.deployment.authentication.accessProtection) { ensurePlatformAccessToken(plan.apiUrl, false, true); ensurePlatformAccessToken(plan.proxyUrl, false, true); @@ -1925,6 +1928,7 @@ export async function installPlatform( plan.deployment.resources.dispatchWorker, ], resumeCommand: dependencies.healthCheckResumeCommand, + ...(emailGatewayUrl ? { emailGatewayUrl } : {}), }; await (dependencies.verifyHealth ?? verifyPlatformHealth)( plan.apiUrl, @@ -5128,9 +5132,8 @@ function interruptedWorkerCutover( generations.set(generation, entry); continue; } - const unsafeTraffic = /^worker-cutover:(\d+):unsafe-traffic:(api|proxy|tail|dispatch)$/.exec( - step.key, - ); + const unsafeTraffic = + /^worker-cutover:(\d+):unsafe-traffic:(api|proxy|emailGateway|tail|dispatch)$/.exec(step.key); if (unsafeTraffic) { const generation = Number(unsafeTraffic[1]); const entry = generations.get(generation) ?? { @@ -5142,7 +5145,9 @@ function interruptedWorkerCutover( generations.set(generation, entry); continue; } - const staged = /^worker-cutover:(\d+):staged:(api|proxy|tail|dispatch)$/.exec(step.key); + const staged = /^worker-cutover:(\d+):staged:(api|proxy|emailGateway|tail|dispatch)$/.exec( + step.key, + ); if (!staged) { continue; } @@ -5293,6 +5298,7 @@ export type PlatformHealthCheckContext = Readonly<{ accountName: string; workers: ReadonlyArray; resumeCommand?: string; + emailGatewayUrl?: string; }>; export class PlatformAccessBlockedError extends Error { @@ -5366,11 +5372,12 @@ export async function verifyPlatformHealth( signal: AbortSignal.timeout(30_000), }); const dispatchUrl = dispatchOrigin ?? `https://test.${applicationBaseDomain}`; - const [health, discovery, proxy, dispatch] = await Promise.all([ + const [health, discovery, proxy, dispatch, emailGateway] = await Promise.all([ request(`${apiUrl}/health`), request(`${apiUrl}/.well-known/void-platform`), request(`${proxyUrl}/health`), request(`${dispatchUrl}/health`), + context?.emailGatewayUrl ? request(`${context.emailGatewayUrl}/health`) : undefined, ]); if (!health.ok) { throw await platformProbeFailure('Health check', apiUrl, health, context); @@ -5400,6 +5407,30 @@ export async function verifyPlatformHealth( if (!dispatch.ok) { throw await platformProbeFailure('Dispatch health check', dispatchUrl, dispatch, context); } + if (emailGateway) { + if (!emailGateway.ok) { + throw await platformProbeFailure( + 'Email gateway health check', + context!.emailGatewayUrl!, + emailGateway, + context, + ); + } + const identity = (await emailGateway.json()) as { + installationId?: unknown; + platformVersion?: unknown; + emailProtocolVersion?: unknown; + } | null; + if ( + identity?.installationId !== installationId || + identity.platformVersion !== platformVersion || + identity.emailProtocolVersion !== 1 + ) { + throw new Error( + 'platform: Deployed email gateway identity, version, or protocol does not match this installation.', + ); + } + } } export async function verifyPlatformSandboxDrain( diff --git a/packages/void/src/runtime/email.ts b/packages/void/src/runtime/email.ts index a16b0a0a0..0eeb27772 100644 --- a/packages/void/src/runtime/email.ts +++ b/packages/void/src/runtime/email.ts @@ -183,10 +183,6 @@ function resolveSendEmailBinding( * no way to act on a delivery failure or a service outage beyond * reporting it. * - * The platform proxy's `classifyUpstream` mirrors this table for its own - * binding, except the two sender codes: there `from` is pinned to the - * project sender, so a sender failure is the platform's to fix and stays - * `UPSTREAM_ERROR`. Keep the recipient and limit rows in lockstep. */ function classifyBindingError(e: unknown): SendEmailError { const message = e instanceof Error ? e.message : String(e); @@ -213,7 +209,6 @@ function classifyBindingError(e: unknown): SendEmailError { // Anchored to Cloudflare's own phrasing ("destination address … not (yet) // verified"), with bounded runs so a long preamble or a multi-line stack // cannot drag an unrelated mention of the address into a false positive. -// Mirrors `classifyUpstream` in the platform proxy. const UNVERIFIED_DESTINATION_RE = /^[^\n]{0,200}destination address[^\n]{0,200}not (?:yet )?verified/i; @@ -468,9 +463,8 @@ type RecipientListRead = { ok: true; entries: Array } | { ok: false; reaso * The rules shared by both shapes: the count equals the recipients sent; * every entry is an object naming a requested recipient exactly once. The * list is compared as a set against the unique, lowercased recipients the - * request carried and returned in the order the proxy gave it — order is - * not part of the contract (the proxy lists allowlist rejections before the - * sends it attempted). `readEntry` decides the rest of the entry's shape and + * request carried and returned in the order the proxy gave it; order is not + * part of the contract. `readEntry` decides the rest of the entry's shape and * returns `undefined` when it does not hold; `shape` names that shape in the * reason. * @@ -516,14 +510,11 @@ function readRecipientList( } /** - * The `ids` list of an `ok: true` response. The proxy answers `ok: true` - * only once every requested recipient passed its allowlist and - * `SEND_EMAIL.send()` confirmed each one, so every entry is - * `{ recipient, messageId }` with `messageId` always a string (`''` when - * Cloudflare returned none; that is the proxy's explicit convention, and the - * framework's own Message-ID stands in for it). An `ok: true` with a - * delivery missing would tell the caller a send was confirmed when it never - * was, and a success carries no per-recipient failure to retry from. + * The `ids` list of an `ok: true` response. The proxy answers `ok: true` only + * after every requested recipient has an accepted provider outcome. Each entry + * is `{ recipient, messageId }`; the framework's own Message-ID stands in for + * an empty provider reference. A missing delivery would leave no safe retry + * decision, so the whole response is rejected as malformed. */ function readDeliveryList( raw: Array, diff --git a/packages/void/test/unit/email-cli-domain.test.ts b/packages/void/test/unit/email-cli-domain.test.ts index 4fe4bcca7..933d39b00 100644 --- a/packages/void/test/unit/email-cli-domain.test.ts +++ b/packages/void/test/unit/email-cli-domain.test.ts @@ -249,7 +249,7 @@ describe('emailDomainAdd', () => { } function client() { return { - addEmailDomain: vi.fn(async () => domainRow()), + addEmailDomain: vi.fn(async () => domainRow({ operationStatus: 'completed' })), getEmailDomain: vi.fn(async () => domainRow()), getEmailOperation: vi.fn(async () => ({ operationId: 'op_1', @@ -463,21 +463,20 @@ describe('emailDomainAdd', () => { expect(api.getEmailOperation).not.toHaveBeenCalled(); }); - it('returns failure for setup needing intervention, even if a row exists', async () => { - const api = client(); - api.addEmailDomain.mockResolvedValue( - domainRow({ - status: 'drifted', - operationId: 'op_1', - operationStatus: 'blocked', - error: 'catch-all conflict', - }), - ); - await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps())).rejects.toThrow( - 'exit 1', - ); - expect(printed(errorSpy)).toContain('catch-all conflict'); - }); + it.each(['pending', 'running', 'blocked', 'unknown'] as const)( + 'returns failure when setup is %s, even if a row exists', + async (operationStatus) => { + const api = client(); + api.addEmailDomain.mockResolvedValue( + domainRow({ operationId: 'op_1', operationStatus, error: 'setup unfinished' }), + ); + await expect(emailDomainAdd(api, 'prj_1', 'acme.com', undefined, addDeps())).rejects.toThrow( + 'exit 1', + ); + expect(printed(errorSpy)).toContain('setup unfinished'); + expect(notedBlocks()).toContain(`op_1 · ${operationStatus}`); + }, + ); }); describe('emailDomainStatus', () => { diff --git a/packages/void/test/unit/operator-cli.test.ts b/packages/void/test/unit/operator-cli.test.ts index 7aa5b6312..4ca53cb7c 100644 --- a/packages/void/test/unit/operator-cli.test.ts +++ b/packages/void/test/unit/operator-cli.test.ts @@ -152,6 +152,32 @@ describe('operator argument and help coverage', () => { expect(() => parseOperatorArgs(['email', 'policy', '--domains', 'x'])).toThrow(); expect(() => parseOperatorArgs(['email', 'limit'])).toThrow(); }); + it('routes attempt inspection and attested resolution with a bounded audit reason', () => { + expect( + parseOperatorArgs(['email', 'attempts', '--project', 'my-project', '--page', '2']), + ).toMatchObject({ + method: 'GET', + path: '/email/attempts', + query: { project: 'my-project', page: '2' }, + }); + expect( + parseOperatorArgs([ + 'email', + 'attempt-resolve', + 'attempt/id', + '--ended', + '--reason', + 'Worker execution ended', + '--yes', + ]), + ).toMatchObject({ + method: 'POST', + path: '/email/attempts/attempt%2Fid/resolve', + body: { ended: true, reason: 'Worker execution ended' }, + yes: true, + }); + expect(() => parseOperatorArgs(['email', 'attempts', '--ended'])).toThrow(); + }); it('routes the email domain verbs and carries their booleans in the body', () => { expect(parseOperatorArgs(['email', 'domains', '--project', 'hr-portal'])).toMatchObject({ method: 'GET', @@ -372,6 +398,46 @@ describe('operator transport and execution', () => { versions: { api: 'version-a' }, }); }); + it('previews then submits an attested email attempt resolution', async () => { + vi.stubEnv('VOID_API_URL', 'https://one.example'); + vi.stubEnv('VOID_OPERATOR_TOKEN', 'operator'); + vi.spyOn(console, 'log').mockImplementation(() => {}); + const fetcher = vi + .fn() + .mockResolvedValueOnce( + Response.json({ + dryRun: true, + action: 'email.attempt.resolve', + target: { attemptId: 'er_1' }, + }), + ) + .mockResolvedValueOnce(Response.json({ state: 'outcome_unknown', charged: true })); + vi.stubGlobal('fetch', fetcher); + await runOperatorCommand( + parseOperatorArgs([ + 'email', + 'attempt-resolve', + 'er_1', + '--ended', + '--reason', + 'Worker execution ended', + '--yes', + ]), + ); + expect(fetcher).toHaveBeenCalledTimes(2); + expect(String(fetcher.mock.calls[0]![0])).toBe( + 'https://one.example/operator/v1/email/attempts/er_1/resolve', + ); + expect(JSON.parse(String(fetcher.mock.calls[0]![1]!.body))).toEqual({ + ended: true, + reason: 'Worker execution ended', + dryRun: true, + }); + expect(JSON.parse(String(fetcher.mock.calls[1]![1]!.body))).toEqual({ + ended: true, + reason: 'Worker execution ended', + }); + }); it('drains runtime cursors and rejects repeated cursors instead of spinning', async () => { vi.spyOn(console, 'log').mockImplementation(() => {}); const fetcher = vi diff --git a/packages/void/test/unit/platform-installer.test.ts b/packages/void/test/unit/platform-installer.test.ts index 8eabf1e09..7a38e6c63 100644 --- a/packages/void/test/unit/platform-installer.test.ts +++ b/packages/void/test/unit/platform-installer.test.ts @@ -543,6 +543,7 @@ describe('platform installer', () => { ); expect(context).toEqual({ accountName: plan.account.name, + emailGatewayUrl: `https://${plan.deployment.resources.emailGatewayWorker}.workers-subdomain.workers.dev`, workers: [ plan.deployment.resources.apiWorker, plan.deployment.resources.proxyWorker, @@ -1418,17 +1419,18 @@ describe('platform installer', () => { }); }); - it('verifies API, discovery, proxy, and dispatch before committing a cutover', async () => { + it('verifies API, discovery, proxy, dispatch, and email gateway before committing a cutover', async () => { const requests: Array<{ headers: Headers; url: string; redirect?: RequestRedirect }> = []; const fetcher = (async (input: string | URL | Request, init?: RequestInit) => { const url = String(input); requests.push({ headers: new Headers(init?.headers), url, redirect: init?.redirect }); return Response.json( - url.endsWith('/.well-known/void-platform') + url.endsWith('/.well-known/void-platform') || url === 'https://email.example.com/health' ? { installationId: 'example-a1b2c3d4', platformVersion: '1.2.3', usageProtocolVersion: 1, + emailProtocolVersion: 1, } : { ok: true }, ); @@ -1443,6 +1445,8 @@ describe('platform installer', () => { 1, 'probe-token', fetcher, + undefined, + { accountName: 'Example', workers: [], emailGatewayUrl: 'https://email.example.com' }, ); expect(requests.map((entry) => entry.url)).toEqual([ @@ -1450,6 +1454,7 @@ describe('platform installer', () => { 'https://api.example.com/.well-known/void-platform', 'https://proxy.example.com/health', 'https://test.apps.example.com/health', + 'https://email.example.com/health', ]); expect( requests.every((entry) => entry.headers.get('X-Void-Platform-Probe') === 'probe-token'), @@ -1721,6 +1726,38 @@ describe('platform installer', () => { ).rejects.toThrow('Proxy health check failed'); }); + it.each([ + { failure: 'unavailable', status: 503, body: {} }, + { failure: 'foreign installation', status: 200, body: { installationId: 'other' } }, + { failure: 'stale version', status: 200, body: { platformVersion: '1.2.2' } }, + { failure: 'unsupported protocol', status: 200, body: { emailProtocolVersion: 2 } }, + ])('rejects an email gateway that is $failure before cutover', async ({ status, body }) => { + const identity = { + installationId: 'example-a1b2c3d4', + platformVersion: '1.2.3', + usageProtocolVersion: 1, + emailProtocolVersion: 1, + }; + const fetcher = (async (input: string | URL | Request) => + String(input) === 'https://email.example.com/health' + ? Response.json({ ...identity, ...body }, { status }) + : Response.json(identity)) as typeof fetch; + await expect( + verifyPlatformHealth( + 'https://api.example.com', + identity.installationId, + 'https://proxy.example.com', + 'apps.example.com', + identity.platformVersion, + 1, + 'probe-token', + fetcher, + undefined, + { accountName: 'Example', workers: [], emailGatewayUrl: 'https://email.example.com' }, + ), + ).rejects.toThrow(/email gateway/i); + }); + it('requires live PostgreSQL migration history to be an exact package prefix', async () => { const database = readPlatformRuntimeManifest().database; const first = database.migrations[0]!; @@ -4600,6 +4637,20 @@ describe('platform installer', () => { 'staged-proxy', ), }, + { + completedAt: '2026-09-14T00:00:06.000Z', + key: 'worker-cutover:999:staged:emailGateway', + resultHash: cutoverSnapshot( + deployment.resources.emailGatewayWorker, + 'previous-email', + 'staged-email', + ), + }, + { + completedAt: '2026-09-14T00:00:06.000Z', + key: 'worker-cutover:999:unsafe-traffic:emailGateway', + resultHash: deployment.resources.emailGatewayWorker, + }, { completedAt: '2026-09-14T00:00:06.000Z', key: 'worker-cutover:999:unsafe-traffic:proxy', @@ -4637,8 +4688,9 @@ describe('platform installer', () => { recoveryEvents.push('verify-cutover'); }, }); - expect(recoveryEvents.slice(0, 3)).toEqual([ + expect(recoveryEvents.slice(0, 4)).toEqual([ `put:${PLATFORM_DISABLED_KEY}`, + 'recover:emailGateway:previous-email:staged-email:true', 'recover:proxy:previous-proxy:staged-proxy:true', 'recover:api:previous-api:staged-api:false', ]); diff --git a/packages/void/test/unit/platform-runtime.test.ts b/packages/void/test/unit/platform-runtime.test.ts index 7b6fe79e4..2fd389a34 100644 --- a/packages/void/test/unit/platform-runtime.test.ts +++ b/packages/void/test/unit/platform-runtime.test.ts @@ -112,6 +112,9 @@ describe('platform runtime manifest', () => { expect(parsePlatformRuntimeManifest(legacySafety).safetyProtocols).toEqual({ sandboxDrain: 0 }); const { emailGateway: _gateway, ...fourArtifacts } = manifest.artifacts; const { emailProtocolVersion: _emailProtocolVersion, ...preEmailRuntime } = manifest; + expect(() => parsePlatformRuntimeManifest(preEmailRuntime)).toThrow( + 'An emailGateway runtime artifact requires email protocol version 1', + ); expect( parsePlatformRuntimeManifest({ ...preEmailRuntime, diff --git a/platform/meta/design-docs/0078-email-cf-native.md b/platform/meta/design-docs/0078-email-cf-native.md index fc551c0b4..74f87b97e 100644 --- a/platform/meta/design-docs/0078-email-cf-native.md +++ b/platform/meta/design-docs/0078-email-cf-native.md @@ -367,6 +367,14 @@ failure leaves a retryable cleanup operation, including after project teardown. Removal never discards an unresolved cleanup record; its operation remains visible until the provider resources have been reconciled. +Recipient consent removal follows the same durability rule. Commit revocation and +cleanup intent together, then delete an unreferenced Cloudflare destination outside +the transaction. Fence registration against that immutable provider tag before +deletion starts, including registrations that read the tag before revocation. +Retain a recipient-free tag tombstone after cleanup so a late registration cannot +restore a reference to a deleted destination. Failed provider cleanup is retried; +a sibling project's live reference prevents account-level deletion. + ## Bounded tenant execution Cloudflare's native email message is not an RPC-serializable application object. @@ -528,6 +536,12 @@ expires, containing only its opaque ID, project, sender domain and start time. That fence must contain no recipient address or message content. A completed `outcome_unknown` remains non-replayable but no longer represents an active call that must block resource cleanup. +An administrator can list unresolved active-call fences and, after confirming +the original Worker execution has ended and at least 24 hours have elapsed, +resolve one as `outcome_unknown` with an audited reason. Resolution is atomic +with removing the fence, retains the recipient-attempt charge, and never +replays the provider call. If the 30-day delivery record has expired, only the +PII-free fence is removed. Elapsed time by itself never resolves an attempt. Analytics, searchable message content and a hosted mailbox remain out of scope. `void email logs` becomes a view over this ledger, with receipt/action IDs that diff --git a/platform/packages/api/drizzle/0047_email_gateway.sql b/platform/packages/api/drizzle/0047_email_gateway.sql index af0952b1d..e5d9305d2 100644 --- a/platform/packages/api/drizzle/0047_email_gateway.sql +++ b/platform/packages/api/drizzle/0047_email_gateway.sql @@ -205,4 +205,18 @@ CREATE INDEX "idx_email_action_recipients_project_reserved" ON "email_action_rec CREATE INDEX "idx_email_actions_project_created" ON "email_actions" USING btree ("project_id","created_at");--> statement-breakpoint CREATE INDEX "idx_email_receipts_project_created" ON "email_receipts" USING btree ("project_id","created_at");--> statement-breakpoint CREATE INDEX "idx_email_unresolved_attempts_project" ON "email_unresolved_attempts" USING btree ("project_id");--> statement-breakpoint -CREATE INDEX "idx_email_unresolved_attempts_domain" ON "email_unresolved_attempts" USING btree ("sender_domain"); \ No newline at end of file +CREATE INDEX "idx_email_unresolved_attempts_domain" ON "email_unresolved_attempts" USING btree ("sender_domain"); +--> statement-breakpoint +CREATE TABLE "email_destination_cleanups" ( + "cf_destination_id" text PRIMARY KEY NOT NULL, + "status" text DEFAULT 'pending' NOT NULL, + "attempts" integer DEFAULT 0 NOT NULL, + "next_attempt_at" timestamp with time zone DEFAULT now() NOT NULL, + "lease_started_at" timestamp with time zone, + "created_at" timestamp with time zone DEFAULT now() NOT NULL, + "updated_at" timestamp with time zone DEFAULT now() NOT NULL, + CONSTRAINT "email_destination_cleanups_status_check" CHECK ("email_destination_cleanups"."status" IN ('pending', 'deleting', 'completed')), + CONSTRAINT "email_destination_cleanups_attempts_check" CHECK ("email_destination_cleanups"."attempts" >= 0) +); +--> statement-breakpoint +CREATE INDEX "idx_email_destination_cleanups_due" ON "email_destination_cleanups" USING btree ("status","next_attempt_at","updated_at"); diff --git a/platform/packages/api/drizzle/meta/0047_snapshot.json b/platform/packages/api/drizzle/meta/0047_snapshot.json index 5c2d04b83..424a8733a 100644 --- a/platform/packages/api/drizzle/meta/0047_snapshot.json +++ b/platform/packages/api/drizzle/meta/0047_snapshot.json @@ -593,6 +593,103 @@ "checkConstraints": {}, "isRLSEnabled": false }, + "public.email_destination_cleanups": { + "name": "email_destination_cleanups", + "schema": "", + "columns": { + "cf_destination_id": { + "name": "cf_destination_id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "status": { + "name": "status", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'pending'" + }, + "attempts": { + "name": "attempts", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "next_attempt_at": { + "name": "next_attempt_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "lease_started_at": { + "name": "lease_started_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "idx_email_destination_cleanups_due": { + "name": "idx_email_destination_cleanups_due", + "columns": [ + { + "expression": "status", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "next_attempt_at", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "updated_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "email_destination_cleanups_status_check": { + "name": "email_destination_cleanups_status_check", + "value": "\"email_destination_cleanups\".\"status\" IN ('pending', 'deleting', 'completed')" + }, + "email_destination_cleanups_attempts_check": { + "name": "email_destination_cleanups_attempts_check", + "value": "\"email_destination_cleanups\".\"attempts\" >= 0" + } + }, + "isRLSEnabled": false + }, "public.email_destinations": { "name": "email_destinations", "schema": "", diff --git a/platform/packages/api/src/admin/routes/email.tsx b/platform/packages/api/src/admin/routes/email.tsx index 27ecde81e..eae0dd23e 100644 --- a/platform/packages/api/src/admin/routes/email.tsx +++ b/platform/packages/api/src/admin/routes/email.tsx @@ -1,14 +1,9 @@ import { asc, desc, eq, gte, inArray, sql } from 'drizzle-orm'; import { Hono, type Context } from 'hono'; import { getPlatformCapabilities } from '../../capabilities.ts'; +import { deleteEmailDestination, getEmailDestinationsByProjectId, getProject } from '../../db.ts'; import { - countProjectsUsingDestination, - deleteEmailDestination, - getEmailDestinationsByProjectId, - getProject, -} from '../../db.ts'; -import { - emailActionRecipients, + emailMonthlyUsage, emailProjectControls, emailReceipts, } from '../../email/admission-schema.ts'; @@ -37,7 +32,7 @@ import type { ApiEnv } from '../../env.ts'; import { executeAuditedMutation, operatorAuditIntent } from '../../operator/audit.ts'; import { OperatorError } from '../../operator/common.ts'; import { setOperatorEmailPolicy, setOperatorEmailSettings } from '../../operator/email-routes.ts'; -import { deleteDestination } from '../../provisioning/email-routing.ts'; +import { runEmailDestinationCleanup } from '../../provisioning/email-destination-cleanup.ts'; import { renderOperationError } from '../operation-error.tsx'; import { EmailSettingsPage } from '../views/email-settings.tsx'; import { STATUS_COLORS, formatDateTime } from '../views/format.ts'; @@ -124,10 +119,10 @@ app.get('/:projectId', async (context) => { const [sentRows, receivedRows, controls, destinations, domainRows] = await Promise.all([ context .get('db') - .select({ count: sql`count(*)::int` }) - .from(emailActionRecipients) + .select({ count: emailMonthlyUsage.recipient_attempts }) + .from(emailMonthlyUsage) .where( - sql`${emailActionRecipients.project_id} = ${projectId} AND ${emailActionRecipients.state} IN ('reserved','attempt_started','provider_accepted','failed','outcome_unknown') AND ${emailActionRecipients.reserved_at} >= ${monthStart}::timestamptz`, + sql`${emailMonthlyUsage.project_id} = ${projectId} AND ${emailMonthlyUsage.month} = ${month}`, ), context .get('db') @@ -579,31 +574,13 @@ app.post('/:projectId/destinations/:destId/delete', async (context) => { if (!destination) { return context.html('

Destination not found

', 404); } - await deleteEmailDestination(context.get('db'), destination.id); - // The Cloudflare destination address is account-level, so deleting it would - // revoke the address for every project that shares it. Only the last - // referencing project may remove it upstream. - if (destination.cf_destination_id) { - const references = await countProjectsUsingDestination( + const cleanupTag = await deleteEmailDestination(context.get('db'), destination.id); + if (cleanupTag) { + await runEmailDestinationCleanup( context.get('db'), - destination.cf_destination_id, + { accountId: context.env.CF_ACCOUNT_ID, apiToken: context.env.CF_API_TOKEN }, + cleanupTag, ); - if (references === 0) { - try { - await deleteDestination( - context.env.CF_ACCOUNT_ID, - context.env.CF_API_TOKEN, - destination.cf_destination_id, - ); - } catch (error) { - // Best effort: the committed SQL revocation already denies sends. - console.error('[admin-email] CF deleteDestination failed', { - projectId, - destinationId, - error, - }); - } - } } return context.redirect(`/admin/email/${projectId}`); }); diff --git a/platform/packages/api/src/db.ts b/platform/packages/api/src/db.ts index 2ccf79e72..9e77b1631 100644 --- a/platform/packages/api/src/db.ts +++ b/platform/packages/api/src/db.ts @@ -32,6 +32,7 @@ import { resources, domains, emailDestinations, + emailDestinationCleanups, platformEvents, invitations, oauthNonces, @@ -1572,51 +1573,12 @@ export interface OwnerVerificationAudit { } /** - * Insert a destination row, returning whether THIS call did the insert. + * RETURNING identifies the sole inserter so only it sends a verification email. + * A missing row means it was concurrently deleted; callers must retry. * - * Uses ON CONFLICT DO NOTHING + RETURNING so the inserter is - * unambiguously identified. Two concurrent POSTs for the same - * (project_id, address) would otherwise both pass through - * `createEmailDestination` + the unique-constraint catch — but the loser - * would then read back the winner's pending/platform row and ALSO fire a - * platform-side verification email. With `inserted=false`, the route can - * correctly gate the email send on the inserter only. - * - * Returns: - * { row, inserted: true } — this call did the INSERT. - * { row, inserted: false } — a sibling call already inserted; we read - * back their row. - * { row: null } — extremely unlikely race where the row was - * deleted between insert-failure and select. - * Caller must treat as a hard error. - * { row: null, ownerEmailChanged: true } - * — `ownerAudit` was given but the owner no - * longer holds `emailSnapshot`; nothing was - * written. See below. - * - * With `ownerAudit`, the insert runs in one transaction behind - * `SELECT … FOR SHARE` on the owner's `users` row and happens only while - * `users.email` still equals the snapshot. The consent an Option C row - * inherits is "this address IS the owner's", and the login callback - * (`updateUserRevokingInheritedDestinations` in `routes/auth.ts`) retires - * exactly these rows when that stops being true — but it can only retire - * rows that exist when it runs. Both callers decide to inherit from an - * unlocked read of the owner's email (the auto-add before its unbounded - * Cloudflare call, the POST's owner branch after it), so a login that - * rotates the address between that read and this insert commits first, - * finds nothing, and the insert would then land a `verified` grant for - * the old mailbox attributed to the old identity; every later login - * compares equal and never looks again. The lock is - * what makes this a real gate under READ COMMITTED: a plain re-read does - * not see the login's uncommitted `UPDATE users`, whereas `FOR SHARE` - * conflicts with the `FOR NO KEY UPDATE` that write takes (`email` is not - * in a unique index), so this either waits for the login and re-reads the - * rotated address, or holds the login until this row is committed and - * visible to its revoke. The `projects` row is locked FIRST, in the - * strength the INSERT's foreign key would take anyway, to keep the - * `projects → users` lock order the build transactions use - * (`createGithubActionsBuildWithinLimit`); taking `users` first deadlocks - * against them. + * Inherited owner consent requires a FOR SHARE lock on users: an email change + * must either commit before this check or revoke the inserted row afterward. + * Lock projects first to match build transactions and avoid a lock-order cycle. */ export async function tryCreateEmailDestination( db: Db, @@ -1646,7 +1608,17 @@ export async function tryCreateEmailDestination( verified_by_user_id: ownerAudit?.userId ?? null, verified_by_email_snapshot: ownerAudit?.emailSnapshot ?? null, }; - const insertRow = async (via: Db): Promise => { + const insertRow = async (via: DbOrTx): Promise => { + if (cfDestinationId) { + const [retired] = await via + .select({ id: emailDestinationCleanups.cf_destination_id }) + .from(emailDestinationCleanups) + .where(eq(emailDestinationCleanups.cf_destination_id, cfDestinationId)) + .limit(1); + if (retired) { + return undefined; + } + } const [row] = await via .insert(emailDestinations) .values(values) @@ -1656,24 +1628,35 @@ export async function tryCreateEmailDestination( }; let inserted: EmailDestination | undefined; if (!ownerAudit) { - inserted = await db.transaction(async (tx) => { + const outcome = await db.transaction(async (tx) => { await lockEmailPolicy(tx); - await tx - .select({ id: projects.id }) + const [project] = await tx + .select({ status: projects.status }) .from(projects) .where(eq(projects.id, projectId)) - .for('update'); - return insertRow(tx as unknown as Db); + .for('update') + .limit(1); + if (!project || project.status === 'deleting') { + return 'project-unavailable' as const; + } + return insertRow(tx); }); + if (outcome === 'project-unavailable') { + return { row: null, inserted: false }; + } + inserted = outcome; } else { const outcome = await db.transaction(async (tx) => { await lockEmailPolicy(tx); - await tx - .select({ id: projects.id }) + const [project] = await tx + .select({ status: projects.status }) .from(projects) .where(eq(projects.id, projectId)) .for('update') .limit(1); + if (!project || project.status === 'deleting') { + return 'project-unavailable' as const; + } const [owner] = await tx .select({ email: users.email }) .from(users) @@ -1683,78 +1666,25 @@ export async function tryCreateEmailDestination( if ((owner?.email?.toLowerCase() ?? null) !== ownerAudit.emailSnapshot.toLowerCase()) { return 'owner-email-changed'; } - return insertRow(tx as unknown as Db); + return insertRow(tx); }); if (outcome === 'owner-email-changed') { return { row: null, inserted: false, ownerEmailChanged: true }; } + if (outcome === 'project-unavailable') { + return { row: null, inserted: false }; + } inserted = outcome; } if (inserted) { return { row: inserted, inserted: true }; } - // ON CONFLICT DO NOTHING didn't return a row, which means a sibling - // request inserted concurrently. Read it back — outside the transaction - // above, which has nothing left to write once the insert found a - // conflict. If the sibling DELETED their own row between insert-failure - // and select (extremely unlikely — only the project owner can DELETE), - // we return `{ row: null }`. The caller treats that as "concurrently - // modified, retry once". + // A concurrent insert may have won, or cleanup retired the provider tag. + // Return an existing project row if present; otherwise the caller retries. const existing = await getEmailDestinationByAddress(db, projectId, address); return { row: existing, inserted: false }; } -export async function createEmailDestination( - db: Db, - projectId: string, - address: string, - cfDestinationId: string | null, - status: EmailDestination['status'] = 'pending', - /** - * Audit timestamp. Pass CF's `verified` field when recovering an - * already-verified destination so the audit trail reflects the real - * verification time rather than local now(). Omit / pass null to use - * now() when status is verified. - */ - verifiedAt?: string | null, - /** - * 'cf' — the CF Email Routing verification email is the source of - * truth (the default; covers fresh adds AND owner-relaxed - * reuse, where the project owner had already verified the - * address on a prior project). - * 'platform' — CF already had the address verified by a different - * project. We're issuing our own confirmation email; the - * row stays 'pending' until that link is clicked. - * - * Defaults to 'cf' to preserve the historical create-path behavior. - */ - verificationSource: EmailDestination['verification_source'] = 'cf', - /** - * Audit columns for owner-relaxed CF reuse (Option C). See - * `tryCreateEmailDestination` for the populate / NULL rules. - */ - ownerAudit?: OwnerVerificationAudit, -): Promise { - const id = generateId('edst'); - const resolvedVerifiedAt = - status === 'verified' ? (verifiedAt ?? new Date().toISOString()) : null; - const [row] = await db - .insert(emailDestinations) - .values({ - id, - project_id: projectId, - address: address.toLowerCase(), - cf_destination_id: cfDestinationId, - status, - verified_at: resolvedVerifiedAt, - verification_source: verificationSource, - verified_by_user_id: ownerAudit?.userId ?? null, - verified_by_email_snapshot: ownerAudit?.emailSnapshot ?? null, - }) - .returning(); - return row; -} - /** * Revoke owner-inherited CF verification when the project owner's email * identity changes (e.g. OAuth email update on a re-link). @@ -1852,19 +1782,6 @@ export async function getEmailDestinationsByProjectId( .orderBy(asc(emailDestinations.created_at)); } -export async function getVerifiedEmailDestinationsByProjectId( - db: Db, - projectId: string, -): Promise> { - return db - .select() - .from(emailDestinations) - .where( - and(eq(emailDestinations.project_id, projectId), eq(emailDestinations.status, 'verified')), - ) - .orderBy(asc(emailDestinations.created_at)); -} - export async function getEmailDestinationByAddress( db: Db, projectId: string, @@ -1916,7 +1833,7 @@ export async function updateEmailDestinationStatus( * preserve the existing source value rather than overwriting it. */ verificationSource?: EmailDestination['verification_source'], -): Promise { +): Promise { const patch: { status: EmailDestination['status']; verified_at?: string | null; @@ -1940,35 +1857,55 @@ export async function updateEmailDestinationStatus( .where(eq(emailDestinations.id, id)) .limit(1); if (!existing) { - return; + return false; } - await db.transaction(async (tx) => { + return db.transaction(async (tx) => { await lockEmailPolicy(tx); await tx .select({ id: projects.id }) .from(projects) .where(eq(projects.id, existing.project_id)) .for('update'); - await tx + if (cfDestinationId) { + const [retired] = await tx + .select({ id: emailDestinationCleanups.cf_destination_id }) + .from(emailDestinationCleanups) + .where(eq(emailDestinationCleanups.cf_destination_id, cfDestinationId)) + .limit(1); + if (retired) { + return false; + } + } + const updated = await tx .update(emailDestinations) .set(patch) .where( and(eq(emailDestinations.id, id), eq(emailDestinations.project_id, existing.project_id)), - ); + ) + .returning({ id: emailDestinations.id }); + return updated.length > 0; }); } -export async function deleteEmailDestination(db: Db, id: string): Promise { - const [existing] = await db - .select({ project_id: emailDestinations.project_id }) - .from(emailDestinations) - .where(eq(emailDestinations.id, id)) - .limit(1); - if (!existing) { - return; - } - await db.transaction(async (tx) => { +async function queueDestinationCleanupTx(tx: Tx, cfDestinationId: string): Promise { + await tx + .insert(emailDestinationCleanups) + .values({ cf_destination_id: cfDestinationId }) + .onConflictDoNothing(); +} + +/** Revoke one project's consent and durably queue the last provider tag. */ +export async function deleteEmailDestination(db: Db, id: string): Promise { + return db.transaction(async (tx) => { await lockEmailPolicy(tx); + const [existing] = await tx + .select() + .from(emailDestinations) + .where(eq(emailDestinations.id, id)) + .for('update'); + if (!existing) { + return null; + } await tx .select({ id: projects.id }) .from(projects) @@ -1979,23 +1916,71 @@ export async function deleteEmailDestination(db: Db, id: string): Promise .where( and(eq(emailDestinations.id, id), eq(emailDestinations.project_id, existing.project_id)), ); + if (!existing.cf_destination_id) { + return null; + } + const [references] = await tx + .select({ n: countDistinct(emailDestinations.project_id) }) + .from(emailDestinations) + .where(eq(emailDestinations.cf_destination_id, existing.cf_destination_id)); + if (Number(references?.n ?? 0) !== 0) { + return null; + } + await queueDestinationCleanupTx(tx, existing.cf_destination_id); + return existing.cf_destination_id; }); } -/** - * How many DISTINCT projects still reference a CF destination. CF - * destinations are account-level, so the CF-side address may only be - * deleted once the last project stops referencing it. - */ -export async function countProjectsUsingDestination( +/** Revoke all project consent rows and queue provider tags with no live sibling. */ +export async function deleteProjectEmailDestinations( + db: Db, + projectId: string, +): Promise> { + return db.transaction(async (tx) => { + await lockEmailPolicy(tx); + await tx + .select({ id: projects.id }) + .from(projects) + .where(eq(projects.id, projectId)) + .for('update'); + const rows = await tx + .select() + .from(emailDestinations) + .where(eq(emailDestinations.project_id, projectId)) + .for('update'); + await tx.delete(emailDestinations).where(eq(emailDestinations.project_id, projectId)); + const queued: Array = []; + for (const tag of new Set(rows.map((row) => row.cf_destination_id).filter(Boolean))) { + const [references] = await tx + .select({ n: countDistinct(emailDestinations.project_id) }) + .from(emailDestinations) + .where(eq(emailDestinations.cf_destination_id, tag!)); + if (Number(references?.n ?? 0) === 0) { + await queueDestinationCleanupTx(tx, tag!); + queued.push(tag!); + } + } + return queued; + }); +} + +/** Queue an allocated tag that never gained a SQL consent row. */ +export async function queueUnreferencedEmailDestinationCleanup( db: Db, cfDestinationId: string, -): Promise { - const result = await db - .select({ n: countDistinct(emailDestinations.project_id) }) - .from(emailDestinations) - .where(eq(emailDestinations.cf_destination_id, cfDestinationId)); - return Number(result[0]?.n ?? 0); +): Promise { + return db.transaction(async (tx) => { + await lockEmailPolicy(tx); + const [references] = await tx + .select({ n: countDistinct(emailDestinations.project_id) }) + .from(emailDestinations) + .where(eq(emailDestinations.cf_destination_id, cfDestinationId)); + if (Number(references?.n ?? 0) !== 0) { + return false; + } + await queueDestinationCleanupTx(tx, cfDestinationId); + return true; + }); } /** @@ -2041,6 +2026,14 @@ export async function promoteEmailDestinationWithOwnerAudit( .where(eq(projects.id, projectId)) .for('update') .limit(1); + const [retired] = await tx + .select({ id: emailDestinationCleanups.cf_destination_id }) + .from(emailDestinationCleanups) + .where(eq(emailDestinationCleanups.cf_destination_id, cfDestinationId)) + .limit(1); + if (retired) { + return false; + } const [owner] = await tx .select({ email: users.email }) .from(users) diff --git a/platform/packages/api/src/email/admission.ts b/platform/packages/api/src/email/admission.ts index 68a9d0675..835386fb3 100644 --- a/platform/packages/api/src/email/admission.ts +++ b/platform/packages/api/src/email/admission.ts @@ -58,6 +58,95 @@ export class EmailAdmissionError extends Error { } } +/** Operator recovery is never based on elapsed time alone. This excludes recent calls. */ +export const EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS = 24 * 60 * 60 * 1_000; + +export async function resolveEmailUnresolvedAttempt( + db: Db, + input: { id: string; ended: boolean; reason: string; now?: Date }, +) { + if (!/^[a-zA-Z0-9_-]{1,128}$/.test(input.id)) { + throw new EmailAdmissionError('INVALID_REQUEST', 'invalid email attempt ID'); + } + if (input.ended !== true || !input.reason.trim() || input.reason.length > 500) { + throw new EmailAdmissionError( + 'INVALID_REQUEST', + 'confirm that the original execution ended and supply a reason of at most 500 characters', + ); + } + const now = input.now ?? new Date(); + return db.transaction(async (tx) => { + // Finishing a send locks the action before deleting its fence. Match that + // order so a late provider response and operator resolution cannot race. + const [initialFence] = await tx + .select() + .from(emailUnresolvedAttempts) + .where(eq(emailUnresolvedAttempts.id, input.id)) + .limit(1); + if (!initialFence) { + throw new EmailAdmissionError('NOT_FOUND', 'unresolved email attempt not found'); + } + const [initialRecipient] = await tx + .select({ actionId: emailActionRecipients.action_id }) + .from(emailActionRecipients) + .where(eq(emailActionRecipients.id, input.id)) + .limit(1); + const [action] = initialRecipient + ? await tx + .select({ projectId: emailActions.project_id, senderDomain: emailActions.sender_domain }) + .from(emailActions) + .where(eq(emailActions.id, initialRecipient.actionId)) + .for('update') + : []; + const [fence] = await tx + .select() + .from(emailUnresolvedAttempts) + .where(eq(emailUnresolvedAttempts.id, input.id)) + .for('update'); + if (!fence) { + throw new EmailAdmissionError('NOT_FOUND', 'unresolved email attempt not found'); + } + if (new Date(fence.started_at).getTime() > now.getTime() - EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS) { + throw new EmailAdmissionError('INVALID_STATE', 'email attempt is too recent to resolve'); + } + const [recipient] = await tx + .select() + .from(emailActionRecipients) + .where(eq(emailActionRecipients.id, input.id)) + .for('update'); + if (recipient) { + if ( + recipient.state !== 'attempt_started' || + recipient.project_id !== fence.project_id || + action?.projectId !== fence.project_id || + action?.senderDomain !== fence.sender_domain || + new Date(recipient.attempt_started_at ?? now).getTime() > + now.getTime() - EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS + ) { + throw new EmailAdmissionError('INVALID_STATE', 'email attempt ledger disagrees with fence'); + } + await tx + .update(emailActionRecipients) + .set({ + state: 'outcome_unknown', + error_code: 'OUTCOME_UNKNOWN', + completed_at: now.toISOString(), + }) + .where(eq(emailActionRecipients.id, input.id)); + } + await tx.delete(emailUnresolvedAttempts).where(eq(emailUnresolvedAttempts.id, input.id)); + return { + id: fence.id, + projectId: fence.project_id, + senderDomain: fence.sender_domain, + startedAt: fence.started_at, + state: 'outcome_unknown' as const, + metadataExpired: !recipient, + charged: true, + }; + }); +} + /** Policy mutations take this exclusive lock; admission takes it shared. */ export async function lockEmailPolicy(tx: Tx): Promise { await tx.execute(sql`select pg_advisory_xact_lock(hashtext('email-admission:policy'))`); @@ -250,7 +339,7 @@ export async function admitEmailAction( throw new EmailAdmissionError('INVALID_REQUEST', 'invalid email transport'); } let senderAllowed = false; - let verifiedOnlyTransport = false; + let verifiedOnlyTransport = input.transport === 'native_forward'; if (shared) { senderAllowed = !isReservedEmailSlug(project.slug) && @@ -914,4 +1003,7 @@ export async function pruneEmailActionHistory( ${emailActions.created_at} < ${before.toISOString()} `); await db.delete(emailReceipts).where(sql`${emailReceipts.created_at} < ${before.toISOString()}`); + await db.delete(emailMonthlyUsage).where(sql` + ${emailMonthlyUsage.month} < ${new Date().toISOString().slice(0, 7)} + `); } diff --git a/platform/packages/api/src/email/cf-domain-probes.ts b/platform/packages/api/src/email/cf-domain-probes.ts index e2a6b7ff5..94cb0b212 100644 --- a/platform/packages/api/src/email/cf-domain-probes.ts +++ b/platform/packages/api/src/email/cf-domain-probes.ts @@ -10,8 +10,13 @@ export async function lookupMxOverDns(domain: string): Promise; }; + if ((json.Status !== 0 && json.Status !== 3) || json.TC) { + throw new Error('public DNS MX lookup did not return a complete answer'); + } return (json.Answer ?? []) .filter((answer) => answer.type === 15) .map((answer) => answer.data.trim().split(/\s+/).slice(1).join(' ').replace(/\.$/, '')); @@ -23,14 +28,10 @@ export async function sendingOnboardedReadback( zoneId: string, domain: string, ): Promise { - try { - const subdomains = await client.listSendingSubdomains(zoneId); - return subdomains.some( - (subdomain) => subdomain.enabled && subdomain.name.toLowerCase() === domain.toLowerCase(), - ); - } catch { - return false; - } + const subdomains = await client.listSendingSubdomains(zoneId); + return subdomains.some( + (subdomain) => subdomain.enabled && subdomain.name.toLowerCase() === domain.toLowerCase(), + ); } /** Find the deepest visible Cloudflare zone containing a domain. */ diff --git a/platform/packages/api/src/email/connection-service.ts b/platform/packages/api/src/email/connection-service.ts index 8cb15e4f3..c1511b316 100644 --- a/platform/packages/api/src/email/connection-service.ts +++ b/platform/packages/api/src/email/connection-service.ts @@ -451,10 +451,17 @@ export async function inspectEmailInboundRoute( connection: Pick, domain: string, ): Promise { - const [catchall, rules] = await Promise.all([ + const [catchall, rules, exchanges] = await Promise.all([ client.getCatchAll(connection.zone_id), client.listRoutingRules(connection.zone_id), + lookupMxOverDns(domain), ]); + if ( + !exchanges.length || + exchanges.some((exchange) => !/\.mx\.cloudflare\.net$/i.test(exchange)) + ) { + return `MX records for ${domain} do not route mail to Cloudflare Email Routing`; + } if (!catchall?.enabled || catchall.workerName !== connection.ingress_worker_name) { return 'zone catch-all does not point to this ingress'; } @@ -2082,9 +2089,15 @@ export async function reconcilePendingEmailOperations( .select({ id: emailOperations.id, status: emailOperations.status }) .from(emailOperations) .where(inArray(emailOperations.status, ['pending', 'running', 'unknown'])) - .orderBy(emailOperations.created_at) + .orderBy(emailOperations.updated_at, emailOperations.id) .limit(limit); for (const row of rows) { + // Ambiguous writes may need human recovery. Rotate visits so they cannot + // occupy every batch slot forever; step.started_at still owns its lease. + await db + .update(emailOperations) + .set({ updated_at: sql`now()` }) + .where(eq(emailOperations.id, row.id)); if (row.status === 'unknown') { await reconcileUnknownEmailOperation(db, env, row.id); } diff --git a/platform/packages/api/src/email/domain-service.ts b/platform/packages/api/src/email/domain-service.ts index 46d887ead..5a9a45feb 100644 --- a/platform/packages/api/src/email/domain-service.ts +++ b/platform/packages/api/src/email/domain-service.ts @@ -241,7 +241,10 @@ export async function getEmailDomainStatusForProject( ); } }); - resolved = (await resolveEmailDomain(db, rawDomain))!; + resolved = await resolveEmailDomain(db, rawDomain); + if (!resolved || resolved.route.project_id !== project.id) { + return context.json({ error: 'email domain not found' }, 404); + } } const op = ( await context @@ -314,7 +317,7 @@ export async function rotateEmailIngressSecretForProject( .limit(1) )[0]; const current = await resolveEmailDomain(context.get('db'), rawDomain); - if (!current) { + if (!current || current.route.project_id !== project.id) { return context.json({ error: 'email domain not found' }, 404); } return context.json({ @@ -373,7 +376,7 @@ export async function getEmailOperationForProject( return context.json({ error: 'email operation not found' }, 404); } const resolved = await resolveEmailDomain(context.get('db'), found.route.domain); - if (!resolved) { + if (!resolved || resolved.route.project_id !== project.id) { return context.json({ error: 'email domain not found' }, 404); } const domain = serializeEmailRoute(resolved.route, resolved.connection); diff --git a/platform/packages/api/src/email/ingress-resolution.ts b/platform/packages/api/src/email/ingress-resolution.ts index 17152da9c..e63918651 100644 --- a/platform/packages/api/src/email/ingress-resolution.ts +++ b/platform/packages/api/src/email/ingress-resolution.ts @@ -3,7 +3,10 @@ import { Hono } from 'hono'; import { hmacVerifyState } from '../auth/hmac.ts'; import type { ApiEnv } from '../env.ts'; import { getVersionedWorkerName } from '../project-secrets.ts'; +import { computeDispatchLimits } from '../routing.ts'; import { deployments, projects, users } from '../schema.ts'; +import { getPlanLimits } from '../tiers.ts'; +import type { DeployManifest } from '../types.ts'; import { emailProjectControls } from './admission-schema.ts'; import { emailZoneConnections } from './connection-schema.ts'; import { @@ -249,6 +252,7 @@ app.post('/resolve-ingress', async (context) => { .select({ projectStatus: projects.status, suspendedReason: users.suspended_reason, + plan: users.plan, emailSuspendedAt: emailProjectControls.suspended_at, }) .from(projects) @@ -283,20 +287,19 @@ app.post('/resolve-ingress', async (context) => { .where(and(eq(deployments.id, deploymentId), eq(deployments.project_id, projectId!))) .limit(1) )[0]; - let protocolVersion: unknown; + let manifest: Pick | null; try { - protocolVersion = deployment?.manifest - ? JSON.parse(deployment.manifest).emailProtocolVersion - : null; + manifest = deployment?.manifest ? JSON.parse(deployment.manifest) : null; } catch { - protocolVersion = null; + manifest = null; } - if (deployment?.status !== 'live' || protocolVersion !== 1) { + if (deployment?.status !== 'live' || manifest?.emailProtocolVersion !== 1) { return context.json( { error: 'active deployment does not support email gateway protocol' }, 409, ); } + const limits = computeDispatchLimits(getPlanLimits(authority.plan), manifest.limits); return context.json({ projectId, slug, @@ -305,6 +308,7 @@ app.post('/resolve-ingress', async (context) => { addressing: route.addressing, domain: route.domain, connectionId: resolved.connection.id, + ...(limits ? { limits } : {}), }); }); diff --git a/platform/packages/api/src/email/settings.ts b/platform/packages/api/src/email/settings.ts index e8b35763a..fbc856539 100644 --- a/platform/packages/api/src/email/settings.ts +++ b/platform/packages/api/src/email/settings.ts @@ -25,11 +25,6 @@ export const DEFAULT_EMAIL_RECIPIENT_POLICY: EmailRecipientPolicy = { export const MAX_POLICY_DOMAINS = 100; const POLICY_MODES: ReadonlyArray = ['verified', 'domains', 'any']; -const MODE_RANK: Readonly> = { - verified: 0, - domains: 1, - any: 2, -}; const MANAGEMENT_MODES: ReadonlyArray = ['self-serve', 'admin']; export class EmailSettingsError extends Error { @@ -95,25 +90,6 @@ export function normalizeEmailRecipientPolicy(input: unknown): EmailRecipientPol return { mode: 'domains', domains: [...normalized].sort() }; } -/** - * True when `next` lets through anything `prev` did not: a higher mode, or - * a `domains` list that gains a domain — even one that also drops others. - * Only a lower mode or a pure shrink is a tightening. - */ -export function widensEmailRecipientPolicy( - prev: EmailRecipientPolicy, - next: EmailRecipientPolicy, -): boolean { - if (next.mode !== prev.mode) { - return MODE_RANK[next.mode] > MODE_RANK[prev.mode]; - } - if (next.mode !== 'domains') { - return false; - } - const before = new Set(prev.domains); - return next.domains.some((domain) => !before.has(domain)); -} - function readStoredPolicy(value: unknown): EmailRecipientPolicy | null { try { return normalizeEmailRecipientPolicy(value); diff --git a/platform/packages/api/src/index.ts b/platform/packages/api/src/index.ts index bbf92ac85..a3b873b83 100644 --- a/platform/packages/api/src/index.ts +++ b/platform/packages/api/src/index.ts @@ -75,6 +75,7 @@ import { deleteCustomHostname, getCustomHostname, } from './provisioning/cloudflare-api.ts'; +import { reconcileEmailDestinationCleanups } from './provisioning/email-destination-cleanup.ts'; import { oidcRoutes } from './routes/auth-oidc.ts'; import auth from './routes/auth.ts'; import deleteRoute from './routes/delete.ts'; @@ -443,6 +444,10 @@ async function scheduled( const capabilities = getPlatformCapabilities(env); if (capabilities.email) { + await reconcileEmailDestinationCleanups(db, { + accountId: env.CF_ACCOUNT_ID, + apiToken: env.CF_API_TOKEN, + }).catch((error) => console.error('[scheduled] email destination cleanup failed:', error)); await (async () => { const operationId = await ensureSharedEmailConnection(db, env); if (operationId) { diff --git a/platform/packages/api/src/operator/audit.ts b/platform/packages/api/src/operator/audit.ts index dbcd81fcd..8ab924e7f 100644 --- a/platform/packages/api/src/operator/audit.ts +++ b/platform/packages/api/src/operator/audit.ts @@ -131,6 +131,13 @@ function auditTarget( if (segments[1] === 'settings') { return JSON.stringify({ domains: boundedString(body.domains, 512) }); } + if (segments[1] === 'attempts' && segments[3] === 'resolve') { + return JSON.stringify({ + attemptId: pathIdentifier(segments[2]), + ended: body.ended === true, + reason: boundedString(body.reason, 500), + }); + } // Never the credential: `apiToken` rides the add body and stays out. const domain = boundedString(segments[2], 253, true); if (segments[1] === 'domains' && segments.length === 2) { diff --git a/platform/packages/api/src/operator/email-routes.ts b/platform/packages/api/src/operator/email-routes.ts index 2b0814ea9..3c8d71a3c 100644 --- a/platform/packages/api/src/operator/email-routes.ts +++ b/platform/packages/api/src/operator/email-routes.ts @@ -1,10 +1,19 @@ -import { asc, eq, inArray } from 'drizzle-orm'; +import { asc, count, eq, inArray } from 'drizzle-orm'; import { Hono } from 'hono'; import type { Context } from 'hono'; import { capabilityMiddleware } from '../capabilities.ts'; import { getProject, getProjectBySlug, type Db } from '../db.ts'; -import { emailProjectControls } from '../email/admission-schema.ts'; -import { setProjectEmailLimits } from '../email/admission.ts'; +import { + emailActionRecipients, + emailProjectControls, + emailUnresolvedAttempts, +} from '../email/admission-schema.ts'; +import { + EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS, + EmailAdmissionError, + resolveEmailUnresolvedAttempt, + setProjectEmailLimits, +} from '../email/admission.ts'; import { lookupMxOverDns } from '../email/cf-domain-probes.ts'; import { emailDomainRoutes, emailZoneConnections } from '../email/connection-schema.ts'; import { @@ -35,7 +44,7 @@ import { } from '../email/settings.ts'; import type { ApiEnv } from '../env.ts'; import { projects } from '../schema.ts'; -import { dryRun, OperatorError, preview, readBody, stringField } from './common.ts'; +import { dryRun, OperatorError, pagination, preview, readBody, stringField } from './common.ts'; /** * Installation-wide email administration (design doc 0078, "Recipient @@ -231,6 +240,114 @@ emailOperatorRoutes.post('/email/projects/:project/limit', async (context) => { return context.json(result, 'ok' in result && result.ok === false ? 207 : 200); }); +emailOperatorRoutes.get('/email/attempts', async (context) => { + const { page, limit, offset } = pagination(context); + const db = context.get('db'); + const selector = context.req.query('project'); + const project = selector ? await resolveProject(db, selector) : undefined; + const filter = project ? eq(emailUnresolvedAttempts.project_id, project.id) : undefined; + const [rows, totals] = await Promise.all([ + db + .select() + .from(emailUnresolvedAttempts) + .where(filter) + .orderBy(asc(emailUnresolvedAttempts.started_at), asc(emailUnresolvedAttempts.id)) + .limit(limit) + .offset(offset), + db.select({ total: count() }).from(emailUnresolvedAttempts).where(filter), + ]); + return context.json({ + page, + limit, + total: totals[0]?.total ?? 0, + attempts: rows.map((row) => ({ + id: row.id, + projectId: row.project_id, + senderDomain: row.sender_domain, + startedAt: row.started_at, + eligibleAt: new Date( + new Date(row.started_at).getTime() + EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS, + ).toISOString(), + })), + }); +}); + +emailOperatorRoutes.post('/email/attempts/:id/resolve', async (context) => { + const body = await readBody(context); + const id = context.req.param('id'); + const reason = stringField(body, 'reason', { maxLength: 500 }); + if (body.ended !== true) { + throw new OperatorError( + 400, + 'Confirm the original provider execution has ended with --ended.', + 'invalid_argument', + ); + } + const db = context.get('db'); + const [fence] = await db + .select() + .from(emailUnresolvedAttempts) + .where(eq(emailUnresolvedAttempts.id, id)) + .limit(1); + if (!fence) { + throw new OperatorError(404, 'Unresolved email attempt not found.', 'not_found'); + } + const eligibleAt = new Date( + new Date(fence.started_at).getTime() + EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS, + ); + if (eligibleAt.getTime() > Date.now()) { + throw new OperatorError( + 409, + `Email attempt cannot be resolved before ${eligibleAt.toISOString()}.`, + 'attempt_too_recent', + ); + } + const action = 'email.attempt.resolve'; + const target = { attemptId: id, projectId: fence.project_id, senderDomain: fence.sender_domain }; + if (dryRun(body)) { + const [recipient] = await db + .select({ + state: emailActionRecipients.state, + projectId: emailActionRecipients.project_id, + attemptStartedAt: emailActionRecipients.attempt_started_at, + }) + .from(emailActionRecipients) + .where(eq(emailActionRecipients.id, id)) + .limit(1); + if ( + recipient && + (recipient.state !== 'attempt_started' || + recipient.projectId !== fence.project_id || + new Date(recipient.attemptStartedAt ?? new Date()).getTime() > + Date.now() - EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS) + ) { + throw new OperatorError(409, 'Email attempt ledger disagrees with fence.', 'invalid_state'); + } + return context.json( + preview(action, target, { + startedAt: fence.started_at, + metadataExpired: !recipient, + reason, + effect: + 'Mark the original send outcome unknown, retain its quota charge, and release its cleanup fence. No send is retried.', + }), + ); + } + try { + const result = await resolveEmailUnresolvedAttempt(db, { id, ended: true, reason }); + return context.json({ action, target, ...result }); + } catch (error) { + if (error instanceof EmailAdmissionError) { + throw new OperatorError( + error.code === 'NOT_FOUND' ? 404 : error.code === 'INVALID_STATE' ? 409 : 400, + error.message, + error.code.toLowerCase(), + ); + } + throw error; + } +}); + // --------------------------------------------------------------------------- // Administrator-managed domains. The operations are the owner routes' own // (email/domain-service.ts); this layer resolves the project for the diff --git a/platform/packages/api/src/provisioning/cleanup.ts b/platform/packages/api/src/provisioning/cleanup.ts index 831b82ff0..9c01dea1d 100644 --- a/platform/packages/api/src/provisioning/cleanup.ts +++ b/platform/packages/api/src/provisioning/cleanup.ts @@ -6,12 +6,11 @@ import { clearCronScheduler } from '../cron-scheduler-client.ts'; import { TERMINAL_DEPLOYMENT_STATUSES, type Db, - countProjectsUsingDestination, deleteProjectCascade, + deleteProjectEmailDestinations, getAllProjectDeployments, getActiveDeployment, getDomainsByProjectId, - getEmailDestinationsByProjectId, getProject, getProjectResources, terminateBuildsForProject, @@ -41,7 +40,7 @@ import { findContainerApplication, perDeployContainerApplicationName, } from './containers.ts'; -import { deleteDestination } from './email-routing.ts'; +import { runEmailDestinationCleanup } from './email-destination-cleanup.ts'; function deleteCloudflareResource( accountId: string, @@ -466,7 +465,7 @@ async function cleanupRaceWindowResourceOrphans( * can't keep acting on its now-revoked token during the cleanup window. * 2. Run critical CF cleanup (container apps + per-deploy container * orphan recovery). Throws on non-404 failure; the caller should surface - * a 5xx and the DB row remains, allowing retry. Then revoke the proxy's + * a 5xx and the DB row remains, allowing retry. * 3. Run best-effort CF cleanup (D1, KV, R2, queues, hyperdrive, custom * hostnames, routing entries, deployment workers). Failures become * warnings. @@ -539,63 +538,22 @@ export async function teardownProject( return { warnings: [...bestEffortWarnings, ...orphanWarnings] }; } -/** - * Best-effort teardown of the Cloudflare Email Routing destinations this - * project is the last holder of. - * - * CF destinations are ACCOUNT-level: one address added for project A is a - * valid `send_email` recipient for every worker in the account. The - * `email_destinations` table is what maps them back to projects, so - * "is anyone else still using this address?" is a query over those rows — - * and `deleteProjectCascade` deletes them. Run this BEFORE the cascade or - * the answer is unknowable and the CF destination leaks forever. - * - * `refs <= 1` means this project is the only referent (1 = us; 0 would mean - * the row vanished under us, which is equally safe to delete). A shared - * address stays on the account for the projects that still reference it. - * - * Never throws: a CF orphan is recoverable by a sweep, but a project - * delete that 5xx's on CF availability leaves a half-torn-down project. - */ +/** Revoke project consent and hand last-reference tags to durable cleanup. */ async function cleanupProjectEmailDestinations( context: Context, projectId: string, ): Promise { const db = context.get('db'); - let destinations: Awaited> = []; - try { - destinations = await getEmailDestinationsByProjectId(db, projectId); - } catch (err) { - console.error(`[cleanup] email destination lookup failed for project=${projectId}:`, err); - } - for (const destination of destinations) { - const cfDestinationId = destination.cf_destination_id; - if (!cfDestinationId) { - continue; - } - try { - const refs = await countProjectsUsingDestination(db, cfDestinationId); - if (refs <= 1) { - await deleteDestination( - context.env.CF_ACCOUNT_ID, - context.env.CF_API_TOKEN, - cfDestinationId, - ); - } - } catch (err) { - console.error( - `[cleanup] CF destination cleanup failed for project=${projectId} dest=${cfDestinationId}:`, - err, - ); - } + const tags = await deleteProjectEmailDestinations(db, projectId); + for (const tag of tags) { + await runEmailDestinationCleanup( + db, + { accountId: context.env.CF_ACCOUNT_ID, apiToken: context.env.CF_API_TOKEN }, + tag, + ); } } -/** - * Thrown when teardown cannot revoke the project's email send authorization. - * The project row is left in place (status `deleting`) so the caller can - * answer with a retryable 5xx; the next teardown attempt repeats the deletes. - */ /** Disable project email assignments and record durable provider cleanup. */ async function cleanupProjectEmailAssignments( context: Context, diff --git a/platform/packages/api/src/provisioning/email-destination-cleanup.ts b/platform/packages/api/src/provisioning/email-destination-cleanup.ts new file mode 100644 index 000000000..e091fcc3e --- /dev/null +++ b/platform/packages/api/src/provisioning/email-destination-cleanup.ts @@ -0,0 +1,129 @@ +import { and, asc, eq, lte, or, sql } from 'drizzle-orm'; +import type { Db } from '../db.ts'; +import { emailDestinationCleanups } from '../schema.ts'; +import { CloudflareApiError } from './cloudflare-api.ts'; +import { deleteDestination } from './email-routing.ts'; + +const LEASE_MS = 5 * 60_000; +const MAX_RETRY_MS = 60 * 60_000; + +type ProviderAuth = Readonly<{ accountId: string; apiToken: string }>; + +async function claimCleanup(db: Db, tag: string, now: Date): Promise { + return db.transaction(async (tx) => { + const [row] = await tx + .select() + .from(emailDestinationCleanups) + .where(eq(emailDestinationCleanups.cf_destination_id, tag)) + .for('update'); + if (!row || row.status === 'completed') { + return null; + } + const nowMs = now.getTime(); + if ( + (row.status === 'pending' && new Date(row.next_attempt_at).getTime() > nowMs) || + (row.status === 'deleting' && + row.lease_started_at !== null && + new Date(row.lease_started_at).getTime() > nowMs - LEASE_MS) + ) { + return null; + } + await tx + .update(emailDestinationCleanups) + .set({ + status: 'deleting', + attempts: sql`${emailDestinationCleanups.attempts} + 1`, + lease_started_at: now.toISOString(), + updated_at: now.toISOString(), + }) + .where(eq(emailDestinationCleanups.cf_destination_id, tag)); + return row.attempts + 1; + }); +} + +/** Delete one queued provider tag. The tombstone remains after success. */ +export async function runEmailDestinationCleanup( + db: Db, + auth: ProviderAuth, + tag: string, + now = new Date(), +): Promise { + const attempt = await claimCleanup(db, tag, now); + if (attempt === null) { + return; + } + + try { + await deleteDestination(auth.accountId, auth.apiToken, tag); + } catch (error) { + if (!(error instanceof CloudflareApiError && error.status === 404)) { + const retryMs = Math.min(MAX_RETRY_MS, 60_000 * 2 ** Math.min(6, attempt)); + await db + .update(emailDestinationCleanups) + .set({ + status: 'pending', + lease_started_at: null, + next_attempt_at: new Date(now.getTime() + retryMs).toISOString(), + updated_at: now.toISOString(), + }) + .where( + and( + eq(emailDestinationCleanups.cf_destination_id, tag), + eq(emailDestinationCleanups.status, 'deleting'), + eq(emailDestinationCleanups.attempts, attempt), + ), + ); + console.error(`[email] destination cleanup failed for tag=${tag}:`, error); + return; + } + } + + await db + .update(emailDestinationCleanups) + .set({ + status: 'completed', + lease_started_at: null, + updated_at: now.toISOString(), + }) + .where( + and( + eq(emailDestinationCleanups.cf_destination_id, tag), + eq(emailDestinationCleanups.status, 'deleting'), + eq(emailDestinationCleanups.attempts, attempt), + ), + ); +} + +/** Fair, bounded repair for failed calls and expired cleanup leases. */ +export async function reconcileEmailDestinationCleanups( + db: Db, + auth: ProviderAuth, + limit = 10, + now = new Date(), +): Promise { + const staleLease = new Date(now.getTime() - LEASE_MS).toISOString(); + const rows = await db + .select({ tag: emailDestinationCleanups.cf_destination_id }) + .from(emailDestinationCleanups) + .where( + or( + and( + eq(emailDestinationCleanups.status, 'pending'), + lte(emailDestinationCleanups.next_attempt_at, now.toISOString()), + ), + and( + eq(emailDestinationCleanups.status, 'deleting'), + lte(emailDestinationCleanups.lease_started_at, staleLease), + ), + ), + ) + .orderBy( + asc(emailDestinationCleanups.next_attempt_at), + asc(emailDestinationCleanups.updated_at), + asc(emailDestinationCleanups.cf_destination_id), + ) + .limit(Math.max(1, Math.min(limit, 100))); + for (const row of rows) { + await runEmailDestinationCleanup(db, auth, row.tag, now); + } +} diff --git a/platform/packages/api/src/provisioning/email-routing.ts b/platform/packages/api/src/provisioning/email-routing.ts index 0b32ec0a4..fc9e26a01 100644 --- a/platform/packages/api/src/provisioning/email-routing.ts +++ b/platform/packages/api/src/provisioning/email-routing.ts @@ -2,10 +2,8 @@ * Cloudflare Email Routing destination-address API client. * * Destinations are CF account-level — adding `user@example.com` here makes - * it a valid recipient for every `send_email` binding in the account - * (across all WfP user workers). Per-project scoping is enforced separately - * at the binding level via `allowed_destination_addresses` in the deploy - * pipeline. + * it available to the account's email senders. Per-project consent is enforced + * by the platform's SQL admission transaction. * * `addDestination` triggers CF to email the recipient with a verification * link. Status flips from `pending` → `verified` once they click. We poll @@ -13,14 +11,11 @@ * fresh status to the caller. */ -import { cfFetch, CF_API_BASE } from './cloudflare-api.ts'; +import { cfFetch, CF_API_BASE, CloudflareApiError } from './cloudflare-api.ts'; // CF Email Routing returns "destination address X already exists" or -// similar wording when re-registering an account-level address. We use -// the message-text match because cfFetch surfaces only an Error string; -// if cfFetch ever starts attaching structured CF error codes, prefer -// `err.cfErrors?.some(e => e.code === 10037)` (the actual code is in the -// CF API reference for /accounts/:id/email/routing/addresses). +// similar wording when re-registering an account-level address. Keep a text +// fallback for provider variants that omit the documented numeric code. const ALREADY_EXISTS_PATTERN = /already exists|destination already/i; export interface CfDestinationAddress { @@ -87,14 +82,7 @@ export async function listDestinations( throw new Error(`listDestinations exceeded ${LIST_PAGE_CAP} pages — increase cap or paginate`); } -/** - * Delete a destination from the CF account. Note: this affects the entire - * account — if multiple projects had this address in their per-project - * allowlist, they all lose it. The platform's destinations API is - * responsible for refusing to delete addresses still referenced by other - * projects (or implementing reference counting if cross-project sharing is - * ever desired). - */ +/** Delete an account-level destination after durable cleanup has fenced new references. */ export async function deleteDestination( accountId: string, apiToken: string, @@ -102,6 +90,7 @@ export async function deleteDestination( ): Promise<{ tag: string }> { return cfFetch<{ tag: string }>(`${ROUTING_BASE(accountId)}/${destinationTag}`, apiToken, { method: 'DELETE', + signal: AbortSignal.timeout(10_000), }); } @@ -114,11 +103,7 @@ export function isAlreadyExistsError(err: unknown): boolean { if (!(err instanceof Error)) { return false; } - // Prefer structured code if available (forward-compat). Today cfFetch - // joins CF error messages into a flat Error string, so this branch is - // a no-op until cfFetch is upgraded to attach `cfErrors`. - const maybe = err as Error & { cfErrors?: Array<{ code?: number }> }; - if (maybe.cfErrors?.some((e) => e.code === 10037)) { + if (err instanceof CloudflareApiError && err.codes.includes(10037)) { return true; } return ALREADY_EXISTS_PATTERN.test(err.message); diff --git a/platform/packages/api/src/routes/email-confirm.ts b/platform/packages/api/src/routes/email-confirm.ts index d6c2dda79..9b9e850f6 100644 --- a/platform/packages/api/src/routes/email-confirm.ts +++ b/platform/packages/api/src/routes/email-confirm.ts @@ -67,7 +67,7 @@ app.get('/destinations/confirm', async (context) => { return context.html(successPage(slug, row.address, true)); } - await updateEmailDestinationStatus( + const updated = await updateEmailDestinationStatus( context.get('db'), row.id, 'verified', @@ -79,6 +79,9 @@ app.get('/destinations/confirm', async (context) => { // (whatever the row was created with) stays put. undefined, ); + if (!updated) { + return context.html(errorPage('Destination not found.'), 404); + } return context.html(successPage(slug, row.address, false)); }); diff --git a/platform/packages/api/src/routes/email.ts b/platform/packages/api/src/routes/email.ts index 36d56cd37..9849cb213 100644 --- a/platform/packages/api/src/routes/email.ts +++ b/platform/packages/api/src/routes/email.ts @@ -4,13 +4,13 @@ import type { Context } from 'hono'; import { signConfirmToken, type ConfirmTokenPayload } from '../auth/confirm-token.ts'; import { capabilityMiddleware } from '../capabilities.ts'; import { - countProjectsUsingDestination, deleteEmailDestination, getEmailDestinationByAddress, getEmailDestinationsByProjectId, getProject, getUser, promoteEmailDestinationWithOwnerAudit, + queueUnreferencedEmailDestinationCleanup, tryCreateEmailDestination, updateEmailDestinationStatus, type Db, @@ -37,9 +37,9 @@ import { } from '../email/settings.ts'; import type { ApiEnv } from '../env.ts'; import { isForeignKeyViolation, isUniqueViolation } from '../pg-errors.ts'; +import { runEmailDestinationCleanup } from '../provisioning/email-destination-cleanup.ts'; import { addDestination, - deleteDestination, isAlreadyExistsError, listDestinations, type CfDestinationAddress, @@ -54,8 +54,7 @@ import type { EmailDestination } from '../types.ts'; * - 5 requests / minute (TTL 5m) * - 50 requests / day (TTL 25h) * - * Counters live in ROUTING KV (same namespace as the email-* counters) - * with poisoning defense identical to the proxy's send counter: + * Counters live in ROUTING KV. Treat malformed values as zero: * `parseInt('NaN', 10) → NaN` would silently bypass `count >= LIMIT` if * not coerced, so any non-finite or negative read becomes 0. */ @@ -78,10 +77,9 @@ const MAX_ADDRESS_LENGTH = 320; /** * Email observability + destinations management. * - * Counters live in `ROUTING` KV under monthly buckets — exposed via the - * `/usage` endpoint. Recipient destinations live in the `email_destinations` - * Postgres table; the `/destinations` endpoints proxy CF Email Routing's - * account-level address API and keep our per-project view in sync. + * Usage and recipient consent are SQL-authoritative. The destination routes + * proxy CF Email Routing's account-level address API and keep the per-project + * consent view in sync. */ const app = new Hono() // Path-scoped, NOT `use('*')` as `domains.ts` does: this router is one of @@ -166,13 +164,16 @@ const app = new Hono() } if (cf.tag === row.cf_destination_id) { // The click answered the destination THIS row registered. - await updateEmailDestinationStatus( + const updated = await updateEmailDestinationStatus( context.get('db'), row.id, 'verified', cf.tag, cf.verified, ); + if (!updated) { + continue; + } } else { // The account carries the address under a tag this row never // registered: its own destination was deleted at Cloudflare @@ -269,9 +270,7 @@ const app = new Hono() return context.json({ error: 'invalid address' }, 400); } - // Per-project rate-limit BEFORE calling CF. Counters use the - // NaN-poison-resistant reader; reads are not strongly consistent so - // the gate is approximate, but at our planned volumes that's fine. + // Rate-limit before Cloudflare calls. KV reads make this abuse gate approximate. const rateCheck = await checkAndIncrementAddRate(context.env.ROUTING, projectId); if (!rateCheck.allowed) { return context.json({ error: rateCheck.message }, 429); @@ -379,8 +378,6 @@ const app = new Hono() context.get('db'), context.env.CF_ACCOUNT_ID, context.env.CF_API_TOKEN, - projectId, - address, cfRow.tag, ); return context.json({ error: 'destination concurrently modified, try again' }, 409); @@ -420,8 +417,6 @@ const app = new Hono() context.get('db'), context.env.CF_ACCOUNT_ID, context.env.CF_API_TOKEN, - projectId, - address, cfRow.tag, ); return context.json({ error: 'destination concurrently modified, try again' }, 409); @@ -466,8 +461,6 @@ const app = new Hono() context.get('db'), context.env.CF_ACCOUNT_ID, context.env.CF_API_TOKEN, - projectId, - address, cfRow.tag, ); return context.json({ error: 'destination concurrently modified, try again' }, 409); @@ -500,21 +493,13 @@ const app = new Hono() return context.json({ error: 'destination not found' }, 404); } - // Admission observes this committed revocation. - await deleteEmailDestination(context.get('db'), dest.id); - if ( - dest.cf_destination_id && - (await countProjectsUsingDestination(context.get('db'), dest.cf_destination_id)) === 0 - ) { - try { - await deleteDestination( - context.env.CF_ACCOUNT_ID, - context.env.CF_API_TOKEN, - dest.cf_destination_id, - ); - } catch (error) { - console.error('[email] destination provider cleanup failed:', error); - } + const cleanupTag = await deleteEmailDestination(context.get('db'), dest.id); + if (cleanupTag) { + await runEmailDestinationCleanup( + context.get('db'), + { accountId: context.env.CF_ACCOUNT_ID, apiToken: context.env.CF_API_TOKEN }, + cleanupTag, + ); } return context.json({ ok: true }); }) @@ -771,25 +756,10 @@ async function dispatchPlatformVerification( /** * Insert + retry-on-race wrapper around `tryCreateEmailDestination`. * - * The underlying helper returns `{ row: null }` only when: - * 1. Our INSERT lost the ON CONFLICT race AND - * 2. The winning row was DELETED before our follow-up SELECT could - * read it back. - * - * That's a real, observable race (sibling tab issuing a DELETE while - * we're processing a duplicate POST). One retry with a fresh insert+ - * select almost always wins — if it still misses, the caller surfaces - * a clean 409 to the user with a "concurrently modified, try again" - * message rather than a generic 500. The caller rolls the CF tag back. - * - * A foreign-key violation reports the same "not inserted" outcome: see - * the catch below. So does `ownerEmailChanged`, without the retry: the - * helper found the owner's address rotated away from the one whose - * Cloudflare consent the Option C branch meant to inherit (the read the - * branch made is unlocked, and a login can commit between it and the - * insert). A second attempt would read the same answer. The 409 is right - * on the merits — the retry re-reads the owner and, the address now being - * somebody else's, takes the Option B platform link instead. + * A missing row can mean the conflicting row disappeared before readback, + * or that project teardown marked the project deleting after the route's + * initial guard. One retry resolves the former; the latter stays rejected + * and lets the caller retire the provider tag. */ async function tryInsertWithRetry( db: Db, @@ -836,54 +806,21 @@ async function tryInsertWithRetry( return { row: null, inserted: false }; } -/** - * Undo the CF-side registration for a destination whose row never landed. - * - * `email_destinations` rows are the ONLY thing that maps an account-level CF - * destination back to a project — teardown's cleanup reads them, and there is - * no sweep for one nothing points at. Every path here already failed to - * persist a row, so without this the address stays allocated forever against - * the shared 200-destination account cap. - * - * The reference count must be ZERO, not `<= 1` the way the DELETE route reads - * it: that route still holds its own row, and we have none. A live sibling - * project can legitimately share the tag (the already-exists recovery above - * reuses one CF address across projects), so a non-zero count must never - * delete — it would silently revoke the sibling's recipient. Anything that - * goes wrong keeps the original log line so an operator can still find the - * tag by hand. - * - * Takes `db` / account / token explicitly rather than a Hono `Context` - * because `autoAddOwnerDestination` in `routes/projects.ts` shares it and has - * no context by design — it runs after the 201 response, so it outlives the - * request whose context it would otherwise borrow. - */ +/** Queue an allocated provider tag when its project row did not land. */ export async function rollbackCfDestination( db: Db, accountId: string, apiToken: string, - projectId: string, - address: string, cfDestinationId: string, ): Promise { - try { - const refs = await countProjectsUsingDestination(db, cfDestinationId); - if (refs === 0) { - await deleteDestination(accountId, apiToken, cfDestinationId); - return; - } - } catch (err) { - console.error('[email] CF destination rollback failed:', err); + if (await queueUnreferencedEmailDestinationCleanup(db, cfDestinationId)) { + await runEmailDestinationCleanup(db, { accountId, apiToken }, cfDestinationId); } - console.error( - `[email] destination row not persisted for project=${projectId} address=${address}; orphan CF tag candidate: ${cfDestinationId}`, - ); } /** - * Approximate per-project rate-limit on POST /destinations. Same - * NaN-poisoning defense as the proxy's send counter (`parseInt('NaN')` - * returns NaN, which would silently bypass `count >= LIMIT`). + * Approximate per-project rate-limit on POST /destinations. Malformed values + * become zero so they cannot bypass the numeric comparisons. * * Not strongly consistent — KV reads can lag writes for ~60s per colo, * so racing requests across colos can exceed the limit by a few. That's diff --git a/platform/packages/api/src/routes/projects.ts b/platform/packages/api/src/routes/projects.ts index 94f01dddf..e8242df04 100644 --- a/platform/packages/api/src/routes/projects.ts +++ b/platform/packages/api/src/routes/projects.ts @@ -3247,7 +3247,7 @@ async function autoAddOwnerDestination( // FK-only check. The `refs === 0` guard inside `rollbackCfDestination` // is what stops it revoking a recipient a sibling project still uses — // including the already-exists path, where the address predates us. - await rollbackCfDestination(db, accountId, apiToken, projectId, address, allocatedTag); + await rollbackCfDestination(db, accountId, apiToken, allocatedTag); } } } diff --git a/platform/packages/api/src/schema.ts b/platform/packages/api/src/schema.ts index 3a7172148..eca031829 100644 --- a/platform/packages/api/src/schema.ts +++ b/platform/packages/api/src/schema.ts @@ -472,17 +472,8 @@ export const domains = pgTable( // --------------------------------------------------------------------------- // email_destinations -// Per-project verified destination addresses for outbound email via the -// shared platform sender (`EMAIL_SENDER_DOMAIN`, e.g. `mail.void.cloud` in -// production and `mail.staging.void.cloud` in staging — never hard-coded). -// Each row tracks the lifecycle of one recipient address — from "the user -// added it" -> CF sends a verification email -> recipient clicks the link -> -// status flips to "verified" and the next deploy puts the address into the -// worker's `send_email` binding `allowed_destination_addresses` allowlist. -// -// `cf_destination_id` is CF's account-level identifier for the address — -// destinations are account-wide on CF's side; per-project scoping is -// enforced via the binding allowlist injected at deploy. +// Per-project recipient consent for shared-sender email. Cloudflare destination +// tags are account-wide; SQL admission enforces consent separately for each project. // --------------------------------------------------------------------------- export const emailDestinations = pgTable( 'email_destinations', @@ -493,10 +484,7 @@ export const emailDestinations = pgTable( .references(() => projects.id, { onDelete: 'cascade' }), address: text('address').notNull(), status: text('status').notNull().default('pending').$type<'pending' | 'verified'>(), - // Always populated by `createEmailDestination` after a successful CF - // addDestination call. Nullable in schema only for forward-compat with - // future async-tag flows (e.g. status='pending' rows created before the - // CF API has returned a tag). + // Cloudflare account-level tag, populated after destination creation. cf_destination_id: text('cf_destination_id'), // Audit timestamp: set the moment status first transitions to 'verified', // never cleared. Use `status === 'verified'` for current state, not @@ -561,6 +549,43 @@ export const emailDestinations = pgTable( ], ); +// Provider destination deletion outlives the project consent row. The opaque +// Cloudflare tag is retained as a tombstone so stale list responses cannot +// reattach a destination while its deletion is pending or after it completes. +export const emailDestinationCleanups = pgTable( + 'email_destination_cleanups', + { + cf_destination_id: text('cf_destination_id').primaryKey(), + status: text('status') + .notNull() + .default('pending') + .$type<'pending' | 'deleting' | 'completed'>(), + attempts: integer('attempts').notNull().default(0), + next_attempt_at: timestamp('next_attempt_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + lease_started_at: timestamp('lease_started_at', { mode: 'string', withTimezone: true }), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + }, + (table) => [ + index('idx_email_destination_cleanups_due').on( + table.status, + table.next_attempt_at, + table.updated_at, + ), + check( + 'email_destination_cleanups_status_check', + sql`${table.status} IN ('pending', 'deleting', 'completed')`, + ), + check('email_destination_cleanups_attempts_check', sql`${table.attempts} >= 0`), + ], +); + // --------------------------------------------------------------------------- // email_domains is retained for generated-schema compatibility with the // published platform runtime rollback contract. New email routes do not use it. diff --git a/platform/packages/api/test/integration/admin-email.test.ts b/platform/packages/api/test/integration/admin-email.test.ts index c517057b5..4e0f27e5f 100644 --- a/platform/packages/api/test/integration/admin-email.test.ts +++ b/platform/packages/api/test/integration/admin-email.test.ts @@ -9,13 +9,20 @@ import { test, vi, } from 'vite-plus/test'; -import { createEmailDestination, getEmailDestinationsByProjectId } from '../../src/db.ts'; +import { getEmailDestinationsByProjectId } from '../../src/db.ts'; import type { Db } from '../../src/db.ts'; -import { emailProjectControls } from '../../src/email/admission-schema.ts'; +import { emailMonthlyUsage, emailProjectControls } from '../../src/email/admission-schema.ts'; +import { pruneEmailActionHistory } from '../../src/email/admission.ts'; import { setProjectEmailLimits, setProjectEmailSuspended } from '../../src/email/admission.ts'; import { emailDomainRoutes, emailZoneConnections } from '../../src/email/connection-schema.ts'; +import { generateId } from '../../src/id.ts'; import { app } from '../../src/index.ts'; -import { operatorEvents, platformSettings } from '../../src/schema.ts'; +import { + emailDestinationCleanups, + emailDestinations, + operatorEvents, + platformSettings, +} from '../../src/schema.ts'; import { stubCustomerCf, callsByTag } from './email-domain-cf-stub.ts'; import { setupEnv, @@ -30,6 +37,21 @@ import { setTestDb } from './setup.ts'; let env: TestEnv; +async function seedVerifiedDestination(db: Db, projectId: string, address: string, cfId: string) { + const [row] = await db + .insert(emailDestinations) + .values({ + id: generateId('edst'), + project_id: projectId, + address, + cf_destination_id: cfId, + status: 'verified', + verified_at: new Date().toISOString(), + }) + .returning(); + return row!; +} + /** * Pause the app's FIRST `db.transaction` until released — the seam for * landing a committed write (a credential replace) between a route's @@ -233,15 +255,17 @@ describe('GET /admin/email/:projectId', () => { test('renders usage, the platform defaults, and the destination list', async () => { const { adminJwt, projectId, slug } = await seedAdminAndProject(); const month = monthBucket(); - await env.ROUTING.put(`email-sent:${projectId}:${month}`, '7'); - await env.ROUTING.put(`email-recv:${projectId}:${month}`, '3'); + await env.db + .insert(emailMonthlyUsage) + .values({ project_id: projectId, month, recipient_attempts: 7 }); + await pruneEmailActionHistory(env.db); const res = await get(`/admin/email/${projectId}`, adminJwt); expect(res.status).toBe(200); const html = await res.text(); expect(html).toContain(slug); - expect(html).toContain('0 / 200'); + expect(html).toContain('7 / 200'); expect(html).toContain('(default)'); expect(html).toContain('Suspend email'); expect(html).toContain('No destinations yet.'); @@ -403,12 +427,11 @@ describe('POST /admin/email/:projectId/limit', () => { describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { test('removes the row and drops an unreferenced CF address', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); - const destination = await createEmailDestination( + const destination = await seedVerifiedDestination( env.db, projectId, 'ops@example.com', 'cf-tag-ops', - 'verified', ); const cfCalls = recordCfCalls(); @@ -422,25 +445,21 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { 'DELETE https://api.cloudflare.com/client/v4/accounts/test-account-id/email/routing/addresses/cf-tag-ops', ]); expect(await getEmailDestinationsByProjectId(env.db, projectId)).toEqual([]); + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ cf_destination_id: 'cf-tag-ops', status: 'completed' }), + ]); }); test('leaves the CF address alone while another project still references it', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); const sibling = await createTestProject(env.db, (await createTestUser(env.db)).id); - const destination = await createEmailDestination( + const destination = await seedVerifiedDestination( env.db, projectId, 'shared@example.com', 'cf-tag-shared', - 'verified', - ); - await createEmailDestination( - env.db, - sibling.id, - 'shared@example.com', - 'cf-tag-shared', - 'verified', ); + await seedVerifiedDestination(env.db, sibling.id, 'shared@example.com', 'cf-tag-shared'); const cfCalls = recordCfCalls(); const res = await post( @@ -455,12 +474,11 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { test('404s for a destination that belongs to another project', async () => { const { adminJwt, projectId } = await seedAdminAndProject(); const sibling = await createTestProject(env.db, (await createTestUser(env.db)).id); - const destination = await createEmailDestination( + const destination = await seedVerifiedDestination( env.db, sibling.id, 'elsewhere@example.com', 'cf-tag-elsewhere', - 'verified', ); const cfCalls = recordCfCalls(); diff --git a/platform/packages/api/test/integration/api-delete.test.ts b/platform/packages/api/test/integration/api-delete.test.ts index ef635ea46..0a7778b00 100644 --- a/platform/packages/api/test/integration/api-delete.test.ts +++ b/platform/packages/api/test/integration/api-delete.test.ts @@ -12,7 +12,15 @@ import { import { createBuild } from '../../src/db.ts'; import * as db from '../../src/db.ts'; import app from '../../src/index.ts'; -import { resources, projects, deployments, builds, emailDestinations } from '../../src/schema.ts'; +import { + resources, + projects, + deployments, + builds, + emailDestinationCleanups, + emailDestinations, + users, +} from '../../src/schema.ts'; import { setupEnv, teardownEnv, @@ -630,7 +638,7 @@ describe('DELETE /projects/:id — CF email destination cleanup', () => { expect(rows).toHaveLength(1); }); - it('still deletes the project when Cloudflare refuses the destination delete', async () => { + it('deletes the project while retaining failed provider cleanup for scheduled retry', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'mail-cf-down'); mockCfApi(); @@ -655,10 +663,12 @@ describe('DELETE /projects/:id — CF email destination cleanup', () => { }), env, ); - // A CF orphan is recoverable by a sweep; a half-torn-down project is not. expect(res.status).toBe(200); const [dbProject] = await env.db.select().from(projects).where(eq(projects.id, project.id)); expect(dbProject).toBeUndefined(); + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ cf_destination_id: 'cf-tag-down', status: 'pending', attempts: 1 }), + ]); }); }); @@ -685,6 +695,47 @@ describe('POST /projects/:id/email/destinations — losing the teardown race', ( .map((call) => (typeof call[0] === 'string' ? call[0] : String(call[0]))); } + it('retires a provider tag when teardown marks the locked project deleting', async () => { + const user = await createTestUser(env.db); + await env.db.update(users).set({ email: 'owner@example.com' }).where(eq(users.id, user.id)); + const project = await createTestProject(env.db, user.id, 'mail-race-deleting'); + const fetchMock = mockCfApi({ + addEmailDestination: async (_url: string, init?: RequestInit) => { + await env.db + .update(projects) + .set({ status: 'deleting' }) + .where(eq(projects.id, project.id)); + const body = typeof init?.body === 'string' ? JSON.parse(init.body) : {}; + return cfSuccess({ + tag: 'cf-tag-project-deleting', + email: body.email, + verified: '2026-04-27T00:00:00Z', + created: '2026-04-27T00:00:00Z', + modified: '2026-04-27T00:00:00Z', + }); + }, + }); + + const res = await app.fetch( + addDestinationRequest(project.id, user.jwt, 'owner@example.com'), + env, + ); + + expect(res.status).toBe(409); + expect(await env.db.select().from(emailDestinations)).toHaveLength(0); + expect(cfDeleteCalls(fetchMock)).toEqual([ + expect.stringContaining( + '/email/routing/addresses/cf-tag-project-deleting', + ) as unknown as string, + ]); + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ + cf_destination_id: 'cf-tag-project-deleting', + status: 'completed', + }), + ]); + }); + it('deletes the CF destination it created and returns the not-inserted status', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'mail-race'); diff --git a/platform/packages/api/test/integration/api-email-domains.test.ts b/platform/packages/api/test/integration/api-email-domains.test.ts index b32174f2e..f35ff547f 100644 --- a/platform/packages/api/test/integration/api-email-domains.test.ts +++ b/platform/packages/api/test/integration/api-email-domains.test.ts @@ -68,7 +68,8 @@ describe('project email domain authority', () => { const project = await createTestProject(env.db, owner.id, 'readiness-mail'); const routingRules: Array<{ enabled: boolean; addresses: Array }> = []; const failures: { routingRulesGet?: { message: string; status: number } } = {}; - const stub = stubCustomerCf({ zones, routingRules, failOn: failures }); + const mx: Record> = {}; + const stub = stubCustomerCf({ zones, routingRules, failOn: failures, mx }); expect( ( await call(project.id, owner.jwt, 'POST', '/domains', { @@ -96,6 +97,12 @@ describe('project email domain authority', () => { }); delete failures.routingRulesGet; routingRules.length = 0; + mx['status.example.com'] = []; + const dnsDrift = await call(project.id, owner.jwt, 'GET', '/domains/status.example.com'); + expect(await dnsDrift.json()).toMatchObject({ + readiness: { inbound: { status: 'drifted', reason: expect.stringContaining('MX records') } }, + }); + mx['status.example.com'] = ['route1.mx.cloudflare.net']; await env.db .update(emailDomainRoutes) .set({ inbound_status: 'pending', inbound_reason: 'waiting for setup proof' }) @@ -110,6 +117,53 @@ describe('project email domain authority', () => { expect(stub.calls.slice(checkpoint).every((call) => call.method === 'GET')).toBe(true); }); + it('does not return a route removed or reassigned during a provider status read', async () => { + const owner = await createTestUser(env.db, 'status-race-owner'); + const other = await createTestUser(env.db, 'status-race-other'); + const project = await createTestProject(env.db, owner.id, 'status-race-mail'); + const foreign = await createTestProject(env.db, other.id, 'status-race-foreign'); + let race: (() => Promise) | undefined; + stubCustomerCf({ + zones, + on: { + routingRulesGet: async () => { + const run = race; + race = undefined; + await run?.(); + }, + }, + }); + for (const domain of ['gone.example.com', 'moved.example.com']) { + expect( + ( + await call(project.id, owner.jwt, 'POST', '/domains', { + domain, + apiToken: token, + }) + ).status, + ).toBe(200); + } + + race = async () => { + await env.db + .delete(emailDomainRoutes) + .where(eq(emailDomainRoutes.domain, 'gone.example.com')); + }; + const removed = await call(project.id, owner.jwt, 'GET', '/domains/gone.example.com'); + expect(removed.status).toBe(404); + expect(await removed.json()).toEqual({ error: 'email domain not found' }); + + race = async () => { + await env.db + .update(emailDomainRoutes) + .set({ project_id: foreign.id }) + .where(eq(emailDomainRoutes.domain, 'moved.example.com')); + }; + const reassigned = await call(project.id, owner.jwt, 'GET', '/domains/moved.example.com'); + expect(reassigned.status).toBe(404); + expect(await reassigned.json()).toEqual({ error: 'email domain not found' }); + }); + it('rejects unauthenticated, foreign-owner, malformed and OAuth requests before Cloudflare writes', async () => { const owner = await createTestUser(env.db, 'domain-owner'), other = await createTestUser(env.db, 'domain-other'); diff --git a/platform/packages/api/test/integration/api-email.test.ts b/platform/packages/api/test/integration/api-email.test.ts index 01b565ac1..43feb03cd 100644 --- a/platform/packages/api/test/integration/api-email.test.ts +++ b/platform/packages/api/test/integration/api-email.test.ts @@ -51,7 +51,17 @@ import { PLATFORM_INTERNAL_EMAIL_SENTINEL, } from '../../src/email/send-verification.ts'; import app from '../../src/index.ts'; -import { emailDestinations, platformSettings, projects, users } from '../../src/schema.ts'; +import { + reconcileEmailDestinationCleanups, + runEmailDestinationCleanup, +} from '../../src/provisioning/email-destination-cleanup.ts'; +import { + emailDestinationCleanups, + emailDestinations, + platformSettings, + projects, + users, +} from '../../src/schema.ts'; import { cfError, cfSuccess, @@ -949,7 +959,7 @@ describe('DELETE /projects/:id/email/destinations/:destId', () => { expect(await rowsFor(projectB.id)).toHaveLength(1); }); - it('still removes the DB row when the CF delete fails', async () => { + it('revokes consent immediately and retries failed provider cleanup from a durable tag', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); mockCfApi(); @@ -966,6 +976,136 @@ describe('DELETE /projects/:id/email/destinations/:destId', () => { .from(emailDestinations) .where(eq(emailDestinations.id, dest.id)); expect(rows).toHaveLength(0); + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ + cf_destination_id: 'cf-tag-a@b.com', + status: 'pending', + attempts: 1, + }), + ]); + + mockCfApi(); + await reconcileEmailDestinationCleanups( + env.db, + { accountId: env.CF_ACCOUNT_ID, apiToken: env.CF_API_TOKEN }, + 10, + new Date(Date.now() + 2 * 60 * 60_000), + ); + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ + cf_destination_id: 'cf-tag-a@b.com', + status: 'completed', + attempts: 2, + }), + ]); + }); + + it('refuses a stale provider tag after its cleanup completed', async () => { + const user = await createTestUser(env.db); + const first = await createTestProject(env.db, user.id, 'first-tag-owner'); + const second = await createTestProject(env.db, user.id, 'second-tag-owner'); + mockCfApi(); + const created = await addDestination(first.id, user.jwt, 'stale@example.com'); + const destination = (await created.json()) as { id: string }; + expect((await removeDestination(first.id, destination.id, user.jwt)).status).toBe(200); + + mockCfApi({ + addEmailDestination: () => cfError('address already exists'), + listEmailDestinations: () => + cfSuccess([ + { + tag: 'cf-tag-stale@example.com', + email: 'stale@example.com', + verified: '2026-09-01T00:00:00Z', + created: '2026-09-01T00:00:00Z', + modified: '2026-09-01T00:00:00Z', + }, + ]), + }); + const stale = await addDestination(second.id, user.jwt, 'stale@example.com', emailEnv()); + expect(stale.status).toBe(409); + expect(await rowsFor(second.id)).toHaveLength(0); + }); + + it('fences a sibling add that recovers the tag while provider deletion is in flight', async () => { + const user = await createTestUser(env.db); + const deleting = await createTestProject(env.db, user.id, 'deleting-tag-owner'); + const sibling = await createTestProject(env.db, user.id, 'sibling-tag-owner'); + mockCfApi(); + const created = await addDestination(deleting.id, user.jwt, 'racing@example.com'); + const destination = (await created.json()) as { id: string }; + + let siblingStatus: number | undefined; + mockCfApi({ + addEmailDestination: () => cfError('address already exists'), + listEmailDestinations: () => + cfSuccess([ + { + tag: 'cf-tag-racing@example.com', + email: 'racing@example.com', + verified: '2026-09-01T00:00:00Z', + created: '2026-09-01T00:00:00Z', + modified: '2026-09-01T00:00:00Z', + }, + ]), + deleteEmailDestination: async () => { + siblingStatus = ( + await addDestination(sibling.id, user.jwt, 'racing@example.com', emailEnv()) + ).status; + return cfSuccess({ tag: 'cf-tag-racing@example.com' }); + }, + }); + + expect((await removeDestination(deleting.id, destination.id, user.jwt)).status).toBe(200); + expect(siblingStatus).toBe(409); + expect(await rowsFor(sibling.id)).toHaveLength(0); + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ + cf_destination_id: 'cf-tag-racing@example.com', + status: 'completed', + }), + ]); + }); + + it('does not let an expired cleanup attempt overwrite a newer completion', async () => { + await env.db + .insert(emailDestinationCleanups) + .values({ cf_destination_id: 'cf-tag-expired-lease' }); + let rejectFirst: ((error: Error) => void) | undefined; + let reachedFirst: (() => void) | undefined; + const firstReached = new Promise((resolve) => { + reachedFirst = resolve; + }); + let calls = 0; + vi.stubGlobal('fetch', async () => { + calls += 1; + if (calls === 1) { + reachedFirst?.(); + return new Promise((_resolve, reject) => { + rejectFirst = reject; + }); + } + return cfSuccess({ tag: 'cf-tag-expired-lease' }); + }); + const startedAt = new Date(); + const first = runEmailDestinationCleanup( + env.db, + { accountId: env.CF_ACCOUNT_ID, apiToken: env.CF_API_TOKEN }, + 'cf-tag-expired-lease', + startedAt, + ); + await firstReached; + await runEmailDestinationCleanup( + env.db, + { accountId: env.CF_ACCOUNT_ID, apiToken: env.CF_API_TOKEN }, + 'cf-tag-expired-lease', + new Date(startedAt.getTime() + 6 * 60_000), + ); + rejectFirst?.(new Error('late timeout')); + await first; + expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ + expect.objectContaining({ status: 'completed', attempts: 2 }), + ]); }); }); @@ -1653,6 +1793,24 @@ describe('GET /email/destinations/confirm', () => { expect(res.headers.get('referrer-policy')).toBe('no-referrer'); }); + it('does not report confirmation after consent is concurrently removed', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id); + const did = await seedPlatformPending('shared@example.com', project); + const updateStatus = dbModule.updateEmailDestinationStatus; + vi.spyOn(dbModule, 'updateEmailDestinationStatus').mockImplementationOnce(async (...args) => { + await dbModule.deleteEmailDestination(env.db, did); + return updateStatus(...args); + }); + const response = await confirm(await makeToken(project.id, did, 'shared@example.com')); + expect(response.status).toBe(404); + expect(await response.text()).toContain('Destination not found'); + expect(await readVerifiedDestinations(project.id)).toEqual([]); + expect(await env.db.select().from(emailDestinationCleanups)).toMatchObject([ + { cf_destination_id: 'cf-tag-shared', status: 'pending' }, + ]); + }); + it('returns 400 for a missing token', async () => { const res = await app.fetch(new Request('http://localhost/email/destinations/confirm'), env); expect(res.status).toBe(400); diff --git a/platform/packages/api/test/integration/auth-email-verification.test.ts b/platform/packages/api/test/integration/auth-email-verification.test.ts index 09ec64ce3..52d52e902 100644 --- a/platform/packages/api/test/integration/auth-email-verification.test.ts +++ b/platform/packages/api/test/integration/auth-email-verification.test.ts @@ -920,8 +920,30 @@ describe('email verification gating on account linking', () => { email: 'new-owner@example.com', emailVerified: true, }); + let deleted = false; const calls = stubEmailRoutingOver(github, (method) => { + if (method === 'DELETE') { + deleted = true; + return Response.json({ + success: true, + errors: [], + messages: [], + result: { tag: 'cf-tag-racing-manual' }, + }); + } if (method === 'POST') { + if (deleted) { + return Response.json({ + success: true, + errors: [], + messages: [], + result: { + tag: 'cf-tag-racing-manual-recreated', + email: 'old-owner@example.com', + verified: null, + }, + }); + } return Response.json( { success: false, @@ -983,9 +1005,8 @@ describe('email verification gating on account linking', () => { expect.stringContaining('/email/routing/addresses/cf-tag-racing-manual'), ]); - // The retry sees the rotated owner: the old address is now somebody - // else's, so it gets the per-project platform link, not inherited - // consent. + // The rollback deleted the old provider tag. The retry creates a fresh + // provider destination and waits on its new verification email. const retry = await app.fetch( new Request(`http://localhost/projects/${project.id}/email/destinations`, { method: 'POST', @@ -998,8 +1019,7 @@ describe('email verification gating on account linking', () => { expect(retry.status).toBe(201); expect(await retry.json()).toMatchObject({ status: 'pending', - verification_source: 'platform', - platformVerificationPending: true, + verification_source: 'cf', }); }); diff --git a/platform/packages/api/test/integration/email-admission.test.ts b/platform/packages/api/test/integration/email-admission.test.ts index 88c81ce0d..351956ac4 100644 --- a/platform/packages/api/test/integration/email-admission.test.ts +++ b/platform/packages/api/test/integration/email-admission.test.ts @@ -1,7 +1,11 @@ import { eq } from 'drizzle-orm'; import { beforeAll, afterAll, beforeEach, describe, expect, it } from 'vite-plus/test'; import { deleteEmailDestination } from '../../src/db.ts'; -import { emailUnresolvedAttempts } from '../../src/email/admission-schema.ts'; +import { + emailActionRecipients, + emailMonthlyUsage, + emailUnresolvedAttempts, +} from '../../src/email/admission-schema.ts'; import { admitEmailAction, claimRelayedEmailReceipt, @@ -12,6 +16,7 @@ import { getProjectEmailLogs, getProjectEmailUsage, pruneEmailActionHistory, + resolveEmailUnresolvedAttempt, setProjectEmailLimits, setProjectEmailSuspended, transitionEmailRecipients, @@ -75,6 +80,34 @@ function input(projectId: string, key: string, recipients = ['one@example.com']) } describe('authoritative email admission', () => { + it('requires verified recipients for shared native forwarding even under an open policy', async () => { + const project = await fixture(); + await setEmailRecipientPolicy(env.db, env.ROUTING, { mode: 'any', domains: [] }); + const receiptId = 'e'.repeat(64); + await recordEmailReceipt(env.db, { + receiptId, + projectId: project.id, + status: 'handler_completed', + }); + const result = await admitEmailAction(env.db, { + ...input(project.id, 'shared-forward', ['one@example.com', 'unverified@example.net']), + kind: 'forward', + transport: 'native_forward', + receiptId, + }); + expect(result.recipients).toEqual( + expect.arrayContaining([ + expect.objectContaining({ recipient: 'one@example.com', state: 'reserved' }), + expect.objectContaining({ + recipient: 'unverified@example.net', + state: 'rejected', + errorCode: 'UNVERIFIED_DESTINATION', + }), + ]), + ); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + }); + it('records unsupported relayed forwarding without charging and retains native verified forwarding', async () => { const project = await fixture(); await env.db.insert(emailCredentials).values({ @@ -288,6 +321,110 @@ describe('authoritative email admission', () => { }); }); + it('resolves a stopped old attempt without retrying or refunding it', async () => { + const project = await fixture(); + const action = await admitEmailAction(env.db, input(project.id, 'crashed')); + await transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'attempt_started', + ); + const [fence] = await env.db.select().from(emailUnresolvedAttempts); + const old = new Date(Date.now() - 25 * 60 * 60_000).toISOString(); + await env.db + .update(emailUnresolvedAttempts) + .set({ started_at: old }) + .where(eq(emailUnresolvedAttempts.id, fence!.id)); + await env.db + .update(emailActionRecipients) + .set({ attempt_started_at: old }) + .where(eq(emailActionRecipients.id, fence!.id)); + + await expect( + resolveEmailUnresolvedAttempt(env.db, { id: fence!.id, ended: false, reason: 'ended' }), + ).rejects.toMatchObject({ code: 'INVALID_REQUEST' }); + await expect( + resolveEmailUnresolvedAttempt(env.db, { id: fence!.id, ended: true, reason: '' }), + ).rejects.toMatchObject({ code: 'INVALID_REQUEST' }); + expect( + await resolveEmailUnresolvedAttempt(env.db, { + id: fence!.id, + ended: true, + reason: 'Worker execution ended; provider status cannot be verified', + }), + ).toMatchObject({ state: 'outcome_unknown', metadataExpired: false, charged: true }); + expect(await env.db.select().from(emailUnresolvedAttempts)).toHaveLength(0); + expect((await getProjectEmailLogs(env.db, project.id)).logs).toEqual([ + expect.objectContaining({ operationId: action.operationId, status: 'outcome_unknown' }), + ]); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect( + (await admitEmailAction(env.db, input(project.id, 'crashed'))).recipients[0]?.state, + ).toBe('outcome_unknown'); + await expect( + transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'provider_accepted', + ), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + }); + + it('requires an old fence even when the operator attests the execution ended', async () => { + const project = await fixture(); + const action = await admitEmailAction(env.db, input(project.id, 'recent')); + await transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'attempt_started', + ); + const [fence] = await env.db.select().from(emailUnresolvedAttempts); + await expect( + resolveEmailUnresolvedAttempt(env.db, { + id: fence!.id, + ended: true, + reason: 'Worker execution ended', + }), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect(await env.db.select().from(emailUnresolvedAttempts)).toHaveLength(1); + expect((await getProjectEmailLogs(env.db, project.id)).logs[0]?.status).toBe('attempt_started'); + }); + + it('releases a PII-free fence after the recipient ledger has expired', async () => { + const project = await fixture(); + const action = await admitEmailAction(env.db, input(project.id, 'expired')); + await transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'attempt_started', + ); + const [fence] = await env.db.select().from(emailUnresolvedAttempts); + await env.db + .update(emailUnresolvedAttempts) + .set({ started_at: new Date(Date.now() - 31 * 86_400_000).toISOString() }) + .where(eq(emailUnresolvedAttempts.id, fence!.id)); + await pruneEmailActionHistory(env.db, new Date(Date.now() + 60_000)); + expect((await getProjectEmailLogs(env.db, project.id)).logs).toHaveLength(0); + expect( + await resolveEmailUnresolvedAttempt(env.db, { + id: fence!.id, + ended: true, + reason: 'Worker execution ended; delivery record expired', + }), + ).toMatchObject({ metadataExpired: true, charged: true }); + expect(await env.db.select().from(emailUnresolvedAttempts)).toHaveLength(0); + expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); + expect(await drainProjectEmailAdmissions(env.db, project.id)).toEqual({ + cancelled: 0, + inFlight: 0, + }); + }); + it('replays one operation without a second quota debit and conflicts on changed payload', async () => { const project = await fixture(); const first = await admitEmailAction(env.db, input(project.id, 'same')); @@ -364,7 +501,7 @@ describe('authoritative email admission', () => { expect(closed.recipients.every((r) => r.errorCode === 'UNVERIFIED_DESTINATION')).toBe(true); }); - it('holds monthly quota after 30-day metadata pruning and clears it at month boundary', async () => { + it('holds current-month quota after metadata pruning while removing expired buckets', async () => { const project = await fixture(); await setProjectEmailLimits(env.db, project.id, { monthly: 1, burst: 10 }); const first = await admitEmailAction(env.db, input(project.id, 'first')); @@ -380,7 +517,18 @@ describe('authoritative email admission', () => { ['one@example.com'], 'provider_accepted', ); + await env.db.insert(emailMonthlyUsage).values([ + { project_id: project.id, month: '2000-01', recipient_attempts: 1 }, + { project_id: 'deleted-project', month: '2000-01', recipient_attempts: 2 }, + ]); await pruneEmailActionHistory(env.db, new Date(Date.now() + 60_000)); + expect(await env.db.select().from(emailMonthlyUsage)).toEqual([ + { + project_id: project.id, + month: new Date().toISOString().slice(0, 7), + recipient_attempts: 1, + }, + ]); expect((await getProjectEmailLogs(env.db, project.id)).logs).toHaveLength(0); expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); const second = await admitEmailAction(env.db, input(project.id, 'second')); diff --git a/platform/packages/api/test/integration/email-connections.test.ts b/platform/packages/api/test/integration/email-connections.test.ts index 26c5c959a..59168adea 100644 --- a/platform/packages/api/test/integration/email-connections.test.ts +++ b/platform/packages/api/test/integration/email-connections.test.ts @@ -9,6 +9,7 @@ import { it, vi, } from 'vite-plus/test'; +import { hmacSignState } from '../../src/auth/hmac.ts'; import { emailUnresolvedAttempts } from '../../src/email/admission-schema.ts'; import { disableEmailDomainRouteAndDrain } from '../../src/email/admission.ts'; import { @@ -28,16 +29,19 @@ import { requestEmailDomainRemove, requestEmailDomainSync, requestEmailSecretRotation, + readConnectionSecret, resolveEmailDomain, resolveEmailIngress, runEmailOperation, } from '../../src/email/connection-service.ts'; import type { ApiEnv } from '../../src/env.ts'; -import { projects } from '../../src/schema.ts'; +import { app } from '../../src/index.ts'; +import { deployments, projects } from '../../src/schema.ts'; import { callsByTag, stubCustomerCf } from './email-domain-cf-stub.ts'; import { clearTables, createTestProject, + createTestDeployment, createTestUser, setupEnv, teardownEnv, @@ -71,6 +75,167 @@ afterEach(() => { }); describe('durable zone email connections', () => { + it('resolves tenant dispatch limits from the owner plan and active deployment', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'ingress-limits'); + stubCustomerCf({ zones }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'limits.example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const deployment = await createTestDeployment(env.db, project.id); + await env.db + .update(deployments) + .set({ manifest: JSON.stringify({ emailProtocolVersion: 1, limits: { cpuMs: 100 } }) }) + .where(eq(deployments.id, deployment.id)); + const { connection } = (await resolveEmailDomain(env.db, 'limits.example.com'))!; + const to = 'support@limits.example.com'; + const proof = await hmacSignState( + `email-ingress-v1\n${connection.account_id}\n${connection.zone_id}\n${connection.ingress_worker_name}\n${to}`, + env.JWT_SECRET, + ); + const response = await app.fetch( + new Request('https://api/internal/email/resolve-ingress', { + method: 'POST', + headers: { 'content-type': 'application/json', 'x-void-internal': proof }, + body: JSON.stringify({ + accountId: connection.account_id, + zoneId: connection.zone_id, + ingressName: connection.ingress_worker_name, + to, + secret: await readConnectionSecret(bindings(), connection), + }), + }), + bindings(), + ); + expect(response.status).toBe(200); + expect(await response.json()).toMatchObject({ + projectId: project.id, + deploymentId: deployment.id, + limits: { cpuMs: 10, subRequests: 50 }, + }); + }); + + it('does not treat a DNS resolver failure as an unused mail domain', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'dns-failure'); + const stub = stubCustomerCf({ zones, dnsStatus: 2 }); + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }), + ).rejects.toThrow('DNS MX lookup'); + expect(stub.calls.filter((call) => call.method !== 'GET')).toEqual([]); + expect(await env.db.select().from(emailOperations)).toEqual([]); + }); + + it('lets newer operations progress while an older write remains unknown', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'reconcile-fairness'); + const failures: NonNullable[0]>['failOn'] = { + scriptPut: { message: 'write outcome unknown', status: 504 }, + }; + const stub = stubCustomerCf({ + zones: { + ...zones, + 'other.test': { id: 'zone-other', name: 'other.test', accountId: 'customer-account' }, + }, + failOn: failures, + }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const first = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'mail.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), first.operationId); + delete failures.scriptPut; + const second = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'mail.other.test', + actor, + token: TOKEN, + }); + await env.db + .update(emailOperations) + .set({ updated_at: '2020-01-01T00:00:00Z' }) + .where(eq(emailOperations.id, first.operationId)); + await reconcilePendingEmailOperations(env.db, bindings(), 1); + expect((await getEmailOperation(env.db, project.id, first.operationId))?.operation.status).toBe( + 'unknown', + ); + await reconcilePendingEmailOperations(env.db, bindings(), 1); + expect( + (await getEmailOperation(env.db, project.id, second.operationId))?.operation.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(2); + }); + + it('keeps uncertain Sending onboarding recoverable without repeating its write', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'sending-uncertain'); + const failures: NonNullable[0]>['failOn'] = { + onboardSending: { message: 'write outcome unavailable', status: 504 }, + sendingSubdomainsGet: { message: 'readback unavailable', status: 504 }, + }; + const senders: Array<{ name: string; enabled: boolean }> = []; + const stub = stubCustomerCf({ zones, failOn: failures, sendingSubdomains: senders }); + const { operationId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'sending.example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), operationId); + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'unknown', + ); + expect((await resolveEmailDomain(env.db, 'sending.example.com'))?.route).toMatchObject({ + inbound_status: 'ready', + outbound_status: 'pending', + }); + delete failures.sendingSubdomainsGet; + senders.push({ name: 'sending.example.com', enabled: true }); + await reconcilePendingEmailOperations(env.db, bindings()); + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'completed', + ); + expect((await resolveEmailDomain(env.db, 'sending.example.com'))?.route.outbound_status).toBe( + 'ready', + ); + expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(1); + }); + + it('does not report sync ready after the domain loses its MX records', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'mx-drift'); + const mx: Record> = {}; + stubCustomerCf({ zones, mx }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'mx.example.com', + token: TOKEN, + actor, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + mx['mx.example.com'] = []; + const sync = await requestEmailDomainSync(env.db, bindings(), added.routeId, actor); + await runEmailOperation(env.db, bindings(), sync); + expect((await getEmailOperation(env.db, project.id, sync))?.operation.status).toBe('blocked'); + expect((await resolveEmailDomain(env.db, 'mx.example.com'))?.route).toMatchObject({ + inbound_status: 'drifted', + inbound_reason: expect.stringContaining('MX records'), + }); + }); + it('checks MX and explicit routing conflicts for new assignments on an existing zone', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'sibling-preflight'); @@ -841,6 +1006,7 @@ describe('durable zone email connections', () => { accountId: env.CF_ACCOUNT_ID, }, }, + mx: { 'example.com': ['route1.mx.cloudflare.net'] }, }); const bootstrap = await ensureSharedEmailConnection(env.db, shared); expect(bootstrap).toBeTruthy(); diff --git a/platform/packages/api/test/integration/email-domain-cf-stub.ts b/platform/packages/api/test/integration/email-domain-cf-stub.ts index 3f8b963ab..b0a0d5814 100644 --- a/platform/packages/api/test/integration/email-domain-cf-stub.ts +++ b/platform/packages/api/test/integration/email-domain-cf-stub.ts @@ -41,6 +41,7 @@ export function stubCustomerCf( verifyStatus?: string; verifyExpiresOn?: string | null; mx?: Record>; + dnsStatus?: number; existingScripts?: ReadonlyArray; /** * Initial catch-all state, applied to every zone. Absent → CF's real @@ -60,6 +61,7 @@ export function stubCustomerCf( } = {}, ) { const calls: Array = []; + const publishedMx = new Map>(); const fail = (tag: StubFailTag): Response | null => { const failure = config.failOn?.[tag]; return failure ? cfError(failure.message, failure.status, failure.code) : null; @@ -101,8 +103,9 @@ export function stubCustomerCf( return failure; } const name = new URL(url).searchParams.get('name') ?? ''; - const exchanges = config.mx?.[name] ?? []; + const exchanges = config.mx?.[name] ?? publishedMx.get(name) ?? []; return Response.json({ + Status: config.dnsStatus ?? 0, Answer: exchanges.map((exchange) => ({ type: 15, data: `10 ${exchange}.` })), }); } @@ -228,7 +231,17 @@ export function stubCustomerCf( if (path.includes('/email/routing/dns') && method === 'POST') { const body = typeof init?.body === 'string' ? JSON.parse(init.body) : undefined; await record({ tag: 'routingDns', method, url, body }); - return fail('routingDns') ?? cfSuccess({}); + const failure = fail('routingDns'); + if (failure) { + return failure; + } + const zoneId = path.split('/')[2]; + const name = + body?.name ?? Object.values(config.zones ?? {}).find((zone) => zone.id === zoneId)?.name; + if (name) { + publishedMx.set(name, ['route1.mx.cloudflare.net']); + } + return cfSuccess({}); } if (path.includes('/email/sending/subdomains') && method === 'POST') { diff --git a/platform/packages/api/test/integration/helpers.ts b/platform/packages/api/test/integration/helpers.ts index b476953da..0b0604c6f 100644 --- a/platform/packages/api/test/integration/helpers.ts +++ b/platform/packages/api/test/integration/helpers.ts @@ -468,6 +468,7 @@ export async function teardownEnv(): Promise { export async function clearTables(db: Db): Promise { for (const table of [ + schema.emailDestinationCleanups, schema.emailOperationSteps, schema.emailOperations, schema.emailDomainRoutes, diff --git a/platform/packages/api/test/integration/operator-email.test.ts b/platform/packages/api/test/integration/operator-email.test.ts index 6a7388a69..3f314929a 100644 --- a/platform/packages/api/test/integration/operator-email.test.ts +++ b/platform/packages/api/test/integration/operator-email.test.ts @@ -9,8 +9,16 @@ import { test, vi, } from 'vite-plus/test'; -import { emailProjectControls } from '../../src/email/admission-schema.ts'; -import { setProjectEmailLimits } from '../../src/email/admission.ts'; +import { + emailActionRecipients, + emailProjectControls, + emailUnresolvedAttempts, +} from '../../src/email/admission-schema.ts'; +import { + admitEmailAction, + setProjectEmailLimits, + transitionEmailRecipients, +} from '../../src/email/admission.ts'; import { EMAIL_DOMAIN_MANAGEMENT_SETTING, EMAIL_RECIPIENT_POLICY_MIRROR_KEY, @@ -18,7 +26,7 @@ import { } from '../../src/email/settings.ts'; import type { ApiEnv } from '../../src/env.ts'; import { app } from '../../src/index.ts'; -import { operatorEvents, platformSettings } from '../../src/schema.ts'; +import { emailDestinations, operatorEvents, platformSettings } from '../../src/schema.ts'; import { clearTables, createOperatorToken, @@ -196,65 +204,6 @@ describe('operator email recipient policy', () => { put.mockRestore(); }); - test('publishes display hints without deleting policy keys', async () => { - const put = vi.spyOn(env.ROUTING, 'put'); - const del = vi.spyOn(env.ROUTING, 'delete'); - - expect((await req('/email/policy', { mode: 'domains', domains: 'a.example' })).status).toBe( - 200, - ); - expect(put).toHaveBeenCalled(); - expect(del).not.toHaveBeenCalled(); - - expect((await req('/email/policy', { mode: 'verified' })).status).toBe(200); - expect(put.mock.calls.length).toBeGreaterThan(1); - expect(del).not.toHaveBeenCalled(); - }); - - test('a list edited both ways publishes as a widening', async () => { - await req('/email/policy', { mode: 'domains', domains: 'a.example,b.example' }); - const put = vi.spyOn(env.ROUTING, 'put').mockRejectedValueOnce(new Error('kv down')); - const response = await req('/email/policy', { - mode: 'domains', - domains: 'b.example,c.example', - }); - expect(response.status).toBe(200); - expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ - mode: 'domains', - domains: ['b.example', 'c.example'], - }); - expect(await env.ROUTING.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)).toBe( - JSON.stringify({ mode: 'domains', domains: ['a.example', 'b.example'] }), - ); - put.mockRestore(); - await req('/email/policy'); - expect(await env.ROUTING.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)).toBe( - JSON.stringify({ mode: 'domains', domains: ['b.example', 'c.example'] }), - ); - }); - - test('a grown list is a widening', async () => { - await req('/email/policy', { mode: 'domains', domains: 'a.example' }); - const put = vi.spyOn(env.ROUTING, 'put').mockRejectedValueOnce(new Error('kv down')); - const response = await req('/email/policy', { - mode: 'domains', - domains: 'a.example,b.example', - }); - expect(response.status).toBe(200); - expect(await setting(EMAIL_RECIPIENT_POLICY_SETTING)).toEqual({ - mode: 'domains', - domains: ['a.example', 'b.example'], - }); - expect(await env.ROUTING.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)).toBe( - JSON.stringify({ mode: 'domains', domains: ['a.example'] }), - ); - put.mockRestore(); - await req('/email/policy'); - expect(await env.ROUTING.get(EMAIL_RECIPIENT_POLICY_MIRROR_KEY)).toBe( - JSON.stringify({ mode: 'domains', domains: ['a.example', 'b.example'] }), - ); - }); - test('is unavailable when the platform does not enable email', async () => { const response = await req('/email/policy', undefined, { PLATFORM_CAPABILITIES: JSON.stringify({ @@ -400,3 +349,88 @@ describe('operator email limits', () => { ); }); }); + +describe('operator email attempt recovery', () => { + test('lists only PII-free fences and audits an explicitly attested resolution', async () => { + const owner = await createTestUser(env.db, 'attempt-owner'); + const project = await createTestProject(env.db, owner.id, 'attempt-project'); + await env.db.insert(emailDestinations).values({ + id: 'attempt-destination', + project_id: project.id, + address: 'recipient@example.com', + status: 'verified', + }); + const action = await admitEmailAction(env.db, { + projectId: project.id, + kind: 'direct', + key: 'attempt-key', + digest: 'a'.repeat(64), + from: 'attempt-project+news@mail.example.com', + recipients: ['recipient@example.com'], + transport: 'binding', + sharedSenderDomain: 'mail.example.com', + }); + await transitionEmailRecipients( + env.db, + action.operationId, + ['recipient@example.com'], + 'attempt_started', + ); + const [fence] = await env.db.select().from(emailUnresolvedAttempts); + const list = await req(`/email/attempts?project=${project.slug}`); + expect(list.status).toBe(200); + const listed = await list.json(); + expect(listed).toMatchObject({ + total: 1, + attempts: [{ id: fence!.id, projectId: project.id }], + }); + expect(JSON.stringify(listed)).not.toContain('recipient@example.com'); + + const tooRecent = await req(`/email/attempts/${fence!.id}/resolve`, { + ended: true, + reason: 'Original Worker execution ended', + dryRun: true, + }); + expect(tooRecent.status).toBe(409); + const old = new Date(Date.now() - 25 * 60 * 60_000).toISOString(); + await env.db + .update(emailUnresolvedAttempts) + .set({ started_at: old }) + .where(eq(emailUnresolvedAttempts.id, fence!.id)); + await env.db + .update(emailActionRecipients) + .set({ attempt_started_at: old }) + .where(eq(emailActionRecipients.id, fence!.id)); + const missingAttestation = await req(`/email/attempts/${fence!.id}/resolve`, { + reason: 'Original Worker execution ended', + dryRun: true, + }); + expect(missingAttestation.status).toBe(400); + const preview = await req(`/email/attempts/${fence!.id}/resolve`, { + ended: true, + reason: 'Original Worker execution ended', + dryRun: true, + }); + expect(preview.status).toBe(200); + expect(await preview.json()).toMatchObject({ dryRun: true, action: 'email.attempt.resolve' }); + expect(await events()).toHaveLength(0); + const response = await req(`/email/attempts/${fence!.id}/resolve`, { + ended: true, + reason: 'Original Worker execution ended', + }); + expect(response.status).toBe(200); + expect(await response.json()).toMatchObject({ state: 'outcome_unknown', charged: true }); + expect(((await (await req('/email/attempts')).json()) as { total: number }).total).toBe(0); + const recorded = await events(); + expect(recorded).toHaveLength(1); + expect(recorded[0]).toMatchObject({ + action: `email/attempts/${fence!.id}/resolve`, + status: 'success', + }); + expect(JSON.parse(recorded[0]!.target)).toEqual({ + attemptId: fence!.id, + ended: true, + reason: 'Original Worker execution ended', + }); + }); +}); diff --git a/platform/packages/api/test/unit/email-routing.test.ts b/platform/packages/api/test/unit/email-routing.test.ts new file mode 100644 index 000000000..1815ef43c --- /dev/null +++ b/platform/packages/api/test/unit/email-routing.test.ts @@ -0,0 +1,14 @@ +import { describe, expect, it } from 'vite-plus/test'; +import { CloudflareApiError } from '../../src/provisioning/cloudflare-api.ts'; +import { isAlreadyExistsError } from '../../src/provisioning/email-routing.ts'; + +describe('Cloudflare email destination errors', () => { + it('recognizes the structured already-exists code without depending on message text', () => { + expect( + isAlreadyExistsError(new CloudflareApiError('localized provider error', 400, [10037])), + ).toBe(true); + expect( + isAlreadyExistsError(new CloudflareApiError('localized provider error', 400, [1000])), + ).toBe(false); + }); +}); diff --git a/platform/packages/api/test/unit/email-settings.test.ts b/platform/packages/api/test/unit/email-settings.test.ts index d3bf6f1d3..37e9f21b8 100644 --- a/platform/packages/api/test/unit/email-settings.test.ts +++ b/platform/packages/api/test/unit/email-settings.test.ts @@ -4,7 +4,6 @@ import { MAX_POLICY_DOMAINS, normalizeEmailRecipientPolicy, serializeEmailRecipientPolicyMirror, - widensEmailRecipientPolicy, } from '../../src/email/settings.ts'; describe('normalizeEmailRecipientPolicy', () => { @@ -59,74 +58,6 @@ describe('normalizeEmailRecipientPolicy', () => { }); }); -describe('widensEmailRecipientPolicy', () => { - it.each([ - [ - 'verified → domains', - { mode: 'verified', domains: [] }, - { mode: 'domains', domains: ['a.example'] }, - true, - ], - [ - 'domains → any', - { mode: 'domains', domains: ['a.example'] }, - { mode: 'any', domains: [] }, - true, - ], - [ - 'any → domains', - { mode: 'any', domains: [] }, - { mode: 'domains', domains: ['a.example'] }, - false, - ], - [ - 'domains → verified', - { mode: 'domains', domains: ['a.example'] }, - { mode: 'verified', domains: [] }, - false, - ], - [ - 'grown domains list', - { mode: 'domains', domains: ['a.example'] }, - { mode: 'domains', domains: ['a.example', 'b.example'] }, - true, - ], - [ - 'shrunk domains list', - { mode: 'domains', domains: ['a.example', 'b.example'] }, - { mode: 'domains', domains: ['a.example'] }, - false, - ], - [ - 'edited domains list', - { mode: 'domains', domains: ['a.example', 'b.example'] }, - { mode: 'domains', domains: ['b.example', 'c.example'] }, - true, - ], - [ - 'pure shrink retaining a different entry', - { mode: 'domains', domains: ['a.example', 'b.example'] }, - { mode: 'domains', domains: ['b.example'] }, - false, - ], - [ - 'replaced domains list', - { mode: 'domains', domains: ['a.example'] }, - { mode: 'domains', domains: ['b.example'] }, - true, - ], - [ - 'unchanged domains list', - { mode: 'domains', domains: ['a.example'] }, - { mode: 'domains', domains: ['a.example'] }, - false, - ], - ['any → any', { mode: 'any', domains: [] }, { mode: 'any', domains: [] }, false], - ] as const)('%s: %s', (_label, prev, next, expected) => { - expect(widensEmailRecipientPolicy(prev, next)).toBe(expected); - }); -}); - describe('serializeEmailRecipientPolicyMirror', () => { it('is the exact wire shape the proxy parses', () => { expect(serializeEmailRecipientPolicyMirror({ mode: 'domains', domains: ['a.example'] })).toBe( diff --git a/platform/packages/email-gateway/src/index.ts b/platform/packages/email-gateway/src/index.ts index 7f4bfa8ff..e24099647 100644 --- a/platform/packages/email-gateway/src/index.ts +++ b/platform/packages/email-gateway/src/index.ts @@ -10,6 +10,7 @@ import type { Env as ProxyEnv } from '../../proxy/src/types.ts'; type Env = ProxyEnv & { PLATFORM_INSTALLATION_ID?: string; + PLATFORM_VERSION?: string; PLATFORM_TRAFFIC_STATE?: string; EMAIL_SHARED_ACCOUNT_ID?: string; EMAIL_SHARED_ZONE_ID?: string; @@ -469,7 +470,12 @@ export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { const url = new URL(request.url); if (request.method === 'GET' && url.pathname === '/health') { - return Response.json({ ok: true }); + return Response.json({ + ok: true, + installationId: env.PLATFORM_INSTALLATION_ID, + platformVersion: env.PLATFORM_VERSION, + emailProtocolVersion: 1, + }); } if (request.method !== 'POST') { return new Response(null, { status: 404 }); @@ -487,6 +493,12 @@ export default { return new Response(null, { status: 404 }); }, async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise { + if ( + env.PLATFORM_TRAFFIC_STATE === 'staging' || + env.PLATFORM_TRAFFIC_STATE === 'sandbox-drain' + ) { + throw new Error('Email gateway temporarily unavailable'); + } const accountId = env.EMAIL_SHARED_ACCOUNT_ID; const zoneId = env.EMAIL_SHARED_ZONE_ID; const ingressName = env.EMAIL_SHARED_INGRESS_NAME; diff --git a/platform/packages/email-gateway/test/unit/gateway.test.ts b/platform/packages/email-gateway/test/unit/gateway.test.ts index da2747117..000c8f7cd 100644 --- a/platform/packages/email-gateway/test/unit/gateway.test.ts +++ b/platform/packages/email-gateway/test/unit/gateway.test.ts @@ -58,6 +58,20 @@ beforeEach(() => { }); describe('dedicated email gateway', () => { + it('reports its deployment identity and protocol for installation health checks', async () => { + const response = await gateway.fetch( + new Request('https://gateway.example/health'), + { PLATFORM_INSTALLATION_ID: 'installation', PLATFORM_VERSION: '1.2.3' } as never, + context, + ); + expect(await response.json()).toEqual({ + ok: true, + installationId: 'installation', + platformVersion: '1.2.3', + emailProtocolVersion: 1, + }); + }); + function receiptApi() { const receipts = new Map(); return vi.fn(async (url: unknown, init?: unknown) => { @@ -153,6 +167,29 @@ describe('dedicated email gateway', () => { expect(message.setReject).not.toHaveBeenCalled(); }); + it.each(['staging', 'sandbox-drain'])( + 'does not dispatch native email during %s', + async (state) => { + const apiFetch = vi.fn(); + const environment = { + ...env(apiFetch), + PLATFORM_TRAFFIC_STATE: state, + } as never; + const message = { + from: 'sender@example.net', + to: 'support@example.com', + setReject: vi.fn(), + } as unknown as ForwardableEmailMessage; + + await expect(gateway.email(message, environment, context)).rejects.toThrow( + 'temporarily unavailable', + ); + expect(message.setReject).not.toHaveBeenCalled(); + expect(apiFetch).not.toHaveBeenCalled(); + expect(router.routeInbound).not.toHaveBeenCalled(); + }, + ); + it.each([ () => new Response(null), () => new Response('{'), diff --git a/platform/packages/proxy/src/email-router.ts b/platform/packages/proxy/src/email-router.ts index 96f445363..a4d5e3eb6 100644 --- a/platform/packages/proxy/src/email-router.ts +++ b/platform/packages/proxy/src/email-router.ts @@ -14,12 +14,12 @@ import { import { leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; import { MAX_MIME_BYTES, + classifySendRawRecipient, + parseSendRawResult, readMimeFromAddrSpec, readSenderDomain, - readSendRawAddressList, recordInboundDelivery, } from './email.ts'; -import type { SendRawResult } from './email.ts'; import type { Env } from './types.ts'; // Built via new RegExp to dodge oxlint no-control-regex rule. @@ -406,7 +406,7 @@ export async function routeRelayed( // delivery against it, exactly as `routeInbound` logs against the real // message. The domain + authenticated project id key its REST send path // (the customer account's send_raw with the domain's leased credential). - const relayed = createRelayedMessage(env, envelope, { domain, projectId }); + const relayed = createRelayedMessage(envelope); const gate: OutboundGate = { projectId, @@ -456,27 +456,48 @@ export async function routeRelayed( return { reject: relayed.rejectedReason() !== null }; } -/** A message stand-in for relayed replies; forwarding requires a native event. */ -function createRelayedMessage( - env: Env, - envelope: EmailEnvelope, - relay: { domain: string; projectId: string }, -): { message: ForwardableEmailMessage; rejectedReason: () => string | null } { +/** A message stand-in for relayed delivery; forwarding requires a native event. */ +function createRelayedMessage(envelope: EmailEnvelope): { + message: ForwardableEmailMessage; + rejectedReason: () => string | null; +} { let reason: string | null = null; - // Relayed replies use the customer account's Email Sending API. - async function sendRaw(from: string, to: string, raw: Uint8Array): Promise { - // The account is selected by the reply sender's verified domain. - const senderDomain = from.slice(from.indexOf('@') + 1).toLowerCase(); - // A fresh lease checks project ownership at send time. - const lease = await leaseEmailDomainCredential(env, senderDomain, relay.projectId); - if (!lease) { - throw new Error('could not lease the domain credential'); - } - // send_raw carries the MIME as a JSON string. Decode FATALLY, as the - // outbound fork does: relayed mail is remote-sender bytes, and a lenient - // decode would silently alter a non-UTF-8 body. - const mimeMessage = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(raw); + const message = { + from: envelope.from, + to: envelope.to, + rawSize: envelope.rawSize, + headers: new Headers(envelope.headers), + raw: envelopeRawStream(envelope.raw), + setReject(r: string) { + reason = r; + }, + async forward(_to: string, _headers?: Headers) { + throw new DefinitiveEmailActionError('relayed forward requires a native email event'); + }, + }; + return { + message: message as unknown as ForwardableEmailMessage, + rejectedReason: () => reason, + }; +} + +// Finish all local work before attempt_started: a missing lease or invalid +// MIME means no provider submission occurred and the reservation can be cancelled. +async function prepareRelayedReply( + env: Env, + projectId: string, + from: string, + raw: Uint8Array, + expectedAccountId?: string, +): Promise<(to: string) => Promise> { + const senderDomain = from.slice(from.indexOf('@') + 1).toLowerCase(); + const lease = await leaseEmailDomainCredential(env, senderDomain, projectId); + if (!lease || (expectedAccountId && lease.accountId !== expectedAccountId)) { + throw new Error('could not lease the domain credential'); + } + const mimeMessage = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(raw); + return async (to) => { let res: Response; try { res = await fetch( @@ -494,54 +515,40 @@ function createRelayedMessage( throw new Error('email sending request failed'); } if (!res.ok) { + if (res.status >= 500 || res.status === 408) { + throw new Error('email sending API outcome unknown'); + } throw new DefinitiveEmailActionError(`email sending API returned ${res.status}`); } - let data: unknown = null; + let data: unknown; try { data = await res.json(); } catch { - data = null; + throw new Error('email sending API response unreadable'); } - const success = - typeof data === 'object' && data !== null && (data as { success?: unknown }).success === true; - if (!success) { + if (typeof data !== 'object' || data === null || !('success' in data)) { + throw new Error('email sending API response invalid'); + } + if (data.success === false) { throw new DefinitiveEmailActionError('email sending API refused the message'); } - // success:true with the one recipient on a failure list is NOT sent — - // the same per-recipient read the outbound fork makes. - const result = (data as { result?: SendRawResult | null }).result; - const target = to.toLowerCase(); - if (readSendRawAddressList(result?.permanent_bounces).has(target)) { + if (data.success !== true) { + throw new Error('email sending API response invalid'); + } + const result = parseSendRawResult((data as { result?: unknown }).result); + if (!result) { + throw new Error('email sending API response invalid'); + } + const outcome = classifySendRawRecipient(result, to); + if (outcome === 'permanent_bounce') { throw new DefinitiveEmailActionError('recipient permanently bounced'); } - if (readSendRawAddressList(result?.suppressed_recipients).has(target)) { + if (outcome === 'suppressed') { throw new DefinitiveEmailActionError('recipient is on the suppression list'); } - } - - const message = { - from: envelope.from, - to: envelope.to, - rawSize: envelope.rawSize, - headers: new Headers(envelope.headers), - raw: envelopeRawStream(envelope.raw), - setReject(r: string) { - reason = r; - }, - async forward(_to: string, _headers?: Headers) { - throw new DefinitiveEmailActionError('relayed forward requires a native email event'); - }, - // The reply channel `enactSanitized` prefers when present. A native - // reply needs both the CF email event this lane never had and a genuine - // EmailMessage — whose class exposes no body accessor, so the recorded - // reply bytes could not cross it anyway; they arrive on the action. - async __voidRelayReply(from: string, to: string, raw: Uint8Array) { - await sendRaw(from, to, raw); - }, - }; - return { - message: message as unknown as ForwardableEmailMessage, - rejectedReason: () => reason, + if (outcome === 'outcome_unknown') { + throw new Error('email sending API did not classify the recipient'); + } }; } @@ -566,23 +573,17 @@ async function logRecv( ); return; } - // Guard the RAW list the same way `validateActions` does. A user worker can - // return anything, this runs OUTSIDE the try below, and it is scheduled on - // `ctx.waitUntil` — so a null entry used to escape as an unhandled rejection - // and silently cost the delivery its recv counter and its audit line. + // Guard the raw list the same way `validateActions` does because a tenant + // response can contain arbitrary values. const status = actions.some((a) => a && typeof a === 'object' && a.type === 'reject') ? 'rejected' : actions.length === 0 ? 'accepted' : 'handled'; try { - await recordInboundDelivery(env, projectId, { + await recordInboundDelivery(projectId, { from: String(message.from ?? ''), to: String(message.to ?? ''), - // sanitize() in email.ts handles control-char stripping before logging; - // don't pre-truncate here so the full subject is available if logging - // ever moves to structured storage. - subject: message.headers.get('Subject') ?? '', byteSize: message.rawSize ?? 0, status, }); @@ -882,6 +883,24 @@ async function enactSanitized( if (admission.replay || admitted?.state !== 'reserved') { continue; } + let relayedReply: ((to: string) => Promise) | undefined; + if (gate.transport === 'relay' && action.type === 'reply') { + try { + relayedReply = await prepareRelayedReply( + env, + gate.projectId, + action.from, + action.raw, + admission.accountId, + ); + } catch { + await finishEmailAttempt(env, admission.operationId, [to], 'cancelled').catch(() => { + console.error('[email-router] could not cancel unsubmitted relayed reply'); + }); + console.error('[email-router] relayed reply could not be prepared'); + continue; + } + } try { await startEmailAttempt(env, admission.operationId, [to]); } catch { @@ -892,13 +911,8 @@ async function enactSanitized( if (action.type === 'forward') { await message.forward(to, action.headers); } else { - const relayReply = ( - message as unknown as { - __voidRelayReply?: (from: string, to: string, raw: Uint8Array) => Promise; - } - ).__voidRelayReply; - if (relayReply) { - await relayReply(action.from, to, action.raw); + if (relayedReply) { + await relayedReply(to); } else { const stream = new ReadableStream({ start(controller) { diff --git a/platform/packages/proxy/src/email.ts b/platform/packages/proxy/src/email.ts index f14d62739..d97227ddf 100644 --- a/platform/packages/proxy/src/email.ts +++ b/platform/packages/proxy/src/email.ts @@ -70,34 +70,12 @@ export function customMimeHeaderBytesWithinLimit(raw: Uint8Array): boolean { return true; } -/** - * Cap the recipient list. Every entry costs a trimmed+lowercased copy, a - * `seen` Set entry, and — for an address this project's allowlist rejects — - * one delivery object whose message interpolates the address, all of which - * is then serialized into the response. That is ~360 bytes of isolate heap - * per recipient, so an uncapped list reaches the 128 MB per-isolate ceiling - * from a ~2.5 MB request body. A tenant worker holds a valid project HMAC, - * so it can POST that body to the public proxy hostname, and the - * all-rejected path returns ABOVE the burst and monthly gates — the work is - * never metered and the request is endlessly repeatable. The proxy isolate - * is shared with every other tenant's in-flight AI/D1/KV/R2 traffic, so the - * kill is cross-tenant. The MIME cap does not bound this: `bcc` recipients - * are deliberately kept out of the rendered headers, so a huge bcc list - * costs nothing against `MAX_MIME_BYTES`. - * - * Checked against the RAW array BEFORE the normalization loop below. The - * loop is what allocates, so deduping first would already have paid the - * per-entry cost for a list of duplicates. - */ +/** Bound the raw list before normalization allocates one copy and Set entry per recipient. */ const MAX_RECIPIENTS = 100; /** - * Cap a single recipient string. `MAX_RECIPIENTS` alone still leaves a - * 100 x
amplifier, because `.trim().toLowerCase()` copies - * the entry — and the allowlist-rejection message interpolates it a second - * time — before anything has looked at its size. Checked BEFORE that - * normalization for exactly that reason. RFC 5321 caps a forward-path at - * 256 octets, so 320 is generous for any address that could be delivered. + * Bound each address before normalization copies it. RFC 5321 caps a + * forward-path at 256 octets, so 320 characters leaves room for validation. */ export const MAX_RECIPIENT_LENGTH = 320; @@ -107,11 +85,8 @@ export const MAX_RECIPIENT_LENGTH = 320; * (measured: V8 returns a fresh full-size string even when nothing * changed), and a sender the strict regex accepts — an unbounded `+tag` * is one — is then echoed verbatim into the MIME `From:` refusal and - * serialized into the response, three more copies of it. All of that runs - * above the allowlist and quota gates, so it is never metered. Checked - * with the other raw-input size gates, before any configuration or KV - * read. Same figure as `MAX_RECIPIENT_LENGTH`, for the same RFC 5321 - * reason. + * serialized into the response. Check it before those copies. The limit + * matches `MAX_RECIPIENT_LENGTH`. * * Both are exported for the platform-token gate in `index.ts`, which * applies them to `/email/internal/send`'s `from` and `to` BEFORE hashing @@ -514,13 +489,9 @@ function singleMailboxAddrSpec(value: string): string | null { * requestId, fromDomain? // for logs * } * - * The proxy: - * 1. Validates structure + size - * 2. Checks platform suspension (`routing.suspended`) and the per-project - * email suspend kill-switch - * 3. Admits the send against the SQL recipient policy and quota ledger - * 4. Calls `env.SEND_EMAIL.send()` per admitted recipient - * 5. Returns per-recipient outcomes to the framework + * The proxy validates and normalizes the request, routes custom senders to + * `send_raw`, and otherwise asks the API to admit each recipient before using + * the platform `send_email` binding. * * The user worker does not have a `send_email` binding. */ @@ -593,10 +564,7 @@ app.post('/send', async (context) => { ); } - // Fail closed on missing sender configuration — never fall back to a - // baked-in domain (see readSenderDomain). Resolved before any KV work so a - // misconfigured environment can't burn quota counters on a send that can't - // possibly be authorized. + // Fail closed on missing sender configuration before admission. const senderDomain = readSenderDomain(context.env); if (!senderDomain) { return context.json( @@ -611,25 +579,8 @@ app.post('/send', async (context) => { ); } - // Same reasoning for the send binding itself. Wrangler does not inherit - // `send_email` into a named env, so a binding missing from one env block - // would otherwise surface as a throw AFTER both counters were incremented. - const sendBinding = context.env.SEND_EMAIL; - if (typeof sendBinding?.send !== 'function') { - return context.json( - { - ok: false, - error: { - code: 'UPSTREAM_ERROR', - message: 'email sending is not configured', - }, - }, - 502, - ); - } - // Recipients must be unique strings; the framework already dedups but we - // re-validate so a buggy client can't double-charge quota or pollute logs. + // re-validate so a buggy client cannot create duplicate attempts or logs. const recipients: Array = []; const seen = new Set(); for (const r of recipientsRaw) { @@ -732,6 +683,22 @@ app.post('/send', async (context) => { ); } + // Custom-domain sends use send_raw and do not depend on this binding. + // Check the platform binding before shared-domain admission starts. + const sendBinding = context.env.SEND_EMAIL; + if (typeof sendBinding?.send !== 'function') { + return context.json( + { + ok: false, + error: { + code: 'UPSTREAM_ERROR', + message: 'email sending is not configured', + }, + }, + 502, + ); + } + // Sender ownership is checked against PostgreSQL by the admission service. const expectedSlug = from.split('@')[0]?.split('+')[0] ?? ''; // Lowercase once for the strict regex + slug compare; the regex anchors @@ -802,8 +769,8 @@ app.post('/send', async (context) => { ); } - // The API transaction is authoritative for project state, sender identity, consent, - // suspension and both recipient-attempt quotas. KV is only a routing hint. + // The API transaction is authoritative for project state, sender identity, + // recipient consent, suspension, and attempt quotas. let admission; try { admission = await admitEmail(context.env, { @@ -962,29 +929,101 @@ app.post('/send', async (context) => { * The Email Sending REST `send_raw` result. snake_case — the REST schema * names the id `message_id`, unlike the `send_email` binding's camelCase * `messageId` (and the api's `SendRawResult` in `email/cf-customer.ts`, - * which declares the same field). `delivered` and `queued` are both - * success for our purposes; `permanent_bounces` and - * `suppressed_recipients` are per-recipient permanent failures. + * which declares the same field). Cloudflare returns every recipient in + * exactly one required list: `delivered` and `queued` are accepted; + * `permanent_bounces` and `suppressed_recipients` are permanent failures. */ export interface SendRawResult { + delivered?: unknown; message_id?: unknown; permanent_bounces?: unknown; + queued?: unknown; suppressed_recipients?: unknown; } -/** A send_raw address list as a lowercase set; non-string entries are dropped. */ -export function readSendRawAddressList(value: unknown): Set { +export interface ParsedSendRawResult { + delivered: ReadonlySet; + messageId: string; + permanentBounces: ReadonlySet; + queued: ReadonlySet; + suppressedRecipients: ReadonlySet; +} + +export type SendRawRecipientOutcome = + | 'provider_accepted' + | 'permanent_bounce' + | 'suppressed' + | 'outcome_unknown'; + +/** Read one required send_raw address list without discarding schema violations. */ +function readSendRawAddressList(value: unknown): Set | null { + if (!Array.isArray(value)) { + return null; + } const out = new Set(); - if (Array.isArray(value)) { - for (const entry of value) { - if (typeof entry === 'string') { - out.add(entry.toLowerCase()); - } + for (const entry of value) { + if (typeof entry !== 'string') { + return null; } + out.add(entry.toLowerCase()); } return out; } +/** + * Parse the documented send_raw result shape. Every recipient is classified by + * exactly one of four required lists; accepting a partial response would turn + * missing provider evidence into a false success. + */ +export function parseSendRawResult(value: unknown): ParsedSendRawResult | null { + if (!value || typeof value !== 'object' || Array.isArray(value)) { + return null; + } + const result = value as SendRawResult; + const delivered = readSendRawAddressList(result.delivered); + const permanentBounces = readSendRawAddressList(result.permanent_bounces); + const queued = readSendRawAddressList(result.queued); + const suppressedRecipients = readSendRawAddressList(result.suppressed_recipients); + if ( + !delivered || + !permanentBounces || + !queued || + !suppressedRecipients || + typeof result.message_id !== 'string' || + result.message_id === '' + ) { + return null; + } + return { + delivered, + messageId: result.message_id, + permanentBounces, + queued, + suppressedRecipients, + }; +} + +/** Require exactly one provider classification for the requested recipient. */ +export function classifySendRawRecipient( + result: ParsedSendRawResult, + recipient: string, +): SendRawRecipientOutcome { + const target = recipient.toLowerCase(); + const classifications = [ + result.delivered.has(target), + result.queued.has(target), + result.permanentBounces.has(target), + result.suppressedRecipients.has(target), + ]; + if (classifications.filter(Boolean).length !== 1) { + return 'outcome_unknown'; + } + if (classifications[0] || classifications[1]) { + return 'provider_accepted'; + } + return classifications[2] ? 'permanent_bounce' : 'suppressed'; +} + /** Send through the customer's Cloudflare account after project-bound admission. */ async function sendViaCustomDomain( context: Context, @@ -1032,7 +1071,7 @@ async function sendViaCustomDomain( // send_raw carries the MIME as a JSON string. Decode FATALLY: the // framework's builder emits 7-bit-clean MIME, and a body that is not // valid UTF-8 would be silently altered by a lenient decode — refuse it - // instead. Local validation, so it runs before any quota is burned. + // instead. Local validation runs before admission. let mimeMessage: string; try { mimeMessage = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(raw); @@ -1157,13 +1196,8 @@ async function sendViaCustomDomain( // one EmailMessage per recipient. The response's message id is shared by // the whole list. let failure: { code: string; message: string } | null = null; - let outcomeUnknown = false; - let messageId = ''; - // Per-recipient permanent outcomes from the send_raw result: a recipient - // on either list was NOT sent to, and reporting it as delivered would - // tell the framework (and the log) a lie it cannot retry its way out of. - let bounced = new Set(); - let suppressed = new Set(); + let failureState: 'failed' | 'outcome_unknown' = 'failed'; + let sendRawResult: ParsedSendRawResult | null = null; let cfRes: Response | null = null; try { cfRes = await fetch( @@ -1179,7 +1213,7 @@ async function sendViaCustomDomain( ); } catch { failure = { code: 'UPSTREAM_ERROR', message: 'email sending request failed' }; - outcomeUnknown = true; + failureState = 'outcome_unknown'; } if (cfRes) { if (!cfRes.ok) { @@ -1189,53 +1223,79 @@ async function sendViaCustomDomain( code: cfRes.status === 429 ? 'QUOTA_EXCEEDED' : 'UPSTREAM_ERROR', message: `email sending API returned ${cfRes.status}`, }; - outcomeUnknown = cfRes.status >= 500; + failureState = cfRes.status >= 500 || cfRes.status === 408 ? 'outcome_unknown' : 'failed'; } else { - let data: unknown = null; + let data: unknown; try { data = await cfRes.json(); } catch { - data = null; + failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response unreadable' }; + failureState = 'outcome_unknown'; } - const success = - typeof data === 'object' && - data !== null && - (data as { success?: unknown }).success === true; - if (!success) { - failure = { code: 'UPSTREAM_ERROR', message: 'email sending API refused the message' }; - } else { - const result = (data as { result?: SendRawResult | null }).result; - const id = result?.message_id; - messageId = typeof id === 'string' ? id : ''; - bounced = readSendRawAddressList(result?.permanent_bounces); - suppressed = readSendRawAddressList(result?.suppressed_recipients); + if (!failure) { + const success = + typeof data === 'object' && data !== null + ? (data as { success?: unknown }).success + : undefined; + if (success === false) { + failure = { code: 'UPSTREAM_ERROR', message: 'email sending API refused the message' }; + } else if (success !== true) { + failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response invalid' }; + failureState = 'outcome_unknown'; + } else { + sendRawResult = parseSendRawResult((data as { result?: unknown }).result); + if (!sendRawResult) { + failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response invalid' }; + failureState = 'outcome_unknown'; + } + } } } } for (const r of recipients) { if (failure) { - deliveries.push({ recipient: r, ok: false, error: failure }); - } else if (bounced.has(r)) { + deliveries.push({ recipient: r, ok: false, state: failureState, error: failure }); + continue; + } + const outcome = classifySendRawRecipient(sendRawResult!, r); + if (outcome === 'permanent_bounce') { deliveries.push({ recipient: r, ok: false, + state: 'failed', error: { code: 'UNVERIFIED_DESTINATION', message: `recipient '${r}' permanently bounced`, }, }); - } else if (suppressed.has(r)) { + } else if (outcome === 'suppressed') { deliveries.push({ recipient: r, ok: false, + state: 'failed', error: { code: 'UNVERIFIED_DESTINATION', message: `recipient '${r}' is on the suppression list`, }, }); + } else if (outcome === 'outcome_unknown') { + deliveries.push({ + recipient: r, + ok: false, + state: 'outcome_unknown', + error: { + code: 'OUTCOME_UNKNOWN', + message: 'email sending API did not classify the recipient', + }, + }); } else { - deliveries.push({ recipient: r, ok: true, messageId }); + deliveries.push({ + recipient: r, + ok: true, + state: 'provider_accepted', + messageId: sendRawResult!.messageId, + }); } } @@ -1247,22 +1307,26 @@ async function sendViaCustomDomain( context.env, admission.operationId, [delivery.recipient], - delivery.ok ? 'provider_accepted' : outcomeUnknown ? 'outcome_unknown' : 'failed', + delivery.ok + ? 'provider_accepted' + : delivery.state === 'outcome_unknown' + ? 'outcome_unknown' + : 'failed', { providerReference: delivery.messageId, errorCode: delivery.ok ? undefined - : outcomeUnknown + : delivery.state === 'outcome_unknown' ? 'OUTCOME_UNKNOWN' : (failure?.code ?? delivery.error?.code), }, ); delivery.state = delivery.ok ? 'provider_accepted' - : outcomeUnknown + : delivery.state === 'outcome_unknown' ? 'outcome_unknown' : 'failed'; - if (outcomeUnknown && !delivery.ok) { + if (delivery.state === 'outcome_unknown' && !delivery.ok) { delivery.error = { code: 'OUTCOME_UNKNOWN', message: 'provider outcome unknown; inspect email logs before retrying', @@ -1291,6 +1355,7 @@ async function sendViaCustomDomain( ids: deliveries.map((d) => ({ recipient: d.recipient, messageId: (d as { messageId: string }).messageId, + state: 'provider_accepted' as const, })), }); } @@ -1306,9 +1371,8 @@ async function sendViaCustomDomain( * 404 (and earlier did so silently). */ export async function recordInboundDelivery( - _env: { ROUTING: KVNamespace }, projectId: string, - info: { from: string; to: string; subject: string; byteSize: number; status: string }, + info: { from: string; to: string; byteSize: number; status: string }, ): Promise { console.log( `[email-recv] ${projectId} ${sanitizeForLog(info.from, 320)} -> ${sanitizeForLog(info.to, 320)} ${info.status} (${info.byteSize}B) @${Date.now()}`, @@ -1359,66 +1423,6 @@ function emailActionResponse( ); } -/** - * Map an error thrown by the platform's `send_email` binding to a - * framework-facing error code. Mirrors `classifyBindingError` in - * `void/email` (the framework's own-binding lane): Email Service throws - * `Error`s carrying a `code` (the `E_*` table in Cloudflare's Workers API - * reference), and that code is read FIRST — the message regex below is the - * fallback for the older, message-only Email Routing sender. Anything else - * is UPSTREAM_ERROR, which the framework retries. - * - * The two sender codes are where the lanes deliberately differ. `from` is - * pinned to `[+tag]@` above, so an - * `E_SENDER_NOT_VERIFIED` / `E_SENDER_DOMAIN_NOT_AVAILABLE` here means the - * PLATFORM's mail zone is not onboarded or verified: the tenant's `from` - * passed the pin and nothing about it is theirs to fix. INVALID_FROM is - * documented as "not the project sender" and as pre-flight, so it would be - * false on both counts; the send stays UPSTREAM_ERROR (retryable once the - * platform is repaired) with Cloudflare's message kept, and the code is - * logged because `logSend` records only ours. - * - * UNVERIFIED_DESTINATION is special — the framework treats it as - * "don't retry; the user has to verify the address first." A false - * positive here turns retryable transient errors into permanent - * non-retries, so the match is intentionally narrow. - * - * Anchored to the literal CF phrasing ("destination address … not - * (yet) verified"), bounded character classes to keep `.*` from - * jumping across log lines / multi-error stack traces, and a leading - * `^[^\n]{0,200}` cap so a long preamble can't drag a tail-of-line - * "destination address foo not verified" into a false positive on a - * transient upstream error message that happens to mention the same - * domain or address. - */ -const UNVERIFIED_DESTINATION_RE = - /^[^\n]{0,200}destination address[^\n]{0,200}not (?:yet )?verified/i; - -function classifyUpstream(e: unknown, projectId: string): string { - const message = e instanceof Error ? e.message : String(e); - const code = - typeof (e as { code?: unknown })?.code === 'string' ? (e as { code: string }).code : ''; - switch (code) { - case 'E_RECIPIENT_NOT_ALLOWED': - return 'UNVERIFIED_DESTINATION'; - case 'E_RATE_LIMIT_EXCEEDED': - case 'E_DAILY_LIMIT_EXCEEDED': - return 'QUOTA_EXCEEDED'; - case 'E_SENDER_NOT_VERIFIED': - case 'E_SENDER_DOMAIN_NOT_AVAILABLE': - console.error( - `[email-send] project ${projectId} send binding refused the platform sender (${code}): ${sanitizeForLog(message)}`, - ); - return 'UPSTREAM_ERROR'; - default: - break; - } - if (UNVERIFIED_DESTINATION_RE.test(message)) { - return 'UNVERIFIED_DESTINATION'; - } - return 'UPSTREAM_ERROR'; -} - function logSend(projectId: string, requestId: string, deliveries: Array): void { for (const d of deliveries) { const status = d.ok ? 'sent' : (d.error?.code ?? 'unknown_error'); diff --git a/platform/packages/proxy/test/unit/email-custom-domain.test.ts b/platform/packages/proxy/test/unit/email-custom-domain.test.ts index 9fae1c37e..3703b08b9 100644 --- a/platform/packages/proxy/test/unit/email-custom-domain.test.ts +++ b/platform/packages/proxy/test/unit/email-custom-domain.test.ts @@ -1,20 +1,4 @@ -/** - * Tests for the custom sender domain fork of POST /email/send (design doc - * 0078, "Custom domains on Cloudflare"). - * - * A `from` whose domain is NOT `EMAIL_SENDER_DOMAIN` belongs to a - * registered `email_domains` row. The proxy reads the `email-domain:` - * KV mirror (its only view of the row), leases a credential from the api - * (`email-lease.ts`, contract 4), and delivers through the CUSTOMER's - * account via Email Sending's `send_raw` — never through the platform's - * `send_email` binding. Platform quota, kill-switch and suspension gates - * run unchanged and BEFORE the external call. - * - * Harness mirrors `email.test.ts`: the real worker entry, an in-memory KV - * mock, `env.API.fetch` as the lease endpoint, and a stubbed global - * `fetch` as `api.cloudflare.com`. The leased credential below is a dummy - * fixture string, never a real token. - */ +/** Custom-domain sends use SQL admission and a customer-account send_raw credential. */ import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; @@ -65,23 +49,7 @@ async function signHmac(data: string, secret: string): Promise { // --- Mocks --- -type MockKv = ReturnType; - -function createMockKv(data: Record = {}) { - const store = new Map(Object.entries(data)); - return { - store, - get: vi.fn(async (key: string, _options?: unknown) => store.get(key) ?? null), - put: vi.fn(async (key: string, value: string, _options?: unknown) => { - store.set(key, value); - }), - delete: vi.fn(async (key: string) => { - store.delete(key); - }), - }; -} - -function createMockEnv(kv: MockKv) { +function createMockEnv() { const actions = new Map< string, { @@ -154,7 +122,7 @@ function createMockEnv(kv: MockKv) { const env = { AI: {}, JWT_SECRET, - ROUTING: kv, + ROUTING: { get: vi.fn(async () => null) }, CF_ACCOUNT_ID: 'acct', CF_API_TOKEN: 'cf-token', API: { fetch: apiFetch }, @@ -166,29 +134,6 @@ function createMockEnv(kv: MockKv) { return { env, apiFetch, sendEmail }; } -/** The mirror the api writes to ROUTING KV; sha field is a placeholder hex string. */ -function domainMirror(overrides: Record = {}) { - return JSON.stringify({ - projectId: 'proj_1', - status: 'active', - relaySecretSha256: '00'.repeat(32), - relayWorkerName: 'void-email-relay', - accountId: 'acct_customer', - zoneId: 'zone_1', - mode: 'subdomain', - ...overrides, - }); -} - -/** KV contents that let `proj_1` send from `support@acme.com`. */ -function customDomainKv(extra: Record = {}) { - return createMockKv({ - 'email-slug:proj_1': 'acme', - [`email-domain:${CUSTOM_DOMAIN}`]: domainMirror(), - ...extra, - }); -} - function base64Of(bytes: Uint8Array): string { let binary = ''; for (const b of bytes) { @@ -259,12 +204,7 @@ function stubCloudflare(handler?: (call: { url: string; init: RequestInit }) => return calls; } -function kvKeysMatching(kv: MockKv, prefix: string): Array { - return [...kv.store.keys()].filter((k) => k.startsWith(prefix)); -} - beforeEach(() => { - // The lease cache is module-level — isolate every test from its neighbours. vi.spyOn(console, 'error').mockImplementation(() => {}); vi.spyOn(console, 'warn').mockImplementation(() => {}); vi.spyOn(console, 'log').mockImplementation(() => {}); @@ -278,14 +218,13 @@ afterEach(() => { describe('POST /email/send — custom sender domain', () => { it('leases a credential and delivers through the customer account via send_raw', async () => { - const kv = customDomainKv(); - const { env, apiFetch, sendEmail } = createMockEnv(kv); + const { env, apiFetch, sendEmail } = createMockEnv(); const calls = stubCloudflare(); const res = await postSend(env, await sendBody()); expect(res.status).toBe(200); expect(await res.json()).toEqual({ ok: true, - ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_1' }], + ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_1', state: 'provider_accepted' }], operationId: 'act_1', }); @@ -323,14 +262,109 @@ describe('POST /email/send — custom sender domain', () => { // The platform binding is never touched on this path. expect(sendEmail).not.toHaveBeenCalled(); + }); - expect(kvKeysMatching(kv, 'email-sent:proj_1:')).toHaveLength(0); - expect(kvKeysMatching(kv, 'email-burst:proj_1:')).toHaveLength(0); + it('does not require the platform send binding for a custom-domain send', async () => { + const { env } = createMockEnv(); + delete (env as { SEND_EMAIL?: unknown }).SEND_EMAIL; + stubCloudflare(); + const response = await postSend(env, await sendBody()); + expect(await response.json()).toMatchObject({ + ok: true, + ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_1', state: 'provider_accepted' }], + }); + }); + + it.each([ + { response: new Response(null, { status: 500 }), state: 'outcome_unknown' }, + { response: new Response('{', { status: 200 }), state: 'outcome_unknown' }, + { response: Response.json({ success: true, result: {} }), state: 'outcome_unknown' }, + { response: Response.json({ success: false }), state: 'failed' }, + ])( + 'records a send_raw response as $state when provider submission may be ambiguous', + async ({ response, state }) => { + const { env, apiFetch } = createMockEnv(); + const calls = stubCloudflare(() => response); + const result = await postSend(env, await sendBody()); + const body = await result.json(); + expect(body).toMatchObject({ + ok: false, + operationId: 'act_1', + deliveries: [{ recipient: 'dev@example.com', ok: false, state }], + }); + expect(calls).toHaveLength(1); + const finishCall = apiFetch.mock.calls.find(([url]) => String(url).endsWith('/finish'))!; + expect(JSON.parse(String(finishCall[1].body)).state).toBe(state); + }, + ); + + it.each([ + { + name: 'omitted', + result: { + message_id: 'cf_msg_missing', + delivered: [], + permanent_bounces: [], + queued: [], + suppressed_recipients: [], + }, + }, + { + name: 'overlapping', + result: { + message_id: 'cf_msg_overlap', + delivered: ['dev@example.com'], + permanent_bounces: ['dev@example.com'], + queued: [], + suppressed_recipients: [], + }, + }, + ])('keeps a recipient with an $name provider classification unresolved', async ({ result }) => { + const { env, apiFetch } = createMockEnv(); + stubCloudflare(() => Response.json({ success: true, result })); + const response = await postSend(env, await sendBody()); + expect(await response.json()).toMatchObject({ + ok: false, + operationId: 'act_1', + deliveries: [ + { + recipient: 'dev@example.com', + ok: false, + state: 'outcome_unknown', + error: { code: 'OUTCOME_UNKNOWN' }, + }, + ], + }); + const finishCall = apiFetch.mock.calls.find(([url]) => String(url).endsWith('/finish'))!; + expect(JSON.parse(String(finishCall[1].body))).toMatchObject({ + recipients: ['dev@example.com'], + state: 'outcome_unknown', + }); + }); + + it('accepts a recipient explicitly classified as queued', async () => { + const { env } = createMockEnv(); + stubCloudflare(() => + Response.json({ + success: true, + result: { + message_id: 'cf_msg_q', + delivered: [], + permanent_bounces: [], + queued: ['dev@example.com'], + suppressed_recipients: [], + }, + }), + ); + expect(await (await postSend(env, await sendBody())).json()).toEqual({ + ok: true, + ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_q', state: 'provider_accepted' }], + operationId: 'act_1', + }); }); it('re-leases the domain for each send', async () => { - const kv = customDomainKv(); - const { env, apiFetch } = createMockEnv(kv); + const { env, apiFetch } = createMockEnv(); stubCloudflare(); await postSend(env, await sendBody()); await postSend(env, await sendBody({ requestId: 'req_2' })); @@ -340,7 +374,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('replays a completed operation without consulting a later revoked credential', async () => { - const { env, apiFetch } = createMockEnv(customDomainKv()); + const { env, apiFetch } = createMockEnv(); const calls = stubCloudflare(); const body = await sendBody({ idempotencyKey: 'same-operation' }); expect((await (await postSend(env, body)).json()).ok).toBe(true); @@ -356,8 +390,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('re-leases after a definitive 401 from send_raw', async () => { - const kv = customDomainKv(); - const { env, apiFetch } = createMockEnv(kv); + const { env, apiFetch } = createMockEnv(); let sendCount = 0; stubCloudflare(() => { sendCount += 1; @@ -394,12 +427,12 @@ describe('POST /email/send — custom sender domain', () => { }, ], }); - // The refusal evicted the lease — the next send re-leases and succeeds. + // A distinct request leases again and can succeed after the refusal. const second = await postSend(env, await sendBody({ requestId: 'req_2' })); expect(second.status).toBe(200); expect(await second.json()).toEqual({ ok: true, - ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_2' }], + ids: [{ recipient: 'dev@example.com', messageId: 'cf_msg_2', state: 'provider_accepted' }], operationId: 'act_2', }); expect( @@ -408,8 +441,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('maps a 429 from send_raw to QUOTA_EXCEEDED', async () => { - const kv = customDomainKv(); - const { env } = createMockEnv(kv); + const { env } = createMockEnv(); stubCloudflare(() => new Response('slow down', { status: 429 })); const res = await postSend(env, await sendBody()); expect(res.status).toBe(200); @@ -419,8 +451,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('marks a network failure on send_raw as an unknown outcome', async () => { - const kv = customDomainKv(); - const { env } = createMockEnv(kv); + const { env } = createMockEnv(); vi.stubGlobal( 'fetch', vi.fn(async () => { @@ -437,25 +468,8 @@ describe('POST /email/send — custom sender domain', () => { }); }); - it('sends with a stale KV domain mirror when PostgreSQL lease and admission agree', async () => { - const kv = customDomainKv({ - [`email-domain:${CUSTOM_DOMAIN}`]: domainMirror({ - projectId: 'p_other', - status: 'pending', - accountId: null, - }), - }); - const { env } = createMockEnv(kv); - const calls = stubCloudflare(); - const res = await postSend(env, await sendBody()); - expect(res.status).toBe(200); - expect((await res.json()).ok).toBe(true); - expect(calls).toHaveLength(1); - }); - it('answers 502 when the lease fails, without burning quota or calling send_raw', async () => { - const kv = customDomainKv(); - const { env, apiFetch } = createMockEnv(kv); + const { env, apiFetch } = createMockEnv(); const normalFetch = apiFetch.getMockImplementation()!; apiFetch.mockImplementation(async (url, init) => String(url).endsWith('/domain-credential') @@ -471,13 +485,10 @@ describe('POST /email/send — custom sender domain', () => { message: 'could not lease the domain credential', }); expect(cfFetch).not.toHaveBeenCalled(); - expect(kvKeysMatching(kv, 'email-sent:proj_1:')).toHaveLength(0); - expect(kvKeysMatching(kv, 'email-burst:proj_1:')).toHaveLength(0); }); it('pins the MIME From to the envelope sender on the custom domain too', async () => { - const kv = customDomainKv(); - const { env, apiFetch } = createMockEnv(kv); + const { env, apiFetch } = createMockEnv(); const cfFetch = vi.fn(); vi.stubGlobal('fetch', cfFetch); const res = await postSend( @@ -493,8 +504,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('refuses MIME that is not valid UTF-8 before leasing or burning quota', async () => { - const kv = customDomainKv(); - const { env, apiFetch } = createMockEnv(kv); + const { env, apiFetch } = createMockEnv(); const cfFetch = vi.fn(); vi.stubGlobal('fetch', cfFetch); const prefix = new TextEncoder().encode(`From: ${CUSTOM_FROM}\r\n\r\n`); @@ -509,12 +519,10 @@ describe('POST /email/send — custom sender domain', () => { }); expect(apiFetch).not.toHaveBeenCalled(); expect(cfFetch).not.toHaveBeenCalled(); - expect(kvKeysMatching(kv, 'email-sent:proj_1:')).toHaveLength(0); }); it('reports a permanently bounced recipient as failed, not sent', async () => { - const kv = customDomainKv(); - const { env } = createMockEnv(kv); + const { env } = createMockEnv(); stubCloudflare( () => new Response( @@ -551,8 +559,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('reports a suppressed recipient as failed, not sent', async () => { - const kv = customDomainKv(); - const { env } = createMockEnv(kv); + const { env } = createMockEnv(); stubCloudflare( () => new Response( @@ -589,8 +596,7 @@ describe('POST /email/send — custom sender domain', () => { }); it('splits a mixed batch: delivered recipients keep the id, bounced ones fail', async () => { - const kv = customDomainKv(); - const { env } = createMockEnv(kv); + const { env } = createMockEnv(); stubCloudflare( () => new Response( diff --git a/platform/packages/proxy/test/unit/email-router.test.ts b/platform/packages/proxy/test/unit/email-router.test.ts index e0802ae5f..5b2f647c0 100644 --- a/platform/packages/proxy/test/unit/email-router.test.ts +++ b/platform/packages/proxy/test/unit/email-router.test.ts @@ -61,56 +61,8 @@ const PROD_DOMAIN = 'mail.void.cloud'; function replyRaw(from: string, body = 'reply body'): Uint8Array { return new TextEncoder().encode(`From: ${from}\r\n\r\n${body}\r\n`); } -const STAGING_DOMAIN = 'mail.staging.void.cloud'; - -/** Frozen clock. Drives both quota buckets below. */ +/** Frozen clock for deterministic log timestamps. */ const FIXED_NOW = new Date('2026-04-29T12:34:56.000Z'); -const MONTH_BUCKET = '2026-04'; -const MINUTE_BUCKET = '20260429T1234'; - -const SENT_KEY = `email-sent:p_test:${MONTH_BUCKET}`; -const BURST_KEY = `email-burst:p_test:${MINUTE_BUCKET}`; -const RECV_KEY = `email-recv:p_test:${MONTH_BUCKET}`; - -/** Default routing entry: project p_test, worker user-worker, no limits. */ -const DEFAULT_ROUTING = JSON.stringify({ - workerName: 'user-worker', - projectId: 'p_test', -}); - -// ----------------------------------------------------------------------- -// KV mock — the inbound router only touches `get` + `put`. -// ----------------------------------------------------------------------- - -interface KvWrite { - key: string; - value: string; - options?: { expirationTtl?: number }; -} - -function createMockKv(seed: Record = {}, failGetKeys: Array = []) { - const store = new Map(Object.entries(seed)); - const writes: Array = []; - const failures = new Set(failGetKeys); - const kv = { - store, - writes, - get: vi.fn(async (key: string, _opts?: { cacheTtl?: number }) => { - if (failures.has(key)) { - throw new Error(`KV get failed for ${key}`); - } - return store.get(key) ?? null; - }), - put: vi.fn(async (key: string, value: string, options?: { expirationTtl?: number }) => { - store.set(key, value); - writes.push({ key, value, options }); - }), - delete: vi.fn(async (key: string) => { - store.delete(key); - }), - }; - return kv; -} // ----------------------------------------------------------------------- // Fake ForwardableEmailMessage. Records every method call — and their @@ -239,9 +191,6 @@ function createCtx() { // ----------------------------------------------------------------------- interface MakeEnvOptions { - kvSeed?: Record; - /** KV keys whose `get` throws — used to exercise fail-closed paths. */ - kvGetFailures?: Array; /** When provided, the dispatch stub's `email()` returns this value. */ emailReturn?: unknown; /** When provided, the dispatch stub's `email()` throws this. */ @@ -257,7 +206,6 @@ interface MakeEnvOptions { } function makeEnv(options: MakeEnvOptions = {}) { - const kv = createMockKv(options.kvSeed ?? {}, options.kvGetFailures ?? []); const emailFn = vi.fn(async (_envelope: unknown) => { if (options.emailThrow) { throw options.emailThrow; @@ -331,7 +279,6 @@ function makeEnv(options: MakeEnvOptions = {}) { const env = { AI: {}, JWT_SECRET: 'test-secret', - ROUTING: kv, CF_ACCOUNT_ID: 'acct', CF_API_TOKEN: 'token', API: { fetch: apiFetch }, @@ -339,7 +286,7 @@ function makeEnv(options: MakeEnvOptions = {}) { SEND_EMAIL: { send: vi.fn() }, ...(senderDomain === null ? {} : { EMAIL_SENDER_DOMAIN: senderDomain }), } as unknown as Env; - return { env, kv, emailFn, dispatchGet, apiFetch }; + return { env, emailFn, dispatchGet, apiFetch }; } function apiBodies( @@ -351,18 +298,6 @@ function apiBodies( .map(([, init]) => JSON.parse(String((init as RequestInit).body)) as Record); } -/** Routing + allowlist seed for the happy outbound-gate path. */ -function withAllowlist( - addresses: Array = ['admin@example.com', 'support@example.com'], - extra: Record = {}, -): Record { - return { - myslug: DEFAULT_ROUTING, - 'email-allowlist:p_test': JSON.stringify(addresses), - ...extra, - }; -} - // ----------------------------------------------------------------------- // Console spies + frozen clock. Every test runs under these. // ----------------------------------------------------------------------- @@ -385,6 +320,7 @@ afterEach(() => { errorSpy.mockRestore(); warnSpy.mockRestore(); logSpy.mockRestore(); + vi.unstubAllGlobals(); vi.useRealTimers(); }); @@ -404,7 +340,7 @@ describe('routeInbound — shared-address parsing', () => { }); it('routes a tag-less recipient (whole local-part is the slug)', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); + const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); @@ -416,7 +352,7 @@ describe('routeInbound — shared-address parsing', () => { }); it('uppercase recipients are lowercased before dispatch', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); + const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `MySlug+Tag@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); @@ -476,7 +412,7 @@ describe('routeInbound — authoritative routing', () => { describe('routeInbound — message size guards', () => { it('rejects messages exceeding rawSize > 10MB before streaming', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING } }); + const { env, emailFn } = makeEnv(); const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}`, rawBytes: new Uint8Array(0), @@ -491,7 +427,7 @@ describe('routeInbound — message size guards', () => { }); it('rejects when stream overflow exceeds cap (rawSize lied)', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING } }); + const { env, emailFn } = makeEnv(); // rawSize claims 1KB but the stream actually carries 11MB. const big = new Uint8Array(11 * 1024 * 1024); const { message, rejectCalls } = createFakeMessage({ @@ -507,7 +443,7 @@ describe('routeInbound — message size guards', () => { }); it('accepts a message just under the cap', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); + const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}`, rawBytes: new Uint8Array(10 * 1024 * 1024), @@ -537,7 +473,7 @@ describe('routeInbound — inbound header count cap', () => { } it('rejects a message carrying more distinct headers than the cap, before dispatch', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); + const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); for (const [name, value] of distinctHeaders(MAX_INBOUND_HEADERS + 1)) { message.headers.append(name, value); @@ -552,7 +488,7 @@ describe('routeInbound — inbound header count cap', () => { }); it('dispatches a message with exactly the cap, every header in the envelope', async () => { - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); + const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); for (const [name, value] of distinctHeaders(MAX_INBOUND_HEADERS)) { message.headers.append(name, value); @@ -574,7 +510,7 @@ describe('routeInbound — inbound header count cap', () => { // 128 MB heap. The bag is a workerd-shaped iterable (see // `headerEntries`), so the heap read below is the router's own cost: // the first `MAX_INBOUND_HEADERS + 1` pairs, then the refusal. - const { env, emailFn } = makeEnv({ kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [] }); + const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}`, headerEntries: distinctHeaders(1_500_000), @@ -601,11 +537,10 @@ describe('routeInbound — inbound header count cap', () => { describe('routeInbound — action enaction', () => { it('drops the WHOLE list when a tenant returns more than 100 actions', async () => { // The tenant worker is not trusted to have capped its own queue: on WfP - // it can ship any WorkerEntrypoint whose email() returns any array. The - // list is walked HERE, in the shared proxy isolate, before any quota gate + // it can ship any WorkerEntrypoint whose receipt response contains any array. The + // list is walked here, in the shared proxy isolate, before admission // has charged for it — so the count is checked before the loop. - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), + const { env, apiFetch } = makeEnv({ emailReturn: Array.from({ length: 101 }, () => ({ type: 'forward', to: 'admin@example.com', @@ -620,21 +555,14 @@ describe('routeInbound — action enaction', () => { expect(replyCalls).toHaveLength(0); // Dropping the list is not a bounce — CF still accepted the message. expect(rejectCalls).toHaveLength(0); - // Nothing was charged: the list never reached the gate. - expect(kv.writes.filter((w) => w.key.startsWith('email-sent:'))).toHaveLength(0); - expect(kv.writes.filter((w) => w.key.startsWith('email-burst:'))).toHaveLength(0); + // Nothing was admitted: the list never reached the API. + expect(apiBodies(apiFetch, '/admit')).toEqual([]); expect(errorSpy).toHaveBeenCalled(); }); it('enacts a list of exactly 100 actions', async () => { // The bound is > MAX_ACTIONS, not >=. const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com'], { - // Burst/month caps must clear 100 for this to be about the action - // count rather than the quota. - 'email-burst-limit:p_test': '1000', - 'email-limit:p_test': '1000', - }), emailReturn: Array.from({ length: 100 }, () => ({ type: 'forward', to: 'admin@example.com', @@ -648,7 +576,6 @@ describe('routeInbound — action enaction', () => { it('reject is terminal: forward and reply after a reject do NOT fire', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(), emailReturn: [ { type: 'reject', reason: 'spam' }, { type: 'forward', to: 'admin@example.com' }, @@ -672,7 +599,6 @@ describe('routeInbound — action enaction', () => { it('a reject with no reason gets the default reason', async () => { const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [{ type: 'reject' }], }); const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); @@ -682,9 +608,7 @@ describe('routeInbound — action enaction', () => { }); it('forward followed by reply: both fire in order', async () => { - // Both targets must be in the per-project allowlist (HIGH H1). const { env } = makeEnv({ - kvSeed: withAllowlist(), emailReturn: [ { type: 'forward', to: 'admin@example.com' }, { @@ -711,7 +635,6 @@ describe('routeInbound — action enaction', () => { it('enacts the list in DECLARATION order across mixed action types', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com', 'support@example.com', 'ops@example.com']), emailReturn: [ { type: 'forward', to: 'admin@example.com' }, { @@ -735,7 +658,6 @@ describe('routeInbound — action enaction', () => { it('rejects a whole action list with an invalid forward address', async () => { const { env, apiFetch } = makeEnv({ - kvSeed: withAllowlist(), emailReturn: [ { type: 'forward', to: 'not-an-email' }, { type: 'forward', to: 'has\x00control@example.com' }, @@ -753,7 +675,6 @@ describe('routeInbound — action enaction', () => { it('reply with invalid from/to is dropped with console.error', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(), emailReturn: [ { type: 'reply', @@ -778,7 +699,6 @@ describe('routeInbound — action enaction', () => { it('reject reason with CR/LF/NUL is sanitized', async () => { const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [ { type: 'reject', @@ -799,7 +719,6 @@ describe('routeInbound — action enaction', () => { it('a throwing forward is logged and does not abort the list', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(), emailReturn: [ { type: 'forward', to: 'admin@example.com' }, { @@ -824,7 +743,6 @@ describe('routeInbound — action enaction', () => { it('reply carries the action bytes through EmailMessage, not a decoded string', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(), emailReturn: [ { type: 'reply', @@ -859,7 +777,6 @@ describe('routeInbound — envelope header bag (prototype pollution guard)', () // pre-buffers headers with Object.fromEntries so the framework // sees it as a plain string property, not as a prototype mutation. const { env, emailFn } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [], }); const { message } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); @@ -868,8 +785,7 @@ describe('routeInbound — envelope header bag (prototype pollution guard)', () const { ctx } = createCtx(); await routeInbound(message, env, ctx); // Pull the envelope passed into emailFn; assert the header bag is an - // ORDINARY object (workerd RPC refuses to serialize a null-prototype - // one) and that the __proto__ key is a real own property (not a + // ordinary object and that the __proto__ key is a real own property (not a // prototype mutation that affects {}). const envelope = emailFn.mock.calls[0]?.[0] as { headers: Record }; expect(Object.getPrototypeOf(envelope.headers)).toBe(Object.prototype); @@ -880,9 +796,8 @@ describe('routeInbound — envelope header bag (prototype pollution guard)', () expect(({} as Record)['evil']).toBeUndefined(); }); - it('serializes the envelope with RPC-safe primitives only', async () => { + it('passes a bounded envelope with the original MIME bytes', async () => { const { env, emailFn } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [], }); const body = new TextEncoder().encode('Subject: hi\r\n\r\nbody\r\n'); @@ -919,7 +834,6 @@ describe('routeInbound — envelope header bag (prototype pollution guard)', () describe('routeInbound — log-recv via ctx.waitUntil', () => { it('schedules log-recv after a successful dispatch', async () => { const { env } = makeEnv({ - kvSeed: { myslug: DEFAULT_ROUTING }, emailReturn: [], }); const { message } = createFakeMessage({ @@ -935,7 +849,6 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { // Invalid action data must not prevent inbound delivery from being logged. it('logs the inbound delivery even when the action list carries a non-object entry', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), emailReturn: [null, { type: 'forward', to: 'admin@example.com' }], }); const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); @@ -952,7 +865,7 @@ describe('routeInbound — log-recv via ctx.waitUntil', () => { describe('routeInbound — authoritative native custom domain', () => { it('dispatches the full custom recipient without KV and enacts native forward and reply', async () => { const from = 'support@custom.example.com'; - const { env, kv, emailFn, dispatchGet, apiFetch } = makeEnv({ + const { env, emailFn, dispatchGet, apiFetch } = makeEnv({ emailReturn: [ { type: 'forward', to: 'admin@example.com' }, { type: 'reply', from, to: 'sender@example.com', raw: replyRaw(from) }, @@ -977,7 +890,6 @@ describe('routeInbound — authoritative native custom domain', () => { viaDomain: 'custom.example.com', }), ); - expect(kv.get).not.toHaveBeenCalled(); expect(forwardCalls).toHaveLength(1); expect(replyCalls).toHaveLength(1); expect(rejectCalls).toHaveLength(0); @@ -1044,6 +956,125 @@ describe('routeRelayed — unsupported forward', () => { }); }); +describe('routeRelayed — reply attempt outcomes', () => { + const from = 'support@custom.example.com'; + const to = 'sender@example.com'; + + async function runReply( + response: Response, + options: { raw?: Uint8Array; leaseUnavailable?: boolean } = {}, + ) { + const { env, apiFetch } = makeEnv({ + emailReturn: [{ type: 'reply', from, to, raw: options.raw ?? replyRaw(from) }], + }); + const normalFetch = apiFetch.getMockImplementation()!; + apiFetch.mockImplementation(async (url, init) => + String(url).endsWith('/domain-credential') + ? options.leaseUnavailable + ? new Response(null, { status: 503 }) + : Response.json({ kind: 'api_token', token: 'test-lease', accountId: 'customer-account' }) + : normalFetch(url, init), + ); + const providerFetch = vi.fn(async () => response); + vi.stubGlobal('fetch', providerFetch); + const { ctx } = createCtx(); + const outcome = await routeRelayed(env, ctx, { + projectId: 'p_test', + domain: 'custom.example.com', + receiptId: 'receipt_1', + envelope: { + from: to, + to: from, + headers: {}, + raw: replyRaw(to), + rawSize: replyRaw(to).byteLength, + }, + authoritative: { + projectId: 'p_test', + workerName: 'user-worker', + deploymentId: 'v1', + slug: 'myslug', + addressing: 'custom', + domain: 'custom.example.com', + }, + }); + return { outcome, apiFetch, providerFetch }; + } + + it.each([ + [new Response(null, { status: 500 }), 'outcome_unknown'], + [new Response('{', { status: 200 }), 'outcome_unknown'], + [Response.json({ success: true, result: {} }), 'outcome_unknown'], + [ + Response.json({ + success: true, + result: { + message_id: 'cf_reply_missing', + delivered: [], + permanent_bounces: [], + queued: [], + suppressed_recipients: [], + }, + }), + 'outcome_unknown', + ], + [ + Response.json({ + success: true, + result: { + message_id: 'cf_reply_overlap', + delivered: [to], + permanent_bounces: [to], + queued: [], + suppressed_recipients: [], + }, + }), + 'outcome_unknown', + ], + [Response.json({ success: false }), 'failed'], + ])( + 'records ambiguous provider responses without marking them failed', + async (response, state) => { + const { outcome, apiFetch, providerFetch } = await runReply(response); + expect(outcome.reject).toBe(false); + expect(providerFetch).toHaveBeenCalledOnce(); + expect(apiBodies(apiFetch, '/start')).toHaveLength(1); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe(state); + }, + ); + + it.each(['delivered', 'queued'] as const)( + 'records a reply explicitly classified as %s as provider accepted', + async (classification) => { + const { outcome, apiFetch, providerFetch } = await runReply( + Response.json({ + success: true, + result: { + message_id: 'cf_reply_accepted', + delivered: classification === 'delivered' ? [to] : [], + permanent_bounces: [], + queued: classification === 'queued' ? [to] : [], + suppressed_recipients: [], + }, + }), + ); + expect(outcome.reject).toBe(false); + expect(providerFetch).toHaveBeenCalledOnce(); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('provider_accepted'); + }, + ); + + it.each([{ leaseUnavailable: true }, { raw: new Uint8Array([...replyRaw(from), 0xff]) }])( + 'cancels a reply that could not be submitted', + async (options) => { + const { apiFetch, providerFetch } = await runReply(Response.json({ success: true }), options); + expect(apiBodies(apiFetch, '/start')).toEqual([]); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('cancelled'); + expect(providerFetch).not.toHaveBeenCalled(); + }, + ); +}); + describe('routeInbound — reply size limits', () => { const MIB = 1024 * 1024; const SENDER = `myslug+support@${PROD_DOMAIN}`; @@ -1065,8 +1096,7 @@ describe('routeInbound — reply size limits', () => { // No `From:` header at all: if the size check ran AFTER the scan, the // drop would be logged as a missing From header instead. const raw = new Uint8Array(5 * MIB + 1).fill(0x41); - const { env, kv } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), + const { env } = makeEnv({ emailReturn: [replyAction(raw)], }); const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); @@ -1077,12 +1107,10 @@ describe('routeInbound — reply size limits', () => { expect.stringContaining(`reply dropped: raw is ${5 * MIB + 1} bytes (max ${5 * MIB})`), ); expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining('no From header')); - expect(kv.store.get(SENT_KEY)).toBeUndefined(); }); it('accepts a reply of exactly 5 MiB', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), emailReturn: [replyAction(sizedReply(5 * MIB))], }); const { message, replyCalls } = createFakeMessage({ to: `myslug+tag@${PROD_DOMAIN}` }); @@ -1094,7 +1122,6 @@ describe('routeInbound — reply size limits', () => { it('rejects a whole list that exceeds the 8 MiB cumulative reply budget', async () => { const { env } = makeEnv({ - kvSeed: withAllowlist(['admin@example.com']), emailReturn: [ replyAction(sizedReply(3 * MIB)), replyAction(sizedReply(3 * MIB)), From 7e7a7d965a17ed7b6ed7541400ed86b475fec33e Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sat, 19 Sep 2026 15:28:14 +0800 Subject: [PATCH 4/6] fix(email): close review gaps in delivery and durable recovery --- docs/guide/email.md | 6 +- docs/guide/platform-administration.md | 42 +- docs/guide/self-hosted-platform.md | 14 +- docs/reference/cli.md | 29 +- packages/platform/src/email-protocol.ts | 42 +- packages/platform/src/manifest.ts | 5 + packages/platform/src/worker-config.ts | 1 + .../platform/test/unit/email-protocol.test.ts | 12 + .../platform/test/unit/worker-config.test.ts | 42 +- packages/void/skills/void/SKILL.md | 4 +- packages/void/src/cli/client.ts | 2 +- packages/void/src/cli/email-args.ts | 2 +- packages/void/src/cli/email.ts | 8 +- packages/void/src/cli/help.ts | 10 +- packages/void/src/cli/operator-args.ts | 44 +- packages/void/src/cli/operator-cmd.ts | 64 +- packages/void/src/cli/platform-args.ts | 3 +- packages/void/src/cli/platform-installer.ts | 112 +- packages/void/src/cli/platform-lifecycle.ts | 3 + packages/void/src/cli/platform-management.ts | 18 +- packages/void/src/cli/platform-plan.ts | 66 +- packages/void/src/router/compile.ts | 15 +- packages/void/src/runtime/email-protocol.ts | 112 + packages/void/src/runtime/email.ts | 281 ++- packages/void/src/runtime/email/inbound.ts | 258 ++- packages/void/src/runtime/email/mime.ts | 59 +- packages/void/test/unit/email-inbound.test.ts | 148 +- packages/void/test/unit/email-mime.test.ts | 22 +- .../void/test/unit/email-own-account.test.ts | 25 +- .../void/test/unit/email-protocol.test.ts | 113 + packages/void/test/unit/email-send.test.ts | 222 +- packages/void/test/unit/operator-cli.test.ts | 167 +- .../void/test/unit/platform-installer.test.ts | 203 +- .../unit/platform-management-upgrade.test.ts | 23 + .../test/unit/platform-management.test.ts | 15 +- packages/void/test/unit/platform-plan.test.ts | 61 + .../meta/design-docs/0078-email-cf-native.md | 29 + platform/meta/operations.md | 35 +- platform/packages/api/README.md | 35 +- .../api/drizzle/0047_email_gateway.sql | 42 +- .../api/drizzle/meta/0047_snapshot.json | 69 +- .../packages/api/src/admin/routes/email.tsx | 279 +-- .../api/src/email/admission-schema.ts | 5 + platform/packages/api/src/email/admission.ts | 436 ++-- .../packages/api/src/email/cf-customer.ts | 18 - .../api/src/email/connection-schema.ts | 62 +- .../api/src/email/connection-service.ts | 2056 +++++++++++++++-- .../packages/api/src/email/domain-service.ts | 56 +- .../api/src/email/ingress-resolution.ts | 2 + .../packages/api/src/email/relay-worker.ts | 51 +- platform/packages/api/src/index.ts | 77 +- .../api/src/middleware/platform-access.ts | 6 + platform/packages/api/src/operator/audit.ts | 37 +- .../packages/api/src/operator/email-routes.ts | 208 +- .../packages/api/src/provisioning/cleanup.ts | 34 +- .../api/src/routes/internal-email-actions.ts | 75 +- .../api/test/integration/admin-email.test.ts | 180 +- .../integration/api-email-domains.test.ts | 36 + .../api/test/integration/api-email.test.ts | 25 +- .../test/integration/email-admission.test.ts | 711 +++++- .../integration/email-connections.test.ts | 1747 +++++++++++++- .../test/integration/email-domain-cf-stub.ts | 15 +- .../test/integration/operator-audit.test.ts | 3 + .../operator-email-domains.test.ts | 506 +++- .../test/integration/operator-email.test.ts | 124 +- .../platform-access-protection.test.ts | 79 + .../platform-email-bootstrap.test.ts | 191 ++ .../test/unit/email-actions-request.test.ts | 31 + .../api/test/unit/email-cf-customer.test.ts | 23 - .../api/test/unit/email-relay-worker.test.ts | 41 +- platform/packages/email-gateway/src/index.ts | 195 +- .../email-gateway/src/tenant-dispatch.ts | 52 +- .../email-gateway/test/unit/gateway.test.ts | 160 +- .../test/unit/tenant-dispatch.test.ts | 45 + platform/packages/proxy/README.md | 100 +- .../packages/proxy/src/email-admission.ts | 292 ++- platform/packages/proxy/src/email-lease.ts | 96 +- .../proxy/src/email-provider-deadline.ts | 44 + .../packages/proxy/src/email-request-body.ts | 70 + platform/packages/proxy/src/email-router.ts | 206 +- platform/packages/proxy/src/email.ts | 287 ++- platform/packages/proxy/src/index.ts | 46 +- .../test/unit/email-admission-send.test.ts | 63 +- .../proxy/test/unit/email-admission.test.ts | 137 +- .../test/unit/email-custom-domain.test.ts | 184 +- .../proxy/test/unit/email-router.test.ts | 255 +- .../packages/proxy/test/unit/email.test.ts | 155 +- .../packages/proxy/test/unit/proxy.test.ts | 133 ++ 88 files changed, 10544 insertions(+), 1553 deletions(-) create mode 100644 packages/void/test/unit/email-protocol.test.ts create mode 100644 platform/packages/api/test/integration/platform-email-bootstrap.test.ts create mode 100644 platform/packages/api/test/unit/email-actions-request.test.ts create mode 100644 platform/packages/email-gateway/test/unit/tenant-dispatch.test.ts create mode 100644 platform/packages/proxy/src/email-provider-deadline.ts create mode 100644 platform/packages/proxy/src/email-request-body.ts diff --git a/docs/guide/email.md b/docs/guide/email.md index f60ae7ee1..a3aa38084 100644 --- a/docs/guide/email.md +++ b/docs/guide/email.md @@ -172,6 +172,8 @@ await sendEmail({ `ok: false` carries either a top-level `error` or a complete per-recipient `deliveries` list. Platform results include an `operationId` when available, and per-recipient `state` distinguishes rejection, reservation, submission, provider acceptance, failure, cancellation, and an unknown outcome. +Provider submissions have a 30-second wait limit and share a 60-second budget per batch. A submission that times out returns `OUTCOME_UNKNOWN`; the provider may still accept it later. + Use an idempotency key for sends you may retry: ```ts @@ -203,9 +205,9 @@ For 30 days, repeating a key with the same payload returns its recorded outcome | `OUTCOME_UNKNOWN` | The send may have reached the provider; do not blindly resend. | | `UPSTREAM_ERROR` | The provider or platform refused the request. | -The default platform allowance is 200 recipient submissions per UTC calendar month and 10 in a rolling 60-second window. Reserved submissions count toward the limits. Once an attempt starts, it stays charged even if the provider fails or the outcome is unknown. Administrators can change these limits. +The default platform allowance is 200 recipient submissions per UTC calendar month and 10 in a rolling 60-second window. Reserved submissions count toward the limits. Hourly cleanup cancels reservations older than 15 minutes that never started and releases their quota. Once an attempt starts, it stays charged even if the provider fails or the outcome is unknown. Administrators can change these limits. -`void email usage` shows the current allowance. `void email logs --limit 50` shows up to 100 recent metadata entries retained for 30 days: operation, recipient, direction, state, provider reference, and error code. It does not store subjects, bodies, or attachments. Receiving a message and sending a reply are separate events. +`void email usage` shows monthly recipient attempts, inbound receipts, and the remaining allowance. `void email logs --limit 50` shows up to 100 recent metadata entries retained for 30 days: operation, recipient, direction, state, provider reference, and error code. It does not store subjects, bodies, or attachments. Receiving a message and sending a reply are separate events. ## Local development diff --git a/docs/guide/platform-administration.md b/docs/guide/platform-administration.md index 3c102c197..fdbc3aba5 100644 --- a/docs/guide/platform-administration.md +++ b/docs/guide/platform-administration.md @@ -252,6 +252,16 @@ attempt remains charged and is never retried. If its 30-day delivery record has expired, only its recipient-free fence is removed. Do not resolve an attempt while its original execution may still be active. +Inspect a project's retained receipt and recipient outcomes with: + +```sh +void platform email logs hr-portal --page 1 --limit 50 --json +``` + +Logs include operation IDs, recorded outcomes, provider references, and error codes. +After project deletion, use its project ID until the 30-day metadata retention +period expires. Message bodies, subjects, attachments, and credentials are not logged. + ### Registering email domains for projects Your users may hold no Cloudflare account. Tell the platform that administrators register email domains, so `void email domain add` prints the command to ask you for instead of opening a token-creation page: @@ -265,10 +275,11 @@ Then register a domain for a project. The zone must be in the platform's Cloudfl ```sh void platform email domain-add mail.example.com --project hr-portal void platform email domain-status mail.example.com +void platform email domain-rotate-secret mail.example.com void platform email domains ``` -Name the exact mail domain: a subdomain such as `mail.example.com` when the apex already receives mail, otherwise the apex itself. `domain-status` reports inbound, outbound, and management readiness separately. Follow any required DNS or Cloudflare dashboard step, then use `domain-sync` to reconcile. Email Sending onboarding needs Workers Paid; after upgrading, `domain-sync` re-attempts it. For a zone in another Cloudflare account, pipe an API token for that account on standard input: +Name the exact mail domain: a subdomain such as `mail.example.com` when the apex already receives mail, otherwise the apex itself. `domain-status` reports inbound, outbound, and management readiness separately. Follow any required DNS or Cloudflare dashboard step, then use `domain-sync` to reconcile. Use `domain-rotate-secret` when you need to replace the zone ingress credential explicitly. Email Sending onboarding needs Workers Paid; after upgrading, `domain-sync` re-attempts it. For a zone in another Cloudflare account, pipe an API token for that account on standard input: ```sh void platform email domain-add mail.other.example --project hr-portal --token-stdin --yes < token.txt @@ -276,6 +287,35 @@ void platform email domain-add mail.other.example --project hr-portal --token-st Project owners see administrator-registered domains in `void email domain list` and `status`; `status` names the `void platform email` command for any step they cannot take themselves, and `sync` and `remove` point them at `domain-sync` and `domain-remove`. A domain an owner registered before you switched to `admin` stays theirs to renew, sync and remove. The runtime token needs the email permissions listed in the [self-hosting guide](./self-hosted-platform.md#runtime-token-permissions) for this to work. +A permission refusal leaves setup blocked. After correcting it, run `domain-sync` +to resume that same setup operation; repeat `domain-rotate-secret` to resume a +blocked rotation without replacing its staged secret. If project deletion leaves +a blocked domain cleanup, correct the permission and run `domain-remove ` +to finish the retained cleanup. If its token has expired or been revoked, provide +a replacement scoped to the same account and zone: + +```sh +void platform email domain-remove mail.other.example --token-stdin --yes < token.txt +``` + +This recovery is available only after project deletion has begun and no other +project uses the connection. For a live project, renew its token through +`domain-add`. A timed-out Cloudflare +mutation stays stopped because replay may duplicate a provider write. After +confirming the original execution ended, wait 24 hours, inspect the exact +routing, Worker, secret, catch-all, or Sending resource named by the preview, +and use its recovery fence: + +```sh +void platform email operation-resolve --ended --outcome --reason "Provider state verified" --plan +void platform email operation-resolve --ended --outcome --reason "Provider state verified" +``` + +Run recovery with the same platform version that created the persisted intent. +`applied` continues without replaying the write; `not-applied` permits that exact +step to retry. Secret rotation keeps its staged generation, and removal resumes +from the unresolved cleanup step. Age alone never authorizes a retry. + Register administrator domains only after a platform upgrade has completed, and remove them before rolling the platform back to a version that predates this feature: an earlier runtime cannot use the platform credential for them and does not distinguish administrator-registered domains from owner-registered ones. ## Previewing Changes diff --git a/docs/guide/self-hosted-platform.md b/docs/guide/self-hosted-platform.md index 7d666b89e..15ff966b8 100644 --- a/docs/guide/self-hosted-platform.md +++ b/docs/guide/self-hosted-platform.md @@ -10,7 +10,7 @@ If you're deploying an app for yourself, [deploy directly to Cloudflare](../inte The core platform supports GitHub, Google, generic OIDC, and Cloudflare Access login, CLI deploys, D1, KV, R2, Queues, cron jobs, Workers AI, WebSockets, SSE, ISR, routing, logs, and rollback. -The user dashboard, GitHub builds and webhooks, build Containers, email, custom project domains, and sandbox orchestration aren't part of the core installation. Source-built platforms that add the optional GitHub services should follow the [isolated webhook ingress setup](./platform-development.md#optional-github-webhook-ingress-for-access-protected-apis) when Access protects the API. +The core installation includes an email gateway; email is enabled when you configure a shared mail domain and zone. The user dashboard, GitHub builds and webhooks, build Containers, custom project domains, and sandbox orchestration aren't part of the core installation. Source-built platforms that add the optional GitHub services should follow the [isolated webhook ingress setup](./platform-development.md#optional-github-webhook-ingress-for-access-protected-apis) when Access protects the API. ## Before You Start {#prerequisites} @@ -134,9 +134,11 @@ Use the following permissions for the core platform. Cloudflare may label write The management token also needs **Zone Edit** with authority to create zones if you ask Void to create the zone. If it already exists, use the selected zone with Zone Read and DNS Edit. Nested application domains additionally need **SSL and Certificates: Read** on the management token. A custom runtime that enables custom project domains needs **SSL and Certificates: Edit** on the runtime token; the core runtime does not enable that feature. -A custom runtime that enables email lets administrators [register email domains for projects](./platform-administration.md#registering-email-domains-for-projects) on the runtime token. That needs **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail, and **Email Sending: Edit** on the account; the token link preselects them when the runtime enables email. Email Sending onboarding itself needs Workers Paid on the account. +Enabling email lets administrators [register email domains for projects](./platform-administration.md#registering-email-domains-for-projects) on the runtime token. That needs **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail, and **Email Sending: Edit** on the account; the token link preselects them when email is enabled. Email Sending onboarding itself needs Workers Paid on the account. -For an email-enabled runtime, set `VOID_EMAIL_SENDER_DOMAIN` to the shared sender domain and `VOID_EMAIL_SHARED_ZONE_ID` to its Cloudflare zone ID when installing or upgrading. Void records both values for later upgrades and rejects attempts to replace them during an ordinary upgrade. The mail zone can differ from the application zone; without an explicit mail-zone identity, shared inbound delivery stays unavailable. The dedicated email gateway is deployed in the platform account. Each customer zone uses its own ingress Worker to forward mail to that gateway. +To enable email, set `VOID_EMAIL_SENDER_DOMAIN` to the shared sender domain and `VOID_EMAIL_SHARED_ZONE_ID` to its Cloudflare zone ID when installing or upgrading. Void records both values for later upgrades and rejects attempts to replace them during an ordinary upgrade. The mail zone can differ from the application zone, but it must belong to the selected platform Cloudflare account; without an explicit mail-zone identity, shared inbound delivery stays unavailable. The dedicated email gateway is deployed in the platform account. Each customer zone uses its own ingress Worker to forward mail to that gateway. + +The installer prepares the shared mail route and verifies inbound readiness before it opens platform traffic. If that setup fails, the installation remains disabled. Correct the reported Cloudflare permission, mail-zone configuration, or routing conflict, then rerun the same install or upgrade command; a fresh install resumes with `void platform install --resume --name `. Void checks access before provisioning. If it reports a missing permission, update the token's permissions for the selected account or zone and retry. @@ -573,7 +575,7 @@ void platform discover --account --installation Discovery restores local installation records after verifying the resources belong to your platform. It also works for interrupted or disabled installations. If infrastructure is missing, run `void platform repair [id]` after discovery. If ownership cannot be verified, the command stops without changing resources. -After discovery, provide `VOID_PLATFORM_DATABASE_URL` for migrations and to coordinate administrator commands. You don't need to re-enter the other secrets for a normal upgrade. If repair must recreate a missing API or proxy Worker, supply its original runtime token, GitHub, R2, JWT, and project-encryption secrets through the `VOID_PLATFORM_*` variables. Cloudflare can't return those values, so keep them in your organization's secret manager. +After discovery, provide `VOID_PLATFORM_DATABASE_URL` for migrations and to coordinate administrator commands. You don't need to re-enter the other secrets for an upgrade that preserves every deployed Worker. If an upgrade adds the email gateway for the first time, or repair recreates only that Worker, restore `VOID_PLATFORM_JWT_SECRET`; the gateway does not need the Cloudflare runtime token. If repair must recreate the API or proxy Worker, restore `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` and `VOID_PLATFORM_JWT_SECRET`. Recreating the API also requires its original GitHub, R2, and project-encryption secrets through the `VOID_PLATFORM_*` variables. Cloudflare can't return those values, so keep them in your organization's secret manager. If you have not rotated the project-encryption key, restore it with `VOID_PLATFORM_PROJECT_SECRET_KEY`. After rotation, supply `VOID_PLATFORM_PROJECT_SECRET_KEYS_JSON` with all retained keys and `VOID_PLATFORM_PROJECT_SECRET_ACTIVE_KEY_VERSION` with the active key's name. Keep older keys needed to decrypt existing project secrets. These values are used to recreate a missing API Worker; they do not replace the live keys during an ordinary upgrade. Supply them from your secret manager. @@ -627,9 +629,13 @@ Inject the following values from protected CI secrets. Do not commit them in a w | `VOID_PLATFORM_JWT_SECRET` | Original JWT signing secret | | `VOID_PLATFORM_PROJECT_SECRET_KEY` | Original base64-encoded project-encryption key | | `VOID_PLATFORM_RECOVERY_KEY` | Base64-encoded 32-byte key for local encrypted recovery state when no keychain is available | +| `VOID_EMAIL_SENDER_DOMAIN` | Optional shared mail domain; requires `VOID_EMAIL_SHARED_ZONE_ID` | +| `VOID_EMAIL_SHARED_ZONE_ID` | Cloudflare zone ID for that mail domain; requires `VOID_EMAIL_SENDER_DOMAIN` | Use that installation's saved signing and encryption keys on every resume or repair that needs them. After a keyring rotation, use the [complete keyring recovery inputs](#manage-an-installation-from-another-machine). The database claim and tables remain after uninstall; use a fresh database for a different installation. +Set both email values to enable email during install or upgrade. Later upgrades reuse the recorded values. + ```sh void platform install \ --name team \ diff --git a/docs/reference/cli.md b/docs/reference/cli.md index c7d279300..f938fa5dc 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -41,7 +41,7 @@ Use this page as a command reference. If you are setting up a project for the fi | `void build logs` | Stream, tail, or download build logs | | `void email status` | Show email readiness on your own Cloudflare account (`--platform cloudflare`) | | `void email setup` | Set email up on your own Cloudflare account, without deploying | -| `void email usage` | Show monthly email send/receive counts and quota | +| `void email usage` | Show monthly recipient attempts, inbound receipts, and quota | | `void email logs` | Show recent email delivery activity | | `void email destinations` | List verified recipient addresses | | `void email allow
` | Add a recipient and send a verification email | @@ -616,14 +616,18 @@ void platform email policy-set [--domains void platform email limit [--monthly ] [--burst ] +void platform email logs [--page ] [--limit ] [--json] void platform email attempts [--project ] [--page ] [--limit ] void platform email attempt-resolve --ended --reason +void platform email operation-resolve --ended --outcome --reason ``` `policy` decides which recipients a project's `+tag@` sender reaches: `verified` (the default) means only that project's verified destinations; `domains` adds every address on the listed domains; `any` lifts the check. Neither widens delivery to addresses on the platform's own mail domain: those stay verified-destination-only, so no project reaches another project's inbox without its consent. Cloudflare still refuses a destination it has not verified until the platform mail domain is onboarded for Email Sending, so under `domains` or `any` such refusals arrive as per-recipient `UNVERIFIED_DESTINATION` results. Custom-domain sends are not affected. `settings-set --domains admin` tells `void email domain add` to print the administrator's command instead of starting token setup. `limit` overrides the project's monthly and rolling 60-second caps (defaults 200 and 10); a project page in the admin UI shows and clears them. +`logs` inspects retained receipt and recipient outcomes, including operation IDs, provider references, error codes, and policy versions. Pages contain at most 100 records, newest first; use `--json` for all fields. After project deletion, use its project ID to inspect metadata until the 30-day retention period expires. Message content and credentials are never included. + `attempts` lists interrupted provider calls and their earliest resolution time. Once the original Worker execution has ended and the attempt is at least 24 hours old, `attempt-resolve` records `outcome_unknown`, retains its quota charge, and releases @@ -632,6 +636,16 @@ longer active; `--reason` is stored in the operator audit log. Keep recipient addresses and message content out of the reason. The send is never retried. Use `--plan` to preview and `--yes` to apply without a prompt. +`operation-resolve` recovers a Cloudflare routing, Worker, secret, catch-all, or +Sending mutation whose outcome remains unknown. After the original execution +has ended and the operation is at least 24 hours old, inspect the exact resource +named by the preview and attest whether its write was `applied` or `not-applied`. +Applied writes continue at the next step; not-applied writes retry the same +persisted intent. The running platform version must match that intent, so restore +the matching version before recovering an operation created by older code. The +preview pins the step, attempt, connection and route generations, resource +identity, and digest used by the apply request. Time alone never retries a write. + Register and maintain email domains for projects whose owners hold no Cloudflare credential: ```sh @@ -639,10 +653,13 @@ void platform email domains [--project ] void platform email domain-add --project [--token-stdin] void platform email domain-status void platform email domain-sync -void platform email domain-remove +void platform email domain-rotate-secret +void platform email domain-remove [--token-stdin] ``` -`domain-add` uses the platform's Cloudflare credential for zones in its account. For another account, pipe a scoped Cloudflare API token on standard input with `--token-stdin --yes`. Name the exact mail domain (`mail.example.com`, or the apex when it receives no mail yet). `domain-status` shows inbound, outbound, and credential-management readiness with the latest operation. A blocked or uncertain operation exits unsuccessfully and can be inspected by its operation ID; use `domain-sync` to reconcile the connection. Domains an administrator adds show `managed_by: admin`; their owners can list and inspect them but use these commands for `sync` and `remove`. +`domain-add` uses the platform's Cloudflare credential for zones in its account. For another account, pipe a scoped Cloudflare API token on standard input with `--token-stdin --yes`. Name the exact mail domain (`mail.example.com`, or the apex when it receives no mail yet). `domain-status` shows inbound, outbound, and credential-management readiness with the latest operation. A blocked operation resumes through `domain-sync`; a blocked rotation resumes through `domain-rotate-secret`, preserving already confirmed steps and its staged credential. An uncertain operation remains stopped until read-back proves the result or an administrator uses `operation-resolve`. Domains an administrator adds show `managed_by: admin`; their owners can list and inspect them but use these commands for `sync`, `domain-rotate-secret`, and `remove`. + +If project deletion leaves cleanup blocked by an expired or revoked Cloudflare token, use `domain-remove --token-stdin --yes` with a replacement scoped to the same account and zone. This resumes the retained cleanup only when no other project uses the connection. For a live project, renew its token through `domain-add` instead. #### System {#operator-system} @@ -701,6 +718,8 @@ Read-only plans, workers.dev installations with the default API hostname, and su The installed platform needs a separate runtime token to provision resources for apps. The interactive installer prompts for it and the other setup values. For non-interactive installs, inject the variables listed in [Install from CI](../guide/self-hosted-platform.md#install-from-ci). +To enable email during install or upgrade, set both `VOID_EMAIL_SENDER_DOMAIN` and `VOID_EMAIL_SHARED_ZONE_ID`. Void records the pair for later upgrades; supplying only one is an error. + `--plan` prints the actual resource names, selected login methods, login callback, and direct setup links without opening credential pages or saving a draft; Cloudflare browser login still opens if needed. New platform resources use `void--` names without random suffixes. Existing installations keep their recorded names, and unowned name conflicts stop installation without overwriting resources. After you confirm an interactive install, Void opens each missing credential's setup page and shows a short permission/checklist fallback. The runtime-token link preselects all required account permissions, including Workers Tail, Hyperdrive, and AI Gateway when needed; domain installations must also select the indicated zone. Supplied credentials skip browser opening. Setup drafts pin Worker names and the login callback and save partial credentials encrypted locally. Interactive installs list unfinished installations, including interrupted provisioning, or offer a new install. Entering an existing unfinished name asks to resume it; declining returns to name entry. Starting new leaves previous setup, credentials, and resources untouched. Completed platforms are not offered for resumption. `--resume` skips the choice and is required for non-interactive recovery. Use an empty PostgreSQL database dedicated to the installation. You can correct a failed initial connection, but after the database is claimed or Hyperdrive is provisioned, commands reject a different URL. @@ -743,7 +762,7 @@ void platform uninstall [id] [--plan] [--purge-data] [--keep-zone] [--yes] Omit `id` when only one installation is configured, or choose from the interactive picker. Non-interactive commands need an ID when several installations exist. Commands that make changes also require `--yes`; `--plan` only previews changes. -After discovery on another machine, set `VOID_PLATFORM_DATABASE_URL`. Normal upgrades preserve deployed Worker secrets. Restore the original runtime, GitHub, R2, JWT, and project-encryption values only if repair needs to recreate a missing API or proxy Worker. +After discovery on another machine, set `VOID_PLATFORM_DATABASE_URL`. An upgrade that preserves every deployed Worker also preserves its secrets. If an upgrade adds the email gateway for the first time, or repair recreates only that Worker, restore `VOID_PLATFORM_JWT_SECRET`; the gateway does not need the Cloudflare runtime token. If repair recreates the API or proxy Worker, restore `VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN` and `VOID_PLATFORM_JWT_SECRET`. Recreating the API also requires its original GitHub, R2, and project-encryption values. | Command | Behavior | | ----------- | --------------------------------------------------------------------------------------------- | @@ -1454,7 +1473,7 @@ Project resolution for email commands follows the same order as deploy (`--proje void email usage [--project ] ``` -Show the current month's outbound and inbound counts, the monthly outbound limit, and how much of it is left. A suspended project is flagged in the output. +Show the current month's recipient attempts and inbound receipts, the monthly attempt limit, and how much of it is left. Reserved submissions count toward the limit; started attempts remain charged even if delivery fails or its outcome is unknown. A suspended project is flagged in the output. ### `void email logs` diff --git a/packages/platform/src/email-protocol.ts b/packages/platform/src/email-protocol.ts index fd572a26b..5d7b5cd6e 100644 --- a/packages/platform/src/email-protocol.ts +++ b/packages/platform/src/email-protocol.ts @@ -140,10 +140,16 @@ export async function readEmailEnvelope( total = nextTotal; } } catch (error) { - await reader.cancel().catch(() => {}); + // Cancellation is cleanup, not part of the protocol deadline. A hostile + // stream may never settle its underlying cancel algorithm. + void reader.cancel().catch(() => {}); throw error; } finally { - reader.releaseLock(); + try { + reader.releaseLock(); + } catch { + // A non-standard stream may keep a read pending after cancellation. + } } if (total < 4) { throw new Error('truncated email envelope'); @@ -289,6 +295,18 @@ function frame(kind: number, payload: Uint8Array): Uint8Array { return bytes; } +function encodeEmailActionMetadata(action: EmailWireAction): Uint8Array { + return encoder.encode( + JSON.stringify( + action.type === 'reply' ? { type: action.type, from: action.from, to: action.to } : action, + ), + ); +} + +function emailActionWireSizeFromMetadata(action: EmailWireAction, metadata: Uint8Array): number { + return 5 + metadata.byteLength + (action.type === 'reply' ? 5 + action.raw.byteLength : 0); +} + export function encodeEmailActions( actions: ReadonlyArray, ): ReadableStream { @@ -311,13 +329,7 @@ export function encodeEmailActions( return; } const action = actions[index++]; - const metadata = encoder.encode( - JSON.stringify( - action.type === 'reply' - ? { type: action.type, from: action.from, to: action.to } - : action, - ), - ); + const metadata = encodeEmailActionMetadata(action); if (metadata.byteLength > EMAIL_MAX_METADATA_BYTES) { throw new Error('email action metadata too large'); } @@ -327,7 +339,7 @@ export function encodeEmailActions( } pending = frame(2, action.raw); } - total += 5 + metadata.byteLength + (pending?.byteLength ?? 0); + total += emailActionWireSizeFromMetadata(action, metadata); if (total + 5 > EMAIL_MAX_RESPONSE_BYTES) { throw new Error('email actions too large'); } @@ -466,9 +478,15 @@ export async function readEmailActions( } } } catch (error) { - await reader.cancel().catch(() => {}); + // Cancellation is cleanup, not part of the protocol deadline. A hostile + // stream may never settle its underlying cancel algorithm. + void reader.cancel().catch(() => {}); throw error; } finally { - reader.releaseLock(); + try { + reader.releaseLock(); + } catch { + // A non-standard stream may keep a read pending after cancellation. + } } } diff --git a/packages/platform/src/manifest.ts b/packages/platform/src/manifest.ts index 11d9018d6..449d50073 100644 --- a/packages/platform/src/manifest.ts +++ b/packages/platform/src/manifest.ts @@ -202,6 +202,11 @@ export function createApplicationRoutes( export function createPlatformDeploymentManifest( input: PlatformDeploymentManifestInput, ): PlatformDeploymentManifest { + if ((input.emailSharedZoneId === undefined) !== (input.emailSenderDomain === undefined)) { + throw new Error( + 'Shared email configuration requires both emailSenderDomain and emailSharedZoneId.', + ); + } const installationSlug = normalizeInstallationSlug(input.installationSlug); const baseDomain = normalizeApplicationDomain(input.application.baseDomain); const workersDev = input.application.workersDev; diff --git a/packages/platform/src/worker-config.ts b/packages/platform/src/worker-config.ts index 58eacc186..495db41b0 100644 --- a/packages/platform/src/worker-config.ts +++ b/packages/platform/src/worker-config.ts @@ -183,6 +183,7 @@ export function createPlatformWorkerConfigs(input: { kv_namespaces: [{ binding: 'ROUTING', id: resources.routingKv }], services: [{ binding: 'API', service: names.apiWorker }], dispatch_namespaces: dispatchNamespace, + ...(deployment.capabilities.email ? { send_email: [{ name: 'SEND_EMAIL' }] } : {}), vars: { AI_GATEWAY_ID: names.aiGateway, PLATFORM_CAPABILITIES: JSON.stringify(deployment.capabilities), diff --git a/packages/platform/test/unit/email-protocol.test.ts b/packages/platform/test/unit/email-protocol.test.ts index 8ab0065d3..7853cd39d 100644 --- a/packages/platform/test/unit/email-protocol.test.ts +++ b/packages/platform/test/unit/email-protocol.test.ts @@ -166,4 +166,16 @@ describe('bounded email receipt protocol', () => { const envelope = new ReadableStream(); await expect(readEmailEnvelope(envelope, 5)).rejects.toThrow('email envelope timeout'); }); + + it('does not extend protocol deadlines while an uncooperative stream cancels', async () => { + const uncooperative = () => + new ReadableStream({ + cancel() { + return new Promise(() => {}); + }, + }); + + await expect(readEmailActions(uncooperative(), 5)).rejects.toThrow('email response timeout'); + await expect(readEmailEnvelope(uncooperative(), 5)).rejects.toThrow('email envelope timeout'); + }); }); diff --git a/packages/platform/test/unit/worker-config.test.ts b/packages/platform/test/unit/worker-config.test.ts index e09d30847..c31ac8623 100644 --- a/packages/platform/test/unit/worker-config.test.ts +++ b/packages/platform/test/unit/worker-config.test.ts @@ -1,7 +1,44 @@ import { describe, expect, it } from 'vite-plus/test'; -import { createPlatformDeploymentManifest } from '../../src/manifest.ts'; +import { + createPlatformDeploymentManifest, + parsePlatformDeploymentManifest, +} from '../../src/manifest.ts'; import { createPlatformWorkerConfigs } from '../../src/worker-config.ts'; +describe('platform email deployment manifest', () => { + const input = { + application: { baseDomain: 'apps.example.com', zoneName: 'example.com' }, + displayName: 'Example', + installationSlug: 'example', + }; + + it.each([{ emailSharedZoneId: 'mail-zone-id' }, { emailSenderDomain: 'mail.example.org' }])( + 'rejects incomplete shared email settings from the factory', + (email) => { + expect(() => createPlatformDeploymentManifest({ ...input, ...email })).toThrow( + 'requires both emailSenderDomain and emailSharedZoneId', + ); + }, + ); + + it('rejects either incomplete shared email setting while parsing', () => { + const complete = createPlatformDeploymentManifest({ + ...input, + emailSharedZoneId: 'mail-zone-id', + emailSenderDomain: 'mail.example.org', + }); + const { emailSenderDomain: _sender, ...zoneOnly } = complete; + const { emailSharedZoneId: _zone, ...senderOnly } = complete; + + expect(() => parsePlatformDeploymentManifest(zoneOnly)).toThrow( + 'requires both emailSenderDomain and emailSharedZoneId', + ); + expect(() => parsePlatformDeploymentManifest(senderOnly)).toThrow( + 'requires both emailSenderDomain and emailSharedZoneId', + ); + }); +}); + describe('platform usage queue bindings', () => { it('routes shared mail through its configured zone, independent of the application zone', () => { const deployment = createPlatformDeploymentManifest({ @@ -49,6 +86,7 @@ describe('platform usage queue bindings', () => { expect(configs.proxy.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); expect(configs.emailGateway.vars).toHaveProperty('EMAIL_SENDER_DOMAIN', 'mail.example.org'); expect(configs.emailGateway).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]); + expect(configs.proxy).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]); expect(configs.api.compatibility_flags).toContain('global_fetch_strictly_public'); expect(configs.api.vars).toHaveProperty( 'EMAIL_GATEWAY_ORIGIN', @@ -129,6 +167,8 @@ describe('platform usage queue bindings', () => { expect(configs.proxy.services).toEqual([ { binding: 'API', service: deployment.resources.apiWorker }, ]); + expect(configs.proxy).not.toHaveProperty('send_email'); + expect(configs.emailGateway).not.toHaveProperty('send_email'); expect(Object.keys(configs).sort()).toEqual([ 'api', 'dispatch', diff --git a/packages/void/skills/void/SKILL.md b/packages/void/skills/void/SKILL.md index 312750115..c6becccb0 100644 --- a/packages/void/skills/void/SKILL.md +++ b/packages/void/skills/void/SKILL.md @@ -32,7 +32,7 @@ When linking reports missing inferred resources, check the listed bindings and i For Cloudflare upload failures, use the detailed error message printed by the CLI and saved in the deploy log. A numeric error code alone may not identify the cause. Platform administration uses `void platform auth login` and the nested -`user`, `project`, `deployment`, `build`, `signup`, `invitation`, `system`, and +`user`, `project`, `deployment`, `build`, `signup`, `invitation`, `email`, `system`, and hosted-only `worker` groups. Open the operator section of `docs/reference/cli.md` before running these commands. Use `--json` for structured reads and `--plan` to inspect mutations; approved noninteractive mutations require `--yes`. @@ -159,4 +159,4 @@ Then ask what to do next. - For Void-managed auth, `void db generate` automatically includes the production Better Auth schema in the generated migration, including configured model/field renames and plugin tables. Keep those migrations under `db/migrations/`; do not duplicate generated auth tables in the application Drizzle schema. - **Env vars:** When the project has `env.ts`, the canonical access pattern is `import { env } from "void/env"`. Declare every env key in `env.ts` via `defineEnv({...})` so values are typed and validated. Do not introduce ad-hoc `process.env.X` or untyped `c.env.X` access in new code — add the key to `env.ts` first. -For platform email domains, use `void email domain add` with an account- and zone-scoped Cloudflare API token. Read inbound, outbound, and management readiness separately; `domain sync` reconciles without rotating secrets. Use a stable `sendEmail({ idempotencyKey })` for retryable sends and inspect `void email logs` when the result is `OUTCOME_UNKNOWN`; never retry an uncertain send with a new key. Native Cloudflare email setup remains `void email setup --platform cloudflare` and does not support platform idempotency keys. +For platform email domains, use `void email domain add` with an account- and zone-scoped Cloudflare API token. Read inbound, outbound, and management readiness separately; `domain sync` reconciles without rotating secrets. Use a stable `sendEmail({ idempotencyKey })` for retryable sends and inspect `void email logs` when the result is `OUTCOME_UNKNOWN`; never retry an uncertain send with a new key. Administrators can inspect retained outcomes with `void platform email logs --json`; use the project ID after deletion. Native Cloudflare email setup remains `void email setup --platform cloudflare` and does not support platform idempotency keys. diff --git a/packages/void/src/cli/client.ts b/packages/void/src/cli/client.ts index db7b60cd9..f429ef22f 100644 --- a/packages/void/src/cli/client.ts +++ b/packages/void/src/cli/client.ts @@ -226,7 +226,7 @@ export type BuildLogsResponse = { export type EmailUsageResponse = { month: string; - sent: number; + attempts: number; received: number; limit: number; remaining: number; diff --git a/packages/void/src/cli/email-args.ts b/packages/void/src/cli/email-args.ts index 2329bf248..48f85d841 100644 --- a/packages/void/src/cli/email-args.ts +++ b/packages/void/src/cli/email-args.ts @@ -7,7 +7,7 @@ const PLATFORM_FLAG = { }; export const emailSubcommands: Array = [ - { name: 'usage', description: 'Show monthly email send/receive counts and quota' }, + { name: 'usage', description: 'Show monthly recipient attempts, inbound receipts, and quota' }, { name: 'logs', description: 'Show recent email delivery activity' }, { name: 'destinations', description: 'List verified recipient addresses for outbound mail' }, { name: 'allow', arg: '
', description: 'Add a recipient and trigger CF verification' }, diff --git a/packages/void/src/cli/email.ts b/packages/void/src/cli/email.ts index 92f6441f0..1dc882265 100644 --- a/packages/void/src/cli/email.ts +++ b/packages/void/src/cli/email.ts @@ -100,10 +100,10 @@ async function emailUsage(client: PlatformClient, projectId: string): Promise', description: - entry.action === 'logs' + entry.action === 'logs' && group !== 'email' ? 'Maximum 500 log records' : 'Maximum 100 records per page', }, - ...(entry.action !== 'logs' + ...(entry.action !== 'logs' || group === 'email' ? [{ command: '--page ', description: 'One-based page number' }] : []), ] @@ -97,7 +97,11 @@ function operatorHelpTree(): HelpTree { ? 'Poll new logs until interrupted or the build ends' : flag === 'ended' ? 'Attest that the original provider execution has ended' - : 'Read a full API session from stdin for explicit operator session exchange', + : flag === 'token-stdin' && group === 'email' + ? entry.action === 'domain-remove' + ? 'Read a replacement Cloudflare token for blocked project cleanup from stdin' + : 'Read a scoped Cloudflare API token from stdin' + : 'Read a full API session from stdin for explicit operator session exchange', })), ], }, diff --git a/packages/void/src/cli/operator-args.ts b/packages/void/src/cli/operator-args.ts index 184e9152c..543fd3f1d 100644 --- a/packages/void/src/cli/operator-args.ts +++ b/packages/void/src/cli/operator-args.ts @@ -299,12 +299,22 @@ export const operatorCommands: Array = [ { group: 'email', action: 'limit', - description: "Set a project's monthly and burst email caps", + description: "Set a project's monthly and burst recipient submission caps", path: '/email/projects/:project/limit', positional: ['project'], - values: { monthly: 'Messages per month', burst: 'Messages per minute' }, + values: { + monthly: 'Recipient submissions per UTC calendar month', + burst: 'Recipient submissions per rolling 60-second window', + }, method: 'POST', }, + { + group: 'email', + action: 'logs', + description: 'Inspect retained email receipt and recipient outcomes for a project', + path: '/email/projects/:project/logs', + positional: ['project'], + }, { group: 'email', action: 'attempts', @@ -322,6 +332,19 @@ export const operatorCommands: Array = [ booleans: ['ended'], method: 'POST', }, + { + group: 'email', + action: 'operation-resolve', + description: 'Resolve an ended ambiguous email setup write with operator attestation', + path: '/email/operations/:id/resolve', + positional: ['id'], + values: { + outcome: 'Provider outcome: applied or not-applied', + reason: 'Audit reason for the verified provider outcome', + }, + booleans: ['ended'], + method: 'POST', + }, { group: 'email', action: 'domains', @@ -349,18 +372,26 @@ export const operatorCommands: Array = [ { group: 'email', action: 'domain-sync', - description: 'Redeploy an email domain relay and rotate its secret', + description: 'Reconcile an email domain with its Cloudflare setup', path: '/email/domains/:domain/sync', positional: ['domain'], method: 'POST', }, + { + group: 'email', + action: 'domain-rotate-secret', + description: "Rotate an email domain's ingress secret", + path: '/email/domains/:domain/rotate-secret', + positional: ['domain'], + method: 'POST', + }, { group: 'email', action: 'domain-remove', description: 'Remove an email domain and its Cloudflare setup', path: '/email/domains/:domain/remove', positional: ['domain'], - booleans: ['force'], + booleans: ['token-stdin'], method: 'POST', }, { @@ -514,7 +545,7 @@ export function parseOperatorArgs(args: Array): OperatorArgs { 'connection', ...(command.method ? ['timeout'] : []), ...Object.keys(command.values ?? {}), - ...(paged ? ['limit', ...(action !== 'logs' ? ['page'] : [])] : []), + ...(paged ? ['limit', ...(action !== 'logs' || group === 'email' ? ['page'] : [])] : []), ]); for (const name of Object.keys(values)) { if (!allowed.has(name)) { @@ -577,7 +608,8 @@ export function parseOperatorArgs(args: Array): OperatorArgs { continue; } if (name === 'page' || name === 'limit') { - const maximum = name === 'limit' ? (action === 'logs' ? 500 : 100) : 1_000_000; + const maximum = + name === 'limit' ? (action === 'logs' && group !== 'email' ? 500 : 100) : 1_000_000; if (!/^[1-9]\d*$/.test(value) || Number(value) > maximum) { throw new Error(`platform: --${name} must be an integer from 1 to ${maximum}.`); } diff --git a/packages/void/src/cli/operator-cmd.ts b/packages/void/src/cli/operator-cmd.ts index 3e146f98d..b86c111e2 100644 --- a/packages/void/src/cli/operator-cmd.ts +++ b/packages/void/src/cli/operator-cmd.ts @@ -180,6 +180,52 @@ function outputLogs(result: Record, json: boolean): void { } } +function operationRecoveryFence(value: unknown): { + stepId: string; + attempt: number; + requestDigest: string; + resourceIdentity: string; + connectionId: string; + desiredGeneration: number; + routeId: string | null; + routeDesiredGeneration: number | null; +} { + const target = + value && typeof value === 'object' && !Array.isArray(value) + ? (value as Record) + : null; + if ( + !target || + typeof target.stepId !== 'string' || + typeof target.attempt !== 'number' || + !Number.isSafeInteger(target.attempt) || + typeof target.requestDigest !== 'string' || + typeof target.resourceIdentity !== 'string' || + typeof target.connectionId !== 'string' || + typeof target.desiredGeneration !== 'number' || + !Number.isSafeInteger(target.desiredGeneration) || + (target.routeId !== null && typeof target.routeId !== 'string') || + (target.routeDesiredGeneration !== null && + (typeof target.routeDesiredGeneration !== 'number' || + !Number.isSafeInteger(target.routeDesiredGeneration))) + ) { + throw new OperatorClientError( + 'The server did not return a valid email operation recovery fence. No change was requested.', + 'invalid_preview', + ); + } + return { + stepId: target.stepId, + attempt: target.attempt, + requestDigest: target.requestDigest, + resourceIdentity: target.resourceIdentity, + connectionId: target.connectionId, + desiredGeneration: target.desiredGeneration, + routeId: target.routeId, + routeDesiredGeneration: target.routeDesiredGeneration, + }; +} + function runtimeLogFingerprint(row: unknown): string { const ingestedAt = row && typeof row === 'object' && !Array.isArray(row) @@ -466,11 +512,12 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { 'confirmation_required', ); } - // `email domain-add --token-stdin`: a Cloudflare API token for a zone - // outside the platform's account, read once and carried in the body of - // both the preview (which only classifies it) and the apply. Never - // printed; the server keeps it out of the audit log. - if (args.tokenStdin && args.group === 'email' && args.action === 'domain-add') { + // Read once for preview and apply; the server excludes the token from audit output. + if ( + args.tokenStdin && + args.group === 'email' && + (args.action === 'domain-add' || args.action === 'domain-remove') + ) { args = { ...args, body: { ...args.body, apiToken: await readOperatorApiTokenStdin() } }; } const preview = await client.request(args.path, { @@ -488,6 +535,10 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { 'invalid_preview', ); } + const recoveryFence = + args.group === 'email' && args.action === 'operation-resolve' + ? operationRecoveryFence(preview.target) + : {}; if (!(await confirmOperatorMutation(origin, preview, args))) { return; } @@ -496,6 +547,7 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { ...(args.group === 'worker' && args.action === 'rollback-all' ? { versions: preview.versions } : {}), + ...recoveryFence, }; output( await client.request(args.path, { method: 'POST', body, timeoutMs: args.timeoutMs }), @@ -505,7 +557,7 @@ export async function runOperatorCommand(args: OperatorArgs): Promise { await followOperatorLogs(client, args); } else { const result = await client.request(args.path, { query: args.query }); - if (args.action === 'logs') { + if (args.action === 'logs' && args.group !== 'email') { outputLogs(result, args.json); } else { output(result, args.json); diff --git a/packages/void/src/cli/platform-args.ts b/packages/void/src/cli/platform-args.ts index cc6b8746c..c93992fbc 100644 --- a/packages/void/src/cli/platform-args.ts +++ b/packages/void/src/cli/platform-args.ts @@ -10,7 +10,8 @@ export const platformSubcommands: Array = [ }, ...operatorGroups.map((name) => ({ name, - hint: name === 'email' ? 'Domains, policy, limits, and send recovery' : 'Operator commands', + hint: + name === 'email' ? 'Domains, policy, limits, outcomes, and recovery' : 'Operator commands', description: `Administer platform ${name}`, })), { name: 'list', description: 'List installed and connected platforms' }, diff --git a/packages/void/src/cli/platform-installer.ts b/packages/void/src/cli/platform-installer.ts index 9642ca862..5e469296d 100644 --- a/packages/void/src/cli/platform-installer.ts +++ b/packages/void/src/cli/platform-installer.ts @@ -336,6 +336,7 @@ export type PlatformInstallerDependencies = Readonly<{ databaseCheckpointExists: boolean, ) => Promise; healthCheckResumeCommand?: string; + bootstrapEmail?: typeof bootstrapPlatformSharedEmail; verifyHealth?: typeof verifyPlatformHealth; verifySandboxDrain?: (apiUrl: string, healthProbeToken: string) => Promise; verifyWorkerCutover?: ( @@ -345,6 +346,7 @@ export type PlatformInstallerDependencies = Readonly<{ }>; export type PlatformInstallationResult = Readonly<{ + emailOperationId?: string; manifest: PlatformInstallationManifest; setupPending?: boolean; waitingForDns: boolean; @@ -818,6 +820,11 @@ export async function installPlatform( plan.actions.some((action) => action.kind === 'worker' && action.action !== 'create')); const wasDisabled = existing?.status === 'disabled'; const preserveDisabled = existing?.desiredState === 'disabled'; + const shouldBootstrapSharedEmail = + !preserveDisabled && + plan.deployment.capabilities.email && + runtime.emailProtocolVersion === 1 && + !!plan.deployment.emailSharedZoneId; const previousPublicEndpoints = stablePublicEndpointState(existing); const authenticationProtocolTransition = hadPriorWorkers && @@ -1461,6 +1468,7 @@ export async function installPlatform( recoveringCreatedWorker || manifest.usageProtocolVersion !== targetUsageProtocolVersion || authenticationProtocolTransition || + shouldBootstrapSharedEmail || requiresSandboxDrain; if (requiresTrafficGuard) { await dependencies.client.putKvValue( @@ -1579,7 +1587,7 @@ export async function installPlatform( dependencies.client, plan.account.id, manifest!, - `${key}-worker`, + key === 'emailGateway' ? 'email-gateway-worker' : `${key}-worker`, snapshot.workerName, ), removeCustomDomains: async () => { @@ -2167,6 +2175,36 @@ export async function installPlatform( } }; await verifyCurrentWorkerCutover(); + let emailOperationId: string | undefined; + if (shouldBootstrapSharedEmail) { + // Shared-zone setup mutates provider routing. Once it begins, retain the + // verified Worker set and keep the installation's routing gate closed on + // failure so a retry can resume the durable email operation safely. + workerDeploymentCommitted = true; + manifest = recordWorkerCutoverResolution( + manifest, + workerCutoverGeneration, + 'committed', + now(), + ); + if (workerSecretUpdateIntent) { + manifest = recordWorkerSecretUpdateState( + manifest, + workerCutoverGeneration, + 'committed', + workerSecretUpdateIntent.id, + now(), + ); + } + writeInstallationManifest(manifest); + await writeRemoteInstallationCheckpoint(dependencies.client, plan, manifest); + workerRollbacks = []; + dependencies.onProgress?.('Preparing shared email routing'); + emailOperationId = await (dependencies.bootstrapEmail ?? bootstrapPlatformSharedEmail)( + plan.apiUrl, + createPlatformHealthProbeToken(manifest.ownershipNonce), + ); + } if (dependencies.client.deleteKvValue) { await dependencies.client.deleteKvValue( plan.account.id, @@ -2224,6 +2262,7 @@ export async function installPlatform( saveInstalledPlatformConnection(plan, manifest); return { manifest, + ...(emailOperationId ? { emailOperationId } : {}), setupPending, waitingForDns: false, waitingForSandboxDrain: false, @@ -2815,9 +2854,16 @@ export function platformWorkerSecretPayload( return null; } if (!existingWorker) { - return worker === 'api' - ? apiWorkerSecrets(secrets, accountId, zoneId) - : proxyWorkerSecrets(secrets, accountId); + if (worker === 'api') { + return apiWorkerSecrets(secrets, accountId, zoneId); + } + if (worker === 'emailGateway') { + return withoutEmptySecrets({ JWT_SECRET: secrets.jwtSecret }); + } + return proxyWorkerSecrets(secrets, accountId); + } + if (worker === 'emailGateway') { + return null; } const allowed = worker === 'api' @@ -2940,12 +2986,20 @@ export function assertRequiredPlatformSecrets( if ( plan.actions.some( (action) => - (action.key === 'proxy-worker' || action.key === 'email-gateway-worker') && + action.key === 'proxy-worker' && action.kind === 'worker' && action.action === 'create', + ) + ) { + requireSecret(secrets.cloudflareApiToken, 'VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN'); + requireSecret(secrets.jwtSecret, 'VOID_PLATFORM_JWT_SECRET'); + } + if ( + plan.actions.some( + (action) => + action.key === 'email-gateway-worker' && action.kind === 'worker' && action.action === 'create', ) ) { - requireSecret(secrets.cloudflareApiToken, 'VOID_PLATFORM_RUNTIME_CLOUDFLARE_API_TOKEN'); requireSecret(secrets.jwtSecret, 'VOID_PLATFORM_JWT_SECRET'); } if (missing.size > 0) { @@ -5501,6 +5555,52 @@ export async function verifyPlatformSandboxDrain( return status.state === 'complete'; } +export async function bootstrapPlatformSharedEmail( + apiUrl: string, + healthProbeToken: string, + fetcher: typeof fetch = fetch, +): Promise { + const response = await fetcher(`${apiUrl}/internal/platform/email-bootstrap`, { + method: 'POST', + headers: { + 'X-Void-Platform-Probe': healthProbeToken, + ...cfAccessHeaders(process.env, apiUrl), + }, + signal: AbortSignal.timeout(30_000), + redirect: 'manual', + }); + let value: unknown; + try { + value = await response.json(); + } catch { + throw new Error( + `platform: Shared email bootstrap failed at ${apiUrl} (HTTP ${response.status}). Traffic remains disabled.`, + ); + } + const status = + value && typeof value === 'object' && !Array.isArray(value) + ? (value as Record) + : null; + if ( + !response.ok || + status?.version !== 1 || + status.state !== 'ready' || + typeof status.operationId !== 'string' || + status.operationId.length === 0 + ) { + const detail = + status && typeof status.operationId === 'string' + ? ` Operation ${status.operationId}: ${typeof status.operationStatus === 'string' ? status.operationStatus : 'incomplete'}.` + : status && typeof status.operationStatus === 'string' + ? ` Operation status: ${status.operationStatus}.` + : ''; + throw new Error( + `platform: Shared email bootstrap did not reach inbound readiness at ${apiUrl} (HTTP ${response.status}).${detail} Traffic remains disabled.`, + ); + } + return status.operationId; +} + export function createPlatformHealthProbeToken(ownershipNonce: string): string { return createHash('sha256') .update('void-platform-health-probe:v1\0') diff --git a/packages/void/src/cli/platform-lifecycle.ts b/packages/void/src/cli/platform-lifecycle.ts index 440d633d4..9b1f44f9b 100644 --- a/packages/void/src/cli/platform-lifecycle.ts +++ b/packages/void/src/cli/platform-lifecycle.ts @@ -816,6 +816,9 @@ export async function runPlatformLifecycleCommand(args: PlatformArgs): Promise; + actions: ReadonlyArray<{ action: string; key: string; kind: string }>; }, secrets: Pick< ReturnType, @@ -571,7 +580,12 @@ export function resolvePlatformRuntimeTokenToPreflight( if (explicitUpdate) { return explicitUpdate; } - return plan.actions.some((action) => action.kind === 'worker' && action.action === 'create') + return plan.actions.some( + (action) => + action.kind === 'worker' && + action.action === 'create' && + (action.key === 'api-worker' || action.key === 'proxy-worker'), + ) ? secrets.cloudflareApiToken : ''; } diff --git a/packages/void/src/cli/platform-plan.ts b/packages/void/src/cli/platform-plan.ts index f699af78c..39793c7b5 100644 --- a/packages/void/src/cli/platform-plan.ts +++ b/packages/void/src/cli/platform-plan.ts @@ -4,6 +4,7 @@ import { createApplicationRoutes, createPlatformResourceOwnershipMarker, createPlatformResourceNames, + normalizeApplicationDomain, normalizeInstallationSlug, parsePlatformInstallationManifest, parsePlatformResourceOwnershipMarker, @@ -97,10 +98,19 @@ export async function createPlatformInstallPlan( `platform: Refusing to resume installation ${existing.id} in a different Cloudflare account.`, ); } + const providedEmailSharedZoneId = input.emailSharedZoneId?.trim(); + const providedEmailSenderDomain = input.emailSenderDomain?.trim(); + if ( + existing?.deployment.emailSharedZoneId && + providedEmailSharedZoneId && + existing.deployment.emailSharedZoneId !== providedEmailSharedZoneId + ) { + throw new Error('platform: The shared email zone is already recorded for this installation.'); + } if ( existing?.deployment.emailSenderDomain && - input.emailSenderDomain && - existing.deployment.emailSenderDomain !== input.emailSenderDomain.trim().toLowerCase() + providedEmailSenderDomain && + existing.deployment.emailSenderDomain !== normalizeApplicationDomain(providedEmailSenderDomain) ) { throw new Error( 'platform: The shared email sender domain is already recorded for this installation.', @@ -131,19 +141,33 @@ export async function createPlatformInstallPlan( ); } const testing = !!workersDev && !input.zoneName; - const deployment = createPlatformDeploymentManifest({ - authentication: input.authentication ?? existing?.deployment.authentication, + const emailSharedZoneId = ( + existing?.deployment.emailSharedZoneId ?? providedEmailSharedZoneId + )?.trim(); + const emailSenderDomain = existing?.deployment.emailSenderDomain ?? providedEmailSenderDomain; + if (!!emailSharedZoneId !== !!emailSenderDomain) { + throw new Error( + 'platform: Set VOID_EMAIL_SENDER_DOMAIN and VOID_EMAIL_SHARED_ZONE_ID together to enable email.', + ); + } + const normalizedEmailSenderDomain = emailSenderDomain + ? normalizeApplicationDomain(emailSenderDomain) + : undefined; + const enableEmail = + options?.includeEmailGateway !== false && !!emailSharedZoneId && !!normalizedEmailSenderDomain; + const capabilities = { + ...existing?.deployment.capabilities, ...(input.authentication ? { - capabilities: { - ...existing?.deployment.capabilities, - githubOAuth: input.authentication.providers.includes('github'), - googleOAuth: input.authentication.providers.includes('google'), - }, + githubOAuth: input.authentication.providers.includes('github'), + googleOAuth: input.authentication.providers.includes('google'), } - : existing - ? { capabilities: existing.deployment.capabilities } - : {}), + : {}), + ...(enableEmail ? { email: true } : {}), + }; + const deployment = createPlatformDeploymentManifest({ + authentication: input.authentication ?? existing?.deployment.authentication, + ...(Object.keys(capabilities).length > 0 ? { capabilities } : {}), application: { baseDomain: testing ? `${accountSubdomain}.workers.dev` : input.applicationDomain, dedicatedZone: input.dedicatedZone, @@ -159,12 +183,8 @@ export async function createPlatformInstallPlan( proxyHostname: null, }, displayName: input.displayName, - ...(existing?.deployment.emailSharedZoneId || input.emailSharedZoneId - ? { emailSharedZoneId: existing?.deployment.emailSharedZoneId ?? input.emailSharedZoneId } - : {}), - ...(existing?.deployment.emailSenderDomain || input.emailSenderDomain - ? { emailSenderDomain: existing?.deployment.emailSenderDomain ?? input.emailSenderDomain } - : {}), + ...(emailSharedZoneId ? { emailSharedZoneId } : {}), + ...(normalizedEmailSenderDomain ? { emailSenderDomain: normalizedEmailSenderDomain } : {}), installationSlug, resources: existing?.deployment.resources ?? createPlatformResourceNames(installationSlug), }); @@ -178,9 +198,17 @@ export async function createPlatformInstallPlan( emailSenderDomain: recordedSenderDomain, ...existingWithoutEmailZone } = existing?.deployment ?? deployment; + const comparableExistingWithoutEmailZone = + existing && deployment.capabilities.email && !existing.deployment.capabilities.email + ? { + ...existingWithoutEmailZone, + capabilities: { ...existingWithoutEmailZone.capabilities, email: true }, + } + : existingWithoutEmailZone; if ( existing && - (JSON.stringify(existingWithoutEmailZone) !== JSON.stringify(deploymentWithoutEmailZone) || + (JSON.stringify(comparableExistingWithoutEmailZone) !== + JSON.stringify(deploymentWithoutEmailZone) || (recordedEmailZone !== undefined && recordedEmailZone !== configuredEmailZone) || (recordedSenderDomain !== undefined && recordedSenderDomain !== configuredSenderDomain)) ) { diff --git a/packages/void/src/router/compile.ts b/packages/void/src/router/compile.ts index ab92a1664..90b014317 100644 --- a/packages/void/src/router/compile.ts +++ b/packages/void/src/router/compile.ts @@ -2887,7 +2887,7 @@ ${envValidateCall}${isrDeploymentStamp} const userEnv = __filterInternalBinding const emailImport = hasEmail ? ', __emailHandler' : ''; const emailRuntimePath = runtimeEmailPath ?? deriveEmailRuntimePath(runtimeEnvPath); const emailProxyImport = hasEmail - ? `import { createMessageProxy as __createMessageProxy, enactEmailActions as __enactEmailActions, isForwardableEmailMessage as __isForwardableEmailMessage } from ${JSON.stringify(emailRuntimePath)};\nimport { EMAIL_PROTOCOL_VERSION as __EMAIL_PROTOCOL_VERSION, encodeEmailActions as __encodeEmailActions, readEmailEnvelope as __readEmailEnvelope } from "void/_email-protocol";\n` + ? `import { createMessageProxy as __createMessageProxy, enactEmailActions as __enactEmailActions, isForwardableEmailMessage as __isForwardableEmailMessage } from ${JSON.stringify(emailRuntimePath)};\nimport { EMAIL_PROTOCOL_VERSION as __EMAIL_PROTOCOL_VERSION, encodeEmailActions as __encodeEmailActions, readEmailEnvelope as __readEmailEnvelope, verifyEmailReceiptThroughProxy as __verifyEmailReceiptThroughProxy } from "void/_email-protocol";\n` : ''; // `__VOID_PROJECT_SLUG` is the same binding the outbound `sendEmail` reads to // default `from`. It is passed to `createMessageProxy` so the user-visible @@ -2932,16 +2932,11 @@ ${envValidateCall} const userEnv = __filterInternalBindings(env); !env.__VOID_PROXY_TOKEN || !env.__PROJECT_ID || !env.__VOID_EMAIL_DEPLOYMENT_ID || !env.__VOID_PROXY) { return new Response(null, { status: 404 }); } - const __verificationBody = JSON.stringify({ receipt: __token, projectId: env.__PROJECT_ID, - deploymentId: env.__VOID_EMAIL_DEPLOYMENT_ID, recipient: __recipient }); - const __verification = await env.__VOID_PROXY.fetch("https://proxy/email/verify-receipt", { - method: "POST", - headers: { "content-type": "application/json", "x-void-internal": env.__VOID_PROXY_TOKEN }, - body: __verificationBody, + const __verified = await __verifyEmailReceiptThroughProxy(env.__VOID_PROXY, env.__VOID_PROXY_TOKEN, { + receipt: __token, projectId: env.__PROJECT_ID, + deploymentId: env.__VOID_EMAIL_DEPLOYMENT_ID, recipient: __recipient, }); - if (!__verification.ok) return new Response(null, { status: 404 }); - const __verified = await __verification.json(); - if (__verified?.valid !== true) return new Response(null, { status: 404 }); + if (!__verified) return new Response(null, { status: 404 }); let __envelope; try { __envelope = await __readEmailEnvelope(request.body); } catch { return new Response(null, { status: 400 }); } diff --git a/packages/void/src/runtime/email-protocol.ts b/packages/void/src/runtime/email-protocol.ts index d57c00109..e6a2e1333 100644 --- a/packages/void/src/runtime/email-protocol.ts +++ b/packages/void/src/runtime/email-protocol.ts @@ -5,3 +5,115 @@ export { encodeEmailActions, readEmailEnvelope, } from '@void/platform/email-protocol'; + +const RECEIPT_VERIFICATION_DEADLINE_MS = 5_000; +const MAX_RECEIPT_VERIFICATION_BYTES = 2 * 1024; +const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }); + +type ReceiptVerificationInput = { + receipt: string; + projectId: string; + deploymentId: string; + recipient: string; +}; + +type ReceiptVerifier = { + fetch(input: string | Request, init?: RequestInit): Promise; +}; + +async function beforeDeadline(deadline: number, run: () => Promise): Promise { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('email receipt verification timeout'); + } + let timer: ReturnType | undefined; + return Promise.race([ + run(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('email receipt verification timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); +} + +async function readResponseJson(response: Response, deadline: number): Promise { + const declaredLength = response.headers.get('content-length'); + if ( + response.headers.has('content-encoding') || + !response.body || + (declaredLength !== null && + (!/^\d+$/.test(declaredLength) || Number(declaredLength) > MAX_RECEIPT_VERIFICATION_BYTES)) + ) { + throw new Error('invalid email receipt verification response'); + } + const expectedLength = declaredLength === null ? null : Number(declaredLength); + const reader = response.body.getReader(); + const bytes = new Uint8Array(MAX_RECEIPT_VERIFICATION_BYTES); + let size = 0; + try { + for (;;) { + const chunk = await beforeDeadline(deadline, () => reader.read()); + if (chunk.done) { + break; + } + const nextSize = size + chunk.value.byteLength; + if (nextSize > bytes.byteLength) { + throw new Error('email receipt verification response too large'); + } + bytes.set(chunk.value, size); + size = nextSize; + } + } finally { + // An uncooperative stream may never settle cancellation. Start cleanup, + // but do not let it extend the hard request-and-response deadline. + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } + } + if (size === 0 || (expectedLength !== null && size !== expectedLength)) { + throw new Error('invalid email receipt verification response length'); + } + return JSON.parse(decoder.decode(bytes.subarray(0, size))); +} + +/** Validate a gateway receipt without exposing the signing secret to the tenant worker. */ +export async function verifyEmailReceiptThroughProxy( + proxy: ReceiptVerifier, + projectToken: string, + input: ReceiptVerificationInput, +): Promise { + const deadline = Date.now() + RECEIPT_VERIFICATION_DEADLINE_MS; + const controller = new AbortController(); + let response: Response | undefined; + try { + response = await beforeDeadline(deadline, () => + proxy.fetch('https://proxy/email/verify-receipt', { + method: 'POST', + headers: { 'content-type': 'application/json', 'x-void-internal': projectToken }, + body: JSON.stringify(input), + signal: controller.signal, + }), + ); + if (!response.ok) { + return false; + } + const body = await readResponseJson(response, deadline); + return ( + !!body && + typeof body === 'object' && + !Array.isArray(body) && + (body as Record).valid === true + ); + } catch { + return false; + } finally { + controller.abort(); + void response?.body?.cancel().catch(() => {}); + } +} diff --git a/packages/void/src/runtime/email.ts b/packages/void/src/runtime/email.ts index 0eeb27772..718a20c5b 100644 --- a/packages/void/src/runtime/email.ts +++ b/packages/void/src/runtime/email.ts @@ -153,6 +153,42 @@ interface ProxyEnv { // The `send_email` binding `void deploy --platform cloudflare` provisions // (`cli/email-cloudflare.ts` writes the same name into wrangler.jsonc). const SEND_EMAIL_BINDING_NAME = 'SEND_EMAIL'; +const EMAIL_PROVIDER_DEADLINE_MS = 30_000; +const PLATFORM_SEND_DEADLINE_MS = 60_000; + +class EmailBindingTimeoutError extends Error { + constructor() { + super('email binding outcome unknown after timeout'); + this.name = 'EmailBindingTimeoutError'; + } +} + +function createBindingSendDeadline() { + const deadline = Date.now() + PLATFORM_SEND_DEADLINE_MS; + return { + expired: () => Date.now() >= deadline, + async run(submit: () => Promise): Promise { + const remaining = Math.min(EMAIL_PROVIDER_DEADLINE_MS, deadline - Date.now()); + if (remaining <= 0) { + throw new EmailBindingTimeoutError(); + } + const work = submit(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + work, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new EmailBindingTimeoutError()), remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }, + }; +} // The legacy `EmailMessage` overload of `SendEmail.send`. Only `messageId` // is read, and defensively: some builds have returned nothing. @@ -179,9 +215,9 @@ function resolveSendEmailBinding( * Cloudflare's Workers API reference); the older Email Routing sender * throws message-only errors, so the destination-verification phrasing the * platform proxy already keys on is kept as a fallback. Anything else is - * `UPSTREAM_ERROR` with the original error as `cause` — the framework has - * no way to act on a delivery failure or a service outage beyond - * reporting it. + * `OUTCOME_UNKNOWN` with the original error as `cause`: once `send()` has + * started, an undocumented rejection does not prove the provider declined + * the message before accepting it. * */ function classifyBindingError(e: unknown): SendEmailError { @@ -203,7 +239,7 @@ function classifyBindingError(e: unknown): SendEmailError { if (UNVERIFIED_DESTINATION_RE.test(message)) { return makeError('UNVERIFIED_DESTINATION', message, e); } - return makeError('UPSTREAM_ERROR', message, e); + return makeError('OUTCOME_UNKNOWN', message, e); } // Anchored to Cloudflare's own phrasing ("destination address … not (yet) @@ -223,10 +259,10 @@ function bytesToReadableStream(bytes: Uint8Array): ReadableStream { /** * Deliver through the worker's own `SEND_EMAIL` binding. One `EmailMessage` - * per recipient, every recipient attempted, and the same `deliveries` shape - * the proxy returns so a caller retries the failed ones the same way in both - * modes. The stream is rebuilt per send because a `ReadableStream` is - * one-shot. + * per recipient, within one bounded batch, and the same `deliveries` shape + * the proxy returns so a caller can inspect each attempted or cancelled + * outcome in either mode. The stream is rebuilt per send because a + * `ReadableStream` is one-shot. */ async function sendViaBinding( binding: SendEmailBinding, @@ -246,15 +282,44 @@ async function sendViaBinding( ); } const deliveries: Array = []; - for (const recipient of recipients) { + const deadline = createBindingSendDeadline(); + for (let index = 0; index < recipients.length; index++) { + const recipient = recipients[index]; + if (deadline.expired()) { + for (const unstarted of recipients.slice(index)) { + deliveries.push({ + recipient: unstarted, + ok: false, + state: 'cancelled', + error: makeError( + 'UPSTREAM_ERROR', + 'email: batch deadline elapsed before provider submission', + ), + }); + } + break; + } try { - const result = await binding.send( - new EmailMessage(from, recipient, bytesToReadableStream(raw)), + const result = await deadline.run(() => + binding.send(new EmailMessage(from, recipient, bytesToReadableStream(raw))), ); const mid = typeof result?.messageId === 'string' ? result.messageId : ''; deliveries.push({ recipient, ok: true, messageId: mid || fallbackId }); } catch (e) { - deliveries.push({ recipient, ok: false, error: classifyBindingError(e) }); + const error = + e instanceof EmailBindingTimeoutError + ? makeError( + 'OUTCOME_UNKNOWN', + 'email: binding submission timed out; inspect provider logs before retrying', + e, + ) + : classifyBindingError(e); + deliveries.push({ + recipient, + ok: false, + ...(error.code === 'OUTCOME_UNKNOWN' ? { state: 'outcome_unknown' as const } : {}), + error, + }); } } if (deliveries.some((d) => !d.ok)) { @@ -352,22 +417,13 @@ function bytesToBase64(bytes: Uint8Array): string { interface ProxySendBody { projectId: string; - /** - * HMAC of `projectId` under the shared `JWT_SECRET`. The proxy currently - * reads this under the legacy `aiToken` key (auth was originally written - * for the AI proxy). New `proxyToken` field below ships the same value - * under the renamed key so the proxy can migrate without a coordinated - * release; once every deployed proxy reads `proxyToken`, drop `aiToken`. - */ + /** Project HMAC accepted by the shared proxy authentication middleware. */ aiToken: string; - proxyToken: string; from: string; recipients: Array; mimeBase64: string; - byteSize: number; requestId: string; idempotencyKey?: string; - fromDomain: string; } interface ProxyOkResponse { @@ -427,11 +483,7 @@ function readProxyRefusal(body: unknown): string | null { return typeof message === 'string' && message !== '' ? message : error; } -// Discriminator + shape check that runs before we destructure. The proxy -// response shape is well-defined, but treating the parsed body as -// `unknown` here lets us short-circuit to a clean UPSTREAM_ERROR for any -// malformed payload (null, primitive, missing discriminator, wrong -// array types) instead of throwing a TypeError mid-map. +// A malformed response leaves the provider outcome unknown. function isValidProxyResponse(b: unknown): b is ProxyResponse { if (typeof b !== 'object' || b === null) { return false; @@ -452,28 +504,10 @@ function isValidProxyResponse(b: unknown): b is ProxyResponse { type RecipientListRead = { ok: true; entries: Array } | { ok: false; reason: string }; /** - * Validate a per-recipient list from the proxy against the recipients this - * send asked for. Both list-bearing responses go through here — `ids` on - * `ok: true` and `deliveries` on a mid-batch `ok: false` — so the two cannot - * drift: the proxy builds both from the same per-recipient list, one entry - * per requested address, and a caller following the documented retry - * pattern (retry only `ok: false` entries) can act on an outcome only if - * every recipient has one. - * - * The rules shared by both shapes: the count equals the recipients sent; - * every entry is an object naming a requested recipient exactly once. The - * list is compared as a set against the unique, lowercased recipients the - * request carried and returned in the order the proxy gave it; order is not - * part of the contract. `readEntry` decides the rest of the entry's shape and - * returns `undefined` when it does not hold; `shape` names that shape in the - * reason. - * - * Anything else is a schema-skewed or corrupt proxy and is refused as a - * whole rather than trimmed to the entries that parse: a dropped entry is a - * recipient whose outcome the caller can neither trust nor retry. Entries - * are named by index only — the body is attached as `cause`, and a recipient - * string from a corrupt response is not a value to interpolate into an - * error message. + * Require exactly one valid outcome per requested recipient in either list + * shape. A missing, duplicate, or foreign entry makes the whole result unknown; + * trimming it could hide a submission. Order is not part of the contract. + * Diagnostics identify entries by index rather than echoing corrupt addresses. */ function readRecipientList( raw: Array, @@ -537,14 +571,8 @@ function readDeliveryList( } /** - * The `deliveries` list of a mid-batch `ok: false` response. Each entry is - * either a confirmed send (`ok: true`, `messageId` a string with the same - * `''` convention as above) or a failure (`ok: false`, `error` with a string - * `message`; the code is coerced, unknown values become `UPSTREAM_ERROR`). - * Both are the proxy's own outcome for that recipient; `ok` is what the - * caller retries on, so an entry that does not state it is not an outcome - * at all — treating it as failed would retry a recipient that may have been - * delivered, and treating it as delivered would silently lose one. + * Preserve each recipient's acceptance or error and recorded state. `ok: false` + * alone does not establish that retrying is safe: submission may be unresolved. */ function readFailureDeliveries( raw: Array, @@ -597,15 +625,99 @@ function readDeliveryState(value: unknown): EmailDeliveryState | undefined { return states.find((state) => state === value); } +const MAX_PROXY_RESPONSE_BYTES = 64 * 1024; + +function createPlatformSendDeadline(): { + signal: AbortSignal; + beforeDeadline: (run: () => Promise) => Promise; +} { + const controller = new AbortController(); + const deadline = Date.now() + PLATFORM_SEND_DEADLINE_MS; + return { + signal: controller.signal, + async beforeDeadline(run: () => Promise): Promise { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + controller.abort(); + throw new Error('email platform send timed out'); + } + const promise = run(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('email platform send timed out')); + }, remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }, + }; +} + +async function readBoundedProxyJson( + response: Response, + beforeDeadline: (run: () => Promise) => Promise, +): Promise { + const declared = response.headers.get('content-length'); + if ( + declared !== null && + (!/^\d+$/.test(declared) || Number(declared) > MAX_PROXY_RESPONSE_BYTES) + ) { + void response.body?.cancel().catch(() => {}); + throw new Error('email proxy response too large'); + } + const reader = response.body?.getReader(); + if (!reader) { + throw new Error('email proxy response is empty'); + } + const bytes = new Uint8Array(MAX_PROXY_RESPONSE_BYTES); + let size = 0; + try { + for (;;) { + const chunk = await beforeDeadline(() => reader.read()); + if (chunk.done) { + break; + } + if (size + chunk.value.byteLength > bytes.byteLength) { + throw new Error('email proxy response too large'); + } + bytes.set(chunk.value, size); + size += chunk.value.byteLength; + } + if (declared !== null && size !== Number(declared)) { + throw new Error('email proxy response length mismatch'); + } + return JSON.parse( + new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes.subarray(0, size)), + ) as unknown; + } finally { + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } + } +} + async function readResponseAsResult( res: Response, recipients: ReadonlyArray, fallbackId: string, + beforeDeadline: (run: () => Promise) => Promise, ): Promise { try { let body: unknown; try { - body = await res.json(); + body = await readBoundedProxyJson(res, beforeDeadline); } catch { return err( 'OUTCOME_UNKNOWN', @@ -658,30 +770,16 @@ async function readResponseAsResult( ? { ok: false, deliveries: list.entries, ...operation } : malformedList(list.reason); } - if ('error' in failure && failure.error) { - const e = failure.error as { code?: unknown; message?: unknown }; - return { - ...err( - coerceErrorCode(e.code), - typeof e.message === 'string' ? e.message : 'email: upstream send failed', - ), - ...operation, - }; - } - // Mid-batch — per-recipient outcomes, one per requested recipient, so - // the caller can retry exactly the failed ones. - const list = readFailureDeliveries( - failure.deliveries as Array, - recipients, - fallbackId, - ); - return list.ok - ? { ok: false, deliveries: list.entries, ...operation } - : malformedList(list.reason); + const e = failure.error as { code?: unknown; message?: unknown }; + return { + ...err( + coerceErrorCode(e.code), + typeof e.message === 'string' ? e.message : 'email: upstream send failed', + ), + ...operation, + }; } catch (e) { - // Defense-in-depth: any unexpected error parsing the proxy response - // becomes a clean UPSTREAM_ERROR rather than escaping `sendEmail` as - // an unhandled rejection. + // Parsing failures must not imply that no provider submission occurred. return err( 'OUTCOME_UNKNOWN', `email: failed to parse proxy response (status ${res.status}): ${e instanceof Error ? e.message : String(e)}`, @@ -974,27 +1072,28 @@ export async function sendEmail(opts: SendEmailOptions): Promise + proxy.fetch('https://email-proxy/email/send', { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: requestBody, + signal: deadline.signal, + }), + ); } catch (e) { return err( 'OUTCOME_UNKNOWN', @@ -1002,7 +1101,7 @@ export async function sendEmail(opts: SendEmailOptions): Promise = []; let total = 0; - for (;;) { - const { value, done } = await reader.read(); - if (done) { - break; + const deadline = Date.now() + EMAIL_STREAM_DEADLINE_MS; + try { + for (;;) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new MimeError('MIME_ERROR', 'email stream timed out'); + } + let timer: ReturnType | undefined; + const { value, done } = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout( + () => reject(new MimeError('MIME_ERROR', 'email stream timed out')), + remaining, + ); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (done) { + break; + } + total += value.byteLength; + if (total > limit) { + throw onOverflow(total); + } + chunks.push(value); } - total += value.byteLength; - if (total > limit) { - // Stop pulling: the producer would otherwise keep filling memory. - await reader.cancel().catch(() => {}); - throw onOverflow(total); + } catch (error) { + // Cancellation is cleanup, not part of the stream deadline. A custom + // handler stream may never settle its underlying cancel algorithm. + void reader.cancel().catch(() => {}); + throw error; + } finally { + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. } - chunks.push(value); } const out = new Uint8Array(total); let offset = 0; @@ -466,12 +505,32 @@ export function createMessageProxy( } let rejected = false; - let replyBytesUsed = 0; + // The gateway counts every metadata/raw frame and the terminal frame, so + // reserve that terminal here and reject an action before recording it. + let actionWireBytesUsed = EMAIL_ACTION_TERMINAL_BYTES; + let pendingReplies = 0; + let replyRecordingTail: Promise = Promise.resolve(); + + function recordAction(action: EmailAction): boolean { + if (rejected) { + return false; + } + if (actions.length >= MAX_ACTIONS) { + throw queueFull(); + } + const nextSize = actionWireBytesUsed + emailActionWireSize(action); + if (nextSize > EMAIL_MAX_RESPONSE_BYTES) { + throw replyBudgetExhausted(nextSize); + } + actions.push(action); + actionWireBytesUsed = nextSize; + return true; + } // `actions` only ever grows through forward/reply, and `setReject` purges // both, so length IS the queue depth. function assertQueueHasRoom(): void { - if (actions.length >= MAX_ACTIONS) { + if (actions.length + pendingReplies >= MAX_ACTIONS) { throw queueFull(); } } @@ -522,7 +581,9 @@ export function createMessageProxy( 'Move the reject earlier in the handler.', ); } - actions.push({ type: 'reject', reason: normalizeRejectReason(reason) }); + const action = { type: 'reject' as const, reason: normalizeRejectReason(reason) }; + actions.push(action); + actionWireBytesUsed = EMAIL_ACTION_TERMINAL_BYTES + emailActionWireSize(action); }, async forward(to: string, fwdHeaders?: Headers | Record) { if (rejected) { @@ -573,7 +634,7 @@ export function createMessageProxy( `forward: action metadata exceeds ${MAX_ACTION_METADATA_BYTES} bytes.`, ); } - actions.push(action); + void recordAction(action); }, async reply(reply: { from: string; to: string; raw: ReadableStream | Uint8Array }) { if (rejected) { @@ -598,49 +659,84 @@ export function createMessageProxy( // every earlier action had fired. Both are bare addresses. validateAddressParts('from', reply.from); validateAddressParts('to', reply.to); - // `replyEmail()` is bounded by `buildMime`; a hand-built reply is not, so - // bound it here before the bytes travel to the proxy (or to native reply). - const remaining = MAX_REPLY_BYTES_TOTAL - replyBytesUsed; - let rawBytes: Uint8Array; - if (reply.raw instanceof Uint8Array) { - if (reply.raw.byteLength > MAX_REPLY_BYTES) { - throw replyTooLarge(reply.raw.byteLength); + pendingReplies++; + const previousReply = replyRecordingTail; + let releaseReply!: () => void; + replyRecordingTail = new Promise((resolve) => { + releaseReply = resolve; + }); + await previousReply; + try { + if (rejected) { + console.warn( + '[void/email] reply() completed after setReject() — ignored. ' + + 'CF rejects are terminal: nothing else runs once setReject fires.', + ); + return; } - if (reply.raw.byteLength > remaining) { - throw replyBudgetExhausted(replyBytesUsed + reply.raw.byteLength); + // `replyEmail()` is bounded by `buildMime`; a hand-built reply is not, so + // bound it here before the bytes travel to the proxy (or to native reply). + const metadataOnlyAction = { + type: 'reply' as const, + from: reply.from, + to: reply.to, + raw: new Uint8Array(), + }; + const replyFrameBytes = emailActionWireSize(metadataOnlyAction); + const remaining = EMAIL_MAX_RESPONSE_BYTES - actionWireBytesUsed - replyFrameBytes; + if (remaining < 0) { + throw replyBudgetExhausted(EMAIL_MAX_RESPONSE_BYTES - remaining); } - rawBytes = reply.raw; - } else { - // A native `EmailMessage` lands here: `from` and `to` only, no `raw`. - // Name the problem instead of failing on `undefined.getReader()`, - // which in platform mode is a generic "project handler error" bounce - // with nothing a handler author could act on. - const raw: unknown = reply.raw; - if ( - typeof raw !== 'object' || - raw === null || - typeof (raw as ReadableStream).getReader !== 'function' - ) { - throw new MimeError( - 'MIME_ERROR', - 'reply: expected { from, to, raw } with raw as a Uint8Array or ReadableStream. ' + - 'A native EmailMessage cannot be replayed from a Void handler — its body has ' + - 'no public accessor. Use replyEmail() from void/email, or pass the MIME bytes as raw.', + let rawBytes: Uint8Array; + if (reply.raw instanceof Uint8Array) { + if (reply.raw.byteLength > MAX_REPLY_BYTES) { + throw replyTooLarge(reply.raw.byteLength); + } + if (reply.raw.byteLength > remaining) { + throw replyBudgetExhausted( + actionWireBytesUsed + replyFrameBytes + reply.raw.byteLength, + ); + } + rawBytes = reply.raw; + } else { + // A native `EmailMessage` lands here: `from` and `to` only, no `raw`. + // Name the problem instead of failing on `undefined.getReader()`, + // which in platform mode is a generic "project handler error" bounce + // with nothing a handler author could act on. + const raw: unknown = reply.raw; + if ( + typeof raw !== 'object' || + raw === null || + typeof (raw as ReadableStream).getReader !== 'function' + ) { + throw new MimeError( + 'MIME_ERROR', + 'reply: expected { from, to, raw } with raw as a Uint8Array or ReadableStream. ' + + 'A native EmailMessage cannot be replayed from a Void handler — its body has ' + + 'no public accessor. Use replyEmail() from void/email, or pass the MIME bytes as raw.', + ); + } + // The REMAINING budget, not the per-reply cap — an earlier reply has + // already spent part of it, and the stream must stop where the budget + // does. Whichever bound is lower is the one that fires, so the + // callback names the one that actually bound this read. + const limit = Math.min(MAX_REPLY_BYTES, remaining); + rawBytes = await readStreamToBytes(reply.raw, limit, (total) => + limit === MAX_REPLY_BYTES + ? replyTooLarge(total) + : replyBudgetExhausted(actionWireBytesUsed + replyFrameBytes + total), ); } - // The REMAINING budget, not the per-reply cap — an earlier reply has - // already spent part of it, and the stream must stop where the budget - // does. Whichever bound is lower is the one that fires, so the - // callback names the one that actually bound this read. - const limit = Math.min(MAX_REPLY_BYTES, remaining); - rawBytes = await readStreamToBytes(reply.raw, limit, (total) => - limit === MAX_REPLY_BYTES - ? replyTooLarge(total) - : replyBudgetExhausted(replyBytesUsed + total), - ); + if (!recordAction({ type: 'reply', from: reply.from, to: reply.to, raw: rawBytes })) { + console.warn( + '[void/email] reply() completed after setReject() — ignored. ' + + 'CF rejects are terminal: nothing else runs once setReject fires.', + ); + } + } finally { + pendingReplies--; + releaseReply(); } - replyBytesUsed += rawBytes.byteLength; - actions.push({ type: 'reply', from: reply.from, to: reply.to, raw: rawBytes }); }, } as unknown as ForwardableEmailMessage; @@ -1236,6 +1332,43 @@ export function isForwardableEmailMessage(value: unknown): value is ForwardableE ); } +const INBOUND_PROVIDER_DEADLINE_MS = 30_000; +const INBOUND_ACTION_BATCH_DEADLINE_MS = 60_000; + +function createInboundProviderDeadline() { + const deadline = Date.now() + INBOUND_ACTION_BATCH_DEADLINE_MS; + return { + async run(submit: () => Promise): Promise { + const remaining = Math.min(INBOUND_PROVIDER_DEADLINE_MS, deadline - Date.now()); + if (remaining <= 0) { + throw new Error('email action batch deadline elapsed before provider submission'); + } + const work = submit(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + work, + new Promise((_, reject) => { + timer = setTimeout( + () => + reject( + new Error( + 'email action provider timed out; outcome unknown, do not retry automatically', + ), + ), + remaining, + ); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }, + }; +} + /** * Replay recorded `EmailAction`s on a real `ForwardableEmailMessage`, in * order. The proxy already made `setReject` terminal (earlier forward/reply @@ -1251,18 +1384,23 @@ export async function enactEmailActions( message: ForwardableEmailMessage, actions: ReadonlyArray, ): Promise { + const providerDeadline = createInboundProviderDeadline(); for (const action of actions) { switch (action.type) { case 'reject': message.setReject(action.reason); break; case 'forward': - await message.forward(action.to, action.headers ? new Headers(action.headers) : undefined); + await providerDeadline.run(() => + message.forward(action.to, action.headers ? new Headers(action.headers) : undefined), + ); break; case 'reply': { const { EmailMessage } = await import('cloudflare:email'); - await message.reply( - new EmailMessage(action.from, action.to, bytesToReadableStream(action.raw)), + await providerDeadline.run(() => + message.reply( + new EmailMessage(action.from, action.to, bytesToReadableStream(action.raw)), + ), ); break; } diff --git a/packages/void/src/runtime/email/mime.ts b/packages/void/src/runtime/email/mime.ts index 340169c38..4cedffd7b 100644 --- a/packages/void/src/runtime/email/mime.ts +++ b/packages/void/src/runtime/email/mime.ts @@ -40,32 +40,16 @@ export const MAX_MESSAGE_BYTES: number = 5 * 1024 * 1024; const MAX_ATTACHMENT_BYTES_TOTAL: number = Math.floor((MAX_MESSAGE_BYTES * 3) / 4); /** - * Cap on the recipient count across `to`, `cc` and `bcc`, checked against - * the RAW input before a single address is parsed. - * - * The platform proxy refuses more than 50 recipients (`MAX_RECIPIENTS` in - * `proxy/src/email.ts`, counted on the deduplicated list this module - * produces), so on the platform a larger list is always rejected — but only - * after the tenant has parsed every address and rendered the whole `To:` - * header. Measured, that rendering costs about 250 bytes of heap per - * recipient plus the header's own ~31 bytes per character, so 230k short, - * valid addresses (a 4.8 MiB message, legal under `MAX_MESSAGE_BYTES`) - * terminated a 128 MB isolate instead of reaching the proxy's `INVALID_TO`. - * Under `void dev` the same list was captured as a success and failed only - * once deployed. Mirroring the cap here makes it a precise, catchable error - * at the call that went wrong, in every mode. - * - * This is the framework's own limit on an own-account deploy, where the - * `SEND_EMAIL` binding sends one envelope per recipient and imposes no - * per-call count. Cloudflare's object-form `send()` API caps `to + cc + bcc` - * at 50, so 100 is the looser of the two. - * - * Counted on the raw entries rather than after deduplication: parsing is what - * this bound exists to skip, so a list of 150 entries with 100 unique - * addresses is refused here where the proxy would have accepted it. + * Bound raw `to`, `cc`, and `bcc` entries before parsing or rendering headers. + * Counting before deduplication also bounds work for duplicate-heavy input. + * The same SDK limit applies in development and on both deployment targets; + * platform admission independently caps the unique recipients at 50. */ export const MAX_RECIPIENTS: number = 50; +/** Maximum serialized size of app-defined top-level MIME fields. */ +const MAX_CUSTOM_HEADER_BYTES: number = 16 * 1024; + /** * Pre-parse cap on one parsed address, in characters. RFC 5321 §4.5.3.1 * allows a 64-octet local part and a 255-octet domain, so nothing over 320 @@ -749,7 +733,9 @@ export async function normalizeEmail(opts: { rejectCRLF('subject', opts.subject); } if (opts.headers) { + let headerInputBytes = 0; let headerBytes = 0; + const encoder = new TextEncoder(); for (const [name, value] of Object.entries(opts.headers)) { if (!HEADER_NAME.test(name)) { throw new MimeError( @@ -775,14 +761,35 @@ export async function normalizeEmail(opts: { `so its line would exceed the ${MAX_LINE_OCTETS}-octet limit in RFC 5322 §2.1.1. Shorten the name.`, ); } - if (headerBytes + name.length + value.length + 4 > 16 * 1024) { + // Keep raw input work bounded even when folding later collapses a long + // whitespace run. The character check rejects huge values before the + // UTF-8 measurement allocates its byte copy. + if (headerInputBytes + name.length + value.length + 4 > MAX_CUSTOM_HEADER_BYTES) { throw new MimeError('MIME_ERROR', 'email: custom headers exceed the 16 KiB limit.'); } - headerBytes += name.length + new TextEncoder().encode(value).byteLength + 4; - if (headerBytes > 16 * 1024) { + headerInputBytes += name.length + encoder.encode(value).byteLength + 4; + if (headerInputBytes > MAX_CUSTOM_HEADER_BYTES) { throw new MimeError('MIME_ERROR', 'email: custom headers exceed the 16 KiB limit.'); } rejectCRLF(`header '${name}'`, value); + if (RESERVED_HEADERS.has(name.toLowerCase())) { + continue; + } + // Reject an obviously oversized value before encoding it. This is a + // lower bound because encoded words and folding only add bytes. + if ( + headerBytes + name.length + CUSTOM_HEADER_FRAMING_OCTETS + minHeaderValueOctets(value) > + MAX_CUSTOM_HEADER_BYTES + ) { + throw new MimeError('MIME_ERROR', 'email: custom headers exceed the 16 KiB limit.'); + } + // Match the proxy's wire-level accounting exactly: RFC 2047 expansion, + // every folded continuation line, and the terminating CRLF. encodeWord + // always returns ASCII, so the rendered string length is its byte size. + headerBytes += foldHeader(name, encodeWord(value)).length + CRLF.length; + if (headerBytes > MAX_CUSTOM_HEADER_BYTES) { + throw new MimeError('MIME_ERROR', 'email: custom headers exceed the 16 KiB limit.'); + } } } // Before any address is parsed: the count is what bounds the work below. diff --git a/packages/void/test/unit/email-inbound.test.ts b/packages/void/test/unit/email-inbound.test.ts index d82ac53de..20fce3521 100644 --- a/packages/void/test/unit/email-inbound.test.ts +++ b/packages/void/test/unit/email-inbound.test.ts @@ -3,6 +3,11 @@ import { mkdirSync, rmSync, writeFileSync } from 'node:fs'; import { pathToFileURL } from 'node:url'; import { join } from 'pathslash'; import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; +import { + EMAIL_MAX_RESPONSE_BYTES, + encodeEmailActions, + readEmailActions, +} from '../../../platform/src/email-protocol.ts'; import { compileRouteTable } from '../../src/router/compile.ts'; import { compileWorkerEntry } from '../../src/router/compile.ts'; import { @@ -16,6 +21,7 @@ import { buildReplyMessage, createMessageProxy, defineEmail, + enactEmailActions, isForwardableEmailMessage, MAX_INBOUND_BYTES, MAX_INBOUND_HEADERS, @@ -33,6 +39,16 @@ const INVALID_ADDRESS = import { createInboundTestHarness } from '../../src/runtime/email/testing.ts'; import { envContext } from '../../src/runtime/env-raw.ts'; +vi.mock('cloudflare:email', () => ({ + EmailMessage: class MockEmailMessage { + constructor( + readonly from: string, + readonly to: string, + readonly raw: ReadableStream | string, + ) {} + }, +})); + const TMP = join(import.meta.dirname, '.tmp-email-inbound'); function setupRoot(files: Record): string { @@ -898,6 +914,7 @@ describe('compileWorkerEntry (email)', () => { ); expect(code).not.toContain('async email(envelope)'); expect(code).toContain('return __handleEmailReceipt(request, env, ctx)'); + expect(code).toContain('await __verifyEmailReceiptThroughProxy('); expect(code).toContain('await __readEmailEnvelope(request.body)'); expect(code).toContain('async function handleEmail'); expect(code).toContain('from "void/_email-protocol"'); @@ -3123,6 +3140,33 @@ describe('end-to-end: envelope → handler → action queue', () => { expect(pulls).toBeLessThanOrEqual(7); }); + it('bounds a stalled reply stream without awaiting its cancellation', async () => { + vi.useFakeTimers(); + try { + const cancel = vi.fn(() => new Promise(() => {})); + const raw = new ReadableStream({ + pull() { + return new Promise(() => {}); + }, + cancel, + }); + const handler = defineEmail(async (message) => { + await message.reply({ + from: 'support@app.dev', + to: 'sender@example.com', + raw, + } as unknown as Parameters[0]); + }); + const result = dispatchToHandler(makeEnvelope(), handler); + const rejected = expect(result).rejects.toThrow('email stream timed out'); + await vi.advanceTimersByTimeAsync(15_001); + await rejected; + expect(cancel).toHaveBeenCalledOnce(); + } finally { + vi.useRealTimers(); + } + }); + it('refuses the 101st queued action and leaves the queue at 100', async () => { // The queue crosses the RPC boundary into the SHARED proxy isolate, where // it is walked entry by entry before any quota gate has looked at it. @@ -3145,18 +3189,24 @@ describe('end-to-end: envelope → handler → action queue', () => { expect((thrown as MimeError).message).toMatch(/more than 100 actions/); }); - it('refuses a third reply once the cumulative reply budget is spent', async () => { - // The first two replies spend the 8 MiB response budget exactly. + it('accounts for action frames in the cumulative reply budget before recording', async () => { + const from = 'support@app.dev'; + const to = 'sender@example.com'; + const metadataBytes = new TextEncoder().encode( + JSON.stringify({ type: 'reply', from, to }), + ).byteLength; + const firstSize = 5 * 1024 * 1024; + const secondSize = EMAIL_MAX_RESPONSE_BYTES - 5 - 2 * (10 + metadataBytes) - firstSize; let thrown: unknown; const handler = defineEmail(async (message) => { const send = (raw: Uint8Array) => message.reply({ - from: 'support@app.dev', - to: 'sender@example.com', + from, + to, raw, } as unknown as Parameters[0]); - await send(new Uint8Array(5 * 1024 * 1024)); - await send(new Uint8Array(3 * 1024 * 1024)); + await send(new Uint8Array(firstSize)); + await send(new Uint8Array(secondSize)); try { await send(new Uint8Array(1)); } catch (e) { @@ -3164,14 +3214,19 @@ describe('end-to-end: envelope → handler → action queue', () => { } }); const actions = await dispatchToHandler(makeEnvelope(), handler); - // Both in-budget replies are queued; only the third is refused. expect(actions).toHaveLength(2); expect(thrown).toBeInstanceOf(MimeError); - expect((thrown as MimeError).message).toMatch(/cumulative reply size/); + expect((thrown as MimeError).message).toMatch(/serialized actions/); + const decoded = await readEmailActions(encodeEmailActions(actions)); + expect(decoded).toHaveLength(2); + expect(decoded.map((action) => (action.type === 'reply' ? action.raw.byteLength : -1))).toEqual( + [firstSize, secondSize], + ); }); it('cancels a stream reply at the REMAINING budget, not the per-reply cap', async () => { - // 7 MiB already spent out of the 8 MiB budget, so 1 MiB is left. A + // 7 MiB of reply bodies plus their frames have already been spent, so + // slightly less than 1 MiB is left. A // stream bounded by the per-reply cap would keep pulling to 5 MiB and // report the wrong limit; the pull count and the message both pin that // the remaining budget is what stopped it. @@ -3209,12 +3264,83 @@ describe('end-to-end: envelope → handler → action queue', () => { const actions = await dispatchToHandler(makeEnvelope(), handler); expect(actions).toHaveLength(2); expect(cancelled).toBe(true); - // 1 MiB of remaining budget + the chunk that crosses it + read-ahead. + // Less than 1 MiB remains; allow the crossing chunk plus read-ahead. expect(pulls).toBeLessThanOrEqual(3); expect(thrown).toBeInstanceOf(MimeError); - expect((thrown as MimeError).message).toMatch(/cumulative reply size/); + expect((thrown as MimeError).message).toMatch(/serialized actions/); + }); + + it('does not record a streamed reply that completes after setReject', async () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + try { + let controller!: ReadableStreamDefaultController; + const raw = new ReadableStream({ + start(value) { + controller = value; + }, + }); + const { message, getActions } = createMessageProxy(makeEnvelope()); + const pending = message.reply({ + from: 'support@app.dev', + to: 'sender@example.com', + raw, + } as unknown as Parameters[0]); + await Promise.resolve(); + message.setReject('stop'); + controller.enqueue(new TextEncoder().encode('From: support@app.dev\r\n\r\nlate')); + controller.close(); + + await pending; + expect(getActions()).toEqual([{ type: 'reject', reason: 'stop' }]); + expect(warn).toHaveBeenCalledWith(expect.stringContaining('completed after setReject')); + } finally { + warn.mockRestore(); + } }); + it('reserves queue slots for concurrent replies before buffering them', async () => { + const { message, getActions } = createMessageProxy(makeEnvelope()); + const reply = () => + message.reply({ + from: 'support@app.dev', + to: 'sender@example.com', + raw: new Uint8Array(), + } as unknown as Parameters[0]); + const pending = Array.from({ length: 100 }, reply); + await expect(reply()).rejects.toThrow(/more than 100 actions/); + await Promise.all(pending); + expect(getActions()).toHaveLength(100); + }); + + it.each(['forward', 'reply'] as const)( + 'bounds a nonsettling native %s provider action', + async (kind) => { + vi.useFakeTimers(); + try { + const message = { + setReject: vi.fn(), + forward: vi.fn(() => new Promise(() => {})), + reply: vi.fn(() => new Promise(() => {})), + } as unknown as ForwardableEmailMessage; + const action = + kind === 'forward' + ? ({ type: 'forward', to: 'archive@example.com' } as const) + : ({ + type: 'reply', + from: 'support@app.dev', + to: 'sender@example.com', + raw: new Uint8Array(), + } as const); + const pending = enactEmailActions(message, [action]); + const outcome = expect(pending).rejects.toThrow(/outcome unknown/); + await vi.advanceTimersByTimeAsync(30_000); + await outcome; + } finally { + vi.useRealTimers(); + } + }, + ); + it('refuses a forward address over the address-length limit', async () => { const handler = defineEmail(async (message) => { await message.forward(`${'a'.repeat(320)}@example.com`); diff --git a/packages/void/test/unit/email-mime.test.ts b/packages/void/test/unit/email-mime.test.ts index bd4b79827..e9d6a14ea 100644 --- a/packages/void/test/unit/email-mime.test.ts +++ b/packages/void/test/unit/email-mime.test.ts @@ -2517,14 +2517,28 @@ describe('buildMime header size projection', () => { }); }); - it('bounds aggregate custom headers before rendering, including names and UTF-8 bytes', async () => { + it('bounds aggregate custom headers by their encoded and folded wire size', async () => { const base = { from: 'a@x.dev', to: 'b@y.dev', subject: 's', text: 'hi' }; await expect( normalizeEmail({ ...base, headers: { 'X-Note': 'x'.repeat(16 * 1024) } }), ).rejects.toThrow('16 KiB'); - await expect( - normalizeEmail({ ...base, headers: { 'X-Note': '漢'.repeat(6000) } }), - ).rejects.toThrow('16 KiB'); + // 15,000 input bytes expand to more than 25 KiB of RFC 2047 words and + // folded continuation lines. The proxy measures the latter. + const unicode = '漢'.repeat(5000); + expect(new TextEncoder().encode(unicode)).toHaveLength(15_000); + await expect(normalizeEmail({ ...base, headers: { 'X-Note': unicode } })).rejects.toThrow( + '16 KiB', + ); + // These two fields occupy under 16 KiB before rendering, but folding + // replaces enough spaces with CRLF + SPACE to cross the wire limit. + const foldedValue = 'word '.repeat(1595).trimEnd(); + const foldedHeaders = { 'X-One': foldedValue, 'X-Two': foldedValue }; + const inputBytes = Object.entries(foldedHeaders).reduce( + (sum, [name, value]) => sum + name.length + new TextEncoder().encode(value).byteLength + 4, + 0, + ); + expect(inputBytes).toBeLessThan(16 * 1024); + await expect(normalizeEmail({ ...base, headers: foldedHeaders })).rejects.toThrow('16 KiB'); const names = Object.fromEntries( Array.from({ length: 40 }, (_, i) => [`X${i}`.padEnd(500, 'a'), '']), ); diff --git a/packages/void/test/unit/email-own-account.test.ts b/packages/void/test/unit/email-own-account.test.ts index 5c5855682..f5e171720 100644 --- a/packages/void/test/unit/email-own-account.test.ts +++ b/packages/void/test/unit/email-own-account.test.ts @@ -178,8 +178,8 @@ describe('sendEmail (SEND_EMAIL binding)', () => { ['E_SENDER_DOMAIN_NOT_AVAILABLE', 'INVALID_FROM'], ['E_RATE_LIMIT_EXCEEDED', 'QUOTA_EXCEEDED'], ['E_DAILY_LIMIT_EXCEEDED', 'QUOTA_EXCEEDED'], - ['E_DELIVERY_FAILED', 'UPSTREAM_ERROR'], - ['E_INTERNAL_SERVER_ERROR', 'UPSTREAM_ERROR'], + ['E_DELIVERY_FAILED', 'OUTCOME_UNKNOWN'], + ['E_INTERNAL_SERVER_ERROR', 'OUTCOME_UNKNOWN'], ])( 'maps a thrown %s to %s per recipient, keeping the Cloudflare message', async (cfCode, code) => { @@ -196,6 +196,7 @@ describe('sendEmail (SEND_EMAIL binding)', () => { { recipient: 'b@example.com', ok: false, + ...(code === 'OUTCOME_UNKNOWN' ? { state: 'outcome_unknown' } : {}), error: { code, message: `cloudflare says: ${cfCode}`, cause: thrown }, }, ], @@ -402,14 +403,7 @@ describe('generated handleEmail on a native ForwardableEmailMessage', () => { }); it('enacts a forward recorded after parseEmail drained the native raw stream', async () => { - // The documented handler shape — `parseEmail(message)`, then - // `message.forward(...)` — reads the one-shot native `raw` to completion - // before the forward is replayed, exactly as Cloudflare's own "Email - // Storage" example does on a real message. The replay must not depend - // on `raw`: `forward(rcptTo, headers?)` carries no bytes, the runtime - // forwards the message it holds (miniflare's local `forward` never reads - // `raw` either), so a disturbed stream at replay time is the ordinary - // case, not a fault. + // Native forwarding must still work after parsing consumes the raw stream. const handleEmail = buildHandleEmail(async (message) => { const parsed = await parseEmail(message); await message.forward('ops@acme.com', new Headers({ 'X-Subject': parsed.subject ?? '' })); @@ -419,18 +413,9 @@ describe('generated handleEmail on a native ForwardableEmailMessage', () => { to: 'support@mail.acme.com', mime: INBOUND_MIME, }); - const nativeForward = message.forward.bind(message); - let rawLockedAtForward: boolean | undefined; - vi.spyOn(message, 'forward').mockImplementation(async (to, fwdHeaders) => { - rawLockedAtForward = message.raw.locked; - return nativeForward(to, fwdHeaders); - }); - const actions = await handleEmail(message, {}, {}); - // The parse consumed the native stream and it is still held by that - // reader when the native forward fires — and the forward fires anyway. - expect(rawLockedAtForward).toBe(true); + expect(await readAll(message.raw)).toBe(''); expect(calls.forwards).toHaveLength(1); expect(calls.forwards[0].to).toBe('ops@acme.com'); expect(calls.forwards[0].headers?.get('X-Subject')).toBe('Help'); diff --git a/packages/void/test/unit/email-protocol.test.ts b/packages/void/test/unit/email-protocol.test.ts new file mode 100644 index 000000000..5d5e59872 --- /dev/null +++ b/packages/void/test/unit/email-protocol.test.ts @@ -0,0 +1,113 @@ +import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; +import { verifyEmailReceiptThroughProxy } from '../../src/runtime/email-protocol.ts'; + +const input = { + receipt: 'receipt-token', + projectId: 'project-1', + deploymentId: 'deployment-1', + recipient: 'support@example.com', +}; + +afterEach(() => { + vi.useRealTimers(); +}); + +describe('email receipt proxy verification', () => { + it('sends the project proof and accepts a bounded valid response', async () => { + const fetch = vi.fn(async (_url: string | Request, _init?: RequestInit) => + Response.json({ valid: true, receiptId: 'receipt-1' }), + ); + + await expect(verifyEmailReceiptThroughProxy({ fetch }, 'project-token', input)).resolves.toBe( + true, + ); + expect(fetch).toHaveBeenCalledOnce(); + const [url, init] = fetch.mock.calls[0]; + expect(url).toBe('https://proxy/email/verify-receipt'); + expect(init?.headers).toMatchObject({ 'x-void-internal': 'project-token' }); + expect(JSON.parse(String(init?.body))).toEqual(input); + }); + + it('ends an uncooperative fetch at the absolute deadline and aborts its signal', async () => { + vi.useFakeTimers(); + const captured: { signal: AbortSignal | null } = { signal: null }; + const verification = verifyEmailReceiptThroughProxy( + { + fetch(_input, init) { + captured.signal = init?.signal ?? null; + return new Promise(() => {}); + }, + }, + 'project-token', + input, + ); + + await vi.advanceTimersByTimeAsync(5_000); + + await expect(verification).resolves.toBe(false); + expect(captured.signal?.aborted).toBe(true); + }); + + it('strictly checks response bytes and declared length', async () => { + const invalidUtf8 = await verifyEmailReceiptThroughProxy( + { + async fetch() { + return new Response(new Uint8Array([0xff]), { + headers: { 'content-length': '1' }, + }); + }, + }, + 'project-token', + input, + ); + expect(invalidUtf8).toBe(false); + + const wrongLength = await verifyEmailReceiptThroughProxy( + { + async fetch() { + return new Response('{}', { headers: { 'content-length': '3' } }); + }, + }, + 'project-token', + input, + ); + expect(wrongLength).toBe(false); + + const oversized = await verifyEmailReceiptThroughProxy( + { + async fetch() { + return new Response(new Uint8Array(2 * 1024 + 1)); + }, + }, + 'project-token', + input, + ); + expect(oversized).toBe(false); + }); + + it('does not await cancellation of a stalled response stream', async () => { + vi.useFakeTimers(); + let cancelled = 0; + const verification = verifyEmailReceiptThroughProxy( + { + async fetch() { + return new Response( + new ReadableStream({ + cancel() { + cancelled++; + return new Promise(() => {}); + }, + }), + ); + }, + }, + 'project-token', + input, + ); + + await vi.advanceTimersByTimeAsync(5_000); + + await expect(verification).resolves.toBe(false); + expect(cancelled).toBe(1); + }); +}); diff --git a/packages/void/test/unit/email-send.test.ts b/packages/void/test/unit/email-send.test.ts index b4d03688a..517dc52ce 100644 --- a/packages/void/test/unit/email-send.test.ts +++ b/packages/void/test/unit/email-send.test.ts @@ -172,6 +172,129 @@ describe('sendEmail (test harness)', () => { } }); + it('bounds native binding submissions and preserves later provider references', async () => { + vi.useFakeTimers(); + try { + const send = vi + .fn() + .mockImplementationOnce(() => new Promise(() => {})) + .mockResolvedValueOnce({ messageId: 'cf-second' }); + const pending = withRuntimeEnv({ SEND_EMAIL: { send } }, () => + sendEmail({ + from: 'a@x.dev', + to: ['first@y.dev', 'second@y.dev'], + subject: 'deadline', + text: 'body', + }), + ); + + await vi.advanceTimersByTimeAsync(30_000); + const result = await pending; + + expect(result).toMatchObject({ + ok: false, + deliveries: [ + { + recipient: 'first@y.dev', + state: 'outcome_unknown', + error: { code: 'OUTCOME_UNKNOWN' }, + }, + { recipient: 'second@y.dev', ok: true, messageId: 'cf-second' }, + ], + }); + expect(send).toHaveBeenCalledTimes(2); + } finally { + vi.useRealTimers(); + } + }); + + it('stops a native binding batch at 60 seconds without submitting the remainder', async () => { + vi.useFakeTimers(); + try { + const send = vi.fn(() => new Promise(() => {})); + const pending = withRuntimeEnv({ SEND_EMAIL: { send } }, () => + sendEmail({ + from: 'a@x.dev', + to: ['first@y.dev', 'second@y.dev', 'third@y.dev'], + subject: 'batch deadline', + text: 'body', + }), + ); + + await vi.advanceTimersByTimeAsync(60_000); + const result = await pending; + + expect(send).toHaveBeenCalledTimes(2); + expect(result).toMatchObject({ + ok: false, + deliveries: [ + { state: 'outcome_unknown', error: { code: 'OUTCOME_UNKNOWN' } }, + { state: 'outcome_unknown', error: { code: 'OUTCOME_UNKNOWN' } }, + { state: 'cancelled', error: { code: 'UPSTREAM_ERROR' } }, + ], + }); + } finally { + vi.useRealTimers(); + } + }); + + it('treats an undocumented native binding rejection as an unknown outcome', async () => { + const cause = new Error('connection closed after submission'); + const send = vi.fn().mockRejectedValue(cause); + const result = await withRuntimeEnv({ SEND_EMAIL: { send } }, () => + sendEmail({ + from: 'a@x.dev', + to: 'b@y.dev', + subject: 'ambiguous rejection', + text: 'body', + }), + ); + + expect(result).toMatchObject({ + ok: false, + deliveries: [ + { + recipient: 'b@y.dev', + state: 'outcome_unknown', + error: { + code: 'OUTCOME_UNKNOWN', + message: 'connection closed after submission', + cause, + }, + }, + ], + }); + }); + + it('keeps a documented native provider refusal definitive', async () => { + const cause = Object.assign(new Error('recipient is not allowed'), { + code: 'E_RECIPIENT_NOT_ALLOWED', + }); + const result = await withRuntimeEnv( + { SEND_EMAIL: { send: vi.fn().mockRejectedValue(cause) } }, + () => + sendEmail({ + from: 'a@x.dev', + to: 'b@y.dev', + subject: 'provider refusal', + text: 'body', + }), + ); + + expect(result).toMatchObject({ + ok: false, + deliveries: [ + { + recipient: 'b@y.dev', + error: { code: 'UNVERIFIED_DESTINATION', cause }, + }, + ], + }); + if (!result.ok && 'deliveries' in result) { + expect(result.deliveries[0].state).toBeUndefined(); + } + }); + it('clear() empties the harness without disposing the sink', async () => { const harness = createEmailTestHarness(); try { @@ -568,11 +691,7 @@ describe('sendEmail (proxy round trip)', () => { expect(calls[0].url).toContain('/email/send'); const body = calls[0].body as Record; expect(body.projectId).toBe('p_test'); - // Legacy auth field name (proxy still reads it under the historical - // `aiToken` key). New `proxyToken` ships the same value so the proxy - // can migrate without a coordinated release. expect(body.aiToken).toBe('tok'); - expect(body.proxyToken).toBe('tok'); expect(body.from).toBe('a@x.dev'); expect(Array.isArray(body.recipients)).toBe(true); expect(body.recipients as Array).toEqual(['b@y.dev']); @@ -646,6 +765,84 @@ describe('sendEmail (proxy round trip)', () => { } }); + it.each(['fetch', 'body'] as const)( + 'returns OUTCOME_UNKNOWN when the platform proxy %s never settles', + async (stall) => { + vi.useFakeTimers(); + try { + let markStarted!: () => void; + const started = new Promise((resolve) => { + markStarted = resolve; + }); + const proxy = { + fetch() { + markStarted(); + if (stall === 'fetch') { + return new Promise(() => {}); + } + return Promise.resolve( + new Response( + new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode('{"ok":true,"ids":[')); + }, + }), + ), + ); + }, + }; + const pending = withRuntimeEnv({ __VOID_PROXY: proxy, ...PROXY_ENV_KEYS }, () => + sendEmail({ + from: 'a@x.dev', + to: 'b@y.dev', + subject: 's', + text: 't', + sendInDev: true, + }), + ); + + await started; + await vi.advanceTimersByTimeAsync(0); + await vi.advanceTimersByTimeAsync(60_000); + const result = await pending; + expect(result).toMatchObject({ ok: false, error: { code: 'OUTCOME_UNKNOWN' } }); + } finally { + vi.useRealTimers(); + } + }, + ); + + it('returns OUTCOME_UNKNOWN without reading an oversized proxy response', async () => { + const cancel = vi.fn(); + const proxy = { + async fetch() { + return new Response( + new ReadableStream( + { + cancel, + pull() { + throw new Error('oversized body must not be read'); + }, + }, + { highWaterMark: 0 }, + ), + { headers: { 'content-length': String(64 * 1024 + 1) } }, + ); + }, + }; + const result = await withRuntimeEnv({ __VOID_PROXY: proxy, ...PROXY_ENV_KEYS }, () => + sendEmail({ + from: 'a@x.dev', + to: 'b@y.dev', + subject: 's', + text: 't', + sendInDev: true, + }), + ); + expect(result).toMatchObject({ ok: false, error: { code: 'OUTCOME_UNKNOWN' } }); + await vi.waitFor(() => expect(cancel).toHaveBeenCalledOnce()); + }); + it('passes mid-batch deliveries through unchanged', async () => { const { proxy } = fakeProxy(() => ({ status: 200, @@ -958,13 +1155,12 @@ describe('sendEmail (proxy delivery list)', () => { // as `ids`: one entry per requested address, each either // `{ recipient, ok: true, messageId }` or `{ recipient, ok: false, error }` // (the proxy always attaches `error` to a failed entry — both its producer -// paths do). The documented retry pattern acts on exactly the `ok: false` -// entries, so a list that skips, repeats or invents a recipient, or an -// entry that does not state its outcome, cannot be acted on: skipping the -// bad entry would leave a recipient with no outcome and no retry, and -// treating an entry with no `ok` as failed would retry a recipient that may -// have been delivered. Such a response is a schema-skewed or corrupt proxy -// and is refused as a whole, under the same rules as the success path. +// paths do). A list that skips, repeats or invents a recipient, or an entry +// that does not state its outcome, cannot be acted on: skipping the bad entry +// would leave a recipient with no outcome, and treating an entry with no `ok` +// as failed could lead to a duplicate delivery. Such a response is a +// schema-skewed or corrupt proxy and is refused as a whole, under the same +// rules as the success path. describe('sendEmail (proxy mid-batch delivery list)', () => { const send = (proxy: ReturnType['proxy'], to: string | Array) => withRuntimeEnv({ __VOID_PROXY: proxy, ...PROXY_ENV_KEYS }, () => @@ -1181,8 +1377,8 @@ describe('sendEmail (proxy mid-batch delivery list)', () => { it('does not refuse a mid-batch list in which every entry succeeded', async () => { // Contradicts `anyFailed`, but every recipient has a trustworthy - // outcome and the retry filter selects nothing. Refusing it would make - // the caller retry the whole call and deliver duplicates. + // accepted outcome. Refusing it would make the caller treat the whole + // call as unknown despite the complete provider evidence. const { proxy } = fakeProxy(() => ({ status: 200, body: { diff --git a/packages/void/test/unit/operator-cli.test.ts b/packages/void/test/unit/operator-cli.test.ts index 4ca53cb7c..7dcb0c98d 100644 --- a/packages/void/test/unit/operator-cli.test.ts +++ b/packages/void/test/unit/operator-cli.test.ts @@ -151,6 +151,15 @@ describe('operator argument and help coverage', () => { }); expect(() => parseOperatorArgs(['email', 'policy', '--domains', 'x'])).toThrow(); expect(() => parseOperatorArgs(['email', 'limit'])).toThrow(); + expect( + parseOperatorArgs(['email', 'logs', 'project/id', '--page', '2', '--limit', '100']), + ).toMatchObject({ + method: 'GET', + path: '/email/projects/project%2Fid/logs', + query: { page: '2', limit: '100' }, + }); + expect(() => parseOperatorArgs(['email', 'logs', 'project', '--limit', '101'])).toThrow(); + expect(() => parseOperatorArgs(['email', 'logs', 'project', '--follow'])).toThrow(); }); it('routes attempt inspection and attested resolution with a bounded audit reason', () => { expect( @@ -177,8 +186,28 @@ describe('operator argument and help coverage', () => { yes: true, }); expect(() => parseOperatorArgs(['email', 'attempts', '--ended'])).toThrow(); + expect( + parseOperatorArgs([ + 'email', + 'operation-resolve', + 'operation/id', + '--ended', + '--outcome', + 'not-applied', + '--reason', + 'Provider audit completed', + ]), + ).toMatchObject({ + method: 'POST', + path: '/email/operations/operation%2Fid/resolve', + body: { + ended: true, + outcome: 'not-applied', + reason: 'Provider audit completed', + }, + }); }); - it('routes the email domain verbs and carries their booleans in the body', () => { + it('routes the email domain verbs', () => { expect(parseOperatorArgs(['email', 'domains', '--project', 'hr-portal'])).toMatchObject({ method: 'GET', path: '/email/domains', @@ -210,14 +239,22 @@ describe('operator argument and help coverage', () => { path: '/email/domains/mail.example.com/sync', body: {}, }); + expect(parseOperatorArgs(['email', 'domain-rotate-secret', 'mail.example.com'])).toMatchObject({ + method: 'POST', + path: '/email/domains/mail.example.com/rotate-secret', + body: {}, + }); + expect(parseOperatorArgs(['email', 'domain-remove', 'mail.example.com']).body).toEqual({}); expect( - parseOperatorArgs(['email', 'domain-remove', 'mail.example.com', '--force']), + parseOperatorArgs(['email', 'domain-remove', 'mail.example.com', '--token-stdin', '--yes']), ).toMatchObject({ method: 'POST', path: '/email/domains/mail.example.com/remove', - body: { force: true }, + body: {}, + tokenStdin: true, + yes: true, }); - expect(parseOperatorArgs(['email', 'domain-remove', 'mail.example.com']).body).toEqual({}); + expect(() => parseOperatorArgs(['email', 'domain-remove', 'x', '--force'])).toThrow(); expect(() => parseOperatorArgs(['email', 'domain-sync', 'x', '--force'])).toThrow(); expect(() => parseOperatorArgs(['email', 'domain-add', 'x', '--force'])).toThrow(); }); @@ -398,6 +435,76 @@ describe('operator transport and execution', () => { versions: { api: 'version-a' }, }); }); + it.each(['--plan', '--yes'])( + 'reads a cleanup token once for %s without printing it', + async (mode) => { + vi.stubEnv('VOID_API_URL', 'https://one.example'); + vi.stubEnv('VOID_OPERATOR_TOKEN', 'operator'); + const output = vi.spyOn(console, 'log').mockImplementation(() => {}); + const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true); + const stdin = vi + .spyOn(process.stdin, Symbol.asyncIterator) + .mockImplementation(async function* () { + yield 'replacement-cloudflare-token\n'; + return undefined; + }); + const fetcher = vi + .fn() + .mockResolvedValueOnce( + Response.json({ + dryRun: true, + action: 'email.domain.remove', + target: { domain: 'mail.example.com', credentialReplacement: true }, + }), + ) + .mockResolvedValueOnce(Response.json({ operationStatus: 'completed' })); + vi.stubGlobal('fetch', fetcher); + await runOperatorCommand( + parseOperatorArgs(['email', 'domain-remove', 'mail.example.com', '--token-stdin', mode]), + ); + expect(stdin).toHaveBeenCalledTimes(1); + expect(fetcher).toHaveBeenCalledTimes(mode === '--plan' ? 1 : 2); + expect(JSON.parse(String(fetcher.mock.calls[0]![1]!.body))).toEqual({ + apiToken: 'replacement-cloudflare-token', + dryRun: true, + }); + if (mode === '--yes') { + expect(JSON.parse(String(fetcher.mock.calls[1]![1]!.body))).toEqual({ + apiToken: 'replacement-cloudflare-token', + }); + } + expect(JSON.stringify([output.mock.calls, stderr.mock.calls])).not.toContain( + 'replacement-cloudflare-token', + ); + }, + ); + it('prints email recipient outcomes through the operator logs command', async () => { + vi.stubEnv('VOID_API_URL', 'https://one.example'); + vi.stubEnv('VOID_OPERATOR_TOKEN', 'operator'); + const output = vi.spyOn(console, 'log').mockImplementation(() => {}); + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue( + Response.json({ + projectId: 'project-1', + page: 1, + limit: 20, + logs: [ + { + operationId: 'action-1', + recipient: 'one@example.com', + status: 'provider_accepted', + transport: 'binding', + }, + ], + }), + ), + ); + await runOperatorCommand(parseOperatorArgs(['email', 'logs', 'project-1'])); + const printed = output.mock.calls.flat().join('\n'); + expect(printed).toContain('one@example.com'); + expect(printed).toContain('provider_accepted'); + }); it('previews then submits an attested email attempt resolution', async () => { vi.stubEnv('VOID_API_URL', 'https://one.example'); vi.stubEnv('VOID_OPERATOR_TOKEN', 'operator'); @@ -438,6 +545,58 @@ describe('operator transport and execution', () => { reason: 'Worker execution ended', }); }); + it('pins email operation recovery execution to the previewed step fence', async () => { + vi.stubEnv('VOID_API_URL', 'https://one.example'); + vi.stubEnv('VOID_OPERATOR_TOKEN', 'operator'); + vi.spyOn(console, 'log').mockImplementation(() => {}); + const fetcher = vi + .fn() + .mockResolvedValueOnce( + Response.json({ + dryRun: true, + action: 'email.operation.resolve', + target: { + operationId: 'eop_1', + stepId: 'estep_1', + attempt: 2, + requestDigest: 'digest-1', + resourceIdentity: 'account/zone/worker/relay/7', + connectionId: 'ezc_1', + desiredGeneration: 4, + routeId: 'edr_1', + routeDesiredGeneration: 3, + }, + }), + ) + .mockResolvedValueOnce(Response.json({ status: 'pending' })); + vi.stubGlobal('fetch', fetcher); + await runOperatorCommand( + parseOperatorArgs([ + 'email', + 'operation-resolve', + 'eop_1', + '--ended', + '--outcome', + 'applied', + '--reason', + 'Exact provider resource verified', + '--yes', + ]), + ); + expect(JSON.parse(String(fetcher.mock.calls[1]![1]!.body))).toEqual({ + ended: true, + outcome: 'applied', + reason: 'Exact provider resource verified', + stepId: 'estep_1', + attempt: 2, + requestDigest: 'digest-1', + resourceIdentity: 'account/zone/worker/relay/7', + connectionId: 'ezc_1', + desiredGeneration: 4, + routeId: 'edr_1', + routeDesiredGeneration: 3, + }); + }); it('drains runtime cursors and rejects repeated cursors instead of spinning', async () => { vi.spyOn(console, 'log').mockImplementation(() => {}); const fetcher = vi diff --git a/packages/void/test/unit/platform-installer.test.ts b/packages/void/test/unit/platform-installer.test.ts index 7a38e6c63..e289fdd1a 100644 --- a/packages/void/test/unit/platform-installer.test.ts +++ b/packages/void/test/unit/platform-installer.test.ts @@ -26,7 +26,7 @@ import { type PlatformRuntimeDatabaseManifest, } from '@void/platform/installer'; import { join } from 'pathslash'; -import { afterEach, beforeEach, describe, expect, it } from 'vite-plus/test'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test'; import { hyperdriveOriginConfigHash, hyperdriveOriginFromConnectionString, @@ -34,6 +34,7 @@ import { import { acquirePlatformDatabaseLifecycleLockConnection, apiWorkerSecrets, + bootstrapPlatformSharedEmail, platformWorkerSecretPayload, assertRequiredPlatformSecrets, classifyPlatformWorkerDeploymentLineage, @@ -568,6 +569,103 @@ describe('platform installer', () => { }, ); + it('keeps traffic disabled and the verified Worker set when shared email bootstrap blocks', async () => { + const directory = mkdtempSync(join(tmpdir(), 'void-platform-email-bootstrap-test-')); + directories.push(directory); + process.env.VOID_PLATFORM_REGISTRY_DIR = directory; + const plan = await createPlatformInstallPlan( + planningClient(), + { + accountId: 'account', + applicationDomain: '', + zoneName: '', + workersDev: true, + controlPlaneDomain: '', + dedicatedZone: false, + displayName: 'Email', + emailSenderDomain: 'mail.example.com', + emailSharedZoneId: 'mail-zone-id', + installationSlug: 'email', + }, + null, + ); + const secrets = createPlatformInstallationSecrets({ + bootstrapGitHubId: '583231', + bootstrapGitHubLogin: 'octocat', + cloudflareApiToken: 'test-token', + databaseUrl: 'postgres://user:password@db.example.com/email', + githubClientId: 'id', + githubClientSecret: 'secret', + jwtSecret: TEST_PLATFORM_JWT_SECRET, + projectSecretKey: TEST_PLATFORM_PROJECT_SECRET_KEY, + r2AccessKeyId: 'id', + r2SecretAccessKey: 'secret', + }); + let index = 0; + const create = async (_account: string, name: string) => ({ + id: `resource-${index++}`, + name, + }); + const rollbacks: Array = []; + const deletedKeys: Array = []; + const kvWrites: Array<{ key: string; value: string }> = []; + const bootstrapEmail = vi.fn(async () => { + throw new Error('shared email operation is blocked'); + }); + + await expect( + installPlatform(plan, secrets, null, { + claimDatabase, + acquireDatabaseLifecycleLock, + bootstrapEmail, + client: { + createAiGateway: create, + createDnsRecord: async () => { + throw new Error('no DNS expected'); + }, + createZone: async () => { + throw new Error('no zone expected'); + }, + createKvNamespace: create, + createR2Bucket: create, + createQueue: create, + createDispatchNamespace: create, + createHyperdrive: create, + putKvValue: async (_account, _namespace, key, value) => { + kvWrites.push({ key, value }); + }, + deleteKvValue: async (_account, _namespace, key) => { + deletedKeys.push(key); + }, + putR2Object: async () => {}, + }, + deployWorker: async (config) => async () => { + rollbacks.push(String(config.name)); + }, + migrateDatabase: async () => {}, + revalidateBeforeWorkerDeploy: async () => {}, + verifyHealth: async () => {}, + }), + ).rejects.toThrow('shared email operation is blocked'); + + expect(bootstrapEmail).toHaveBeenCalledTimes(1); + expect(deletedKeys).not.toContain(PLATFORM_DISABLED_KEY); + expect(kvWrites).toContainEqual({ key: PLATFORM_DISABLED_KEY, value: PLATFORM_DISABLED_VALUE }); + expect(rollbacks).toEqual([]); + const failed = listInstallationManifests(directory)[0]!; + expect(failed.status).toBe('failed'); + expect( + failed.steps.some( + (step) => step.key.startsWith('worker-cutover:') && step.resultHash === 'committed', + ), + ).toBe(true); + expect( + failed.steps.some( + (step) => step.key.startsWith('worker-traffic-state:') && step.resultHash === 'enabled', + ), + ).toBe(false); + }); + it('requires externally custodied identity keys for a fresh installation', () => { const input = { bootstrapGitHubId: '583231', @@ -1463,6 +1561,39 @@ describe('platform installer', () => { expect(requests.every((entry) => entry.redirect === 'manual')).toBe(true); }); + it('requires the shared email bootstrap probe to report durable inbound readiness', async () => { + const requests: Array<{ headers: Headers; method?: string; redirect?: RequestRedirect }> = []; + const readyFetcher = (async (_input: string | URL | Request, init?: RequestInit) => { + requests.push({ + headers: new Headers(init?.headers), + method: init?.method, + redirect: init?.redirect, + }); + return Response.json({ version: 1, state: 'ready', operationId: 'eop-ready' }); + }) as typeof fetch; + + expect( + await bootstrapPlatformSharedEmail('https://api.example.com', 'probe-token', readyFetcher), + ).toBe('eop-ready'); + expect(requests).toHaveLength(1); + expect(requests[0]?.method).toBe('POST'); + expect(requests[0]?.redirect).toBe('manual'); + expect(requests[0]?.headers.get('X-Void-Platform-Probe')).toBe('probe-token'); + + await expect( + bootstrapPlatformSharedEmail('https://api.example.com', 'probe-token', (async () => + Response.json( + { + version: 1, + state: 'incomplete', + operationId: 'eop-blocked', + operationStatus: 'blocked', + }, + { status: 503 }, + )) as typeof fetch), + ).rejects.toThrow('Operation eop-blocked: blocked. Traffic remains disabled'); + }); + it.each([ 'https://api.example.com/health', 'https://api.example.com/.well-known/void-platform', @@ -2727,6 +2858,72 @@ describe('platform installer', () => { ); }); + it('recreates only the email gateway with its shared JWT and no Cloudflare token', async () => { + const fullPlan = await createPlatformInstallPlan( + planningClient(), + { + accountId: 'account', + applicationDomain: 'apps.example.com', + controlPlaneDomain: '', + dedicatedZone: false, + displayName: 'Example', + installationSlug: 'example', + zoneName: 'example.com', + }, + null, + ); + const plan = { + ...fullPlan, + actions: fullPlan.actions.filter((action) => action.key === 'email-gateway-worker'), + }; + let manifest = createPlatformInstallationManifest({ + account: plan.account, + createdAt: '2026-01-01T00:00:00.000Z', + deployment: plan.deployment, + id: plan.installationId, + ownershipNonce: 'ownership-nonce-0123456789abcdef', + platformVersion: '1.0.0', + }); + manifest = recordInstallationStep( + manifest, + { + completedAt: '2026-01-01T00:00:00.000Z', + key: 'bootstrap-access:v1', + resultHash: 'bootstrap-hash', + }, + '2026-01-01T00:00:00.000Z', + ); + const secrets = createPlatformInstallationSecrets({ + bootstrapGitHubId: '', + bootstrapGitHubLogin: '', + cloudflareApiToken: '', + databaseUrl: 'postgres://user:password@db.example.com/void', + existingInstallation: true, + githubClientId: '', + githubClientSecret: '', + jwtSecret: TEST_PLATFORM_JWT_SECRET, + r2AccessKeyId: '', + r2SecretAccessKey: '', + }); + + expect(() => assertRequiredPlatformSecrets(plan, manifest, secrets)).not.toThrow(); + expect(platformWorkerSecretPayload('emailGateway', secrets, 'account', 'zone', false)).toEqual({ + JWT_SECRET: TEST_PLATFORM_JWT_SECRET, + }); + expect( + platformWorkerSecretPayload( + 'emailGateway', + { ...secrets, cloudflareApiToken: 'must-not-be-deployed' }, + 'account', + 'zone', + false, + ), + ).toEqual({ JWT_SECRET: TEST_PLATFORM_JWT_SECRET }); + expect( + platformWorkerSecretPayload('emailGateway', secrets, 'account', 'zone', true), + ).toBeNull(); + }); + it('does not checkpoint failure when another host owns the lifecycle lock', async () => { const directory = mkdtempSync(join(tmpdir(), 'void-platform-lock-contender-test-')); directories.push(directory); @@ -3478,10 +3675,14 @@ describe('platform installer', () => { putR2Object: async () => {}, }, deployWorker: async () => {}, + bootstrapEmail: async () => { + throw new Error('email bootstrap must stay disabled'); + }, migrateDatabase: async () => {}, revalidateBeforeWorkerDeploy: async () => {}, verifyHealth: async () => {}, }); + expect(installed.manifest.deployment.capabilities.email).toBe(false); const byKey = new Map(installed.manifest.resources.map((resource) => [resource.key, resource])); expect(byKey.get('hyperdrive')?.configHash).toBe( hyperdriveOriginConfigHash(hyperdriveOriginFromConnectionString(secrets.databaseUrl)), diff --git a/packages/void/test/unit/platform-management-upgrade.test.ts b/packages/void/test/unit/platform-management-upgrade.test.ts index 0b6d4aa59..25635790e 100644 --- a/packages/void/test/unit/platform-management-upgrade.test.ts +++ b/packages/void/test/unit/platform-management-upgrade.test.ts @@ -181,6 +181,7 @@ vi.mock('../../src/cli/platform-registry.ts', async (importOriginal) => { import { log, note } from '@clack/prompts'; import { installPlatform } from '../../src/cli/platform-installer.ts'; import { runInstalledPlatformCommand } from '../../src/cli/platform-management.ts'; +import { createPlatformInstallPlan } from '../../src/cli/platform-plan.ts'; describe('installed platform upgrade', () => { beforeEach(() => { @@ -248,10 +249,32 @@ describe('installed platform upgrade', () => { afterEach(() => { vi.restoreAllMocks(); + vi.unstubAllEnvs(); delete process.env.VOID_PLATFORM_PROJECT_SECRET_ACTIVE_KEY_VERSION; delete process.env.VOID_PLATFORM_PROJECT_SECRET_KEYS_JSON; }); + it('includes shared email configuration when planning an upgrade', async () => { + vi.stubEnv('VOID_EMAIL_SHARED_ZONE_ID', 'mail-zone'); + vi.stubEnv('VOID_EMAIL_SENDER_DOMAIN', 'mail.example.com'); + await runInstalledPlatformCommand({ + plan: true, + runtime: '', + selector: state.manifest!.id, + subcommand: 'upgrade', + yes: true, + }); + expect(createPlatformInstallPlan).toHaveBeenCalledWith( + expect.anything(), + expect.objectContaining({ + emailSharedZoneId: 'mail-zone', + emailSenderDomain: 'mail.example.com', + }), + expect.anything(), + expect.anything(), + ); + }); + it('borrows database preparation from the held lifecycle lock', async () => { await runInstalledPlatformCommand({ plan: false, diff --git a/packages/void/test/unit/platform-management.test.ts b/packages/void/test/unit/platform-management.test.ts index a0deba381..59b616dc0 100644 --- a/packages/void/test/unit/platform-management.test.ts +++ b/packages/void/test/unit/platform-management.test.ts @@ -294,7 +294,9 @@ const uninstallArgs = { describe('platform lifecycle management', () => { it('preflights only a runtime token that will be applied', () => { - const updatePlan = { actions: [{ action: 'update', kind: 'worker' }] }; + const updatePlan = { + actions: [{ action: 'update', key: 'api-worker', kind: 'worker' }], + }; expect( resolvePlatformRuntimeTokenToPreflight(updatePlan, { cloudflareApiToken: 'stale-checkpoint-token', @@ -309,13 +311,22 @@ describe('platform lifecycle management', () => { ).toBe('explicit-rotation-token'); expect( resolvePlatformRuntimeTokenToPreflight( - { actions: [{ action: 'create', kind: 'worker' }] }, + { actions: [{ action: 'create', key: 'api-worker', kind: 'worker' }] }, { cloudflareApiToken: 'recovery-token', workerSecretUpdates: {}, }, ), ).toBe('recovery-token'); + expect( + resolvePlatformRuntimeTokenToPreflight( + { actions: [{ action: 'create', key: 'email-gateway-worker', kind: 'worker' }] }, + { + cloudflareApiToken: 'stale-checkpoint-token', + workerSecretUpdates: {}, + }, + ), + ).toBe(''); }); it('requires explicit acknowledgement for a non-interactive uninstall', async () => { diff --git a/packages/void/test/unit/platform-plan.test.ts b/packages/void/test/unit/platform-plan.test.ts index 3adf718b0..e368150ac 100644 --- a/packages/void/test/unit/platform-plan.test.ts +++ b/packages/void/test/unit/platform-plan.test.ts @@ -80,6 +80,21 @@ function legacyInstallation(suffix = '0123456789ab') { } describe('platform installation planning', () => { + it.each(['install', 'upgrade'] as const)( + 'rejects incomplete shared email settings during %s', + async (mode) => { + const existing = mode === 'upgrade' ? legacyInstallation() : null; + for (const emailSettings of [ + { emailSharedZoneId: 'mail-zone-id' }, + { emailSenderDomain: 'mail.example.org' }, + ]) { + await expect( + createPlatformInstallPlan(client(), { ...input, ...emailSettings }, existing), + ).rejects.toThrow('VOID_EMAIL_SENDER_DOMAIN and VOID_EMAIL_SHARED_ZONE_ID together'); + } + }, + ); + it('persists the shared email zone separately from the application zone on resume', async () => { const configured = await createPlatformInstallPlan( client(), @@ -88,6 +103,7 @@ describe('platform installation planning', () => { ); expect(configured.deployment.emailSharedZoneId).toBe('mail-zone-id'); expect(configured.deployment.emailSenderDomain).toBe('mail.example.org'); + expect(configured.deployment.capabilities.email).toBe(true); const manifest = createPlatformInstallationManifest({ account: configured.account, deployment: configured.deployment, @@ -99,7 +115,36 @@ describe('platform installation planning', () => { const resumed = await createPlatformInstallPlan(client(), input, manifest); expect(resumed.deployment.emailSharedZoneId).toBe('mail-zone-id'); expect(resumed.deployment.emailSenderDomain).toBe('mail.example.org'); + expect(resumed.deployment.capabilities.email).toBe(true); expect(resumed.zone?.id).not.toBe('mail-zone-id'); + await expect( + createPlatformInstallPlan( + client(), + { ...input, emailSharedZoneId: 'different-zone' }, + manifest, + ), + ).rejects.toThrow('shared email zone is already recorded'); + }); + + it('canonicalizes a trailing-dot sender domain before fresh-install resume checks', async () => { + const configuredInput = { + ...input, + emailSharedZoneId: 'mail-zone-id', + emailSenderDomain: 'Mail.Example.Org.', + }; + const configured = await createPlatformInstallPlan(client(), configuredInput, null); + expect(configured.deployment.emailSenderDomain).toBe('mail.example.org'); + const manifest = createPlatformInstallationManifest({ + account: configured.account, + deployment: configured.deployment, + id: configured.installationId, + ownershipNonce: '0123456789abcdef0123456789abcdef', + platformVersion: '1.0.0', + createdAt: '2026-09-17T00:00:00.000Z', + }); + + const resumed = await createPlatformInstallPlan(client(), configuredInput, manifest); + expect(resumed.deployment.emailSenderDomain).toBe('mail.example.org'); }); it('adds a configured shared email zone to a previously unconfigured installation', async () => { @@ -119,6 +164,7 @@ describe('platform installation planning', () => { ); expect(upgraded.deployment.emailSharedZoneId).toBe('mail-zone-id'); expect(upgraded.deployment.emailSenderDomain).toBe('mail.example.org'); + expect(upgraded.deployment.capabilities.email).toBe(true); await expect( createPlatformInstallPlan( client(), @@ -135,6 +181,21 @@ describe('platform installation planning', () => { ).rejects.toThrow('already recorded'); }); + it('records shared email settings without enabling an older runtime', async () => { + const configured = await createPlatformInstallPlan( + client(), + { ...input, emailSharedZoneId: 'mail-zone-id', emailSenderDomain: 'mail.example.org' }, + null, + { includeEmailGateway: false }, + ); + expect(configured.deployment.emailSharedZoneId).toBe('mail-zone-id'); + expect(configured.deployment.emailSenderDomain).toBe('mail.example.org'); + expect(configured.deployment.capabilities.email).toBe(false); + expect(configured.actions).not.toContainEqual( + expect.objectContaining({ key: 'email-gateway-worker' }), + ); + }); + it('resumes the recorded namespaces using the real unfiltered KV API response', async () => { const initial = await createPlatformInstallPlan(client(), input, null); let manifest = createPlatformInstallationManifest({ diff --git a/platform/meta/design-docs/0078-email-cf-native.md b/platform/meta/design-docs/0078-email-cf-native.md index 74f87b97e..f7cdf7fae 100644 --- a/platform/meta/design-docs/0078-email-cf-native.md +++ b/platform/meta/design-docs/0078-email-cf-native.md @@ -267,6 +267,18 @@ outcome or stop for operator recovery. Repeat only an operation demonstrated to be idempotent with the same stored payload. A late response cannot overwrite a newer database generation. +For provider mutations whose outcome cannot always be proved by read-back +(`routing_enable`, `ingress_deploy`, `probe_route_enable`, `secret_put`, +`catchall_ensure`, `sending_onboard`, `catchall_detach`, and `ingress_delete`), +operator recovery requires the original execution to have ended, a minimum age +of 24 hours, an explicit `applied` or `not-applied` attestation, and an audit +reason. Preview and apply are fenced by operation, step, attempt, connection and +route generation, resource identity, and request digest. Applied records the +database postcondition without repeating the provider write; not-applied retries +only when the current runtime reproduces the stored identity and digest. For a +secret write, that identity includes the staged generation. Elapsed time alone +never permits replay. + Setup proceeds through: 1. Resolve the exact account and zone, check grant scope, inspect existing MX and @@ -367,6 +379,14 @@ failure leaves a retryable cleanup operation, including after project teardown. Removal never discards an unresolved cleanup record; its operation remains visible until the provider resources have been reconciled. +When project teardown leaves the final assignment disabled with a blocked system +cleanup, an administrator may provide a replacement scoped API token through +`void platform email domain-remove --token-stdin`. Verify that the replacement is +active and can read the same account and zone before committing it. Require the +project to be missing or deleting and no live sibling assignment; preserve the +connection manager, cleanup operation, and connection/route generations. This +does not authorize taking over a live project or retrying an uncertain write. + Recipient consent removal follows the same durability rule. Commit revocation and cleanup intent together, then delete an unreferenced Cloudflare destination outside the transaction. Fence registration against that immutable provider tag before @@ -446,6 +466,12 @@ flowchart TD ### Policy and atomic quotas +Provider submissions have a 30-second wait limit within a 60-second batch +budget. Expiry never proves a provider refusal: started submissions stay unknown, +and only reservations proven unstarted may be cancelled and refunded. Native +bindings may finish after the caller stops waiting; do not automatically retry +them. The zone relay also bounds its fetch and upload together to 60 seconds. + PostgreSQL is the authority for project identity, exact-domain ownership, verified destination consent, installation policy, suspension and quota reservations. KV may suggest a route or accelerate display, but cannot independently authorize @@ -500,6 +526,9 @@ that commit but before the actual call is conservatively unknown. A retry that i known safe is a new provider attempt with a fresh quota check and debit. Concurrent retries cannot consume one reservation twice. Account-level Cloudflare limits remain additional constraints, including when several projects share an account. +Hourly cleanup cancels and refunds reservations older than 15 minutes only while +they remain `reserved`; a delayed start fails if cleanup won, and +`attempt_started` is never resolved by age alone. ### Cache publication diff --git a/platform/meta/operations.md b/platform/meta/operations.md index 49fb46c6b..838c6d777 100644 --- a/platform/meta/operations.md +++ b/platform/meta/operations.md @@ -24,7 +24,7 @@ vp run check vp test run ``` -Void Cloud deploys the API after PostgreSQL migrations, then the proxy, tail, dispatch, and dashboard Workers. The API hosts the build scheduler and build-container Durable Objects. The optional dashboard uses the API for authentication and is deployed after the API it depends on. +Void Cloud deploys the API after PostgreSQL migrations, then the proxy, email gateway, tail, dispatch, and dashboard Workers. The API hosts the build scheduler and build-container Durable Objects. The optional dashboard uses the API for authentication and is deployed after the API it depends on. The `deploy` and `deploy:staging` scripts in `platform/package.json` target these existing hosted environments. Forks should use `void platform upgrade --runtime` as described in [source deployment](../../docs/guide/platform-development.md#source-build-ci). @@ -48,11 +48,11 @@ procedures in that owner's private runbook. ## Hosted Worker Maintenance -Void Cloud operators can inspect the platform's five Workers and their versions: +Void Cloud operators can inspect the platform's six Workers and their versions: ```sh void platform worker list -void platform worker show +void platform worker show void platform worker rollback void platform worker rollback-all void platform worker events [batch-id] @@ -73,7 +73,7 @@ Keep these values recoverable through the deployment owner's secret manager: | Configuration | Purpose | | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `CF_API_TOKEN`, `CF_ACCOUNT_ID`, `CF_ZONE_ID` | Runtime Cloudflare account and application-zone access | -| `JWT_SECRET` | API and proxy authentication | +| `JWT_SECRET` | API, proxy, and email gateway authentication | | `PROJECT_SECRET_KEYS_JSON`, `PROJECT_SECRET_ACTIVE_KEY_VERSION` | Encryption of project secrets | | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | GitHub sign-in OAuth application | | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | Google sign-in OAuth client | @@ -108,13 +108,31 @@ The dedicated email gateway receives inbound mail and dispatches bounded request For a managed installation, provide `VOID_EMAIL_SENDER_DOMAIN` and `VOID_EMAIL_SHARED_ZONE_ID` during installation or upgrade. These values are recorded in the installation; routine upgrades preserve them. The installer supplies the platform account and gateway identity separately from the application zone. -For repository deployments, configure the equivalent Worker values before enabling email: +For repository deployments, add the equivalent values to the selected `env.production.vars` or `env.staging.vars` blocks in the Workers' Wrangler configuration before enabling email. Do not rely on dashboard-only plain-text variables; the checked-in Wrangler files remain the deployment source of truth. - API, proxy, and email gateway: the same `EMAIL_SENDER_DOMAIN`. - API and email gateway: `EMAIL_SHARED_ACCOUNT_ID`, `EMAIL_SHARED_ZONE_ID`, and `EMAIL_SHARED_INGRESS_NAME`, identifying the platform account, mail zone, and dedicated gateway Worker. - API: `EMAIL_GATEWAY_ORIGIN`, the gateway's HTTPS origin reachable from customer ingress Workers. - API, proxy, and email gateway: the same installation `JWT_SECRET`; the API retains the scoped runtime token and project-encryption keys. +Install the gateway's copy of the shared JWT as a Wrangler secret in each environment before deploying it: + +```sh +cd platform/packages/email-gateway +wrangler secret put JWT_SECRET --env production +wrangler secret put JWT_SECRET --env staging +``` + +For the first email rollout, configure and deploy the proxy and email gateway before adding the API's shared-email values. Verify both Workers, then add the API values and deploy the API so scheduled reconciliation cannot direct inbound mail at an unavailable gateway. From the repository root, the production sequence is: + +```sh +vp run --filter @voidcloud/platform deploy:proxy +vp run --filter @voidcloud/platform deploy:email-gateway +vp run --filter @voidcloud/platform deploy:api +``` + +Use the corresponding `deploy:staging:*` commands for staging. After email is enabled and all three Workers exist, the normal platform deployment command can update them. + The API's scheduled reconciliation creates the shared connection and reserved shared-domain route only when the complete identity is configured. Confirm the resulting operation and inbound readiness before directing traffic to the gateway. Provision routing and Sending independently: a provider permission or plan refusal must remain visible in the corresponding readiness state. Sending to arbitrary recipients requires Cloudflare Email Sending onboarding and its supported plan. Customer connections deploy one ingress Worker in the customer's account and zone. Shared and custom domain assignments can coexist on one zone. Setup proves the deployed ingress secret and the gateway's acceptance before changing the owned catch-all. Inspect foreign rules and preserve them; never repoint a catch-all simply because its Worker name resembles Void's. @@ -131,6 +149,13 @@ records. The new reconciler does not migrate old `email_domains` records. Inspect all three readiness states and the operation ID with `void email domain status `. Use `sync` to reconcile recoverable steps and `rotate-secret` for explicit ingress-secret rotation. An uncertain provider write remains blocked until its outcome can be proved; neither a timeout nor a missing cache entry authorizes another write. Never erase the operation to force a retry. +If read-back cannot prove whether a routing, Worker, secret, catch-all, or Sending +mutation applied, confirm that the original execution ended and wait at least 24 +hours before using `void platform email operation-resolve`. Its preview identifies +the exact stored mutation. Record `applied` to continue without replaying it, or +`not-applied` to retry only that fenced intent. Keep the same platform version and +preserve staged secret state until the operation completes. + PostgreSQL is authoritative for consent, policy, suspension, and recipient-attempt quotas. Cache publication retries independently. `void email logs` exposes receipt and action metadata: provider acceptance is not proof of delivery, and an unknown result must not be retried with a new idempotency key. Removing one domain or project must preserve sibling routes and unresolved cleanup records. Before production enablement, complete the [email design's acceptance gates](./design-docs/0078-email-cf-native.md#acceptance-gates), including live Cloudflare routing, forwarding/reply, scoped-token, rotation, and failure-recovery checks. diff --git a/platform/packages/api/README.md b/platform/packages/api/README.md index cb2cee499..c43642cf9 100644 --- a/platform/packages/api/README.md +++ b/platform/packages/api/README.md @@ -146,6 +146,11 @@ partial external failures report completed work instead of silently retrying. Requests are bounded to 32 KiB, list pages to 100 rows, and responses disable caching. +`GET /operator/v1/email/projects/:project/logs` provides administrator access to +retained receipt and recipient outcomes, with `page` and `limit` pagination. +Accept a current project ID or slug; deleted projects remain inspectable by ID +until ledger retention expires. Responses exclude message content and credentials. + Managed Sandbox disablement uses `void platform system sandbox-drain`. The preview inventories bounded pages of deployment manifests and container resources without writing. Apply closes the activation gate, cancels active @@ -178,7 +183,7 @@ recovery or promotion bypass. - `/admin/builds/:id` — build detail page (live log panel for container builds; GitHub link for `github_actions`) - `/admin/builds/:id/logs?since=N` — build-log poll endpoint backing the live tail; container builds front the `BuildManager`/`BuildManagerLarge` DO's read-only `GET /logs?since=N` (routed by `instance_type` via `buildManagerNamespace`), `github_actions` builds return the external `logs_url` - `/admin/deployments` -- `/admin/email/:projectId` — per-project email usage, caps, outbound kill switch, and destination list +- `/admin/email/:projectId` — per-project email usage, caps, inbound/outbound suspension, and destination list - `/admin/signup-control` - `/admin/platform` @@ -237,7 +242,7 @@ Connect a repo through a GitHub App; a `git push` then builds and deploys automa ## Email -Projects send and receive mail through `void/email`. The API owns consent and quota policy; the proxy worker (`packages/proxy/src/email.ts`) owns the send/receive path and every counter. +Projects send and receive mail through `void/email`. The API authorizes routing, consent, suspension, and quota reservations in PostgreSQL. The proxy submits outbound mail, and the dedicated email gateway authenticates inbound zone traffic and dispatches it to the active project worker. ### Sender identity is per-environment @@ -252,31 +257,21 @@ The runtime defaults `from` from those two bindings and refuses to send when eit ### Who a project may send to -`email_destinations` in Postgres is the source of truth: one row per (project, recipient), `pending` until the recipient consents. `email-allowlist:` in `ROUTING` KV is a denormalized read-cache of the **verified** rows, which is what the proxy enforces on every send. Every destination mutation re-syncs that key — the owner-facing add/revoke routes, the admin revoke, the project-create auto-add of the owner's own address, and the recipient's click on a platform confirmation link; an empty list deletes it. **Nothing syncs it on deploy.** - -Those writes are best-effort, so one swallowed KV failure after Postgres already committed `verified` would otherwise be unrecoverable — the proxy reads a missing key as deny-all, and the owner sees a `verified` destination whose every send is rejected as unverified. `GET /projects/:id/email/destinations` is the repair: it compares the mirror against the verified rows and rewrites it only when they differ (one KV read per listing; never a write on every listing). Same read-compare-write self-heal shape as the hourly `email-slug:` backfill in `index.ts`. - -Cloudflare Email Routing destination addresses are account-level, so a row is only deleted upstream when no other project still references the same address. +`email_destinations` records consent per project and recipient. Admission reads verified destinations, current ownership, and installation policy from PostgreSQL. The default shared-sender policy requires verified destinations; operators may allow exact external domains or all external recipients. Destinations on the platform’s shared mail domain always require project consent. Custom senders may send externally when their domain and credential are ready, subject to transport capability, suspension, and quotas. -### Quotas and counters +KV contains routing and policy hints; it cannot authorize a send. Cloudflare destination addresses are account-level, so upstream cleanup occurs only after the last project reference is removed. -All of it lives in `ROUTING` KV, written by the proxy and read (and overridden) by the admin page: +### Quotas and outcomes -| Key | Meaning | -| ---------------------------------- | ----------------------------------------------------------------------- | -| `email-sent::` | Outbound count for the UTC month; expires shortly after the month ends | -| `email-recv::` | Inbound count for the UTC month | -| `email-suspended:` | Presence stops mail both ways: outbound sends fail, inbound is rejected | -| `email-limit:` | Monthly outbound override; absent means the platform default (200) | -| `email-burst-limit:` | Per-minute override; absent means the platform default (10) | +`emailProjectControls` holds suspension and per-project limits. Admission atomically records a deduplicated action, reserves quota in `emailMonthlyUsage`, and creates per-recipient states in `emailActionRecipients`. The defaults are 200 recipient attempts per UTC month and 10 per minute. Direct sends and inbound actions use the same ledger. -The defaults live in the proxy and are mirrored in `admin/routes/email.tsx` so the page can label a cap `default` or `override`. Nothing at build time catches a drift between the two — change them together. +Only reservations that never started can be cancelled and refunded. Started or uncertain submissions retain their quota and are never automatically replayed. Suspension blocks new attempts; already-started submissions may finish. `emailReceipts` records inbound processing, and unresolved attempt records preserve the removal fence after detailed logs expire. ### Operator page -`/admin/email/:projectId` is the whole control plane in one page: this month's outbound/inbound counts against the effective caps, the resolved sender address, the suspend/unsuspend kill switch, monthly and burst overrides (submit a blank value to drop an override back to the default), a counter reset, and the destination list with per-row revoke. +`/admin/email/:projectId` displays current-month recipient attempts and inbound receipts, effective limits, sender identity, verified destinations, and custom-domain readiness. Operators can suspend email, change monthly or burst limits, revoke destination consent, and manage domain operations. A blank limit restores the default. -The counter reset is guarded server-side — the operator types the project slug — so it cannot be triggered by a POST that never rendered the page. There is deliberately no operator-side "add destination": consent belongs to the recipient, and the owner-facing `POST /projects/:id/email/destinations` is the only path that asks for it. +Destinations are added through the owner-facing `POST /projects/:id/email/destinations` consent flow. Operators cannot consent on a recipient’s behalf. Incomplete provider operations retain their operation ID and outcome for reconciliation or audited recovery; the page must not report them as completed. Every admin write is additionally same-origin checked in `admin/middleware/auth.ts` before authentication runs; a `POST` whose `Origin` (or, failing that, `Referer`) does not match the request host is rejected with `403`, as is one that carries neither. @@ -318,7 +313,7 @@ Notable sections: - project and deployment inspection - deployment log viewing - per-project Builds section (ongoing build highlighted) plus a build detail page with a client-side polling live-log tail for container builds (mirrors the deployment live-tail; not a WebSocket), or a GitHub Actions link for `github_actions` builds. The tail polls `GET /admin/builds/:id/logs?since=N`, which fronts the `BuildManager`/`BuildManagerLarge` DO's read-only `GET /logs?since=N` (DO chosen by `instance_type` via `buildManagerNamespace`). -- per-project email page (linked from the project detail view): usage, caps, outbound kill switch, destinations +- per-project email page (linked from the project detail view): usage, caps, inbound/outbound suspension, destinations - signup restrictions and allowlists - platform worker version history and orchestrated rollback diff --git a/platform/packages/api/drizzle/0047_email_gateway.sql b/platform/packages/api/drizzle/0047_email_gateway.sql index e5d9305d2..1b058b42e 100644 --- a/platform/packages/api/drizzle/0047_email_gateway.sql +++ b/platform/packages/api/drizzle/0047_email_gateway.sql @@ -5,8 +5,8 @@ CREATE TABLE "email_cache_outbox" ( "resource_id" text NOT NULL, "version" integer NOT NULL, "payload" jsonb, - "published_at" timestamp, - "created_at" timestamp DEFAULT now() NOT NULL + "published_at" timestamp with time zone, + "created_at" timestamp with time zone DEFAULT now() NOT NULL ); --> statement-breakpoint CREATE TABLE "email_credentials" ( @@ -21,11 +21,11 @@ CREATE TABLE "email_credentials" ( "iv" text, "key_version" text, "token_id" text, - "expires_on" timestamp, + "expires_on" timestamp with time zone, "generation" integer DEFAULT 1 NOT NULL, "status" text DEFAULT 'healthy' NOT NULL, - "created_at" timestamp DEFAULT now() NOT NULL, - "updated_at" timestamp DEFAULT now() NOT NULL, + "created_at" timestamp with time zone DEFAULT now() NOT NULL, + "updated_at" timestamp with time zone DEFAULT now() NOT NULL, CONSTRAINT "email_credentials_material_check" CHECK (("email_credentials"."kind" = 'platform' AND "email_credentials"."ciphertext" IS NULL AND "email_credentials"."iv" IS NULL AND "email_credentials"."key_version" IS NULL) OR ("email_credentials"."kind" = 'api_token' AND "email_credentials"."ciphertext" IS NOT NULL AND "email_credentials"."iv" IS NOT NULL AND "email_credentials"."key_version" IS NOT NULL)) ); --> statement-breakpoint @@ -40,13 +40,13 @@ CREATE TABLE "email_domain_routes" ( "desired_state" text DEFAULT 'active' NOT NULL, "inbound_status" text DEFAULT 'pending' NOT NULL, "inbound_reason" text, - "inbound_observed_at" timestamp, + "inbound_observed_at" timestamp with time zone, "outbound_status" text DEFAULT 'pending' NOT NULL, "outbound_reason" text, - "outbound_observed_at" timestamp, + "outbound_observed_at" timestamp with time zone, "desired_generation" integer DEFAULT 1 NOT NULL, - "created_at" timestamp DEFAULT now() NOT NULL, - "updated_at" timestamp DEFAULT now() NOT NULL, + "created_at" timestamp with time zone DEFAULT now() NOT NULL, + "updated_at" timestamp with time zone DEFAULT now() NOT NULL, CONSTRAINT "email_domain_routes_assignment_check" CHECK (("email_domain_routes"."addressing" = 'custom' AND "email_domain_routes"."project_id" IS NOT NULL) OR ("email_domain_routes"."addressing" = 'shared' AND "email_domain_routes"."project_id" IS NULL)) ); --> statement-breakpoint @@ -62,8 +62,8 @@ CREATE TABLE "email_operation_steps" ( "outcome" jsonb, "failure_code" text, "failure_detail" text, - "started_at" timestamp, - "finished_at" timestamp + "started_at" timestamp with time zone, + "finished_at" timestamp with time zone ); --> statement-breakpoint CREATE TABLE "email_operations" ( @@ -71,6 +71,7 @@ CREATE TABLE "email_operations" ( "installation_id" text NOT NULL, "connection_id" text NOT NULL, "route_id" text, + "route_generation" integer, "actor_kind" text NOT NULL, "actor_user_id" text, "actor_scope" text NOT NULL, @@ -82,8 +83,8 @@ CREATE TABLE "email_operations" ( "current_step" text, "failure_code" text, "failure_detail" text, - "created_at" timestamp DEFAULT now() NOT NULL, - "updated_at" timestamp DEFAULT now() NOT NULL + "created_at" timestamp with time zone DEFAULT now() NOT NULL, + "updated_at" timestamp with time zone DEFAULT now() NOT NULL ); --> statement-breakpoint CREATE TABLE "email_zone_connections" ( @@ -107,15 +108,15 @@ CREATE TABLE "email_zone_connections" ( "staged_secret_iv" text, "staged_secret_key_version" text, "previous_secret_hash" text, - "previous_secret_until" timestamp, + "previous_secret_until" timestamp with time zone, "inbound_status" text DEFAULT 'pending' NOT NULL, "inbound_reason" text, - "inbound_observed_at" timestamp, + "inbound_observed_at" timestamp with time zone, "management_status" text DEFAULT 'probe_failed' NOT NULL, "management_reason" text, - "management_observed_at" timestamp, - "created_at" timestamp DEFAULT now() NOT NULL, - "updated_at" timestamp DEFAULT now() NOT NULL, + "management_observed_at" timestamp with time zone, + "created_at" timestamp with time zone DEFAULT now() NOT NULL, + "updated_at" timestamp with time zone DEFAULT now() NOT NULL, CONSTRAINT "email_zone_connections_manager_check" CHECK (("email_zone_connections"."managed_by" = 'owner' AND "email_zone_connections"."manager_user_id" IS NOT NULL) OR ("email_zone_connections"."managed_by" = 'admin')) ); --> statement-breakpoint @@ -153,8 +154,10 @@ CREATE TABLE "email_monthly_usage" ( "project_id" text NOT NULL, "month" text NOT NULL, "recipient_attempts" integer DEFAULT 0 NOT NULL, + "inbound_receipts" integer DEFAULT 0 NOT NULL, CONSTRAINT "email_monthly_usage_project_month_uq" UNIQUE("project_id","month"), - CONSTRAINT "email_monthly_usage_nonnegative_check" CHECK ("email_monthly_usage"."recipient_attempts" >= 0) + CONSTRAINT "email_monthly_usage_nonnegative_check" CHECK ("email_monthly_usage"."recipient_attempts" >= 0), + CONSTRAINT "email_monthly_usage_inbound_nonnegative_check" CHECK ("email_monthly_usage"."inbound_receipts" >= 0) ); --> statement-breakpoint CREATE TABLE "email_project_controls" ( @@ -202,6 +205,7 @@ CREATE UNIQUE INDEX "email_zone_connections_zone_uq" ON "email_zone_connections" CREATE UNIQUE INDEX "email_zone_connections_ingress_uq" ON "email_zone_connections" USING btree ("account_id","ingress_worker_name");--> statement-breakpoint CREATE INDEX "email_zone_connections_manager_idx" ON "email_zone_connections" USING btree ("manager_user_id");--> statement-breakpoint CREATE INDEX "idx_email_action_recipients_project_reserved" ON "email_action_recipients" USING btree ("project_id","reserved_at");--> statement-breakpoint +CREATE INDEX "idx_email_action_recipients_expiring" ON "email_action_recipients" USING btree ("reserved_at") WHERE "email_action_recipients"."state" = 'reserved';--> statement-breakpoint CREATE INDEX "idx_email_actions_project_created" ON "email_actions" USING btree ("project_id","created_at");--> statement-breakpoint CREATE INDEX "idx_email_receipts_project_created" ON "email_receipts" USING btree ("project_id","created_at");--> statement-breakpoint CREATE INDEX "idx_email_unresolved_attempts_project" ON "email_unresolved_attempts" USING btree ("project_id");--> statement-breakpoint diff --git a/platform/packages/api/drizzle/meta/0047_snapshot.json b/platform/packages/api/drizzle/meta/0047_snapshot.json index 424a8733a..38afebcbd 100644 --- a/platform/packages/api/drizzle/meta/0047_snapshot.json +++ b/platform/packages/api/drizzle/meta/0047_snapshot.json @@ -3844,13 +3844,13 @@ }, "published_at": { "name": "published_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, "created_at": { "name": "created_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" @@ -3985,7 +3985,7 @@ }, "expires_on": { "name": "expires_on", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, @@ -4005,14 +4005,14 @@ }, "created_at": { "name": "created_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" }, "updated_at": { "name": "updated_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" @@ -4127,7 +4127,7 @@ }, "inbound_observed_at": { "name": "inbound_observed_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, @@ -4146,7 +4146,7 @@ }, "outbound_observed_at": { "name": "outbound_observed_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, @@ -4159,14 +4159,14 @@ }, "created_at": { "name": "created_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" }, "updated_at": { "name": "updated_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" @@ -4315,13 +4315,13 @@ }, "started_at": { "name": "started_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, "finished_at": { "name": "finished_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false } @@ -4394,6 +4394,12 @@ "primaryKey": false, "notNull": false }, + "route_generation": { + "name": "route_generation", + "type": "integer", + "primaryKey": false, + "notNull": false + }, "actor_kind": { "name": "actor_kind", "type": "text", @@ -4463,14 +4469,14 @@ }, "created_at": { "name": "created_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" }, "updated_at": { "name": "updated_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" @@ -4695,7 +4701,7 @@ }, "previous_secret_until": { "name": "previous_secret_until", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, @@ -4714,7 +4720,7 @@ }, "inbound_observed_at": { "name": "inbound_observed_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, @@ -4733,20 +4739,20 @@ }, "management_observed_at": { "name": "management_observed_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": false }, "created_at": { "name": "created_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" }, "updated_at": { "name": "updated_at", - "type": "timestamp", + "type": "timestamp with time zone", "primaryKey": false, "notNull": true, "default": "now()" @@ -4915,6 +4921,22 @@ "concurrently": false, "method": "btree", "with": {} + }, + "idx_email_action_recipients_expiring": { + "name": "idx_email_action_recipients_expiring", + "columns": [ + { + "expression": "reserved_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "where": "\"email_action_recipients\".\"state\" = 'reserved'", + "concurrently": false, + "method": "btree", + "with": {} } }, "foreignKeys": { @@ -5084,6 +5106,13 @@ "primaryKey": false, "notNull": true, "default": 0 + }, + "inbound_receipts": { + "name": "inbound_receipts", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 } }, "indexes": {}, @@ -5101,6 +5130,10 @@ "email_monthly_usage_nonnegative_check": { "name": "email_monthly_usage_nonnegative_check", "value": "\"email_monthly_usage\".\"recipient_attempts\" >= 0" + }, + "email_monthly_usage_inbound_nonnegative_check": { + "name": "email_monthly_usage_inbound_nonnegative_check", + "value": "\"email_monthly_usage\".\"inbound_receipts\" >= 0" } }, "isRLSEnabled": false diff --git a/platform/packages/api/src/admin/routes/email.tsx b/platform/packages/api/src/admin/routes/email.tsx index eae0dd23e..bf33e0136 100644 --- a/platform/packages/api/src/admin/routes/email.tsx +++ b/platform/packages/api/src/admin/routes/email.tsx @@ -1,12 +1,8 @@ -import { asc, desc, eq, gte, inArray, sql } from 'drizzle-orm'; +import { asc, desc, eq, inArray, sql } from 'drizzle-orm'; import { Hono, type Context } from 'hono'; import { getPlatformCapabilities } from '../../capabilities.ts'; import { deleteEmailDestination, getEmailDestinationsByProjectId, getProject } from '../../db.ts'; -import { - emailMonthlyUsage, - emailProjectControls, - emailReceipts, -} from '../../email/admission-schema.ts'; +import { emailMonthlyUsage, emailProjectControls } from '../../email/admission-schema.ts'; import { setProjectEmailLimits, setProjectEmailSuspended } from '../../email/admission.ts'; import { emailDomainRoutes, @@ -50,18 +46,41 @@ app.use('*', async (context, next) => { await next(); }); -/** Operator email settings and project usage from the email ledger. */ -const recvKey = (projectId: string, month: string) => `email-recv:${projectId}:${month}`; - /** The admin layout has no utility classes, so secondary text is inline. */ const META = 'font-size: 0.8rem; color: #666'; +type AdminEmailOperationOutcome = { + operationId?: string; + operationStatus?: typeof emailOperations.$inferSelect.status | null; + error?: string | null; +}; + +async function incompleteEmailOperationResponse( + context: Context, + projectId: string, + label: string, + outcome: AdminEmailOperationOutcome, +): Promise { + const status = outcome.operationStatus ?? 'pending'; + return context.html( + +

+ {label} {status} +

+

{outcome.error ?? 'The operation has not completed. Check its status before retrying.'}

+

+ Operation ID: {outcome.operationId ?? 'unavailable'} +

+ Back to email settings +
, + status === 'blocked' || status === 'unknown' ? 409 : 202, + ); +} + // GET /email/ — installation-wide recipient policy and domain management app.get('/', async (context) => { const db = context.get('db'); - // Every read surface republishes a drifted mirror, this page included: - // an administrator who sees `verified` here must be seeing what the - // proxy enforces. + // Refresh the best-effort display mirror before showing the authoritative SQL policy. await repairEmailRecipientPolicyMirror(db, context.env.ROUTING); const [policy, management] = await Promise.all([ getEmailRecipientPolicy(db), @@ -115,22 +134,17 @@ app.get('/:projectId', async (context) => { } const month = monthBucket(); - const monthStart = `${month}-01T00:00:00.000Z`; - const [sentRows, receivedRows, controls, destinations, domainRows] = await Promise.all([ + const [usageRows, controls, destinations, domainRows] = await Promise.all([ context .get('db') - .select({ count: emailMonthlyUsage.recipient_attempts }) + .select({ + attempts: emailMonthlyUsage.recipient_attempts, + received: emailMonthlyUsage.inbound_receipts, + }) .from(emailMonthlyUsage) .where( sql`${emailMonthlyUsage.project_id} = ${projectId} AND ${emailMonthlyUsage.month} = ${month}`, ), - context - .get('db') - .select({ count: sql`count(*)::int` }) - .from(emailReceipts) - .where( - sql`${emailReceipts.project_id} = ${projectId} AND ${emailReceipts.created_at} >= ${monthStart}::timestamptz`, - ), context .get('db') .select() @@ -149,8 +163,8 @@ app.get('/:projectId', async (context) => { .where(eq(emailDomainRoutes.project_id, projectId)) .orderBy(asc(emailDomainRoutes.created_at)), ]); - const sent = sentRows[0]?.count ?? 0; - const received = receivedRows[0]?.count ?? 0; + const attempts = usageRows[0]?.attempts ?? 0; + const received = usageRows[0]?.received ?? 0; const latestOperations = domainRows.length ? await context .get('db') @@ -237,9 +251,9 @@ app.get('/:projectId', async (context) => { - + @@ -269,9 +283,9 @@ app.get('/:projectId', async (context) => { {isSuspended ? 'Unsuspend email' : 'Suspend email'} {' '} - Suspending stops mail in both directions immediately. Outbound sends fail, and inbound - messages are rejected with a permanent SMTP error, so the sender gets a bounce rather than - a silent drop. There is no per-direction switch. + Suspending stops new outbound attempts and rejects new inbound messages with a permanent + SMTP error. Outbound submissions that already started may still finish. There is no + per-direction switch. @@ -498,35 +512,14 @@ app.post('/:projectId/domains/add', async (context) => { typeof json.error === 'string' ? json.error : 'Adding the email domain failed.', ); } - const row = (await res.json()) as { - status?: string; - error?: string; - setup_state?: { failed_step?: string }; - }; - if ( - row.status === 'failed' || - row.status === 'token_revoked' || - row.status === 'token_expired' - ) { - const message = - row.error ?? - (row.setup_state?.failed_step - ? `Setup failed at step "${row.setup_state.failed_step}".` - : 'The email domain setup did not finish.'); + const outcome = (await res.json()) as AdminEmailOperationOutcome; + if (outcome.operationStatus !== 'completed') { return { - response: await context.html( - -

Adding {domain} did not finish

-

{message}

-

- Fix the step named above, then add the domain again — adding again retries it; rules - stay. -

-

- ← Back to project email -

-
, - 502, + response: await incompleteEmailOperationResponse( + context, + projectId, + `Adding ${domain}`, + outcome, ), succeeded: false, }; @@ -545,14 +538,18 @@ app.post('/:projectId/suspend', async (context) => { } const body = await context.req.parseBody(); const desired = body.state; - if (desired === 'suspended') { - await setProjectEmailSuspended(context.get('db'), projectId, true); - } else if (desired === 'active') { - await setProjectEmailSuspended(context.get('db'), projectId, false); - } else { + if (desired !== 'suspended' && desired !== 'active') { return context.html('

Invalid state

Expected "suspended" or "active".

', 400); } - return context.redirect(`/admin/email/${projectId}`); + const suspended = desired === 'suspended'; + return executeAuditedMutation( + context, + operatorAuditIntent(`email/projects/${projectId}/suspend`, { suspended }), + async () => { + await setProjectEmailSuspended(context.get('db'), projectId, suspended); + return { response: context.redirect(`/admin/email/${projectId}`), succeeded: true }; + }, + ); }); // POST /email/:projectId/limit — set (or clear) the monthly outbound override @@ -574,15 +571,21 @@ app.post('/:projectId/destinations/:destId/delete', async (context) => { if (!destination) { return context.html('

Destination not found

', 404); } - const cleanupTag = await deleteEmailDestination(context.get('db'), destination.id); - if (cleanupTag) { - await runEmailDestinationCleanup( - context.get('db'), - { accountId: context.env.CF_ACCOUNT_ID, apiToken: context.env.CF_API_TOKEN }, - cleanupTag, - ); - } - return context.redirect(`/admin/email/${projectId}`); + return executeAuditedMutation( + context, + operatorAuditIntent(`email/projects/${projectId}/destinations/${destinationId}/remove`), + async () => { + const cleanupTag = await deleteEmailDestination(context.get('db'), destination.id); + if (cleanupTag) { + await runEmailDestinationCleanup( + context.get('db'), + { accountId: context.env.CF_ACCOUNT_ID, apiToken: context.env.CF_API_TOKEN }, + cleanupTag, + ); + } + return { response: context.redirect(`/admin/email/${projectId}`), succeeded: true }; + }, + ); }); // An administrator removes one exact assignment through the same durable @@ -597,37 +600,36 @@ app.post('/:projectId/domains/:domain/revoke', async (context) => { if (body.confirm !== project.slug) { return context.html('

Not confirmed

', 400); } - const result = await removeEmailDomainForProject( + const domain = context.req.param('domain'); + return executeAuditedMutation( context, - project, - context.req.param('domain'), - 'admin', + operatorAuditIntent(`email/domains/${domain}/remove`, { force: false }), + async () => { + const result = await removeEmailDomainForProject(context, project, domain, 'admin'); + if (!result.ok) { + return { + response: await context.html( + '

Email domain removal failed

', + result.status as 400, + ), + succeeded: false, + }; + } + const outcome = (await result.json()) as AdminEmailOperationOutcome; + if (outcome.operationStatus !== 'completed') { + return { + response: await incompleteEmailOperationResponse( + context, + projectId, + 'Email domain removal', + outcome, + ), + succeeded: false, + }; + } + return { response: context.redirect(`/admin/email/${projectId}`), succeeded: true }; + }, ); - if (!result.ok) { - return context.html('

Email domain removal failed

', result.status as 400); - } - const outcome = (await result.json()) as { - operationId?: string; - operationStatus?: string; - error?: string; - }; - if (outcome.operationStatus !== 'completed') { - return context.html( - -

Email domain removal {outcome.operationStatus ?? 'pending'}

-

- {outcome.error ?? - 'The operation has not completed. Check the domain status before retrying.'} -

-

- Operation ID: {outcome.operationId ?? 'unavailable'} -

- Back to email settings -
, - outcome.operationStatus === 'blocked' || outcome.operationStatus === 'unknown' ? 409 : 202, - ); - } - return context.redirect(`/admin/email/${projectId}`); }); app.post('/:projectId/domains/:domain/rotate-secret', async (context) => { @@ -636,37 +638,36 @@ app.post('/:projectId/domains/:domain/rotate-secret', async (context) => { if (!project) { return context.html('

Project not found

', 404); } - const result = await rotateEmailIngressSecretForProject( + const domain = context.req.param('domain'); + return executeAuditedMutation( context, - project, - context.req.param('domain'), - 'admin', + operatorAuditIntent(`email/domains/${domain}/rotate-secret`), + async () => { + const result = await rotateEmailIngressSecretForProject(context, project, domain, 'admin'); + if (!result.ok) { + return { + response: await context.html( + '

Email ingress rotation failed

', + result.status as 400, + ), + succeeded: false, + }; + } + const outcome = (await result.json()) as AdminEmailOperationOutcome; + if (outcome.operationStatus !== 'completed') { + return { + response: await incompleteEmailOperationResponse( + context, + projectId, + 'Email ingress rotation', + outcome, + ), + succeeded: false, + }; + } + return { response: context.redirect(`/admin/email/${projectId}`), succeeded: true }; + }, ); - if (!result.ok) { - return context.html('

Email ingress rotation failed

', result.status as 400); - } - const outcome = (await result.json()) as { - operationId?: string; - operationStatus?: string; - error?: string; - }; - if (outcome.operationStatus !== 'completed') { - return context.html( - -

Email ingress rotation {outcome.operationStatus ?? 'pending'}

-

- {outcome.error ?? - 'The operation has not completed. Check the domain status before retrying.'} -

-

- Operation ID: {outcome.operationId ?? 'unavailable'} -

- Back to email settings -
, - outcome.operationStatus === 'blocked' || outcome.operationStatus === 'unknown' ? 409 : 202, - ); - } - return context.redirect(`/admin/email/${projectId}`); }); /** @@ -686,16 +687,20 @@ async function setLimit( const body = await context.req.parseBody(); const submitted = body[field]; const raw = typeof submitted === 'string' ? submitted.trim() : ''; - if (raw === '') { - await setProjectEmailLimits(context.get('db'), projectId, { [kind]: null }); - return context.redirect(`/admin/email/${projectId}`); - } - const limit = parseEmailLimitInput(raw); + const limit = raw === '' ? null : parseEmailLimitInput(raw); if (limit === undefined) { return context.html('

Invalid limit

Expected a positive integer, or blank.

', 400); } - await setProjectEmailLimits(context.get('db'), projectId, { [kind]: limit }); - return context.redirect(`/admin/email/${projectId}`); + return executeAuditedMutation( + context, + operatorAuditIntent(`email/projects/${projectId}/limit`, { + [kind]: limit === null ? 'default' : String(limit), + }), + async () => { + await setProjectEmailLimits(context.get('db'), projectId, { [kind]: limit }); + return { response: context.redirect(`/admin/email/${projectId}`), succeeded: true }; + }, + ); } /** Domain readiness uses the shared status palette. */ diff --git a/platform/packages/api/src/email/admission-schema.ts b/platform/packages/api/src/email/admission-schema.ts index 7d969a99c..0bdb84f83 100644 --- a/platform/packages/api/src/email/admission-schema.ts +++ b/platform/packages/api/src/email/admission-schema.ts @@ -28,10 +28,12 @@ export const emailMonthlyUsage = pgTable( project_id: text('project_id').notNull(), month: text('month').notNull(), recipient_attempts: integer('recipient_attempts').notNull().default(0), + inbound_receipts: integer('inbound_receipts').notNull().default(0), }, (table) => [ unique('email_monthly_usage_project_month_uq').on(table.project_id, table.month), check('email_monthly_usage_nonnegative_check', sql`${table.recipient_attempts} >= 0`), + check('email_monthly_usage_inbound_nonnegative_check', sql`${table.inbound_receipts} >= 0`), ], ); @@ -102,6 +104,9 @@ export const emailActionRecipients = pgTable( (table) => [ unique('email_action_recipients_action_recipient_uq').on(table.action_id, table.recipient), index('idx_email_action_recipients_project_reserved').on(table.project_id, table.reserved_at), + index('idx_email_action_recipients_expiring') + .on(table.reserved_at) + .where(sql`${table.state} = 'reserved'`), check( 'email_action_recipients_state_check', sql`${table.state} IN ('rejected', 'reserved', 'attempt_started', 'provider_accepted', 'failed', 'outcome_unknown', 'cancelled')`, diff --git a/platform/packages/api/src/email/admission.ts b/platform/packages/api/src/email/admission.ts index 835386fb3..65a155eb4 100644 --- a/platform/packages/api/src/email/admission.ts +++ b/platform/packages/api/src/email/admission.ts @@ -1,4 +1,4 @@ -import { and, asc, count, desc, eq, gte, ne, sql } from 'drizzle-orm'; +import { and, asc, count, eq, gte, ne, sql } from 'drizzle-orm'; import type { Db, DbOrTx, Tx } from '../db.ts'; import { generateId } from '../id.ts'; import { isReservedEmailSlug } from '../reserved-slugs.ts'; @@ -11,8 +11,8 @@ import { emailReceipts, emailUnresolvedAttempts, } from './admission-schema.ts'; -import { emailCredentials, emailDomainRoutes } from './connection-schema.ts'; -import { resolveEmailDomain } from './connection-service.ts'; +import { emailCredentials, emailDomainRoutes, emailZoneConnections } from './connection-schema.ts'; +import { isEmailCredentialExpired, resolveEmailDomain } from './connection-service.ts'; import { getEmailRecipientPolicy } from './settings.ts'; export type EmailActionState = @@ -49,6 +49,15 @@ export type EmailAdmissionInput = { sharedSenderDomain: string; }; +export type EmailReceiptRouteFence = { + routeId: string; + routeGeneration: number; + connectionId: string; + addressing: 'shared' | 'custom'; + domain: string; + projectSlug: string; +}; + export class EmailAdmissionError extends Error { constructor( readonly code: 'CONFLICT' | 'INVALID_REQUEST' | 'NOT_FOUND' | 'INVALID_STATE', @@ -235,6 +244,24 @@ function monthStart(now: Date): string { return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1)).toISOString(); } +function utcMonth(timestamp: string): string { + return new Date(timestamp).toISOString().slice(0, 7); +} + +async function incrementInboundReceiptUsage( + tx: Tx, + projectId: string, + createdAt: string, +): Promise { + await tx + .insert(emailMonthlyUsage) + .values({ project_id: projectId, month: utcMonth(createdAt), inbound_receipts: 1 }) + .onConflictDoUpdate({ + target: [emailMonthlyUsage.project_id, emailMonthlyUsage.month], + set: { inbound_receipts: sql`${emailMonthlyUsage.inbound_receipts} + 1` }, + }); +} + async function currentRecipients( tx: DbOrTx, actionId: string, @@ -335,7 +362,8 @@ export async function admitEmailAction( !shared && input.kind !== 'direct' && input.transport === (input.kind === 'forward' ? 'native_forward' : 'native_reply'); - if (input.transport !== expectedTransport && !nativeCustomTransport) { + const sharedBindingReply = shared && input.kind === 'reply' && input.transport === 'binding'; + if (input.transport !== expectedTransport && !nativeCustomTransport && !sharedBindingReply) { throw new EmailAdmissionError('INVALID_REQUEST', 'invalid email transport'); } let senderAllowed = false; @@ -356,11 +384,12 @@ export async function admitEmailAction( nativeCustomTransport || domain?.route.outbound_status === 'verified_only'; if (senderAllowed && domain?.connection.credential_id) { const [credential] = await tx - .select({ status: emailCredentials.status }) + .select({ status: emailCredentials.status, expiresOn: emailCredentials.expires_on }) .from(emailCredentials) .where(eq(emailCredentials.id, domain.connection.credential_id)) .limit(1); - senderAllowed = credential?.status === 'healthy'; + senderAllowed = + credential?.status === 'healthy' && !isEmailCredentialExpired(credential.expiresOn); } else { senderAllowed = false; } @@ -507,7 +536,7 @@ export async function transitionEmailRecipients( return db.transaction(async (tx) => { // Serialize starts with project teardown. Once deleting is visible, an // admitted reservation cannot become a provider side effect. - if (next === 'attempt_started') { + if (next === 'attempt_started' || next === 'cancelled') { await lockEmailPolicyForAdmission(tx); } const [actionIdentity] = await tx @@ -519,12 +548,31 @@ export async function transitionEmailRecipients( throw new EmailAdmissionError('NOT_FOUND', 'email action not found'); } if (next === 'attempt_started') { + const [projectIdentity] = await tx + .select({ ownerId: projects.user_id }) + .from(projects) + .where(eq(projects.id, actionIdentity.projectId)) + .limit(1); + if (!projectIdentity) { + throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); + } + // Lock the owner before the project so a user deletion never has to wait + // on the project while this transaction waits on the user. Re-check the + // relationship under the project lock in case the unlocked lookup raced. + const [owner] = await tx + .select({ suspendedReason: users.suspended_reason }) + .from(users) + .where(eq(users.id, projectIdentity.ownerId)) + .for('share'); const [project] = await tx - .select({ status: projects.status }) + .select({ status: projects.status, ownerId: projects.user_id }) .from(projects) .where(eq(projects.id, actionIdentity.projectId)) .for('update'); - if (project?.status !== 'active') { + if (!owner || owner.suspendedReason) { + throw new EmailAdmissionError('INVALID_STATE', 'email sending is suspended'); + } + if (project?.status !== 'active' || project.ownerId !== projectIdentity.ownerId) { throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); } } @@ -561,6 +609,17 @@ export async function transitionEmailRecipients( ) { throw new EmailAdmissionError('INVALID_STATE', 'email route is not active'); } + if (!route.connection.credential_id) { + throw new EmailAdmissionError('INVALID_STATE', 'email route credential is unavailable'); + } + const [credential] = await tx + .select({ status: emailCredentials.status, expiresOn: emailCredentials.expires_on }) + .from(emailCredentials) + .where(eq(emailCredentials.id, route.connection.credential_id)) + .limit(1); + if (credential?.status !== 'healthy' || isEmailCredentialExpired(credential.expiresOn)) { + throw new EmailAdmissionError('INVALID_STATE', 'email route credential is unavailable'); + } } } } @@ -608,7 +667,7 @@ export async function transitionEmailRecipients( .where( and( eq(emailMonthlyUsage.project_id, action.project_id), - eq(emailMonthlyUsage.month, current.reserved_at.slice(0, 7)), + eq(emailMonthlyUsage.month, utcMonth(current.reserved_at)), ), ); } @@ -654,7 +713,7 @@ export async function drainProjectEmailAdmissions( const monthlyRefunds = new Map(); for (const row of cancelled) { if (row.reservedAt) { - const month = row.reservedAt.slice(0, 7); + const month = utcMonth(row.reservedAt); monthlyRefunds.set(month, (monthlyRefunds.get(month) ?? 0) + 1); } } @@ -677,13 +736,6 @@ export async function drainProjectEmailAdmissions( } /** Disable a custom route and drain its unstarted sends under the admission fence. */ -export async function disableEmailDomainRouteAndDrain( - db: Db, - routeId: string, -): Promise<{ cancelled: number; inFlight: number }> { - return db.transaction((tx) => disableEmailDomainRouteAndDrainTx(tx, routeId)); -} - export async function disableEmailDomainRouteAndDrainTx( tx: Tx, routeId: string, @@ -700,15 +752,17 @@ export async function disableEmailDomainRouteAndDrainTx( if (route.desired_state === 'removed') { return { cancelled: 0, inFlight: 0 }; } - await tx - .update(emailDomainRoutes) - .set({ - desired_state: 'disabled', - inbound_status: 'disabled', - desired_generation: sql`${emailDomainRoutes.desired_generation} + 1`, - updated_at: sql`now()`, - }) - .where(eq(emailDomainRoutes.id, routeId)); + if (route.desired_state !== 'disabled') { + await tx + .update(emailDomainRoutes) + .set({ + desired_state: 'disabled', + inbound_status: 'disabled', + desired_generation: sql`${emailDomainRoutes.desired_generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailDomainRoutes.id, routeId)); + } const cancelled = await tx .update(emailActionRecipients) .set({ @@ -727,7 +781,7 @@ export async function disableEmailDomainRouteAndDrainTx( const monthlyRefunds = new Map(); for (const row of cancelled) { if (row.reservedAt) { - const month = row.reservedAt.slice(0, 7); + const month = utcMonth(row.reservedAt); monthlyRefunds.set(month, (monthlyRefunds.get(month) ?? 0) + 1); } } @@ -753,55 +807,117 @@ export async function disableEmailDomainRouteAndDrainTx( return { cancelled: cancelled.length, inFlight: unresolved?.n ?? 0 }; } -export async function countEmailDomainInFlight(db: Db, routeId: string): Promise { - const [route] = await db - .select({ projectId: emailDomainRoutes.project_id, domain: emailDomainRoutes.domain }) - .from(emailDomainRoutes) - .where(eq(emailDomainRoutes.id, routeId)) +async function lockReceiptAdmissionProject(tx: Tx, projectId: string) { + await lockEmailPolicyForAdmission(tx); + const [identity] = await tx + .select({ ownerId: projects.user_id }) + .from(projects) + .where(eq(projects.id, projectId)) .limit(1); - if (!route?.projectId) { - return 0; + if (!identity) { + return null; } - const [row] = await db - .select({ n: count() }) - .from(emailUnresolvedAttempts) - .where( - and( - eq(emailUnresolvedAttempts.project_id, route.projectId), - eq(emailUnresolvedAttempts.sender_domain, route.domain), - ), - ); - return row?.n ?? 0; + // Match outbound admission's owner-before-project lock order during user deletion. + const [owner] = await tx + .select({ suspendedReason: users.suspended_reason }) + .from(users) + .where(eq(users.id, identity.ownerId)) + .for('share'); + const [project] = await tx + .select({ status: projects.status, ownerId: projects.user_id, slug: projects.slug }) + .from(projects) + .where(eq(projects.id, projectId)) + .for('update'); + if (!project || project.ownerId !== identity.ownerId) { + return null; + } + const [controls] = await tx + .select({ suspendedAt: emailProjectControls.suspended_at }) + .from(emailProjectControls) + .where(eq(emailProjectControls.project_id, projectId)); + return { + status: project.status, + slug: project.slug, + suspended: !owner || !!owner.suspendedReason || !!controls?.suspendedAt, + }; } -export async function getEmailAction( - db: Db, - actionId: string, -): Promise { - const [action] = await db +function validReceiptRouteFence(value: unknown): value is EmailReceiptRouteFence { + if (!value || typeof value !== 'object' || Array.isArray(value)) { + return false; + } + const route = value as Partial; + return ( + typeof route.routeId === 'string' && + route.routeId.length > 0 && + route.routeId.length <= 128 && + Number.isSafeInteger(route.routeGeneration) && + route.routeGeneration! >= 1 && + typeof route.connectionId === 'string' && + route.connectionId.length > 0 && + route.connectionId.length <= 128 && + (route.addressing === 'shared' || route.addressing === 'custom') && + typeof route.domain === 'string' && + route.domain.length > 0 && + route.domain.length <= 253 && + typeof route.projectSlug === 'string' && + route.projectSlug.length > 0 && + route.projectSlug.length <= 128 + ); +} + +async function requireCurrentReceiptRoute( + tx: Tx, + project: { slug: string }, + projectId: string, + fence: EmailReceiptRouteFence, +): Promise { + const [route] = await tx .select() - .from(emailActions) - .where(eq(emailActions.id, actionId)) + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, fence.routeId)) + .for('share'); + if ( + !route || + route.connection_id !== fence.connectionId || + route.desired_generation !== fence.routeGeneration || + route.desired_state !== 'active' || + route.inbound_status !== 'ready' || + route.addressing !== fence.addressing || + route.domain !== fence.domain.toLowerCase() || + project.slug.toLowerCase() !== fence.projectSlug.toLowerCase() || + (route.addressing === 'custom' ? route.project_id !== projectId : route.project_id !== null) + ) { + throw new EmailAdmissionError('INVALID_STATE', 'email route is not active'); + } + const [connection] = await tx + .select({ inboundStatus: emailZoneConnections.inbound_status }) + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, fence.connectionId)) .limit(1); - if (!action) { - return null; + if (connection?.inboundStatus !== 'ready') { + throw new EmailAdmissionError('INVALID_STATE', 'email route is not active'); } - return { operationId: actionId, replay: true, recipients: await currentRecipients(db, actionId) }; } export async function recordEmailReceipt( db: Db, - input: { receiptId: string; projectId: string; status: string }, + input: { + receiptId: string; + projectId: string; + status: string; + route?: EmailReceiptRouteFence; + }, ): Promise { - if (!/^[a-zA-Z0-9_-]{1,128}$/.test(input.receiptId) || !/^[a-z_]{1,32}$/.test(input.status)) { + if ( + !/^[a-zA-Z0-9_-]{1,128}$/.test(input.receiptId) || + !/^[a-z_]{1,32}$/.test(input.status) || + (input.route !== undefined && !validReceiptRouteFence(input.route)) + ) { throw new EmailAdmissionError('INVALID_REQUEST', 'invalid receipt'); } await db.transaction(async (tx) => { - const [project] = await tx - .select({ id: projects.id, status: projects.status }) - .from(projects) - .where(eq(projects.id, input.projectId)) - .for('update'); + const project = await lockReceiptAdmissionProject(tx, input.projectId); if (!project) { throw new EmailAdmissionError('NOT_FOUND', 'project not found'); } @@ -813,8 +929,8 @@ export async function recordEmailReceipt( if (existing && existing.project_id !== input.projectId) { throw new EmailAdmissionError('CONFLICT', 'receipt belongs to another project'); } - if (!existing && project.status !== 'active') { - throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); + if (!existing && (project.status !== 'active' || project.suspended)) { + throw new EmailAdmissionError('INVALID_STATE', 'inbound email is not active'); } if (existing) { await tx @@ -822,29 +938,64 @@ export async function recordEmailReceipt( .set({ status: input.status }) .where(eq(emailReceipts.id, input.receiptId)); } else { - await tx + if (!input.route) { + throw new EmailAdmissionError('INVALID_REQUEST', 'receipt route is required'); + } + await requireCurrentReceiptRoute(tx, project, input.projectId, input.route); + const [inserted] = await tx .insert(emailReceipts) - .values({ id: input.receiptId, project_id: input.projectId, status: input.status }); + .values({ id: input.receiptId, project_id: input.projectId, status: input.status }) + .returning({ createdAt: emailReceipts.created_at }); + await incrementInboundReceiptUsage(tx, input.projectId, inserted!.createdAt); } }); } export async function claimRelayedEmailReceipt( db: Db, - input: { receiptId: string; projectId: string; payloadDigest: string }, + input: { + receiptId: string; + projectId: string; + payloadDigest: string; + route?: EmailReceiptRouteFence; + }, ): Promise<{ state: 'claimed' | 'in_progress' | 'completed'; reject?: boolean }> { - if (!/^[a-f0-9]{64}$/.test(input.receiptId) || !/^[a-f0-9]{64}$/.test(input.payloadDigest)) { + if ( + !/^[a-f0-9]{64}$/.test(input.receiptId) || + !/^[a-f0-9]{64}$/.test(input.payloadDigest) || + (input.route !== undefined && !validReceiptRouteFence(input.route)) + ) { throw new EmailAdmissionError('INVALID_REQUEST', 'invalid relay claim'); } return db.transaction(async (tx) => { - const [project] = await tx - .select({ status: projects.status }) - .from(projects) - .where(eq(projects.id, input.projectId)) - .for('update'); + const project = await lockReceiptAdmissionProject(tx, input.projectId); if (!project || project.status !== 'active') { throw new EmailAdmissionError('INVALID_STATE', 'project is not active'); } + const [existing] = await tx + .select() + .from(emailReceipts) + .where(eq(emailReceipts.id, input.receiptId)) + .for('update'); + if (existing) { + if ( + existing.project_id !== input.projectId || + existing.payload_digest !== input.payloadDigest + ) { + throw new EmailAdmissionError('CONFLICT', 'relay invocation content conflict'); + } + return (existing.status === 'delivery_completed' || existing.status === 'actions_rejected') && + existing.final_reject !== null + ? { state: 'completed', reject: existing.final_reject } + : { state: 'in_progress' }; + } + if (!input.route) { + throw new EmailAdmissionError('INVALID_REQUEST', 'receipt route is required'); + } + if (project.suspended) { + throw new EmailAdmissionError('INVALID_STATE', 'inbound email is suspended'); + } + await requireCurrentReceiptRoute(tx, project, input.projectId, input.route); const inserted = await tx .insert(emailReceipts) .values({ @@ -854,25 +1005,27 @@ export async function claimRelayedEmailReceipt( status: 'received', }) .onConflictDoNothing() - .returning({ id: emailReceipts.id }); + .returning({ id: emailReceipts.id, createdAt: emailReceipts.created_at }); if (inserted.length) { + await incrementInboundReceiptUsage(tx, input.projectId, inserted[0]!.createdAt); return { state: 'claimed' }; } - const [existing] = await tx + const [concurrent] = await tx .select() .from(emailReceipts) .where(eq(emailReceipts.id, input.receiptId)) .for('update'); if ( - !existing || - existing.project_id !== input.projectId || - existing.payload_digest !== input.payloadDigest + !concurrent || + concurrent.project_id !== input.projectId || + concurrent.payload_digest !== input.payloadDigest ) { throw new EmailAdmissionError('CONFLICT', 'relay invocation content conflict'); } - return (existing.status === 'delivery_completed' || existing.status === 'actions_rejected') && - existing.final_reject !== null - ? { state: 'completed', reject: existing.final_reject } + return (concurrent.status === 'delivery_completed' || + concurrent.status === 'actions_rejected') && + concurrent.final_reject !== null + ? { state: 'completed', reject: concurrent.final_reject } : { state: 'in_progress' }; }); } @@ -929,75 +1082,64 @@ export async function getProjectEmailUsage(db: Db, projectId: string) { eq(emailMonthlyUsage.month, monthStart(now).slice(0, 7)), ), ); - const [received] = await db - .select({ n: count() }) - .from(emailReceipts) - .where( - and(eq(emailReceipts.project_id, projectId), gte(emailReceipts.created_at, monthStart(now))), - ); const limit = controls?.monthly_limit ?? 200; - const sent = monthly?.recipient_attempts ?? 0; + const attempts = monthly?.recipient_attempts ?? 0; return { month: monthStart(now).slice(0, 7), - sent, - received: received?.n ?? 0, + attempts, + received: monthly?.inbound_receipts ?? 0, limit, - remaining: Math.max(0, limit - sent), + remaining: Math.max(0, limit - attempts), suspended: !!controls?.suspended_at, }; } -export async function getProjectEmailLogs(db: Db, projectId: string, limit = 50) { +export async function getProjectEmailLogs(db: Db, projectId: string, limit = 50, offset = 0) { const cap = Math.max(1, Math.min(limit, 100)); - const rows = await db - .select({ action: emailActions, recipient: emailActionRecipients }) - .from(emailActionRecipients) - .innerJoin(emailActions, eq(emailActions.id, emailActionRecipients.action_id)) - .where(eq(emailActions.project_id, projectId)) - .orderBy(desc(emailActions.created_at)) - .limit(cap); - const receipts = await db - .select() - .from(emailReceipts) - .where(eq(emailReceipts.project_id, projectId)) - .orderBy(desc(emailReceipts.created_at)) - .limit(cap); - return { - logs: [ - ...rows.map(({ action, recipient }) => ({ - timestamp: Date.parse(action.created_at), - direction: 'sent' as const, - operationId: action.id, - receiptId: action.receipt_id, - recipient: recipient.recipient, - status: recipient.state, - transport: action.transport, - providerReference: recipient.provider_reference, - errorCode: recipient.error_code, - policyVersion: action.policy_version, - })), - ...receipts.map((receipt) => ({ - timestamp: Date.parse(receipt.created_at), - direction: 'received' as const, - operationId: receipt.id, - receiptId: receipt.id, - recipient: null, - status: receipt.status, - transport: 'email_event', - providerReference: null, - errorCode: receipt.status === 'actions_rejected' ? 'INVALID_ACTIONS' : null, - policyVersion: null, - })), - ] - .sort((a, b) => b.timestamp - a.timestamp) - .slice(0, cap), - }; + const result = await db.execute<{ + timestamp: number; + direction: 'sent' | 'received'; + operationId: string; + receiptId: string | null; + recipient: string | null; + status: string; + transport: string; + providerReference: string | null; + errorCode: string | null; + policyVersion: number | null; + }>(sql` + SELECT (extract(epoch FROM occurred_at) * 1000)::double precision AS timestamp, + direction, operation_id AS "operationId", receipt_id AS "receiptId", recipient, + status, transport, provider_reference AS "providerReference", error_code AS "errorCode", + policy_version AS "policyVersion" + FROM ( + SELECT a.created_at AS occurred_at, 'recipient:' || r.id AS sort_id, + 'sent' AS direction, a.id AS operation_id, a.receipt_id, + r.recipient, r.state AS status, a.transport, r.provider_reference, + r.error_code, a.policy_version + FROM ${emailActionRecipients} r + JOIN ${emailActions} a ON a.id = r.action_id + WHERE a.project_id = ${projectId} + UNION ALL + SELECT created_at AS occurred_at, 'receipt:' || id AS sort_id, + 'received' AS direction, id AS operation_id, id AS receipt_id, + NULL AS recipient, status, 'email_event' AS transport, NULL AS provider_reference, + CASE WHEN status = 'actions_rejected' THEN 'INVALID_ACTIONS' ELSE NULL END AS error_code, + NULL::integer AS policy_version + FROM ${emailReceipts} + WHERE project_id = ${projectId} + ) outcomes + ORDER BY occurred_at DESC, sort_id DESC + LIMIT ${cap} OFFSET ${offset} + `); + return { logs: result.rows }; } export async function pruneEmailActionHistory( db: Db, before: Date = new Date(Date.now() - 30 * 86_400_000), ) { + await cancelExpiredEmailReservations(db); // Active calls leave PII-free tombstones; delivery metadata expires normally. await db.delete(emailActions).where(sql` ${emailActions.created_at} < ${before.toISOString()} @@ -1007,3 +1149,27 @@ export async function pruneEmailActionHistory( ${emailMonthlyUsage.month} < ${new Date().toISOString().slice(0, 7)} `); } + +async function cancelExpiredEmailReservations(db: Db) { + const before = new Date(Date.now() - 15 * 60_000).toISOString(); + await db.transaction(async (tx) => { + // Starts and explicit cancellations take this lock shared. Whichever wins + // decides whether the provider may be called and whether quota is refunded. + await lockEmailPolicy(tx); + await tx.execute(sql` + with cancelled as ( + update ${emailActionRecipients} + set state = 'cancelled', completed_at = now(), error_code = 'UPSTREAM_ERROR' + where state = 'reserved' and reserved_at < ${before} + returning project_id, to_char(reserved_at at time zone 'UTC', 'YYYY-MM') as month + ), refunds as ( + select project_id, month, count(*) as amount + from cancelled group by project_id, month + ) + update ${emailMonthlyUsage} as usage + set recipient_attempts = greatest(0, usage.recipient_attempts - refunds.amount) + from refunds + where usage.project_id = refunds.project_id and usage.month = refunds.month + `); + }); +} diff --git a/platform/packages/api/src/email/cf-customer.ts b/platform/packages/api/src/email/cf-customer.ts index 4c47c0f2c..de1f16496 100644 --- a/platform/packages/api/src/email/cf-customer.ts +++ b/platform/packages/api/src/email/cf-customer.ts @@ -69,16 +69,6 @@ export type RelayScriptUpload = Readonly<{ ingressName: string; }>; -export type SendRawMessage = Readonly<{ - from: string; - recipients: ReadonlyArray; - mime_message: string; -}>; - -export type SendRawResult = Readonly<{ - message_id?: string; -}>; - export type CfCatchAllRule = Readonly<{ enabled: boolean; /** The worker name a 'worker' action points at; null for any other action shape. */ @@ -154,8 +144,6 @@ export type CfCustomerClient = Readonly<{ getRoutingSettings: (zoneId: string) => Promise; /** DELETE the relay script. 404 is success — the customer may have deleted it themselves. */ deleteRelayScript: (accountId: string, scriptName: string) => Promise; - /** POST /accounts/{a}/email/sending/send_raw — the REST send (contract 5). */ - sendRaw: (accountId: string, message: SendRawMessage) => Promise; }>; export function createCfCustomerClient(credential: string): CfCustomerClient { @@ -405,11 +393,5 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { throw err; } }, - - sendRaw: (accountId, message) => - call(`/accounts/${accountId}/email/sending/send_raw`, { - method: 'POST', - body: JSON.stringify(message), - }), }; } diff --git a/platform/packages/api/src/email/connection-schema.ts b/platform/packages/api/src/email/connection-schema.ts index 971f5eee2..6a9113239 100644 --- a/platform/packages/api/src/email/connection-schema.ts +++ b/platform/packages/api/src/email/connection-schema.ts @@ -36,21 +36,31 @@ export const emailZoneConnections = pgTable( staged_secret_iv: text('staged_secret_iv'), staged_secret_key_version: text('staged_secret_key_version'), previous_secret_hash: text('previous_secret_hash'), - previous_secret_until: timestamp('previous_secret_until', { mode: 'string' }), + previous_secret_until: timestamp('previous_secret_until', { + mode: 'string', + withTimezone: true, + }), inbound_status: text('inbound_status') .notNull() .default('pending') .$type<'pending' | 'ready' | 'disabled' | 'drifted'>(), inbound_reason: text('inbound_reason'), - inbound_observed_at: timestamp('inbound_observed_at', { mode: 'string' }), + inbound_observed_at: timestamp('inbound_observed_at', { mode: 'string', withTimezone: true }), management_status: text('management_status') .notNull() .default('probe_failed') .$type<'healthy' | 'expired' | 'revoked' | 'refresh_unknown' | 'probe_failed'>(), management_reason: text('management_reason'), - management_observed_at: timestamp('management_observed_at', { mode: 'string' }), - created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), - updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + management_observed_at: timestamp('management_observed_at', { + mode: 'string', + withTimezone: true, + }), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), }, (table) => [ uniqueIndex('email_zone_connections_zone_uq').on( @@ -92,16 +102,20 @@ export const emailDomainRoutes = pgTable( .default('pending') .$type<'pending' | 'ready' | 'disabled' | 'drifted'>(), inbound_reason: text('inbound_reason'), - inbound_observed_at: timestamp('inbound_observed_at', { mode: 'string' }), + inbound_observed_at: timestamp('inbound_observed_at', { mode: 'string', withTimezone: true }), outbound_status: text('outbound_status') .notNull() .default('pending') .$type<'pending' | 'verified_only' | 'ready' | 'blocked'>(), outbound_reason: text('outbound_reason'), - outbound_observed_at: timestamp('outbound_observed_at', { mode: 'string' }), + outbound_observed_at: timestamp('outbound_observed_at', { mode: 'string', withTimezone: true }), desired_generation: integer('desired_generation').notNull().default(1), - created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), - updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), }, (table) => [ uniqueIndex('email_domain_routes_domain_uq').on(table.domain), @@ -128,14 +142,18 @@ export const emailCredentials = pgTable( iv: text('iv'), key_version: text('key_version'), token_id: text('token_id'), - expires_on: timestamp('expires_on', { mode: 'string' }), + expires_on: timestamp('expires_on', { mode: 'string', withTimezone: true }), generation: integer('generation').notNull().default(1), status: text('status') .notNull() .default('healthy') .$type<'healthy' | 'expired' | 'revoked' | 'probe_failed'>(), - created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), - updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), }, (table) => [ index('email_credentials_scope_idx').on(table.installation_id, table.account_id, table.zone_id), @@ -155,6 +173,8 @@ export const emailOperations = pgTable( .notNull() .references(() => emailZoneConnections.id), route_id: text('route_id').references(() => emailDomainRoutes.id, { onDelete: 'set null' }), + /** Route generation captured when the operation intent was committed. */ + route_generation: integer('route_generation'), actor_kind: text('actor_kind').notNull().$type<'owner' | 'admin' | 'system'>(), actor_user_id: text('actor_user_id'), actor_scope: text('actor_scope').notNull(), @@ -169,8 +189,12 @@ export const emailOperations = pgTable( current_step: text('current_step'), failure_code: text('failure_code'), failure_detail: text('failure_detail'), - created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), - updated_at: timestamp('updated_at', { mode: 'string' }).notNull().defaultNow(), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), + updated_at: timestamp('updated_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), }, (table) => [ uniqueIndex('email_operations_key_uq').on( @@ -202,8 +226,8 @@ export const emailOperationSteps = pgTable( outcome: jsonb('outcome').$type | null>(), failure_code: text('failure_code'), failure_detail: text('failure_detail'), - started_at: timestamp('started_at', { mode: 'string' }), - finished_at: timestamp('finished_at', { mode: 'string' }), + started_at: timestamp('started_at', { mode: 'string', withTimezone: true }), + finished_at: timestamp('finished_at', { mode: 'string', withTimezone: true }), }, (table) => [uniqueIndex('email_operation_steps_order_uq').on(table.operation_id, table.ordinal)], ); @@ -217,8 +241,10 @@ export const emailCacheOutbox = pgTable( resource_id: text('resource_id').notNull(), version: integer('version').notNull(), payload: jsonb('payload').$type | null>(), - published_at: timestamp('published_at', { mode: 'string' }), - created_at: timestamp('created_at', { mode: 'string' }).notNull().defaultNow(), + published_at: timestamp('published_at', { mode: 'string', withTimezone: true }), + created_at: timestamp('created_at', { mode: 'string', withTimezone: true }) + .notNull() + .defaultNow(), }, (table) => [ uniqueIndex('email_cache_outbox_version_uq').on( diff --git a/platform/packages/api/src/email/connection-service.ts b/platform/packages/api/src/email/connection-service.ts index c1511b316..e5bb3fb16 100644 --- a/platform/packages/api/src/email/connection-service.ts +++ b/platform/packages/api/src/email/connection-service.ts @@ -1,11 +1,12 @@ -import { and, count, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm'; -import type { Db, DbOrTx } from '../db.ts'; +import { and, count, desc, eq, inArray, isNull, ne, or, sql } from 'drizzle-orm'; +import type { Db, DbOrTx, Tx } from '../db.ts'; import type { ApiEnv } from '../env.ts'; import { generateId } from '../id.ts'; import { decryptPlatformCredential, encryptPlatformCredential } from '../project-secrets.ts'; +import { CloudflareApiError } from '../provisioning/cloudflare-api.ts'; import { projects } from '../schema.ts'; import { emailUnresolvedAttempts } from './admission-schema.ts'; -import { disableEmailDomainRouteAndDrainTx } from './admission.ts'; +import { disableEmailDomainRouteAndDrainTx, lockEmailPolicy } from './admission.ts'; import { createCfCustomerClient } from './cf-customer.ts'; import { findZoneForEmailDomain, @@ -37,6 +38,61 @@ export class EmailOperationError extends Error { } } +export class EmailCredentialExpiredError extends EmailOperationError { + constructor() { + super('email connection credential has expired', 503); + } +} + +export function isEmailCredentialExpired(expiresOn: string | null): boolean { + if (!expiresOn) { + return false; + } + const expiresAt = Date.parse(expiresOn); + return Number.isFinite(expiresAt) && expiresAt <= Date.now(); +} + +function verifiedApiTokenMetadata(verification: { id: string; expires_on?: string | null }): { + tokenId: string; + expiresOn: string | null; +} { + if (!verification.id) { + throw new EmailOperationError('Cloudflare API token identity is unavailable', 503); + } + if (!verification.expires_on) { + return { tokenId: verification.id, expiresOn: null }; + } + const expiresAt = Date.parse(verification.expires_on); + if (!Number.isFinite(expiresAt)) { + throw new EmailOperationError('Cloudflare API token expiry is invalid', 503); + } + if (expiresAt <= Date.now()) { + throw new EmailOperationError('Cloudflare API token has expired', 403); + } + return { tokenId: verification.id, expiresOn: new Date(expiresAt).toISOString() }; +} + +/** A failed local/read-only prerequisite proves that no provider mutation ran. */ +class EmailOperationPreflightError extends Error { + constructor(error: unknown) { + super(error instanceof Error ? error.message : String(error)); + this.name = 'EmailOperationPreflightError'; + } +} + +async function emailOperationPreflight(run: () => Promise): Promise { + try { + return await run(); + } catch (error) { + if (error instanceof EmailOperationPreflightError) { + throw error; + } + throw new EmailOperationPreflightError(error); + } +} + +export const EMAIL_OPERATION_RECOVERY_MIN_AGE_MS = 24 * 60 * 60 * 1000; + const SETUP_STEPS = [ 'routing_enable', 'ingress_deploy', @@ -49,6 +105,19 @@ const SETUP_STEPS = [ 'sending_onboard', 'publish', ] as const; +const STAGED_SECRET_REPAIR_STEPS = [ + 'routing_enable', + 'ingress_deploy', + 'probe_route_enable', + 'secret_put', + 'relay_probe', + 'gateway_probe', + 'secret_retire', + 'catchall_ensure', + 'inbound_probe', + 'sending_onboard', + 'publish', +] as const; const SYNC_STEPS = [ 'ingress_deploy', 'probe_route_enable', @@ -82,12 +151,41 @@ const ROTATE_STEPS = [ ] as const; type StepKind = | (typeof SETUP_STEPS)[number] + | (typeof STAGED_SECRET_REPAIR_STEPS)[number] | (typeof REMOVE_STEPS)[number] | (typeof ROTATE_STEPS)[number]; +const OPERATOR_RECOVERABLE_WRITE_STEPS = [ + 'routing_enable', + 'ingress_deploy', + 'probe_route_enable', + 'secret_put', + 'catchall_ensure', + 'sending_onboard', + 'catchall_detach', + 'ingress_delete', +] as const satisfies ReadonlyArray; +type OperatorRecoverableWriteStep = (typeof OPERATOR_RECOVERABLE_WRITE_STEPS)[number]; +function isOperatorRecoverableWriteStep(kind: string): kind is OperatorRecoverableWriteStep { + return (OPERATOR_RECOVERABLE_WRITE_STEPS as ReadonlyArray).includes(kind); +} + +type EmailStepRoute = Pick< + typeof emailDomainRoutes.$inferSelect, + 'id' | 'domain' | 'desired_generation' +>; export function emailInstallationId(env: Bindings): string { return env.PLATFORM_INSTALLATION_ID ?? 'void-hosted'; } +async function lockEmailZoneConnectionIdentity( + tx: Tx, + installationId: string, + accountId: string, + zoneId: string, +): Promise { + const identity = `email-zone-connection-v1:${installationId}:${accountId}:${zoneId}`; + await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${identity}, 0))`); +} function gatewayOrigin(env: Bindings): string { const origin = (env as Bindings & { EMAIL_GATEWAY_ORIGIN?: string }).EMAIL_GATEWAY_ORIGIN; if (!origin || !/^https:\/\/[^/]+$/i.test(origin)) { @@ -283,6 +381,9 @@ function ingressName(installationId: string, zoneId: string): string { .slice(-48); return `void-email-${suffix}`; } +function isCloudflareEmailRoutingMx(exchange: string): boolean { + return /\.mx\.cloudflare\.net$/i.test(exchange); +} function isSharedGatewayConnection( env: Bindings, connection: typeof emailZoneConnections.$inferSelect, @@ -314,6 +415,245 @@ function canManageConnection( ); } +function emailStepResourceIdentity( + connection: typeof emailZoneConnections.$inferSelect, + kind: StepKind, + route?: EmailStepRoute | null, + secretGeneration?: number, +): string { + const base = `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`; + if (kind === 'routing_enable') { + if (!route) { + throw new EmailOperationError('email route identity is unavailable', 503); + } + return `${base}/routing/${route.domain}`; + } + if (kind === 'ingress_deploy') { + return `${base}/relay/${RELAY_VERSION}`; + } + if (kind === 'probe_route_enable') { + return `${base}/workers-dev/enabled`; + } + if (kind === 'secret_put') { + if (secretGeneration === undefined) { + throw new EmailOperationError('email secret generation is unavailable', 503); + } + return `${base}/secret/${secretGeneration}`; + } + if (kind === 'catchall_ensure' || kind === 'catchall_detach') { + return `${base}/catch-all/${kind === 'catchall_ensure' ? 'ensure' : 'detach'}`; + } + if (kind === 'ingress_delete') { + return `${base}/relay/delete`; + } + if (kind === 'sending_onboard') { + if (!route) { + throw new EmailOperationError('email route identity is unavailable', 503); + } + return `${base}/sending/${route.domain}`; + } + return secretGeneration === undefined ? base : `${base}/secret/${secretGeneration}`; +} + +async function emailStepRequestDigest( + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, + kind: StepKind, + generation: number, + route?: EmailStepRoute | null, + secretGeneration?: number, +): Promise { + const intent = { + kind, + connectionId: connection.id, + generation, + accountId: connection.account_id, + zoneId: connection.zone_id, + ingressName: connection.ingress_worker_name, + routeId: route?.id, + routeDomain: route?.domain, + routeGeneration: route?.desired_generation, + secretGeneration, + }; + if (kind === 'ingress_deploy') { + return digest({ + ...intent, + relayVersion: RELAY_VERSION, + relaySourceDigest: await digest(RELAY_SOURCE), + compatibilityDate: RELAY_COMPATIBILITY_DATE, + gatewayOrigin: gatewayOrigin(env), + }); + } + return digest(intent); +} + +function emailStepSecretGeneration( + operationKind: typeof emailOperations.$inferSelect.kind, + connection: typeof emailZoneConnections.$inferSelect, + stepKind: StepKind, +): number | undefined { + if (stepKind === 'secret_retire') { + if (connection.staged_secret_generation === null) { + throw new EmailOperationError('staged ingress generation unavailable', 503); + } + return connection.staged_secret_generation; + } + if (stepKind !== 'secret_put') { + return undefined; + } + if (operationKind === 'rotate_secret') { + if (connection.staged_secret_generation === null) { + throw new EmailOperationError('staged ingress generation unavailable', 503); + } + return connection.staged_secret_generation; + } + return connection.active_secret_generation; +} + +async function resumeBlockedEmailOperationTx( + tx: DbOrTx, + env: Bindings, + operationId: string, + actor: EmailActor, + expectedRouteId?: string, + expectedProjectId?: string, +): Promise { + const snapshot = ( + await tx.select().from(emailOperations).where(eq(emailOperations.id, operationId)).limit(1) + )[0]; + if (!snapshot || snapshot.status !== 'blocked') { + return false; + } + if ( + snapshot.installation_id !== emailInstallationId(env) || + (expectedRouteId !== undefined && snapshot.route_id !== expectedRouteId) + ) { + throw new EmailOperationError('email operation is unavailable', 404); + } + const route = snapshot.route_id + ? ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, snapshot.route_id)) + .for('update') + .limit(1) + )[0] + : null; + if (snapshot.route_id && !route) { + throw new EmailOperationError('email operation is unavailable', 404); + } + if (route && expectedProjectId !== undefined && route.project_id !== expectedProjectId) { + throw new EmailOperationError('email operation is unavailable', 404); + } + if (route && actor.kind === 'owner') { + const project = route.project_id + ? ( + await tx + .select({ userId: projects.user_id, status: projects.status }) + .from(projects) + .where(eq(projects.id, route.project_id)) + .limit(1) + )[0] + : null; + if ( + !project || + project.status === 'deleting' || + project.userId !== actor.userId || + route.managed_by !== 'owner' + ) { + throw new EmailOperationError('forbidden', 403); + } + } + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, snapshot.connection_id)) + .for('update') + .limit(1) + )[0]; + const operation = ( + await tx + .select() + .from(emailOperations) + .where(eq(emailOperations.id, snapshot.id)) + .for('update') + .limit(1) + )[0]; + if ( + !connection || + !operation || + operation.status !== 'blocked' || + operation.connection_id !== snapshot.connection_id || + operation.route_id !== snapshot.route_id || + operation.desired_generation !== snapshot.desired_generation || + connection.desired_generation !== operation.desired_generation || + !canManageConnection(actor, connection) + ) { + throw new EmailOperationError('blocked email operation cannot be resumed', 409); + } + const blocked = await tx + .select() + .from(emailOperationSteps) + .where( + and( + eq(emailOperationSteps.operation_id, operation.id), + eq(emailOperationSteps.status, 'blocked'), + ), + ) + .orderBy(emailOperationSteps.ordinal); + if (blocked.length !== 1 || operation.current_step !== blocked[0]!.kind) { + throw new EmailOperationError('blocked email operation step is unavailable', 409); + } + const step = blocked[0]!; + const resumed = await tx + .update(emailOperationSteps) + .set({ + status: 'pending', + outcome: null, + failure_code: null, + failure_detail: null, + started_at: null, + finished_at: null, + }) + .where( + and( + eq(emailOperationSteps.id, step.id), + eq(emailOperationSteps.status, 'blocked'), + eq(emailOperationSteps.attempt, step.attempt), + ), + ) + .returning({ id: emailOperationSteps.id }); + if (!resumed.length) { + return false; + } + await tx + .update(emailOperations) + .set({ + status: 'pending', + current_step: null, + failure_code: null, + failure_detail: null, + updated_at: sql`now()`, + }) + .where(and(eq(emailOperations.id, operation.id), eq(emailOperations.status, 'blocked'))); + return true; +} + +async function resumeBlockedEmailOperation( + db: Db, + env: Bindings, + operationId: string, + actor: EmailActor, + expectedRouteId?: string, + expectedProjectId?: string, +): Promise { + return db.transaction((tx) => + resumeBlockedEmailOperationTx(tx, env, operationId, actor, expectedRouteId, expectedProjectId), + ); +} + export async function resolveEmailDomain(db: DbOrTx, rawDomain: string) { const domain = normalizeEmailDomain(rawDomain); const rows = await db @@ -379,13 +719,18 @@ export async function credentialFor( )[0]; if ( !row || - row.status !== 'healthy' || row.installation_id !== connection.installation_id || row.account_id !== connection.account_id || row.zone_id !== connection.zone_id ) { throw new EmailOperationError('email connection credential is unavailable', 503); } + if (row.status === 'expired' || isEmailCredentialExpired(row.expires_on)) { + throw new EmailCredentialExpiredError(); + } + if (row.status !== 'healthy') { + throw new EmailOperationError('email connection credential is unavailable', 503); + } if (row.kind === 'platform') { if (connection.account_id !== env.CF_ACCOUNT_ID || !env.CF_API_TOKEN) { throw new EmailOperationError('platform credential cannot manage this zone', 403); @@ -402,85 +747,371 @@ export async function credentialFor( }); } -async function forgetUnusedEmailCredential( - tx: DbOrTx, - connectionId: string, - removingRouteId: string, -): Promise { +export async function replaceBlockedSystemEmailCleanupCredential( + db: Db, + env: Bindings, + routeId: string, + token: string, +): Promise { + const route = ( + await db.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.id, routeId)).limit(1) + )[0]; + if ( + !route || + route.addressing !== 'custom' || + !route.project_id || + route.desired_state !== 'disabled' + ) { + throw new EmailOperationError( + 'replacement credential is available only for blocked project cleanup', + 409, + ); + } const connection = ( - await tx + await db .select() .from(emailZoneConnections) - .where(eq(emailZoneConnections.id, connectionId)) - .for('update') + .where(eq(emailZoneConnections.id, route.connection_id)) .limit(1) )[0]; - if (!connection?.credential_id) { - return; + if ( + !connection || + connection.installation_id !== emailInstallationId(env) || + !connection.credential_id + ) { + throw new EmailOperationError('email cleanup connection is unavailable', 409); + } + const project = ( + await db + .select({ status: projects.status }) + .from(projects) + .where(eq(projects.id, route.project_id)) + .limit(1) + )[0]; + if (project && project.status !== 'deleting') { + throw new EmailOperationError('project cleanup is not in progress', 409); } const sibling = ( - await tx + await db .select({ id: emailDomainRoutes.id }) .from(emailDomainRoutes) .where( and( - eq(emailDomainRoutes.connection_id, connectionId), - ne(emailDomainRoutes.id, removingRouteId), + eq(emailDomainRoutes.connection_id, connection.id), + ne(emailDomainRoutes.id, route.id), ne(emailDomainRoutes.desired_state, 'removed'), ), ) .limit(1) )[0]; if (sibling) { - return; + throw new EmailOperationError('email connection still has another domain assignment', 409); } - await tx - .update(emailZoneConnections) - .set({ - credential_id: null, - management_status: 'revoked', - management_observed_at: sql`now()`, - updated_at: sql`now()`, - }) - .where(eq(emailZoneConnections.id, connectionId)); - await tx.delete(emailCredentials).where(eq(emailCredentials.id, connection.credential_id)); -} - -export async function inspectEmailInboundRoute( - client: ReturnType, - connection: Pick, - domain: string, -): Promise { - const [catchall, rules, exchanges] = await Promise.all([ - client.getCatchAll(connection.zone_id), - client.listRoutingRules(connection.zone_id), - lookupMxOverDns(domain), - ]); - if ( - !exchanges.length || - exchanges.some((exchange) => !/\.mx\.cloudflare\.net$/i.test(exchange)) - ) { - return `MX records for ${domain} do not route mail to Cloudflare Email Routing`; + const unresolved = ( + await db + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connection.id), + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + ), + ) + .limit(1) + )[0]; + if (unresolved) { + throw new EmailOperationError(`connection operation ${unresolved.id} is unresolved`, 409); } - if (!catchall?.enabled || catchall.workerName !== connection.ingress_worker_name) { - return 'zone catch-all does not point to this ingress'; + const candidates = await db + .select() + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connection.id), + eq(emailOperations.route_id, route.id), + eq(emailOperations.kind, 'remove'), + eq(emailOperations.actor_kind, 'system'), + eq(emailOperations.status, 'blocked'), + eq(emailOperations.desired_generation, connection.desired_generation), + eq(emailOperations.route_generation, route.desired_generation), + ), + ) + .orderBy(desc(emailOperations.created_at), desc(emailOperations.id)) + .limit(2); + if (candidates.length !== 1) { + throw new EmailOperationError('blocked system cleanup operation is unavailable', 409); } - return rules.some( - (rule) => rule.enabled && rule.addresses.some((address) => address.endsWith(`@${domain}`)), - ) - ? `enabled explicit Cloudflare email rules conflict with ${domain}` - : null; -} - -export async function readConnectionSecret( - env: Bindings, - connection: typeof emailZoneConnections.$inferSelect, -): Promise { - return decryptPlatformCredential( - env, - connection.installation_id, - `${connection.id}:secret:${connection.active_secret_generation}`, - { + const operation = candidates[0]!; + const client = createCfCustomerClient(token); + let verifiedToken: { tokenId: string; expiresOn: string | null }; + try { + const verification = await client.verifyToken(); + if (verification.status !== 'active') { + throw new EmailOperationError('Cloudflare API token is not active', 403); + } + verifiedToken = verifiedApiTokenMetadata(verification); + const zone = await client.findZone(connection.zone_name); + if ( + !zone || + zone.id !== connection.zone_id || + zone.account.id !== connection.account_id || + zone.name.toLowerCase() !== connection.zone_name.toLowerCase() + ) { + throw new EmailOperationError('Cloudflare API token cannot manage this email zone', 403); + } + await client.getRoutingSettings(connection.zone_id); + } catch (error) { + if (error instanceof EmailOperationError) { + throw error; + } + if (error instanceof CloudflareApiError) { + throw new EmailOperationError(error.message, error.status >= 500 ? 503 : error.status); + } + throw new EmailOperationError('Cloudflare API token could not be verified', 503); + } + const encrypted = await encryptPlatformCredential( + env, + connection.installation_id, + connection.credential_id, + token, + ); + + return db.transaction(async (tx) => { + const currentRoute = ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, route.id)) + .for('update') + .limit(1) + )[0]; + if ( + !currentRoute || + currentRoute.connection_id !== route.connection_id || + currentRoute.project_id !== route.project_id || + currentRoute.addressing !== 'custom' || + currentRoute.desired_state !== 'disabled' || + currentRoute.desired_generation !== route.desired_generation + ) { + throw new EmailOperationError('email cleanup changed while verifying the credential', 409); + } + const currentConnection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connection.id)) + .for('update') + .limit(1) + )[0]; + if ( + !currentConnection || + currentConnection.installation_id !== connection.installation_id || + currentConnection.account_id !== connection.account_id || + currentConnection.zone_id !== connection.zone_id || + currentConnection.zone_name !== connection.zone_name || + currentConnection.credential_id !== connection.credential_id || + currentConnection.managed_by !== connection.managed_by || + currentConnection.manager_user_id !== connection.manager_user_id || + currentConnection.desired_generation !== connection.desired_generation + ) { + throw new EmailOperationError('email cleanup changed while verifying the credential', 409); + } + const currentProject = ( + await tx + .select({ status: projects.status }) + .from(projects) + .where(eq(projects.id, currentRoute.project_id!)) + .limit(1) + )[0]; + if (currentProject && currentProject.status !== 'deleting') { + throw new EmailOperationError('project cleanup is not in progress', 409); + } + const currentSibling = ( + await tx + .select({ id: emailDomainRoutes.id }) + .from(emailDomainRoutes) + .where( + and( + eq(emailDomainRoutes.connection_id, currentConnection.id), + ne(emailDomainRoutes.id, currentRoute.id), + ne(emailDomainRoutes.desired_state, 'removed'), + ), + ) + .limit(1) + )[0]; + if (currentSibling) { + throw new EmailOperationError('email connection still has another domain assignment', 409); + } + const currentUnresolved = ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, currentConnection.id), + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + ), + ) + .limit(1) + )[0]; + if (currentUnresolved) { + throw new EmailOperationError( + `connection operation ${currentUnresolved.id} is unresolved`, + 409, + ); + } + const currentOperation = ( + await tx + .select() + .from(emailOperations) + .where(eq(emailOperations.id, operation.id)) + .for('update') + .limit(1) + )[0]; + if ( + !currentOperation || + currentOperation.connection_id !== currentConnection.id || + currentOperation.route_id !== currentRoute.id || + currentOperation.kind !== 'remove' || + currentOperation.actor_kind !== 'system' || + currentOperation.status !== 'blocked' || + currentOperation.desired_generation !== currentConnection.desired_generation || + currentOperation.route_generation !== currentRoute.desired_generation + ) { + throw new EmailOperationError('blocked system cleanup operation is unavailable', 409); + } + const currentCredential = ( + await tx + .select() + .from(emailCredentials) + .where(eq(emailCredentials.id, currentConnection.credential_id!)) + .for('update') + .limit(1) + )[0]; + if ( + !currentCredential || + currentCredential.installation_id !== currentConnection.installation_id || + currentCredential.account_id !== currentConnection.account_id || + currentCredential.zone_id !== currentConnection.zone_id || + currentCredential.managed_by !== currentConnection.managed_by || + currentCredential.manager_user_id !== currentConnection.manager_user_id + ) { + throw new EmailOperationError('email cleanup credential changed while it was verified', 409); + } + await tx + .update(emailCredentials) + .set({ + kind: 'api_token', + ciphertext: encrypted.ciphertext, + iv: encrypted.iv, + key_version: encrypted.keyVersion, + token_id: verifiedToken.tokenId, + expires_on: verifiedToken.expiresOn, + status: 'healthy', + generation: sql`${emailCredentials.generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailCredentials.id, currentCredential.id)); + await tx + .update(emailZoneConnections) + .set({ + management_status: 'healthy', + management_reason: null, + management_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, currentConnection.id)); + const resumed = await resumeBlockedEmailOperationTx( + tx, + env, + currentOperation.id, + { kind: 'system' }, + currentRoute.id, + currentRoute.project_id!, + ); + if (!resumed) { + throw new EmailOperationError('blocked system cleanup operation could not be resumed', 409); + } + return currentOperation.id; + }); +} + +async function forgetUnusedEmailCredential( + tx: DbOrTx, + connectionId: string, + removingRouteId: string, +): Promise { + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connectionId)) + .for('update') + .limit(1) + )[0]; + if (!connection?.credential_id) { + return; + } + const sibling = ( + await tx + .select({ id: emailDomainRoutes.id }) + .from(emailDomainRoutes) + .where( + and( + eq(emailDomainRoutes.connection_id, connectionId), + ne(emailDomainRoutes.id, removingRouteId), + ne(emailDomainRoutes.desired_state, 'removed'), + ), + ) + .limit(1) + )[0]; + if (sibling) { + return; + } + await tx + .update(emailZoneConnections) + .set({ + credential_id: null, + management_status: 'revoked', + management_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connectionId)); + await tx.delete(emailCredentials).where(eq(emailCredentials.id, connection.credential_id)); +} + +export async function inspectEmailInboundRoute( + client: ReturnType, + connection: Pick, + domain: string, +): Promise { + const [catchall, rules, exchanges] = await Promise.all([ + client.getCatchAll(connection.zone_id), + client.listRoutingRules(connection.zone_id), + lookupMxOverDns(domain), + ]); + if (!exchanges.length || exchanges.some((exchange) => !isCloudflareEmailRoutingMx(exchange))) { + return `MX records for ${domain} do not route mail to Cloudflare Email Routing`; + } + if (!catchall?.enabled || catchall.workerName !== connection.ingress_worker_name) { + return 'zone catch-all does not point to this ingress'; + } + return rules.some( + (rule) => rule.enabled && rule.addresses.some((address) => address.endsWith(`@${domain}`)), + ) + ? `enabled explicit Cloudflare email rules conflict with ${domain}` + : null; +} + +export async function readConnectionSecret( + env: Bindings, + connection: typeof emailZoneConnections.$inferSelect, +): Promise { + return decryptPlatformCredential( + env, + connection.installation_id, + `${connection.id}:secret:${connection.active_secret_generation}`, + { ciphertext: connection.secret_ciphertext, iv: connection.secret_iv, keyVersion: connection.secret_key_version, @@ -556,6 +1187,14 @@ export async function requestEmailDomainAdd( if (previous.request_digest !== requestDigest || !previous.route_id) { throw new EmailOperationError('email operation key was reused with a different request'); } + await resumeBlockedEmailOperation( + db, + env, + previous.id, + actor, + previous.route_id, + input.projectId, + ); return { operationId: previous.id, routeId: previous.route_id }; } if (!input.token && input.actor.kind === 'owner') { @@ -596,11 +1235,13 @@ export async function requestEmailDomainAdd( 403, ); } + let verifiedToken: { tokenId: string; expiresOn: string | null } | null = null; if (input.token) { const verification = await client.verifyToken(); if (verification.status !== 'active') { throw new EmailOperationError('Cloudflare API token is not active', 403); } + verifiedToken = verifiedApiTokenMetadata(verification); // The actual zone read above proves resource scope more reliably than a template URL. await client.getRoutingSettings(zone.id); } @@ -618,13 +1259,16 @@ export async function requestEmailDomainAdd( .limit(1) )[0]; const existingAssignment = await resolveEmailDomain(db, domain); - if (!existingAssignment) { + if (!existingAssignment || existingAssignment.route.desired_state !== 'active') { const preflight = await Promise.all([ lookupMxOverDns(domain), client.getCatchAll(zone.id), client.listRoutingRules(zone.id), ]); - if (preflight[0].length > 0) { + const mxConflict = existingAssignment + ? preflight[0].some((exchange) => !isCloudflareEmailRoutingMx(exchange)) + : preflight[0].length > 0; + if (mxConflict) { throw new EmailOperationError( `${domain} already has MX records; use an unused mail subdomain`, 409, @@ -681,6 +1325,7 @@ export async function requestEmailDomainAdd( if (actor.kind === 'owner' && project.user_id !== actor.userId) { throw new EmailOperationError('forbidden', 403); } + await lockEmailZoneConnectionIdentity(tx, installationId, zone.account.id, zone.id); const existingRoute = ( await tx .select() @@ -772,6 +1417,25 @@ export async function requestEmailDomainAdd( 403, ); } + const blockedAssignment = ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connection.id), + eq(emailOperations.route_id, existingRoute.id), + eq(emailOperations.route_generation, existingRoute.desired_generation), + eq(emailOperations.actor_kind, actor.kind), + eq(emailOperations.actor_user_id, actor.userId), + inArray(emailOperations.kind, ['setup', 'sync']), + eq(emailOperations.status, 'blocked'), + eq(emailOperations.desired_generation, connection.desired_generation), + ), + ) + .orderBy(desc(emailOperations.created_at), desc(emailOperations.id)) + .limit(1) + )[0]; if (connection.credential_id) { const replacement = input.token ? await encryptPlatformCredential( @@ -788,6 +1452,8 @@ export async function requestEmailDomainAdd( ciphertext: replacement?.ciphertext ?? null, iv: replacement?.iv ?? null, key_version: replacement?.keyVersion ?? null, + token_id: verifiedToken?.tokenId ?? null, + expires_on: verifiedToken?.expiresOn ?? null, status: 'healthy', generation: sql`${emailCredentials.generation} + 1`, updated_at: sql`now()`, @@ -805,6 +1471,8 @@ export async function requestEmailDomainAdd( ciphertext: encryptedToken?.ciphertext ?? null, iv: encryptedToken?.iv ?? null, key_version: encryptedToken?.keyVersion ?? null, + token_id: verifiedToken?.tokenId ?? null, + expires_on: verifiedToken?.expiresOn ?? null, }); await tx .update(emailZoneConnections) @@ -812,11 +1480,14 @@ export async function requestEmailDomainAdd( .where(eq(emailZoneConnections.id, connection.id)); } const generation = connection.desired_generation + 1; + const routeGeneration = + existingRoute.desired_generation + (existingRoute.desired_state !== 'active' ? 1 : 0); await tx .update(emailZoneConnections) .set({ desired_generation: generation, management_status: 'healthy', + management_reason: null, management_observed_at: sql`now()`, updated_at: sql`now()`, }) @@ -852,6 +1523,7 @@ export async function requestEmailDomainAdd( installation_id: installationId, connection_id: connection.id, route_id: existingRoute.id, + route_generation: routeGeneration, actor_kind: actor.kind, actor_user_id: actor.userId, actor_scope: actorScope, @@ -860,19 +1532,38 @@ export async function requestEmailDomainAdd( request_digest: requestDigest, desired_generation: generation, }); - const steps = connection.inbound_status === 'disabled' ? SETUP_STEPS : SYNC_STEPS; + const steps = + connection.staged_secret_generation !== null + ? STAGED_SECRET_REPAIR_STEPS + : connection.inbound_status === 'disabled' || blockedAssignment + ? SETUP_STEPS + : SYNC_STEPS; + const stepRoute: EmailStepRoute = { + id: existingRoute.id, + domain, + desired_generation: routeGeneration, + }; for (let i = 0; i < steps.length; i++) { + const secretGeneration = emailStepSecretGeneration('sync', connection, steps[i]); await tx.insert(emailOperationSteps).values({ id: generateId('estep'), operation_id: operationId, ordinal: i, kind: steps[i], - resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, - request_digest: await digest({ - kind: steps[i], - connectionId: connection.id, + resource_identity: emailStepResourceIdentity( + connection, + steps[i], + stepRoute, + secretGeneration, + ), + request_digest: await emailStepRequestDigest( + env, + connection, + steps[i], generation, - }), + stepRoute, + secretGeneration, + ), }); } return { operationId, routeId: existingRoute.id }; @@ -889,6 +1580,8 @@ export async function requestEmailDomainAdd( ciphertext: encryptedToken?.ciphertext ?? null, iv: encryptedToken?.iv ?? null, key_version: encryptedToken?.keyVersion ?? null, + token_id: verifiedToken?.tokenId ?? null, + expires_on: verifiedToken?.expiresOn ?? null, }); await tx.insert(emailZoneConnections).values({ id: connectionId, @@ -926,12 +1619,15 @@ export async function requestEmailDomainAdd( ciphertext: encryptedToken?.ciphertext ?? null, iv: encryptedToken?.iv ?? null, key_version: encryptedToken?.keyVersion ?? null, + token_id: verifiedToken?.tokenId ?? null, + expires_on: verifiedToken?.expiresOn ?? null, }); await tx .update(emailZoneConnections) .set({ credential_id: credentialId, management_status: 'healthy', + management_reason: null, management_observed_at: sql`now()`, updated_at: sql`now()`, }) @@ -939,9 +1635,6 @@ export async function requestEmailDomainAdd( } else if (input.token) { // A sibling assignment supplies the manager's current zone token. // The connection, rather than either project, owns its ciphertext. - if (!connection.credential_id) { - throw new EmailOperationError('connection credential missing', 503); - } const replacement = await encryptPlatformCredential( env, installationId, @@ -955,11 +1648,35 @@ export async function requestEmailDomainAdd( ciphertext: replacement.ciphertext, iv: replacement.iv, key_version: replacement.keyVersion, + token_id: verifiedToken!.tokenId, + expires_on: verifiedToken!.expiresOn, status: 'healthy', generation: sql`${emailCredentials.generation} + 1`, updated_at: sql`now()`, }) .where(eq(emailCredentials.id, connection.credential_id)); + await tx + .update(emailZoneConnections) + .set({ + management_status: 'healthy', + management_reason: null, + management_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connection.id)); + } + const repairStaged = connection.staged_secret_generation !== null; + if (repairStaged) { + connection = ( + await tx + .update(emailZoneConnections) + .set({ + desired_generation: sql`${emailZoneConnections.desired_generation} + 1`, + updated_at: sql`now()`, + }) + .where(eq(emailZoneConnections.id, connection.id)) + .returning() + )[0]!; } await tx.insert(emailDomainRoutes).values({ id: routeId, @@ -975,6 +1692,7 @@ export async function requestEmailDomainAdd( installation_id: installationId, connection_id: connection.id, route_id: routeId, + route_generation: 1, actor_kind: actor.kind, actor_user_id: actor.userId, actor_scope: actorScope, @@ -983,20 +1701,33 @@ export async function requestEmailDomainAdd( request_digest: requestDigest, desired_generation: connection.desired_generation, }); - const steps = - created || connection.inbound_status === 'disabled' ? SETUP_STEPS : SIBLING_STEPS; + const steps = repairStaged + ? STAGED_SECRET_REPAIR_STEPS + : created || connection.inbound_status === 'disabled' + ? SETUP_STEPS + : SIBLING_STEPS; + const stepRoute: EmailStepRoute = { id: routeId, domain, desired_generation: 1 }; for (let i = 0; i < steps.length; i++) { + const secretGeneration = emailStepSecretGeneration('setup', connection, steps[i]); await tx.insert(emailOperationSteps).values({ id: generateId('estep'), operation_id: operationId, ordinal: i, kind: steps[i], - resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, - request_digest: await digest({ - kind: steps[i], - connectionId: connection.id, - generation: connection.desired_generation, - }), + resource_identity: emailStepResourceIdentity( + connection, + steps[i], + stepRoute, + secretGeneration, + ), + request_digest: await emailStepRequestDigest( + env, + connection, + steps[i], + connection.desired_generation, + stepRoute, + secretGeneration, + ), }); } return { operationId, routeId }; @@ -1065,6 +1796,7 @@ export async function ensureSharedEmailConnection(db: Db, env: Bindings): Promis .limit(1) )[0]; if (previous) { + await resumeBlockedEmailOperation(db, env, previous.id, { kind: 'system' }, previous.route_id!); return previous.id; } const client = createCfCustomerClient(env.CF_API_TOKEN); @@ -1096,6 +1828,7 @@ export async function ensureSharedEmailConnection(db: Db, env: Bindings): Promis randomSecret(), ); return db.transaction(async (tx) => { + await lockEmailZoneConnectionIdentity(tx, installationId, zone.account.id, zone.id); const existingRoute = ( await tx.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.domain, domain)).limit(1) )[0]; @@ -1111,6 +1844,15 @@ export async function ensureSharedEmailConnection(db: Db, env: Bindings): Promis .orderBy(sql`${emailOperations.created_at} DESC`) .limit(1) )[0]; + if (latest) { + await resumeBlockedEmailOperationTx( + tx, + env, + latest.id, + { kind: 'system' }, + existingRoute.id, + ); + } return latest?.id ?? null; } let connection = ( @@ -1184,6 +1926,7 @@ export async function ensureSharedEmailConnection(db: Db, env: Bindings): Promis installation_id: installationId, connection_id: connection.id, route_id: routeId, + route_generation: 1, actor_kind: 'system', actor_scope: 'system:shared', kind: 'setup', @@ -1196,18 +1939,21 @@ export async function ensureSharedEmailConnection(db: Db, env: Bindings): Promis const steps = created ? (['catchall_ensure', 'inbound_probe', 'publish'] as const) : (['inbound_probe', 'publish'] as const); + const stepRoute: EmailStepRoute = { id: routeId, domain, desired_generation: 1 }; for (let i = 0; i < steps.length; i++) { await tx.insert(emailOperationSteps).values({ id: generateId('estep'), operation_id: operationId, ordinal: i, kind: steps[i], - resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, - request_digest: await digest({ - kind: steps[i], - connectionId: connection.id, - generation: connection.desired_generation, - }), + resource_identity: emailStepResourceIdentity(connection, steps[i], stepRoute), + request_digest: await emailStepRequestDigest( + env, + connection, + steps[i], + connection.desired_generation, + stepRoute, + ), }); } return operationId; @@ -1246,14 +1992,32 @@ export async function requestEmailDomainSync( ): Promise { return requestExistingOperation(db, env, routeId, actor, 'sync', key); } +export function requestEmailDomainRemove( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + key?: string, +): Promise; +export function requestEmailDomainRemove( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + key: string, + expectedProjectId: string, +): Promise; export async function requestEmailDomainRemove( db: Db, env: Bindings, routeId: string, actor: EmailActor, key = generateId('erem'), -): Promise { - return requestExistingOperation(db, env, routeId, actor, 'remove', key); + expectedProjectId?: string, +): Promise { + return expectedProjectId === undefined + ? requestExistingOperation(db, env, routeId, actor, 'remove', key) + : requestExistingOperation(db, env, routeId, actor, 'remove', key, expectedProjectId); } /** Stage a new zone secret. The old generation stays active until a signed * challenge proves the deployed Worker actually received the new value. */ @@ -1285,7 +2049,9 @@ export async function requestEmailSecretRotation( if (prior.request_digest !== requestDigest) { throw new EmailOperationError('email operation key conflict'); } - return prior.id; + if (prior.status !== 'blocked') { + return prior.id; + } } const secret = randomSecret(); return db.transaction(async (tx) => { @@ -1320,6 +2086,7 @@ export async function requestEmailSecretRotation( if (replay.request_digest !== requestDigest) { throw new EmailOperationError('email operation key conflict'); } + await resumeBlockedEmailOperationTx(tx, env, replay.id, actor); return replay.id; } if (isSharedGatewayConnection(env, connection)) { @@ -1328,9 +2095,6 @@ export async function requestEmailSecretRotation( 409, ); } - if (connection.staged_secret_generation !== null) { - throw new EmailOperationError('ingress rotation already staged'); - } const unresolved = ( await tx .select({ id: emailOperations.id }) @@ -1346,6 +2110,28 @@ export async function requestEmailSecretRotation( if (unresolved) { throw new EmailOperationError(`connection operation ${unresolved.id} is unresolved`); } + const blockedRotation = ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.connection_id, connectionId), + eq(emailOperations.kind, 'rotate_secret'), + eq(emailOperations.status, 'blocked'), + eq(emailOperations.desired_generation, connection.desired_generation), + ), + ) + .orderBy(desc(emailOperations.created_at), desc(emailOperations.id)) + .limit(1) + )[0]; + if (blockedRotation) { + await resumeBlockedEmailOperationTx(tx, env, blockedRotation.id, actor); + return blockedRotation.id; + } + if (connection.staged_secret_generation !== null) { + throw new EmailOperationError('ingress rotation already staged'); + } const generation = connection.desired_generation + 1, secretGeneration = connection.active_secret_generation + 1; const encrypted = await encryptPlatformCredential( @@ -1384,30 +2170,60 @@ export async function requestEmailSecretRotation( operation_id: operationId, ordinal: i, kind: ROTATE_STEPS[i], - resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}/secret/${secretGeneration}`, - request_digest: await digest({ - kind: ROTATE_STEPS[i], - connectionId, + resource_identity: emailStepResourceIdentity( + connection, + ROTATE_STEPS[i], + null, + secretGeneration, + ), + request_digest: await emailStepRequestDigest( + env, + connection, + ROTATE_STEPS[i], generation, + null, secretGeneration, - }), + ), }); } return operationId; }); } -async function requestExistingOperation( +function requestExistingOperation( db: Db, env: Bindings, routeId: string, actor: EmailActor, kind: 'sync' | 'remove', key: string, -): Promise { - const installationId = emailInstallationId(env); - const actorScope = - actor.kind === 'system' ? 'system' : `${actor.kind}:${actor.userId}:${routeId}`; - const requestDigest = await digest({ routeId, kind, actor: actor.kind }); +): Promise; +function requestExistingOperation( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + kind: 'sync' | 'remove', + key: string, + expectedProjectId: string, +): Promise; +async function requestExistingOperation( + db: Db, + env: Bindings, + routeId: string, + actor: EmailActor, + kind: 'sync' | 'remove', + key: string, + expectedProjectId?: string, +): Promise { + const installationId = emailInstallationId(env); + const actorScope = + actor.kind === 'system' ? 'system' : `${actor.kind}:${actor.userId}:${routeId}`; + const requestDigest = await digest({ + routeId, + kind, + actor: actor.kind, + ...(expectedProjectId === undefined ? {} : { expectedProjectId }), + }); const existing = ( await db .select() @@ -1421,17 +2237,19 @@ async function requestExistingOperation( ) .limit(1) )[0]; - if (existing) { + if (existing && expectedProjectId === undefined) { if (existing.request_digest !== requestDigest) { throw new EmailOperationError('email operation key conflict'); } - return existing.id; + if (existing.status !== 'blocked') { + return existing.id; + } } return db.transaction(async (tx) => { if (kind === 'remove') { - await disableEmailDomainRouteAndDrainTx(tx, routeId); + await lockEmailPolicy(tx); } - const route = ( + let route = ( await tx .select() .from(emailDomainRoutes) @@ -1442,6 +2260,20 @@ async function requestExistingOperation( if (!route) { throw new EmailOperationError('email domain not available', 404); } + if (expectedProjectId !== undefined && route.project_id !== expectedProjectId) { + return null; + } + if (kind === 'remove') { + await disableEmailDomainRouteAndDrainTx(tx, routeId); + route = ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, routeId)) + .for('update') + .limit(1) + )[0]!; + } if (kind === 'sync' && route.desired_state !== 'active') { throw new EmailOperationError('email domain must be active before reconciliation', 409); } @@ -1456,7 +2288,15 @@ async function requestExistingOperation( const project = route.project_id ? (await tx.select().from(projects).where(eq(projects.id, route.project_id)).limit(1))[0] : null; - if (!connection || (actor.kind !== 'system' && (!project || project.status === 'deleting'))) { + const adminRemoval = + actor.kind === 'admin' && + kind === 'remove' && + route.addressing === 'custom' && + route.project_id !== null; + if ( + !connection || + (actor.kind !== 'system' && !adminRemoval && (!project || project.status === 'deleting')) + ) { throw new EmailOperationError('email domain not available', 404); } if ( @@ -1488,19 +2328,27 @@ async function requestExistingOperation( if (replay.request_digest !== requestDigest) { throw new EmailOperationError('email operation key conflict'); } + await resumeBlockedEmailOperationTx(tx, env, replay.id, actor, routeId); return replay.id; } const existingRemoval = kind === 'remove' ? ( await tx - .select({ id: emailOperations.id }) + .select() .from(emailOperations) .where( and( eq(emailOperations.route_id, routeId), eq(emailOperations.kind, 'remove'), - inArray(emailOperations.status, ['pending', 'running', 'unknown']), + or( + inArray(emailOperations.status, ['pending', 'running', 'unknown']), + and( + eq(emailOperations.status, 'blocked'), + eq(emailOperations.desired_generation, connection.desired_generation), + eq(emailOperations.route_generation, route.desired_generation), + ), + ), ), ) .orderBy(emailOperations.created_at, emailOperations.id) @@ -1508,6 +2356,19 @@ async function requestExistingOperation( )[0] : null; if (existingRemoval) { + if (existingRemoval.status === 'blocked') { + const recoveringOrphanedSystemCleanup = + actor.kind === 'admin' && + existingRemoval.actor_kind === 'system' && + (!project || project.status === 'deleting'); + await resumeBlockedEmailOperationTx( + tx, + env, + existingRemoval.id, + recoveringOrphanedSystemCleanup ? { kind: 'system' } : actor, + routeId, + ); + } return existingRemoval.id; } const unresolved = ( @@ -1526,6 +2387,27 @@ async function requestExistingOperation( if (unresolved && kind !== 'remove') { throw new EmailOperationError(`connection operation ${unresolved.id} is unresolved`); } + if (kind === 'sync') { + const blocked = ( + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.route_id, routeId), + inArray(emailOperations.kind, ['setup', 'sync']), + eq(emailOperations.status, 'blocked'), + eq(emailOperations.desired_generation, connection.desired_generation), + ), + ) + .orderBy(desc(emailOperations.created_at), desc(emailOperations.id)) + .limit(1) + )[0]; + if (blocked) { + await resumeBlockedEmailOperationTx(tx, env, blocked.id, actor, routeId); + return blocked.id; + } + } const opId = generateId('eop'); const generation = unresolved ? connection.desired_generation @@ -1541,6 +2423,7 @@ async function requestExistingOperation( installation_id: installationId, connection_id: connection.id, route_id: routeId, + route_generation: route.desired_generation, actor_kind: actor.kind, actor_user_id: actor.kind === 'system' ? null : actor.userId, actor_scope: actorScope, @@ -1557,17 +2440,21 @@ async function requestExistingOperation( : SYNC_STEPS : REMOVE_STEPS; for (let i = 0; i < steps.length; i++) { + const secretGeneration = emailStepSecretGeneration(kind, connection, steps[i]); await tx.insert(emailOperationSteps).values({ id: generateId('estep'), operation_id: opId, ordinal: i, kind: steps[i], - resource_identity: `${connection.account_id}/${connection.zone_id}/${connection.ingress_worker_name}`, - request_digest: await digest({ - kind: steps[i], - connectionId: connection.id, + resource_identity: emailStepResourceIdentity(connection, steps[i], route, secretGeneration), + request_digest: await emailStepRequestDigest( + env, + connection, + steps[i], generation, - }), + route, + secretGeneration, + ), }); } return opId; @@ -1578,6 +2465,28 @@ async function requestExistingOperation( export async function runEmailOperation(db: Db, env: Bindings, operationId: string): Promise { for (let iteration = 0; iteration < 12; iteration++) { const claim = await db.transaction(async (tx) => { + const snapshot = ( + await tx.select().from(emailOperations).where(eq(emailOperations.id, operationId)).limit(1) + )[0]; + if ( + !snapshot || + snapshot.status === 'completed' || + snapshot.status === 'blocked' || + snapshot.status === 'unknown' + ) { + return null; + } + // Every operation driver and recovery path locks the connection before + // the operation and step. Read the operation once without a lock only to + // discover that connection, then re-read and validate it under the lock. + const connection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, snapshot.connection_id)) + .for('update') + .limit(1) + )[0]; const op = ( await tx .select() @@ -1586,9 +2495,20 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri .for('update') .limit(1) )[0]; - if (!op || op.status === 'completed' || op.status === 'blocked' || op.status === 'unknown') { + if ( + !op || + op.connection_id !== snapshot.connection_id || + op.route_id !== snapshot.route_id || + op.desired_generation !== snapshot.desired_generation || + op.status === 'completed' || + op.status === 'blocked' || + op.status === 'unknown' + ) { return null; } + if (!connection || connection.desired_generation !== op.desired_generation) { + throw new EmailOperationError('email operation generation changed'); + } if (op.kind === 'remove') { // Removal intents form a durable chain. A later sibling removal may // wait for this one, but must never stop it from making progress. @@ -1613,17 +2533,6 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri } } } - const connection = ( - await tx - .select() - .from(emailZoneConnections) - .where(eq(emailZoneConnections.id, op.connection_id)) - .for('update') - .limit(1) - )[0]; - if (!connection || connection.desired_generation !== op.desired_generation) { - throw new EmailOperationError('email operation generation changed'); - } const steps = await tx .select() .from(emailOperationSteps) @@ -1641,7 +2550,16 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri // A second scheduler must leave the current driver alone. A crashed // driver is fenced only after its lease ages out; its provider write // is never replayed merely because the lease expired. - if (step.started_at && Date.now() - Date.parse(step.started_at) < 5 * 60_000) { + const lease = ( + await tx + .select({ + expired: sql`${emailOperationSteps.started_at} IS NULL OR ${emailOperationSteps.started_at} <= now() - interval '5 minutes'`, + }) + .from(emailOperationSteps) + .where(eq(emailOperationSteps.id, step.id)) + .limit(1) + )[0]; + if (!lease?.expired) { return null; } await tx @@ -1695,6 +2613,38 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri return null; } } + const [sibling] = await tx + .select({ id: emailDomainRoutes.id }) + .from(emailDomainRoutes) + .where( + and( + eq(emailDomainRoutes.connection_id, connection.id), + ne(emailDomainRoutes.desired_state, 'removed'), + ne(emailDomainRoutes.id, op.route_id), + ), + ) + .limit(1); + const retained = sibling + ? { retainedForSibling: true } + : !canManageConnection( + { kind: op.actor_kind, userId: op.actor_user_id ?? '' } as EmailActor, + connection, + ) + ? { retainedForManager: true } + : null; + if (retained) { + // Local retention is atomic with its outcome, so a driver crash cannot + // turn a step that never called the provider into an unknown write. + await tx + .update(emailOperationSteps) + .set({ status: 'confirmed', outcome: retained, finished_at: sql`now()` }) + .where(eq(emailOperationSteps.id, step.id)); + await tx + .update(emailOperations) + .set({ status: 'pending', current_step: step.kind, updated_at: sql`now()` }) + .where(eq(emailOperations.id, operationId)); + return { local: true }; + } } await tx .update(emailOperationSteps) @@ -1709,14 +2659,11 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri if (!claim) { return; } + if ('local' in claim) { + continue; + } try { - const outcome = await executeEmailStep( - db, - env, - claim.op, - claim.connection, - claim.step.kind as StepKind, - ); + const outcome = await executeEmailStep(db, env, claim.op, claim.connection, claim.step); await db.transaction(async (tx) => { const current = ( await tx @@ -1729,6 +2676,26 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri if (!current || current.desired_generation !== claim.op.desired_generation) { return; } + const currentOperation = ( + await tx + .select({ + status: emailOperations.status, + connectionId: emailOperations.connection_id, + desiredGeneration: emailOperations.desired_generation, + }) + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .for('update') + .limit(1) + )[0]; + if ( + !currentOperation || + !['running', 'unknown'].includes(currentOperation.status) || + currentOperation.connectionId !== current.id || + currentOperation.desiredGeneration !== claim.op.desired_generation + ) { + return; + } const updated = await tx .update(emailOperationSteps) .set({ @@ -1778,9 +2745,44 @@ export async function runEmailOperation(db: Db, env: Bindings, operationId: stri // A write may have reached Cloudflare even if fetch failed. Stop until // an explicit probe or operator decision establishes its outcome. const detail = error instanceof Error ? error.message : String(error); - const blocked = error instanceof EmailOperationError && error.status < 500; + const blocked = + error instanceof EmailOperationPreflightError || + ((error instanceof EmailOperationError || error instanceof CloudflareApiError) && + error.status < 500 && + error.status !== 408); const status = blocked ? 'blocked' : 'unknown'; await db.transaction(async (tx) => { + const current = ( + await tx + .select({ desiredGeneration: emailZoneConnections.desired_generation }) + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, claim.connection.id)) + .for('update') + .limit(1) + )[0]; + if (!current || current.desiredGeneration !== claim.op.desired_generation) { + return; + } + const currentOperation = ( + await tx + .select({ + status: emailOperations.status, + connectionId: emailOperations.connection_id, + desiredGeneration: emailOperations.desired_generation, + }) + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .for('update') + .limit(1) + )[0]; + if ( + !currentOperation || + !['running', 'unknown'].includes(currentOperation.status) || + currentOperation.connectionId !== claim.connection.id || + currentOperation.desiredGeneration !== claim.op.desired_generation + ) { + return; + } const updated = await tx .update(emailOperationSteps) .set({ @@ -1825,17 +2827,44 @@ async function executeEmailStep( env: Bindings, op: typeof emailOperations.$inferSelect, connection: typeof emailZoneConnections.$inferSelect, - kind: StepKind, + step: typeof emailOperationSteps.$inferSelect, ): Promise> { - const route = op.route_id - ? ( - await db - .select() - .from(emailDomainRoutes) - .where(eq(emailDomainRoutes.id, op.route_id)) - .limit(1) - )[0] - : null; + const kind = step.kind as StepKind; + const route = await emailOperationPreflight(async () => + op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null, + ); + if (isOperatorRecoverableWriteStep(kind) || kind === 'secret_retire') { + const { expectedIdentity, expectedDigest } = await emailOperationPreflight(async () => ({ + expectedIdentity: emailStepResourceIdentity( + connection, + kind, + route, + emailStepSecretGeneration(op.kind, connection, kind), + ), + expectedDigest: await emailStepRequestDigest( + env, + connection, + kind, + op.desired_generation, + route, + emailStepSecretGeneration(op.kind, connection, kind), + ), + })); + if (step.resource_identity !== expectedIdentity || step.request_digest !== expectedDigest) { + throw new EmailOperationError( + 'email operation intent does not match the current relay implementation', + 409, + ); + } + } if (kind === 'route_disable') { return { disabled: true }; } @@ -1864,7 +2893,37 @@ async function executeEmailStep( } return { published: false, queued: true }; } - const credential = await credentialFor(env, db, connection); + if (kind === 'secret_retire') { + if ( + (op.kind !== 'setup' && op.kind !== 'sync') || + connection.staged_secret_generation === null + ) { + throw new EmailOperationError('staged ingress generation unavailable'); + } + const retiredGeneration = connection.staged_secret_generation; + const retired = await db + .update(emailZoneConnections) + .set({ + staged_secret_generation: null, + staged_secret_ciphertext: null, + staged_secret_iv: null, + staged_secret_key_version: null, + updated_at: sql`now()`, + }) + .where( + and( + eq(emailZoneConnections.id, connection.id), + eq(emailZoneConnections.desired_generation, op.desired_generation), + eq(emailZoneConnections.staged_secret_generation, retiredGeneration), + ), + ) + .returning({ id: emailZoneConnections.id }); + if (!retired.length) { + throw new EmailOperationError('staged ingress retirement lost its generation fence', 503); + } + return { retiredGeneration }; + } + const credential = await emailOperationPreflight(() => credentialFor(env, db, connection)); const client = createCfCustomerClient(credential); if (kind === 'routing_enable') { if (!route) { @@ -1896,9 +2955,8 @@ async function executeEmailStep( } if (kind === 'probe_route_enable') { if ( - !(await client.getScriptSubdomainEnabled( - connection.account_id, - connection.ingress_worker_name, + !(await emailOperationPreflight(() => + client.getScriptSubdomainEnabled(connection.account_id, connection.ingress_worker_name), )) ) { await client.enableScriptSubdomain(connection.account_id, connection.ingress_worker_name); @@ -1907,9 +2965,9 @@ async function executeEmailStep( } if (kind === 'secret_put') { const staged = op.kind === 'rotate_secret'; - const secret = staged - ? await readStagedConnectionSecret(env, connection) - : await readConnectionSecret(env, connection); + const secret = await emailOperationPreflight(() => + staged ? readStagedConnectionSecret(env, connection) : readConnectionSecret(env, connection), + ); await client.putRelaySecret(connection.account_id, connection.ingress_worker_name, secret); return { generation: staged @@ -1964,7 +3022,7 @@ async function executeEmailStep( return { generation: connection.staged_secret_generation }; } if (kind === 'catchall_ensure') { - const current = await client.getCatchAll(connection.zone_id); + const current = await emailOperationPreflight(() => client.getCatchAll(connection.zone_id)); if (current?.enabled && current.workerName !== connection.ingress_worker_name) { throw new EmailOperationError('another enabled catch-all owns this zone'); } @@ -1987,11 +3045,45 @@ async function executeEmailStep( inbound_observed_at: sql`now()`, }) .where( - and(eq(emailDomainRoutes.id, route.id), eq(emailDomainRoutes.desired_state, 'active')), + and( + eq(emailDomainRoutes.id, route.id), + eq(emailDomainRoutes.connection_id, connection.id), + eq(emailDomainRoutes.desired_generation, route.desired_generation), + eq(emailDomainRoutes.desired_state, 'active'), + ), ); throw new EmailOperationError(issue); } - await db.transaction(async (tx) => { + const observed = await db.transaction(async (tx) => { + // Route-bearing transactions always lock route before connection. Re-read + // both generations because the provider probe ran outside this transaction. + const currentRoute = ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, route.id)) + .for('update') + .limit(1) + )[0]; + if ( + !currentRoute || + currentRoute.connection_id !== connection.id || + currentRoute.desired_generation !== route.desired_generation || + currentRoute.desired_state !== 'active' + ) { + return false; + } + const currentConnection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connection.id)) + .for('update') + .limit(1) + )[0]; + if (!currentConnection || currentConnection.desired_generation !== op.desired_generation) { + return false; + } await tx .update(emailZoneConnections) .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) @@ -2001,14 +3093,20 @@ async function executeEmailStep( eq(emailZoneConnections.desired_generation, op.desired_generation), ), ); - if (route && route.desired_state === 'active') { - await tx - .update(emailDomainRoutes) - .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) - .where(eq(emailDomainRoutes.id, route.id)); - } + await tx + .update(emailDomainRoutes) + .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) + .where( + and( + eq(emailDomainRoutes.id, route.id), + eq(emailDomainRoutes.connection_id, connection.id), + eq(emailDomainRoutes.desired_generation, route.desired_generation), + eq(emailDomainRoutes.desired_state, 'active'), + ), + ); + return true; }); - return { ready: true }; + return observed ? { ready: true } : { ready: false, stale: true }; } if (kind === 'sending_onboard') { if (!route || route.desired_state !== 'active') { @@ -2016,8 +3114,21 @@ async function executeEmailStep( } try { await client.onboardSending(connection.zone_id, route.domain); - } catch { - if (!(await sendingOnboardedReadback(client, connection.zone_id, route.domain))) { + } catch (error) { + let onboarded: boolean; + try { + onboarded = await sendingOnboardedReadback(client, connection.zone_id, route.domain); + } catch { + // A failed probe cannot narrow the original write outcome. Preserve the + // original error so an uncertain POST remains behind operator recovery. + throw error; + } + if (!onboarded) { + const definitiveRefusal = + error instanceof CloudflareApiError && error.status < 500 && error.status !== 408; + if (!definitiveRefusal) { + throw error; + } await db .update(emailDomainRoutes) .set({ @@ -2025,52 +3136,39 @@ async function executeEmailStep( outbound_reason: 'Cloudflare Sending onboarding unavailable', outbound_observed_at: sql`now()`, }) - .where(eq(emailDomainRoutes.id, route.id)); + .where( + and( + eq(emailDomainRoutes.id, route.id), + eq(emailDomainRoutes.connection_id, connection.id), + eq(emailDomainRoutes.desired_generation, route.desired_generation), + eq(emailDomainRoutes.desired_state, 'active'), + ), + ); return { verifiedOnly: true }; } } await db .update(emailDomainRoutes) .set({ outbound_status: 'ready', outbound_reason: null, outbound_observed_at: sql`now()` }) - .where(eq(emailDomainRoutes.id, route.id)); + .where( + and( + eq(emailDomainRoutes.id, route.id), + eq(emailDomainRoutes.connection_id, connection.id), + eq(emailDomainRoutes.desired_state, 'active'), + eq(emailDomainRoutes.desired_generation, route.desired_generation), + ), + ); return { ready: true }; } if (kind === 'catchall_detach' || kind === 'ingress_delete') { - // Every non-removed sibling, including a disabled assignment awaiting - // reconciliation, retains the shared zone resources. This check is - // repeated at each destructive provider step. - const sibling = ( - await db - .select({ id: emailDomainRoutes.id }) - .from(emailDomainRoutes) - .where( - and( - eq(emailDomainRoutes.connection_id, connection.id), - ne(emailDomainRoutes.desired_state, 'removed'), - ...(route ? [ne(emailDomainRoutes.id, route.id)] : []), - ), - ) - .limit(1) - )[0]; - if (sibling) { - return { retainedForSibling: true }; - } - if ( - !canManageConnection( - { kind: op.actor_kind, userId: op.actor_user_id ?? '' } as EmailActor, - connection, - ) - ) { - return { retainedForManager: true }; - } if (kind === 'catchall_detach') { - const current = await client.getCatchAll(connection.zone_id); + const current = await emailOperationPreflight(() => client.getCatchAll(connection.zone_id)); if (current?.enabled && current.workerName === connection.ingress_worker_name) { await client.resetCatchAll(connection.zone_id); } return { detached: true }; } - const current = await client.getCatchAll(connection.zone_id); + const current = await emailOperationPreflight(() => client.getCatchAll(connection.zone_id)); if (current?.enabled && current.workerName === connection.ingress_worker_name) { throw new EmailOperationError('owned catch-all still targets ingress'); } @@ -2106,6 +3204,438 @@ export async function reconcilePendingEmailOperations( return rows.length; } +export type EmailOperationRecoveryFence = { + operationId: string; + stepId: string; + step: OperatorRecoverableWriteStep; + attempt: number; + requestDigest: string; + resourceIdentity: string; + connectionId: string; + desiredGeneration: number; + routeId: string | null; + routeDesiredGeneration: number | null; + startedAt: string; + eligibleAt: string; +}; + +async function supersedingRemovalId( + db: DbOrTx, + operation: typeof emailOperations.$inferSelect, + route: typeof emailDomainRoutes.$inferSelect | null, + lock = false, +): Promise { + if ( + !route || + (operation.kind !== 'setup' && operation.kind !== 'sync') || + operation.route_id !== route.id || + operation.route_generation === null || + route.desired_state === 'active' + ) { + return null; + } + const query = db + .select({ id: emailOperations.id }) + .from(emailOperations) + .where( + and( + eq(emailOperations.route_id, route.id), + eq(emailOperations.route_generation, route.desired_generation), + eq(emailOperations.kind, 'remove'), + eq(emailOperations.status, 'pending'), + eq(emailOperations.current_step, `wait:${operation.id}`), + ), + ) + .limit(1); + const [removal] = lock ? await query.for('update') : await query; + return removal?.id ?? null; +} + +async function completeSupersededEmailOperation( + tx: Tx, + operation: typeof emailOperations.$inferSelect, + removalId: string, +): Promise { + await tx + .update(emailOperationSteps) + .set({ + status: 'confirmed', + outcome: { skipped: true, supersededByRemoval: removalId }, + failure_code: null, + failure_detail: null, + finished_at: sql`now()`, + }) + .where( + and( + eq(emailOperationSteps.operation_id, operation.id), + eq(emailOperationSteps.status, 'pending'), + ), + ); +} + +async function unknownEmailOperationRecoveryFence( + db: DbOrTx, + env: Bindings, + operationId: string, + lock = false, +) { + const snapshot = ( + await db.select().from(emailOperations).where(eq(emailOperations.id, operationId)).limit(1) + )[0]; + if ( + !snapshot || + snapshot.installation_id !== emailInstallationId(env) || + snapshot.status !== 'unknown' + ) { + throw new EmailOperationError('unknown email operation not found', 404); + } + const route = snapshot.route_id + ? lock + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, snapshot.route_id)) + .for('update') + .limit(1) + )[0] + : ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, snapshot.route_id)) + .limit(1) + )[0] + : null; + const connection = lock + ? ( + await db + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, snapshot.connection_id)) + .for('update') + .limit(1) + )[0] + : ( + await db + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, snapshot.connection_id)) + .limit(1) + )[0]; + const operation = lock + ? ( + await db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, snapshot.id)) + .for('update') + .limit(1) + )[0] + : snapshot; + const step = lock + ? ( + await db + .select() + .from(emailOperationSteps) + .where( + and( + eq(emailOperationSteps.operation_id, snapshot.id), + eq(emailOperationSteps.status, 'unknown'), + ), + ) + .orderBy(emailOperationSteps.ordinal) + .for('update') + .limit(1) + )[0] + : ( + await db + .select() + .from(emailOperationSteps) + .where( + and( + eq(emailOperationSteps.operation_id, snapshot.id), + eq(emailOperationSteps.status, 'unknown'), + ), + ) + .orderBy(emailOperationSteps.ordinal) + .limit(1) + )[0]; + if ( + !connection || + !operation || + !step || + operation.status !== 'unknown' || + operation.connection_id !== snapshot.connection_id || + operation.route_id !== snapshot.route_id || + operation.route_generation !== snapshot.route_generation || + operation.desired_generation !== snapshot.desired_generation || + connection.desired_generation !== operation.desired_generation || + operation.current_step !== step.kind || + !isOperatorRecoverableWriteStep(step.kind) || + (operation.kind === 'rotate_secret' + ? operation.route_id !== null || operation.route_generation !== null || route !== null + : operation.route_id === null || + operation.route_generation === null || + !route || + route.connection_id !== connection.id || + route.id !== operation.route_id) || + !step.started_at + ) { + throw new EmailOperationError('email operation recovery fence is unavailable', 409); + } + const removalId = await supersedingRemovalId(db, operation, route, lock); + if ( + operation.route_id !== null && + !removalId && + (route!.desired_generation !== operation.route_generation || + ((operation.kind === 'setup' || operation.kind === 'sync') && + route!.desired_state !== 'active')) + ) { + throw new EmailOperationError('email operation recovery fence is unavailable', 409); + } + const intentRoute = route + ? { + id: route.id, + domain: route.domain, + desired_generation: operation.route_generation!, + } + : null; + const secretGeneration = emailStepSecretGeneration(operation.kind, connection, step.kind); + const expectedIdentity = emailStepResourceIdentity( + connection, + step.kind, + intentRoute, + secretGeneration, + ); + const expectedDigest = await emailStepRequestDigest( + env, + connection, + step.kind, + operation.desired_generation, + intentRoute, + secretGeneration, + ); + if (step.resource_identity !== expectedIdentity || step.request_digest !== expectedDigest) { + throw new EmailOperationError( + 'email operation intent does not match the current relay implementation', + 409, + ); + } + const startedAt = new Date(step.started_at); + const fence: EmailOperationRecoveryFence = { + operationId: operation.id, + stepId: step.id, + step: step.kind, + attempt: step.attempt, + requestDigest: step.request_digest, + resourceIdentity: step.resource_identity, + connectionId: connection.id, + desiredGeneration: operation.desired_generation, + routeId: route?.id ?? null, + routeDesiredGeneration: operation.route_generation, + startedAt: startedAt.toISOString(), + eligibleAt: new Date(startedAt.getTime() + EMAIL_OPERATION_RECOVERY_MIN_AGE_MS).toISOString(), + }; + return { fence, operation, step, connection, route, removalId }; +} + +export async function inspectUnknownEmailOperationRecovery( + db: Db, + env: Bindings, + operationId: string, +): Promise { + return (await unknownEmailOperationRecoveryFence(db, env, operationId)).fence; +} + +export async function resolveUnknownEmailOperation( + db: Db, + env: Bindings, + input: { + operationId: string; + stepId: string; + attempt: number; + requestDigest: string; + resourceIdentity: string; + connectionId: string; + desiredGeneration: number; + routeId: string | null; + routeDesiredGeneration: number | null; + ended: boolean; + outcome: 'applied' | 'not-applied'; + reason: string; + now?: number; + }, +): Promise<{ + operationId: string; + stepId: string; + status: 'pending' | 'completed'; + outcome: string; +}> { + if (!input.ended) { + throw new EmailOperationError('confirm the original provider execution has ended', 400); + } + if (!input.reason.trim() || input.reason.length > 500) { + throw new EmailOperationError('a bounded operator recovery reason is required', 400); + } + if (input.outcome !== 'applied' && input.outcome !== 'not-applied') { + throw new EmailOperationError('email operation recovery outcome is invalid', 400); + } + const now = input.now ?? Date.now(); + return db.transaction(async (tx) => { + const { fence, operation, step, connection, route, removalId } = + await unknownEmailOperationRecoveryFence(tx, env, input.operationId, true); + if (new Date(fence.eligibleAt).getTime() > now) { + throw new EmailOperationError( + `email operation cannot be resolved before ${fence.eligibleAt}`, + 409, + ); + } + if ( + fence.stepId !== input.stepId || + fence.attempt !== input.attempt || + fence.requestDigest !== input.requestDigest || + fence.resourceIdentity !== input.resourceIdentity || + fence.connectionId !== input.connectionId || + fence.desiredGeneration !== input.desiredGeneration || + fence.routeId !== input.routeId || + fence.routeDesiredGeneration !== input.routeDesiredGeneration + ) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + const updated = await tx + .update(emailOperationSteps) + .set( + input.outcome === 'applied' || removalId + ? { + status: 'confirmed', + outcome: { + operatorResolution: input.outcome, + reason: input.reason.trim(), + ...(removalId ? { supersededByRemoval: removalId } : {}), + }, + failure_code: null, + failure_detail: null, + finished_at: sql`now()`, + } + : { + status: 'pending', + outcome: null, + failure_code: null, + failure_detail: null, + started_at: null, + finished_at: null, + }, + ) + .where( + and( + eq(emailOperationSteps.id, step.id), + eq(emailOperationSteps.operation_id, operation.id), + eq(emailOperationSteps.status, 'unknown'), + eq(emailOperationSteps.attempt, step.attempt), + eq(emailOperationSteps.request_digest, step.request_digest), + ), + ) + .returning({ id: emailOperationSteps.id }); + if (!updated.length) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + if (input.outcome === 'applied' && step.kind === 'ingress_deploy') { + const match = /\/relay\/(\d+)$/.exec(step.resource_identity); + const relayVersion = match ? Number(match[1]) : NaN; + if (!Number.isSafeInteger(relayVersion) || relayVersion < 1) { + throw new EmailOperationError('email relay recovery identity is invalid', 409); + } + const postcondition = await tx + .update(emailZoneConnections) + .set({ ingress_version: relayVersion, updated_at: sql`now()` }) + .where( + and( + eq(emailZoneConnections.id, connection.id), + eq(emailZoneConnections.desired_generation, operation.desired_generation), + ), + ) + .returning({ id: emailZoneConnections.id }); + if (!postcondition.length) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + } + if (input.outcome === 'applied' && !removalId && step.kind === 'sending_onboard') { + if (!route || route.desired_state !== 'active') { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + const postcondition = await tx + .update(emailDomainRoutes) + .set({ + outbound_status: 'ready', + outbound_reason: null, + outbound_observed_at: sql`now()`, + updated_at: sql`now()`, + }) + .where( + and( + eq(emailDomainRoutes.id, route.id), + eq(emailDomainRoutes.connection_id, connection.id), + eq(emailDomainRoutes.desired_state, 'active'), + eq(emailDomainRoutes.desired_generation, route.desired_generation), + ), + ) + .returning({ id: emailDomainRoutes.id }); + if (!postcondition.length) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + } + if (input.outcome === 'applied' && step.kind === 'ingress_delete') { + if (!route) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + const postcondition = await tx + .update(emailZoneConnections) + .set({ inbound_status: 'disabled', inbound_observed_at: sql`now()` }) + .where( + and( + eq(emailZoneConnections.id, connection.id), + eq(emailZoneConnections.desired_generation, operation.desired_generation), + ), + ) + .returning({ id: emailZoneConnections.id }); + if (!postcondition.length) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + await forgetUnusedEmailCredential(tx, connection.id, route.id); + } + if (removalId) { + await completeSupersededEmailOperation(tx, operation, removalId); + } + const resumed = await tx + .update(emailOperations) + .set({ + status: removalId ? 'completed' : 'pending', + current_step: null, + failure_code: null, + failure_detail: null, + updated_at: sql`now()`, + }) + .where( + and( + eq(emailOperations.id, operation.id), + eq(emailOperations.status, 'unknown'), + eq(emailOperations.desired_generation, operation.desired_generation), + ), + ) + .returning({ id: emailOperations.id }); + if (!resumed.length) { + throw new EmailOperationError('email operation recovery fence changed', 409); + } + return { + operationId: operation.id, + stepId: step.id, + status: removalId ? ('completed' as const) : ('pending' as const), + outcome: input.outcome, + }; + }); +} + /** Read-only recovery for ambiguous provider writes. A result is confirmed * only where the currently observed resource proves this exact step's intent. * Script upload and routing enable remain unknown without that proof. */ @@ -2170,6 +3700,41 @@ export async function reconcileUnknownEmailOperation( ) { outcome = { generation: connection.active_secret_generation }; } + } else if (step.kind === 'secret_retire') { + const target = Number(step.resource_identity.split('/secret/')[1]); + const route = op.route_id + ? ( + await db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .limit(1) + )[0] + : null; + const intentRoute = + route && op.route_generation !== null + ? { id: route.id, domain: route.domain, desired_generation: op.route_generation } + : null; + if ( + Number.isInteger(target) && + intentRoute && + step.resource_identity === + emailStepResourceIdentity(connection, 'secret_retire', intentRoute, target) && + step.request_digest === + (await emailStepRequestDigest( + env, + connection, + 'secret_retire', + op.desired_generation, + intentRoute, + target, + )) && + (connection.staged_secret_generation === null || + connection.staged_secret_generation === target) && + connection.active_secret_generation !== target + ) { + outcome = { retiredGeneration: target }; + } } else if (step.kind === 'publish') { const route = op.route_id ? ( @@ -2264,6 +3829,19 @@ export async function reconcileUnknownEmailOperation( return false; } return db.transaction(async (tx) => { + const currentRoute = op.route_id + ? ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, op.route_id)) + .for('update') + .limit(1) + )[0] + : null; + if (op.route_id && (!currentRoute || currentRoute.connection_id !== connection.id)) { + return false; + } const current = ( await tx .select() @@ -2275,6 +3853,73 @@ export async function reconcileUnknownEmailOperation( if (!current || current.desired_generation !== op.desired_generation) { return false; } + const currentOperation = ( + await tx + .select() + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .for('update') + .limit(1) + )[0]; + if ( + !currentOperation || + currentOperation.status !== 'unknown' || + currentOperation.connection_id !== connection.id || + currentOperation.route_id !== op.route_id || + currentOperation.route_generation !== op.route_generation || + currentOperation.desired_generation !== op.desired_generation || + currentOperation.current_step !== step.kind + ) { + return false; + } + if ( + currentOperation.kind === 'rotate_secret' + ? currentOperation.route_id !== null || + currentOperation.route_generation !== null || + currentRoute !== null + : currentOperation.route_id === null || + currentOperation.route_generation === null || + !currentRoute || + currentRoute.connection_id !== connection.id + ) { + return false; + } + const removalId = await supersedingRemovalId(tx, currentOperation, currentRoute, true); + if ( + currentOperation.route_id !== null && + !removalId && + (currentRoute!.desired_generation !== currentOperation.route_generation || + ((currentOperation.kind === 'setup' || currentOperation.kind === 'sync') && + currentRoute!.desired_state !== 'active')) + ) { + return false; + } + if (step.kind === 'secret_retire' && current.staged_secret_generation !== null) { + const target = outcome.retiredGeneration; + if (typeof target !== 'number' || current.staged_secret_generation !== target) { + return false; + } + const retired = await tx + .update(emailZoneConnections) + .set({ + staged_secret_generation: null, + staged_secret_ciphertext: null, + staged_secret_iv: null, + staged_secret_key_version: null, + updated_at: sql`now()`, + }) + .where( + and( + eq(emailZoneConnections.id, current.id), + eq(emailZoneConnections.desired_generation, currentOperation.desired_generation), + eq(emailZoneConnections.staged_secret_generation, target), + ), + ) + .returning({ id: emailZoneConnections.id }); + if (!retired.length) { + return false; + } + } const updated = await tx .update(emailOperationSteps) .set({ @@ -2295,7 +3940,7 @@ export async function reconcileUnknownEmailOperation( if (!updated.length) { return false; } - if (step.kind === 'inbound_probe') { + if (!removalId && step.kind === 'inbound_probe') { await tx .update(emailZoneConnections) .set({ inbound_status: 'ready', inbound_reason: null, inbound_observed_at: sql`now()` }) @@ -2312,7 +3957,7 @@ export async function reconcileUnknownEmailOperation( ); } } - if (step.kind === 'sending_onboard' && op.route_id) { + if (!removalId && step.kind === 'sending_onboard' && op.route_id) { await tx .update(emailDomainRoutes) .set({ outbound_status: 'ready', outbound_reason: null, outbound_observed_at: sql`now()` }) @@ -2325,9 +3970,18 @@ export async function reconcileUnknownEmailOperation( .where(eq(emailZoneConnections.id, connection.id)); await forgetUnusedEmailCredential(tx, connection.id, op.route_id); } + if (removalId) { + await completeSupersededEmailOperation(tx, currentOperation, removalId); + } await tx .update(emailOperations) - .set({ status: 'pending', failure_code: null, failure_detail: null, updated_at: sql`now()` }) + .set({ + status: removalId ? 'completed' : 'pending', + current_step: removalId ? null : currentOperation.current_step, + failure_code: null, + failure_detail: null, + updated_at: sql`now()`, + }) .where(and(eq(emailOperations.id, operationId), eq(emailOperations.status, 'unknown'))); return true; }); diff --git a/platform/packages/api/src/email/domain-service.ts b/platform/packages/api/src/email/domain-service.ts index 5a9a45feb..fb8c34b05 100644 --- a/platform/packages/api/src/email/domain-service.ts +++ b/platform/packages/api/src/email/domain-service.ts @@ -11,6 +11,7 @@ import { emailDomainRoutes, emailOperations, emailZoneConnections } from './conn import { EmailOperationError, credentialFor, + EmailCredentialExpiredError, getEmailOperation, inspectEmailInboundRoute, requestEmailDomainAdd, @@ -167,6 +168,7 @@ export async function getEmailDomainStatusForProject( } const snapshot = resolved; if (snapshot.route.desired_state === 'active') { + let managementStatus: 'healthy' | 'expired' | 'probe_failed' = 'healthy'; let managementReason: string | null = null; let inboundIssue: string | null = null; let outbound: 'ready' | 'verified_only' | 'blocked' = 'blocked'; @@ -192,15 +194,55 @@ export async function getEmailDomainStatusForProject( } catch { outboundReason = 'Cloudflare Sending status could not be verified'; } - } catch { - managementReason = - 'Cloudflare routing status could not be verified; check the connection credential'; + } catch (error) { + if (error instanceof EmailCredentialExpiredError) { + managementStatus = 'expired'; + managementReason = 'Cloudflare API token has expired'; + } else { + managementStatus = 'probe_failed'; + managementReason = + 'Cloudflare routing status could not be verified; check the connection credential'; + } } await db.transaction(async (tx) => { + // Keep every route/connection mutation on the same lock order as setup, + // removal and recovery. The provider reads above may have raced a route + // transition, so validate that exact route before recording observations. + const currentRoute = ( + await tx + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, snapshot.route.id)) + .for('update') + .limit(1) + )[0]; + if ( + !currentRoute || + currentRoute.project_id !== snapshot.route.project_id || + currentRoute.connection_id !== snapshot.connection.id || + currentRoute.desired_generation !== snapshot.route.desired_generation || + currentRoute.desired_state !== 'active' + ) { + return; + } + const currentConnection = ( + await tx + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, snapshot.connection.id)) + .for('update') + .limit(1) + )[0]; + if ( + !currentConnection || + currentConnection.desired_generation !== snapshot.connection.desired_generation + ) { + return; + } const updated = await tx .update(emailZoneConnections) .set({ - management_status: managementReason ? 'probe_failed' : 'healthy', + management_status: managementStatus, management_reason: managementReason, management_observed_at: sql`now()`, }) @@ -212,7 +254,7 @@ export async function getEmailDomainStatusForProject( ) .returning({ id: emailZoneConnections.id }); // A failed credential probe does not revoke independently authenticated ingress. - if (updated.length && !managementReason) { + if (updated.length && managementStatus === 'healthy') { // Routing reads cannot replace the setup operation's ingress identity proof. const revalidateInbound = snapshot.connection.inbound_status === 'ready' && @@ -235,6 +277,8 @@ export async function getEmailDomainStatusForProject( .where( and( eq(emailDomainRoutes.id, snapshot.route.id), + eq(emailDomainRoutes.project_id, snapshot.route.project_id!), + eq(emailDomainRoutes.connection_id, snapshot.connection.id), eq(emailDomainRoutes.desired_generation, snapshot.route.desired_generation), eq(emailDomainRoutes.desired_state, 'active'), ), @@ -331,7 +375,7 @@ export async function rotateEmailIngressSecretForProject( } export async function removeEmailDomainForProject( context: Context, - project: Project, + project: Pick, rawDomain: string, actor: 'owner' | 'admin', ): Promise { diff --git a/platform/packages/api/src/email/ingress-resolution.ts b/platform/packages/api/src/email/ingress-resolution.ts index e63918651..465df364e 100644 --- a/platform/packages/api/src/email/ingress-resolution.ts +++ b/platform/packages/api/src/email/ingress-resolution.ts @@ -307,6 +307,8 @@ app.post('/resolve-ingress', async (context) => { workerName: getVersionedWorkerName(slug, deploymentId), addressing: route.addressing, domain: route.domain, + routeId: route.id, + routeGeneration: route.desired_generation, connectionId: resolved.connection.id, ...(limits ? { limits } : {}), }); diff --git a/platform/packages/api/src/email/relay-worker.ts b/platform/packages/api/src/email/relay-worker.ts index 079251d0e..b4c10f4a2 100644 --- a/platform/packages/api/src/email/relay-worker.ts +++ b/platform/packages/api/src/email/relay-worker.ts @@ -14,7 +14,7 @@ * Worker before promotion. The Worker name stays stable for its zone. */ -export const RELAY_VERSION = 6; +export const RELAY_VERSION = 7; // Baked into the upload metadata; bump with RELAY_VERSION if the source // ever depends on newer runtime behavior. @@ -35,9 +35,10 @@ export const RELAY_INGRESS_BINDING = 'VOID_EMAIL_INGRESS'; * The stream is piped through a FixedLengthStream(rawSize): * the runtime derives Content-Length from the body and IGNORES a manually * set one, so a plain ReadableStream would go out chunked — and the gateway - * rejects a length-less body before any crypto. The POST rides - * ctx.waitUntil AND is awaited: waitUntil keeps the stream alive, the - * await is what lets a non-2xx answer reject the message. The reject + * rejects a length-less body before any crypto. The pump and POST share a + * 60-second absolute deadline and abort signal; bounded waitUntil wrappers + * keep the stream alive without retaining a stuck fetch or pipe. The POST is + * also awaited so a non-2xx answer can reject the message. The reject * reason is deliberately generic — it travels back to the original sender * in a bounce. * @@ -61,7 +62,27 @@ export const RELAY_SOURCE = `export default { async email(message, env, ctx) { const requestId = crypto.randomUUID(); const { readable, writable } = new FixedLengthStream(message.rawSize); - const relay = fetch(env.VOID_EMAIL_GATEWAY_ORIGIN + '/email/ingress', { + const controller = new AbortController(); + const deadline = Date.now() + 60000; + const beforeDeadline = (run) => { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + controller.abort(); + return Promise.reject(new Error('Email gateway temporarily unavailable')); + } + const work = run(); + let timer; + return Promise.race([ + work, + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('Email gateway temporarily unavailable')); + }, remaining); + }), + ]).finally(() => clearTimeout(timer)); + }; + const relay = beforeDeadline(() => fetch(env.VOID_EMAIL_GATEWAY_ORIGIN + '/email/ingress', { method: 'POST', headers: { Authorization: 'Bearer ' + env.VOID_RELAY_SECRET, @@ -73,10 +94,22 @@ export const RELAY_SOURCE = `export default { 'X-Void-Email-To': message.to, }, body: readable, - }); - ctx.waitUntil(message.raw.pipeTo(writable)); - ctx.waitUntil(relay); - const response = await relay; + signal: controller.signal, + })); + const pump = beforeDeadline(() => message.raw.pipeTo(writable, { signal: controller.signal })); + ctx.waitUntil(pump.catch(() => {})); + ctx.waitUntil(relay.catch(() => {})); + let response; + try { + response = await relay; + } catch { + controller.abort(); + void pump.catch(() => {}); + throw new Error('Email gateway temporarily unavailable'); + } + controller.abort(); + void pump.catch(() => {}); + void response.body?.cancel().catch(() => {}); if (response.status >= 500 || response.status === 408 || response.status === 429) { throw new Error('Email gateway temporarily unavailable'); } diff --git a/platform/packages/api/src/index.ts b/platform/packages/api/src/index.ts index a3b873b83..27e517ef4 100644 --- a/platform/packages/api/src/index.ts +++ b/platform/packages/api/src/index.ts @@ -5,7 +5,7 @@ import { PLATFORM_DISABLED_KEY, PLATFORM_DISABLED_VALUE, } from '@void/platform'; -import { lt, sql } from 'drizzle-orm'; +import { eq, lt, sql } from 'drizzle-orm'; import { Hono } from 'hono'; import { adminAuthMiddleware } from './admin/middleware/auth.ts'; import { adminCsrfMiddleware } from './admin/middleware/csrf.ts'; @@ -48,6 +48,7 @@ import { } from './db.ts'; import { escapeHtml } from './email.ts'; import { pruneEmailActionHistory } from './email/admission.ts'; +import { emailDomainRoutes, emailOperations } from './email/connection-schema.ts'; import { ensureSharedEmailConnection, reconcilePendingEmailOperations, @@ -159,6 +160,8 @@ const app = new Hono() (context.req.path === '/health' || context.req.path === '/.well-known/void-platform' || context.req.path === '/internal/platform/sandbox-drain' || + (context.req.path === '/internal/platform/email-bootstrap' && + context.req.method === 'POST') || (context.req.path === '/internal/platform/domain-preflight' && context.req.method === 'POST')); const maintenanceSandboxDrain = @@ -279,6 +282,78 @@ const app = new Hono() ); }) .post('/internal/platform/domain-preflight', platformDomainPreflight) + .post('/internal/platform/email-bootstrap', async (context) => { + const healthProbeToken = context.env.PLATFORM_HEALTH_PROBE_TOKEN; + if ( + !healthProbeToken || + context.req.header('X-Void-Platform-Probe') !== healthProbeToken || + !context.env.PLATFORM_INSTALLATION_ID || + !getPlatformCapabilities(context.env).email + ) { + return context.json({ error: 'not found' }, 404); + } + let operationId: string | null = null; + try { + const db = context.get('db'); + operationId = await ensureSharedEmailConnection(db, context.env); + if (!operationId) { + return context.json({ version: 1, state: 'unconfigured' }, 503); + } + await runEmailOperation(db, context.env, operationId); + const operation = ( + await db + .select({ + currentStep: emailOperations.current_step, + failureCode: emailOperations.failure_code, + routeId: emailOperations.route_id, + status: emailOperations.status, + }) + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .limit(1) + )[0]; + const route = operation?.routeId + ? ( + await db + .select({ + desiredState: emailDomainRoutes.desired_state, + inboundStatus: emailDomainRoutes.inbound_status, + }) + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, operation.routeId)) + .limit(1) + )[0] + : null; + if ( + operation?.status !== 'completed' || + route?.desiredState !== 'active' || + route.inboundStatus !== 'ready' + ) { + return context.json( + { + version: 1, + state: 'incomplete', + operationId, + operationStatus: operation?.status ?? 'missing', + currentStep: operation?.currentStep ?? null, + failureCode: operation?.failureCode ?? null, + }, + 503, + ); + } + return context.json({ version: 1, state: 'ready', operationId }); + } catch (error) { + console.error('[api] shared email installer bootstrap failed', error); + return context.json( + { + version: 1, + state: 'failed', + ...(operationId ? { operationId, operationStatus: 'failed' } : {}), + }, + 503, + ); + } + }) .get('/internal/platform/sandbox-drain', async (context) => { const healthProbeToken = context.env.PLATFORM_HEALTH_PROBE_TOKEN; if (!healthProbeToken || context.req.header('X-Void-Platform-Probe') !== healthProbeToken) { diff --git a/platform/packages/api/src/middleware/platform-access.ts b/platform/packages/api/src/middleware/platform-access.ts index b8f008d08..bfc913b9c 100644 --- a/platform/packages/api/src/middleware/platform-access.ts +++ b/platform/packages/api/src/middleware/platform-access.ts @@ -13,6 +13,11 @@ function internallyAuthenticated(method: string, path: string): boolean { ) || path === '/internal/revalidate' || path === '/internal/email/domain-credential' || + path === '/internal/email/probe-ingress' || + path === '/internal/email/resolve-ingress' || + /^\/internal\/email\/actions\/(?:admit|receipts(?:\/(?:claim|complete))?|[^/]+\/(?:start|finish|status))$/.test( + path, + ) || path === '/internal/github-webhook') ); } @@ -59,6 +64,7 @@ export const platformAccessProtection: MiddlewareHandler = async (contex (probe && ((path === '/health' && method === 'GET') || (path === '/internal/platform/sandbox-drain' && method === 'GET') || + (path === '/internal/platform/email-bootstrap' && method === 'POST') || (path === '/internal/platform/domain-preflight' && method === 'POST'))) ) { return next(); diff --git a/platform/packages/api/src/operator/audit.ts b/platform/packages/api/src/operator/audit.ts index 8ab924e7f..e32cd22bd 100644 --- a/platform/packages/api/src/operator/audit.ts +++ b/platform/packages/api/src/operator/audit.ts @@ -5,7 +5,7 @@ import type { ApiEnv } from '../env.ts'; import { operatorEvents } from '../schema.ts'; import { dryRun, OperatorError, pagination, readBody } from './common.ts'; -const WORKER_NAMES = ['dispatch', 'dashboard', 'api', 'tail', 'proxy'] as const; +const WORKER_NAMES = ['dispatch', 'dashboard', 'api', 'tail', 'proxy', 'email-gateway'] as const; function boundedString(value: unknown, maximum: number, lowerCase = false) { if (typeof value !== 'string' || !value.trim() || value.length > maximum) { @@ -90,6 +90,17 @@ function auditTarget( if (segments[0] === 'projects' && id && segments[2] === 'delete') { return JSON.stringify({ projectId: id }); } + if (segments[0] === 'email' && segments[1] === 'operations' && segments[3] === 'resolve') { + return JSON.stringify({ + operationId: pathIdentifier(segments[2]), + stepId: boundedString(body.stepId, 128), + attempt: typeof body.attempt === 'number' ? body.attempt : undefined, + requestDigest: boundedString(body.requestDigest, 128), + outcome: boundedString(body.outcome, 32), + ended: body.ended === true, + reason: boundedString(body.reason, 500), + }); + } if (segments[0] === 'signup') { if (segments[1] === 'restrict' || segments[1] === 'open') { return JSON.stringify({ restrictionsEnabled: segments[1] === 'restrict' }); @@ -149,16 +160,28 @@ function auditTarget( if (segments[1] === 'domains' && domain && segments[3] === 'sync') { return JSON.stringify({ domain }); } + if (segments[1] === 'domains' && domain && segments[3] === 'rotate-secret') { + return JSON.stringify({ domain }); + } if (segments[1] === 'domains' && domain && segments[3] === 'remove') { return JSON.stringify({ domain, force: body.force === true }); } const project = pathIdentifier(segments[2]); - if (segments[1] === 'projects' && project && segments[3] === 'limit') { - return JSON.stringify({ - project, - monthly: boundedString(body.monthly, 16), - burst: boundedString(body.burst, 16), - }); + if (segments[1] === 'projects' && project) { + if (segments[3] === 'limit') { + return JSON.stringify({ + project, + monthly: boundedString(body.monthly, 16), + burst: boundedString(body.burst, 16), + }); + } + if (segments[3] === 'suspend') { + return JSON.stringify({ project, suspended: body.suspended === true }); + } + const destinationId = boundedString(segments[4], 128); + if (segments[3] === 'destinations' && destinationId && segments[5] === 'remove') { + return JSON.stringify({ project, destinationId }); + } } } if (segments[0] === 'system' && segments[1] === 'backfill-queue-tokens') { diff --git a/platform/packages/api/src/operator/email-routes.ts b/platform/packages/api/src/operator/email-routes.ts index 3c8d71a3c..479001f4a 100644 --- a/platform/packages/api/src/operator/email-routes.ts +++ b/platform/packages/api/src/operator/email-routes.ts @@ -11,11 +11,18 @@ import { import { EMAIL_ATTEMPT_RECOVERY_MIN_AGE_MS, EmailAdmissionError, + getProjectEmailLogs, resolveEmailUnresolvedAttempt, setProjectEmailLimits, } from '../email/admission.ts'; import { lookupMxOverDns } from '../email/cf-domain-probes.ts'; import { emailDomainRoutes, emailZoneConnections } from '../email/connection-schema.ts'; +import { + EmailOperationError, + inspectUnknownEmailOperationRecovery, + replaceBlockedSystemEmailCleanupCredential, + resolveUnknownEmailOperation, +} from '../email/connection-service.ts'; import { MAX_DOMAIN_LENGTH, isValidEmailDomain, @@ -25,6 +32,7 @@ import { addEmailDomainForProject, getEmailDomainRowByDomain, getEmailDomainStatusForProject, + MAX_CREDENTIAL_LENGTH, removeEmailDomainForProject, rotateEmailIngressSecretForProject, serializeEmailRoute, @@ -240,6 +248,27 @@ emailOperatorRoutes.post('/email/projects/:project/limit', async (context) => { return context.json(result, 'ok' in result && result.ok === false ? 207 : 200); }); +emailOperatorRoutes.get('/email/projects/:project/logs', async (context) => { + const { page, limit, offset } = pagination(context); + const selector = context.req.param('project'); + if (!selector || selector.length > 128) { + throw new OperatorError( + 400, + 'Project ID or slug must be at most 128 characters.', + 'invalid_argument', + ); + } + const db = context.get('db'); + const project = (await getProject(db, selector)) ?? (await getProjectBySlug(db, selector)); + const projectId = project?.id ?? selector; + return context.json({ + projectId, + page, + limit, + ...(await getProjectEmailLogs(db, projectId, limit, offset)), + }); +}); + emailOperatorRoutes.get('/email/attempts', async (context) => { const { page, limit, offset } = pagination(context); const db = context.get('db'); @@ -348,6 +377,117 @@ emailOperatorRoutes.post('/email/attempts/:id/resolve', async (context) => { } }); +emailOperatorRoutes.post('/email/operations/:id/resolve', async (context) => { + const body = await readBody(context); + const id = context.req.param('id'); + const reason = stringField(body, 'reason', { maxLength: 500 }); + const outcome = stringField(body, 'outcome', { maxLength: 32 }); + if (outcome !== 'applied' && outcome !== 'not-applied') { + throw new OperatorError(400, 'Outcome must be applied or not-applied.', 'invalid_argument'); + } + if (body.ended !== true) { + throw new OperatorError( + 400, + 'Confirm the original provider execution has ended with --ended.', + 'invalid_argument', + ); + } + const db = context.get('db'); + let fence; + try { + fence = await inspectUnknownEmailOperationRecovery(db, context.env, id); + } catch (error) { + if (error instanceof EmailOperationError) { + throw new OperatorError( + error.status === 404 ? 404 : error.status === 400 ? 400 : 409, + error.message, + error.status === 404 ? 'not_found' : 'invalid_state', + ); + } + throw error; + } + if (new Date(fence.eligibleAt).getTime() > Date.now()) { + throw new OperatorError( + 409, + `Email operation cannot be resolved before ${fence.eligibleAt}.`, + 'operation_too_recent', + ); + } + const action = 'email.operation.resolve'; + const target = { ...fence, outcome }; + if (dryRun(body)) { + return context.json( + preview(action, target, { + reason, + effect: + outcome === 'applied' + ? 'Confirm the exact provider write and continue from the next step without replaying it.' + : 'Return the exact provider write to pending so the same fenced step can be retried.', + }), + ); + } + const stepId = stringField(body, 'stepId', { maxLength: 128 }); + const requestDigest = stringField(body, 'requestDigest', { maxLength: 128 }); + const resourceIdentity = stringField(body, 'resourceIdentity', { maxLength: 500 }); + const connectionId = stringField(body, 'connectionId', { maxLength: 128 }); + const attempt = body.attempt; + if (typeof attempt !== 'number' || !Number.isSafeInteger(attempt) || attempt < 1) { + throw new OperatorError(400, 'Attempt must be a positive integer.', 'invalid_argument'); + } + const desiredGeneration = body.desiredGeneration; + if ( + typeof desiredGeneration !== 'number' || + !Number.isSafeInteger(desiredGeneration) || + desiredGeneration < 1 + ) { + throw new OperatorError( + 400, + 'Desired generation must be a positive integer.', + 'invalid_argument', + ); + } + const routeId = body.routeId === null ? null : stringField(body, 'routeId', { maxLength: 128 }); + const routeDesiredGeneration = body.routeDesiredGeneration; + if ( + routeDesiredGeneration !== null && + (typeof routeDesiredGeneration !== 'number' || + !Number.isSafeInteger(routeDesiredGeneration) || + routeDesiredGeneration < 1) + ) { + throw new OperatorError( + 400, + 'Route desired generation must be a positive integer or null.', + 'invalid_argument', + ); + } + try { + const result = await resolveUnknownEmailOperation(db, context.env, { + operationId: id, + stepId, + attempt, + requestDigest, + resourceIdentity, + connectionId, + desiredGeneration, + routeId, + routeDesiredGeneration, + ended: true, + outcome, + reason, + }); + return context.json({ action, target, ...result }); + } catch (error) { + if (error instanceof EmailOperationError) { + throw new OperatorError( + error.status === 404 ? 404 : error.status === 400 ? 400 : 409, + error.message, + error.status === 404 ? 'not_found' : 'invalid_state', + ); + } + throw error; + } +}); + // --------------------------------------------------------------------------- // Administrator-managed domains. The operations are the owner routes' own // (email/domain-service.ts); this layer resolves the project for the @@ -369,16 +509,9 @@ async function operatorResult( : 'The email domain operation failed.'; throw new OperatorError(response.status, message, 'email_domain_error', body); } - // A kept row after a failed destructive step answers 200 with `ok: false` - // (the owner contract), and a setup or sync that ended on a Cloudflare - // failure answers 200 with the row in a failed state. Both surface as a - // top-level `ok: false` so the audit records a failed mutation and the - // CLI reports the partial result. - const failed = - body.ok === false || - body.status === 'failed' || - body.status === 'token_revoked' || - body.status === 'token_expired'; + // Owner routes return durable operation state with HTTP 200. The operator + // contract also needs a failure signal for its audit log and CLI exit status. + const failed = body.ok === false || body.operationStatus !== 'completed'; return { action, target, ...(failed ? { ok: false } : {}), domain: body }; } @@ -409,6 +542,19 @@ async function requireDomainRow(db: Db, raw: string) { return { domain, row, project }; } +async function requireRemovableDomainRow(db: Db, raw: string) { + const domain = requireDomain(raw); + const row = await getEmailDomainRowByDomain(db, domain); + if (!row) { + throw new OperatorError(404, 'Email domain not found.'); + } + if (!row.project_id) { + throw new OperatorError(404, 'Project not found.'); + } + const projectId = row.project_id; + return { domain, row, projectId, project: await getProject(db, projectId) }; +} + export async function listOperatorEmailDomains(context: Context, selector?: string) { const db = context.get('db'); const project = selector ? await resolveProject(db, selector) : null; @@ -533,20 +679,46 @@ export async function removeOperatorEmailDomain( context: Context, rawDomain: string, dryRunRequested = false, + apiToken?: string, ) { - const { domain, row, project } = await requireDomainRow(context.get('db'), rawDomain); + const { domain, row, projectId, project } = await requireRemovableDomainRow( + context.get('db'), + rawDomain, + ); const action = 'email.domain.remove'; - const target = { domain, projectId: project.id, slug: project.slug }; + const target = { + domain, + projectId, + slug: project?.slug ?? null, + ...(apiToken ? { credentialReplacement: true } : {}), + }; if (dryRunRequested) { return preview(action, target, { status: row.inbound_status, managed_by: row.managed_by, connection_id: row.connection_id, - effect: 'Disables this assignment; shared ingress remains while sibling domains use it.', + effect: apiToken + ? 'Verifies the replacement scoped token and resumes the retained blocked project cleanup operation.' + : 'Disables this assignment; shared ingress remains while sibling domains use it.', }); } + if (apiToken) { + try { + await replaceBlockedSystemEmailCleanupCredential( + context.get('db'), + context.env, + row.id, + apiToken, + ); + } catch (error) { + if (error instanceof EmailOperationError) { + throw new OperatorError(error.status, error.message, 'email_domain_error'); + } + throw error; + } + } return operatorResult( - await removeEmailDomainForProject(context, project, domain, 'admin'), + await removeEmailDomainForProject(context, { id: projectId }, domain, 'admin'), action, target, ); @@ -614,6 +786,12 @@ emailOperatorRoutes.post('/email/domains/:domain/rotate-secret', async (context) emailOperatorRoutes.post('/email/domains/:domain/remove', async (context) => { const body = await readBody(context); return context.json( - await removeOperatorEmailDomain(context, context.req.param('domain'), dryRun(body)), + await removeOperatorEmailDomain( + context, + context.req.param('domain'), + dryRun(body), + stringField(body, 'apiToken', { optional: true, maxLength: MAX_CREDENTIAL_LENGTH }) || + undefined, + ), ); }); diff --git a/platform/packages/api/src/provisioning/cleanup.ts b/platform/packages/api/src/provisioning/cleanup.ts index 9c01dea1d..2253821aa 100644 --- a/platform/packages/api/src/provisioning/cleanup.ts +++ b/platform/packages/api/src/provisioning/cleanup.ts @@ -1,4 +1,4 @@ -import { sql as drizzleSql, and, eq, notInArray } from 'drizzle-orm'; +import { sql as drizzleSql, and, eq, ne, notInArray } from 'drizzle-orm'; import type { Context } from 'hono'; import { deleteProjectAssets, deleteWorkerBundle } from '../assets.ts'; import { DEFAULT_DISPATCH_NAMESPACE } from '../constants.ts'; @@ -16,7 +16,7 @@ import { terminateBuildsForProject, } from '../db.ts'; import { drainProjectEmailAdmissions } from '../email/admission.ts'; -import { emailDomainRoutes } from '../email/connection-schema.ts'; +import { emailDomainRoutes, emailZoneConnections } from '../email/connection-schema.ts'; import { requestEmailDomainRemove, runEmailOperation } from '../email/connection-service.ts'; import type { ApiEnv } from '../env.ts'; import { cancelContainerBuildDos } from '../github/cancel-builds.ts'; @@ -569,7 +569,31 @@ async function cleanupProjectEmailAssignments( .where(eq(emailDomainRoutes.project_id, projectId)); for (const assignment of assignments) { if (assignment.desired_state === 'removed') { - continue; + // An administrator may remove an owner-managed assignment while leaving + // its connection resources for the manager. Project teardown inherits + // cleanup authority, but only after the last live sibling is gone. + const [connection] = await db + .select({ id: emailZoneConnections.id, credentialId: emailZoneConnections.credential_id }) + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, assignment.connection_id)) + .limit(1); + if (!connection?.credentialId) { + continue; + } + const [sibling] = await db + .select({ id: emailDomainRoutes.id }) + .from(emailDomainRoutes) + .where( + and( + eq(emailDomainRoutes.connection_id, connection.id), + ne(emailDomainRoutes.id, assignment.id), + ne(emailDomainRoutes.desired_state, 'removed'), + ), + ) + .limit(1); + if (sibling) { + continue; + } } // The durable intent must exist before the project can cascade away. // A provider failure after that point is safe to reconcile later. @@ -579,7 +603,11 @@ async function cleanupProjectEmailAssignments( assignment.id, { kind: 'system' }, `teardown:${projectId}:${assignment.id}`, + projectId, ); + if (!opId) { + continue; + } try { await runEmailOperation(db, context.env, opId); } catch (error) { diff --git a/platform/packages/api/src/routes/internal-email-actions.ts b/platform/packages/api/src/routes/internal-email-actions.ts index c21703518..156a7f28a 100644 --- a/platform/packages/api/src/routes/internal-email-actions.ts +++ b/platform/packages/api/src/routes/internal-email-actions.ts @@ -4,8 +4,8 @@ import { admitEmailAction, claimRelayedEmailReceipt, completeRelayedEmailReceipt, + type EmailReceiptRouteFence, EmailAdmissionError, - getEmailAction, recordEmailReceipt, transitionEmailRecipients, } from '../email/admission.ts'; @@ -20,6 +20,7 @@ app.use('*', async (context, next) => { return context.json({ error: 'invalid internal auth' }, 403); } if (Number(context.req.header('content-length')) > 32_768) { + void context.req.raw.body?.cancel().catch(() => {}); return context.json({ error: 'action request too large' }, 413); } const reader = context.req.raw.body?.getReader(); @@ -28,35 +29,46 @@ app.use('*', async (context, next) => { } const chunks: Array = []; let size = 0; - let timedOut = false; - const deadline = setTimeout(() => { - timedOut = true; - void reader.cancel().catch(() => {}); - }, 5_000); + const deadline = Date.now() + 5_000; try { for (;;) { - const { done, value } = await reader.read(); - if (timedOut) { - return context.json({ error: 'action request timed out' }, 408); + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('action request timed out'); } + let timer: ReturnType | undefined; + const { done, value } = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('action request timed out')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); if (done) { break; } size += value.byteLength; if (size > 32_768) { - await reader.cancel(); + void reader.cancel().catch(() => {}); return context.json({ error: 'action request too large' }, 413); } chunks.push(value); } } catch (error) { - if (timedOut) { + if (error instanceof Error && error.message === 'action request timed out') { return context.json({ error: 'action request timed out' }, 408); } throw error; } finally { - clearTimeout(deadline); - reader.releaseLock(); + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } } const bytes = new Uint8Array(size); let offset = 0; @@ -91,6 +103,27 @@ function status(error: EmailAdmissionError): 400 | 404 | 409 { : 400; } +function receiptRoute(value: unknown): EmailReceiptRouteFence | undefined { + if (value === undefined) { + return undefined; + } + if (!value || typeof value !== 'object' || Array.isArray(value)) { + return undefined; + } + const route = value as Record; + if ( + typeof route.routeId !== 'string' || + typeof route.routeGeneration !== 'number' || + typeof route.connectionId !== 'string' || + (route.addressing !== 'shared' && route.addressing !== 'custom') || + typeof route.domain !== 'string' || + typeof route.projectSlug !== 'string' + ) { + return undefined; + } + return route as EmailReceiptRouteFence; +} + app.post('/admit', async (context) => { const body = context.get('emailActionBody' as never) as unknown as EmailAdmissionInput; if ( @@ -127,6 +160,7 @@ app.post('/receipts', async (context) => { receiptId?: unknown; projectId?: unknown; status?: unknown; + route?: unknown; }; if ( typeof body?.receiptId !== 'string' || @@ -136,10 +170,15 @@ app.post('/receipts', async (context) => { return context.json({ error: 'invalid receipt' }, 400); } try { + const route = receiptRoute(body.route); + if (body.route !== undefined && !route) { + return context.json({ error: 'invalid receipt' }, 400); + } await recordEmailReceipt(context.get('db'), { receiptId: body.receiptId, projectId: body.projectId, status: body.status, + ...(route ? { route } : {}), }); return context.json({ ok: true }); } catch (error) { @@ -160,11 +199,16 @@ app.post('/receipts/claim', async (context) => { return context.json({ error: 'invalid relay claim' }, 400); } try { + const route = receiptRoute(body.route); + if (body.route !== undefined && !route) { + return context.json({ error: 'invalid relay claim' }, 400); + } return context.json( await claimRelayedEmailReceipt(context.get('db'), { receiptId: body.receiptId, projectId: body.projectId, payloadDigest: body.payloadDigest, + ...(route ? { route } : {}), }), ); } catch (error) { @@ -260,9 +304,4 @@ app.post('/:id/finish', async (context) => { } }); -app.post('/:id/status', async (context) => { - const action = await getEmailAction(context.get('db'), context.req.param('id')); - return action ? context.json(action) : context.json({ error: 'email action not found' }, 404); -}); - export default app; diff --git a/platform/packages/api/test/integration/admin-email.test.ts b/platform/packages/api/test/integration/admin-email.test.ts index 4e0f27e5f..7cdb47c4b 100644 --- a/platform/packages/api/test/integration/admin-email.test.ts +++ b/platform/packages/api/test/integration/admin-email.test.ts @@ -240,6 +240,14 @@ describe('admin write guard (cross-origin)', () => { .where(eq(emailProjectControls.project_id, projectId)) )[0]?.suspended_at, ).not.toBeNull(); + expect(await env.db.select().from(operatorEvents)).toEqual([ + expect.objectContaining({ + action: `email/projects/${projectId}/suspend`, + target: JSON.stringify({ project: projectId, suspended: true }), + status: 'success', + http_status: 302, + }), + ]); }); test('leaves reads alone', async () => { @@ -257,7 +265,7 @@ describe('GET /admin/email/:projectId', () => { const month = monthBucket(); await env.db .insert(emailMonthlyUsage) - .values({ project_id: projectId, month, recipient_attempts: 7 }); + .values({ project_id: projectId, month, recipient_attempts: 7, inbound_receipts: 3 }); await pruneEmailActionHistory(env.db); const res = await get(`/admin/email/${projectId}`, adminJwt); @@ -266,6 +274,8 @@ describe('GET /admin/email/:projectId', () => { const html = await res.text(); expect(html).toContain(slug); expect(html).toContain('7 / 200'); + expect(html).toContain('Outbound recipient attempts'); + expect(html).toContain('Inbound (received)'); expect(html).toContain('(default)'); expect(html).toContain('Suspend email'); expect(html).toContain('No destinations yet.'); @@ -326,6 +336,14 @@ describe('POST /admin/email/:projectId/suspend', () => { .where(eq(emailProjectControls.project_id, projectId)) )[0]?.suspended_at, ).toBeNull(); + expect(await env.db.select().from(operatorEvents)).toEqual([ + expect.objectContaining({ + action: `email/projects/${projectId}/suspend`, + target: JSON.stringify({ project: projectId, suspended: false }), + status: 'success', + http_status: 302, + }), + ]); }); test('suspending twice is idempotent, not a toggle', async () => { @@ -369,6 +387,14 @@ describe('POST /admin/email/:projectId/limit', () => { .where(eq(emailProjectControls.project_id, projectId)) )[0]?.monthly_limit, ).toBe(5000); + expect(await env.db.select().from(operatorEvents)).toEqual([ + expect.objectContaining({ + action: `email/projects/${projectId}/limit`, + target: JSON.stringify({ project: projectId, monthly: '5000' }), + status: 'success', + http_status: 302, + }), + ]); }); test('a blank value drops the override back to the platform default', async () => { @@ -421,6 +447,29 @@ describe('POST /admin/email/:projectId/limit', () => { .where(eq(emailProjectControls.project_id, projectId)) )[0]?.burst_limit, ).toBe(10); + const recorded = (await env.db.select().from(operatorEvents)).map((event) => ({ + action: event.action, + target: event.target, + status: event.status, + httpStatus: event.http_status, + })); + expect(recorded).toHaveLength(2); + expect(recorded).toEqual( + expect.arrayContaining([ + { + action: `email/projects/${projectId}/limit`, + target: JSON.stringify({ project: projectId, burst: '60' }), + status: 'success', + httpStatus: 302, + }, + { + action: `email/projects/${projectId}/limit`, + target: JSON.stringify({ project: projectId, burst: 'default' }), + status: 'success', + httpStatus: 302, + }, + ]), + ); }); }); @@ -448,6 +497,16 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { expect(await env.db.select().from(emailDestinationCleanups)).toEqual([ expect.objectContaining({ cf_destination_id: 'cf-tag-ops', status: 'completed' }), ]); + const events = await env.db.select().from(operatorEvents); + expect(events).toEqual([ + expect.objectContaining({ + action: `email/projects/${projectId}/destinations/${destination.id}/remove`, + target: JSON.stringify({ project: projectId, destinationId: destination.id }), + status: 'success', + http_status: 302, + }), + ]); + expect(JSON.stringify(events)).not.toContain('ops@example.com'); }); test('leaves the CF address alone while another project still references it', async () => { @@ -493,6 +552,125 @@ describe('POST /admin/email/:projectId/destinations/:destId/delete', () => { }); describe('admin email domain controls', () => { + test('reports durable incomplete outcomes for add, rotate, and remove operations', async () => { + const { adminJwt } = await seedAdminAndProject(); + const failures: NonNullable[0]>['failOn'] = {}; + stubCustomerCf({ + zones: { + 'unknown.example.com': { + id: 'zone-unknown', + name: 'unknown.example.com', + accountId: CF_ACCOUNT_ID, + }, + 'blocked.example.net': { + id: 'zone-blocked', + name: 'blocked.example.net', + accountId: CF_ACCOUNT_ID, + }, + 'rotate.example.org': { + id: 'zone-rotate', + name: 'rotate.example.org', + accountId: CF_ACCOUNT_ID, + }, + 'remove.example.dev': { + id: 'zone-remove', + name: 'remove.example.dev', + accountId: CF_ACCOUNT_ID, + }, + }, + failOn: failures, + }); + const project = async (slug: string) => + createTestProject(env.db, (await createTestUser(env.db, `${slug}-owner`)).id, slug); + + const unknownProject = await project('unknown-add'); + failures.routingDns = { message: 'routing outcome unavailable', status: 408 }; + const unknownAdd = await post(`/admin/email/${unknownProject.id}/domains/add`, adminJwt, { + domain: 'unknown.example.com', + }); + expect({ status: unknownAdd.status, html: await unknownAdd.text() }).toMatchObject({ + status: 409, + html: expect.stringContaining('unknown'), + }); + delete failures.routingDns; + + const blockedProject = await project('blocked-add'); + failures.routingDns = { message: 'routing permission denied', status: 403 }; + const blockedAdd = await post(`/admin/email/${blockedProject.id}/domains/add`, adminJwt, { + domain: 'blocked.example.net', + }); + expect(blockedAdd.status).toBe(409); + expect(await blockedAdd.text()).toContain('blocked'); + delete failures.routingDns; + + const rotateProject = await project('blocked-rotate'); + expect( + ( + await post(`/admin/email/${rotateProject.id}/domains/add`, adminJwt, { + domain: 'rotate.example.org', + }) + ).status, + ).toBe(302); + failures.secretPut = { message: 'secret permission denied', status: 403 }; + const blockedRotate = await post( + `/admin/email/${rotateProject.id}/domains/rotate.example.org/rotate-secret`, + adminJwt, + ); + expect(blockedRotate.status).toBe(409); + expect(await blockedRotate.text()).toContain('blocked'); + delete failures.secretPut; + + const removeProject = await project('unknown-remove'); + expect( + ( + await post(`/admin/email/${removeProject.id}/domains/add`, adminJwt, { + domain: 'remove.example.dev', + }) + ).status, + ).toBe(302); + failures.scriptDelete = { message: 'delete outcome unavailable', status: 504 }; + const unknownRemove = await post( + `/admin/email/${removeProject.id}/domains/remove.example.dev/revoke`, + adminJwt, + { confirm: removeProject.slug }, + ); + expect(unknownRemove.status).toBe(409); + expect(await unknownRemove.text()).toContain('unknown'); + + const failedEvents = (await env.db.select().from(operatorEvents)) + .filter((event) => event.status === 'failed') + .map((event) => ({ + action: event.action, + status: event.http_status, + target: JSON.parse(event.target), + })); + expect(failedEvents).toHaveLength(4); + expect(failedEvents).toEqual( + expect.arrayContaining([ + { + action: 'email/domains', + status: 409, + target: { domain: 'unknown.example.com', project: unknownProject.id }, + }, + { + action: 'email/domains', + status: 409, + target: { domain: 'blocked.example.net', project: blockedProject.id }, + }, + { + action: 'email/domains/rotate.example.org/rotate-secret', + status: 409, + target: { domain: 'rotate.example.org' }, + }, + { + action: 'email/domains/remove.example.dev/remove', + status: 409, + target: { domain: 'remove.example.dev', force: false }, + }, + ]), + ); + }); + test('registers, rotates and removes an exact route without exposing credential material', async () => { const { adminJwt, projectId, slug } = await seedAdminAndProject(); const stub = stubCustomerCf({ diff --git a/platform/packages/api/test/integration/api-email-domains.test.ts b/platform/packages/api/test/integration/api-email-domains.test.ts index f35ff547f..ee9813119 100644 --- a/platform/packages/api/test/integration/api-email-domains.test.ts +++ b/platform/packages/api/test/integration/api-email-domains.test.ts @@ -63,6 +63,42 @@ afterEach(() => { }); describe('project email domain authority', () => { + it('persists token identity and expiry and reports a known expired credential locally', async () => { + const owner = await createTestUser(env.db, 'expiry-owner'); + const project = await createTestProject(env.db, owner.id, 'expiry-mail'); + const expiresOn = new Date(Date.now() + 86_400_000).toISOString(); + const stub = stubCustomerCf({ zones, verifyExpiresOn: expiresOn }); + expect( + ( + await call(project.id, owner.jwt, 'POST', '/domains', { + domain: 'expiry.example.com', + apiToken: token, + }) + ).status, + ).toBe(200); + const credential = (await env.db.select().from(emailCredentials))[0]!; + expect(credential).toMatchObject({ + token_id: 'tok_dummy', + status: 'healthy', + }); + expect(Date.parse(credential.expires_on!)).toBe(Date.parse(expiresOn)); + + await env.db + .update(emailCredentials) + .set({ expires_on: new Date(Date.now() - 60_000).toISOString() }); + const checkpoint = stub.calls.length; + const status = await call(project.id, owner.jwt, 'GET', '/domains/expiry.example.com'); + expect(await status.json()).toMatchObject({ + readiness: { + management: { + status: 'expired', + reason: expect.stringContaining('expired'), + }, + }, + }); + expect(stub.calls).toHaveLength(checkpoint); + }); + it('refreshes readiness from provider reads and preserves inbound state when the credential probe fails', async () => { const owner = await createTestUser(env.db, 'readiness-owner'); const project = await createTestProject(env.db, owner.id, 'readiness-mail'); diff --git a/platform/packages/api/test/integration/api-email.test.ts b/platform/packages/api/test/integration/api-email.test.ts index 43feb03cd..66e155645 100644 --- a/platform/packages/api/test/integration/api-email.test.ts +++ b/platform/packages/api/test/integration/api-email.test.ts @@ -41,11 +41,7 @@ import { signConfirmToken } from '../../src/auth/confirm-token.ts'; import { revokeOwnerVerifiedDestinationsForUserChange } from '../../src/db.ts'; import * as dbModule from '../../src/db.ts'; import { emailMonthlyUsage } from '../../src/email/admission-schema.ts'; -import { - recordEmailReceipt, - setProjectEmailLimits, - setProjectEmailSuspended, -} from '../../src/email/admission.ts'; +import { setProjectEmailLimits, setProjectEmailSuspended } from '../../src/email/admission.ts'; import { hashSendContent, PLATFORM_INTERNAL_EMAIL_SENTINEL, @@ -2076,7 +2072,7 @@ describe('GET /projects/:id/email/usage', () => { expect(res.status).toBe(200); expect(await res.json()).toEqual({ month: monthBucket(), - sent: 0, + attempts: 0, received: 0, limit: 200, remaining: 200, @@ -2090,14 +2086,7 @@ describe('GET /projects/:id/email/usage', () => { const month = monthBucket(); await env.db .insert(emailMonthlyUsage) - .values({ project_id: project.id, month, recipient_attempts: 7 }); - for (let n = 0; n < 3; n++) { - await recordEmailReceipt(env.db, { - receiptId: `receipt_${n}`, - projectId: project.id, - status: 'received', - }); - } + .values({ project_id: project.id, month, recipient_attempts: 7, inbound_receipts: 3 }); await setProjectEmailLimits(env.db, project.id, { monthly: 50 }); await setProjectEmailSuspended(env.db, project.id, true); @@ -2105,7 +2094,7 @@ describe('GET /projects/:id/email/usage', () => { expect(res.status).toBe(200); expect(await res.json()).toEqual({ month, - sent: 7, + attempts: 7, received: 3, limit: 50, remaining: 43, @@ -2123,8 +2112,8 @@ describe('GET /projects/:id/email/usage', () => { await env.ROUTING.put(`email-limit:${project.id}`, '-5'); const res = await usage(project.id, user.jwt); - const body = (await res.json()) as { sent: number; limit: number; remaining: number }; - expect(body.sent).toBe(0); + const body = (await res.json()) as { attempts: number; limit: number; remaining: number }; + expect(body.attempts).toBe(0); // A non-positive override is ignored in favour of the default. expect(body.limit).toBe(200); expect(body.remaining).toBe(200); @@ -2375,7 +2364,7 @@ describe('email platform capability', () => { const usage = await get(`/projects/${project.id}/email/usage`, user.jwt, capabilityEnv(true)); expect(usage.status).toBe(200); - expect(await usage.json()).toMatchObject({ sent: 0, received: 0, limit: 200 }); + expect(await usage.json()).toMatchObject({ attempts: 0, received: 0, limit: 200 }); const list = await listDestinations(project.id, user.jwt, capabilityEnv(true)); expect(list.status).toBe(200); diff --git a/platform/packages/api/test/integration/email-admission.test.ts b/platform/packages/api/test/integration/email-admission.test.ts index 351956ac4..8b12269ed 100644 --- a/platform/packages/api/test/integration/email-admission.test.ts +++ b/platform/packages/api/test/integration/email-admission.test.ts @@ -1,9 +1,10 @@ -import { eq } from 'drizzle-orm'; +import { eq, sql } from 'drizzle-orm'; import { beforeAll, afterAll, beforeEach, describe, expect, it } from 'vite-plus/test'; import { deleteEmailDestination } from '../../src/db.ts'; import { emailActionRecipients, emailMonthlyUsage, + emailReceipts, emailUnresolvedAttempts, } from '../../src/email/admission-schema.ts'; import { @@ -15,6 +16,7 @@ import { EmailAdmissionError, getProjectEmailLogs, getProjectEmailUsage, + lockEmailPolicy, pruneEmailActionHistory, resolveEmailUnresolvedAttempt, setProjectEmailLimits, @@ -27,7 +29,7 @@ import { emailZoneConnections, } from '../../src/email/connection-schema.ts'; import { setEmailRecipientPolicy } from '../../src/email/settings.ts'; -import { emailDestinations, projects } from '../../src/schema.ts'; +import { emailDestinations, projects, users } from '../../src/schema.ts'; import { clearTables, createTestProject, @@ -51,6 +53,34 @@ beforeEach(async () => { async function fixture() { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'acme'); + await env.db + .insert(emailZoneConnections) + .values({ + id: 'receipt-connection', + installation_id: 'installation', + account_id: 'account', + zone_id: 'shared-zone', + zone_name: 'mail.example.com', + managed_by: 'admin', + ingress_worker_name: 'receipt-gateway', + secret_ciphertext: 'ciphertext', + secret_iv: 'iv', + secret_key_version: 'key', + inbound_status: 'ready', + }) + .onConflictDoNothing(); + await env.db + .insert(emailDomainRoutes) + .values({ + id: 'receipt-route', + domain: 'mail.example.com', + connection_id: 'receipt-connection', + project_id: null, + addressing: 'shared', + managed_by: 'admin', + inbound_status: 'ready', + }) + .onConflictDoNothing(); await env.db.insert(emailDestinations).values({ id: `dest_${project.id}`, project_id: project.id, @@ -63,7 +93,25 @@ async function fixture() { address: 'two@example.com', status: 'verified', }); - return project; + return { ...project, userId: user.id }; +} + +async function waitForPostgresLockWaiter(): Promise { + const deadline = Date.now() + 5_000; + while (Date.now() < deadline) { + const result = await env.db.execute(sql` + SELECT count(*)::int AS waiters + FROM pg_stat_activity + WHERE datname = current_database() + AND pid <> pg_backend_pid() + AND wait_event_type = 'Lock' + `); + if (Number((result.rows[0] as { waiters?: number } | undefined)?.waiters ?? 0) >= 1) { + return; + } + await new Promise((resolve) => setTimeout(resolve, 10)); + } + throw new Error('timed out waiting for the attempt-start owner lock'); } function input(projectId: string, key: string, recipients = ['one@example.com']) { @@ -79,7 +127,372 @@ function input(projectId: string, key: string, recipients = ['one@example.com']) }; } +function receiptRoute(projectSlug = 'acme') { + return { + routeId: 'receipt-route', + routeGeneration: 1, + connectionId: 'receipt-connection', + addressing: 'shared' as const, + domain: 'mail.example.com', + projectSlug, + }; +} + describe('authoritative email admission', () => { + it.each(['native', 'relayed'] as const)( + 'requires an authoritative route fence for a fresh %s receipt', + async (transport) => { + const project = await fixture(); + const receive = + transport === 'native' + ? recordEmailReceipt(env.db, { + receiptId: 'missing-route-fence', + projectId: project.id, + status: 'received', + }) + : claimRelayedEmailReceipt(env.db, { + receiptId: '0'.repeat(64), + projectId: project.id, + payloadDigest: '1'.repeat(64), + }); + await expect(receive).rejects.toMatchObject({ code: 'INVALID_REQUEST' }); + expect(await env.db.select().from(emailReceipts)).toHaveLength(0); + }, + ); + + it.each(['native', 'relayed'] as const)( + 'rejects a fresh %s receipt after its resolved route is disabled', + async (transport) => { + const project = await fixture(); + await env.db + .update(emailDomainRoutes) + .set({ desired_state: 'disabled' }) + .where(eq(emailDomainRoutes.id, 'receipt-route')); + + const receive = + transport === 'native' + ? recordEmailReceipt(env.db, { + receiptId: 'route-disabled', + projectId: project.id, + status: 'received', + route: receiptRoute(), + }) + : claimRelayedEmailReceipt(env.db, { + receiptId: 'a'.repeat(64), + projectId: project.id, + payloadDigest: 'b'.repeat(64), + route: receiptRoute(), + }); + await expect(receive).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect(await env.db.select().from(emailReceipts)).toHaveLength(0); + expect((await getProjectEmailUsage(env.db, project.id)).received).toBe(0); + }, + ); + + it.each([ + [ + 'route generation changes', + async () => { + await env.db + .update(emailDomainRoutes) + .set({ desired_generation: 2 }) + .where(eq(emailDomainRoutes.id, 'receipt-route')); + }, + ], + [ + 'route readiness changes', + async () => { + await env.db + .update(emailDomainRoutes) + .set({ inbound_status: 'drifted' }) + .where(eq(emailDomainRoutes.id, 'receipt-route')); + }, + ], + [ + 'connection readiness changes', + async () => { + await env.db + .update(emailZoneConnections) + .set({ inbound_status: 'drifted' }) + .where(eq(emailZoneConnections.id, 'receipt-connection')); + }, + ], + [ + 'the shared project slug changes', + async () => { + await env.db.update(projects).set({ slug: 'renamed' }); + }, + ], + ] as const)('rejects a fresh relayed receipt when %s', async (_label, mutate) => { + const project = await fixture(); + await mutate(); + await expect( + claimRelayedEmailReceipt(env.db, { + receiptId: 'c'.repeat(64), + projectId: project.id, + payloadDigest: 'd'.repeat(64), + route: receiptRoute(), + }), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + }); + + it('rejects a stale custom-route assignment for another project', async () => { + const project = await fixture(); + const otherUser = await createTestUser(env.db); + const other = await createTestProject(env.db, otherUser.id, 'other'); + await env.db.insert(emailDomainRoutes).values({ + id: 'custom-receipt-route', + domain: 'custom.example.com', + connection_id: 'receipt-connection', + project_id: project.id, + addressing: 'custom', + managed_by: 'admin', + inbound_status: 'ready', + desired_generation: 3, + }); + await env.db + .update(emailDomainRoutes) + .set({ project_id: other.id, desired_generation: 4 }) + .where(eq(emailDomainRoutes.id, 'custom-receipt-route')); + + await expect( + recordEmailReceipt(env.db, { + receiptId: 'stale-custom-route', + projectId: project.id, + status: 'received', + route: { + routeId: 'custom-receipt-route', + routeGeneration: 3, + connectionId: 'receipt-connection', + addressing: 'custom', + domain: 'custom.example.com', + projectSlug: project.slug, + }, + }), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + }); + + it('allows an existing native receipt to finish after its route is disabled', async () => { + const project = await fixture(); + await recordEmailReceipt(env.db, { + receiptId: 'existing-native-route', + projectId: project.id, + status: 'received', + route: receiptRoute(), + }); + await env.db + .update(emailDomainRoutes) + .set({ desired_state: 'disabled', inbound_status: 'disabled' }) + .where(eq(emailDomainRoutes.id, 'receipt-route')); + + await expect( + recordEmailReceipt(env.db, { + receiptId: 'existing-native-route', + projectId: project.id, + status: 'handler_completed', + }), + ).resolves.toBeUndefined(); + expect((await getProjectEmailUsage(env.db, project.id)).received).toBe(1); + }); + + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL)).each(['native', 'relayed'] as const)( + 'serializes a fresh %s receipt with a concurrent route disable', + async (transport) => { + const project = await fixture(); + let routeDisabled!: () => void; + const disabled = new Promise((resolve) => { + routeDisabled = resolve; + }); + let releaseDisable!: () => void; + const disableMayCommit = new Promise((resolve) => { + releaseDisable = resolve; + }); + const disabling = env.db.transaction(async (tx) => { + await lockEmailPolicy(tx); + await tx + .update(emailDomainRoutes) + .set({ desired_state: 'disabled', inbound_status: 'disabled' }) + .where(eq(emailDomainRoutes.id, 'receipt-route')); + routeDisabled(); + await disableMayCommit; + }); + await disabled; + const receive = + transport === 'native' + ? recordEmailReceipt(env.db, { + receiptId: 'route-disable-race', + projectId: project.id, + status: 'received', + route: receiptRoute(), + }) + : claimRelayedEmailReceipt(env.db, { + receiptId: 'e'.repeat(64), + projectId: project.id, + payloadDigest: 'f'.repeat(64), + route: receiptRoute(), + }); + try { + await waitForPostgresLockWaiter(); + releaseDisable(); + await disabling; + await expect(receive).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect(await env.db.select().from(emailReceipts)).toHaveLength(0); + } finally { + releaseDisable(); + await Promise.allSettled([disabling, receive]); + } + }, + 15_000, + ); + + it('rejects a custom sender after its stored Cloudflare token expiry', async () => { + const project = await fixture(); + await env.db.insert(emailCredentials).values({ + id: 'expired-cred', + installation_id: 'installation', + managed_by: 'owner', + manager_user_id: project.userId, + kind: 'api_token', + account_id: 'account', + zone_id: 'zone', + ciphertext: 'ciphertext', + iv: 'iv', + key_version: 'key', + expires_on: new Date(Date.now() - 60_000).toISOString(), + }); + await env.db.insert(emailZoneConnections).values({ + id: 'expired-connection', + installation_id: 'installation', + account_id: 'account', + zone_id: 'zone', + zone_name: 'example.com', + managed_by: 'owner', + manager_user_id: project.userId, + credential_id: 'expired-cred', + ingress_worker_name: 'gateway', + secret_ciphertext: 'ciphertext', + secret_iv: 'iv', + secret_key_version: 'key', + management_status: 'healthy', + }); + await env.db.insert(emailDomainRoutes).values({ + id: 'expired-route', + domain: 'custom.example.com', + connection_id: 'expired-connection', + project_id: project.id, + addressing: 'custom', + managed_by: 'owner', + assigned_by_user_id: project.userId, + inbound_status: 'ready', + outbound_status: 'ready', + }); + + const action = await admitEmailAction(env.db, { + ...input(project.id, 'expired-sender'), + from: 'support@custom.example.com', + transport: 'send_raw', + }); + expect(action.recipients).toMatchObject([{ state: 'rejected', errorCode: 'INVALID_FROM' }]); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(0); + }); + + it('does not start a reserved custom send after the stored token expires', async () => { + const project = await fixture(); + await env.db.insert(emailCredentials).values({ + id: 'expiring-cred', + installation_id: 'installation', + managed_by: 'owner', + manager_user_id: project.userId, + kind: 'api_token', + account_id: 'account', + zone_id: 'zone', + ciphertext: 'ciphertext', + iv: 'iv', + key_version: 'key', + expires_on: new Date(Date.now() + 60_000).toISOString(), + }); + await env.db.insert(emailZoneConnections).values({ + id: 'expiring-connection', + installation_id: 'installation', + account_id: 'account', + zone_id: 'zone', + zone_name: 'example.com', + managed_by: 'owner', + manager_user_id: project.userId, + credential_id: 'expiring-cred', + ingress_worker_name: 'gateway', + secret_ciphertext: 'ciphertext', + secret_iv: 'iv', + secret_key_version: 'key', + management_status: 'healthy', + }); + await env.db.insert(emailDomainRoutes).values({ + id: 'expiring-route', + domain: 'expiring.example.com', + connection_id: 'expiring-connection', + project_id: project.id, + addressing: 'custom', + managed_by: 'owner', + assigned_by_user_id: project.userId, + inbound_status: 'ready', + outbound_status: 'ready', + }); + const action = await admitEmailAction(env.db, { + ...input(project.id, 'expiring-sender'), + from: 'support@expiring.example.com', + transport: 'send_raw', + }); + expect(action.recipients[0]?.state).toBe('reserved'); + await env.db + .update(emailCredentials) + .set({ expires_on: new Date(Date.now() - 60_000).toISOString() }) + .where(eq(emailCredentials.id, 'expiring-cred')); + + await expect( + transitionEmailRecipients(env.db, action.operationId, ['one@example.com'], 'attempt_started'), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect( + ( + await admitEmailAction(env.db, { + ...input(project.id, 'expiring-sender'), + from: 'support@expiring.example.com', + transport: 'send_raw', + }) + ).recipients[0]?.state, + ).toBe('reserved'); + expect(await env.db.select().from(emailUnresolvedAttempts)).toHaveLength(0); + await transitionEmailRecipients(env.db, action.operationId, ['one@example.com'], 'cancelled'); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(0); + }); + + it('admits shared-sender replies through the binding while enforcing recipient consent', async () => { + const project = await fixture(); + const receiptId = 'f'.repeat(64); + await recordEmailReceipt(env.db, { + receiptId, + projectId: project.id, + status: 'handler_completed', + route: receiptRoute(), + }); + const result = await admitEmailAction(env.db, { + ...input(project.id, 'shared-binding-reply', ['one@example.com', 'unverified@example.net']), + kind: 'reply', + receiptId, + }); + expect(result.recipients).toHaveLength(2); + expect(result.recipients).toEqual( + expect.arrayContaining([ + expect.objectContaining({ recipient: 'one@example.com', state: 'reserved' }), + expect.objectContaining({ + recipient: 'unverified@example.net', + state: 'rejected', + errorCode: 'UNVERIFIED_DESTINATION', + }), + ]), + ); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); + }); + it('requires verified recipients for shared native forwarding even under an open policy', async () => { const project = await fixture(); await setEmailRecipientPolicy(env.db, env.ROUTING, { mode: 'any', domains: [] }); @@ -88,6 +501,7 @@ describe('authoritative email admission', () => { receiptId, projectId: project.id, status: 'handler_completed', + route: receiptRoute(), }); const result = await admitEmailAction(env.db, { ...input(project.id, 'shared-forward', ['one@example.com', 'unverified@example.net']), @@ -105,7 +519,7 @@ describe('authoritative email admission', () => { }), ]), ); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); }); it('records unsupported relayed forwarding without charging and retains native verified forwarding', async () => { @@ -147,6 +561,7 @@ describe('authoritative email admission', () => { receiptId, projectId: project.id, status: 'handler_completed', + route: receiptRoute(), }); const forward = { ...input(project.id, 'relay-forward'), @@ -158,7 +573,7 @@ describe('authoritative email admission', () => { expect(unsupported.recipients).toMatchObject([ { state: 'rejected', errorCode: 'UNSUPPORTED_ACTION' }, ]); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(0); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(0); const native = await admitEmailAction(env.db, { ...forward, key: 'native-forward', @@ -183,6 +598,7 @@ describe('authoritative email admission', () => { receiptId: 'c'.repeat(64), payloadDigest: 'd'.repeat(64), projectId: project.id, + route: receiptRoute(), }; await claimRelayedEmailReceipt(env.db, identity); await recordEmailReceipt(env.db, { ...identity, status: 'actions_rejected' }); @@ -206,12 +622,18 @@ describe('authoritative email admission', () => { receiptId: 'a'.repeat(64), projectId: project.id, payloadDigest: 'b'.repeat(64), + route: receiptRoute(), }; const claims = await Promise.all( Array.from({ length: 3 }, () => claimRelayedEmailReceipt(env.db, identity)), ); expect(claims.filter((claim) => claim.state === 'claimed')).toHaveLength(1); expect(claims.filter((claim) => claim.state === 'in_progress')).toHaveLength(2); + expect((await getProjectEmailUsage(env.db, project.id)).received).toBe(1); + await env.db + .update(emailDomainRoutes) + .set({ desired_state: 'disabled', inbound_status: 'disabled' }) + .where(eq(emailDomainRoutes.id, 'receipt-route')); await expect( completeRelayedEmailReceipt(env.db, { ...identity, reject: false }), ).rejects.toMatchObject({ code: 'INVALID_STATE' }); @@ -221,12 +643,21 @@ describe('authoritative email admission', () => { status: 'handler_completed', }); await completeRelayedEmailReceipt(env.db, { ...identity, reject: false }); - expect(await claimRelayedEmailReceipt(env.db, identity)).toEqual({ + const replayIdentity = { + receiptId: identity.receiptId, + projectId: identity.projectId, + payloadDigest: identity.payloadDigest, + }; + expect(await claimRelayedEmailReceipt(env.db, replayIdentity)).toEqual({ state: 'completed', reject: false, }); + expect((await getProjectEmailUsage(env.db, project.id)).received).toBe(1); await expect( - claimRelayedEmailReceipt(env.db, { ...identity, payloadDigest: 'c'.repeat(64) }), + claimRelayedEmailReceipt(env.db, { + ...replayIdentity, + payloadDigest: 'c'.repeat(64), + }), ).rejects.toMatchObject({ code: 'CONFLICT' }); await expect( completeRelayedEmailReceipt(env.db, { ...identity, reject: true }), @@ -258,7 +689,7 @@ describe('authoritative email admission', () => { cancelled: 1, inFlight: 1, }); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); await transitionEmailRecipients( env.db, started.operationId, @@ -277,7 +708,7 @@ describe('authoritative email admission', () => { expect.objectContaining({ operationId: started.operationId, status: 'outcome_unknown' }), ]), ); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); }); it('expires completed unknown metadata but retains a PII-free active-attempt fence', async () => { @@ -358,7 +789,7 @@ describe('authoritative email admission', () => { expect((await getProjectEmailLogs(env.db, project.id)).logs).toEqual([ expect.objectContaining({ operationId: action.operationId, status: 'outcome_unknown' }), ]); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); expect( (await admitEmailAction(env.db, input(project.id, 'crashed'))).recipients[0]?.state, ).toBe('outcome_unknown'); @@ -417,7 +848,7 @@ describe('authoritative email admission', () => { }), ).toMatchObject({ metadataExpired: true, charged: true }); expect(await env.db.select().from(emailUnresolvedAttempts)).toHaveLength(0); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); expect(await drainProjectEmailAdmissions(env.db, project.id)).toEqual({ cancelled: 0, @@ -433,7 +864,7 @@ describe('authoritative email admission', () => { const again = await admitEmailAction(env.db, input(project.id, 'same')); expect(again.operationId).toBe(first.operationId); expect(again.replay).toBe(true); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); await expect( admitEmailAction(env.db, { ...input(project.id, 'same'), digest: 'b'.repeat(64) }), ).rejects.toMatchObject({ code: 'CONFLICT' } satisfies Partial); @@ -464,7 +895,7 @@ describe('authoritative email admission', () => { 'outcome_unknown', { errorCode: 'OUTCOME_UNKNOWN' }, ); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); const replay = await admitEmailAction( env.db, input(project.id, 'batch', ['one@example.com', 'two@example.com']), @@ -482,9 +913,148 @@ describe('authoritative email admission', () => { await setProjectEmailSuspended(env.db, project.id, true); const result = await admitEmailAction(env.db, input(project.id, 'blocked')); expect(result.recipients[0]).toMatchObject({ state: 'rejected', errorCode: 'SUSPENDED' }); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(0); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(0); }); + it.each([ + ['native', 'project'], + ['native', 'owner'], + ['relayed', 'project'], + ['relayed', 'owner'], + ] as const)( + 'blocks new %s receipts after %s suspension but finishes an existing receipt', + async (transport, scope) => { + const project = await fixture(); + const receive = (receiptId: string) => + transport === 'native' + ? recordEmailReceipt(env.db, { + receiptId, + projectId: project.id, + status: 'received', + route: receiptRoute(), + }) + : claimRelayedEmailReceipt(env.db, { + receiptId, + projectId: project.id, + payloadDigest: 'd'.repeat(64), + route: receiptRoute(), + }); + const receiptId = 'a'.repeat(64); + await receive(receiptId); + if (scope === 'owner') { + await env.db + .update(users) + .set({ suspended_reason: 'admin_suspended' }) + .where(eq(users.id, project.userId)); + } else { + await setProjectEmailSuspended(env.db, project.id, true); + } + await expect(receive('b'.repeat(64))).rejects.toMatchObject({ code: 'INVALID_STATE' }); + await recordEmailReceipt(env.db, { + receiptId, + projectId: project.id, + status: 'handler_completed', + }); + if (transport === 'relayed') { + await completeRelayedEmailReceipt(env.db, { + receiptId, + projectId: project.id, + payloadDigest: 'd'.repeat(64), + reject: false, + }); + await expect(receive(receiptId)).resolves.toEqual({ state: 'completed', reject: false }); + } + expect(await env.db.select().from(emailReceipts)).toHaveLength(1); + expect((await getProjectEmailUsage(env.db, project.id)).received).toBe(1); + }, + ); + + it('does not start an admitted reservation after its owner is suspended', async () => { + const project = await fixture(); + const action = await admitEmailAction(env.db, input(project.id, 'owner-suspended')); + await env.db + .update(users) + .set({ suspended_reason: 'admin_suspended' }) + .where(eq(users.id, project.userId)); + + await expect( + transitionEmailRecipients(env.db, action.operationId, ['one@example.com'], 'attempt_started'), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect( + (await admitEmailAction(env.db, input(project.id, 'owner-suspended'))).recipients[0]?.state, + ).toBe('reserved'); + }); + + it + .runIf(Boolean(process.env.VOID_TEST_DATABASE_URL)) + .each(['outbound', 'native', 'relayed'] as const)( + 'serializes %s admission with a concurrent owner suspension', + async (transport) => { + const project = await fixture(); + const action = + transport === 'outbound' + ? await admitEmailAction(env.db, input(project.id, 'owner-suspension-race')) + : null; + let markSuspended!: () => void; + const suspended = new Promise((resolve) => { + markSuspended = resolve; + }); + let releaseSuspension!: () => void; + const suspensionMayCommit = new Promise((resolve) => { + releaseSuspension = resolve; + }); + const suspension = env.db.transaction(async (tx) => { + await tx + .update(users) + .set({ suspended_reason: 'admin_suspended' }) + .where(eq(users.id, project.userId)); + markSuspended(); + await suspensionMayCommit; + }); + await suspended; + + const start = action + ? transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'attempt_started', + ) + : transport === 'native' + ? recordEmailReceipt(env.db, { + receiptId: 'c'.repeat(64), + projectId: project.id, + status: 'received', + route: receiptRoute(), + }) + : claimRelayedEmailReceipt(env.db, { + receiptId: 'c'.repeat(64), + projectId: project.id, + payloadDigest: 'd'.repeat(64), + route: receiptRoute(), + }); + try { + await waitForPostgresLockWaiter(); + releaseSuspension(); + await suspension; + await expect(start).rejects.toMatchObject({ code: 'INVALID_STATE' }); + if (action) { + expect( + (await admitEmailAction(env.db, input(project.id, 'owner-suspension-race'))) + .recipients[0]?.state, + ).toBe('reserved'); + } else { + expect(await env.db.select().from(emailReceipts)).toHaveLength(0); + expect((await getProjectEmailUsage(env.db, project.id)).received).toBe(0); + } + } finally { + releaseSuspension(); + await Promise.allSettled([suspension, start]); + } + }, + 15_000, + ); + it('applies a tightened policy and revoked consent on the next operation', async () => { const project = await fixture(); const kv = { put: async () => {}, get: async () => null } as unknown as KVNamespace; @@ -517,6 +1087,12 @@ describe('authoritative email admission', () => { ['one@example.com'], 'provider_accepted', ); + await recordEmailReceipt(env.db, { + receiptId: 'retained-current-month-count', + projectId: project.id, + status: 'handler_completed', + route: receiptRoute(), + }); await env.db.insert(emailMonthlyUsage).values([ { project_id: project.id, month: '2000-01', recipient_attempts: 1 }, { project_id: 'deleted-project', month: '2000-01', recipient_attempts: 2 }, @@ -527,10 +1103,14 @@ describe('authoritative email admission', () => { project_id: project.id, month: new Date().toISOString().slice(0, 7), recipient_attempts: 1, + inbound_receipts: 1, }, ]); expect((await getProjectEmailLogs(env.db, project.id)).logs).toHaveLength(0); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect(await getProjectEmailUsage(env.db, project.id)).toMatchObject({ + attempts: 1, + received: 1, + }); const second = await admitEmailAction(env.db, input(project.id, 'second')); expect(second.recipients[0]).toMatchObject({ state: 'rejected', errorCode: 'QUOTA_EXCEEDED' }); expect(first.operationId).not.toBe(second.operationId); @@ -540,7 +1120,7 @@ describe('authoritative email admission', () => { const project = await fixture(); const first = await admitEmailAction(env.db, input(project.id, 'cancel')); await transitionEmailRecipients(env.db, first.operationId, ['one@example.com'], 'cancelled'); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(0); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(0); await expect( transitionEmailRecipients(env.db, first.operationId, ['one@example.com'], 'attempt_started'), ).rejects.toMatchObject({ code: 'INVALID_STATE' }); @@ -563,7 +1143,104 @@ describe('authoritative email admission', () => { await expect( transitionEmailRecipients(env.db, second.operationId, ['one@example.com'], 'cancelled'), ).rejects.toMatchObject({ code: 'INVALID_STATE' }); - expect((await getProjectEmailUsage(env.db, project.id)).sent).toBe(1); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); + }); + + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'refunds the UTC quota month under a non-UTC PostgreSQL session', + async () => { + const project = await fixture(); + const action = await admitEmailAction(env.db, input(project.id, 'utc-month-refund')); + await env.db.update(emailActionRecipients).set({ reserved_at: '2026-10-01T00:01:00.000Z' }); + await env.db.update(emailMonthlyUsage).set({ month: '2026-10' }); + await env.db.execute(sql`set time zone 'Pacific/Honolulu'`); + try { + const [stored] = await env.db.select().from(emailActionRecipients); + expect(stored!.reserved_at!.slice(0, 7)).toBe('2026-09'); + await transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'cancelled', + ); + } finally { + await env.db.execute(sql`set time zone 'UTC'`); + } + expect(await env.db.select().from(emailMonthlyUsage)).toEqual([ + expect.objectContaining({ month: '2026-10', recipient_attempts: 0 }), + ]); + }, + ); + + it('reclaims abandoned reservations without reopening started or uncertain sends', async () => { + const project = await fixture(); + const abandoned = await admitEmailAction(env.db, input(project.id, 'abandoned')); + const started = await admitEmailAction(env.db, input(project.id, 'started')); + const uncertain = await admitEmailAction(env.db, input(project.id, 'unknown')); + for (const action of [started, uncertain]) { + await transitionEmailRecipients( + env.db, + action.operationId, + ['one@example.com'], + 'attempt_started', + ); + } + await transitionEmailRecipients( + env.db, + uncertain.operationId, + ['one@example.com'], + 'outcome_unknown', + ); + await env.db.update(emailActionRecipients).set({ + reserved_at: new Date(Date.now() - 20 * 60_000).toISOString(), + }); + const recent = await admitEmailAction(env.db, input(project.id, 'recent')); + + await pruneEmailActionHistory(env.db); + await pruneEmailActionHistory(env.db); + for (const [key, operationId, state] of [ + ['abandoned', abandoned.operationId, 'cancelled'], + ['started', started.operationId, 'attempt_started'], + ['unknown', uncertain.operationId, 'outcome_unknown'], + ['recent', recent.operationId, 'reserved'], + ]) { + const replay = await admitEmailAction(env.db, input(project.id, key!)); + expect(replay.operationId).toBe(operationId); + expect(replay.recipients[0]?.state).toBe(state); + } + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(3); + await expect( + transitionEmailRecipients( + env.db, + abandoned.operationId, + ['one@example.com'], + 'attempt_started', + ), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); + expect(await env.db.select().from(emailUnresolvedAttempts)).toHaveLength(1); + }); + + it('does not refund a previous-month reservation against this month', async () => { + const project = await fixture(); + const abandoned = await admitEmailAction(env.db, input(project.id, 'last-month')); + const previousMonth = new Date(); + previousMonth.setUTCDate(0); + await env.db.update(emailActionRecipients).set({ reserved_at: previousMonth.toISOString() }); + await env.db.update(emailMonthlyUsage).set({ month: previousMonth.toISOString().slice(0, 7) }); + await admitEmailAction(env.db, input(project.id, 'this-month')); + await pruneEmailActionHistory(env.db); + expect( + (await admitEmailAction(env.db, input(project.id, 'last-month'))).recipients[0]?.state, + ).toBe('cancelled'); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); + await expect( + transitionEmailRecipients( + env.db, + abandoned.operationId, + ['one@example.com'], + 'attempt_started', + ), + ).rejects.toMatchObject({ code: 'INVALID_STATE' }); }); it('enforces direct caller bounds at the authoritative API', async () => { diff --git a/platform/packages/api/test/integration/email-connections.test.ts b/platform/packages/api/test/integration/email-connections.test.ts index 59168adea..8903999eb 100644 --- a/platform/packages/api/test/integration/email-connections.test.ts +++ b/platform/packages/api/test/integration/email-connections.test.ts @@ -1,4 +1,4 @@ -import { eq } from 'drizzle-orm'; +import { and, eq, sql } from 'drizzle-orm'; import { afterAll, afterEach, @@ -11,7 +11,7 @@ import { } from 'vite-plus/test'; import { hmacSignState } from '../../src/auth/hmac.ts'; import { emailUnresolvedAttempts } from '../../src/email/admission-schema.ts'; -import { disableEmailDomainRouteAndDrain } from '../../src/email/admission.ts'; +import { disableEmailDomainRouteAndDrainTx } from '../../src/email/admission.ts'; import { emailCacheOutbox, emailCredentials, @@ -22,9 +22,12 @@ import { } from '../../src/email/connection-schema.ts'; import { ensureSharedEmailConnection, + EMAIL_OPERATION_RECOVERY_MIN_AGE_MS, flushEmailCacheOutbox, getEmailOperation, + inspectUnknownEmailOperationRecovery, reconcilePendingEmailOperations, + reconcileUnknownEmailOperation, requestEmailDomainAdd, requestEmailDomainRemove, requestEmailDomainSync, @@ -32,6 +35,7 @@ import { readConnectionSecret, resolveEmailDomain, resolveEmailIngress, + resolveUnknownEmailOperation, runEmailOperation, } from '../../src/email/connection-service.ts'; import type { ApiEnv } from '../../src/env.ts'; @@ -60,6 +64,24 @@ function bindings(): ApiEnv['Bindings'] { } as unknown as ApiEnv['Bindings']; } +async function waitForPostgresLockWaiters(minimum: number): Promise { + const deadline = Date.now() + 5_000; + while (Date.now() < deadline) { + const result = await env.db.execute(sql` + SELECT count(*)::int AS waiters + FROM pg_stat_activity + WHERE datname = current_database() + AND pid <> pg_backend_pid() + AND wait_event_type = 'Lock' + `); + if (Number((result.rows[0] as { waiters?: number } | undefined)?.waiters ?? 0) >= minimum) { + return; + } + await new Promise((resolve) => setTimeout(resolve, 10)); + } + throw new Error(`timed out waiting for ${minimum} PostgreSQL lock waiters`); +} + beforeAll(async () => { env = await setupEnv(); }); @@ -91,7 +113,7 @@ describe('durable zone email connections', () => { .update(deployments) .set({ manifest: JSON.stringify({ emailProtocolVersion: 1, limits: { cpuMs: 100 } }) }) .where(eq(deployments.id, deployment.id)); - const { connection } = (await resolveEmailDomain(env.db, 'limits.example.com'))!; + const { connection, route } = (await resolveEmailDomain(env.db, 'limits.example.com'))!; const to = 'support@limits.example.com'; const proof = await hmacSignState( `email-ingress-v1\n${connection.account_id}\n${connection.zone_id}\n${connection.ingress_worker_name}\n${to}`, @@ -115,6 +137,9 @@ describe('durable zone email connections', () => { expect(await response.json()).toMatchObject({ projectId: project.id, deploymentId: deployment.id, + routeId: route.id, + routeGeneration: route.desired_generation, + connectionId: connection.id, limits: { cpuMs: 10, subRequests: 50 }, }); }); @@ -135,6 +160,302 @@ describe('durable zone email connections', () => { expect(await env.db.select().from(emailOperations)).toEqual([]); }); + it('blocks setup when Cloudflare definitively refuses a provider write', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'routing-permission'); + const failures: NonNullable[0]>['failOn'] = { + routingDns: { message: 'permission denied', status: 403 }, + }; + const stub = stubCustomerCf({ + zones, + failOn: failures, + }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const { operationId, routeId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'permission.example.com', + token: TOKEN, + actor, + }); + + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation).toMatchObject({ + status: 'blocked', + current_step: 'routing_enable', + failure_code: 'blocked', + failure_detail: expect.stringContaining('permission denied'), + }); + expect(callsByTag(stub.calls, 'routingDns')).toHaveLength(1); + expect(await reconcilePendingEmailOperations(env.db, bindings())).toBe(0); + + delete failures.routingDns; + const resumed = await requestEmailDomainSync(env.db, bindings(), routeId, actor); + expect(resumed).toBe(operationId); + await runEmailOperation(env.db, bindings(), resumed); + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'completed', + ); + expect(callsByTag(stub.calls, 'routingDns')).toHaveLength(2); + }); + + it('keeps a Cloudflare request timeout outcome unknown', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'routing-timeout'); + const stub = stubCustomerCf({ + zones, + failOn: { routingDns: { message: 'request timeout', status: 408 } }, + }); + const { operationId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'timeout.example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation).toMatchObject({ + status: 'unknown', + current_step: 'routing_enable', + failure_code: 'outcome_unknown', + failure_detail: expect.stringContaining('request timeout'), + }); + expect(callsByTag(stub.calls, 'routingDns')).toHaveLength(1); + }); + + it('repairs a blocked initial setup with a corrected credential under a new attempt', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'setup-credential-repair'); + const failures: NonNullable[0]>['failOn'] = { + routingDns: { message: 'routing permission denied', status: 403 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const first = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'setup-repair.example.com', + token: TOKEN, + actor, + attemptId: 'initial-setup-attempt', + }); + await runEmailOperation(env.db, bindings(), first.operationId); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, first.operationId)) + )[0], + ).toMatchObject({ status: 'blocked', current_step: 'routing_enable' }); + + delete failures.routingDns; + const replacementInput = { + projectId: project.id, + domain: 'setup-repair.example.com', + token: 'corrected-customer-token', + actor, + attemptId: 'replacement-setup-attempt', + }; + const repaired = await requestEmailDomainAdd(env.db, bindings(), replacementInput); + expect(repaired.operationId).not.toBe(first.operationId); + expect(await requestEmailDomainAdd(env.db, bindings(), replacementInput)).toEqual(repaired); + + await runEmailOperation(env.db, bindings(), repaired.operationId); + + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, repaired.operationId)) + )[0]?.status, + ).toBe('completed'); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, first.operationId)) + )[0]?.status, + ).toBe('blocked'); + expect( + (await resolveEmailDomain(env.db, 'setup-repair.example.com'))?.route.inbound_status, + ).toBe('ready'); + expect(callsByTag(stub.calls, 'routingDns')).toHaveLength(2); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(1); + }); + + it('blocks a failed provider read before its write and resumes without an ambiguous mutation', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'probe-route-preflight'); + const failures: NonNullable[0]>['failOn'] = { + scriptSubdomain: { message: 'subdomain lookup unavailable', status: 503 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const { operationId, routeId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'probe-route.example.com', + token: TOKEN, + actor, + }); + + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation).toMatchObject({ + status: 'blocked', + current_step: 'probe_route_enable', + failure_code: 'blocked', + }); + expect(callsByTag(stub.calls, 'scriptSubdomain')).toMatchObject([{ method: 'GET' }]); + + delete failures.scriptSubdomain; + expect(await requestEmailDomainSync(env.db, bindings(), routeId, actor)).toBe(operationId); + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'completed', + ); + expect( + callsByTag(stub.calls, 'scriptSubdomain').filter((call) => call.method === 'POST'), + ).toHaveLength(1); + }); + + it('blocks a failed catch-all ownership read before its write and resumes safely', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'catchall-preflight'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const { operationId, routeId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'catchall-preflight.example.com', + token: TOKEN, + actor, + }); + failures.catchAllGet = { message: 'catch-all lookup unavailable', status: 503 }; + + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation).toMatchObject({ + status: 'blocked', + current_step: 'catchall_ensure', + failure_code: 'blocked', + }); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(0); + + delete failures.catchAllGet; + expect(await requestEmailDomainSync(env.db, bindings(), routeId, actor)).toBe(operationId); + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'completed', + ); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(1); + }); + + it('retries an attested not-applied routing write only through its exact recovery fence', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'routing-recovery'); + const failures: NonNullable[0]>['failOn'] = { + routingDns: { message: 'response lost', status: 504 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const { operationId, routeId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'recover-routing.example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), operationId); + const old = new Date(Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000).toISOString(); + await env.db + .update(emailOperationSteps) + .set({ started_at: old }) + .where(eq(emailOperationSteps.operation_id, operationId)); + const fence = await inspectUnknownEmailOperationRecovery(env.db, bindings(), operationId); + await expect( + resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + attempt: fence.attempt + 1, + ended: true, + outcome: 'not-applied', + reason: 'Provider audit shows the request did not apply', + }), + ).rejects.toThrow('fence changed'); + + await resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome: 'not-applied', + reason: 'Provider audit shows the request did not apply', + }); + delete failures.routingDns; + await env.db + .update(emailOperationSteps) + .set({ request_digest: 'different-runtime-intent' }) + .where(eq(emailOperationSteps.id, fence.stepId)); + await runEmailOperation(env.db, bindings(), operationId); + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'blocked', + ); + expect(callsByTag(stub.calls, 'routingDns')).toHaveLength(1); + await env.db + .update(emailOperationSteps) + .set({ request_digest: fence.requestDigest }) + .where(eq(emailOperationSteps.id, fence.stepId)); + expect( + await requestEmailDomainSync(env.db, bindings(), routeId, { + kind: 'owner', + userId: owner.id, + }), + ).toBe(operationId); + await runEmailOperation(env.db, bindings(), operationId); + expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( + 'completed', + ); + expect(callsByTag(stub.calls, 'routingDns')).toHaveLength(2); + }); + + it('accepts an attested applied relay upload without replaying the ambiguous write', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'relay-recovery'); + const failures: NonNullable[0]>['failOn'] = { + scriptPut: { message: 'response lost', status: 504 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const { operationId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'recover-relay.example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), operationId); + await env.db + .update(emailOperationSteps) + .set({ + started_at: new Date( + Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000, + ).toISOString(), + }) + .where(eq(emailOperationSteps.operation_id, operationId)); + const fence = await inspectUnknownEmailOperationRecovery(env.db, bindings(), operationId); + expect(fence.step).toBe('ingress_deploy'); + await resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome: 'applied', + reason: 'Cloudflare shows the exact relay upload is active', + }); + delete failures.scriptPut; + await runEmailOperation(env.db, bindings(), operationId); + const operation = (await getEmailOperation(env.db, project.id, operationId))?.operation; + expect(operation?.status).toBe('completed'); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(1); + expect( + ( + await env.db + .select({ version: emailZoneConnections.ingress_version }) + .from(emailZoneConnections) + )[0]?.version, + ).toBeGreaterThan(0); + }); + it('lets newer operations progress while an older write remains unknown', async () => { const owner = await createTestUser(env.db); const project = await createTestProject(env.db, owner.id, 'reconcile-fairness'); @@ -178,15 +499,14 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(2); }); - it('keeps uncertain Sending onboarding recoverable without repeating its write', async () => { + it('applies an attested Sending onboarding result and restores outbound readiness', async () => { const owner = await createTestUser(env.db); const project = await createTestProject(env.db, owner.id, 'sending-uncertain'); const failures: NonNullable[0]>['failOn'] = { onboardSending: { message: 'write outcome unavailable', status: 504 }, sendingSubdomainsGet: { message: 'readback unavailable', status: 504 }, }; - const senders: Array<{ name: string; enabled: boolean }> = []; - const stub = stubCustomerCf({ zones, failOn: failures, sendingSubdomains: senders }); + const stub = stubCustomerCf({ zones, failOn: failures }); const { operationId } = await requestEmailDomainAdd(env.db, bindings(), { projectId: project.id, domain: 'sending.example.com', @@ -201,9 +521,25 @@ describe('durable zone email connections', () => { inbound_status: 'ready', outbound_status: 'pending', }); + await env.db + .update(emailOperationSteps) + .set({ + started_at: new Date( + Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000, + ).toISOString(), + }) + .where(eq(emailOperationSteps.operation_id, operationId)); + const fence = await inspectUnknownEmailOperationRecovery(env.db, bindings(), operationId); + expect(fence.step).toBe('sending_onboard'); + await resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome: 'applied', + reason: 'Cloudflare shows the exact sending domain is active', + }); + delete failures.onboardSending; delete failures.sendingSubdomainsGet; - senders.push({ name: 'sending.example.com', enabled: true }); - await reconcilePendingEmailOperations(env.db, bindings()); + await runEmailOperation(env.db, bindings(), operationId); expect((await getEmailOperation(env.db, project.id, operationId))?.operation.status).toBe( 'completed', ); @@ -213,6 +549,37 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(1); }); + it('keeps a timed-out Sending onboarding unknown when readback is negative', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'sending-negative-readback'); + const stub = stubCustomerCf({ + zones, + sendingSubdomains: [], + failOn: { + onboardSending: { message: 'write outcome unavailable', status: 504 }, + }, + }); + const { operationId } = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'sending-negative.example.com', + token: TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + + await runEmailOperation(env.db, bindings(), operationId); + + expect((await getEmailOperation(env.db, project.id, operationId))?.operation).toMatchObject({ + status: 'unknown', + current_step: 'sending_onboard', + failure_code: 'outcome_unknown', + }); + expect( + (await resolveEmailDomain(env.db, 'sending-negative.example.com'))?.route.outbound_status, + ).toBe('pending'); + expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(1); + expect(callsByTag(stub.calls, 'sendingSubdomainsGet')).toHaveLength(1); + }); + it('does not report sync ready after the domain loses its MX records', async () => { const owner = await createTestUser(env.db); const project = await createTestProject(env.db, owner.id, 'mx-drift'); @@ -303,16 +670,341 @@ describe('durable zone email connections', () => { expect(new Set(syncs).size).toBe(1); }); - it('persists removal behind an unknown setup and resumes after project deletion', async () => { + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'serializes concurrent first assignments on the same Cloudflare zone', + async () => { + const user = await createTestUser(env.db); + const first = await createTestProject(env.db, user.id, 'concurrent-zone-first'); + const second = await createTestProject(env.db, user.id, 'concurrent-zone-second'); + stubCustomerCf({ zones }); + const actor = { kind: 'owner' as const, userId: user.id }; + + const results = await Promise.allSettled([ + requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'concurrent-one.example.com', + actor, + token: TOKEN, + }), + requestEmailDomainAdd(env.db, bindings(), { + projectId: second.id, + domain: 'concurrent-two.example.com', + actor, + token: TOKEN, + }), + ]); + + const acceptedIndex = results.findIndex((result) => result.status === 'fulfilled'); + const accepted = results[acceptedIndex]; + const deferred = results[1 - acceptedIndex]; + expect(acceptedIndex).toBeGreaterThanOrEqual(0); + expect(deferred?.status).toBe('rejected'); + if (accepted?.status !== 'fulfilled' || deferred?.status !== 'rejected') { + throw new Error('expected one accepted assignment and one deferred assignment'); + } + expect(deferred.reason).toMatchObject({ + message: expect.stringMatching(/^connection operation .* is unresolved$/), + status: 409, + }); + expect(await env.db.select().from(emailZoneConnections)).toHaveLength(1); + expect(await env.db.select().from(emailDomainRoutes)).toHaveLength(1); + + await runEmailOperation(env.db, bindings(), accepted.value.operationId); + const deferredProject = acceptedIndex === 0 ? second : first; + const deferredDomain = + deferredProject.id === first.id + ? 'concurrent-one.example.com' + : 'concurrent-two.example.com'; + await requestEmailDomainAdd(env.db, bindings(), { + projectId: deferredProject.id, + domain: deferredDomain, + actor, + token: TOKEN, + }); + expect(await env.db.select().from(emailDomainRoutes)).toHaveLength(2); + }, + 15_000, + ); + + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'keeps provider status read-back behind the route-to-connection removal lock order', + async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'status-removal-lock-order'); + stubCustomerCf({ zones }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'status-removal.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const before = (await resolveEmailDomain(env.db, 'status-removal.example.com'))!; + + let continueRemoval!: () => void; + let routeLocked!: () => void; + const removalMayContinue = new Promise((resolve) => { + continueRemoval = resolve; + }); + const removalHasRoute = new Promise((resolve) => { + routeLocked = resolve; + }); + const removal = env.db.transaction(async (tx) => { + await disableEmailDomainRouteAndDrainTx(tx, added.routeId); + routeLocked(); + await removalMayContinue; + await tx + .select({ id: emailZoneConnections.id }) + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, before.connection.id)) + .for('update'); + }); + await removalHasRoute; + + const status = app.fetch( + new Request( + `http://localhost/projects/${project.id}/email/domains/status-removal.example.com`, + { headers: { Authorization: `Bearer ${user.jwt}` } }, + ), + bindings(), + ); + try { + await waitForPostgresLockWaiters(1); + continueRemoval(); + const results = await Promise.allSettled([status, removal]); + expect(results.every((result) => result.status === 'fulfilled')).toBe(true); + if (results[0]?.status !== 'fulfilled') { + throw results[0]?.reason; + } + expect(results[0].value.status).toBe(200); + expect(await results[0].value.json()).toMatchObject({ status: 'disabled' }); + + const after = (await resolveEmailDomain(env.db, 'status-removal.example.com'))!; + expect(after.route).toMatchObject({ + desired_state: 'disabled', + inbound_status: 'disabled', + }); + expect(after.connection.management_observed_at).toEqual( + before.connection.management_observed_at, + ); + } finally { + continueRemoval(); + await Promise.allSettled([status, removal]); + } + }, + 15_000, + ); + + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'keeps inbound probe read-back behind the route-to-connection removal lock order', + async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'probe-removal-lock-order'); + let gateInboundProbe = false; + let releaseProvider!: () => void; + let providerEntered!: () => void; + const providerMayReturn = new Promise((resolve) => { + releaseProvider = resolve; + }); + const providerWasEntered = new Promise((resolve) => { + providerEntered = resolve; + }); + stubCustomerCf({ + zones, + on: { + routingRulesGet: async () => { + if (!gateInboundProbe) { + return; + } + gateInboundProbe = false; + providerEntered(); + await providerMayReturn; + }, + }, + }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'probe-removal.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + const before = (await resolveEmailDomain(env.db, 'probe-removal.example.com'))!; + + gateInboundProbe = true; + const driver = runEmailOperation(env.db, bindings(), added.operationId); + await providerWasEntered; + + let continueRemoval!: () => void; + let routeLocked!: () => void; + const removalMayContinue = new Promise((resolve) => { + continueRemoval = resolve; + }); + const removalHasRoute = new Promise((resolve) => { + routeLocked = resolve; + }); + const removal = env.db.transaction(async (tx) => { + await disableEmailDomainRouteAndDrainTx(tx, added.routeId); + routeLocked(); + await removalMayContinue; + await tx + .select({ id: emailZoneConnections.id }) + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, before.connection.id)) + .for('update'); + }); + await removalHasRoute; + + try { + releaseProvider(); + await waitForPostgresLockWaiters(1); + continueRemoval(); + const results = await Promise.allSettled([driver, removal]); + expect(results.every((result) => result.status === 'fulfilled')).toBe(true); + + const after = (await resolveEmailDomain(env.db, 'probe-removal.example.com'))!; + expect(after.route).toMatchObject({ + desired_state: 'disabled', + inbound_status: 'disabled', + }); + expect(after.connection.inbound_status).toBe(before.connection.inbound_status); + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, added.operationId)) + )[0]?.status, + ).toBe('blocked'); + } finally { + releaseProvider(); + continueRemoval(); + await Promise.allSettled([driver, removal]); + } + }, + 15_000, + ); + + it.each(['applied', 'not-applied'] as const)( + 'finishes removal after an unknown setup is resolved as %s without resuming setup', + async (outcome) => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'remove-unknown'); + const failures: { scriptPut?: { message: string; status: number } } = { + scriptPut: { message: 'lost response', status: 504 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'unknown.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0]?.status, + ).toBe('unknown'); + const remove = await requestEmailDomainRemove(env.db, bindings(), add.routeId, { + kind: 'system', + }); + expect((await resolveEmailDomain(env.db, 'unknown.example.com'))?.route.desired_state).toBe( + 'disabled', + ); + await runEmailOperation(env.db, bindings(), remove); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + await env.db.delete(projects).where(eq(projects.id, project.id)); + await env.db + .update(emailOperationSteps) + .set({ + started_at: new Date( + Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000, + ).toISOString(), + }) + .where( + and( + eq(emailOperationSteps.operation_id, add.operationId), + eq(emailOperationSteps.status, 'unknown'), + ), + ); + const fence = await inspectUnknownEmailOperationRecovery(env.db, bindings(), add.operationId); + expect(fence.step).toBe('ingress_deploy'); + const resolution = await resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome, + reason: `Provider audit says the relay upload was ${outcome}`, + }); + expect(resolution).toMatchObject({ + operationId: add.operationId, + stepId: fence.stepId, + status: 'completed', + outcome, + }); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0], + ).toMatchObject({ status: 'completed', current_step: null }); + const predecessorSteps = await env.db + .select() + .from(emailOperationSteps) + .where(eq(emailOperationSteps.operation_id, add.operationId)) + .orderBy(emailOperationSteps.ordinal); + const resolvedStep = predecessorSteps.find((step) => step.id === fence.stepId)!; + expect(resolvedStep).toMatchObject({ + status: 'confirmed', + outcome: { + operatorResolution: outcome, + reason: `Provider audit says the relay upload was ${outcome}`, + supersededByRemoval: remove, + }, + }); + const skippedSteps = predecessorSteps.filter((step) => step.ordinal > resolvedStep.ordinal); + expect(skippedSteps.length).toBeGreaterThan(0); + expect( + skippedSteps.every( + (step) => + step.status === 'confirmed' && + (step.outcome as { skipped?: boolean; supersededByRemoval?: string } | null) + ?.skipped === true && + (step.outcome as { skipped?: boolean; supersededByRemoval?: string } | null) + ?.supersededByRemoval === remove, + ), + ).toBe(true); + delete failures.scriptPut; + await runEmailOperation(env.db, bindings(), add.operationId); + await runEmailOperation(env.db, bindings(), remove); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] + ?.status, + ).toBe('completed'); + expect((await resolveEmailDomain(env.db, 'unknown.example.com'))?.route.desired_state).toBe( + 'removed', + ); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(1); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(0); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(0); + expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(0); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + }, + ); + + it('finishes removal after Sending readback confirms a superseded setup', async () => { const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'remove-unknown'); - const failures: { scriptPut?: { message: string; status: number } } = { - scriptPut: { message: 'lost response', status: 504 }, + const project = await createTestProject(env.db, user.id, 'remove-sending-unknown'); + const failures: NonNullable[0]>['failOn'] = { + onboardSending: { message: 'lost response', status: 504 }, + sendingSubdomainsGet: { message: 'readback unavailable', status: 504 }, }; - const stub = stubCustomerCf({ zones, failOn: failures }); + const stub = stubCustomerCf({ + zones, + failOn: failures, + sendingSubdomains: [{ name: 'sending-removal.example.com', enabled: true }], + }); const add = await requestEmailDomainAdd(env.db, bindings(), { projectId: project.id, - domain: 'unknown.example.com', + domain: 'sending-removal.example.com', actor: { kind: 'owner', userId: user.id }, token: TOKEN, }); @@ -320,30 +1012,41 @@ describe('durable zone email connections', () => { expect( ( await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) - )[0]?.status, - ).toBe('unknown'); + )[0], + ).toMatchObject({ status: 'unknown', current_step: 'sending_onboard' }); + const remove = await requestEmailDomainRemove(env.db, bindings(), add.routeId, { kind: 'system', }); - expect((await resolveEmailDomain(env.db, 'unknown.example.com'))?.route.desired_state).toBe( - 'disabled', - ); - await runEmailOperation(env.db, bindings(), remove); - expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); await env.db.delete(projects).where(eq(projects.id, project.id)); - delete failures.scriptPut; - await reconcilePendingEmailOperations(env.db, bindings()); - await reconcilePendingEmailOperations(env.db, bindings()); - // The failed upload cannot be proved by readback, so the removal stays - // durably queued instead of replaying or deleting a possibly live relay. + expect(await reconcileUnknownEmailOperation(env.db, bindings(), add.operationId)).toBe(false); + delete failures.sendingSubdomainsGet; + expect(await reconcileUnknownEmailOperation(env.db, bindings(), add.operationId)).toBe(true); + + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, add.operationId)) + )[0], + ).toMatchObject({ status: 'completed', current_step: null }); + expect(await resolveEmailDomain(env.db, 'sending-removal.example.com')).toMatchObject({ + route: { desired_state: 'disabled', outbound_status: 'pending' }, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + await runEmailOperation(env.db, bindings(), remove); + expect( (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] ?.status, - ).toBe('pending'); - expect((await resolveEmailDomain(env.db, 'unknown.example.com'))?.route.desired_state).toBe( - 'disabled', - ); + ).toBe('completed'); + expect( + (await resolveEmailDomain(env.db, 'sending-removal.example.com'))?.route.desired_state, + ).toBe('removed'); + expect(callsByTag(stub.calls, 'onboardSending')).toHaveLength(1); + expect(callsByTag(stub.calls, 'sendingSubdomainsGet')).toHaveLength(3); expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(1); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(1); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(2); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); }); it('runs a persisted system removal after its project row is gone', async () => { @@ -367,39 +1070,79 @@ describe('durable zone email connections', () => { ); }); - it('keeps ingress while a disabled sibling still owns the connection', async () => { - const user = await createTestUser(env.db); - const first = await createTestProject(env.db, user.id, 'disabled-first'); - const second = await createTestProject(env.db, user.id, 'disabled-second'); - const stub = stubCustomerCf({ zones }); - const a = await requestEmailDomainAdd(env.db, bindings(), { - projectId: first.id, - domain: 'one.example.com', - actor: { kind: 'owner', userId: user.id }, - token: TOKEN, - }); - await runEmailOperation(env.db, bindings(), a.operationId); - const b = await requestEmailDomainAdd(env.db, bindings(), { - projectId: second.id, - domain: 'two.example.com', - actor: { kind: 'owner', userId: user.id }, - token: TOKEN, - }); - await runEmailOperation(env.db, bindings(), b.operationId); - await env.db - .update(emailDomainRoutes) - .set({ desired_state: 'disabled', inbound_status: 'disabled' }) - .where(eq(emailDomainRoutes.id, b.routeId)); - const remove = await requestEmailDomainRemove(env.db, bindings(), a.routeId, { - kind: 'owner', - userId: user.id, - }); - await runEmailOperation(env.db, bindings(), remove); - expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); - expect((await resolveEmailDomain(env.db, 'two.example.com'))?.route.desired_state).toBe( - 'disabled', - ); - }); + it.each([ + { credentialStatus: 'healthy', interruptStep: null }, + { credentialStatus: 'expired', interruptStep: null }, + { credentialStatus: 'expired', interruptStep: 'catchall_detach' }, + { credentialStatus: 'expired', interruptStep: 'ingress_delete' }, + ] as const)( + 'keeps sibling ingress with $credentialStatus credentials after interruption at $interruptStep', + async ({ credentialStatus, interruptStep }) => { + const user = await createTestUser(env.db); + const first = await createTestProject(env.db, user.id, 'disabled-first'); + const second = await createTestProject(env.db, user.id, 'disabled-second'); + const stub = stubCustomerCf({ zones }); + const a = await requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'one.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), a.operationId); + const b = await requestEmailDomainAdd(env.db, bindings(), { + projectId: second.id, + domain: 'two.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), b.operationId); + await env.db + .update(emailDomainRoutes) + .set({ desired_state: 'disabled', inbound_status: 'disabled' }) + .where(eq(emailDomainRoutes.id, b.routeId)); + await env.db.update(emailCredentials).set({ status: credentialStatus }); + const callsBeforeRemoval = stub.calls.length; + const remove = await requestEmailDomainRemove(env.db, bindings(), a.routeId, { + kind: 'owner', + userId: user.id, + }); + if (interruptStep) { + const transaction = env.db.transaction.bind(env.db); + const interrupted = vi.spyOn(env.db, 'transaction').mockImplementation(async (...args) => { + const result = await transaction(...args); + const [operation] = await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, remove)); + if (operation?.current_step === interruptStep) { + interrupted.mockRestore(); + throw new Error('driver exited after transaction commit'); + } + return result; + }); + await expect(runEmailOperation(env.db, bindings(), remove)).rejects.toThrow( + 'driver exited after transaction commit', + ); + await env.db + .update(emailOperationSteps) + .set({ started_at: sql`now() - interval '10 minutes'` }) + .where(eq(emailOperationSteps.operation_id, remove)); + } + await runEmailOperation(env.db, bindings(), remove); + expect((await resolveEmailDomain(env.db, 'one.example.com'))?.route.desired_state).toBe( + 'removed', + ); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, remove)))[0] + ?.status, + ).toBe('completed'); + expect(stub.calls).toHaveLength(callsBeforeRemoval); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + expect((await resolveEmailDomain(env.db, 'two.example.com'))?.route.desired_state).toBe( + 'disabled', + ); + }, + ); it('defers destructive removal while an admitted provider attempt is live', async () => { const user = await createTestUser(env.db); @@ -470,40 +1213,237 @@ describe('durable zone email connections', () => { 'removed', ); - const readded = await requestEmailDomainAdd(env.db, bindings(), { + const readded = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'readd.example.com', + actor, + token: TOKEN, + }); + expect(readded.routeId).toBe(first.routeId); + const pending = (await resolveEmailDomain(env.db, 'readd.example.com'))!; + expect(pending.route.desired_generation).toBeGreaterThan(removedVersion); + expect(pending.route.inbound_status).toBe('pending'); + expect(pending.route.outbound_status).toBe('pending'); + expect(pending.connection.credential_id).not.toBeNull(); + await runEmailOperation(env.db, bindings(), readded.operationId); + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, readded.operationId)) + )[0]?.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(2); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + expect((await resolveEmailDomain(env.db, 'readd.example.com'))?.route.inbound_status).toBe( + 'ready', + ); + await flushEmailCacheOutbox(env.db, env.ROUTING); + const activeVersion = Number(await env.ROUTING.get(`${cacheBase}:latest`)); + expect(activeVersion).toBeGreaterThan(removedVersion); + expect(JSON.parse((await env.ROUTING.get(`${cacheBase}:v${activeVersion}`))!).status).toBe( + 'active', + ); + expect(original.connection.id).toBe(pending.connection.id); + expect(await env.db.select().from(emailCacheOutbox)).toHaveLength(3); + }); + + it.each(['readd-staged.example.com', 'replacement-staged.example.com'])( + 'retires a blocked rotation when the last removed connection is reused by %s', + async (replacementDomain) => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'readd-staged-rotation'); + const failures: NonNullable[0]>['failOn'] = {}; + stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'readd-staged.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const original = (await resolveEmailDomain(env.db, 'readd-staged.example.com'))!.connection; + const rotation = await requestEmailSecretRotation(env.db, bindings(), original.id, actor); + failures.secretPut = { message: 'secret permission denied', status: 403 }; + await runEmailOperation(env.db, bindings(), rotation); + const staged = (await resolveEmailDomain(env.db, 'readd-staged.example.com'))!.connection; + expect(staged.staged_secret_generation).toBe(original.active_secret_generation + 1); + + const removal = await requestEmailDomainRemove(env.db, bindings(), added.routeId, actor); + await runEmailOperation(env.db, bindings(), removal); + expect( + (await resolveEmailDomain(env.db, 'readd-staged.example.com'))?.route.desired_state, + ).toBe('removed'); + expect( + (await resolveEmailDomain(env.db, 'readd-staged.example.com'))?.connection + .staged_secret_generation, + ).toBe(staged.staged_secret_generation); + + delete failures.secretPut; + const readded = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: replacementDomain, + actor, + token: 'readd-corrected-token', + attemptId: 'readd-staged-attempt', + }); + await runEmailOperation(env.db, bindings(), readded.operationId); + + const repaired = (await resolveEmailDomain(env.db, replacementDomain))!; + expect(repaired.route.desired_state).toBe('active'); + expect(repaired.route.inbound_status).toBe('ready'); + expect(repaired.connection.active_secret_generation).toBe(original.active_secret_generation); + expect(repaired.connection.staged_secret_generation).toBeNull(); + expect(repaired.connection.staged_secret_ciphertext).toBeNull(); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('blocked'); + const nextRotation = await requestEmailSecretRotation(env.db, bindings(), original.id, actor); + await runEmailOperation(env.db, bindings(), nextRotation); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, nextRotation)))[0] + ?.status, + ).toBe('completed'); + }, + ); + + it('retires a blocked rotation when a manager-retained connection gets a new domain', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'manager-retained-staged'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'manager-retained-staged.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const original = (await resolveEmailDomain(env.db, 'manager-retained-staged.example.com'))! + .connection; + const rotation = await requestEmailSecretRotation(env.db, bindings(), original.id, actor); + failures.secretPut = { message: 'secret permission denied', status: 403 }; + await runEmailOperation(env.db, bindings(), rotation); + + const removal = await requestEmailDomainRemove(env.db, bindings(), added.routeId, { + kind: 'admin', + userId: 'admin-actor', + }); + await runEmailOperation(env.db, bindings(), removal); + const retained = (await resolveEmailDomain(env.db, 'manager-retained-staged.example.com'))!; + expect(retained.route.desired_state).toBe('removed'); + expect(retained.connection.inbound_status).toBe('ready'); + expect(retained.connection.staged_secret_generation).toBe( + original.active_secret_generation + 1, + ); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + + delete failures.secretPut; + const replacement = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'manager-retained-replacement.example.com', + actor, + token: 'manager-retained-corrected-token', + }); + await runEmailOperation(env.db, bindings(), replacement.operationId); + + const repaired = (await resolveEmailDomain( + env.db, + 'manager-retained-replacement.example.com', + ))!; + expect(repaired.route.inbound_status).toBe('ready'); + expect(repaired.connection.active_secret_generation).toBe(original.active_secret_generation); + expect(repaired.connection.staged_secret_generation).toBeNull(); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('blocked'); + const nextRotation = await requestEmailSecretRotation(env.db, bindings(), original.id, actor); + await runEmailOperation(env.db, bindings(), nextRotation); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, nextRotation)))[0] + ?.status, + ).toBe('completed'); + }); + + it('does not reuse a blocked removal from an older route and connection generation', async () => { + const user = await createTestUser(env.db, 'stale-removal-owner'); + const project = await createTestProject(env.db, user.id, 'stale-removal-project'); + const failures: NonNullable[0]>['failOn'] = {}; + stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'stale-removal.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + + failures.scriptDelete = { message: 'script delete permission denied', status: 403 }; + const staleRemoval = await requestEmailDomainRemove(env.db, bindings(), added.routeId, actor); + await runEmailOperation(env.db, bindings(), staleRemoval); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, staleRemoval)))[0], + ).toMatchObject({ status: 'blocked', current_step: 'ingress_delete' }); + + delete failures.scriptDelete; + const reactivated = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'stale-removal.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), reactivated.operationId); + const removal = await requestEmailDomainRemove(env.db, bindings(), added.routeId, actor); + expect(removal).not.toBe(staleRemoval); + await runEmailOperation(env.db, bindings(), removal); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, staleRemoval)))[0] + ?.status, + ).toBe('blocked'); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, removal)))[0] + ?.status, + ).toBe('completed'); + }); + + it('rejects new external MX records before reactivating a removed route', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'readd-mx-conflict'); + const mx: Record> = {}; + const stub = stubCustomerCf({ zones, mx }); + const actor = { kind: 'owner' as const, userId: user.id }; + const first = await requestEmailDomainAdd(env.db, bindings(), { projectId: project.id, - domain: 'readd.example.com', + domain: 'readd-conflict.example.com', actor, token: TOKEN, }); - expect(readded.routeId).toBe(first.routeId); - const pending = (await resolveEmailDomain(env.db, 'readd.example.com'))!; - expect(pending.route.desired_generation).toBeGreaterThan(removedVersion); - expect(pending.route.inbound_status).toBe('pending'); - expect(pending.route.outbound_status).toBe('pending'); - expect(pending.connection.credential_id).not.toBeNull(); - await runEmailOperation(env.db, bindings(), readded.operationId); - expect( - ( - await env.db - .select() - .from(emailOperations) - .where(eq(emailOperations.id, readded.operationId)) - )[0]?.status, - ).toBe('completed'); - expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(2); - expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); - expect((await resolveEmailDomain(env.db, 'readd.example.com'))?.route.inbound_status).toBe( - 'ready', - ); - await flushEmailCacheOutbox(env.db, env.ROUTING); - const activeVersion = Number(await env.ROUTING.get(`${cacheBase}:latest`)); - expect(activeVersion).toBeGreaterThan(removedVersion); - expect(JSON.parse((await env.ROUTING.get(`${cacheBase}:v${activeVersion}`))!).status).toBe( - 'active', - ); - expect(original.connection.id).toBe(pending.connection.id); - expect(await env.db.select().from(emailCacheOutbox)).toHaveLength(3); + await runEmailOperation(env.db, bindings(), first.operationId); + const removed = await requestEmailDomainRemove(env.db, bindings(), first.routeId, actor); + await runEmailOperation(env.db, bindings(), removed); + const writes = stub.calls.filter((call) => call.method !== 'GET').length; + mx['readd-conflict.example.com'] = ['route1.mx.cloudflare.net', 'mx.external.example.net']; + + await expect( + requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'readd-conflict.example.com', + actor, + token: TOKEN, + }), + ).rejects.toThrow('already has MX'); + + expect(stub.calls.filter((call) => call.method !== 'GET')).toHaveLength(writes); + expect((await resolveEmailDomain(env.db, 'readd-conflict.example.com'))?.route).toMatchObject({ + desired_state: 'removed', + inbound_status: 'disabled', + }); }); it('retains the credential after an uncertain ingress delete until readback proves cleanup', async () => { @@ -550,6 +1490,66 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); }); + it('retries only an attested not-applied ingress delete and completes removal cleanup', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'not-applied-delete'); + const existingScripts: Array = []; + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, existingScripts, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'not-applied-delete.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const connection = (await resolveEmailDomain(env.db, 'not-applied-delete.example.com'))! + .connection; + existingScripts.push(connection.ingress_worker_name); + const removal = await requestEmailDomainRemove(env.db, bindings(), added.routeId, actor); + failures.scriptDelete = { message: 'request ended before Cloudflare applied it', status: 504 }; + + await runEmailOperation(env.db, bindings(), removal); + + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, removal)))[0] + ?.status, + ).toBe('unknown'); + const catchAllWrites = callsByTag(stub.calls, 'catchAll').length; + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + await reconcilePendingEmailOperations(env.db, bindings()); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + + await env.db + .update(emailOperationSteps) + .set({ + started_at: new Date( + Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000, + ).toISOString(), + }) + .where(eq(emailOperationSteps.operation_id, removal)); + const fence = await inspectUnknownEmailOperationRecovery(env.db, bindings(), removal); + expect(fence.step).toBe('ingress_delete'); + await resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome: 'not-applied', + reason: 'Provider audit proves the Worker delete did not apply', + }); + delete failures.scriptDelete; + await runEmailOperation(env.db, bindings(), removal); + + const resolved = await resolveEmailDomain(env.db, 'not-applied-delete.example.com'); + expect(resolved?.route.desired_state).toBe('removed'); + expect(resolved?.connection).toMatchObject({ + inbound_status: 'disabled', + credential_id: null, + }); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(2); + expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(catchAllWrites); + }); + it('transfers only a completed removed assignment and never exposes old operation history', async () => { const manager = await createTestUser(env.db, 'transfer-manager'); const stranger = await createTestUser(env.db, 'transfer-stranger'); @@ -862,6 +1862,269 @@ describe('durable zone email connections', () => { ).toBe('completed'); }); + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'serializes late provider success with unknown-operation read-back', + async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'late-success-mail'); + let gateSecretWrite = false; + let releaseProvider!: () => void; + let enteredProvider!: () => void; + const providerMayReturn = new Promise((resolve) => { + releaseProvider = resolve; + }); + const providerEntered = new Promise((resolve) => { + enteredProvider = resolve; + }); + stubCustomerCf({ + zones, + on: { + secretPut: async () => { + if (gateSecretWrite) { + enteredProvider(); + await providerMayReturn; + } + }, + }, + }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'late-success.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const connection = (await resolveEmailDomain(env.db, 'late-success.example.com'))!.connection; + const operationId = await requestEmailSecretRotation( + env.db, + bindings(), + connection.id, + actor, + ); + + gateSecretWrite = true; + const firstDriver = runEmailOperation(env.db, bindings(), operationId); + await providerEntered; + await env.db + .update(emailOperationSteps) + .set({ started_at: new Date(Date.now() - 10 * 60_000).toISOString() }) + .where( + and( + eq(emailOperationSteps.operation_id, operationId), + eq(emailOperationSteps.status, 'in_flight'), + ), + ); + await runEmailOperation(env.db, bindings(), operationId); + + let releaseOperationLock!: () => void; + let operationLocked!: () => void; + const operationMayUnlock = new Promise((resolve) => { + releaseOperationLock = resolve; + }); + const operationLockAcquired = new Promise((resolve) => { + operationLocked = resolve; + }); + const operationBlocker = env.db.transaction(async (tx) => { + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .for('update'); + operationLocked(); + await operationMayUnlock; + }); + await operationLockAcquired; + + let readBack: Promise | undefined; + try { + releaseProvider(); + await waitForPostgresLockWaiters(1); + readBack = reconcileUnknownEmailOperation(env.db, bindings(), operationId); + await waitForPostgresLockWaiters(2); + releaseOperationLock(); + + const results = await Promise.allSettled([firstDriver, readBack, operationBlocker]); + expect(results.every((result) => result.status === 'fulfilled')).toBe(true); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, operationId)) + )[0]?.status, + ).toBe('completed'); + } finally { + releaseProvider(); + releaseOperationLock(); + await Promise.allSettled([firstDriver, operationBlocker, ...(readBack ? [readBack] : [])]); + } + }, + 15_000, + ); + + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'serializes an expired lease with a late provider failure', + async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'late-failure-mail'); + const failures: NonNullable[0]>['failOn'] = {}; + let gateSecretWrite = false; + let releaseProvider!: () => void; + let enteredProvider!: () => void; + const providerMayReturn = new Promise((resolve) => { + releaseProvider = resolve; + }); + const providerEntered = new Promise((resolve) => { + enteredProvider = resolve; + }); + stubCustomerCf({ + zones, + failOn: failures, + on: { + secretPut: async () => { + if (gateSecretWrite) { + enteredProvider(); + await providerMayReturn; + } + }, + }, + }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'late-failure.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const connection = (await resolveEmailDomain(env.db, 'late-failure.example.com'))!.connection; + const operationId = await requestEmailSecretRotation( + env.db, + bindings(), + connection.id, + actor, + ); + failures.secretPut = { message: 'provider response ended late', status: 504 }; + + gateSecretWrite = true; + const firstDriver = runEmailOperation(env.db, bindings(), operationId); + await providerEntered; + await env.db + .update(emailOperationSteps) + .set({ started_at: new Date(Date.now() - 10 * 60_000).toISOString() }) + .where( + and( + eq(emailOperationSteps.operation_id, operationId), + eq(emailOperationSteps.status, 'in_flight'), + ), + ); + + let releaseOperationLock!: () => void; + let operationLocked!: () => void; + const operationMayUnlock = new Promise((resolve) => { + releaseOperationLock = resolve; + }); + const operationLockAcquired = new Promise((resolve) => { + operationLocked = resolve; + }); + const operationBlocker = env.db.transaction(async (tx) => { + await tx + .select({ id: emailOperations.id }) + .from(emailOperations) + .where(eq(emailOperations.id, operationId)) + .for('update'); + operationLocked(); + await operationMayUnlock; + }); + await operationLockAcquired; + + let expiryDriver: Promise | undefined; + try { + expiryDriver = runEmailOperation(env.db, bindings(), operationId); + await waitForPostgresLockWaiters(1); + releaseProvider(); + await waitForPostgresLockWaiters(2); + releaseOperationLock(); + + const results = await Promise.allSettled([firstDriver, expiryDriver, operationBlocker]); + expect(results.every((result) => result.status === 'fulfilled')).toBe(true); + const operation = ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, operationId)) + )[0]; + const step = ( + await env.db + .select() + .from(emailOperationSteps) + .where(eq(emailOperationSteps.operation_id, operationId)) + .orderBy(emailOperationSteps.ordinal) + )[0]; + expect(operation).toMatchObject({ status: 'unknown', current_step: 'secret_put' }); + expect(step).toMatchObject({ status: 'unknown', failure_code: 'outcome_unknown' }); + } finally { + releaseProvider(); + releaseOperationLock(); + await Promise.allSettled([ + firstDriver, + operationBlocker, + ...(expiryDriver ? [expiryDriver] : []), + ]); + } + }, + 15_000, + ); + + it.runIf(Boolean(process.env.VOID_TEST_DATABASE_URL))( + 'keeps operator recovery ineligible for 24 real hours under a non-UTC process timezone', + async () => { + const previousTimezone = process.env.TZ; + process.env.TZ = 'Asia/Singapore'; + try { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'recovery-timezone-mail'); + stubCustomerCf({ + zones, + failOn: { scriptPut: { message: 'provider response lost', status: 504 } }, + }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'recovery-timezone.example.com', + actor: { kind: 'owner', userId: user.id }, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + await env.db + .update(emailOperationSteps) + .set({ started_at: sql`now() - interval '23 hours'` }) + .where( + and( + eq(emailOperationSteps.operation_id, added.operationId), + eq(emailOperationSteps.status, 'unknown'), + ), + ); + + const fence = await inspectUnknownEmailOperationRecovery( + env.db, + bindings(), + added.operationId, + ); + expect(Date.parse(fence.eligibleAt)).toBeGreaterThan(Date.now()); + await expect( + resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome: 'not-applied', + reason: 'Provider audit completed before the minimum recovery age', + }), + ).rejects.toThrow('cannot be resolved before'); + } finally { + if (previousTimezone === undefined) { + delete process.env.TZ; + } else { + process.env.TZ = previousTimezone; + } + } + }, + 15_000, + ); + it('promotes a rotated secret only after the gateway accepts it', async () => { const user = await createTestUser(env.db), project = await createTestProject(env.db, user.id, 'rotation-mail'); @@ -911,6 +2174,62 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); }); + it('blocks secret rotation before the provider write when its credential is unavailable', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'rotation-credential-preflight'); + const stub = stubCustomerCf({ zones }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'rotation-credential.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const connection = (await resolveEmailDomain(env.db, 'rotation-credential.example.com'))! + .connection; + const operationId = await requestEmailSecretRotation( + env.db, + bindings(), + connection.id, + actor, + 'credential-preflight-rotation', + ); + await env.db + .update(emailCredentials) + .set({ status: 'revoked' }) + .where(eq(emailCredentials.id, connection.credential_id!)); + const writesBefore = callsByTag(stub.calls, 'secretPut').length; + + await runEmailOperation(env.db, bindings(), operationId); + + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, operationId)))[0], + ).toMatchObject({ status: 'blocked', current_step: 'secret_put', failure_code: 'blocked' }); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(writesBefore); + + await env.db + .update(emailCredentials) + .set({ status: 'healthy' }) + .where(eq(emailCredentials.id, connection.credential_id!)); + expect( + await requestEmailSecretRotation( + env.db, + bindings(), + connection.id, + actor, + 'credential-preflight-rotation', + ), + ).toBe(operationId); + await runEmailOperation(env.db, bindings(), operationId); + + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, operationId)))[0] + ?.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(writesBefore + 1); + }); + it('recovers a lost secret PUT response by proving the staged deployed value', async () => { const user = await createTestUser(env.db), project = await createTestProject(env.db, user.id, 'lost-rotation'); @@ -943,6 +2262,244 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); }); + it('retries an attested not-applied secret write with the same staged generation', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'not-applied-rotation'); + const failures: NonNullable[0]>['failOn'] = {}; + const failBeforeEffect: Array<'secretPut'> = []; + const stub = stubCustomerCf({ zones, failOn: failures, failBeforeEffect }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'not-applied-rotation.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const before = (await resolveEmailDomain(env.db, 'not-applied-rotation.example.com'))! + .connection; + const setupSecretWrites = callsByTag(stub.calls, 'secretPut').length; + const setupScriptWrites = callsByTag(stub.calls, 'scriptPut').length; + const rotation = await requestEmailSecretRotation(env.db, bindings(), before.id, actor); + failures.secretPut = { message: 'request ended before Cloudflare applied it', status: 504 }; + failBeforeEffect.push('secretPut'); + + await runEmailOperation(env.db, bindings(), rotation); + + const staged = ( + await env.db.select().from(emailZoneConnections).where(eq(emailZoneConnections.id, before.id)) + )[0]!; + expect(staged.staged_secret_generation).toBe(before.active_secret_generation + 1); + await reconcilePendingEmailOperations(env.db, bindings()); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('unknown'); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(setupSecretWrites + 1); + + await env.db + .update(emailOperationSteps) + .set({ + started_at: new Date( + Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000, + ).toISOString(), + }) + .where(eq(emailOperationSteps.operation_id, rotation)); + const fence = await inspectUnknownEmailOperationRecovery(env.db, bindings(), rotation); + expect(fence).toMatchObject({ + step: 'secret_put', + desiredGeneration: staged.desired_generation, + routeId: null, + routeDesiredGeneration: null, + }); + expect(fence.resourceIdentity).toContain(`/secret/${staged.staged_secret_generation}`); + await resolveUnknownEmailOperation(env.db, bindings(), { + ...fence, + ended: true, + outcome: 'not-applied', + reason: 'Provider audit proves the secret write did not apply', + }); + delete failures.secretPut; + failBeforeEffect.length = 0; + await runEmailOperation(env.db, bindings(), rotation); + + const promoted = ( + await env.db.select().from(emailZoneConnections).where(eq(emailZoneConnections.id, before.id)) + )[0]!; + expect(promoted.active_secret_generation).toBe(staged.staged_secret_generation); + expect(promoted.staged_secret_generation).toBeNull(); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('completed'); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(setupSecretWrites + 2); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(setupScriptWrites); + }); + + it('resumes a blocked secret rotation without replacing its staged generation', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'blocked-rotation'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'blocked-rotation.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const before = (await resolveEmailDomain(env.db, 'blocked-rotation.example.com'))!.connection; + const rotation = await requestEmailSecretRotation(env.db, bindings(), before.id, actor); + failures.secretPut = { message: 'secret permission denied', status: 403 }; + await runEmailOperation(env.db, bindings(), rotation); + const staged = ( + await env.db.select().from(emailZoneConnections).where(eq(emailZoneConnections.id, before.id)) + )[0]!; + expect(staged.staged_secret_generation).toBe(before.active_secret_generation + 1); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0], + ).toMatchObject({ status: 'blocked', current_step: 'secret_put' }); + + delete failures.secretPut; + const resumed = await requestEmailSecretRotation(env.db, bindings(), before.id, actor); + expect(resumed).toBe(rotation); + await runEmailOperation(env.db, bindings(), resumed); + const promoted = ( + await env.db.select().from(emailZoneConnections).where(eq(emailZoneConnections.id, before.id)) + )[0]!; + expect(promoted.active_secret_generation).toBe(before.active_secret_generation + 1); + expect(promoted.staged_secret_generation).toBeNull(); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(3); + }); + + it('repairs a blocked rotation with a corrected credential before retiring its staged secret', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'rotation-credential-repair'); + const failures: NonNullable[0]>['failOn'] = {}; + stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'rotation-repair.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + const before = (await resolveEmailDomain(env.db, 'rotation-repair.example.com'))!.connection; + const rotation = await requestEmailSecretRotation(env.db, bindings(), before.id, actor); + failures.secretPut = { message: 'replacement token lacks secret permission', status: 403 }; + await runEmailOperation(env.db, bindings(), rotation); + const staged = (await resolveEmailDomain(env.db, 'rotation-repair.example.com'))!.connection; + expect(staged.staged_secret_generation).toBe(before.active_secret_generation + 1); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0], + ).toMatchObject({ status: 'blocked', current_step: 'secret_put' }); + + delete failures.secretPut; + failures.gatewayProbe = { message: 'gateway proof temporarily unavailable', status: 503 }; + const replacementInput = { + projectId: project.id, + domain: 'rotation-repair.example.com', + actor, + token: 'corrected-rotation-token', + attemptId: 'replacement-rotation-credential', + }; + const repair = await requestEmailDomainAdd(env.db, bindings(), replacementInput); + expect(await requestEmailDomainAdd(env.db, bindings(), replacementInput)).toEqual(repair); + await runEmailOperation(env.db, bindings(), repair.operationId); + + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, repair.operationId)) + )[0], + ).toMatchObject({ status: 'unknown', current_step: 'gateway_probe' }); + const awaitingProof = (await resolveEmailDomain(env.db, 'rotation-repair.example.com'))! + .connection; + expect(awaitingProof.active_secret_generation).toBe(before.active_secret_generation); + expect(awaitingProof.staged_secret_generation).toBe(staged.staged_secret_generation); + + delete failures.gatewayProbe; + await reconcilePendingEmailOperations(env.db, bindings()); + + const repaired = (await resolveEmailDomain(env.db, 'rotation-repair.example.com'))!.connection; + expect(repaired.active_secret_generation).toBe(before.active_secret_generation); + expect(repaired.staged_secret_generation).toBeNull(); + expect(repaired.staged_secret_ciphertext).toBeNull(); + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, repair.operationId)) + )[0]?.status, + ).toBe('completed'); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, rotation)))[0] + ?.status, + ).toBe('blocked'); + expect( + await env.db + .select({ kind: emailOperationSteps.kind }) + .from(emailOperationSteps) + .where(eq(emailOperationSteps.operation_id, repair.operationId)) + .orderBy(emailOperationSteps.ordinal), + ).toContainEqual({ kind: 'secret_retire' }); + }); + + it('resumes a blocked removal without changing its route generation', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'blocked-removal'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const add = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'blocked-removal.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), add.operationId); + + failures.scriptDelete = { message: 'script delete permission denied', status: 403 }; + const removalKey = 'blocked-removal-attempt'; + const removal = await requestEmailDomainRemove( + env.db, + bindings(), + add.routeId, + actor, + removalKey, + ); + await runEmailOperation(env.db, bindings(), removal); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, removal)))[0], + ).toMatchObject({ status: 'blocked', current_step: 'ingress_delete' }); + const disabled = (await resolveEmailDomain(env.db, 'blocked-removal.example.com'))!.route; + expect(disabled.desired_state).toBe('disabled'); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + + delete failures.scriptDelete; + expect(await requestEmailDomainRemove(env.db, bindings(), add.routeId, actor, removalKey)).toBe( + removal, + ); + expect( + (await resolveEmailDomain(env.db, 'blocked-removal.example.com'))!.route.desired_generation, + ).toBe(disabled.desired_generation); + await runEmailOperation(env.db, bindings(), removal); + + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, removal)))[0] + ?.status, + ).toBe('completed'); + expect( + (await resolveEmailDomain(env.db, 'blocked-removal.example.com'))!.route.desired_state, + ).toBe('removed'); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(2); + }); + it('does not replace a foreign zone catch-all', async () => { const user = await createTestUser(env.db), project = await createTestProject(env.db, user.id, 'foreign-mail'); @@ -1048,7 +2605,9 @@ describe('durable zone email connections', () => { await runEmailOperation(env.db, shared, remove); const removedRoute = (await resolveEmailDomain(env.db, 'alerts.example.com'))!.route; expect(removedRoute.desired_state).toBe('removed'); - expect(await disableEmailDomainRouteAndDrain(env.db, removedRoute.id)).toEqual({ + expect( + await env.db.transaction((tx) => disableEmailDomainRouteAndDrainTx(tx, removedRoute.id)), + ).toEqual({ cancelled: 0, inFlight: 0, }); diff --git a/platform/packages/api/test/integration/email-domain-cf-stub.ts b/platform/packages/api/test/integration/email-domain-cf-stub.ts index b0a0d5814..169c27d6a 100644 --- a/platform/packages/api/test/integration/email-domain-cf-stub.ts +++ b/platform/packages/api/test/integration/email-domain-cf-stub.ts @@ -56,6 +56,8 @@ export function stubCustomerCf( /** GET sending/subdomains entries; default []. */ sendingSubdomains?: ReadonlyArray<{ name: string; enabled: boolean }>; failOn?: Partial>; + /** Tags whose configured failure is returned before the provider-side mutation occurs. */ + failBeforeEffect?: ReadonlyArray; /** Side-effect hook fired right after a call is recorded (mid-request seams). */ on?: Partial void | Promise>>; } = {}, @@ -327,11 +329,6 @@ export function stubCustomerCf( if (secretsMatch && method === 'PUT') { const parsed = typeof init?.body === 'string' ? JSON.parse(init.body) : {}; const text = typeof parsed.text === 'string' ? parsed.text : ''; - // The worker's CURRENT secret, tracked by sha256 only — the same - // form the ROUTING mirror stores — so a test can prove worker, row - // and mirror carry ONE secret without the value ever being recorded. - secretHashes.set(secretsMatch[1]!, await sha256Hex(text)); - relaySecrets.set(secretsMatch[1]!, text); await record({ tag: 'secretPut', method, @@ -343,6 +340,14 @@ export function stubCustomerCf( textShape: `len=${text.length} ${/^[A-Za-z0-9_-]+$/.test(text) ? 'base64url' : 'other'}`, }, }); + if (config.failBeforeEffect?.includes('secretPut')) { + return fail('secretPut') ?? cfSuccess({}); + } + // The worker's CURRENT secret, tracked by sha256 only — the same + // form the ROUTING mirror stores — so a test can prove worker, row + // and mirror carry ONE secret without the value ever being recorded. + secretHashes.set(secretsMatch[1]!, await sha256Hex(text)); + relaySecrets.set(secretsMatch[1]!, text); return fail('secretPut') ?? cfSuccess({}); } diff --git a/platform/packages/api/test/integration/operator-audit.test.ts b/platform/packages/api/test/integration/operator-audit.test.ts index a58a8be29..2db2a4917 100644 --- a/platform/packages/api/test/integration/operator-audit.test.ts +++ b/platform/packages/api/test/integration/operator-audit.test.ts @@ -161,6 +161,9 @@ test('records complete and partial 207 mutation outcomes as failed', async () => const events = await env.db.select().from(operatorEvents); expect(events).toHaveLength(2); + expect( + JSON.parse(events.find((event) => event.action === 'workers/rollback-all')!.target!), + ).toMatchObject({ versions: { 'email-gateway': 'previous' } }); expect(events).toEqual( expect.arrayContaining([ expect.objectContaining({ diff --git a/platform/packages/api/test/integration/operator-email-domains.test.ts b/platform/packages/api/test/integration/operator-email-domains.test.ts index ca33d31ed..cea7fbd99 100644 --- a/platform/packages/api/test/integration/operator-email-domains.test.ts +++ b/platform/packages/api/test/integration/operator-email-domains.test.ts @@ -1,3 +1,4 @@ +import { eq } from 'drizzle-orm'; import { afterAll, afterEach, @@ -8,9 +9,22 @@ import { it, vi, } from 'vite-plus/test'; -import { emailDomainRoutes, emailZoneConnections } from '../../src/email/connection-schema.ts'; +import { + emailCredentials, + emailDomainRoutes, + emailOperations, + emailOperationSteps, + emailZoneConnections, +} from '../../src/email/connection-schema.ts'; +import { + EMAIL_OPERATION_RECOVERY_MIN_AGE_MS, + requestEmailDomainAdd, + requestEmailDomainRemove, + runEmailOperation, +} from '../../src/email/connection-service.ts'; import type { ApiEnv } from '../../src/env.ts'; import app from '../../src/index.ts'; +import { operatorEvents, projects } from '../../src/schema.ts'; import { callsByTag, stubCustomerCf } from './email-domain-cf-stub.ts'; import { CF_ACCOUNT_ID, @@ -27,6 +41,13 @@ let env: TestEnv, operatorToken: string; const zones = { 'example.com': { id: 'zone-platform', name: 'example.com', accountId: CF_ACCOUNT_ID }, }; +const OWNER_TOKEN = 'owner-scoped-token'; +function bindings(): ApiEnv['Bindings'] { + return { + ...env, + EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test', + } as unknown as ApiEnv['Bindings']; +} function request(path: string, body?: Record, token = operatorToken) { return app.fetch( new Request(`http://localhost/operator/v1${path}`, { @@ -37,10 +58,7 @@ function request(path: string, body?: Record, token = operatorT }, body: body ? JSON.stringify(body) : undefined, }), - { - ...env, - EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test', - } as unknown as ApiEnv['Bindings'], + bindings(), ); } beforeAll(async () => { @@ -114,4 +132,482 @@ describe('operator email domain management', () => { expect(callsByTag(stub.calls, 'catchAll')).toHaveLength(0); expect(await env.db.select().from(emailDomainRoutes)).toHaveLength(0); }); + + it('previews and applies an exact aged unknown-write recovery fence', async () => { + const owner = await createTestUser(env.db, 'recovery-owner'); + const project = await createTestProject(env.db, owner.id, 'recovery-project'); + stubCustomerCf({ + zones, + failOn: { scriptPut: { message: 'response lost', status: 504 } }, + }); + const added = await request('/email/domains', { + domain: 'recovery.example.com', + project: project.slug, + }); + expect(await added.json()).toMatchObject({ + ok: false, + domain: { operationStatus: 'unknown' }, + }); + expect(await env.db.select().from(operatorEvents)).toEqual([ + expect.objectContaining({ action: 'email/domains', status: 'failed' }), + ]); + const [operation] = await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.status, 'unknown')); + expect(operation?.current_step).toBe('ingress_deploy'); + const tooRecent = await request(`/email/operations/${operation!.id}/resolve`, { + ended: true, + outcome: 'not-applied', + reason: 'Provider audit completed', + dryRun: true, + }); + expect(tooRecent.status).toBe(409); + await env.db + .update(emailOperationSteps) + .set({ + started_at: new Date( + Date.now() - EMAIL_OPERATION_RECOVERY_MIN_AGE_MS - 1_000, + ).toISOString(), + }) + .where(eq(emailOperationSteps.operation_id, operation!.id)); + const preview = await request(`/email/operations/${operation!.id}/resolve`, { + ended: true, + outcome: 'not-applied', + reason: 'Provider audit completed', + dryRun: true, + }); + expect(preview.status).toBe(200); + const target = ((await preview.json()) as { target: Record }).target; + expect(target).toMatchObject({ + operationId: operation!.id, + step: 'ingress_deploy', + outcome: 'not-applied', + }); + const applied = await request(`/email/operations/${operation!.id}/resolve`, { + ended: true, + outcome: 'not-applied', + reason: 'Provider audit completed', + stepId: target.stepId, + attempt: target.attempt, + requestDigest: target.requestDigest, + resourceIdentity: target.resourceIdentity, + connectionId: target.connectionId, + desiredGeneration: target.desiredGeneration, + routeId: target.routeId, + routeDesiredGeneration: target.routeDesiredGeneration, + }); + expect(applied.status).toBe(200); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, operation!.id)))[0] + ?.status, + ).toBe('pending'); + }); + + it('reports blocked setup as failure and a completed sync as success', async () => { + const owner = await createTestUser(env.db, 'blocked-owner'); + const project = await createTestProject(env.db, owner.id, 'blocked-project'); + const failOn: { scriptPut?: { message: string; status: number } } = { + scriptPut: { message: 'Permission denied', status: 403 }, + }; + stubCustomerCf({ zones, failOn }); + const added = await request('/email/domains', { + domain: 'blocked.example.com', + project: project.slug, + }); + expect(await added.json()).toMatchObject({ + ok: false, + domain: { operationStatus: 'blocked' }, + }); + expect(await env.db.select().from(operatorEvents)).toEqual([ + expect.objectContaining({ action: 'email/domains', status: 'failed' }), + ]); + + delete failOn.scriptPut; + const synced = await request('/email/domains/blocked.example.com/sync', {}); + const result = await synced.json(); + expect(result).toMatchObject({ domain: { operationStatus: 'completed' } }); + expect(result).not.toHaveProperty('ok', false); + expect( + await env.db + .select() + .from(operatorEvents) + .where(eq(operatorEvents.action, 'email/domains/blocked.example.com/sync')), + ).toEqual([expect.objectContaining({ status: 'success' })]); + }); + + it('lets an administrator finish blocked cleanup after the project is deleted', async () => { + const owner = await createTestUser(env.db, 'deleted-cleanup-owner'); + const project = await createTestProject(env.db, owner.id, 'deleted-cleanup-project'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const added = await request('/email/domains', { + domain: 'deleted-cleanup.example.com', + project: project.slug, + }); + expect(added.status).toBe(200); + const [route] = await env.db.select().from(emailDomainRoutes); + failures.scriptDelete = { message: 'script delete permission denied', status: 403 }; + const cleanup = await requestEmailDomainRemove( + env.db, + bindings(), + route!.id, + { kind: 'system' }, + `teardown:${project.id}:${route!.id}`, + ); + await runEmailOperation(env.db, bindings(), cleanup); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, cleanup)))[0], + ).toMatchObject({ status: 'blocked', current_step: 'ingress_delete' }); + + await env.db.delete(projects).where(eq(projects.id, project.id)); + delete failures.scriptDelete; + const removed = await request('/email/domains/deleted-cleanup.example.com/remove', {}); + expect(removed.status).toBe(200); + expect(await removed.json()).toMatchObject({ + domain: { removed: true, operationStatus: 'completed' }, + }); + expect( + (await env.db.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.id, route!.id)))[0] + ?.desired_state, + ).toBe('removed'); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(2); + }); + + it('resumes an owner-managed system cleanup after the project is deleted', async () => { + const owner = await createTestUser(env.db, 'deleted-owner-cleanup-owner'); + const project = await createTestProject(env.db, owner.id, 'deleted-owner-cleanup-project'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'deleted-owner-cleanup.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + expect((await env.db.select().from(emailZoneConnections))[0]?.managed_by).toBe('owner'); + + failures.scriptDelete = { message: 'script delete permission denied', status: 403 }; + const cleanup = await requestEmailDomainRemove( + env.db, + bindings(), + added.routeId, + { kind: 'system' }, + `teardown:${project.id}:${added.routeId}`, + ); + await runEmailOperation(env.db, bindings(), cleanup); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, cleanup)))[0], + ).toMatchObject({ + actor_kind: 'system', + status: 'blocked', + current_step: 'ingress_delete', + }); + + await env.db.delete(projects).where(eq(projects.id, project.id)); + delete failures.scriptDelete; + const removed = await request('/email/domains/deleted-owner-cleanup.example.com/remove', {}); + expect(removed.status).toBe(200); + expect(await removed.json()).toMatchObject({ + domain: { operationId: cleanup, removed: true, operationStatus: 'completed' }, + }); + expect( + (await env.db.select().from(emailOperations)).filter( + (operation) => operation.kind === 'remove', + ), + ).toHaveLength(1); + expect((await env.db.select().from(emailZoneConnections))[0]?.credential_id).toBeNull(); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(2); + }); + + it('replaces an expired credential only to finish the original orphaned system cleanup', async () => { + const owner = await createTestUser(env.db, 'replacement-cleanup-owner'); + const project = await createTestProject(env.db, owner.id, 'replacement-cleanup-project'); + const stub = stubCustomerCf({ zones }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'replacement-cleanup.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const [connectionBefore] = await env.db.select().from(emailZoneConnections); + await env.db.update(emailCredentials).set({ status: 'expired' }); + const cleanup = await requestEmailDomainRemove( + env.db, + bindings(), + added.routeId, + { kind: 'system' }, + `teardown:${project.id}:${added.routeId}`, + ); + await runEmailOperation(env.db, bindings(), cleanup); + const cleanupBefore = ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, cleanup)) + )[0]!; + expect(cleanupBefore).toMatchObject({ + actor_kind: 'system', + status: 'blocked', + current_step: 'catchall_detach', + }); + + await env.db.delete(projects).where(eq(projects.id, project.id)); + const checkpoint = stub.calls.length; + const preview = await request('/email/domains/replacement-cleanup.example.com/remove', { + apiToken: 'replacement-scoped-token', + dryRun: true, + }); + expect(preview.status).toBe(200); + expect(await preview.json()).toMatchObject({ + dryRun: true, + target: { credentialReplacement: true }, + effect: expect.stringContaining('resumes the retained blocked project cleanup'), + }); + expect(stub.calls).toHaveLength(checkpoint); + const removed = await request('/email/domains/replacement-cleanup.example.com/remove', { + apiToken: 'replacement-scoped-token', + }); + expect(removed.status).toBe(200); + expect(await removed.json()).toMatchObject({ + domain: { operationId: cleanup, removed: true, operationStatus: 'completed' }, + }); + const [connectionAfter] = await env.db.select().from(emailZoneConnections); + expect(connectionAfter).toMatchObject({ + managed_by: connectionBefore!.managed_by, + manager_user_id: connectionBefore!.manager_user_id, + desired_generation: cleanupBefore.desired_generation, + credential_id: null, + }); + expect( + (await env.db.select().from(emailOperations)).filter( + (operation) => operation.kind === 'remove', + ), + ).toHaveLength(1); + expect(callsByTag(stub.calls, 'verifyToken')).toHaveLength(2); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + }); + + it('rejects cleanup credential replacement for an active owner, sibling, or unresolved operation', async () => { + const owner = await createTestUser(env.db, 'guarded-replacement-owner'); + const project = await createTestProject(env.db, owner.id, 'guarded-replacement-project'); + const stub = stubCustomerCf({ zones }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'guarded-replacement.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const [connection] = await env.db.select().from(emailZoneConnections); + await env.db.update(emailCredentials).set({ status: 'expired' }); + const cleanup = await requestEmailDomainRemove( + env.db, + bindings(), + added.routeId, + { kind: 'system' }, + `teardown:${project.id}:${added.routeId}`, + ); + await runEmailOperation(env.db, bindings(), cleanup); + const activeOwner = await request('/email/domains/guarded-replacement.example.com/remove', { + apiToken: 'replacement-scoped-token', + }); + expect(activeOwner.status).toBe(409); + await env.db.update(projects).set({ status: 'deleting' }).where(eq(projects.id, project.id)); + await env.db.insert(emailDomainRoutes).values({ + id: 'replacement-sibling', + domain: 'replacement-sibling.example.com', + connection_id: connection!.id, + project_id: project.id, + addressing: 'custom', + managed_by: 'owner', + assigned_by_user_id: owner.id, + }); + + const sibling = await request('/email/domains/guarded-replacement.example.com/remove', { + apiToken: 'replacement-scoped-token', + }); + expect(sibling.status).toBe(409); + await env.db + .update(emailDomainRoutes) + .set({ desired_state: 'removed' }) + .where(eq(emailDomainRoutes.id, 'replacement-sibling')); + await env.db.insert(emailOperations).values({ + id: 'replacement-unresolved', + installation_id: connection!.installation_id, + connection_id: connection!.id, + actor_kind: 'system', + actor_scope: 'system', + kind: 'cleanup', + idempotency_key: 'replacement-unresolved', + request_digest: 'a'.repeat(64), + desired_generation: connection!.desired_generation, + }); + for (const status of ['pending', 'running', 'unknown'] as const) { + await env.db + .update(emailOperations) + .set({ status }) + .where(eq(emailOperations.id, 'replacement-unresolved')); + const unresolved = await request('/email/domains/guarded-replacement.example.com/remove', { + apiToken: 'replacement-scoped-token', + }); + expect(unresolved.status).toBe(409); + } + expect(callsByTag(stub.calls, 'verifyToken')).toHaveLength(1); + }); + + it('reclaims an admin-removed final owner connection during project teardown', async () => { + const owner = await createTestUser(env.db, 'teardown-owner-cleanup-owner'); + const first = await createTestProject(env.db, owner.id, 'teardown-owner-cleanup-first'); + const second = await createTestProject(env.db, owner.id, 'teardown-owner-cleanup-second'); + const stub = stubCustomerCf({ zones }); + const firstAdded = await requestEmailDomainAdd(env.db, bindings(), { + projectId: first.id, + domain: 'teardown-first.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), firstAdded.operationId); + const secondAdded = await requestEmailDomainAdd(env.db, bindings(), { + projectId: second.id, + domain: 'teardown-second.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), secondAdded.operationId); + + expect((await request('/email/domains/teardown-first.example.com/remove', {})).status).toBe( + 200, + ); + expect( + ( + await app.fetch( + new Request(`http://localhost/projects/${first.id}`, { + method: 'DELETE', + headers: { Authorization: `Bearer ${owner.jwt}` }, + }), + bindings(), + ) + ).status, + ).toBe(200); + expect( + (await env.db.select().from(emailOperations)).filter( + (operation) => operation.kind === 'remove', + ), + ).toHaveLength(1); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(0); + + expect((await request('/email/domains/teardown-second.example.com/remove', {})).status).toBe( + 200, + ); + expect((await env.db.select().from(emailZoneConnections))[0]?.credential_id).not.toBeNull(); + expect( + ( + await app.fetch( + new Request(`http://localhost/projects/${second.id}`, { + method: 'DELETE', + headers: { Authorization: `Bearer ${owner.jwt}` }, + }), + bindings(), + ) + ).status, + ).toBe(200); + + const removals = (await env.db.select().from(emailOperations)).filter( + (operation) => operation.kind === 'remove', + ); + expect(removals).toHaveLength(3); + expect(removals).toContainEqual( + expect.objectContaining({ + route_id: secondAdded.routeId, + actor_kind: 'system', + status: 'completed', + }), + ); + expect((await env.db.select().from(emailZoneConnections))[0]?.credential_id).toBeNull(); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + }); + + it('does not let a stale project teardown remove a reassigned route', async () => { + const owner = await createTestUser(env.db, 'stale-teardown-owner'); + const original = await createTestProject(env.db, owner.id, 'stale-teardown-original'); + const replacement = await createTestProject(env.db, owner.id, 'stale-teardown-replacement'); + stubCustomerCf({ zones }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: original.id, + domain: 'stale-teardown.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + expect((await request('/email/domains/stale-teardown.example.com/remove', {})).status).toBe( + 200, + ); + const reassigned = await requestEmailDomainAdd(env.db, bindings(), { + projectId: replacement.id, + domain: 'stale-teardown.example.com', + token: OWNER_TOKEN, + actor: { kind: 'owner', userId: owner.id }, + }); + await runEmailOperation(env.db, bindings(), reassigned.operationId); + + expect( + await requestEmailDomainRemove( + env.db, + bindings(), + reassigned.routeId, + { kind: 'system' }, + `teardown:${original.id}:${reassigned.routeId}`, + original.id, + ), + ).toBeNull(); + expect( + ( + await env.db.select().from(emailDomainRoutes).where(eq(emailDomainRoutes.id, added.routeId)) + )[0], + ).toMatchObject({ project_id: replacement.id, desired_state: 'active' }); + expect( + (await env.db.select().from(emailOperations)).filter( + (operation) => operation.kind === 'remove', + ), + ).toHaveLength(1); + }); + + it('does not replay unknown cleanup after the project is deleted', async () => { + const owner = await createTestUser(env.db, 'unknown-cleanup-owner'); + const project = await createTestProject(env.db, owner.id, 'unknown-cleanup-project'); + const failures: NonNullable[0]>['failOn'] = {}; + const stub = stubCustomerCf({ zones, failOn: failures }); + const added = await request('/email/domains', { + domain: 'unknown-cleanup.example.com', + project: project.slug, + }); + expect(added.status).toBe(200); + const [route] = await env.db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.domain, 'unknown-cleanup.example.com')); + failures.scriptDelete = { message: 'script delete response lost', status: 504 }; + const cleanup = await requestEmailDomainRemove( + env.db, + bindings(), + route!.id, + { kind: 'system' }, + `teardown:${project.id}:${route!.id}`, + ); + await runEmailOperation(env.db, bindings(), cleanup); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, cleanup)))[0] + ?.status, + ).toBe('unknown'); + + await env.db.delete(projects).where(eq(projects.id, project.id)); + delete failures.scriptDelete; + const retained = await request('/email/domains/unknown-cleanup.example.com/remove', {}); + expect(retained.status).toBe(200); + expect(await retained.json()).toMatchObject({ + ok: false, + domain: { operationId: cleanup, operationStatus: 'unknown' }, + }); + expect(callsByTag(stub.calls, 'scriptDelete')).toHaveLength(1); + }); }); diff --git a/platform/packages/api/test/integration/operator-email.test.ts b/platform/packages/api/test/integration/operator-email.test.ts index 3f314929a..555b5a397 100644 --- a/platform/packages/api/test/integration/operator-email.test.ts +++ b/platform/packages/api/test/integration/operator-email.test.ts @@ -11,7 +11,9 @@ import { } from 'vite-plus/test'; import { emailActionRecipients, + emailActions, emailProjectControls, + emailReceipts, emailUnresolvedAttempts, } from '../../src/email/admission-schema.ts'; import { @@ -26,7 +28,7 @@ import { } from '../../src/email/settings.ts'; import type { ApiEnv } from '../../src/env.ts'; import { app } from '../../src/index.ts'; -import { emailDestinations, operatorEvents, platformSettings } from '../../src/schema.ts'; +import { emailDestinations, operatorEvents, platformSettings, projects } from '../../src/schema.ts'; import { clearTables, createOperatorToken, @@ -86,6 +88,126 @@ async function events() { return env.db.select().from(operatorEvents); } +describe('operator email outcome logs', () => { + test('paginates retained receipt and recipient outcomes, including after project deletion', async () => { + const owner = await createTestUser(env.db, 'logs-owner'); + const project = await createTestProject(env.db, owner.id, 'logs-project'); + const other = await createTestProject(env.db, owner.id, 'other-logs'); + const createdAt = '2026-09-19T01:02:03Z'; + for (const [id, projectId] of [ + ['action-a', project.id], + ['action-other', other.id], + ] as const) { + await env.db.insert(emailActions).values({ + id, + project_id: projectId, + sender_domain: 'mail.example.com', + kind: 'direct', + idempotency_key: 'private-request-key', + payload_digest: 'd'.repeat(64), + transport: 'binding', + policy_version: 3, + created_at: createdAt, + }); + } + await env.db.insert(emailActionRecipients).values([ + { + id: 'recipient-a', + action_id: 'action-a', + project_id: project.id, + recipient: 'one@example.com', + state: 'provider_accepted', + provider_reference: 'provider-1', + }, + { + id: 'recipient-b', + action_id: 'action-a', + project_id: project.id, + recipient: 'two@example.com', + state: 'failed', + error_code: 'RATE_LIMIT', + }, + { + id: 'recipient-other', + action_id: 'action-other', + project_id: other.id, + recipient: 'other@example.com', + state: 'reserved', + }, + ]); + await env.db.insert(emailReceipts).values({ + id: 'receipt-a', + project_id: project.id, + status: 'handler_completed', + created_at: createdAt, + }); + const page1 = await req(`/email/projects/${project.slug}/logs?limit=2`); + expect(page1.status).toBe(200); + const first = (await page1.json()) as { + projectId: string; + logs: Array>; + }; + expect(first.projectId).toBe(project.id); + expect(first.logs).toHaveLength(2); + const second = (await ( + await req(`/email/projects/${project.id}/logs?limit=2&page=2`) + ).json()) as { logs: Array> }; + expect(second.logs).toHaveLength(1); + const all = [...first.logs, ...second.logs]; + expect(all).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + operationId: 'action-a', + recipient: 'one@example.com', + status: 'provider_accepted', + providerReference: 'provider-1', + policyVersion: 3, + timestamp: Date.parse(createdAt), + }), + expect.objectContaining({ + operationId: 'action-a', + recipient: 'two@example.com', + status: 'failed', + errorCode: 'RATE_LIMIT', + }), + expect.objectContaining({ + operationId: 'receipt-a', + receiptId: 'receipt-a', + direction: 'received', + recipient: null, + }), + ]), + ); + for (const log of all) { + expect(Object.keys(log).sort()).toEqual([ + 'direction', + 'errorCode', + 'operationId', + 'policyVersion', + 'providerReference', + 'receiptId', + 'recipient', + 'status', + 'timestamp', + 'transport', + ]); + } + await env.db.delete(projects).where(eq(projects.id, project.id)); + expect(await (await req(`/email/projects/${project.id}/logs?limit=2`)).json()).toMatchObject( + first, + ); + expect(await events()).toHaveLength(0); + }); + + test('requires operator authentication and bounds outcome log pages', async () => { + for (const query of ['limit=101', 'page=0', 'page=1000001']) { + expect((await req(`/email/projects/retained-project/logs?${query}`)).status).toBe(400); + } + token = 'invalid'; + expect((await req('/email/projects/retained-project/logs')).status).toBe(401); + }); +}); + describe('operator email recipient policy', () => { test('defaults to verified-only and repairs a missing mirror on read', async () => { const response = await req('/email/policy'); diff --git a/platform/packages/api/test/integration/platform-access-protection.test.ts b/platform/packages/api/test/integration/platform-access-protection.test.ts index ef6784442..54fce3669 100644 --- a/platform/packages/api/test/integration/platform-access-protection.test.ts +++ b/platform/packages/api/test/integration/platform-access-protection.test.ts @@ -15,6 +15,7 @@ import { hmacSignState } from '../../src/auth/hmac.ts'; import { signJwt } from '../../src/auth/jwt.ts'; import { createCodeChallenge } from '../../src/auth/pkce.ts'; import { createHumanSession } from '../../src/auth/sessions.ts'; +import { emailReceipts } from '../../src/email/admission-schema.ts'; import { createGitHubWebhookIngressProof } from '../../src/github/webhook-ingress-auth.ts'; import { app } from '../../src/index.ts'; import { platformAuthSettings, users } from '../../src/schema.ts'; @@ -148,6 +149,84 @@ async function githubSignature(body: string): Promise { } describe('Access-protected platform requests', () => { + it('admits the installer email probe only with both service Access and installation proof', async () => { + const call = (access?: string, probe = 'probe-fixture') => + app.fetch( + new Request(`${origin}/internal/platform/email-bootstrap`, { + method: 'POST', + headers: { + ...(access ? { 'Cf-Access-Jwt-Assertion': access } : {}), + 'X-Void-Platform-Probe': probe, + }, + }), + { + ...env, + PLATFORM_INSTALLATION_ID: 'installation', + PLATFORM_HEALTH_PROBE_TOKEN: 'probe-fixture', + }, + ); + const service = await assertion({ service: true }); + const response = await call(service); + expect(response.status).toBe(503); + expect(await response.json()).toMatchObject({ state: 'unconfigured' }); + expect((await call()).status).toBe(403); + expect((await call(service, 'wrong')).status).toBe(403); + }); + + it('keeps internal email HMAC authentication usable behind Access without exempting unrelated routes', async () => { + const project = await createTestProject(env.db, user.id, 'email-access'); + const receipt = { projectId: project.id, receiptId: 'a'.repeat(64), status: 'received' }; + await env.db + .insert(emailReceipts) + .values({ id: receipt.receiptId, project_id: project.id, status: 'received' }); + const proof = await hmacSignState(JSON.stringify(receipt), env.JWT_SECRET); + const accepted = await request( + '/internal/email/actions/receipts', + undefined, + undefined, + receipt, + { 'x-void-internal': proof }, + ); + expect(accepted.status).toBe(200); + const refused = await request( + '/internal/email/actions/receipts', + undefined, + undefined, + receipt, + { 'x-void-internal': 'invalid' }, + ); + expect(refused.status).toBe(403); + expect(await refused.json()).toEqual({ error: 'invalid internal auth' }); + for (const operation of ['probe', 'resolve'] as const) { + const body = { + accountId: 'account', + zoneId: 'zone', + ingressName: 'ingress', + to: 'x@example.com', + secret: 'secret', + }; + const payload = + operation === 'probe' + ? 'email-probe-v1\naccount\nzone\ningress' + : 'email-ingress-v1\naccount\nzone\ningress\nx@example.com'; + const response = await request( + `/internal/email/${operation}-ingress`, + undefined, + undefined, + body, + { 'x-void-internal': await hmacSignState(payload, env.JWT_SECRET) }, + ); + expect(response.status).toBe(404); + } + expect( + ( + await request('/internal/email/actions/unrecognized', undefined, undefined, receipt, { + 'x-void-internal': proof, + }) + ).status, + ).toBe(403); + }); + it('keeps existing signup controls authoritative after authentication migration without removing the gate', async () => { const access = await assertion(); const elevation = await request('/operator/v1/session', access, humanToken, {}); diff --git a/platform/packages/api/test/integration/platform-email-bootstrap.test.ts b/platform/packages/api/test/integration/platform-email-bootstrap.test.ts new file mode 100644 index 000000000..8e481456a --- /dev/null +++ b/platform/packages/api/test/integration/platform-email-bootstrap.test.ts @@ -0,0 +1,191 @@ +import { PLATFORM_DISABLED_KEY } from '@void/platform'; +import { eq } from 'drizzle-orm'; +import { + afterAll, + afterEach, + beforeAll, + beforeEach, + describe, + expect, + it, + vi, +} from 'vite-plus/test'; +import { emailDomainRoutes, emailOperations } from '../../src/email/connection-schema.ts'; +import * as emailConnections from '../../src/email/connection-service.ts'; +import type { ApiEnv } from '../../src/env.ts'; +import { app } from '../../src/index.ts'; +import { callsByTag, stubCustomerCf } from './email-domain-cf-stub.ts'; +import { clearTables, setupEnv, teardownEnv, type TestEnv } from './helpers.ts'; + +let env: TestEnv; + +beforeAll(async () => { + env = await setupEnv(); +}); + +afterAll(async () => { + await teardownEnv(); +}); + +beforeEach(async () => { + await clearTables(env.db); + await env.ROUTING.put(PLATFORM_DISABLED_KEY, 'disabled'); +}); + +afterEach(async () => { + await env.ROUTING.delete(PLATFORM_DISABLED_KEY); + vi.restoreAllMocks(); + vi.unstubAllGlobals(); +}); + +function bindings(): ApiEnv['Bindings'] { + return { + ...env, + EMAIL_GATEWAY_ORIGIN: 'https://email-gateway.example.test', + EMAIL_SENDER_DOMAIN: 'mail.example.com', + EMAIL_SHARED_ACCOUNT_ID: env.CF_ACCOUNT_ID, + EMAIL_SHARED_ZONE_ID: 'platform-mail-zone', + EMAIL_SHARED_INGRESS_NAME: 'void-email-gateway', + PLATFORM_CAPABILITIES: JSON.stringify({ + ai: true, + customDomains: false, + email: true, + githubActions: false, + githubOAuth: true, + googleOAuth: false, + managedBuilds: false, + sandbox: false, + }), + PLATFORM_HEALTH_PROBE_TOKEN: 'probe-token', + PLATFORM_INSTALLATION_ID: 'installation-id', + PLATFORM_TRAFFIC_STATE: 'staging', + } as unknown as ApiEnv['Bindings']; +} + +function request(token = 'probe-token') { + return new Request('http://localhost/internal/platform/email-bootstrap', { + method: 'POST', + headers: { 'X-Void-Platform-Probe': token }, + }); +} + +describe('POST /internal/platform/email-bootstrap', () => { + it('retains the durable operation ID if execution fails after setup was recorded', async () => { + stubCustomerCf({ + zones: { + 'mail.example.com': { + id: 'platform-mail-zone', + name: 'mail.example.com', + accountId: env.CF_ACCOUNT_ID, + }, + }, + }); + vi.spyOn(emailConnections, 'runEmailOperation').mockRejectedValueOnce( + new Error('database unavailable'), + ); + const response = await app.fetch(request(), bindings()); + expect(response.status).toBe(503); + const [operation] = await env.db.select().from(emailOperations); + expect(operation).toBeDefined(); + expect(await response.json()).toMatchObject({ state: 'failed', operationId: operation!.id }); + }); + + it('completes the durable shared route before the installer opens traffic', async () => { + const cloudflare = stubCustomerCf({ + zones: { + 'mail.example.com': { + id: 'platform-mail-zone', + name: 'mail.example.com', + accountId: env.CF_ACCOUNT_ID, + }, + }, + mx: { 'mail.example.com': ['route1.mx.cloudflare.net'] }, + }); + + const response = await app.fetch(request(), bindings()); + + expect(response.status).toBe(200); + expect(await response.json()).toEqual({ + version: 1, + state: 'ready', + operationId: expect.any(String), + }); + expect(callsByTag(cloudflare.calls, 'catchAll')).toHaveLength(1); + const operation = (await env.db.select().from(emailOperations))[0]; + const route = ( + await env.db + .select() + .from(emailDomainRoutes) + .where(eq(emailDomainRoutes.id, operation!.route_id!)) + )[0]; + expect(operation?.status).toBe('completed'); + expect(route).toMatchObject({ + addressing: 'shared', + desired_state: 'active', + inbound_status: 'ready', + }); + }); + + it('does not let an invalid probe token bypass the lifecycle gate', async () => { + const response = await app.fetch(request('wrong-token'), bindings()); + expect(response.status).toBe(503); + expect(await response.json()).toEqual({ error: 'Platform disabled' }); + }); + + it('fails readiness when the durable setup operation is blocked', async () => { + stubCustomerCf({ + zones: { + 'mail.example.com': { + id: 'platform-mail-zone', + name: 'mail.example.com', + accountId: env.CF_ACCOUNT_ID, + }, + }, + mx: { 'mail.example.com': ['route1.mx.cloudflare.net'] }, + failOn: { catchAll: { message: 'permission denied', status: 403 } }, + }); + + const response = await app.fetch(request(), bindings()); + expect(response.status).toBe(503); + expect(await response.json()).toMatchObject({ + version: 1, + state: 'incomplete', + operationStatus: 'blocked', + }); + }); + + it('resumes the same blocked shared operation after configuration is corrected', async () => { + const config: NonNullable[0]> = { + zones: { + 'mail.example.com': { + id: 'platform-mail-zone', + name: 'mail.example.com', + accountId: env.CF_ACCOUNT_ID, + }, + }, + mx: {}, + }; + const cloudflare = stubCustomerCf(config); + + const blocked = await app.fetch(request(), bindings()); + expect(blocked.status).toBe(503); + const blockedBody = (await blocked.json()) as Record; + expect(blockedBody).toMatchObject({ + version: 1, + state: 'incomplete', + operationStatus: 'blocked', + currentStep: 'inbound_probe', + }); + + config.mx!['mail.example.com'] = ['route1.mx.cloudflare.net']; + const resumed = await app.fetch(request(), bindings()); + expect(resumed.status).toBe(200); + expect(await resumed.json()).toEqual({ + version: 1, + state: 'ready', + operationId: blockedBody.operationId, + }); + expect(callsByTag(cloudflare.calls, 'catchAll')).toHaveLength(1); + expect(await env.db.select().from(emailOperations)).toHaveLength(1); + }); +}); diff --git a/platform/packages/api/test/unit/email-actions-request.test.ts b/platform/packages/api/test/unit/email-actions-request.test.ts new file mode 100644 index 000000000..253a4d525 --- /dev/null +++ b/platform/packages/api/test/unit/email-actions-request.test.ts @@ -0,0 +1,31 @@ +import { describe, expect, it, vi } from 'vite-plus/test'; +import emailActions from '../../src/routes/internal-email-actions.ts'; + +describe('internal email action request bounds', () => { + it('times out a stalled body without awaiting its cancellation', async () => { + vi.useFakeTimers(); + try { + const cancel = vi.fn(() => new Promise(() => {})); + const body = new ReadableStream({ + pull() { + return new Promise(() => {}); + }, + cancel, + }); + const request = new Request('https://api/internal/email/actions/admit', { + method: 'POST', + headers: { 'x-void-internal': 'present' }, + body, + duplex: 'half', + } as RequestInit); + const result = emailActions.request(request); + await vi.advanceTimersByTimeAsync(5_001); + const response = await result; + expect(response.status).toBe(408); + expect(await response.json()).toEqual({ error: 'action request timed out' }); + expect(cancel).toHaveBeenCalledOnce(); + } finally { + vi.useRealTimers(); + } + }); +}); diff --git a/platform/packages/api/test/unit/email-cf-customer.test.ts b/platform/packages/api/test/unit/email-cf-customer.test.ts index 540997971..6941c3b7b 100644 --- a/platform/packages/api/test/unit/email-cf-customer.test.ts +++ b/platform/packages/api/test/unit/email-cf-customer.test.ts @@ -401,27 +401,4 @@ describe('cf-customer client', () => { await expect(client.deleteRelayScript(ACCOUNT, RELAY)).rejects.toThrow('boom'); }); }); - - describe('sendRaw', () => { - it('POSTs { from, recipients, mime_message } to the account send_raw endpoint', async () => { - fetchMock.mockResolvedValueOnce(cfSuccess({ message_id: 'msg_1' })); - const client = createCfCustomerClient(CREDENTIAL); - - const result = await client.sendRaw(ACCOUNT, { - from: 'noreply@acme.com', - recipients: ['user@example.org'], - mime_message: 'MIME-DUMMY', - }); - - const { url, init } = lastCall(fetchMock); - expect(url).toBe(`${CF_CUSTOMER_API_BASE}/accounts/${ACCOUNT}/email/sending/send_raw`); - expect(init.method).toBe('POST'); - expect(JSON.parse(init.body as string)).toEqual({ - from: 'noreply@acme.com', - recipients: ['user@example.org'], - mime_message: 'MIME-DUMMY', - }); - expect(result).toEqual({ message_id: 'msg_1' }); - }); - }); }); diff --git a/platform/packages/api/test/unit/email-relay-worker.test.ts b/platform/packages/api/test/unit/email-relay-worker.test.ts index 26899fec5..8259868b4 100644 --- a/platform/packages/api/test/unit/email-relay-worker.test.ts +++ b/platform/packages/api/test/unit/email-relay-worker.test.ts @@ -125,7 +125,11 @@ describe('RELAY_SOURCE', () => { }); it('POSTs the raw MIME to the gateway through a FixedLengthStream with the zone identity', async () => { - const fetchMock = vi.fn().mockResolvedValueOnce(new Response('ok', { status: 200 })); + let uploaded = new Uint8Array(); + const fetchMock = vi.fn(async (_url: string, init: RequestInit) => { + uploaded = new Uint8Array(await new Response(init.body).arrayBuffer()); + return new Response('ok', { status: 200 }); + }); vi.stubGlobal('fetch', fetchMock); const { env, message, ctx } = relayContext(); @@ -154,9 +158,9 @@ describe('RELAY_SOURCE', () => { const body = init.body as ReadableStream; expect(body).toBeInstanceOf(ReadableStream); expect(body).not.toBe(message.raw); - const drained = await new Response(body).arrayBuffer(); - expect(drained.byteLength).toBe(message.rawSize); - expect(new TextDecoder().decode(drained)).toBe(MIME_BODY); + expect(uploaded.byteLength).toBe(message.rawSize); + expect(new TextDecoder().decode(uploaded)).toBe(MIME_BODY); + expect(init.signal?.aborted).toBe(true); // The pump and the POST both ride waitUntil. expect(ctx.waitUntil).toHaveBeenCalledTimes(2); expect(message.setReject).not.toHaveBeenCalled(); @@ -216,6 +220,35 @@ describe('RELAY_SOURCE', () => { expect(message.setReject).not.toHaveBeenCalled(); }); + it('aborts both a stalled gateway fetch and MIME pipe at the 60-second deadline', async () => { + vi.useFakeTimers(); + try { + const requestSignals: Array = []; + const fetchMock = vi.fn((_url: string, init: RequestInit) => { + requestSignals.push(init.signal as AbortSignal); + return new Promise(() => {}); + }); + vi.stubGlobal('fetch', fetchMock); + const { env, message, ctx } = relayContext(); + const cancel = vi.fn(); + message.rawSize = 1; + message.raw = new ReadableStream({ cancel }); + + const pending = loadRelayWorker().email(message, env, ctx); + const outcome = expect(pending).rejects.toThrow('temporarily unavailable'); + await vi.advanceTimersByTimeAsync(60_000); + await outcome; + + expect(requestSignals[0]?.aborted).toBe(true); + await Promise.all(ctx.waitUntil.mock.calls.map(([promise]) => promise as Promise)); + expect(cancel).toHaveBeenCalledOnce(); + expect(ctx.waitUntil).toHaveBeenCalledTimes(2); + expect(message.setReject).not.toHaveBeenCalled(); + } finally { + vi.useRealTimers(); + } + }); + it('proves the deployed secret with a challenge bound to the zone and generation', async () => { const { env } = relayContext(); const challenge = 'a'.repeat(64); diff --git a/platform/packages/email-gateway/src/index.ts b/platform/packages/email-gateway/src/index.ts index e24099647..6493479ff 100644 --- a/platform/packages/email-gateway/src/index.ts +++ b/platform/packages/email-gateway/src/index.ts @@ -24,6 +24,16 @@ const MAX_ENVELOPE_HEADER = 320; const MAX_CONCURRENT_DELIVERIES = 2; let activeDeliveries = 0; +class MimeHeaderError extends Error { + constructor( + message: string, + readonly status: 400 | 413, + ) { + super(message); + this.name = 'MimeHeaderError'; + } +} + async function withDeliverySlot(run: () => Promise): Promise { if (activeDeliveries >= MAX_CONCURRENT_DELIVERIES) { throw new Error('email gateway busy'); @@ -53,6 +63,8 @@ async function sign(value: string, secret: string): Promise { } type Route = { + routeId: string; + routeGeneration: number; connectionId: string; projectId: string; workerName: string; @@ -75,17 +87,45 @@ async function resolveIngress( native?: true; }, ): Promise { + const deadline = Date.now() + 5_000; + const controller = new AbortController(); + const beforeDeadline = async (run: () => Promise): Promise => { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + controller.abort(); + throw new Error('ingress resolution timeout'); + } + let timer: ReturnType | undefined; + try { + return await Promise.race([ + run(), + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('ingress resolution timeout')); + }, remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }; const proof = await sign( `email-ingress-v1\n${input.accountId}\n${input.zoneId}\n${input.ingressName}\n${input.to.toLowerCase()}`, env.JWT_SECRET, ); - const response = await env.API.fetch('https://api/internal/email/resolve-ingress', { - method: 'POST', - headers: { 'content-type': 'application/json', 'x-void-internal': proof }, - body: JSON.stringify(input), - signal: AbortSignal.timeout(5_000), - }); + const response = await beforeDeadline(() => + env.API.fetch('https://api/internal/email/resolve-ingress', { + method: 'POST', + headers: { 'content-type': 'application/json', 'x-void-internal': proof }, + body: JSON.stringify(input), + signal: controller.signal, + }), + ); if (!response.ok) { + void response.body?.cancel().catch(() => {}); if (response.status >= 500 || response.status === 429) { throw new Error('email routing unavailable'); } @@ -93,6 +133,7 @@ async function resolveIngress( } const contentLength = Number(response.headers.get('content-length')); if (Number.isFinite(contentLength) && contentLength > 4096) { + void response.body?.cancel().catch(() => {}); throw new Error('invalid email routing response'); } const reader = response.body?.getReader(); @@ -101,24 +142,9 @@ async function resolveIngress( } const chunks: Array = []; let total = 0; - const deadline = Date.now() + 5_000; try { while (true) { - const remaining = deadline - Date.now(); - if (remaining <= 0) { - throw new Error('email routing response timeout'); - } - let timer: ReturnType | undefined; - const chunk = await Promise.race([ - reader.read(), - new Promise((_, reject) => { - timer = setTimeout(() => reject(new Error('ingress resolution timeout')), remaining); - }), - ]).finally(() => { - if (timer !== undefined) { - clearTimeout(timer); - } - }); + const chunk = await beforeDeadline(() => reader.read()); if (chunk.done) { break; } @@ -129,8 +155,12 @@ async function resolveIngress( chunks.push(chunk.value); } } finally { - await reader.cancel().catch(() => {}); - reader.releaseLock(); + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } } const bytes = new Uint8Array(total); let offset = 0; @@ -150,6 +180,9 @@ async function resolveIngress( } const value = route as Partial; if ( + typeof value.routeId !== 'string' || + !Number.isSafeInteger(value.routeGeneration) || + value.routeGeneration! < 1 || typeof value.projectId !== 'string' || typeof value.connectionId !== 'string' || typeof value.workerName !== 'string' || @@ -205,10 +238,14 @@ async function readMime( } return result; } catch (error) { - await reader.cancel().catch(() => {}); + void reader.cancel().catch(() => {}); throw error; } finally { - reader.releaseLock(); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } } } @@ -220,8 +257,14 @@ function parseHeaders(raw: Uint8Array): Record { break; } } - if (end < 0 || end > MAX_HEADER_BYTES) { - throw new Error('invalid MIME headers'); + if (end < 0) { + throw new MimeHeaderError( + 'invalid MIME headers', + raw.byteLength > MAX_HEADER_BYTES ? 413 : 400, + ); + } + if (end > MAX_HEADER_BYTES) { + throw new MimeHeaderError('MIME headers too large', 413); } const lines = decoder.decode(raw.subarray(0, end)).split('\r\n'); const headers: Record = Object.create(null); @@ -229,22 +272,22 @@ function parseHeaders(raw: Uint8Array): Record { let physicalLines = 0; for (const line of lines) { if (++physicalLines > MAX_INBOUND_HEADERS) { - throw new Error('too many MIME headers'); + throw new MimeHeaderError('too many MIME headers', 413); } if (/^[ \t]/.test(line)) { if (!current) { - throw new Error('invalid MIME header fold'); + throw new MimeHeaderError('invalid MIME header fold', 400); } headers[current] += ` ${line.trim()}`; continue; } const colon = line.indexOf(':'); if (colon <= 0) { - throw new Error('invalid MIME header'); + throw new MimeHeaderError('invalid MIME header', 400); } const name = line.slice(0, colon).toLowerCase(); if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name)) { - throw new Error('invalid MIME header name'); + throw new MimeHeaderError('invalid MIME header name', 400); } headers[name] = headers[name] ? `${headers[name]}, ${line.slice(colon + 1).trim()}` @@ -304,9 +347,26 @@ async function ingress(request: Request, env: Env, ctx: ExecutionContext): Promi if (!route) { return new Response(null, { status: 403 }); } + let raw: Uint8Array; + try { + raw = await readMime(request.body, declared); + } catch (error) { + console.error( + '[email-gateway] ingress failed:', + error instanceof Error ? error.message.slice(0, 200) : 'unknown', + ); + return new Response(null, { status: 502 }); + } + let headers: Record; + try { + headers = parseHeaders(raw); + } catch (error) { + if (error instanceof MimeHeaderError) { + return new Response(null, { status: error.status }); + } + throw error; + } try { - const raw = await readMime(request.body, declared); - const headers = parseHeaders(raw); const domain = to.slice(to.lastIndexOf('@') + 1).toLowerCase(); if (domain !== route.domain) { return new Response(null, { status: 403 }); @@ -319,11 +379,34 @@ async function ingress(request: Request, env: Env, ctx: ExecutionContext): Promi headers, ...(route.addressing === 'custom' ? { viaDomain: domain } : {}), }; + let stub: Fetcher; + try { + stub = ( + route.limits + ? env.DISPATCH.get(route.workerName, {}, { limits: route.limits }) + : env.DISPATCH.get(route.workerName) + ) as Fetcher; + } catch (error) { + console.error('[email-gateway] tenant dispatch stub unavailable:', error); + return new Response(null, { status: 503 }); + } const receiptId = await sha256(encoder.encode(JSON.stringify([route.connectionId, requestId]))); const payloadDigest = await sha256( encoder.encode(JSON.stringify([from, to, await sha256(raw)])), ); - const identity = { receiptId, projectId: route.projectId, payloadDigest }; + const identity = { + receiptId, + projectId: route.projectId, + payloadDigest, + route: { + routeId: route.routeId, + routeGeneration: route.routeGeneration, + connectionId: route.connectionId, + addressing: route.addressing, + domain: route.domain, + projectSlug: route.slug, + }, + }; let claim; try { claim = await claimRelayedReceipt(env, identity); @@ -343,6 +426,7 @@ async function ingress(request: Request, env: Env, ctx: ExecutionContext): Promi return new Response(null, { status: 503, headers: { 'x-void-email-receipt': receiptId } }); } const result = await routeRelayed(env, ctx, { + stub, projectId: route.projectId, domain, envelope, @@ -380,10 +464,12 @@ async function sha256(bytes: Uint8Array): Promise { async function probe(request: Request, env: Env): Promise { if (request.headers.get('content-encoding')) { + void request.body?.cancel().catch(() => {}); return new Response(null, { status: 400 }); } const declared = request.headers.get('content-length'); if (declared && (!/^\d+$/.test(declared) || Number(declared) > 1024)) { + void request.body?.cancel().catch(() => {}); return new Response(null, { status: 400 }); } const authorization = request.headers.get('authorization') ?? ''; @@ -426,8 +512,12 @@ async function probe(request: Request, env: Env): Promise { } catch { return new Response(null, { status: 400 }); } finally { - await reader.cancel().catch(() => {}); - reader.releaseLock(); + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } } if (size === 0 || (declared && size !== Number(declared))) { return new Response(null, { status: 400 }); @@ -453,16 +543,35 @@ async function probe(request: Request, env: Env): Promise { `email-probe-v1\n${accountId}\n${zoneId}\n${ingressName}`, env.JWT_SECRET, ); + const controller = new AbortController(); + const apiDeadline = Date.now() + 5_000; + let timer: ReturnType | undefined; try { - const response = await env.API.fetch('https://api/internal/email/probe-ingress', { - method: 'POST', - headers: { 'content-type': 'application/json', 'x-void-internal': proof }, - body: JSON.stringify({ accountId, zoneId, ingressName, secret: authorization.slice(7) }), - signal: AbortSignal.timeout(5_000), - }); + const response = await Promise.race([ + env.API.fetch('https://api/internal/email/probe-ingress', { + method: 'POST', + headers: { 'content-type': 'application/json', 'x-void-internal': proof }, + body: JSON.stringify({ accountId, zoneId, ingressName, secret: authorization.slice(7) }), + signal: controller.signal, + }), + new Promise((_, reject) => { + timer = setTimeout( + () => { + controller.abort(); + reject(new Error('email probe timeout')); + }, + Math.max(0, apiDeadline - Date.now()), + ); + }), + ]); + void response.body?.cancel().catch(() => {}); return new Response(null, { status: response.status === 204 ? 204 : 403 }); } catch { return new Response(null, { status: 503 }); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } } } diff --git a/platform/packages/email-gateway/src/tenant-dispatch.ts b/platform/packages/email-gateway/src/tenant-dispatch.ts index f616cd950..284144c78 100644 --- a/platform/packages/email-gateway/src/tenant-dispatch.ts +++ b/platform/packages/email-gateway/src/tenant-dispatch.ts @@ -9,6 +9,8 @@ import { } from '@void/platform/email-protocol'; const MAX_CONCURRENT_PER_PROJECT = 8; +const TENANT_DISPATCH_DEADLINE_MS = 20_000; +const TENANT_RESPONSE_DEADLINE_MS = 15_000; const active = new Map(); export async function dispatchBoundedEmailToTenant( @@ -33,6 +35,9 @@ export async function dispatchBoundedEmailToTenant( throw new Error('email project concurrency exceeded'); } active.set(input.projectId, count + 1); + const deadline = Date.now() + TENANT_DISPATCH_DEADLINE_MS; + const controller = new AbortController(); + let response: Response | undefined; try { const receipt = await signEmailReceipt( { @@ -45,16 +50,35 @@ export async function dispatchBoundedEmailToTenant( }, env.JWT_SECRET, ); - const response = await stub.fetch(`https://worker${EMAIL_RECEIPT_PATH}`, { - method: 'POST', - headers: { - 'content-type': 'application/vnd.void.email-envelope; version=1', - 'x-void-email-receipt': receipt, - 'x-void-email-recipient': input.envelope.to, - }, - body: encodeEmailEnvelope(input.envelope), - signal: AbortSignal.timeout(20_000), - }); + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('email tenant request timeout'); + } + let timer: ReturnType | undefined; + try { + response = await Promise.race([ + stub.fetch(`https://worker${EMAIL_RECEIPT_PATH}`, { + method: 'POST', + headers: { + 'content-type': 'application/vnd.void.email-envelope; version=1', + 'x-void-email-receipt': receipt, + 'x-void-email-recipient': input.envelope.to, + }, + body: encodeEmailEnvelope(input.envelope), + signal: controller.signal, + }), + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('email tenant request timeout')); + }, remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } if ( !response.ok || response.headers.get('content-encoding') || @@ -64,9 +88,15 @@ export async function dispatchBoundedEmailToTenant( ) { throw new Error(`invalid email tenant response (${response.status})`); } - const actions = await readEmailActions(response.body, 15_000); + const responseDeadline = Math.min(TENANT_RESPONSE_DEADLINE_MS, deadline - Date.now()); + if (responseDeadline <= 0) { + throw new Error('email tenant request timeout'); + } + const actions = await readEmailActions(response.body, responseDeadline); return { actions, receiptId }; } finally { + controller.abort(); + void response?.body?.cancel().catch(() => {}); const remaining = (active.get(input.projectId) ?? 1) - 1; if (remaining === 0) { active.delete(input.projectId); diff --git a/platform/packages/email-gateway/test/unit/gateway.test.ts b/platform/packages/email-gateway/test/unit/gateway.test.ts index 000c8f7cd..e04c43b72 100644 --- a/platform/packages/email-gateway/test/unit/gateway.test.ts +++ b/platform/packages/email-gateway/test/unit/gateway.test.ts @@ -20,6 +20,8 @@ const identityHeaders = { 'x-void-email-to': 'support@example.com', }; const route = { + routeId: 'route-1', + routeGeneration: 1, connectionId: 'connection-1', projectId: 'project-1', slug: 'support', @@ -29,15 +31,42 @@ const route = { domain: 'example.com', }; const context = { waitUntil: vi.fn() } as unknown as ExecutionContext; -const env = (apiFetch: (...args: Array) => Promise) => +const env = ( + apiFetch: (...args: Array) => Promise, + dispatchGet: (...args: Array) => Fetcher = () => ({ fetch: vi.fn() }) as never, +) => ({ JWT_SECRET: 'platform-secret', API: { fetch: apiFetch }, EMAIL_SHARED_ACCOUNT_ID: 'account-1', EMAIL_SHARED_ZONE_ID: 'zone-1', EMAIL_SHARED_INGRESS_NAME: 'gateway-1', + DISPATCH: { get: dispatchGet }, }) as never; +function uncooperativeStream(chunk: Uint8Array): ReadableStream { + return new ReadableStream({ + start(controller) { + controller.enqueue(chunk); + }, + cancel() { + return new Promise(() => {}); + }, + }); +} + +async function settlesSoon(promise: Promise): Promise { + return Promise.race([ + promise, + new Promise((_, reject) => { + setTimeout( + () => reject(new Error('operation did not settle after stream cancellation')), + 250, + ); + }), + ]); +} + function request(body: BodyInit, headers: Record = {}) { return new Request('https://gateway.example/email/ingress', { method: 'POST', @@ -86,6 +115,14 @@ describe('dedicated email gateway', () => { const input = JSON.parse(raw); const existing = receipts.get(input.receiptId); if (String(url).endsWith('/receipts/claim')) { + expect(input.route).toEqual({ + routeId: route.routeId, + routeGeneration: route.routeGeneration, + connectionId: route.connectionId, + addressing: route.addressing, + domain: route.domain, + projectSlug: route.slug, + }); if (!existing) { receipts.set(input.receiptId, { digest: input.payloadDigest }); return Response.json({ state: 'claimed' }); @@ -153,6 +190,28 @@ describe('dedicated email gateway', () => { expect(router.routeRelayed).toHaveBeenCalledTimes(1); }); + it('can retry the same request ID after tenant stub resolution fails before claiming', async () => { + const apiFetch = receiptApi(); + const resolvedStub = { fetch: vi.fn() }; + const dispatchGet = vi + .fn() + .mockImplementationOnce(() => { + throw new Error('dispatch unavailable'); + }) + .mockReturnValue(resolvedStub); + const environment = env(apiFetch, dispatchGet); + const raw = new TextEncoder().encode('From: sender@example.net\r\n\r\nbody'); + + expect((await gateway.fetch(request(raw), environment, context)).status).toBe(503); + expect((await gateway.fetch(request(raw), environment, context)).status).toBe(204); + + expect(router.routeRelayed).toHaveBeenCalledTimes(1); + expect(router.routeRelayed.mock.calls[0]?.[2]).toMatchObject({ stub: resolvedStub }); + expect( + apiFetch.mock.calls.filter(([url]) => String(url).endsWith('/receipts/claim')), + ).toHaveLength(1); + }); + it('preserves transient routing failures for both HTTP and native ingress', async () => { const environment = env(async () => new Response(null, { status: 503 })); expect((await gateway.fetch(request(new Uint8Array()), environment, context)).status).toBe(503); @@ -216,6 +275,30 @@ describe('dedicated email gateway', () => { expect(router.routeRelayed).not.toHaveBeenCalled(); }, ); + + it('does not await cancellation of an oversized authority response', async () => { + const environment = env(async () => new Response(uncooperativeStream(new Uint8Array(4097)))); + const response = await settlesSoon( + gateway.fetch(request(new Uint8Array()), environment, context), + ); + expect(response.status).toBe(503); + }); + + it('bounds an authority fetch that ignores abort by the same response deadline', async () => { + vi.useFakeTimers(); + try { + const pending = gateway.fetch( + request(new Uint8Array()), + env(() => new Promise(() => {})), + context, + ); + await vi.advanceTimersByTimeAsync(5_001); + expect((await pending).status).toBe(503); + } finally { + vi.useRealTimers(); + } + }); + it('authenticates ingress before consuming MIME bytes', async () => { const pulled = vi.fn(() => { throw new Error('body must stay unread'); @@ -241,6 +324,18 @@ describe('dedicated email gateway', () => { expect(apiFetch).not.toHaveBeenCalled(); }); + it('does not await cancellation after streamed MIME exceeds its declared length', async () => { + const body = uncooperativeStream(new Uint8Array(2)); + const response = await settlesSoon( + gateway.fetch( + request(body, { 'content-length': '1' }), + env(async () => Response.json(route)), + context, + ), + ); + expect(response.status).toBe(502); + }); + it('requires complete ingress identity', async () => { const apiFetch = vi.fn(); const response = await gateway.fetch( @@ -253,13 +348,21 @@ describe('dedicated email gateway', () => { }); it('counts repeated physical MIME headers before routing to a tenant', async () => { + const apiFetch = vi.fn(async () => Response.json(route)); const raw = new TextEncoder().encode(`${'X-A: value\r\n'.repeat(1025)}\r\nbody`); - const response = await gateway.fetch( - request(raw), - env(async () => Response.json(route)), - context, - ); - expect(response.status).toBe(502); + const response = await gateway.fetch(request(raw), env(apiFetch), context); + expect(response.status).toBe(413); + expect(apiFetch).toHaveBeenCalledTimes(1); + expect(router.routeRelayed).not.toHaveBeenCalled(); + }); + + it('permanently refuses malformed MIME headers before claiming or routing', async () => { + const apiFetch = vi.fn(async () => Response.json(route)); + const raw = new TextEncoder().encode('not-a-header\r\n\r\nbody'); + const response = await gateway.fetch(request(raw), env(apiFetch), context); + + expect(response.status).toBe(400); + expect(apiFetch).toHaveBeenCalledTimes(1); expect(router.routeRelayed).not.toHaveBeenCalled(); }); @@ -347,4 +450,47 @@ describe('dedicated email gateway', () => { ); expect(response.status).toBe(204); }); + + it('bounds a probe API call that ignores abort', async () => { + vi.useFakeTimers(); + try { + const body = JSON.stringify({ + accountId: 'account-1', + zoneId: 'zone-1', + ingressName: 'gateway-1', + }); + let markStarted!: () => void; + const started = new Promise((resolve) => { + markStarted = resolve; + }); + const response = gateway.fetch( + new Request('https://gateway.example/email/probe', { + method: 'POST', + body, + headers: { authorization: 'Bearer staged-secret' }, + }), + env(() => { + markStarted(); + return new Promise(() => {}); + }), + context, + ); + await started; + await vi.advanceTimersByTimeAsync(5_001); + expect((await response).status).toBe(503); + } finally { + vi.useRealTimers(); + } + }); + + it('does not await cancellation of an oversized probe body', async () => { + const probe = new Request('https://gateway.example/email/probe', { + method: 'POST', + body: uncooperativeStream(new Uint8Array(1025)), + headers: { authorization: 'Bearer staged-secret' }, + duplex: 'half', + } as RequestInit); + const response = await settlesSoon(gateway.fetch(probe, env(vi.fn()), context)); + expect(response.status).toBe(400); + }); }); diff --git a/platform/packages/email-gateway/test/unit/tenant-dispatch.test.ts b/platform/packages/email-gateway/test/unit/tenant-dispatch.test.ts new file mode 100644 index 000000000..3cf45df2e --- /dev/null +++ b/platform/packages/email-gateway/test/unit/tenant-dispatch.test.ts @@ -0,0 +1,45 @@ +import { describe, expect, it, vi } from 'vite-plus/test'; +import { dispatchBoundedEmailToTenant } from '../../src/tenant-dispatch.ts'; + +describe('bounded tenant email dispatch', () => { + it('times out a service binding fetch that ignores abort', async () => { + vi.useFakeTimers(); + try { + let signal: AbortSignal | undefined; + let markStarted!: () => void; + const started = new Promise((resolve) => { + markStarted = resolve; + }); + const stub = { + fetch: vi.fn((_url: string, init?: RequestInit) => { + signal = init?.signal ?? undefined; + markStarted(); + return new Promise(() => {}); + }), + }; + const pending = dispatchBoundedEmailToTenant( + stub as never, + { JWT_SECRET: 'secret' }, + { + projectId: 'project-1', + deploymentId: 'deployment-1', + receiptId: 'a'.repeat(64), + envelope: { + from: 'sender@example.com', + to: 'support@example.com', + headers: {}, + raw: new Uint8Array(), + rawSize: 0, + }, + }, + ); + const rejected = expect(pending).rejects.toThrow('email tenant request timeout'); + await started; + await vi.advanceTimersByTimeAsync(20_001); + await rejected; + expect(signal?.aborted).toBe(true); + } finally { + vi.useRealTimers(); + } + }); +}); diff --git a/platform/packages/proxy/README.md b/platform/packages/proxy/README.md index 6c801e72a..9ef69269e 100644 --- a/platform/packages/proxy/README.md +++ b/platform/packages/proxy/README.md @@ -1,6 +1,6 @@ # @voidcloud/proxy -Shared proxy worker for platform-owned capabilities: AI metering, ISR revalidation, remote D1/KV/R2 access, and platform email (outbound sends and the inbound catch-all router). +Shared proxy worker for platform-owned capabilities: AI metering, ISR revalidation, remote D1/KV/R2 access, and platform email submission. The dedicated email gateway uses the shared inbound routing helpers. ## Architecture @@ -8,7 +8,7 @@ Shared proxy worker for platform-owned capabilities: AI metering, ISR revalidati - **ISR revalidation** forwards to the API worker over a service binding. - **Remote bindings** resolve the active deployment on every operation, then try its user worker via `DISPATCH` and `/__void/*`. Read operations can fall back to Cloudflare REST APIs when native dispatch is unavailable. - **Resource resolution** happens through internal API endpoints, not direct DB reads inside the proxy. -- **Email** is centralized here: the proxy holds the account-level `send_email` binding and is the catch-all inbound router for the platform mail zone. User workers hold no mail binding, so per-project allowlists and quotas cannot be bypassed. +- **Email** submissions use the API’s PostgreSQL admission ledger. Shared senders use the platform `send_email` binding; custom senders use scoped credential leases. Inbound mail enters through the dedicated email gateway, which resolves exact-domain authority through the API before dispatch. Tenant workers hold neither mail bindings nor customer credentials. ```text Deployed user worker Proxy Downstream @@ -16,11 +16,8 @@ Deployed user worker Proxy Downstream │ ai.run() │────────▶│ /ai/* │─────▶│ AI Gateway / AI │ │ revalidate() │────────▶│ /revalidate │─────▶│ void-api │ │ remote D1/KV/R2 │────────▶│ /d1/* /kv/* /r2/* │─────▶│ user worker / CF │ -│ sendEmail() │────────▶│ /email/send │─────▶│ SEND_EMAIL (CF) │ +│ sendEmail() │────────▶│ /email/send │─────▶│ CF email service │ └────────────────────┘ └────────────────────┘ └────────────────────┘ - ▲ ▲ - │ email(envelope) RPC │ email() handler - └──────────────────────────────┴───── CF Email Routing (inbound) ``` ## Authentication @@ -79,86 +76,29 @@ The proxy forwards the request to `API.fetch("https://api/internal/revalidate/:p ### Email -| Endpoint | Body | Notes | -| --------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `POST /email/send` | `{ projectId, aiToken, from, recipients, mimeBase64, byteSize, requestId, fromDomain }` | Outbound send. Gate chain below; calls `SEND_EMAIL` once per allowed recipient and returns `SendEmailResult`-shaped JSON. | -| `POST /email/internal/send` | `{ platformToken, platformTimestamp, from, to, mimeBase64 }` | Platform-internal verification mail from the api worker. `from` is locked to `noreply@$EMAIL_SENDER_DOMAIN`. Not reachable from a user worker. | - -Outbound gate chain, in order — the first failure short-circuits, and nothing before the counters burns quota: +`POST /email/send` accepts authenticated project identity, envelope sender and recipients, MIME bytes, a request ID, and an optional idempotency key. The proxy validates the message and asks the internal API to reserve each permitted recipient. PostgreSQL checks project ownership, consent, installation policy, suspension, domain readiness, and quota atomically. ```text -body shape ▸ `from` length ▸ EMAIL_SENDER_DOMAIN set ▸ SEND_EMAIL bound ▸ recipients ▸ MIME size - ▸ email-slug: (pins `from` local-part to the project's slug) - ▸ strict `from` regex ([+tag]@$EMAIL_SENDER_DOMAIN, no CR/LF or display names) - ▸ MIME `From:` addr-spec (exactly one From header, one mailbox, equal to `from`; the - display name is not inspected — CF's own From-vs-envelope - check is undocumented, so the proxy does not rely on it. - The header scan keeps byte offsets, never a view per line, - so a fold of millions of continuations costs its bytes and - nothing per line; the value itself has no length bound - beyond MIME size, matching the framework's unbounded - display name) - ▸ routing.suspended (platform-wide; the marker dispatch answers with 429) - ▸ email-suspended: (email-only kill-switch) - ▸ email-allowlist: (per-project verified destinations) - ▸ email-burst:: ▸ email-sent:: - ▸ SEND_EMAIL.send() per recipient +Tenant send → proxy validation → API admission → per-recipient attempt start + → platform binding (shared sender) or scoped send_raw (custom sender) + → record accepted, failed, or unknown outcome + +Cloudflare Email Routing → gateway (native or authenticated zone relay) + → API exact-domain resolution → receipt claim → active tenant dispatch + → validate handler actions → same API admission and outcome ledger ``` -`requestId` is a caller-supplied log correlation id and is never validated: it is truncated to 128 -characters and stripped of control characters once at intake (a missing or non-string id logs as -`unknown`), so the per-delivery `[email-log]` line can neither be forged with a newline nor carry a -tenant-sized value. - -`POST /email/internal/send` authenticates with an HMAC of -`..` under `JWT_SECRET` (sentinel auth plus -content binding, 5-minute skew window). Only the proxy and api hold `JWT_SECRET`. The reference -signer is `packages/api/src/email/send-verification.ts`; changing the format needs a coordinated -proxy + api deploy. The three hashed fields are size-bounded BEFORE the hash — `mimeBase64` to -the base64 form of the MIME cap, `from` and `to` to the same 320 characters `/email/send` applies -— because the hash runs ahead of the token check, so an unauthenticated caller would otherwise -choose how much is copied and hashed. The token itself is refused unless it is exactly 43 -characters — the only length an HMAC-SHA256 tag has as unpadded base64url — BEFORE it is decoded, -because the decode copies it several times over (a 4 MB token exhausts the 128 MB isolate). Every -pre-auth refusal is the same opaque `403 invalid platform token`; `platform token required` is -reserved for an absent token or timestamp. - -The worker also exports `email()` as the catch-all CF Email Routing handler for the mail zone -(`packages/proxy/src/email-router.ts`). Inbound parses `+` from the recipient, reads the -project's routing blob, and dispatches into the user worker over an `email(envelope)` RPC call — -`ForwardableEmailMessage` is not RPC-serializable, so the router sends an envelope and enacts the -returned `EmailAction[]` on the real message. Inbound honors `routing.suspended` and -`email-suspended:` **before** dispatch, and passes the project's `routing.limits` into -`DISPATCH.get` exactly as the HTTP router does. Forward/reply actions returned by a handler run -through the same per-project allowlist and burst/monthly quotas as `/email/send` — CF Email Routing -destinations are account-wide, so per-project gating is the platform's security boundary. - -The returned action list is re-validated at the proxy no matter what produced it — a -Workers-for-Platforms tenant can ship any `WorkerEntrypoint`, so the framework's own guardrails are -not the boundary. Before any outbound gate: at most 100 actions; every address at most 320 chars; a -forward's header bag a plain object of at most 32 string headers of at most 1024 chars each (an -invalid bag drops the whole list); a reply's `raw` a `Uint8Array` of at most 10 MiB, with at most -20 MiB of replies across one delivery (an overrunning reply is dropped and not charged, so a later -one that fits still goes); and a reply's MIME `From:` pinned to its envelope sender. Reject reasons -are truncated to 1,000 chars **before** control chars are stripped, so a control-heavy reason never -costs a full-length pass. A value that is logged because it failed validation — a non-object -action, an unknown action `type`, an address that is not a string — is never coerced with -`String()`: a string is truncated then stripped, and anything else (a typed array or Array, which -`String()` would join element by element; a BigInt, whose decimal conversion is superlinear) is -logged by kind only. - -Inbound requests are **not** metered today; only the `email-recv::` delivery counter is -written. +An idempotency key binds an action to its payload digest. Replays return recorded recipient states; a conflicting payload fails. An uncertain provider outcome is never automatically retried. Unstarted reservations can be cancelled and refunded; started attempts retain quota. Provider submissions wait at most 30 seconds within a 60-second batch budget. + +`POST /email/internal/send` sends platform verification mail. It authenticates a timestamped, content-bound HMAC under `JWT_SECRET` and pins the sender to `noreply@$EMAIL_SENDER_DOMAIN`. Field sizes are bounded before hashing; the API signer is `src/email/send-verification.ts` in the API package. + +The gateway resolves the active project worker and dispatch limits from the API. Tenant requests and framed responses have an absolute deadline, and a durable receipt prevents replay after dispatch may have started. Native ingress can forward or reply using the original Cloudflare message. Relayed replies select delivery by sender domain: the shared binding for platform addresses, or scoped `send_raw` for custom addresses. Relayed forwarding returns `UNSUPPORTED_ACTION` without consuming quota because REST resending does not preserve native forwarding semantics. + +All handler actions are validated again at the platform boundary. MIME is capped at 5 MiB per message, replies at 8 MiB in aggregate, and action lists at 100 entries. The shared protocol bounds encoded response size, recipient counts, and headers. See `packages/platform/src/email-protocol.ts` and `src/email-router.ts` for the wire limits. PostgreSQL records inbound receipts and outbound recipient outcomes; KV hints cannot authorize delivery. #### Sender domain -The mail zone is configuration, not a constant: `EMAIL_SENDER_DOMAIN` (`mail.void.cloud` in -production, `mail.staging.void.cloud` in staging) is declared as a `vars` entry in **every** -`wrangler.jsonc` scope, since wrangler does not inherit `vars` — or `send_email` — into a named env -and deploys run `--env production`. Deployed user workers receive the same value as the -`__VOID_EMAIL_DOMAIN` plain-text binding so the framework builds its default `from` against the same -zone. There is no baked-in fallback: if the var is missing, both send endpoints fail closed with a -502 rather than sending on the production zone from a staging worker. +`EMAIL_SENDER_DOMAIN` configures the shared mail domain for each installation. Deployed apps receive `__VOID_EMAIL_DOMAIN` and `__VOID_PROJECT_SLUG` to construct their default `+noreply@` sender. Missing configuration fails closed. Email-enabled installations provision the shared binding and verify gateway ingress before opening traffic. ### Managed Sandbox @@ -182,7 +122,7 @@ src/ kv.ts # KV remote access r2.ts # R2 remote access email.ts # Outbound /email/send + platform-internal /email/internal/send - email-router.ts # Inbound CF Email Routing catch-all -> user worker email() RPC + email-router.ts # Shared native/relayed inbound routing and handler actions types.ts # Env and JWT types test/unit/ proxy.test.ts diff --git a/platform/packages/proxy/src/email-admission.ts b/platform/packages/proxy/src/email-admission.ts index 441938c00..67d7242c1 100644 --- a/platform/packages/proxy/src/email-admission.ts +++ b/platform/packages/proxy/src/email-admission.ts @@ -22,6 +22,8 @@ export type Admission = { const encoder = new TextEncoder(); const decoder = new TextDecoder(); +const ADMISSION_DEADLINE_MS = 5_000; +const MAX_ADMISSION_RESPONSE_BYTES = 65_536; async function sign(data: string, secret: string): Promise { const key = await crypto.subtle.importKey( @@ -43,17 +45,47 @@ async function call( path: string, body: unknown, ): Promise { + const controller = new AbortController(); + const deadline = Date.now() + ADMISSION_DEADLINE_MS; + const beforeDeadline = async (run: () => Promise): Promise => { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + controller.abort(); + throw new Error('EMAIL_ADMISSION_TIMEOUT'); + } + const promise = run(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('EMAIL_ADMISSION_TIMEOUT')); + }, remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }; const raw = JSON.stringify(body); - const response = await env.API.fetch(`https://api/internal/email/actions${path}`, { - method: 'POST', - headers: { - 'content-type': 'application/json', - 'x-void-internal': await sign(raw, env.JWT_SECRET), - }, - body: raw, - signal: AbortSignal.timeout(5_000), - }); + const proof = await sign(raw, env.JWT_SECRET); + const response = await beforeDeadline(() => + env.API.fetch(`https://api/internal/email/actions${path}`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + 'x-void-internal': proof, + }, + body: raw, + signal: controller.signal, + }), + ); if (!response.ok) { + void response.body?.cancel().catch(() => {}); if (response.status === 409) { throw new Error('IDEMPOTENCY_CONFLICT'); } @@ -63,26 +95,11 @@ async function call( if (!reader) { throw new Error('EMAIL_ADMISSION_EMPTY_RESPONSE'); } - const bytes = new Uint8Array(65_536); + const bytes = new Uint8Array(MAX_ADMISSION_RESPONSE_BYTES); let size = 0; - const deadline = Date.now() + 5_000; try { for (;;) { - const remaining = deadline - Date.now(); - if (remaining <= 0) { - throw new Error('EMAIL_ADMISSION_TIMEOUT'); - } - let timer: ReturnType | undefined; - const chunk = await Promise.race([ - reader.read(), - new Promise((_, reject) => { - timer = setTimeout(() => reject(new Error('EMAIL_ADMISSION_TIMEOUT')), remaining); - }), - ]).finally(() => { - if (timer !== undefined) { - clearTimeout(timer); - } - }); + const chunk = await beforeDeadline(() => reader.read()); if (chunk.done) { break; } @@ -95,7 +112,11 @@ async function call( return JSON.parse(decoder.decode(bytes.subarray(0, size))) as T; } finally { void reader.cancel().catch(() => {}); - reader.releaseLock(); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } } } @@ -103,6 +124,16 @@ export type RelayedReceiptIdentity = { receiptId: string; projectId: string; payloadDigest: string; + route?: ReceiptRouteFence; +}; + +export type ReceiptRouteFence = { + routeId: string; + routeGeneration: number; + connectionId: string; + addressing: 'shared' | 'custom'; + domain: string; + projectSlug: string; }; export function claimRelayedReceipt( @@ -117,69 +148,185 @@ export function completeRelayedReceipt( identity: RelayedReceiptIdentity, reject: boolean, ): Promise<{ ok: true }> { - return call(env, '/receipts/complete', { ...identity, reject }); + return call(env, '/receipts/complete', { + receiptId: identity.receiptId, + projectId: identity.projectId, + payloadDigest: identity.payloadDigest, + reject, + }); } /** Only generated, transport-irrelevant MIME fields are normalized. Body text stays byte-sensitive. */ export function canonicalizeVoidMime(raw: Uint8Array): Uint8Array { - const mime = decoder.decode(raw); - if (!mime.includes('\r\n\r\n')) { + if (findCrlfCrlf(raw) === -1) { return raw; } - const lines = mime.split('\r\n'); const boundaries = new Map(); - const output: Array = []; + const output: Array = []; + let outputBytes = 0; + let copyStart = 0; + let changed = false; let inHeaders = true; let topHeaders = true; - for (const line of lines) { + + const append = (bytes: Uint8Array): void => { + if (bytes.byteLength === 0) { + return; + } + output.push(bytes); + outputBytes += bytes.byteLength; + }; + const replace = (start: number, end: number, replacement: Uint8Array): void => { + append(raw.subarray(copyStart, start)); + append(replacement); + copyStart = end; + changed = true; + }; + + let lineStart = 0; + while (lineStart < raw.byteLength) { + const lineEnd = findCrlf(raw, lineStart); + const nextLine = lineEnd === raw.byteLength ? raw.byteLength : lineEnd + 2; if (inHeaders) { - if (line === '') { - output.push(line); + if (lineEnd === lineStart) { inHeaders = false; topHeaders = false; - continue; - } - if (topHeaders && /^(?:Date|Message-ID): /i.test(line)) { - continue; - } - if (/^Content-Type:\s*multipart\//i.test(line)) { - output.push( - line.replace( - /boundary="(=_void_(?:mixed|alternative|related)_[A-Za-z0-9_-]+)"/g, - (_, token: string) => { - let marker = boundaries.get(token); - if (!marker) { - marker = ``; - boundaries.set(token, marker); - } - return `boundary="${marker}"`; - }, - ), + } else if ( + topHeaders && + (asciiPrefixEquals(raw, lineStart, lineEnd, 'Date: ') || + asciiPrefixEquals(raw, lineStart, lineEnd, 'Message-ID: ')) + ) { + // Remove the generated field and its CRLF. The next header (or the + // terminating empty line) remains byte-for-byte unchanged. + replace(lineStart, nextLine, new Uint8Array()); + } else if (isMultipartContentType(raw, lineStart, lineEnd)) { + const line = decoder.decode(raw.subarray(lineStart, lineEnd)); + const normalized = line.replace( + /boundary="(=_void_(?:mixed|alternative|related)_[A-Za-z0-9_-]+)"/g, + (_, token: string) => { + let marker = boundaries.get(token); + if (!marker) { + marker = ``; + boundaries.set(token, marker); + } + return `boundary="${marker}"`; + }, ); - continue; + if (normalized !== line) { + replace(lineStart, lineEnd, encoder.encode(normalized)); + } } - output.push(line); - continue; - } - let delimiter = false; - for (const [token, marker] of boundaries) { - if (line === `--${token}`) { - output.push(`--${marker}`); + } else if (raw[lineStart] === 45 && raw[lineStart + 1] === 45) { + const tokenStart = lineStart + 2; + const token = isBoundaryToken(raw, tokenStart, lineEnd) + ? decoder.decode(raw.subarray(tokenStart, lineEnd)) + : undefined; + const openingMarker = token === undefined ? undefined : boundaries.get(token); + if (openingMarker !== undefined) { + replace(lineStart, lineEnd, encoder.encode(`--${openingMarker}`)); inHeaders = true; - delimiter = true; - break; - } - if (line === `--${token}--`) { - output.push(`--${marker}--`); - delimiter = true; - break; + } else if ( + lineEnd - tokenStart >= 2 && + raw[lineEnd - 2] === 45 && + raw[lineEnd - 1] === 45 && + isBoundaryToken(raw, tokenStart, lineEnd - 2) + ) { + const closingToken = decoder.decode(raw.subarray(tokenStart, lineEnd - 2)); + const closingMarker = boundaries.get(closingToken); + if (closingMarker !== undefined) { + replace(lineStart, lineEnd, encoder.encode(`--${closingMarker}--`)); + } } } - if (!delimiter) { - output.push(line); + lineStart = nextLine; + } + + if (!changed) { + return raw; + } + append(raw.subarray(copyStart)); + const normalized = new Uint8Array(outputBytes); + let offset = 0; + for (const chunk of output) { + normalized.set(chunk, offset); + offset += chunk.byteLength; + } + return normalized; +} + +function findCrlfCrlf(raw: Uint8Array): number { + for (let i = 0; i + 3 < raw.byteLength; i++) { + if (raw[i] === 13 && raw[i + 1] === 10 && raw[i + 2] === 13 && raw[i + 3] === 10) { + return i; + } + } + return -1; +} + +function findCrlf(raw: Uint8Array, start: number): number { + let cursor = start; + while (cursor < raw.byteLength) { + const cr = raw.indexOf(13, cursor); + if (cr === -1) { + return raw.byteLength; + } + if (raw[cr + 1] === 10) { + return cr; + } + cursor = cr + 1; + } + return raw.byteLength; +} + +function asciiPrefixEquals(raw: Uint8Array, start: number, end: number, expected: string): boolean { + if (end - start < expected.length) { + return false; + } + for (let i = 0; i < expected.length; i++) { + const actual = raw[start + i]; + const wanted = expected.charCodeAt(i); + if ((actual >= 65 && actual <= 90 ? actual + 32 : actual) !== (wanted | 32)) { + return false; + } + } + return true; +} + +function isMultipartContentType(raw: Uint8Array, start: number, end: number): boolean { + const field = 'Content-Type:'; + if (!asciiPrefixEquals(raw, start, end, field)) { + return false; + } + let cursor = start + field.length; + while ( + cursor < end && + (raw[cursor] === 32 || raw[cursor] === 9 || raw[cursor] === 11 || raw[cursor] === 12) + ) { + cursor++; + } + return asciiPrefixEquals(raw, cursor, end, 'multipart/'); +} + +function isBoundaryToken(raw: Uint8Array, start: number, end: number): boolean { + if (end <= start) { + return false; + } + for (let i = start; i < end; i++) { + const byte = raw[i]; + if ( + !( + (byte >= 65 && byte <= 90) || + (byte >= 97 && byte <= 122) || + (byte >= 48 && byte <= 57) || + byte === 95 || + byte === 45 || + byte === 61 + ) + ) { + return false; } } - return encoder.encode(output.join('\r\n')); + return true; } export async function emailPayloadDigest( @@ -244,6 +391,7 @@ export function recordEmailReceipt( receiptId: string, projectId: string, status: string, + route?: ReceiptRouteFence, ): Promise<{ ok: true }> { - return call(env, '/receipts', { receiptId, projectId, status }); + return call(env, '/receipts', { receiptId, projectId, status, ...(route ? { route } : {}) }); } diff --git a/platform/packages/proxy/src/email-lease.ts b/platform/packages/proxy/src/email-lease.ts index 4c7040b83..b44ea49af 100644 --- a/platform/packages/proxy/src/email-lease.ts +++ b/platform/packages/proxy/src/email-lease.ts @@ -4,6 +4,9 @@ import type { Env } from './types.ts'; export type EmailDomainLease = { kind: 'api_token'; token: string; accountId: string }; +const LEASE_DEADLINE_MS = 5_000; +const MAX_LEASE_RESPONSE_BYTES = 4 * 1024; + /** The bearer value for the send_raw Authorization header. */ export function leaseBearer(lease: EmailDomainLease): string { return lease.token; @@ -18,37 +21,100 @@ export async function leaseEmailDomainCredential( domain: string, projectId: string, ): Promise { + const controller = new AbortController(); + const deadline = Date.now() + LEASE_DEADLINE_MS; + const beforeDeadline = async (run: () => Promise): Promise => { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + controller.abort(); + throw new Error('email credential lease timed out'); + } + const promise = run(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('email credential lease timed out')); + }, remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }; + let res: Response; try { const token = await hmacSign( `email-lease-v1\n${projectId}\n${domain.toLowerCase()}`, env.JWT_SECRET, ); - res = await env.API.fetch('https://api/internal/email/domain-credential', { - method: 'POST', - headers: { - 'content-type': 'application/json', - 'x-void-internal': token, - }, - body: JSON.stringify({ domain, projectId }), - }); + res = await beforeDeadline(() => + env.API.fetch('https://api/internal/email/domain-credential', { + method: 'POST', + headers: { + 'content-type': 'application/json', + 'x-void-internal': token, + }, + body: JSON.stringify({ domain, projectId }), + signal: controller.signal, + }), + ); } catch { return null; } if (!res.ok) { + void res.body?.cancel().catch(() => {}); return null; } - let data: unknown; - try { - data = await res.json(); - } catch { + const declared = res.headers.get('content-length'); + if ( + declared !== null && + (!/^\d+$/.test(declared) || Number(declared) > MAX_LEASE_RESPONSE_BYTES) + ) { + void res.body?.cancel().catch(() => {}); return null; } - const lease = parseLease(data); - if (!lease) { + const reader = res.body?.getReader(); + if (!reader) { + return null; + } + const bytes = new Uint8Array(MAX_LEASE_RESPONSE_BYTES); + let size = 0; + try { + for (;;) { + const chunk = await beforeDeadline(() => reader.read()); + if (chunk.done) { + break; + } + if (size + chunk.value.byteLength > bytes.byteLength) { + throw new Error('email credential lease response too large'); + } + bytes.set(chunk.value, size); + size += chunk.value.byteLength; + } + if (declared !== null && size !== Number(declared)) { + return null; + } + const data: unknown = JSON.parse( + new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes.subarray(0, size)), + ); + return parseLease(data); + } catch { return null; + } finally { + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } } - return lease; } function parseLease(data: unknown): EmailDomainLease | null { diff --git a/platform/packages/proxy/src/email-provider-deadline.ts b/platform/packages/proxy/src/email-provider-deadline.ts new file mode 100644 index 000000000..572d0b029 --- /dev/null +++ b/platform/packages/proxy/src/email-provider-deadline.ts @@ -0,0 +1,44 @@ +export const EMAIL_PROVIDER_DEADLINE_MS = 30_000; +export const EMAIL_PROVIDER_BATCH_DEADLINE_MS = 60_000; + +export class EmailProviderTimeoutError extends Error { + constructor() { + super('email provider outcome unknown after timeout'); + this.name = 'EmailProviderTimeoutError'; + } +} + +/** One absolute batch budget, with a shorter ceiling for each provider submission. */ +export function createEmailProviderDeadline(totalMs = EMAIL_PROVIDER_BATCH_DEADLINE_MS) { + const deadline = Date.now() + totalMs; + return { + remainingMs(): number { + return Math.max(0, deadline - Date.now()); + }, + expired(): boolean { + return Date.now() >= deadline; + }, + async run(submit: () => Promise): Promise { + const remaining = Math.min(EMAIL_PROVIDER_DEADLINE_MS, deadline - Date.now()); + if (remaining <= 0) { + throw new EmailProviderTimeoutError(); + } + const work = submit(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + work, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new EmailProviderTimeoutError()), remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }, + }; +} + +export type EmailProviderDeadline = ReturnType; diff --git a/platform/packages/proxy/src/email-request-body.ts b/platform/packages/proxy/src/email-request-body.ts new file mode 100644 index 000000000..ce887a885 --- /dev/null +++ b/platform/packages/proxy/src/email-request-body.ts @@ -0,0 +1,70 @@ +const EMAIL_REQUEST_DEADLINE_MS = 5_000; +const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }); + +async function beforeDeadline(deadline: number, run: () => Promise): Promise { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('email request timeout'); + } + let timer: ReturnType | undefined; + return Promise.race([ + run(), + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('email request timeout')), remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); +} + +/** Bound public email request bodies before JSON parsing or authentication. */ +export async function readEmailRequestJson( + request: Request, + maxBytes = 2 * 1024, +): Promise { + const declaredLength = request.headers.get('content-length'); + if ( + request.headers.has('content-encoding') || + !request.body || + (declaredLength !== null && + (!/^\d+$/.test(declaredLength) || Number(declaredLength) > maxBytes)) + ) { + void request.body?.cancel().catch(() => {}); + throw new Error('invalid email request body'); + } + const expectedLength = declaredLength === null ? null : Number(declaredLength); + const reader = request.body.getReader(); + let bytes = new Uint8Array(Math.min(1024, maxBytes)); + const deadline = Date.now() + EMAIL_REQUEST_DEADLINE_MS; + let size = 0; + try { + for (;;) { + const chunk = await beforeDeadline(deadline, () => reader.read()); + if (chunk.done) { + break; + } + const nextSize = size + chunk.value.byteLength; + if (nextSize > maxBytes) { + throw new Error('email request body too large'); + } + if (nextSize > bytes.byteLength) { + const grown = new Uint8Array(Math.min(maxBytes, Math.max(nextSize, bytes.byteLength * 2))); + grown.set(bytes.subarray(0, size)); + bytes = grown; + } + bytes.set(chunk.value, size); + size = nextSize; + } + } finally { + // An uncooperative stream may never settle cancellation. Start cleanup, + // but do not let it extend the hard request-body deadline. + void reader.cancel().catch(() => {}); + reader.releaseLock(); + } + if (size === 0 || (expectedLength !== null && size !== expectedLength)) { + throw new Error('invalid email request body length'); + } + return JSON.parse(decoder.decode(bytes.subarray(0, size))); +} diff --git a/platform/packages/proxy/src/email-router.ts b/platform/packages/proxy/src/email-router.ts index a4d5e3eb6..955be7369 100644 --- a/platform/packages/proxy/src/email-router.ts +++ b/platform/packages/proxy/src/email-router.ts @@ -11,7 +11,12 @@ import { recordEmailReceipt, startEmailAttempt, } from './email-admission.ts'; +import type { ReceiptRouteFence } from './email-admission.ts'; import { leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; +import { + EMAIL_PROVIDER_DEADLINE_MS, + createEmailProviderDeadline, +} from './email-provider-deadline.ts'; import { MAX_MIME_BYTES, classifySendRawRecipient, @@ -19,6 +24,7 @@ import { readMimeFromAddrSpec, readSenderDomain, recordInboundDelivery, + requestSendRaw, } from './email.ts'; import type { Env } from './types.ts'; @@ -49,6 +55,9 @@ function describeUntrusted(value: unknown, maxLen: number): string { } export interface AuthoritativeEmailRoute { + routeId: string; + routeGeneration: number; + connectionId: string; projectId: string; workerName: string; deploymentId: string; @@ -58,6 +67,17 @@ export interface AuthoritativeEmailRoute { limits?: Record; } +function receiptRouteFence(route: AuthoritativeEmailRoute): ReceiptRouteFence { + return { + routeId: route.routeId, + routeGeneration: route.routeGeneration, + connectionId: route.connectionId, + addressing: route.addressing, + domain: route.domain, + projectSlug: route.slug, + }; +} + /** Bounded envelope passed through the gateway's tenant dispatch protocol. */ interface EmailEnvelope { from: string; @@ -106,6 +126,7 @@ const MAX_REPLY_BYTES = 5 * 1024 * 1024; /** Limit total reply MIME bytes in one delivery. */ const MAX_REPLY_BYTES_TOTAL = 8 * 1024 * 1024; +const INBOUND_STREAM_DEADLINE_MS = 15_000; class InboundTooLargeError extends Error { constructor(public readonly size: number) { @@ -315,7 +336,13 @@ export async function routeInbound( let actions: Array; try { - await recordEmailReceipt(env, receiptId, projectId, 'received'); + await recordEmailReceipt( + env, + receiptId, + projectId, + 'received', + receiptRouteFence(authoritative), + ); } catch { throw new Error('email admission temporarily unavailable'); } @@ -369,6 +396,7 @@ export async function routeRelayed( env: Env, ctx: ExecutionContext, input: { + stub: Fetcher; projectId: string; domain: string; envelope: EmailEnvelope; @@ -376,7 +404,7 @@ export async function routeRelayed( receiptId: string; }, ): Promise { - const { projectId, domain, envelope, authoritative, receiptId } = input; + const { stub, projectId, domain, envelope, authoritative, receiptId } = input; if ( authoritative.projectId !== projectId || @@ -389,19 +417,6 @@ export async function routeRelayed( const slug = authoritative.slug; const workerName = authoritative.workerName; - let stub: Fetcher; - try { - // Same per-project dispatch limits pass-through as the platform lane. - stub = ( - authoritative.limits - ? env.DISPATCH.get(workerName, {}, { limits: authoritative.limits }) - : env.DISPATCH.get(workerName) - ) as Fetcher; - } catch (e) { - console.error(`[email-relay] DISPATCH.get(${sanitize(workerName, 320)}) failed:`, e); - return { reject: true, temporary: true }; - } - // Built before dispatch so the dispatch-failure paths can log the // delivery against it, exactly as `routeInbound` logs against the real // message. The domain + authenticated project id key its REST send path @@ -490,42 +505,46 @@ async function prepareRelayedReply( from: string, raw: Uint8Array, expectedAccountId?: string, -): Promise<(to: string) => Promise> { +): Promise<(to: string, deadlineMs?: number) => Promise> { const senderDomain = from.slice(from.indexOf('@') + 1).toLowerCase(); + if (senderDomain === readSenderDomain(env)) { + const binding = env.SEND_EMAIL; + if (!binding || typeof binding.send !== 'function') { + throw new Error('shared email binding is unavailable'); + } + return async (to) => { + const result = await binding.send(new EmailMessage(from, to, envelopeRawStream(raw))); + return result?.messageId; + }; + } const lease = await leaseEmailDomainCredential(env, senderDomain, projectId); if (!lease || (expectedAccountId && lease.accountId !== expectedAccountId)) { throw new Error('could not lease the domain credential'); } const mimeMessage = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(raw); - return async (to) => { - let res: Response; + return async (to, deadlineMs = EMAIL_PROVIDER_DEADLINE_MS) => { + let response; try { - res = await fetch( - `https://api.cloudflare.com/client/v4/accounts/${lease.accountId}/email/sending/send_raw`, + response = await requestSendRaw( { - method: 'POST', - headers: { - authorization: `Bearer ${leaseBearer(lease)}`, - 'content-type': 'application/json', - }, - body: JSON.stringify({ from, recipients: [to], mime_message: mimeMessage }), + accountId: lease.accountId, + bearer: leaseBearer(lease), + from, + recipients: [to], + mimeMessage, }, + deadlineMs, ); } catch { throw new Error('email sending request failed'); } - if (!res.ok) { - if (res.status >= 500 || res.status === 408) { + if (!response.ok) { + if (response.status >= 500 || response.status === 408) { throw new Error('email sending API outcome unknown'); } - throw new DefinitiveEmailActionError(`email sending API returned ${res.status}`); - } - let data: unknown; - try { - data = await res.json(); - } catch { - throw new Error('email sending API response unreadable'); + throw new DefinitiveEmailActionError(`email sending API returned ${response.status}`); } + const data = response.data; if (typeof data !== 'object' || data === null || !('success' in data)) { throw new Error('email sending API response invalid'); } @@ -549,6 +568,7 @@ async function prepareRelayedReply( if (outcome === 'outcome_unknown') { throw new Error('email sending API did not classify the recipient'); } + return result.messageId; }; } @@ -626,23 +646,47 @@ async function readStreamToBytes(stream: ReadableStream): Promise = []; let total = 0; - for (;;) { - const { value, done } = await reader.read(); - if (done) { - break; - } - total += value.byteLength; - if (total > MAX_INBOUND_BYTES) { - // Cancel the stream so CF stops sending; throw a typed error the - // caller can recognize and turn into a clean SMTP reject. - try { - await reader.cancel(); - } catch { - // Cancellation is best-effort. + const deadline = Date.now() + INBOUND_STREAM_DEADLINE_MS; + try { + for (;;) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('inbound message stream timed out'); } - throw new InboundTooLargeError(total); + let timer: ReturnType | undefined; + const { value, done } = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout( + () => reject(new Error('inbound message stream timed out')), + remaining, + ); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (done) { + break; + } + total += value.byteLength; + if (total > MAX_INBOUND_BYTES) { + throw new InboundTooLargeError(total); + } + chunks.push(value); + } + } catch (error) { + // Do not let an uncooperative source extend the read deadline while its + // cancellation algorithm runs. + void reader.cancel().catch(() => {}); + throw error; + } finally { + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. } - chunks.push(value); } const out = new Uint8Array(total); let offset = 0; @@ -840,11 +884,16 @@ async function enactSanitized( ); return; } + const providerDeadline = createEmailProviderDeadline(); for (const [index, action] of actions.entries()) { if (action.type === 'reject') { message.setReject(action.reason); return; } + if (providerDeadline.expired()) { + console.error('[email-router] action batch deadline elapsed before admission'); + break; + } const to = action.to.toLowerCase(); const from = action.type === 'reply' ? action.from : message.to; const digest = await emailPayloadDigest( @@ -866,7 +915,11 @@ async function enactSanitized( recipients: [to], transport: gate.transport === 'relay' - ? 'send_raw' + ? action.type === 'reply' && + action.from.slice(action.from.indexOf('@') + 1).toLowerCase() === + readSenderDomain(env) + ? 'binding' + : 'send_raw' : action.type === 'forward' ? 'native_forward' : 'native_reply', @@ -883,7 +936,9 @@ async function enactSanitized( if (admission.replay || admitted?.state !== 'reserved') { continue; } - let relayedReply: ((to: string) => Promise) | undefined; + let relayedReply: + | ((to: string, deadlineMs?: number) => Promise) + | undefined; if (gate.transport === 'relay' && action.type === 'reply') { try { relayedReply = await prepareRelayedReply( @@ -901,18 +956,35 @@ async function enactSanitized( continue; } } + if (providerDeadline.expired()) { + const cancelled = await cancelUnstartedAction(env, admission.operationId, to); + console.error( + cancelled + ? '[email-router] action batch deadline elapsed; reservation cancelled' + : '[email-router] action batch deadline elapsed; cancellation unresolved', + ); + break; + } try { await startEmailAttempt(env, admission.operationId, [to]); } catch { - console.error('[email-router] could not commit attempt_started'); + const cancelled = await cancelUnstartedAction(env, admission.operationId, to); + console.error( + cancelled + ? '[email-router] attempt did not start; reservation cancelled' + : '[email-router] could not confirm attempt status', + ); continue; } try { + let providerReference: string | undefined; if (action.type === 'forward') { - await message.forward(to, action.headers); + await providerDeadline.run(() => message.forward(to, action.headers)); } else { if (relayedReply) { - await relayedReply(to); + providerReference = await providerDeadline.run(() => + relayedReply!(to, providerDeadline.remainingMs()), + ); } else { const stream = new ReadableStream({ start(controller) { @@ -920,11 +992,15 @@ async function enactSanitized( controller.close(); }, }); - await message.reply(new EmailMessage(action.from, to, stream) as never); + await providerDeadline.run(() => + message.reply(new EmailMessage(action.from, to, stream) as never), + ); } } try { - await finishEmailAttempt(env, admission.operationId, [to], 'provider_accepted'); + await finishEmailAttempt(env, admission.operationId, [to], 'provider_accepted', { + providerReference, + }); } catch { console.error('[email-router] provider accepted action but outcome ledger write failed'); } @@ -951,3 +1027,19 @@ async function enactSanitized( } } } + +/** Cancel only when the API still proves that no provider attempt started. */ +async function cancelUnstartedAction( + env: Env, + operationId: string, + recipient: string, +): Promise { + try { + const result = await finishEmailAttempt(env, operationId, [recipient], 'cancelled'); + return result.recipients.some( + (row) => row.recipient === recipient && row.state === 'cancelled', + ); + } catch { + return false; + } +} diff --git a/platform/packages/proxy/src/email.ts b/platform/packages/proxy/src/email.ts index d97227ddf..102aa398e 100644 --- a/platform/packages/proxy/src/email.ts +++ b/platform/packages/proxy/src/email.ts @@ -10,6 +10,11 @@ import { startEmailAttempt, } from './email-admission.ts'; import { leaseBearer, leaseEmailDomainCredential } from './email-lease.ts'; +import { + EMAIL_PROVIDER_DEADLINE_MS, + EmailProviderTimeoutError, + createEmailProviderDeadline, +} from './email-provider-deadline.ts'; import type { Env, ProxyEnv } from './types.ts'; const app = new Hono(); @@ -71,7 +76,7 @@ export function customMimeHeaderBytesWithinLimit(raw: Uint8Array): boolean { } /** Bound the raw list before normalization allocates one copy and Set entry per recipient. */ -const MAX_RECIPIENTS = 100; +const MAX_RECIPIENTS = 50; /** * Bound each address before normalization copies it. RFC 5321 caps a @@ -485,8 +490,7 @@ function singleMailboxAddrSpec(value: string): string | null { * from, // envelope sender (must be on an Email-Routing-enabled zone) * recipients: string[], // unique normalized recipient addresses * mimeBase64, // raw MIME, base64-encoded - * byteSize, // declared raw byte count - * requestId, fromDomain? // for logs + * requestId // for logs and default operation identity * } * * The proxy validates and normalizes the request, routes custom senders to @@ -812,11 +816,15 @@ app.post('/send', async (context) => { r.errorCode ?? (r.state === 'outcome_unknown' || r.state === 'attempt_started' ? 'OUTCOME_UNKNOWN' - : 'UNVERIFIED_DESTINATION'), + : r.state === 'cancelled' + ? 'UPSTREAM_ERROR' + : 'UNVERIFIED_DESTINATION'), message: r.state === 'outcome_unknown' || r.state === 'attempt_started' ? 'provider outcome unknown; inspect email logs before retrying' - : 'recipient was not admitted', + : r.state === 'cancelled' + ? 'email attempt was cancelled before provider submission' + : 'recipient was not admitted', }, })); if (admission.replay) { @@ -836,18 +844,48 @@ app.post('/send', async (context) => { const allowed = admission.recipients .filter((r) => r.state === 'reserved') .map((r) => r.recipient); + const providerDeadline = createEmailProviderDeadline(); // Send fan-out. CF's `send_email` binding takes one recipient per // EmailMessage — we already split by recipient above. - for (const r of allowed) { + for (let index = 0; index < allowed.length; index++) { + const r = allowed[index]; + if (providerDeadline.expired()) { + const unstarted = allowed.slice(index); + const cancelled = await cancelUnstartedRecipients( + context.env, + admission.operationId, + unstarted, + ); + for (const recipient of unstarted) { + deliveries.push({ + recipient, + ok: false, + state: cancelled ? 'cancelled' : 'outcome_unknown', + error: cancelled + ? { + code: 'UPSTREAM_ERROR', + message: 'email batch deadline elapsed before provider submission', + } + : { code: 'OUTCOME_UNKNOWN', message: 'could not cancel unstarted email attempt' }, + }); + } + break; + } try { await startEmailAttempt(context.env, admission.operationId, [r]); } catch { + const cancelled = await cancelUnstartedRecipients(context.env, admission.operationId, [r]); deliveries.push({ recipient: r, ok: false, - state: 'outcome_unknown', - error: { code: 'OUTCOME_UNKNOWN', message: 'could not confirm email attempt status' }, + state: cancelled ? 'cancelled' : 'outcome_unknown', + error: cancelled + ? { + code: 'UPSTREAM_ERROR', + message: 'email attempt did not start; reservation cancelled', + } + : { code: 'OUTCOME_UNKNOWN', message: 'could not confirm email attempt status' }, }); continue; } @@ -858,7 +896,7 @@ app.post('/send', async (context) => { const msg = new EmailMessage(from, r, bytesToStream(raw)); // Some CF builds don't return the messageId; we surface "" rather // than crash and let the framework decide whether to fall back. - const result = await sendBinding.send(msg); + const result = await providerDeadline.run(() => sendBinding.send(msg)); const providerReference = typeof result?.messageId === 'string' ? result.messageId : ''; try { await finishEmailAttempt(context.env, admission.operationId, [r], 'provider_accepted', { @@ -928,8 +966,7 @@ app.post('/send', async (context) => { /** * The Email Sending REST `send_raw` result. snake_case — the REST schema * names the id `message_id`, unlike the `send_email` binding's camelCase - * `messageId` (and the api's `SendRawResult` in `email/cf-customer.ts`, - * which declares the same field). Cloudflare returns every recipient in + * `messageId`. Cloudflare returns every recipient in * exactly one required list: `delivered` and `queued` are accepted; * `permanent_bounces` and `suppressed_recipients` are permanent failures. */ @@ -955,6 +992,115 @@ export type SendRawRecipientOutcome = | 'suppressed' | 'outcome_unknown'; +type SendRawHttpResponse = { ok: true; data: unknown } | { ok: false; status: number }; + +const MAX_SEND_RAW_RESPONSE_BYTES = 64 * 1024; + +/** Submit once and read the provider response within one absolute deadline. */ +export async function requestSendRaw( + input: { + accountId: string; + bearer: string; + from: string; + recipients: Array; + mimeMessage: string; + }, + deadlineMs = EMAIL_PROVIDER_DEADLINE_MS, +): Promise { + const requestBody = JSON.stringify({ + from: input.from, + recipients: input.recipients, + mime_message: input.mimeMessage, + }); + const controller = new AbortController(); + const deadline = Date.now() + Math.min(EMAIL_PROVIDER_DEADLINE_MS, deadlineMs); + const beforeDeadline = async (run: () => Promise): Promise => { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + controller.abort(); + throw new Error('email sending request timed out'); + } + const promise = run(); + let timer: ReturnType | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('email sending request timed out')); + }, remaining); + }), + ]); + } finally { + if (timer !== undefined) { + clearTimeout(timer); + } + } + }; + const response = await beforeDeadline(() => + fetch( + `https://api.cloudflare.com/client/v4/accounts/${input.accountId}/email/sending/send_raw`, + { + method: 'POST', + headers: { + authorization: `Bearer ${input.bearer}`, + 'content-type': 'application/json', + }, + body: requestBody, + signal: controller.signal, + }, + ), + ); + if (!response.ok) { + void response.body?.cancel().catch(() => {}); + return { ok: false, status: response.status }; + } + const declared = response.headers.get('content-length'); + if ( + declared !== null && + (!/^\d+$/.test(declared) || Number(declared) > MAX_SEND_RAW_RESPONSE_BYTES) + ) { + void response.body?.cancel().catch(() => {}); + throw new Error('email sending API response too large'); + } + const reader = response.body?.getReader(); + if (!reader) { + throw new Error('email sending API response unreadable'); + } + const bytes = new Uint8Array(MAX_SEND_RAW_RESPONSE_BYTES); + let size = 0; + try { + for (;;) { + const chunk = await beforeDeadline(() => reader.read()); + if (chunk.done) { + break; + } + if (size + chunk.value.byteLength > bytes.byteLength) { + throw new Error('email sending API response too large'); + } + bytes.set(chunk.value, size); + size += chunk.value.byteLength; + } + if (declared !== null && size !== Number(declared)) { + throw new Error('email sending API response length mismatch'); + } + return { + ok: true, + data: JSON.parse( + new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes.subarray(0, size)), + ) as unknown, + }; + } finally { + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } + } +} + /** Read one required send_raw address list without discarding schema violations. */ function readSendRawAddressList(value: unknown): Set | null { if (!Array.isArray(value)) { @@ -1123,11 +1269,15 @@ async function sendViaCustomDomain( r.errorCode ?? (r.state === 'outcome_unknown' || r.state === 'attempt_started' ? 'OUTCOME_UNKNOWN' - : 'UNVERIFIED_DESTINATION'), + : r.state === 'cancelled' + ? 'UPSTREAM_ERROR' + : 'UNVERIFIED_DESTINATION'), message: r.state === 'outcome_unknown' || r.state === 'attempt_started' ? 'provider outcome unknown; inspect email logs before retrying' - : 'recipient was not admitted', + : r.state === 'cancelled' + ? 'email attempt was cancelled before provider submission' + : 'recipient was not admitted', }, })); if (admission.replay) { @@ -1181,12 +1331,22 @@ async function sendViaCustomDomain( try { await startEmailAttempt(context.env, admission.operationId, recipients); } catch { + const cancelled = await cancelUnstartedRecipients( + context.env, + admission.operationId, + recipients, + ); for (const recipient of recipients) { deliveries.push({ recipient, ok: false, - state: 'outcome_unknown', - error: { code: 'OUTCOME_UNKNOWN', message: 'could not confirm email attempt status' }, + state: cancelled ? 'cancelled' : 'outcome_unknown', + error: cancelled + ? { + code: 'UPSTREAM_ERROR', + message: 'email attempt did not start; reservation cancelled', + } + : { code: 'OUTCOME_UNKNOWN', message: 'could not confirm email attempt status' }, }); } return emailActionResponse(context, admission.operationId, deliveries); @@ -1198,56 +1358,47 @@ async function sendViaCustomDomain( let failure: { code: string; message: string } | null = null; let failureState: 'failed' | 'outcome_unknown' = 'failed'; let sendRawResult: ParsedSendRawResult | null = null; - let cfRes: Response | null = null; + let providerResponse: SendRawHttpResponse | null = null; try { - cfRes = await fetch( - `https://api.cloudflare.com/client/v4/accounts/${lease.accountId}/email/sending/send_raw`, - { - method: 'POST', - headers: { - authorization: `Bearer ${leaseBearer(lease)}`, - 'content-type': 'application/json', - }, - body: JSON.stringify({ from, recipients, mime_message: mimeMessage }), - }, - ); + providerResponse = await requestSendRaw({ + accountId: lease.accountId, + bearer: leaseBearer(lease), + from, + recipients, + mimeMessage, + }); } catch { failure = { code: 'UPSTREAM_ERROR', message: 'email sending request failed' }; failureState = 'outcome_unknown'; } - if (cfRes) { - if (!cfRes.ok) { + if (providerResponse) { + if (!providerResponse.ok) { // A fresh credential is leased for every attempt. Provider error // bodies are not echoed or logged. failure = { - code: cfRes.status === 429 ? 'QUOTA_EXCEEDED' : 'UPSTREAM_ERROR', - message: `email sending API returned ${cfRes.status}`, + code: providerResponse.status === 429 ? 'QUOTA_EXCEEDED' : 'UPSTREAM_ERROR', + message: `email sending API returned ${providerResponse.status}`, }; - failureState = cfRes.status >= 500 || cfRes.status === 408 ? 'outcome_unknown' : 'failed'; + failureState = + providerResponse.status >= 500 || providerResponse.status === 408 + ? 'outcome_unknown' + : 'failed'; } else { - let data: unknown; - try { - data = await cfRes.json(); - } catch { - failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response unreadable' }; + const data = providerResponse.data; + const success = + typeof data === 'object' && data !== null + ? (data as { success?: unknown }).success + : undefined; + if (success === false) { + failure = { code: 'UPSTREAM_ERROR', message: 'email sending API refused the message' }; + } else if (success !== true) { + failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response invalid' }; failureState = 'outcome_unknown'; - } - if (!failure) { - const success = - typeof data === 'object' && data !== null - ? (data as { success?: unknown }).success - : undefined; - if (success === false) { - failure = { code: 'UPSTREAM_ERROR', message: 'email sending API refused the message' }; - } else if (success !== true) { + } else { + sendRawResult = parseSendRawResult((data as { result?: unknown }).result); + if (!sendRawResult) { failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response invalid' }; failureState = 'outcome_unknown'; - } else { - sendRawResult = parseSendRawResult((data as { result?: unknown }).result); - if (!sendRawResult) { - failure = { code: 'OUTCOME_UNKNOWN', message: 'email sending API response invalid' }; - failureState = 'outcome_unknown'; - } } } } @@ -1345,7 +1496,7 @@ async function sendViaCustomDomain( // Same mid-batch contract as the shared path: any per-recipient failure // (bounce, suppression, or a whole-call failure) answers ok:false with - // the per-recipient list so the caller retries exactly the failed ones. + // the complete per-recipient evidence needed for a safe retry decision. if (deliveries.some((d) => !d.ok)) { return context.json({ ok: false, operationId: admission.operationId, deliveries }, 200); } @@ -1391,6 +1542,26 @@ interface RecipientResult { error?: { code: string; message: string }; } +/** + * A failed start response is ambiguous: its transaction may or may not have + * committed. Cancellation is the safe discriminator because the API accepts + * it only from `reserved`; a committed `attempt_started` transition conflicts. + */ +async function cancelUnstartedRecipients( + env: Pick, + operationId: string, + recipients: Array, +): Promise { + try { + const result = await finishEmailAttempt(env, operationId, recipients, 'cancelled'); + return recipients.every((recipient) => + result.recipients.some((row) => row.recipient === recipient && row.state === 'cancelled'), + ); + } catch { + return false; + } +} + function emailActionResponse( context: Context, operationId: string, @@ -1538,14 +1709,20 @@ app.post('/internal/send', async (context) => { try { const msg = new EmailMessage(from, to, bytesToStream(raw)); - await sendBinding.send(msg); + await createEmailProviderDeadline(EMAIL_PROVIDER_DEADLINE_MS).run(() => sendBinding.send(msg)); return context.json({ ok: true }); } catch (err) { const message = err instanceof Error ? err.message : String(err); console.error( `[email-internal] send failed from=${sanitizeForLog(from, 320)} to=${sanitizeForLog(to, 320)}: ${sanitizeForLog(message, 320)}`, ); - return context.json({ ok: false, error: 'upstream error' }, 502); + return context.json( + { + ok: false, + error: err instanceof EmailProviderTimeoutError ? 'outcome unknown' : 'upstream error', + }, + err instanceof EmailProviderTimeoutError ? 504 : 502, + ); } }); diff --git a/platform/packages/proxy/src/index.ts b/platform/packages/proxy/src/index.ts index 8012ae01d..a07b2fd43 100644 --- a/platform/packages/proxy/src/index.ts +++ b/platform/packages/proxy/src/index.ts @@ -5,6 +5,7 @@ import { ai } from './ai.ts'; import { asNumber, asString, isProxyBody } from './body.ts'; import { proxyCapabilityEnabled } from './capabilities.ts'; import { d1 } from './d1.ts'; +import { readEmailRequestJson } from './email-request-body.ts'; import { email, MAX_MIME_BYTES, MAX_RECIPIENT_LENGTH, MAX_SENDER_LENGTH } from './email.ts'; import { guardHumanStream } from './human-stream.ts'; import { kv } from './kv.ts'; @@ -76,12 +77,8 @@ app.all('/*', async (context, next) => { // coordinated proxy + api deploy. const PLATFORM_INTERNAL_EMAIL_SENTINEL = 'void-platform-internal-email-v1'; -/** - * Largest base64 payload the platform-internal auth path will hash. Mirrors - * `MAX_MIME_BYTES` in `email.ts` (10 MiB), expressed as its base64 length with - * `+4` for padding rounding. - */ -const MAX_PLATFORM_MIME_BASE64_LENGTH = Math.ceil((10 * 1024 * 1024 * 4) / 3) + 4; +// Refuse impossible MIME sizes before hashing; the handler checks decoded bytes. +const MAX_PLATFORM_MIME_BASE64_LENGTH = Math.ceil((MAX_MIME_BYTES * 4) / 3) + 4; // Bind a fresh timestamp into the HMAC and require the request to land // within this many seconds of "now" — without it, a single observed @@ -127,38 +124,9 @@ async function hmacSign(data: string, secret: string): Promise { // The tenant calls this over its internal service binding. JWT_SECRET never // enters the tenant, so a project token cannot mint a gateway receipt. app.post('/email/verify-receipt', async (context) => { - const declaredLength = context.req.header('content-length'); - if (declaredLength && (!/^\d+$/.test(declaredLength) || Number(declaredLength) > 2048)) { - return context.json({ valid: false }, 400); - } let body: unknown; try { - const reader = context.req.raw.body?.getReader(); - if (!reader) { - return context.json({ valid: false }, 400); - } - const bytes = new Uint8Array(2048); - let size = 0; - try { - while (true) { - const chunk = await reader.read(); - if (chunk.done) { - break; - } - size += chunk.value.byteLength; - if (size > bytes.byteLength) { - return context.json({ valid: false }, 400); - } - bytes.set(chunk.value, size - chunk.value.byteLength); - } - } finally { - await reader.cancel().catch(() => {}); - reader.releaseLock(); - } - if (size === 0 || (declaredLength && size !== Number(declaredLength))) { - return context.json({ valid: false }, 400); - } - body = JSON.parse(new TextDecoder().decode(bytes.subarray(0, size))); + body = await readEmailRequestJson(context.req.raw); } catch { return context.json({ valid: false }, 400); } @@ -200,7 +168,11 @@ app.post('/*', async (context, next) => { let body: ProxyBody; try { - const json = await context.req.json(); + // Five MiB of MIME expands to about seven MiB of base64, plus JSON metadata. + const json = + path === '/email' || path.startsWith('/email/') + ? await readEmailRequestJson(context.req.raw, 8 * 1024 * 1024) + : await context.req.json(); if (!isProxyBody(json)) { return context.json({ error: 'invalid JSON body' }, 400); } diff --git a/platform/packages/proxy/test/unit/email-admission-send.test.ts b/platform/packages/proxy/test/unit/email-admission-send.test.ts index 7da527dbe..d6b7c5b9a 100644 --- a/platform/packages/proxy/test/unit/email-admission-send.test.ts +++ b/platform/packages/proxy/test/unit/email-admission-send.test.ts @@ -65,11 +65,19 @@ function fixture() { const entry = [...actions.values()].find((a) => a.operationId === operationId)!; if (path.endsWith('/start')) { for (const recipient of body.recipients as Array) { - entry.recipients.find((r) => r.recipient === recipient)!.state = 'attempt_started'; + const row = entry.recipients.find((r) => r.recipient === recipient)!; + if (row.state !== 'reserved') { + return Response.json({ code: 'INVALID_STATE' }, { status: 409 }); + } + row.state = 'attempt_started'; } } else if (path.endsWith('/finish')) { for (const recipient of body.recipients as Array) { const row = entry.recipients.find((r) => r.recipient === recipient)!; + const expected = body.state === 'cancelled' ? 'reserved' : 'attempt_started'; + if (row.state !== expected) { + return Response.json({ code: 'INVALID_STATE' }, { status: 409 }); + } row.state = body.state as string; row.providerReference = (body.providerReference as string) ?? null; row.errorCode = (body.errorCode as string) ?? null; @@ -149,4 +157,57 @@ describe('proxy email admission delivery', () => { 'provider_accepted', ]); }); + + it('cancels and durably replays a reservation when start fails before committing', async () => { + const test = fixture(); + const normalFetch = test.apiFetch.getMockImplementation()!; + test.apiFetch.mockImplementation(async (request, init) => { + const path = new URL(typeof request === 'string' ? request : request.url).pathname; + return path.endsWith('/start') + ? new Response(null, { status: 503 }) + : normalFetch(request, init); + }); + + const first = (await (await test.send('unstarted')).json()) as { + deliveries: Array<{ state: string; error: { code: string } }>; + }; + expect(first.deliveries[0]).toMatchObject({ + state: 'cancelled', + error: { code: 'UPSTREAM_ERROR' }, + }); + expect(test.actions.get('unstarted')?.recipients[0]?.state).toBe('cancelled'); + expect(test.sender).not.toHaveBeenCalled(); + + const replay = (await (await test.send('unstarted')).json()) as { + deliveries: Array<{ state: string; error: { code: string } }>; + }; + expect(replay.deliveries[0]).toMatchObject({ + state: 'cancelled', + error: { code: 'UPSTREAM_ERROR' }, + }); + expect(test.sender).not.toHaveBeenCalled(); + }); + + it('keeps the outcome unknown when start committed but its response was lost', async () => { + const test = fixture(); + const normalFetch = test.apiFetch.getMockImplementation()!; + test.apiFetch.mockImplementation(async (request, init) => { + const path = new URL(typeof request === 'string' ? request : request.url).pathname; + if (path.endsWith('/start')) { + await normalFetch(request, init); + return new Response(null, { status: 503 }); + } + return normalFetch(request, init); + }); + + const body = (await (await test.send('ambiguous-start')).json()) as { + deliveries: Array<{ state: string; error: { code: string } }>; + }; + expect(body.deliveries[0]).toMatchObject({ + state: 'outcome_unknown', + error: { code: 'OUTCOME_UNKNOWN' }, + }); + expect(test.actions.get('ambiguous-start')?.recipients[0]?.state).toBe('attempt_started'); + expect(test.sender).not.toHaveBeenCalled(); + }); }); diff --git a/platform/packages/proxy/test/unit/email-admission.test.ts b/platform/packages/proxy/test/unit/email-admission.test.ts index 58720c615..d748b82a6 100644 --- a/platform/packages/proxy/test/unit/email-admission.test.ts +++ b/platform/packages/proxy/test/unit/email-admission.test.ts @@ -1,5 +1,5 @@ -import { describe, expect, it } from 'vite-plus/test'; -import { emailPayloadDigest } from '../../src/email-admission.ts'; +import { describe, expect, it, vi } from 'vite-plus/test'; +import { admitEmail, emailPayloadDigest } from '../../src/email-admission.ts'; const encoder = new TextEncoder(); function message(date: string, id: string, boundary: string, body: string) { @@ -23,6 +23,41 @@ function message(date: string, id: string, boundary: string, body: string) { ); } +function nestedMessage(generation: string, bodyLine: string) { + const depth = 64; + const boundaries = Array.from( + { length: depth }, + (_, index) => `=_void_mixed_${generation}_${index}`, + ); + const lines = [ + `Date: Fri, 18 Sep 2026 01:00:${generation.padStart(2, '0')} +0000`, + 'From: acme@mail.example.com', + 'To: recipient@example.com', + `Message-ID: <${generation}@mail.example.com>`, + 'MIME-Version: 1.0', + `Content-Type: multipart/mixed; boundary="${boundaries[0]}"`, + '', + ]; + for (let index = 0; index < boundaries.length - 1; index++) { + lines.push( + `--${boundaries[index]}`, + `Content-Type: multipart/mixed; boundary="${boundaries[index + 1]}"`, + '', + ); + } + lines.push( + `--${boundaries.at(-1)}`, + 'Content-Type: text/plain; charset=UTF-8', + '', + ...Array.from({ length: 512 }, () => bodyLine), + ); + for (let index = boundaries.length - 1; index >= 0; index--) { + lines.push(`--${boundaries[index]}--`); + } + lines.push(''); + return encoder.encode(lines.join('\r\n')); +} + describe('email admission payload digest', () => { it('deduplicates retries when generated date, message ID and multipart boundary change', async () => { const a = message( @@ -42,6 +77,52 @@ describe('email admission payload digest', () => { ).toBe( await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], b), ); + + const boundaryEndingInDashesA = message( + 'Fri, 18 Sep 2026 01:00:00 +0000', + 'one@mail.example.com', + '=_void_mixed_A--', + 'hello', + ); + const boundaryEndingInDashesB = message( + 'Fri, 18 Sep 2026 01:01:00 +0000', + 'two@mail.example.com', + '=_void_mixed_B--', + 'hello', + ); + expect( + await emailPayloadDigest( + 'direct', + 'acme@mail.example.com', + ['recipient@example.com'], + boundaryEndingInDashesA, + ), + ).toBe( + await emailPayloadDigest( + 'direct', + 'acme@mail.example.com', + ['recipient@example.com'], + boundaryEndingInDashesB, + ), + ); + + const dateOnlyA = encoder.encode('Date: first\r\nFrom: acme@mail.example.com\r\n\r\nhello'); + const dateOnlyB = encoder.encode('Date: second\r\nFrom: acme@mail.example.com\r\n\r\nhello'); + expect( + await emailPayloadDigest( + 'direct', + 'acme@mail.example.com', + ['recipient@example.com'], + dateOnlyA, + ), + ).toBe( + await emailPayloadDigest( + 'direct', + 'acme@mail.example.com', + ['recipient@example.com'], + dateOnlyB, + ), + ); }); it('conflicts on changed message content and preserves boundary-like body text', async () => { @@ -94,4 +175,56 @@ describe('email admission payload digest', () => { await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], b), ); }); + + it('normalizes deeply nested generated boundaries without normalizing dense body lines', async () => { + const a = nestedMessage('1', 'same body'); + const b = nestedMessage('2', 'same body'); + const changed = nestedMessage('3', 'changed body'); + + const first = await emailPayloadDigest( + 'direct', + 'acme@mail.example.com', + ['recipient@example.com'], + a, + ); + expect(first).toBe( + await emailPayloadDigest('direct', 'acme@mail.example.com', ['recipient@example.com'], b), + ); + expect(first).not.toBe( + await emailPayloadDigest( + 'direct', + 'acme@mail.example.com', + ['recipient@example.com'], + changed, + ), + ); + }); +}); + +describe('email admission service deadline', () => { + it('settles when the service binding ignores its abort signal', async () => { + vi.useFakeTimers(); + try { + const fetch = vi.fn(() => new Promise(() => {})); + const pending = admitEmail( + { API: { fetch } as never, JWT_SECRET: 'secret' }, + { + projectId: 'project_1', + kind: 'direct', + key: 'request_1', + digest: 'a'.repeat(64), + from: 'sender@example.com', + recipients: ['recipient@example.com'], + transport: 'binding', + }, + ); + + await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce()); + const rejection = expect(pending).rejects.toThrow('EMAIL_ADMISSION_TIMEOUT'); + await vi.advanceTimersByTimeAsync(5_000); + await rejection; + } finally { + vi.useRealTimers(); + } + }); }); diff --git a/platform/packages/proxy/test/unit/email-custom-domain.test.ts b/platform/packages/proxy/test/unit/email-custom-domain.test.ts index 3703b08b9..b78796ff6 100644 --- a/platform/packages/proxy/test/unit/email-custom-domain.test.ts +++ b/platform/packages/proxy/test/unit/email-custom-domain.test.ts @@ -131,7 +131,7 @@ function createMockEnv() { SEND_EMAIL: { send: sendEmail }, EMAIL_SENDER_DOMAIN: PROD_DOMAIN, }; - return { env, apiFetch, sendEmail }; + return { env, apiFetch, sendEmail, actions }; } function base64Of(bytes: Uint8Array): string { @@ -264,6 +264,113 @@ describe('POST /email/send — custom sender domain', () => { expect(sendEmail).not.toHaveBeenCalled(); }); + it('cancels the whole unstarted batch when the start checkpoint fails', async () => { + const { env, apiFetch, actions } = createMockEnv(); + const normalFetch = apiFetch.getMockImplementation()!; + apiFetch.mockImplementation(async (url, init) => + String(url).endsWith('/start') ? new Response(null, { status: 503 }) : normalFetch(url, init), + ); + const providerCalls = stubCloudflare(); + + const response = await postSend( + env, + await sendBody({ recipients: ['one@example.com', 'two@example.com'] }), + ); + const body = (await response.json()) as { + deliveries: Array<{ state: string; error: { code: string } }>; + }; + expect(body.deliveries).toHaveLength(2); + expect(body.deliveries).toEqual( + expect.arrayContaining([ + expect.objectContaining({ + state: 'cancelled', + error: expect.objectContaining({ code: 'UPSTREAM_ERROR' }), + }), + expect.objectContaining({ + state: 'cancelled', + error: expect.objectContaining({ code: 'UPSTREAM_ERROR' }), + }), + ]), + ); + expect([...actions.values()][0]?.recipients.map((row) => row.state)).toEqual([ + 'cancelled', + 'cancelled', + ]); + expect(providerCalls).toEqual([]); + }); + + it.each(['fetch', 'body'] as const)( + 'times out a stalled credential lease %s and cancels before provider submission', + async (stall) => { + vi.useFakeTimers(); + const { env, apiFetch, actions } = createMockEnv(); + const normalFetch = apiFetch.getMockImplementation()!; + let markLeaseStarted!: () => void; + const leaseStarted = new Promise((resolve) => { + markLeaseStarted = resolve; + }); + apiFetch.mockImplementation(async (url, init) => { + if (!String(url).endsWith('/domain-credential')) { + return normalFetch(url, init); + } + markLeaseStarted(); + if (stall === 'fetch') { + return new Promise(() => {}); + } + return new Response( + new ReadableStream({ + start(controller) { + controller.enqueue( + new TextEncoder().encode( + JSON.stringify({ + kind: 'api_token', + token: LEASED, + accountId: 'acct_customer', + }), + ), + ); + }, + }), + ); + }); + const providerCalls = stubCloudflare(); + + const pending = postSend(env, await sendBody()); + await leaseStarted; + await vi.advanceTimersByTimeAsync(0); + await vi.advanceTimersByTimeAsync(5_000); + const response = await pending; + + expect(response.status).toBe(502); + expect([...actions.values()][0]?.recipients[0]?.state).toBe('cancelled'); + const finish = apiFetch.mock.calls.find(([url]) => String(url).endsWith('/finish')); + expect(finish).toBeDefined(); + expect(JSON.parse(String((finish![1] as RequestInit).body))).toMatchObject({ + state: 'cancelled', + }); + expect(providerCalls).toEqual([]); + }, + ); + + it('rejects an oversized credential lease body before provider submission', async () => { + const { env, apiFetch, actions } = createMockEnv(); + const normalFetch = apiFetch.getMockImplementation()!; + apiFetch.mockImplementation(async (url, init) => + String(url).endsWith('/domain-credential') + ? Response.json({ + kind: 'api_token', + token: 'x'.repeat(5 * 1024), + accountId: 'acct_customer', + }) + : normalFetch(url, init), + ); + const providerCalls = stubCloudflare(); + + expect((await postSend(env, await sendBody())).status).toBe(502); + expect([...actions.values()][0]?.recipients[0]?.state).toBe('cancelled'); + expect(providerCalls).toEqual([]); + }); + it('does not require the platform send binding for a custom-domain send', async () => { const { env } = createMockEnv(); delete (env as { SEND_EMAIL?: unknown }).SEND_EMAIL; @@ -468,6 +575,81 @@ describe('POST /email/send — custom sender domain', () => { }); }); + it.each(['fetch', 'body'] as const)( + 'bounds a send_raw %s that never settles and records an unknown outcome', + async (stall) => { + vi.useFakeTimers(); + const { env, apiFetch } = createMockEnv(); + let markProviderStarted!: () => void; + const providerStarted = new Promise((resolve) => { + markProviderStarted = resolve; + }); + vi.stubGlobal( + 'fetch', + vi.fn(() => { + markProviderStarted(); + if (stall === 'fetch') { + return new Promise(() => {}); + } + return Promise.resolve( + new Response( + new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode('{"success":true,"result":')); + }, + }), + ), + ); + }), + ); + + const pending = postSend(env, await sendBody()); + await providerStarted; + await vi.advanceTimersByTimeAsync(0); + await vi.advanceTimersByTimeAsync(30_000); + const body = await (await pending).json(); + + expect(body).toMatchObject({ + ok: false, + deliveries: [{ state: 'outcome_unknown', error: { code: 'OUTCOME_UNKNOWN' } }], + }); + const finishCall = apiFetch.mock.calls.find(([url]) => String(url).endsWith('/finish'))!; + expect(JSON.parse(String(finishCall[1].body)).state).toBe('outcome_unknown'); + }, + ); + + it('bounds an oversized send_raw response and records an unknown outcome', async () => { + const { env, apiFetch } = createMockEnv(); + const cancel = vi.fn(); + stubCloudflare( + () => + new Response( + new ReadableStream( + { + cancel, + pull() { + throw new Error('oversized body must not be read'); + }, + }, + { highWaterMark: 0 }, + ), + { headers: { 'content-length': String(64 * 1024 + 1) } }, + ), + ); + + const body = await (await postSend(env, await sendBody())).json(); + expect(body).toMatchObject({ + ok: false, + deliveries: [{ state: 'outcome_unknown', error: { code: 'OUTCOME_UNKNOWN' } }], + }); + expect( + JSON.parse( + String(apiFetch.mock.calls.find(([url]) => String(url).endsWith('/finish'))?.[1].body), + ).state, + ).toBe('outcome_unknown'); + await vi.waitFor(() => expect(cancel).toHaveBeenCalledOnce()); + }); + it('answers 502 when the lease fails, without burning quota or calling send_raw', async () => { const { env, apiFetch } = createMockEnv(); const normalFetch = apiFetch.getMockImplementation()!; diff --git a/platform/packages/proxy/test/unit/email-router.test.ts b/platform/packages/proxy/test/unit/email-router.test.ts index 5b2f647c0..a793020a5 100644 --- a/platform/packages/proxy/test/unit/email-router.test.ts +++ b/platform/packages/proxy/test/unit/email-router.test.ts @@ -25,6 +25,12 @@ import { } from '../../src/email-router.ts'; import type { Env } from '../../src/types.ts'; +const ROUTE_FENCE = { + routeId: 'route-1', + routeGeneration: 1, + connectionId: 'connection-1', +} as const; + async function routeInbound( message: ForwardableEmailMessage, env: Env, @@ -37,6 +43,7 @@ async function routeInbound( env, ctx, route ?? { + ...ROUTE_FENCE, projectId: 'p_test', workerName: 'user-worker', deploymentId: 'v1', @@ -340,7 +347,7 @@ describe('routeInbound — shared-address parsing', () => { }); it('routes a tag-less recipient (whole local-part is the slug)', async () => { - const { env, emailFn } = makeEnv({ emailReturn: [] }); + const { env, emailFn, apiFetch } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx); @@ -349,6 +356,12 @@ describe('routeInbound — shared-address parsing', () => { // The user worker sees the full, untruncated recipient. const envelope = emailFn.mock.calls[0]?.[0] as { to: string }; expect(envelope.to).toBe(`myslug@${PROD_DOMAIN}`); + expect(apiBodies(apiFetch, '/receipts')[0]?.route).toEqual({ + ...ROUTE_FENCE, + addressing: 'shared', + domain: PROD_DOMAIN, + projectSlug: 'myslug', + }); }); it('uppercase recipients are lowercased before dispatch', async () => { @@ -371,6 +384,7 @@ describe('routeInbound — authoritative routing', () => { const { message, rejectCalls } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); const { ctx } = createCtx(); await routeInbound(message, env, ctx, { + ...ROUTE_FENCE, projectId: 'p_test', workerName: 'user-worker', deploymentId: 'v1', @@ -388,6 +402,7 @@ describe('routeInbound — authoritative routing', () => { const { ctx } = createCtx(); const limits = { cpuMs: 1000 }; await routeInbound(message, env, ctx, { + ...ROUTE_FENCE, projectId: 'p_test', workerName: 'user-worker', deploymentId: 'v1', @@ -442,6 +457,34 @@ describe('routeInbound — message size guards', () => { expect(emailFn).not.toHaveBeenCalled(); }); + it('bounds a stalled inbound stream without awaiting its cancellation', async () => { + vi.useFakeTimers(); + vi.setSystemTime(FIXED_NOW); + try { + const { env, emailFn } = makeEnv(); + const { message, rejectCalls } = createFakeMessage({ + to: `myslug+tag@${PROD_DOMAIN}`, + rawSize: 1024, + }); + (message as unknown as { raw: ReadableStream }).raw = new ReadableStream({ + pull() { + return new Promise(() => {}); + }, + cancel() { + return new Promise(() => {}); + }, + }); + const { ctx } = createCtx(); + const result = routeInbound(message, env, ctx); + await vi.advanceTimersByTimeAsync(15_001); + await result; + expect(rejectCalls).toEqual(['mail.void.cloud: could not read inbound message body']); + expect(emailFn).not.toHaveBeenCalled(); + } finally { + vi.useRealTimers(); + } + }); + it('accepts a message just under the cap', async () => { const { env, emailFn } = makeEnv({ emailReturn: [] }); const { message, rejectCalls } = createFakeMessage({ @@ -760,6 +803,73 @@ describe('routeInbound — action enaction', () => { expect(replyCalls[0]?.to).toBe('admin@example.com'); expect(replyCalls[0]?.raw).toBeInstanceOf(ReadableStream); }); + + it('stops native action dispatch at the 60-second batch deadline', async () => { + vi.useFakeTimers(); + let firstSubmit!: () => void; + let secondSubmit!: () => void; + const firstSubmitted = new Promise((resolve) => { + firstSubmit = resolve; + }); + const secondSubmitted = new Promise((resolve) => { + secondSubmit = resolve; + }); + const { env, apiFetch } = makeEnv({ + emailReturn: [ + { type: 'forward', to: 'one@example.com' }, + { type: 'forward', to: 'two@example.com' }, + { type: 'forward', to: 'three@example.com' }, + ], + }); + const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); + let submissions = 0; + const forward = vi.fn(() => { + submissions++; + (submissions === 1 ? firstSubmit : secondSubmit)(); + return new Promise(() => {}); + }); + message.forward = forward; + const { ctx } = createCtx(); + const pending = routeInbound(message, env, ctx); + await firstSubmitted; + await vi.advanceTimersByTimeAsync(30_000); + await secondSubmitted; + await vi.advanceTimersByTimeAsync(30_000); + await pending; + + expect(forward).toHaveBeenCalledTimes(2); + expect(apiBodies(apiFetch, '/admit')).toHaveLength(2); + expect(apiBodies(apiFetch, '/finish').map((body) => body.state)).toEqual([ + 'outcome_unknown', + 'outcome_unknown', + ]); + }); + + it('marks a nonsettling native reply outcome unknown after 30 seconds', async () => { + vi.useFakeTimers(); + let markSubmitted!: () => void; + const submitted = new Promise((resolve) => { + markSubmitted = resolve; + }); + const sender = `myslug+support@${PROD_DOMAIN}`; + const { env, apiFetch } = makeEnv({ + emailReturn: [ + { type: 'reply', from: sender, to: 'admin@example.com', raw: replyRaw(sender) }, + ], + }); + const { message } = createFakeMessage({ to: `myslug@${PROD_DOMAIN}` }); + message.reply = vi.fn(() => { + markSubmitted(); + return new Promise(() => {}); + }); + const { ctx } = createCtx(); + const pending = routeInbound(message, env, ctx); + await submitted; + await vi.advanceTimersByTimeAsync(30_000); + await pending; + + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('outcome_unknown'); + }); }); // ----------------------------------------------------------------------- @@ -876,6 +986,7 @@ describe('routeInbound — authoritative native custom domain', () => { }); const { ctx } = createCtx(); await routeInbound(message, env, ctx, { + ...ROUTE_FENCE, projectId: 'p_test', workerName: 'custom-worker', deploymentId: 'v1', @@ -928,6 +1039,7 @@ describe('routeRelayed — unsupported forward', () => { const fetchSpy = vi.spyOn(globalThis, 'fetch'); const { ctx } = createCtx(); const outcome = await routeRelayed(env, ctx, { + stub: env.DISPATCH.get('user-worker') as Fetcher, projectId: 'p_test', domain: 'custom.example.com', receiptId: 'receipt_1', @@ -939,6 +1051,7 @@ describe('routeRelayed — unsupported forward', () => { rawSize: 42, }, authoritative: { + ...ROUTE_FENCE, projectId: 'p_test', workerName: 'user-worker', deploymentId: 'v1', @@ -962,23 +1075,62 @@ describe('routeRelayed — reply attempt outcomes', () => { async function runReply( response: Response, - options: { raw?: Uint8Array; leaseUnavailable?: boolean } = {}, + options: { + raw?: Uint8Array; + leaseUnavailable?: boolean; + from?: string; + bindingUnavailable?: boolean; + bindingNever?: boolean; + bindingStarted?: () => void; + startUnavailable?: boolean; + cancelUnavailable?: boolean; + } = {}, ) { + const replyFrom = options.from ?? from; const { env, apiFetch } = makeEnv({ - emailReturn: [{ type: 'reply', from, to, raw: options.raw ?? replyRaw(from) }], + emailReturn: [ + { type: 'reply', from: replyFrom, to, raw: options.raw ?? replyRaw(replyFrom) }, + ], }); + if (options.bindingUnavailable) { + delete (env as { SEND_EMAIL?: Env['SEND_EMAIL'] }).SEND_EMAIL; + } else if (options.bindingNever) { + vi.mocked(env.SEND_EMAIL.send).mockImplementation(() => { + options.bindingStarted?.(); + return new Promise(() => {}); + }); + } else { + vi.mocked(env.SEND_EMAIL.send).mockResolvedValue({ messageId: 'shared_reply' }); + } const normalFetch = apiFetch.getMockImplementation()!; - apiFetch.mockImplementation(async (url, init) => - String(url).endsWith('/domain-credential') - ? options.leaseUnavailable + apiFetch.mockImplementation(async (url, init) => { + const path = String(url); + if (path.endsWith('/domain-credential')) { + return options.leaseUnavailable ? new Response(null, { status: 503 }) - : Response.json({ kind: 'api_token', token: 'test-lease', accountId: 'customer-account' }) - : normalFetch(url, init), - ); + : Response.json({ + kind: 'api_token', + token: 'test-lease', + accountId: 'customer-account', + }); + } + if (options.startUnavailable && path.endsWith('/start')) { + return new Response(null, { status: 503 }); + } + if ( + options.cancelUnavailable && + path.endsWith('/finish') && + JSON.parse(String((init as RequestInit).body)).state === 'cancelled' + ) { + return new Response(null, { status: 503 }); + } + return normalFetch(url, init); + }); const providerFetch = vi.fn(async () => response); vi.stubGlobal('fetch', providerFetch); const { ctx } = createCtx(); const outcome = await routeRelayed(env, ctx, { + stub: env.DISPATCH.get('user-worker') as Fetcher, projectId: 'p_test', domain: 'custom.example.com', receiptId: 'receipt_1', @@ -990,6 +1142,7 @@ describe('routeRelayed — reply attempt outcomes', () => { rawSize: replyRaw(to).byteLength, }, authoritative: { + ...ROUTE_FENCE, projectId: 'p_test', workerName: 'user-worker', deploymentId: 'v1', @@ -998,9 +1151,72 @@ describe('routeRelayed — reply attempt outcomes', () => { domain: 'custom.example.com', }, }); - return { outcome, apiFetch, providerFetch }; + return { outcome, apiFetch, providerFetch, env }; } + it('sends a relayed shared-sender reply through the shared binding', async () => { + const { outcome, apiFetch, providerFetch, env } = await runReply(new Response(null), { + from: `myslug+support@${PROD_DOMAIN}`, + }); + expect(outcome.reject).toBe(false); + expect(apiBodies(apiFetch, '/admit')[0]).toMatchObject({ kind: 'reply', transport: 'binding' }); + expect(apiBodies(apiFetch, '/domain-credential')).toEqual([]); + expect(providerFetch).not.toHaveBeenCalled(); + expect(env.SEND_EMAIL.send).toHaveBeenCalledOnce(); + expect(apiBodies(apiFetch, '/finish')[0]).toMatchObject({ + state: 'provider_accepted', + providerReference: 'shared_reply', + }); + }); + + it('marks a timed-out relayed shared-sender binding submission outcome unknown', async () => { + vi.useFakeTimers(); + let markSubmitted!: () => void; + const submitted = new Promise((resolve) => { + markSubmitted = resolve; + }); + const pending = runReply(new Response(null), { + from: `myslug+support@${PROD_DOMAIN}`, + bindingNever: true, + bindingStarted: markSubmitted, + }); + await submitted; + await vi.advanceTimersByTimeAsync(30_000); + const { apiFetch, env } = await pending; + + expect(env.SEND_EMAIL.send).toHaveBeenCalledOnce(); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('outcome_unknown'); + }); + + it('cancels a shared reply before submission when its binding is unavailable', async () => { + const { outcome, apiFetch, providerFetch } = await runReply(new Response(null), { + from: `myslug+support@${PROD_DOMAIN}`, + bindingUnavailable: true, + }); + expect(outcome.reject).toBe(false); + expect(apiBodies(apiFetch, '/start')).toEqual([]); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('cancelled'); + expect(providerFetch).not.toHaveBeenCalled(); + }); + + it.each([ + [false, '[email-router] attempt did not start; reservation cancelled'], + [true, '[email-router] could not confirm attempt status'], + ])( + 'does not submit after a failed start checkpoint (cancellation unavailable: %s)', + async (cancelUnavailable, expectedLog) => { + const { apiFetch, providerFetch, env } = await runReply(new Response(null), { + from: `myslug+support@${PROD_DOMAIN}`, + startUnavailable: true, + cancelUnavailable, + }); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('cancelled'); + expect(env.SEND_EMAIL.send).not.toHaveBeenCalled(); + expect(providerFetch).not.toHaveBeenCalled(); + expect(errorSpy).toHaveBeenCalledWith(expectedLog); + }, + ); + it.each([ [new Response(null, { status: 500 }), 'outcome_unknown'], [new Response('{', { status: 200 }), 'outcome_unknown'], @@ -1064,6 +1280,25 @@ describe('routeRelayed — reply attempt outcomes', () => { }, ); + it('keeps an oversized provider response for a relayed reply unresolved', async () => { + const cancel = vi.fn(); + const response = new Response( + new ReadableStream( + { + cancel, + pull() { + throw new Error('oversized body must not be read'); + }, + }, + { highWaterMark: 0 }, + ), + { headers: { 'content-length': String(64 * 1024 + 1) } }, + ); + const { apiFetch } = await runReply(response); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('outcome_unknown'); + await vi.waitFor(() => expect(cancel).toHaveBeenCalledOnce()); + }); + it.each([{ leaseUnavailable: true }, { raw: new Uint8Array([...replyRaw(from), 0xff]) }])( 'cancels a reply that could not be submitted', async (options) => { diff --git a/platform/packages/proxy/test/unit/email.test.ts b/platform/packages/proxy/test/unit/email.test.ts index 73e5f14eb..d4dc4bb32 100644 --- a/platform/packages/proxy/test/unit/email.test.ts +++ b/platform/packages/proxy/test/unit/email.test.ts @@ -520,6 +520,32 @@ describe('POST /email/internal/send', () => { expect(await res.json()).toMatchObject({ capability: 'email' }); expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); }); + + it('returns an unknown outcome when the internal binding submission times out', async () => { + vi.useFakeTimers(); + try { + let markSubmitted!: () => void; + const submitted = new Promise((resolve) => { + markSubmitted = resolve; + }); + const env = createMockEnv(createMockKv(), { + SEND_EMAIL: { + send: vi.fn(() => { + markSubmitted(); + return new Promise(() => {}); + }), + }, + }); + const pending = postInternal(env, await internalBody(PROD_DOMAIN)); + await submitted; + await vi.advanceTimersByTimeAsync(30_000); + const response = await pending; + expect(response.status).toBe(504); + expect(await response.json()).toEqual({ ok: false, error: 'outcome unknown' }); + } finally { + vi.useRealTimers(); + } + }); }); async function drainStream(raw: unknown): Promise { @@ -605,6 +631,7 @@ interface SendResponseBody { deliveries?: Array<{ recipient: string; ok: boolean; + state?: string; messageId?: string; error?: { code: string }; }>; @@ -658,6 +685,55 @@ describe('POST /email/send — request validation', () => { expect(kv.store.get(monthKeyFor('proj_1'))).toBeUndefined(); }); + it('bounds binding fan-out at 60 seconds and cancels the unstarted reservation', async () => { + vi.useFakeTimers(); + try { + const recipients = ['first@example.com', 'second@example.com', 'third@example.com']; + const kv = happyPathKv({ + 'email-allowlist:proj_1': JSON.stringify(recipients), + }); + let markFirst!: () => void; + let markSecond!: () => void; + const firstSubmitted = new Promise((resolve) => { + markFirst = resolve; + }); + const secondSubmitted = new Promise((resolve) => { + markSecond = resolve; + }); + let submissions = 0; + const send = vi.fn(() => { + submissions++; + (submissions === 1 ? markFirst : markSecond)(); + return new Promise(() => {}); + }); + const env = createMockEnv(kv, { SEND_EMAIL: { send } }); + const pending = postSend(env, await sendBody({ recipients })); + + await firstSubmitted; + await vi.advanceTimersByTimeAsync(30_000); + await secondSubmitted; + await vi.advanceTimersByTimeAsync(30_000); + const body = await readSend(await pending); + + expect(send).toHaveBeenCalledTimes(2); + expect(body.deliveries?.map((delivery) => delivery.state)).toEqual([ + 'outcome_unknown', + 'outcome_unknown', + 'cancelled', + ]); + const finishes = (env.API as { fetch: ReturnType }).fetch.mock.calls + .filter(([url]) => String(url).endsWith('/finish')) + .map(([, init]) => JSON.parse(String((init as RequestInit).body)) as { state: string }); + expect(finishes.map((entry) => entry.state)).toEqual([ + 'outcome_unknown', + 'outcome_unknown', + 'cancelled', + ]); + } finally { + vi.useRealTimers(); + } + }); + it('rejects invalid base64 with 400 MIME_ERROR', async () => { const env = createMockEnv(happyPathKv()); const res = await postSend(env, await sendBody({ mimeBase64: '!!!not-base64!!!' })); @@ -690,17 +766,9 @@ describe('POST /email/send — request validation', () => { expect(res.status).toBe(400); }); - // A tenant worker holds a valid project HMAC (`__VOID_PROXY_TOKEN` is baked - // in as a plain-text binding), so it can POST any body to the public proxy - // hostname. Every recipient costs a normalized copy, a `seen` Set entry, - // and — when the allowlist rejects it — a delivery object interpolating the - // address, all of it then serialized into the response. Uncapped, a ~2.5 MB - // body reaches the 128 MB per-isolate ceiling, and the all-rejected path - // returns ABOVE the quota gates so the work is never metered and is - // endlessly repeatable. The proxy isolate is shared with every other - // tenant's in-flight traffic, so the kill is cross-tenant. + // Authenticated tenants still need a work bound before per-recipient processing. it('rejects a recipient list one over the cap, before any KV read', async () => { - const MAX_RECIPIENTS = 100; + const MAX_RECIPIENTS = 50; const kv = happyPathKv(); const sender = createSender(); const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); @@ -723,7 +791,7 @@ describe('POST /email/send — request validation', () => { }); it('still sends a recipient list sitting exactly at the cap', async () => { - const MAX_RECIPIENTS = 100; + const MAX_RECIPIENTS = 50; const recipients = Array.from({ length: MAX_RECIPIENTS }, (_, i) => `dev${i}@example.com`); const kv = createMockKv({ 'email-slug:proj_1': 'acme', @@ -742,9 +810,7 @@ describe('POST /email/send — request validation', () => { expect(kv.store.get(monthKeyFor('proj_1'))).toBeUndefined(); }); - // `MAX_RECIPIENTS` alone still leaves a 100 x
amplifier, - // because `.trim().toLowerCase()` copies each entry before anything has - // looked at its size. + // Bound each address before normalization copies it. it('rejects an over-long recipient before normalization allocates', async () => { const MAX_RECIPIENT_LENGTH = 320; const kv = happyPathKv(); @@ -1473,7 +1539,7 @@ describe('POST /email/internal/send — replay window + content binding', () => expect(sender.calls).toHaveLength(0); }); - it('rejects invalid base64 with 400 and oversized MIME with 413', async () => { + it('rejects invalid base64 and oversized JSON bodies before sending', async () => { const sender = createSender(); const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); @@ -1492,20 +1558,8 @@ describe('POST /email/internal/send — replay window + content binding', () => }); expect(bad.status).toBe(400); - // 11 MB decodes past the 10 MB cap. The size bound for this endpoint lives - // at the AUTH boundary, not in the handler: the token binds - // sha256(from|to|mimeBase64), so hashing an unbounded body would let an - // unauthenticated caller choose how much work we do. The middleware - // therefore refuses to hash anything longer than the base64 form of the - // cap, and an oversized body is rejected as an invalid token rather than - // reaching the handler's 413. Outsiders get one uniform rejection. - const big = new Uint8Array(11 * 1024 * 1024); - let binary = ''; - const CHUNK = 0x8000; - for (let i = 0; i < big.length; i += CHUNK) { - binary += String.fromCharCode(...big.subarray(i, i + CHUNK)); - } - const oversized = btoa(binary); + // The JSON byte limit runs before parsing or authentication. + const oversized = 'AAAA'.repeat((8 * 1024 * 1024) / 4 + 1); const bigTs = Math.floor(Date.now() / 1000); const tooBig = await post(env, { platformToken: await signPlatform({ @@ -1519,7 +1573,29 @@ describe('POST /email/internal/send — replay window + content binding', () => to: TO, mimeBase64: oversized, }); - expect(tooBig.status).toBe(403); + expect(tooBig.status).toBe(400); + expect(sender.calls).toHaveLength(0); + }); + + it('refuses MIME over the send limit before authenticating its content hash', async () => { + const sender = createSender(); + const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); + const mime = 'A'.repeat(Math.ceil((5 * 1024 * 1024 * 4) / 3) + 5); + const platformTimestamp = Math.floor(Date.now() / 1000); + const response = await post(env, { + platformToken: await signPlatform({ + unixSeconds: platformTimestamp, + from: FROM, + to: TO, + mimeBase64: mime, + }), + platformTimestamp, + from: FROM, + to: TO, + mimeBase64: mime, + }); + expect(response.status).toBe(403); + expect(await response.json()).toEqual({ error: 'invalid platform token' }); expect(sender.calls).toHaveLength(0); }); @@ -1559,17 +1635,9 @@ describe('POST /email/internal/send — replay window + content binding', () => it.each([ ['one character short (42)', (t: string) => t.slice(0, 42)], ['one character long (44)', (t: string) => `${t}A`], - ['30 MB', () => 'ab-_'.repeat((30 * 1024 * 1024) / 4)], + ['4 MiB', () => 'ab-_'.repeat((4 * 1024 * 1024) / 4)], ])('refuses a token that is %s before decoding it', async (_label, mutate) => { - // The only signer emits an HMAC-SHA256 tag as unpadded base64url — 32 - // bytes, exactly 43 characters — so any other length can never verify. - // `verifyHmac` decodes the token before comparing (two global replaces, - // `atob`, then `Uint8Array.from` over every character), which is ~50 B - // of heap per token character and runs ahead of every credential check: - // measured, a 30 MB token is ~1.5 GB and ~2 s, and a 4 MB one exhausts - // a 128 MB heap. The gate refuses on length, so `crypto.subtle.verify` - // — the only consumer of the decoded bytes — is never reached, and the - // refusal is the same opaque one every other pre-auth gate gives. + // Reject malformed lengths before HMAC decoding, even within the JSON byte limit. const sender = createSender(); const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); const mime = mimeBase64(); @@ -1579,7 +1647,6 @@ describe('POST /email/internal/send — replay window + content binding', () => ); const verify = vi.spyOn(crypto.subtle, 'verify'); try { - const t0 = performance.now(); const res = await post(env, { platformToken, platformTimestamp, @@ -1587,14 +1654,10 @@ describe('POST /email/internal/send — replay window + content binding', () => to: TO, mimeBase64: mime, }); - const elapsed = performance.now() - t0; expect(res.status).toBe(403); expect(await res.json()).toEqual({ error: 'invalid platform token' }); expect(verify).not.toHaveBeenCalled(); expect(sender.calls).toHaveLength(0); - // Generous: parsing the 30 MB JSON body is the whole cost now; the - // decode it no longer reaches measured ~2 s on this input. - expect(elapsed).toBeLessThan(1000); } finally { verify.mockRestore(); } @@ -1765,7 +1828,7 @@ describe('POST /email/send — the envelope handed to CF', () => { // hex chars, but a hand-built tenant worker holding a valid project HMAC can // send any string, and `logSend` used to interpolate it verbatim into one // `[email-log]` line per delivery — so a `\n` in it forged a second line under -// any project id, and a multi-megabyte one was repeated up to 100 times into +// any project id, and a multi-megabyte one was repeated per recipient into // the shared proxy log stream. It is bounded and sanitized once at intake. // --------------------------------------------------------------------------- diff --git a/platform/packages/proxy/test/unit/proxy.test.ts b/platform/packages/proxy/test/unit/proxy.test.ts index 28de9e329..e08a8a067 100644 --- a/platform/packages/proxy/test/unit/proxy.test.ts +++ b/platform/packages/proxy/test/unit/proxy.test.ts @@ -1,4 +1,5 @@ import { describe, it, expect, vi, beforeAll, afterEach } from 'vite-plus/test'; +import { readEmailRequestJson } from '../../src/email-request-body.ts'; import worker from '../../src/index.ts'; import { PLATFORM_DISABLED_KEY } from '../../src/platform-lifecycle.ts'; @@ -173,6 +174,7 @@ describe('proxy worker', () => { const aiTokens: Record = {}; afterEach(() => { + vi.useRealTimers(); vi.unstubAllGlobals(); }); @@ -280,6 +282,137 @@ describe('proxy worker', () => { }); }); + describe('email receipt verification', () => { + it('initiates cancellation without awaiting an uncooperative request stream', async () => { + vi.useFakeTimers(); + let cancelled = 0; + const body = new ReadableStream({ + cancel() { + cancelled++; + return new Promise(() => {}); + }, + }); + const request = new Request('https://proxy.void.cloud/email/verify-receipt', { + method: 'POST', + body, + duplex: 'half', + } as RequestInit); + const outcome = readEmailRequestJson(request).then( + () => 'resolved', + (error: unknown) => error, + ); + + await vi.advanceTimersByTimeAsync(5_000); + + expect(await outcome).toBeInstanceOf(Error); + expect(String(await outcome)).toContain('timeout'); + expect(cancelled).toBe(1); + }); + + it('ends a stalled unauthenticated request body at five seconds', async () => { + vi.useFakeTimers(); + const body = new ReadableStream({ + cancel() { + return new Promise(() => {}); + }, + }); + const request = new Request('https://proxy.void.cloud/email/verify-receipt', { + method: 'POST', + body, + duplex: 'half', + } as RequestInit); + const response = worker.fetch(request, createEnv()); + + await vi.advanceTimersByTimeAsync(5_000); + + expect((await response).status).toBe(400); + }); + + it('rejects invalid UTF-8 before receipt authentication', async () => { + const response = await worker.fetch( + new Request('https://proxy.void.cloud/email/verify-receipt', { + method: 'POST', + headers: { 'content-length': '1' }, + body: new Uint8Array([0xff]), + }), + createEnv(), + ); + + expect(response.status).toBe(400); + expect(await response.json()).toEqual({ valid: false }); + }); + + it('rejects a mismatched declared request length', async () => { + const response = await worker.fetch( + new Request('https://proxy.void.cloud/email/verify-receipt', { + method: 'POST', + headers: { 'content-length': '3' }, + body: '{}', + }), + createEnv(), + ); + + expect(response.status).toBe(400); + expect(await response.json()).toEqual({ valid: false }); + }); + }); + + describe('email send request bounds', () => { + it('allows a maximum-size MIME envelope through to authentication', async () => { + const response = await worker.fetch( + new Request('https://proxy.void.cloud/email/send', { + method: 'POST', + body: JSON.stringify({ + projectId: 'proj_1', + aiToken: 'invalid-project-token', + mimeBase64: 'AAAA'.repeat(Math.ceil((5 * 1024 * 1024) / 3)), + }), + }), + createEnv(), + ); + expect(response.status).toBe(403); + }); + + it.each(['/email/send', '/email/internal/send', '/email/unknown'])( + 'rejects an oversized declared body before reading %s', + async (path) => { + const pull = vi.fn((controller: ReadableStreamDefaultController) => { + controller.enqueue(new TextEncoder().encode('{}')); + controller.close(); + }); + const cancel = vi.fn(); + const request = new Request(`https://proxy.void.cloud${path}`, { + method: 'POST', + headers: { 'content-length': String(8 * 1024 * 1024 + 1) }, + body: new ReadableStream({ pull, cancel }, { highWaterMark: 0 }), + duplex: 'half', + } as RequestInit); + const response = await worker.fetch(request, createEnv()); + expect(response.status).toBe(400); + expect(pull).not.toHaveBeenCalled(); + expect(cancel).toHaveBeenCalledOnce(); + }, + ); + + it('ends a stalled unauthenticated send body without waiting for cancellation', async () => { + vi.useFakeTimers(); + const cancel = vi.fn(() => new Promise(() => {})); + const request = new Request('https://proxy.void.cloud/email/send', { + method: 'POST', + body: new ReadableStream({ cancel }), + duplex: 'half', + } as RequestInit); + let status: number | undefined; + const response = worker.fetch(request, createEnv()).then((value) => { + status = value.status; + }); + await vi.advanceTimersByTimeAsync(5_000); + expect(status).toBe(400); + expect(cancel).toHaveBeenCalledOnce(); + await response; + }); + }); + describe('JWT authentication (HTTPS path)', () => { it('accepts valid JWT for the project owner', async () => { const env = createEnv(); From e269fb2a48bda0173a6c60239de6ae00a0ffff74 Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sat, 19 Sep 2026 15:40:24 +0800 Subject: [PATCH 5/6] fix(email): select recovery steps from current connection state --- docs/guide/email.md | 2 +- docs/reference/cli.md | 2 +- .../api/src/email/connection-service.ts | 41 +++-- .../integration/email-connections.test.ts | 172 ++++++++++++++++++ 4 files changed, 203 insertions(+), 14 deletions(-) diff --git a/docs/guide/email.md b/docs/guide/email.md index a3aa38084..790609273 100644 --- a/docs/guide/email.md +++ b/docs/guide/email.md @@ -89,7 +89,7 @@ Setup returns an operation ID. If your connection drops, the platform keeps the - **Outbound**: whether sending is ready, restricted to verified destinations, pending, or blocked. - **Management**: whether the stored Cloudflare credential can manage the connection. -Use `void email domain sync ` to reconcile setup and refresh readiness. Sync does not rotate the connection secret. Use `void email domain rotate-secret ` for an explicit rotation; it applies to all domains sharing that zone connection and verifies the deployed secret before completing. If a dashboard or credential step is required, the status names it. Removing a domain disables its assignment; zone resources used by another domain remain in place, and unfinished cleanup stays recorded for reconciliation. +Use `void email domain sync ` to reconcile setup and refresh readiness. Sync does not rotate the connection secret. Use `void email domain rotate-secret ` for an explicit rotation; it applies to all domains sharing that zone connection and verifies the deployed secret before completing. Rotation requires inbound readiness; run `sync` first if setup is incomplete. If a dashboard or credential step is required, the status names it. Removing a domain disables its assignment; zone resources used by another domain remain in place, and unfinished cleanup stays recorded for reconciliation. After the last assignment's ingress is deleted, the platform forgets its stored credential. Revoke a token you no longer use in Cloudflare; Void does not revoke diff --git a/docs/reference/cli.md b/docs/reference/cli.md index f938fa5dc..4ce50e703 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1555,7 +1555,7 @@ Reconcile the domain connection and refresh readiness. Sync does not rotate its void email domain rotate-secret [--project ] ``` -Rotate the ingress secret for the zone connection shared by this domain and its siblings. The platform accepts the staged secret before updating the Worker and promotes it only after verifying the deployed generation. An uncertain update stays recorded for reconciliation. +Rotate the ingress secret for the zone connection shared by this domain and its siblings. Inbound must be ready; run `void email domain sync ` first if setup is incomplete. The platform accepts the staged secret before updating the Worker and promotes it only after verifying the deployed generation. An uncertain update stays recorded for reconciliation. #### `void email domain remove` diff --git a/platform/packages/api/src/email/connection-service.ts b/platform/packages/api/src/email/connection-service.ts index e5bb3fb16..a19ae1e03 100644 --- a/platform/packages/api/src/email/connection-service.ts +++ b/platform/packages/api/src/email/connection-service.ts @@ -588,11 +588,13 @@ async function resumeBlockedEmailOperationTx( operation.connection_id !== snapshot.connection_id || operation.route_id !== snapshot.route_id || operation.desired_generation !== snapshot.desired_generation || - connection.desired_generation !== operation.desired_generation || !canManageConnection(actor, connection) ) { throw new EmailOperationError('blocked email operation cannot be resumed', 409); } + if (connection.desired_generation !== operation.desired_generation) { + return false; + } const blocked = await tx .select() .from(emailOperationSteps) @@ -1427,7 +1429,9 @@ export async function requestEmailDomainAdd( eq(emailOperations.route_id, existingRoute.id), eq(emailOperations.route_generation, existingRoute.desired_generation), eq(emailOperations.actor_kind, actor.kind), - eq(emailOperations.actor_user_id, actor.userId), + ...(actor.kind === 'owner' + ? [eq(emailOperations.actor_user_id, actor.userId)] + : []), inArray(emailOperations.kind, ['setup', 'sync']), eq(emailOperations.status, 'blocked'), eq(emailOperations.desired_generation, connection.desired_generation), @@ -1532,10 +1536,14 @@ export async function requestEmailDomainAdd( request_digest: requestDigest, desired_generation: generation, }); - const steps = - connection.staged_secret_generation !== null + const steps = isSharedGatewayConnection(env, connection) + ? SHARED_SYNC_STEPS + : connection.staged_secret_generation !== null ? STAGED_SECRET_REPAIR_STEPS - : connection.inbound_status === 'disabled' || blockedAssignment + : connection.inbound_status !== 'ready' || + existingRoute.inbound_status !== 'ready' || + reactivating || + blockedAssignment ? SETUP_STEPS : SYNC_STEPS; const stepRoute: EmailStepRoute = { @@ -1666,7 +1674,7 @@ export async function requestEmailDomainAdd( .where(eq(emailZoneConnections.id, connection.id)); } const repairStaged = connection.staged_secret_generation !== null; - if (repairStaged) { + if (!created) { connection = ( await tx .update(emailZoneConnections) @@ -1701,11 +1709,13 @@ export async function requestEmailDomainAdd( request_digest: requestDigest, desired_generation: connection.desired_generation, }); - const steps = repairStaged - ? STAGED_SECRET_REPAIR_STEPS - : created || connection.inbound_status === 'disabled' - ? SETUP_STEPS - : SIBLING_STEPS; + const steps = isSharedGatewayConnection(env, connection) + ? SHARED_SYNC_STEPS + : repairStaged + ? STAGED_SECRET_REPAIR_STEPS + : created || connection.inbound_status !== 'ready' + ? SETUP_STEPS + : SIBLING_STEPS; const stepRoute: EmailStepRoute = { id: routeId, domain, desired_generation: 1 }; for (let i = 0; i < steps.length; i++) { const secretGeneration = emailStepSecretGeneration('setup', connection, steps[i]); @@ -2129,6 +2139,9 @@ export async function requestEmailSecretRotation( await resumeBlockedEmailOperationTx(tx, env, blockedRotation.id, actor); return blockedRotation.id; } + if (connection.inbound_status !== 'ready') { + throw new EmailOperationError('email ingress must be ready before rotating its secret', 409); + } if (connection.staged_secret_generation !== null) { throw new EmailOperationError('ingress rotation already staged'); } @@ -2437,7 +2450,11 @@ async function requestExistingOperation( kind === 'sync' ? isSharedGatewayConnection(env, connection) ? SHARED_SYNC_STEPS - : SYNC_STEPS + : connection.staged_secret_generation !== null + ? STAGED_SECRET_REPAIR_STEPS + : connection.inbound_status !== 'ready' || route.inbound_status !== 'ready' + ? SETUP_STEPS + : SYNC_STEPS : REMOVE_STEPS; for (let i = 0; i < steps.length; i++) { const secretGeneration = emailStepSecretGeneration(kind, connection, steps[i]); diff --git a/platform/packages/api/test/integration/email-connections.test.ts b/platform/packages/api/test/integration/email-connections.test.ts index 8903999eb..4a5a8bb70 100644 --- a/platform/packages/api/test/integration/email-connections.test.ts +++ b/platform/packages/api/test/integration/email-connections.test.ts @@ -280,6 +280,69 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(1); }); + it('repairs a pending reused connection and its superseded original route', async () => { + const owner = await createTestUser(env.db); + const project = await createTestProject(env.db, owner.id, 'pending-connection-repair'); + const failures: NonNullable[0]>['failOn'] = { + routingDns: { message: 'routing permission denied', status: 403 }, + }; + const stub = stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: owner.id }; + const originalInput = { + projectId: project.id, + domain: 'pending-original.example.com', + token: TOKEN, + actor, + attemptId: 'pending-original-attempt', + }; + const original = await requestEmailDomainAdd(env.db, bindings(), originalInput); + await runEmailOperation(env.db, bindings(), original.operationId); + const blocked = ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, original.operationId)) + )[0]!; + expect(blocked).toMatchObject({ status: 'blocked', current_step: 'routing_enable' }); + + delete failures.routingDns; + const replacement = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'pending-replacement.example.com', + token: 'corrected-customer-token', + actor, + }); + await runEmailOperation(env.db, bindings(), replacement.operationId); + + const replacementRoute = (await resolveEmailDomain(env.db, 'pending-replacement.example.com'))!; + expect(replacementRoute.route.inbound_status).toBe('ready'); + expect(replacementRoute.connection.desired_generation).toBeGreaterThan( + blocked.desired_generation, + ); + expect(await requestEmailDomainAdd(env.db, bindings(), originalInput)).toEqual(original); + expect( + ( + await env.db + .select() + .from(emailOperations) + .where(eq(emailOperations.id, original.operationId)) + )[0]?.status, + ).toBe('blocked'); + + const repairedOriginal = await requestEmailDomainSync( + env.db, + bindings(), + original.routeId, + actor, + ); + await runEmailOperation(env.db, bindings(), repairedOriginal); + expect( + (await resolveEmailDomain(env.db, 'pending-original.example.com'))?.route.inbound_status, + ).toBe('ready'); + expect(callsByTag(stub.calls, 'scriptPut')).toHaveLength(2); + expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(2); + }); + it('blocks a failed provider read before its write and resumes without an ambiguous mutation', async () => { const owner = await createTestUser(env.db); const project = await createTestProject(env.db, owner.id, 'probe-route-preflight'); @@ -2373,6 +2436,93 @@ describe('durable zone email connections', () => { expect(callsByTag(stub.calls, 'secretPut')).toHaveLength(3); }); + it('retires a blocked rotation through domain sync before allowing the next rotation', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'sync-staged-rotation'); + const failures: NonNullable[0]>['failOn'] = {}; + stubCustomerCf({ zones, failOn: failures }); + const actor = { kind: 'owner' as const, userId: user.id }; + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'sync-staged-rotation.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const connection = (await resolveEmailDomain(env.db, 'sync-staged-rotation.example.com'))! + .connection; + const blockedKey = 'sync-staged-blocked-rotation'; + const blockedRotation = await requestEmailSecretRotation( + env.db, + bindings(), + connection.id, + actor, + blockedKey, + ); + failures.secretPut = { message: 'secret permission denied', status: 403 }; + await runEmailOperation(env.db, bindings(), blockedRotation); + const staged = (await resolveEmailDomain(env.db, 'sync-staged-rotation.example.com'))! + .connection; + expect(staged.staged_secret_generation).toBe(connection.active_secret_generation + 1); + + delete failures.secretPut; + const sync = await requestEmailDomainSync(env.db, bindings(), added.routeId, actor); + await runEmailOperation(env.db, bindings(), sync); + const repaired = (await resolveEmailDomain(env.db, 'sync-staged-rotation.example.com'))! + .connection; + expect(repaired.active_secret_generation).toBe(connection.active_secret_generation); + expect(repaired.staged_secret_generation).toBeNull(); + expect( + ( + await env.db.select().from(emailOperations).where(eq(emailOperations.id, blockedRotation)) + )[0]?.status, + ).toBe('blocked'); + expect( + await requestEmailSecretRotation(env.db, bindings(), connection.id, actor, blockedKey), + ).toBe(blockedRotation); + + const nextRotation = await requestEmailSecretRotation(env.db, bindings(), connection.id, actor); + await runEmailOperation(env.db, bindings(), nextRotation); + expect( + (await env.db.select().from(emailOperations).where(eq(emailOperations.id, nextRotation)))[0] + ?.status, + ).toBe('completed'); + }); + + it('rejects a fresh secret rotation while the connection setup is pending', async () => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'pending-rotation'); + const actor = { kind: 'owner' as const, userId: user.id }; + stubCustomerCf({ + zones, + failOn: { routingDns: { message: 'routing permission denied', status: 403 } }, + }); + const added = await requestEmailDomainAdd(env.db, bindings(), { + projectId: project.id, + domain: 'pending-rotation.example.com', + actor, + token: TOKEN, + }); + await runEmailOperation(env.db, bindings(), added.operationId); + const connection = (await resolveEmailDomain(env.db, 'pending-rotation.example.com'))! + .connection; + + await expect( + requestEmailSecretRotation(env.db, bindings(), connection.id, actor), + ).rejects.toThrow('must be ready'); + expect( + ( + await env.db + .select() + .from(emailZoneConnections) + .where(eq(emailZoneConnections.id, connection.id)) + )[0], + ).toMatchObject({ + desired_generation: connection.desired_generation, + staged_secret_generation: null, + }); + }); + it('repairs a blocked rotation with a corrected credential before retiring its staged secret', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id, 'rotation-credential-repair'); @@ -2592,6 +2742,13 @@ describe('durable zone email connections', () => { userId: owner.id, }); await runEmailOperation(env.db, shared, sync); + const retried = await requestEmailDomainAdd(env.db, shared, { + projectId: project.id, + domain: 'alerts.example.com', + actor: { kind: 'admin', userId: owner.id }, + attemptId: 'shared-active-retry', + }); + await runEmailOperation(env.db, shared, retried.operationId); await expect( requestEmailSecretRotation(env.db, shared, route!.connection.id, { kind: 'admin', @@ -2603,6 +2760,21 @@ describe('durable zone email connections', () => { userId: owner.id, }); await runEmailOperation(env.db, shared, remove); + const readded = await requestEmailDomainAdd(env.db, shared, { + projectId: project.id, + domain: 'alerts.example.com', + actor: { kind: 'admin', userId: owner.id }, + attemptId: 'shared-removed-retry', + }); + await runEmailOperation(env.db, shared, readded.operationId); + expect((await resolveEmailDomain(env.db, 'alerts.example.com'))?.route.inbound_status).toBe( + 'ready', + ); + const finalRemove = await requestEmailDomainRemove(env.db, shared, added.routeId, { + kind: 'admin', + userId: owner.id, + }); + await runEmailOperation(env.db, shared, finalRemove); const removedRoute = (await resolveEmailDomain(env.db, 'alerts.example.com'))!.route; expect(removedRoute.desired_state).toBe('removed'); expect( From a6612c363a6d0e09177a4c59e270895542b434be Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sat, 19 Sep 2026 20:15:15 +0800 Subject: [PATCH 6/6] fix(email): require ingress identity before runtime upgrades --- docs/guide/self-hosted-platform.md | 2 +- packages/void/src/cli/platform-plan.ts | 5 +++ packages/void/test/unit/platform-plan.test.ts | 33 +++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/guide/self-hosted-platform.md b/docs/guide/self-hosted-platform.md index 15ff966b8..8e0e5f024 100644 --- a/docs/guide/self-hosted-platform.md +++ b/docs/guide/self-hosted-platform.md @@ -634,7 +634,7 @@ Inject the following values from protected CI secrets. Do not commit them in a w Use that installation's saved signing and encryption keys on every resume or repair that needs them. After a keyring rotation, use the [complete keyring recovery inputs](#manage-an-installation-from-another-machine). The database claim and tables remain after uninstall; use a fresh database for a different installation. -Set both email values to enable email during install or upgrade. Later upgrades reuse the recorded values. +Set both email values to enable email during install or upgrade. Later upgrades reuse the recorded values. If an email-enabled installation has no recorded values, supply both before upgrading. ```sh void platform install \ diff --git a/packages/void/src/cli/platform-plan.ts b/packages/void/src/cli/platform-plan.ts index 39793c7b5..4fad5f1b7 100644 --- a/packages/void/src/cli/platform-plan.ts +++ b/packages/void/src/cli/platform-plan.ts @@ -165,6 +165,11 @@ export async function createPlatformInstallPlan( : {}), ...(enableEmail ? { email: true } : {}), }; + if (capabilities.email && options?.includeEmailGateway !== false && !enableEmail) { + throw new Error( + 'platform: Email-enabled installations require VOID_EMAIL_SENDER_DOMAIN and VOID_EMAIL_SHARED_ZONE_ID before deploying this runtime.', + ); + } const deployment = createPlatformDeploymentManifest({ authentication: input.authentication ?? existing?.deployment.authentication, ...(Object.keys(capabilities).length > 0 ? { capabilities } : {}), diff --git a/packages/void/test/unit/platform-plan.test.ts b/packages/void/test/unit/platform-plan.test.ts index e368150ac..870212b54 100644 --- a/packages/void/test/unit/platform-plan.test.ts +++ b/packages/void/test/unit/platform-plan.test.ts @@ -126,6 +126,39 @@ describe('platform installation planning', () => { ).rejects.toThrow('shared email zone is already recorded'); }); + it('requires shared ingress identity before upgrading an email-enabled installation', async () => { + const existing = legacyInstallation(); + const enabled = { + ...existing, + deployment: createPlatformDeploymentManifest({ + ...existing.deployment, + capabilities: { ...existing.deployment.capabilities, email: true }, + }), + }; + const listWorkerNames = vi.fn(async () => []); + await expect( + createPlatformInstallPlan(client({ listWorkerNames }), input, enabled, { + includeEmailGateway: true, + }), + ).rejects.toThrow('VOID_EMAIL_SENDER_DOMAIN and VOID_EMAIL_SHARED_ZONE_ID'); + expect(listWorkerNames).not.toHaveBeenCalled(); + + const configured = await createPlatformInstallPlan( + client(), + { ...input, emailSharedZoneId: 'mail-zone-id', emailSenderDomain: 'mail.example.org' }, + enabled, + { includeEmailGateway: true }, + ); + expect(configured.deployment).toMatchObject({ + capabilities: { email: true }, + emailSharedZoneId: 'mail-zone-id', + emailSenderDomain: 'mail.example.org', + }); + expect(configured.actions).toContainEqual( + expect.objectContaining({ key: 'email-gateway-worker' }), + ); + }); + it('canonicalizes a trailing-dot sender domain before fresh-install resume checks', async () => { const configuredInput = { ...input,
Outbound (sent)Outbound recipient attempts - {sent} / {monthlyLimit ?? DEFAULT_MONTHLY_LIMIT}{' '} + {attempts} / {monthlyLimit ?? DEFAULT_MONTHLY_LIMIT}{' '} ({monthlyLimit === undefined ? 'default' : 'override'})
3