From a0044dcbdd8164bf6670fb0aa3263b129088b55e Mon Sep 17 00:00:00 2001 From: LongYinan Date: Sun, 20 Sep 2026 01:14:07 +0800 Subject: [PATCH] fix(email): address live staging acceptance failures --- docs/guide/email.md | 12 +- docs/guide/self-hosted-platform.md | 2 +- docs/reference/cli.md | 2 +- packages/platform/src/worker-config.ts | 1 + .../platform/test/unit/worker-config.test.ts | 6 + packages/void/src/cli/deploy.ts | 86 ++- packages/void/src/cli/email-cloudflare.ts | 11 +- packages/void/src/cli/email.ts | 95 ++- packages/void/src/cli/platform-setup.ts | 6 +- .../void/test/unit/cloudflare-deploy.test.ts | 185 +++-- .../test/unit/email-cli-cloudflare.test.ts | 78 +- .../void/test/unit/email-cloudflare.test.ts | 105 ++- .../void/test/unit/platform-setup.test.ts | 14 +- .../meta/design-docs/0078-email-cf-native.md | 28 +- platform/packages/api/README.md | 2 +- platform/packages/api/src/email/admission.ts | 16 +- .../packages/api/src/email/cf-customer.ts | 20 +- .../api/src/email/connection-service.ts | 31 +- .../api/src/email/send-verification.ts | 287 ++------ platform/packages/api/src/env.ts | 2 +- platform/packages/api/src/index.ts | 9 +- .../api/src/middleware/platform-access.ts | 23 +- .../api/src/provisioning/provision.ts | 2 +- platform/packages/api/src/reserved-slugs.ts | 3 +- .../packages/api/src/routes/email-confirm.ts | 12 +- platform/packages/api/src/routes/email.ts | 10 +- .../api/test/integration/api-email.test.ts | 228 +++--- .../api/test/integration/api-projects.test.ts | 6 +- .../auth-email-verification.test.ts | 6 +- .../test/integration/email-admission.test.ts | 112 +++ .../packages/api/test/integration/helpers.ts | 40 +- .../platform-access-protection.test.ts | 10 + .../api/test/unit/email-cf-customer.test.ts | 36 +- .../test/unit/email-platform-token.test.ts | 287 -------- .../api/test/unit/email-verification.test.ts | 247 +++++++ .../test/unit/platform-worker-config.test.ts | 1 + .../packages/api/test/unit/provision.test.ts | 6 +- .../api/test/unit/reserved-bindings.test.ts | 4 +- platform/packages/api/wrangler.jsonc | 37 +- platform/packages/dispatch/src/metering.ts | 4 +- platform/packages/email-gateway/src/index.ts | 139 ++++ .../email-gateway/test/unit/gateway.test.ts | 163 +++++ .../packages/email-gateway/wrangler.jsonc | 23 +- platform/packages/proxy/README.md | 6 +- platform/packages/proxy/src/body.ts | 4 - .../packages/proxy/src/email-admission.ts | 26 +- platform/packages/proxy/src/email-lease.ts | 3 +- .../proxy/src/email-provider-deadline.ts | 12 +- platform/packages/proxy/src/email.ts | 302 ++++---- platform/packages/proxy/src/index.ts | 145 +--- platform/packages/proxy/src/types.ts | 2 +- .../proxy/test/unit/email-admission.test.ts | 95 ++- .../test/unit/email-custom-domain.test.ts | 57 +- .../test/unit/email-platform-token.test.ts | 199 ----- .../proxy/test/unit/email-router.test.ts | 18 + .../packages/proxy/test/unit/email.test.ts | 685 +++--------------- .../packages/proxy/test/unit/proxy.test.ts | 2 +- platform/packages/proxy/wrangler.jsonc | 2 +- 58 files changed, 1963 insertions(+), 1992 deletions(-) delete mode 100644 platform/packages/api/test/unit/email-platform-token.test.ts create mode 100644 platform/packages/api/test/unit/email-verification.test.ts delete mode 100644 platform/packages/proxy/test/unit/email-platform-token.test.ts diff --git a/docs/guide/email.md b/docs/guide/email.md index 790609273..178b76f15 100644 --- a/docs/guide/email.md +++ b/docs/guide/email.md @@ -172,7 +172,7 @@ 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. +Provider submissions have a 30-second wait limit. Platform `sendEmail` requests are bounded to 60 seconds, including admission and recording the result; native and inbound handler submissions share a 60-second batch budget. A submission that times out returns `OUTCOME_UNKNOWN`; the provider may still accept it later. Use an idempotency key for sends you may retry: @@ -524,7 +524,9 @@ Enter (Yes is the default) applies only the `+` rows that are not ready, then th outbound sendEmail() from support@mail.acme.com ``` -On the second deploy every row reads ready: no prompt, no account call, and wrangler reports `Email Routing rules are up to date.` Answer No, and the deploy continues without email. +On the second deploy every row reads ready: no prompt, no account call, and wrangler reports `Email Routing rules are up to date.` Answer No before any setup has been committed, and the deploy continues without email. + +DNS can take a few minutes to become visible to the resolver running the deploy. If `void email setup` has already written the exact `addresses` plan but that resolver still sees no subdomain MX, Void preserves the plan and stops before the build or upload. Run `void email status --platform cloudflare`, then retry the deploy after it sees Cloudflare's MX records. Two rows live in `wrangler.jsonc` rather than in your account, and a deploy that finds every account row ready reconciles them with a plain file write, no prompt: the `addresses` array is rewritten whenever it is not the current derivation (an entry pruned since, a worker rename, a new handler), and `vars.__VOID_EMAIL_FROM` follows a changed `email.from`. Routing rules are `wrangler deploy`'s own work, so a committed `addresses` entry whose rule does not exist yet — the state right after `void email setup` — still reads ready; the address map marks it `(rule created by this deploy)`. @@ -571,7 +573,7 @@ How handlers become addresses, with `email.from` on `mail.acme.com` under the zo | `email/_default.ts` | **none** — a catch-all exists only on an apex | `*@acme.com` (the catch-all) | | `email/[user].ts`, `email/[user]+[tag].ts` (dynamic local part) | **refused** — a dynamic local part needs a catch-all | `*@acme.com` (the catch-all) | -On a subdomain, `email/_default.ts` gets no rule and never runs: mail to any other `@mail.acme.com` address bounces at Cloudflare. The checklist says so in a `!` row, and the handler is absent from the address map. +On a subdomain, `email/_default.ts` gets no rule of its own, so it cannot make arbitrary `@mail.acme.com` addresses reach the worker. Mail admitted by an explicit rule can still fall through to `_default` when no handler pattern matches—for example, bare `support@mail.acme.com` admitted by the rule for `support+anything@`. Addresses that match no Cloudflare rule bounce before the worker runs. The checklist says so in a `!` row, and the handler is absent from the address map. Inside the worker, a message reaches your handlers exactly as addressed — `support+T-42@mail.acme.com` matches `email/support+[ticket].ts` with `info.params.ticket === "T-42"` — and `setReject`, `forward` and `replyEmail` act on the real message. `replyEmail` defaults `from` to `message.to`, the address on your zone the mail was delivered to. @@ -602,9 +604,9 @@ deploy: email on mail.acme.com is not set up, and this shell cannot ask. Run `void email setup --platform cloudflare` once locally, commit wrangler.jsonc, then redeploy — deploying without email. ``` -then deploys **without** email. Pass `--require-email` to fail instead. Automatic resource provisioning is not an escape hatch: it creates D1/KV/R2/Queue/Hyperdrive resources, never a mail setup. To read the rows without deploying or being asked anything, run `void email status --platform cloudflare`. +then deploys **without** email. Pass `--require-email` to fail instead. When setup has already committed the exact subdomain `addresses` plan and only its MX records are not visible yet, every deploy stops and preserves that plan until DNS can be verified. Automatic resource provisioning is not an escape hatch: it creates D1/KV/R2/Queue/Hyperdrive resources, never a mail setup. To read the rows without deploying or being asked anything, run `void email status --platform cloudflare`. -So the CI story is: run `void email setup --platform cloudflare` once on your machine (it runs the same preflight, checklist and prompt as the first deploy, then writes `wrangler.jsonc`, without deploying), commit `wrangler.jsonc`, and let CI run `void deploy --platform cloudflare --require-email`. With the binding and `addresses` committed, every row reads ready and nothing is asked — on Workers Free too, where the committed binding is what remembers the refused sending onboarding (see [Sending](#sending)). +So the CI story is: run `void email setup --platform cloudflare` once on your machine (it runs the same preflight, checklist and prompt as the first deploy, then writes `wrangler.jsonc`, without deploying), commit `wrangler.jsonc`, and let CI run `void deploy --platform cloudflare --require-email`. Once the MX records are visible, the committed binding and `addresses` make every row read ready and nothing is asked — on Workers Free too, where the committed binding is what remembers the refused sending onboarding (see [Sending](#sending)). ### If the subdomain step is refused diff --git a/docs/guide/self-hosted-platform.md b/docs/guide/self-hosted-platform.md index 8e0e5f024..875d8d43c 100644 --- a/docs/guide/self-hosted-platform.md +++ b/docs/guide/self-hosted-platform.md @@ -134,7 +134,7 @@ 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. -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. +Enabling email lets administrators [register email domains for projects](./platform-administration.md#registering-email-domains-for-projects) and lets projects register destination addresses through the runtime token. That needs **Email Routing Addresses: Edit** and **Email Sending: Edit** on the account, plus **Zone: Read**, **Zone Settings: Edit** and **Email Routing Rules: Edit** on the zones that will carry mail; the token link preselects them when email is enabled. Email Sending onboarding itself needs Workers Paid on the account. 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. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 4ce50e703..bb7016652 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -912,7 +912,7 @@ Provisioning reuses known resource IDs and writes newly resolved IDs into `wrang Existing remote secrets are preserved. Void also preserves or creates `BETTER_AUTH_SECRET` for auth apps. -**Email.** When the app uses email (`sendEmail()` or `email/` handlers) and `void.json` has `email.from`, the deploy reads the state of that address's zone before the build — session scopes, zone, MX records, Email Routing, subaddressing, routing rules, Email Sending, and what `wrangler.jsonc` holds — prints a checklist of what it would change in your account, and asks once (default Yes). On Yes it enables what is missing, writes `send_email: [{ "name": "SEND_EMAIL" }]`, the `__VOID_EMAIL_FROM` var and the `addresses` array into `wrangler.jsonc`, and lets wrangler create the routing rules when the activated version's triggers are synchronized; the deploy ends with the address map. A deploy with nothing left to set up asks nothing. Without `email.from` the deploy prints `add "email": { "from": "you@mail.acme.com" } to void.json` and continues without email. Non-interactive runs (CI, or stdin/stdout not a terminal) never prompt: they print the checklist plus `Run void email setup --platform cloudflare once locally, commit wrangler.jsonc, then redeploy` and deploy without email (or with the setup `wrangler.jsonc` already carries, when the binding is committed; a committed `addresses` array whose routing is off is removed first, since wrangler's plan on it would fail after the upload) — unless `--require-email` is passed, which fails instead. A deploy whose account rows all read ready reconciles the two config rows — `addresses` against the current derivation and `vars.__VOID_EMAIL_FROM` against `email.from` — with a plain file write and no prompt. See [Your own Cloudflare account](../guide/email.md#your-own-cloudflare-account) for the whole flow, including the subdomain-vs-apex rule and what stays manual. +**Email.** When the app uses email (`sendEmail()` or `email/` handlers) and `void.json` has `email.from`, the deploy reads the state of that address's zone before the build — session scopes, zone, MX records, Email Routing, subaddressing, routing rules, Email Sending, and what `wrangler.jsonc` holds — prints a checklist of what it would change in your account, and asks once (default Yes). On Yes it enables what is missing, writes `send_email: [{ "name": "SEND_EMAIL" }]`, the `__VOID_EMAIL_FROM` var and the `addresses` array into `wrangler.jsonc`, and lets wrangler create the routing rules when the activated version's triggers are synchronized; the deploy ends with the address map. A deploy with nothing left to set up asks nothing. Without `email.from` the deploy prints `add "email": { "from": "you@mail.acme.com" } to void.json` and continues without email. Non-interactive runs (CI, or stdin/stdout not a terminal) never prompt: they print the checklist plus `Run void email setup --platform cloudflare once locally, commit wrangler.jsonc, then redeploy` and deploy without email (or with the setup `wrangler.jsonc` already carries, when the binding is committed) — unless `--require-email` is passed, which fails instead. If setup has committed the exact subdomain `addresses` plan but the deploy's resolver still sees no MX records, Void preserves the plan and stops before build or upload until DNS can be verified. A deploy whose account rows all read ready reconciles the two config rows — `addresses` against the current derivation and `vars.__VOID_EMAIL_FROM` against `email.from` — with a plain file write and no prompt. See [Your own Cloudflare account](../guide/email.md#your-own-cloudflare-account) for the whole flow, including the subdomain-vs-apex rule and what stays manual. See the [Cloudflare guide](../integrations/cloudflare.md#deploy-to-your-own-cloudflare-account) for the complete deployment sequence, first-deploy exceptions, secret precedence, and recovery behavior. diff --git a/packages/platform/src/worker-config.ts b/packages/platform/src/worker-config.ts index 495db41b0..a422d69d9 100644 --- a/packages/platform/src/worker-config.ts +++ b/packages/platform/src/worker-config.ts @@ -108,6 +108,7 @@ export function createPlatformWorkerConfigs(input: { placement: { mode: 'smart' }, hyperdrive: [{ binding: 'HYPERDRIVE', id: resources.hyperdrive }], kv_namespaces: kv, + ...(deployment.capabilities.email ? { send_email: [{ name: 'EMAIL' }] } : {}), r2_buckets: r2, dispatch_namespaces: dispatchNamespace, durable_objects: { diff --git a/packages/platform/test/unit/worker-config.test.ts b/packages/platform/test/unit/worker-config.test.ts index c31ac8623..1425b7b3b 100644 --- a/packages/platform/test/unit/worker-config.test.ts +++ b/packages/platform/test/unit/worker-config.test.ts @@ -45,6 +45,7 @@ describe('platform usage queue bindings', () => { application: { baseDomain: 'apps.example.com', zoneName: 'example.com' }, emailSharedZoneId: 'mail-zone-id', emailSenderDomain: 'mail.example.org', + authentication: { accessProtection: true }, capabilities: { email: true }, displayName: 'Example', installationSlug: 'example', @@ -85,8 +86,12 @@ describe('platform usage queue bindings', () => { 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.api).toHaveProperty('send_email', [{ name: 'EMAIL' }]); expect(configs.emailGateway).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]); expect(configs.proxy).toHaveProperty('send_email', [{ name: 'SEND_EMAIL' }]); + expect(configs.api.workers_dev).toBe(false); + expect(configs.proxy.workers_dev).toBe(false); + expect(configs.emailGateway.workers_dev).toBe(true); expect(configs.api.compatibility_flags).toContain('global_fetch_strictly_public'); expect(configs.api.vars).toHaveProperty( 'EMAIL_GATEWAY_ORIGIN', @@ -167,6 +172,7 @@ describe('platform usage queue bindings', () => { expect(configs.proxy.services).toEqual([ { binding: 'API', service: deployment.resources.apiWorker }, ]); + expect(configs.api).not.toHaveProperty('send_email'); expect(configs.proxy).not.toHaveProperty('send_email'); expect(configs.emailGateway).not.toHaveProperty('send_email'); expect(Object.keys(configs).sort()).toEqual([ diff --git a/packages/void/src/cli/deploy.ts b/packages/void/src/cli/deploy.ts index 1d339e316..71f36d2e9 100644 --- a/packages/void/src/cli/deploy.ts +++ b/packages/void/src/cli/deploy.ts @@ -3714,19 +3714,58 @@ interface CloudflareEmailStepResult { satisfied: boolean; /** True when the root wrangler config was rewritten — the caller re-parses `rootConfig`. */ configWritten: boolean; + /** Stop before project code, the build, or upload; used for an ambiguous DNS handoff. */ + abortDeploy?: true; /** The post-deploy address map, when the worker ships with the binding; `null` otherwise. */ map: EmailAddressMapInput | null; } +/** + * Immediately after setup, the local resolver can retain ENODATA while Cloudflare's public DNS + * already serves the new subdomain MX. When the committed config is exactly setup's plan and + * every other inbound prerequisite is still ready, DNS is ambiguous: deleting `addresses` + * destroys the handoff, while deploying it could fail after upload if routing is genuinely off. + */ +function isCommittedSubdomainPlanWaitingForDns( + pre: EmailPreflight, + rootConfig: Record, +): boolean { + if ( + pre.mode !== 'subdomain' || + (pre.domainMx.state !== 'empty' && pre.domainMx.state !== 'unknown') || + pre.routing.enabled !== true || + pre.subaddressing.state !== 'on' || + pre.binding.state !== 'present' || + pre.sender.state !== 'ready' || + pre.addressesOwnership.state !== 'mine' || + pre.addressesStale || + pre.rules.state === 'unknown' || + pre.rules.foreign.length > 0 || + !Array.isArray(rootConfig.addresses) || + rootConfig.addresses.length === 0 + ) { + return false; + } + + const allBlockers = pre.blockers.filter((blocker) => blocker.scope === 'all'); + if (pre.domainMx.state === 'empty') { + return allBlockers.length === 0; + } + // `preflightEmail` always adds one all-scope blocker for an unknown domain MX. Exactly one + // therefore means DNS is the only such blocker, without coupling this gate to rendered prose. + return allBlockers.length === 1; +} + /** * Step 3b-ii — Mode B email on the developer's own account (design doc 0078, "One keystroke"). * Preflight is read-only; the checklist is shown; ONE `confirm` (default Yes) authorizes the * apply, which runs only the rows not ready and returns the root-config patch this writes. - * Every branch that cannot finish prints why and returns `satisfied: false` so the deploy - * continues (never a deploy failure on its own — `--require-email` is the caller's call), - * WITH the email setup the config already carries when the binding is committed, and - * without email otherwise. No output of this step ever contains the session bearer: the - * module borrows it through `getSessionBearer` inside its own closures and drops it. + * Most branches that cannot finish return `satisfied: false`, leaving `--require-email` to + * decide whether deployment continues. One ambiguous handoff fails closed for every deploy: + * an exact committed subdomain plan whose new MX is still empty or unreadable. It is preserved, + * and the caller stops before build/upload until DNS can be verified. No output of this step + * ever contains the session bearer: the module borrows it through `getSessionBearer` inside its + * own closures and drops it. */ async function runCloudflareEmailStep( input: CloudflareEmailStepInput, @@ -3862,13 +3901,31 @@ async function runCloudflareEmailStep( // The checklist carries the `✘` rows, so a blocked run explains itself before the warn line. log.message(renderEmailChecklist(pre)); + if (isCommittedSubdomainPlanWaitingForDns(pre, rootConfig)) { + const dnsState = + pre.domainMx.state === 'empty' + ? 'this resolver sees no MX records yet' + : 'the MX lookup failed'; + log.error( + [ + `deploy: cannot verify Email Routing on ${pre.domain} because ${dnsState}.`, + `The existing addresses plan in ${configName} is preserved. DNS may still be propagating after \`void email setup\`; run \`void email status --platform cloudflare\` and retry the deploy when this resolver sees Cloudflare's MX records.`, + 'Nothing was built or uploaded.', + ].join('\n'), + ); + return { + ...without, + abortDeploy: true, + map: mapFor(existingAddresses(rootConfig, pre), pre.sending.state === 'ready'), + }; + } // The three exits below leave the account alone. What the worker then ships is whatever // the config already carries — so when the binding is committed the deploy is WITH the - // existing setup (map printed, wording says so), and a committed `addresses` array whose - // routing preflight found off is withdrawn first: wrangler's plan on it 400s (`2062`) - // AFTER the upload, on every deploy, until the key goes (0078: "deleted, never `[]`, - // when a later preflight finds routing off"). Only Void's own array is touched (decision - // 13); deleting the KEY changes no rule — wrangler skips the plan on `undefined`. + // existing setup (map printed, wording says so). A committed `addresses` array whose routing + // is verifiably off is withdrawn first: wrangler's plan on it 400s (`2062`) AFTER the upload, + // on every deploy, until the key goes (0078: "deleted, never `[]`, when a later preflight finds + // routing off"). The ambiguous post-setup DNS case returned above instead. Only Void's own + // array is touched (decision 13); deleting the KEY changes no rule — wrangler skips the plan. const shipsBinding = pre.binding.state === 'present'; const leaveAccount = (reason: string): CloudflareEmailStepResult => { let configWritten = false; @@ -4332,9 +4389,9 @@ export async function runCloudflareDeploy( // code has run when a credentialed call is made — and so `rootConfig` can simply be RE-PARSED // after the write: the post-probe laundering guard (the full-config `deepEqual` after 3c) then // sees `send_email` / `addresses` / `vars` as the pre-probe baseline and needs no exception. - // Only `needsEmail` apps pay for it. The step never fails the deploy on its own; - // `--require-email` turns every "deploying without email" branch into an exit BEFORE anything - // is built or uploaded. + // Only `needsEmail` apps pay for it. The step stops every deploy for an ambiguous committed + // subdomain plan waiting on DNS; otherwise `--require-email` turns every "deploying without + // email" branch into an exit BEFORE anything is built or uploaded. let emailMap: EmailAddressMapInput | null = null; if (needsEmail) { if (!assertUploaderStillPinned()) { @@ -4360,6 +4417,9 @@ export async function runCloudflareDeploy( fetchImpl: deps.emailFetch ?? fetch, dns: deps.emailDns ?? (await createNodeEmailDns()), }); + if (email.abortDeploy) { + return exit(1); + } if (options.requireEmail && !email.satisfied) { log.error( [ diff --git a/packages/void/src/cli/email-cloudflare.ts b/packages/void/src/cli/email-cloudflare.ts index 4c052bbb5..d46048f5c 100644 --- a/packages/void/src/cli/email-cloudflare.ts +++ b/packages/void/src/cli/email-cloudflare.ts @@ -914,8 +914,8 @@ export async function preflightEmail(inputs: EmailCloudflareInputs): Promise never; } +interface EmailWranglerConfigContext { + path: string; + cleanup: () => void; +} + +/** + * Wrangler discovers config files by walking parent directories. A standalone email command in + * an app with no root config must still run in an explicit empty config context, otherwise an + * unrelated ancestor config can select the wrong account. The real project path remains separate: + * setup writes there only after it succeeds, while status leaves the project untouched. + */ +function createEmailWranglerConfigContext(configPath: string): EmailWranglerConfigContext { + if (existsSync(configPath)) { + return { path: configPath, cleanup: () => {} }; + } + + const directory = mkdtempSync(join(tmpdir(), 'void-email-wrangler-')); + const path = join(directory, 'wrangler.jsonc'); + try { + writeFileSync(path, '{}\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 }); + } catch (error) { + rmSync(directory, { recursive: true, force: true }); + throw error; + } + return { + path, + cleanup: () => rmSync(directory, { recursive: true, force: true }), + }; +} + /** * `void email setup --platform cloudflare` and `void email status --platform cloudflare`. * @@ -1048,27 +1081,65 @@ export async function runEmailCloudflareCommand( args: EmailArgs, deps: EmailCloudflareCommandDeps = {}, ): Promise { - const exit = deps.exit ?? ((code: number): never => process.exit(code)); - const print = deps.print ?? ((block: string): void => log.message(block)); - const fail = (message: string): never => { - log.error(message); - return exit(1); - }; - - // 1. Inputs from the local project: `email.from` is the ONLY domain input (decision 9). + const rawExit = deps.exit ?? ((code: number): never => process.exit(code)); + // Keep project validation ahead of Cloudflare-config discovery, including its legacy-TOML + // refusal. No config context is needed until the command is ready to make account reads. const voidConfig = readConfig(root); const from = voidConfig.email?.from; if (!from) { - return fail( + log.error( 'email: no sender configured. Add "email": { "from": "you@mail.acme.com" } to void.json — its host is the domain email is set up on.', ); + return rawExit(1); } const paths = readProjectPaths(root); const handlers = scanEmailHandlersSync(paths.sourceRoot); + const configPath = discoverRootWranglerConfig(root); + const wranglerConfig = createEmailWranglerConfigContext(configPath); + try { + return await runEmailCloudflareCommandInConfig( + root, + args, + { from, handlers }, + configPath, + wranglerConfig.path, + { + ...deps, + exit: (code: number): never => { + wranglerConfig.cleanup(); + return rawExit(code); + }, + }, + ); + } finally { + wranglerConfig.cleanup(); + } +} + +async function runEmailCloudflareCommandInConfig( + root: string, + args: EmailArgs, + project: { + from: string; + handlers: ReturnType; + }, + configPath: string, + wranglerConfigPath: string, + deps: EmailCloudflareCommandDeps, +): Promise { + const exit = deps.exit ?? ((code: number): never => process.exit(code)); + const print = deps.print ?? ((block: string): void => log.message(block)); + const fail = (message: string): never => { + log.error(message); + return exit(1); + }; + + // 1. Inputs from the local project: `email.from` is the ONLY domain input (decision 9). + const { from, handlers } = project; + // 2. The same pinned transport + account + worker name as `void deploy --platform // cloudflare`, so every wrangler child here consults the account the deploy will. - const configPath = discoverRootWranglerConfig(root); const rootConfig = parseRootWranglerConfig(configPath); await loadProvisionModule(); let apiBaseUrl: string; @@ -1094,7 +1165,7 @@ export async function runEmailCloudflareCommand( // The same bearer bridge the deploy's step 3b-ii uses: `wrangler auth token --json` on the // pinned runner, WRANGLER_WRITE_LOGS=false so the token never reaches wrangler's on-disk log. const getSessionBearer = - deps.getSessionBearer ?? (() => runWranglerAuthToken(runWrangler, configPath)); + deps.getSessionBearer ?? (() => runWranglerAuthToken(runWrangler, wranglerConfigPath)); const sendEmail = rootConfig.send_email; const inputs: EmailCloudflareInputs = { handlers, @@ -1108,7 +1179,7 @@ export async function runEmailCloudflareCommand( ? (rootConfig.vars as Record) : null, configConflicts: findEmailConfigConflicts(rootConfig), - wranglerArgs: ['-c', configPath, '--env='], + wranglerArgs: ['-c', wranglerConfigPath, '--env='], apiBaseUrl, runWrangler, getSessionBearer, diff --git a/packages/void/src/cli/platform-setup.ts b/packages/void/src/cli/platform-setup.ts index a5076b857..3accf5175 100644 --- a/packages/void/src/cli/platform-setup.ts +++ b/packages/void/src/cli/platform-setup.ts @@ -88,12 +88,12 @@ export function platformSetupPages(plan: PlatformInstallPlan): { ...(plan.deployment.capabilities.customDomains ? [{ key: 'ssl_and_certificates', type: 'edit' }] : []), - // Administrator-registered email domains run the Email Routing / Email - // Sending setup on this token against zones in this account. + // Email domain setup and destination consent use this token. ...(plan.deployment.capabilities.email ? [ { key: 'zone', type: 'read' }, { key: 'zone_settings', type: 'edit' }, + { key: 'email_routing_address', type: 'edit' }, { key: 'email_routing_rule', type: 'edit' }, { key: 'email_sending', type: 'edit' }, ] @@ -121,7 +121,7 @@ export function platformSetupPages(plan: PlatformInstallPlan): { : []), ...(plan.deployment.capabilities.email ? [ - 'Administrator-registered email domains need Zone: Read, Zone Settings: Edit and Email Routing Rules: Edit on the mail zones, and Email Sending: Edit.', + 'Email-enabled installations need Email Routing Addresses: Edit and Email Sending: Edit on the account, plus Zone: Read, Zone Settings: Edit and Email Routing Rules: Edit on the mail zones.', ] : []), 'If the form differs, match the permissions above. Create the token, then paste it here.', diff --git a/packages/void/test/unit/cloudflare-deploy.test.ts b/packages/void/test/unit/cloudflare-deploy.test.ts index 65b9c5162..c3792283c 100644 --- a/packages/void/test/unit/cloudflare-deploy.test.ts +++ b/packages/void/test/unit/cloudflare-deploy.test.ts @@ -35,6 +35,7 @@ import { type EmittedWorkerVarsResult, } from '../../src/cli/deploy.ts'; import { SENDING_FREE_PLAN_HINT, type EmailDns } from '../../src/cli/email-cloudflare.ts'; +import { runEmailCloudflareCommand } from '../../src/cli/email.ts'; import { resolveEnvSchemaFactsViaSubprocess, validateEmittedVarsViaSubprocess, @@ -9831,6 +9832,90 @@ describe('runCloudflareDeploy — Mode B email step (3b-ii)', () => { }, }; + it('preserves setup output and stops before build while the local resolver still sees no subdomain MX', async () => { + const root = emailProject(); + const setupSpawns: Array = []; + const setupTrace: Array = []; + const setupFetchCalls: Array = []; + + await runEmailCloudflareCommand( + root, + { subcommand: 'setup', platform: 'cloudflare' }, + { + runWrangler: emailRunner({}, setupSpawns, setupTrace), + fetchImpl: emailFetch(setupFetchCalls), + dns: emailDns(), + isInteractive: true, + confirm: async () => true, + print: () => {}, + exit: (code): never => { + throw new ExitError(code); + }, + }, + ); + + expect(readRootConfig(root)).toMatchObject({ + send_email: [{ name: 'SEND_EMAIL' }], + addresses: ['support@mail.acme.com'], + vars: { __VOID_EMAIL_FROM: 'noreply@mail.acme.com' }, + }); + expect( + setupFetchCalls.filter((call) => call.method !== 'GET').map((call) => call.method), + ).toEqual(['POST', 'PATCH']); + const afterSetup = readFileSync(join(root, 'wrangler.jsonc'), 'utf8'); + + const baseDns = emailDns(); + const dnsCases: Array<{ name: string; dns: EmailDns }> = [ + { name: 'ENODATA', dns: emailDns() }, + { + name: 'lookup failure', + dns: { + ...baseDns, + resolveMx: async (name) => { + if (name === 'mail.acme.com') { + throw new Error('SERVFAIL'); + } + return baseDns.resolveMx(name); + }, + }, + }, + ]; + for (const dnsCase of dnsCases) { + // The setup calls returned success, but this process still cannot verify the new MX. + const { deps, spawns, exitCalls, trace } = emailHarness({ + subaddressing: true, + dns: dnsCase.dns, + isCI: true, + }); + const output = captureOutput(); + try { + await expect( + runCloudflareDeploy(root, { backend: 'cloudflare' }, silentCliLog, deps), + ).rejects.toBeInstanceOf(ExitError); + } finally { + output.restore(); + } + + expect(exitCalls, dnsCase.name).toEqual([1]); + expect(readFileSync(join(root, 'wrangler.jsonc'), 'utf8'), dnsCase.name).toBe(afterSetup); + expect(trace, dnsCase.name).not.toContain('probe'); + expect(trace, dnsCase.name).not.toContain('build'); + expect( + spawns.some((spawn) => spawn.args[0] === 'deploy'), + dnsCase.name, + ).toBe(false); + const printed = output.lines.join('\n'); + expect(printed, dnsCase.name).toContain('cannot verify Email Routing on mail.acme.com'); + expect(printed, dnsCase.name).toContain( + 'existing addresses plan in wrangler.jsonc is preserved', + ); + expect(printed, dnsCase.name).toContain( + 'DNS may still be propagating after `void email setup`', + ); + expect(printed, dnsCase.name).toContain('Nothing was built or uploaded'); + } + }); + it('an API-token session (CLOUDFLARE_API_TOKEN) in CI with a committed config: --require-email passes, no prompt, map printed', async () => { // The CI credential. wrangler reports no `tokenPermissions` for it (they come from the // stored login file), so gating on them would fail every CI deploy before the build. @@ -10140,72 +10225,50 @@ describe('runCloudflareDeploy — Mode B email step (3b-ii)', () => { expect(printed).toContain('outbound sendEmail() from hello@mail.acme.com'); }); - it('a committed `addresses` array is withdrawn when routing is off, on the CI, declined and blocked exits; the worker ships with its binding', async () => { + it('a committed `addresses` array is still withdrawn when a separate blocker proves setup cannot proceed', async () => { // Left in place, wrangler's plan on it 400s (2062) AFTER the upload, on every deploy. // Deleting the KEY changes no rule (wrangler skips the plan on `undefined`). - const cases: Array<{ - name: string; - options: Parameters[0]; - wantConfirm: boolean; - }> = [ - { - name: 'CI', - options: { - isCI: true, - confirm: async () => { - throw new Error('confirm must not be called in CI'); - }, - }, - wantConfirm: false, - }, - { name: 'declined', options: { confirm: async () => false }, wantConfirm: false }, - { - name: 'blocked (apex unlocked)', - options: { - runner: { 'email routing settings acme.com': routingSettings('acme.com', 'unlocked') }, + const root = emailProject(COMMITTED_EMAIL); + const baseDns = emailDns(); + // Even with an unreadable MX, `unlocked` is independent evidence that this is not only a + // propagating DNS answer, so the preservation exception must not hide the stable blocker. + const { deps, spawns, fetchCalls, confirms, exitCalls, trace } = emailHarness({ + runner: { 'email routing settings acme.com': routingSettings('acme.com', 'unlocked') }, + dns: { + ...baseDns, + resolveMx: async (name) => { + if (name === 'mail.acme.com') { + throw new Error('SERVFAIL'); + } + return baseDns.resolveMx(name); }, - wantConfirm: false, }, - ]; - for (const c of cases) { - const root = emailProject(COMMITTED_EMAIL); - // The default harness DNS has no MX on mail.acme.com: routing reads `pending`. - const { deps, spawns, fetchCalls, confirms, exitCalls, trace } = emailHarness(c.options); - const output = captureOutput(); - try { - await runCloudflareDeploy(root, { backend: 'cloudflare' }, silentCliLog, deps); - } finally { - output.restore(); - } - expect(exitCalls, c.name).toEqual([]); - expect(confirms.length > 0, c.name).toBe(c.wantConfirm); - expect( - fetchCalls.filter((f) => f.method !== 'GET'), - c.name, - ).toEqual([]); - expect( - spawns.some((s) => s.args[0] === 'email' && s.args[2] === 'enable'), - c.name, - ).toBe(false); - const after = readRootConfig(root); - expect(after.addresses, c.name).toBeUndefined(); - expect(after.send_email, c.name).toEqual(COMMITTED_EMAIL.send_email); - expect(after.vars, c.name).toEqual(COMMITTED_EMAIL.vars); - expect(trace, c.name).toContain('build'); - expect( - spawns.some((s) => s.args[0] === 'deploy'), - c.name, - ).toBe(true); - const printed = output.lines.join('\n'); - expect(printed, c.name).toContain('addresses removed from wrangler.jsonc'); - expect(printed, c.name).toContain('support@mail.acme.com'); - // The binding is committed, so the deploy is WITH email — the wording and the map say so. - expect(printed, c.name).not.toContain('deploying without email'); - expect(printed, c.name).toContain( - 'deploying with the email setup wrangler.jsonc already carries', - ); - expect(printed, c.name).toContain('outbound sendEmail() from noreply@mail.acme.com'); + }); + const output = captureOutput(); + try { + await runCloudflareDeploy(root, { backend: 'cloudflare' }, silentCliLog, deps); + } finally { + output.restore(); } + expect(exitCalls).toEqual([]); + expect(confirms).toEqual([]); + expect(fetchCalls.filter((call) => call.method !== 'GET')).toEqual([]); + expect(spawns.some((spawn) => spawn.args[0] === 'email' && spawn.args[2] === 'enable')).toBe( + false, + ); + const after = readRootConfig(root); + expect(after.addresses).toBeUndefined(); + expect(after.send_email).toEqual(COMMITTED_EMAIL.send_email); + expect(after.vars).toEqual(COMMITTED_EMAIL.vars); + expect(trace).toContain('build'); + expect(spawns.some((spawn) => spawn.args[0] === 'deploy')).toBe(true); + const printed = output.lines.join('\n'); + expect(printed).toContain('addresses removed from wrangler.jsonc'); + expect(printed).toContain('support@mail.acme.com'); + // The binding is committed, so the deploy is WITH email — the wording and the map say so. + expect(printed).not.toContain('deploying without email'); + expect(printed).toContain('deploying with the email setup wrangler.jsonc already carries'); + expect(printed).toContain('outbound sendEmail() from noreply@mail.acme.com'); }); it('a committed `addresses` array Void did not derive stays untouched when routing is off too (decision 13)', async () => { diff --git a/packages/void/test/unit/email-cli-cloudflare.test.ts b/packages/void/test/unit/email-cli-cloudflare.test.ts index a98fea36f..7ea3f9a25 100644 --- a/packages/void/test/unit/email-cli-cloudflare.test.ts +++ b/packages/void/test/unit/email-cli-cloudflare.test.ts @@ -1,4 +1,4 @@ -import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { log } from '@clack/prompts'; import { join } from 'pathslash'; @@ -73,9 +73,11 @@ type FetchCall = { url: string; method: string; headers: Record; function fakeRunner(table: Record, calls: Array) { return (args: Array, opts: { capture: boolean }): EmailWranglerRunResult => { calls.push({ args: [...args], capture: opts.capture }); - // The command appends `-c --env=` to every call; key the table on the - // command words and assert the suffix separately. - const key = args.slice(0, args.indexOf('-c') < 0 ? args.length : args.indexOf('-c')).join(' '); + // Key the table on command words; config context is asserted separately. + const configIndex = args.indexOf('-c'); + const envIndex = args.indexOf('--env='); + const suffixIndex = configIndex >= 0 ? configIndex : envIndex >= 0 ? envIndex : args.length; + const key = args.slice(0, suffixIndex).join(' '); const hit = table[key]; if (!hit) { throw new Error(`unexpected wrangler call: ${args.join(' ')}`); @@ -794,6 +796,74 @@ describe('void email setup --platform cloudflare', () => { }); describe('void email status --platform cloudflare', () => { + it('fences off an ancestor config without creating a root config, then removes the temporary config', async () => { + const parent = mkdtempSync(join(tmpdir(), 'void-email-cli-parent-')); + roots.push(parent); + const parentConfigPath = join(parent, 'wrangler.jsonc'); + const parentConfig = '{ "account_id": "wrong-account", "name": "wrong-worker" }\n'; + writeFileSync(parentConfigPath, parentConfig); + const root = join(parent, 'app'); + mkdirSync(join(root, 'email'), { recursive: true }); + writeFileSync( + join(root, 'void.json'), + JSON.stringify({ email: { from: 'noreply@mail.acme.com' } }), + ); + writeFileSync(join(root, 'email', 'support+[ticket].ts'), 'export default () => {};\n'); + const configPath = join(root, 'wrangler.jsonc'); + const { deps, calls, fetchCalls } = transcriptDeps({ + runnerTable: { + 'auth token --json': { + status: 0, + stdout: JSON.stringify({ type: 'oauth', token: BEARER }), + stderr: '', + }, + }, + }); + const { getSessionBearer: _injectedBearer, ...defaultBearerDeps } = deps; + const runWrangler = defaultBearerDeps.runWrangler!; + const temporaryConfigPaths: Array = []; + defaultBearerDeps.runWrangler = (args, options) => { + const configIndex = args.indexOf('-c'); + expect(configIndex).toBeGreaterThanOrEqual(0); + const temporaryConfigPath = args[configIndex + 1] as string; + temporaryConfigPaths.push(temporaryConfigPath); + expect(temporaryConfigPath).not.toBe(parentConfigPath); + expect(temporaryConfigPath).not.toBe(configPath); + expect(readFileSync(temporaryConfigPath, 'utf8')).toBe('{}\n'); + return runWrangler(args, options); + }; + const savedAccountId = process.env.CLOUDFLARE_ACCOUNT_ID; + process.env.CLOUDFLARE_ACCOUNT_ID = ACCOUNT; + + try { + const code = await run(root, 'status', defaultBearerDeps); + + expect(code).toBe(1); + expect(existsSync(configPath)).toBe(false); + expect(readFileSync(parentConfigPath, 'utf8')).toBe(parentConfig); + expect(fetchCalls.every((call) => call.method === 'GET')).toBe(true); + expect(temporaryConfigPaths.length).toBeGreaterThan(0); + expect(new Set(temporaryConfigPaths).size).toBe(1); + expect(existsSync(temporaryConfigPaths[0] as string)).toBe(false); + expect(calls.every((call) => call.args.includes('-c'))).toBe(true); + expect(calls.every((call) => call.args.at(-1) === '--env=')).toBe(true); + expect(calls.find((call) => call.args[0] === 'auth')?.args).toEqual([ + 'auth', + 'token', + '--json', + '-c', + temporaryConfigPaths[0], + '--env=', + ]); + } finally { + if (savedAccountId === undefined) { + delete process.env.CLOUDFLARE_ACCOUNT_ID; + } else { + process.env.CLOUDFLARE_ACCOUNT_ID = savedAccountId; + } + } + }); + it('not ready: status rows + address map, exit 1, read-only', async () => { const root = makeProject(); roots.push(root); diff --git a/packages/void/test/unit/email-cloudflare.test.ts b/packages/void/test/unit/email-cloudflare.test.ts index 5076d214d..0902100a1 100644 --- a/packages/void/test/unit/email-cloudflare.test.ts +++ b/packages/void/test/unit/email-cloudflare.test.ts @@ -945,11 +945,14 @@ describe('preflightEmail', () => { expect(pre.blockers.map((b) => b.scope)).toEqual(['all']); }); - it('blocks on routing status unlocked / misconfigured — never re-locks', async () => { + it('keeps apex-mode routing status unlocked / misconfigured blocked — never re-locks', async () => { for (const status of ['unlocked', 'misconfigured', 'misconfigured_locked']) { const { inputs } = transcriptInputs({ + from: 'noreply@acme.com', + dns: fakeDns({}), runnerTable: { 'email routing settings acme.com': routingSettings('acme.com', true, status, ZONE_ID), + 'email sending settings acme.com': sendingNotFound('acme.com'), }, }); const pre = await preflightEmail(inputs); @@ -961,6 +964,63 @@ describe('preflightEmail', () => { } }); + it('keeps an explicitly unlocked apex blocked for subdomain setup', async () => { + const { inputs } = transcriptInputs({ + runnerTable: { + 'email routing settings acme.com': routingSettings('acme.com', true, 'unlocked', ZONE_ID), + }, + }); + const pre = await preflightEmail(inputs); + expect(pre.blockers).toContainEqual({ + scope: 'all', + message: + 'Email Routing on acme.com is unlocked — fix it in the Cloudflare dashboard; Void never re-locks records you unlocked', + }); + }); + + it('uses the subdomain MX as authoritative when apex routing is misconfigured', async () => { + const { inputs } = readyAccount({ + runnerTable: { + 'email routing settings acme.com': routingSettings( + 'acme.com', + true, + 'misconfigured', + ZONE_ID, + ), + }, + }); + const pre = await preflightEmail(inputs); + expect(pre.mode).toBe('subdomain'); + expect(pre.routing).toEqual({ + state: 'ready', + status: 'misconfigured', + enabled: true, + }); + expect(pre.blockers).toEqual([]); + expect(pre.ready).toBe(true); + }); + + it('still blocks foreign MX on the subdomain when apex routing is misconfigured', async () => { + const { inputs } = transcriptInputs({ + runnerTable: { + 'email routing settings acme.com': routingSettings( + 'acme.com', + true, + 'misconfigured', + ZONE_ID, + ), + }, + dns: fakeDns({ mx: { 'mail.acme.com': ['mx.example.net'] } }), + }); + const pre = await preflightEmail(inputs); + expect(pre.routing.state).toBe('pending'); + expect(pre.blockers).toContainEqual({ + scope: 'all', + message: + 'mail.acme.com already receives mail (mx.example.net). Void never enables routing over live mail.', + }); + }); + it('refuses sending onboarding when _dmarc / cf-bounce TXT already exist (sending-scoped)', async () => { const { inputs } = transcriptInputs({ dns: fakeDns({ @@ -1448,6 +1508,49 @@ describe('applyEmailSetup', () => { } }); + it('first subdomain setup proceeds when only the apex routing status is misconfigured', async () => { + const calls: Array = []; + const fetchCalls: Array = []; + const { inputs } = transcriptInputs({ + calls, + fetchCalls, + runnerTable: { + 'email routing settings acme.com': routingSettings( + 'acme.com', + true, + 'misconfigured', + ZONE_ID, + ), + 'email sending enable mail.acme.com': sendingEnabled('mail.acme.com'), + }, + fetchTable: { + [ROUTING_DNS_POST]: () => + jsonResponse(200, { success: true, result: { name: 'mail.acme.com' } }), + [ROUTING_PATCH]: () => + jsonResponse(200, { success: true, result: { support_subaddress: true } }), + }, + }); + const pre = await preflightEmail(inputs); + expect(pre.routing).toEqual({ + state: 'pending', + status: 'misconfigured', + enabled: true, + }); + expect(pre.blockers).toEqual([]); + + calls.length = 0; + fetchCalls.length = 0; + const out = await applyEmailSetup(pre, inputs); + expect(out.routingReady).toBe(true); + expect(out.inboundReady).toBe(true); + expect( + fetchCalls.map((call) => `${call.method} ${call.url.slice(call.url.indexOf('/zones'))}`), + ).toEqual([ROUTING_DNS_POST, ROUTING_PATCH]); + expect(calls.map((call) => call.args)).toEqual([ + ['email', 'sending', 'enable', 'mail.acme.com'], + ]); + }); + it('apex path: `wrangler email routing enable `, then the subaddressing PATCH through the bearer', async () => { const calls: Array = []; const fetchCalls: Array = []; diff --git a/packages/void/test/unit/platform-setup.test.ts b/packages/void/test/unit/platform-setup.test.ts index aedd6806e..7e798db33 100644 --- a/packages/void/test/unit/platform-setup.test.ts +++ b/packages/void/test/unit/platform-setup.test.ts @@ -146,14 +146,26 @@ describe('platform credential setup links', () => { JSON.parse( new URL(platformSetupPages(input).runtime.url).searchParams.get('permissionGroupKeys')!, ) as Array<{ key: string; type: string }>; - const emailKeys = ['zone', 'zone_settings', 'email_routing_rule', 'email_sending']; + const emailKeys = [ + 'zone', + 'zone_settings', + 'email_routing_address', + 'email_routing_rule', + 'email_sending', + ]; expect(permissions(withEmail).map((permission) => permission.key)).toEqual( expect.arrayContaining(emailKeys), ); expect(permissions(original).some((permission) => emailKeys.includes(permission.key))).toBe( false, ); + expect(platformSetupPages(withEmail).runtime.instructions).toContain( + 'Email Routing Addresses: Edit', + ); expect(platformSetupPages(withEmail).runtime.instructions).toContain('Email Sending: Edit'); + expect(platformSetupPages(original).runtime.instructions).not.toContain( + 'Email Routing Addresses', + ); expect(platformSetupPages(original).runtime.instructions).not.toContain('Email Sending'); }); it('shows the final callback in previews as well as interactive setup', () => { diff --git a/platform/meta/design-docs/0078-email-cf-native.md b/platform/meta/design-docs/0078-email-cf-native.md index f7cdf7fae..999a48394 100644 --- a/platform/meta/design-docs/0078-email-cf-native.md +++ b/platform/meta/design-docs/0078-email-cf-native.md @@ -69,7 +69,9 @@ Interactive deployment shows the selected account, the domain and the unfinished account changes before offering setup. Non-interactive deployment reports unfinished setup and deploys without email; `--require-email` makes setup a prerequisite. Ready configuration is reconciled without repeating -account mutations. +account mutations. If setup already committed the exact subdomain routing plan +and only its new MX records remain empty or unreadable, preserve that plan and +stop every deployment before build or upload. Retry after DNS is verifiable. The checklist separates account work, config updates and routing rules. `wrangler deploy` owns rule application; a pending rule is not a reason to @@ -111,8 +113,10 @@ Void owns the whole derived top-level `addresses` array. Hand-written entries it cannot derive skip setup without changing the array. Addresses already routed elsewhere are pruned from the plan. When routing is unready the key is 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. +rule. The exception is the exact committed subdomain plan waiting only for MX +propagation described above: preserve the array and abort deployment. The root +config is re-read after edits and the deployment verifier's whole-array check +is preserved. ### Error map and degraded branches @@ -126,11 +130,11 @@ 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 +### Remaining live Cloudflare checks Unit tests are not provider acceptance. Still to establish with the selected credential type, per the [live release procedure](../release-acceptance.md): -the subdomain routing POST and subaddressing PATCH, rule-plan permissions, +the subaddressing PATCH, rule-plan permissions, conflict behavior after dashboard edits or Worker renames, and multi-label mail subdomains. @@ -466,8 +470,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, +Provider submissions have a 30-second wait limit. Direct sends share a 50-second +proxy budget across admission, attempt checkpoints and provider work; stop new +provider work at 45 seconds and reserve the remainder for finish or cancellation. +The SDK bounds the full request to 60 seconds, including the proxy's bounded +request-body read. Inbound handler action batches retain a 60-second 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. @@ -495,6 +503,12 @@ 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. +Confirmation links use the email gateway's public Worker origin so recipients can +reach them when Cloudflare Access protects the API. The gateway accepts only the +fixed confirmation path with one bounded token query and relays it through its API +service binding. The API remains responsible for HMAC verification and the +single-use destination-row transition. + 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 diff --git a/platform/packages/api/README.md b/platform/packages/api/README.md index c43642cf9..7fabb1bb8 100644 --- a/platform/packages/api/README.md +++ b/platform/packages/api/README.md @@ -246,7 +246,7 @@ Projects send and receive mail through `void/email`. The API authorizes routing, ### Sender identity is per-environment -The platform mail domain is a configured var, `EMAIL_SENDER_DOMAIN` — never a literal in code. Production and staging run different domains (`mail.void.cloud` / `mail.staging.void.cloud`), and the proxy builds its sender regex from the same var, so a hard-coded domain would make a staging send unroutable. +The platform mail domain is a configured var, `EMAIL_SENDER_DOMAIN` — never a literal in code. Production and staging run different domains (`mail.void.cloud` / `mail.voidcloud.dev`), and the proxy builds its sender regex from the same var, so a hard-coded domain would make a staging send unroutable. A project's sender address is `+noreply@`. Deployed user workers receive the two halves as plain-text bindings: diff --git a/platform/packages/api/src/email/admission.ts b/platform/packages/api/src/email/admission.ts index 65a155eb4..ee97df3ec 100644 --- a/platform/packages/api/src/email/admission.ts +++ b/platform/packages/api/src/email/admission.ts @@ -12,7 +12,11 @@ import { emailUnresolvedAttempts, } from './admission-schema.ts'; import { emailCredentials, emailDomainRoutes, emailZoneConnections } from './connection-schema.ts'; -import { isEmailCredentialExpired, resolveEmailDomain } from './connection-service.ts'; +import { + isEmailCredentialExpired, + resolveEmailDomain, + resolveEmailDomains, +} from './connection-service.ts'; import { getEmailRecipientPolicy } from './settings.ts'; export type EmailActionState = @@ -345,7 +349,7 @@ export async function admitEmailAction( 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)) { + 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 = @@ -461,13 +465,16 @@ export async function admitEmailAction( transport: input.transport, policy_version: controls.version, }); + const recipientDomains = [...new Set(recipients.map((recipient) => recipient.split('@')[1]!))]; + const destinationRoutes = await resolveEmailDomains(tx, recipientDomains); let admittedCount = 0; + const recipientRows: Array = []; 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 destinationRoute = destinationRoutes.get(domain); const sharedDestination = domain === input.sharedSenderDomain.toLowerCase() || destinationRoute?.route.addressing === 'shared'; @@ -486,7 +493,7 @@ export async function admitEmailAction( errorCode = 'QUOTA_EXCEEDED'; } const admitted = errorCode === null; - await tx.insert(emailActionRecipients).values({ + recipientRows.push({ id: generateId('emailrcpt'), action_id: actionId, project_id: input.projectId, @@ -501,6 +508,7 @@ export async function admitEmailAction( admittedCount++; } } + await tx.insert(emailActionRecipients).values(recipientRows); if (admittedCount) { await tx .update(emailMonthlyUsage) diff --git a/platform/packages/api/src/email/cf-customer.ts b/platform/packages/api/src/email/cf-customer.ts index de1f16496..9f046adbc 100644 --- a/platform/packages/api/src/email/cf-customer.ts +++ b/platform/packages/api/src/email/cf-customer.ts @@ -87,8 +87,8 @@ export type CfSendingSubdomain = Readonly<{ }>; export type CfCustomerClient = Readonly<{ - /** GET /user/tokens/verify — the api_token verify step. */ - verifyToken: () => Promise; + /** Verify a user or account token against the zone's authoritative account. */ + verifyToken: (accountId: string) => Promise; /** GET /zones?name= — exact-name match, or null when the credential can't see it. */ findZone: (name: string) => Promise; /** @@ -151,7 +151,21 @@ export function createCfCustomerClient(credential: string): CfCustomerClient { cfCustomerFetch(`${CF_CUSTOMER_API_BASE}${path}`, credential, init); return { - verifyToken: () => call('/user/tokens/verify'), + verifyToken: async (accountId) => { + try { + return await call('/user/tokens/verify'); + } catch (error) { + if ( + !(error instanceof CloudflareApiError) || + (error.status !== 401 && error.status !== 403) + ) { + throw error; + } + return call( + `/accounts/${encodeURIComponent(accountId)}/tokens/verify`, + ); + } + }, findZone: async (name) => { const zones = await call>( diff --git a/platform/packages/api/src/email/connection-service.ts b/platform/packages/api/src/email/connection-service.ts index a19ae1e03..fad8aa2cf 100644 --- a/platform/packages/api/src/email/connection-service.ts +++ b/platform/packages/api/src/email/connection-service.ts @@ -667,6 +667,33 @@ export async function resolveEmailDomain(db: DbOrTx, rawDomain: string) { return rows[0] ?? null; } +type ResolvedEmailDomain = NonNullable>>; + +export async function resolveEmailDomains( + db: DbOrTx, + rawDomains: ReadonlyArray, +): Promise> { + const normalizedByInput = new Map( + rawDomains.map((rawDomain) => [rawDomain, normalizeEmailDomain(rawDomain)]), + ); + const domains = [...new Set(normalizedByInput.values())]; + if (domains.length === 0) { + return new Map(); + } + const rows = await db + .select({ route: emailDomainRoutes, connection: emailZoneConnections }) + .from(emailDomainRoutes) + .innerJoin(emailZoneConnections, eq(emailDomainRoutes.connection_id, emailZoneConnections.id)) + .where(inArray(emailDomainRoutes.domain, domains)); + const byDomain = new Map(rows.map((row) => [row.route.domain, row])); + return new Map( + [...normalizedByInput].flatMap(([input, normalized]) => { + const row = byDomain.get(normalized); + return row ? [[input, row] as const] : []; + }), + ); +} + export async function resolveEmailIngress( db: DbOrTx, input: { @@ -847,7 +874,7 @@ export async function replaceBlockedSystemEmailCleanupCredential( const client = createCfCustomerClient(token); let verifiedToken: { tokenId: string; expiresOn: string | null }; try { - const verification = await client.verifyToken(); + const verification = await client.verifyToken(connection.account_id); if (verification.status !== 'active') { throw new EmailOperationError('Cloudflare API token is not active', 403); } @@ -1239,7 +1266,7 @@ export async function requestEmailDomainAdd( } let verifiedToken: { tokenId: string; expiresOn: string | null } | null = null; if (input.token) { - const verification = await client.verifyToken(); + const verification = await client.verifyToken(zone.account.id); if (verification.status !== 'active') { throw new EmailOperationError('Cloudflare API token is not active', 403); } diff --git a/platform/packages/api/src/email/send-verification.ts b/platform/packages/api/src/email/send-verification.ts index f4a5bff98..232ecfaa1 100644 --- a/platform/packages/api/src/email/send-verification.ts +++ b/platform/packages/api/src/email/send-verification.ts @@ -1,199 +1,49 @@ /** * Platform-side destination verification email. * - * When project A adds an address that another project already verified - * via Cloudflare Email Routing, we cannot trust CF's verified flag for - * per-project consent (Option C+B from the email design doc): the - * recipient consented to project B, not project A. We issue our own - * confirmation email with a single-use HMAC link and only flip the row - * to 'verified' when the recipient clicks it. - * - * Sending mechanics: the api worker doesn't hold the per-tenant sender - * — only the proxy worker does. We POST to the proxy's - * `/email/internal/send` endpoint, authenticated with an HMAC of a fixed - * sentinel string under JWT_SECRET (a value only the proxy and api - * hold). User workers never see JWT_SECRET, so they can't forge - * platform-internal sends. - * - * Best-effort for DELIVERY: the destination row is already inserted as - * 'pending' before we get here. If the send fails, the row stays pending - * and a repeat `POST /projects/:id/email/destinations` for the same - * address (`void email allow
` again) resends the link, so we - * log and return rather than throw. - * - * NOT best-effort for CONFIGURATION: a missing `EMAIL_SENDER_DOMAIN` - * throws before anything is attempted. Every send from this worker would - * fail the same way, and a log line among the transient-failure lines is - * exactly how that goes unnoticed. + * When project A adds an address that another project already verified via + * Cloudflare Email Routing, the recipient must consent to project A as well. + * The destination remains pending until its single-use confirmation link is + * opened. */ import type { ApiEnv } from '../env.ts'; -/** - * Sentinel string the proxy expects in the HMAC. - * - * THE definition. The proxy worker is a separate bundle and cannot import - * from `packages/api`, so it mirrors this literal — keep the two in sync, - * and change them in the same commit. Bumping this value (e.g. to `-v2`) - * invalidates every in-flight platform-internal send token in exchange - * for forcing a coordinated proxy + api deploy; today there is no reason - * to bump it. - */ -export const PLATFORM_INTERNAL_EMAIL_SENTINEL = 'void-platform-internal-email-v1'; - -/** - * `From` for platform-issued verification mail, built from the - * per-environment `EMAIL_SENDER_DOMAIN` var so production and staging - * each ride their own DKIM/SPF/DMARC configuration. The proxy's - * `/email/internal/send` allow-lists exactly `noreply@`, so the two vars must name the same domain - * within one environment. - * - * Deliberately NOT defaulted: a fallback to the production domain would - * make a misconfigured staging worker sign mail for a domain it has no - * business sending from — and the proxy would reject it anyway, turning - * a config error into a silent 403 per send. Throwing surfaces it once, - * with the var name in the message. - */ -function resolveFromAddress(env: ApiEnv['Bindings']): string { - const domain = env.EMAIL_SENDER_DOMAIN?.trim(); - if (!domain) { +function resolveConfirmationOrigin(env: ApiEnv['Bindings']): string { + const configured = env.EMAIL_GATEWAY_ORIGIN?.trim(); + if (!configured) { throw new Error( - 'EMAIL_SENDER_DOMAIN is not configured on the api worker; refusing to send platform verification mail', + 'EMAIL_GATEWAY_ORIGIN is not configured on the api worker; refusing to send platform verification mail', ); } - return `noreply@${domain}`; -} - -/** - * Resolve the public host for the confirmation link. Production is - * `api.void.cloud`; staging gates on `PLATFORM_ENV` because Access - * blocks staging API publicly anyway and we still want the link to - * point at the right environment for ops/testing. - * - * `SITE_DOMAIN` is intentionally NOT used here — that constant is the - * user-app domain (`void.app`), not the api host. - */ -function resolveApiHost(env: ApiEnv['Bindings']): string { - if (env.PLATFORM_ENV === 'staging') { - return 'api.staging.void.cloud'; - } - // Local dev (PLATFORM_ENV unset / 'development' / etc.) falls through - // to api.void.cloud — local-dev clicks should test against the dev - // api worker by overriding SITE_DOMAIN if needed. - return env.SITE_DOMAIN && /^api\./.test(env.SITE_DOMAIN) ? env.SITE_DOMAIN : 'api.void.cloud'; -} - -/** - * Resolve the proxy worker's public URL the same way. The api worker has - * no service binding to the proxy today — we go through CF's public edge. - */ -function resolveProxyOrigin(env: ApiEnv['Bindings']): string { - if (env.PLATFORM_ENV === 'staging') { - return 'https://proxy.staging.void.cloud'; + let url: URL; + try { + url = new URL(configured); + } catch { + throw new Error('EMAIL_GATEWAY_ORIGIN must be an HTTPS origin'); } - return 'https://proxy.void.cloud'; -} - -/** - * Build a minimal RFC 5322 `text/plain` message and base64-encode it. - * No attachments, no multipart — just the confirmation link plus a short - * explanation. CRLF terminators are mandatory for SMTP. - */ -function buildVerificationMime(opts: { - from: string; - to: string; - subject: string; - body: string; -}): string { - const lines = [ - `From: ${opts.from}`, - `To: ${opts.to}`, - `Subject: ${opts.subject}`, - 'MIME-Version: 1.0', - 'Content-Type: text/plain; charset=utf-8', - 'Content-Transfer-Encoding: 7bit', - '', - opts.body, - '', - ]; - const mime = lines.join('\r\n'); - return base64Encode(new TextEncoder().encode(mime)); -} - -function base64Encode(bytes: Uint8Array): string { - let binary = ''; - for (const b of bytes) { - binary += String.fromCharCode(b); + if ( + url.protocol !== 'https:' || + url.origin !== configured || + url.username || + url.password || + url.pathname !== '/' || + url.search || + url.hash + ) { + throw new Error('EMAIL_GATEWAY_ORIGIN must be an HTTPS origin'); } - return btoa(binary); + return url.origin; } -const encoder = new TextEncoder(); -let cachedKey: CryptoKey | undefined; -let cachedSecret: string | undefined; - -/** - * Sign `..`. The proxy - * verifies the same concatenation and rejects timestamps outside a - * 5-minute window. - * - * Why bind content into the HMAC: without it, a single observed - * platformToken+timestamp pair could be replayed by an attacker who - * intercepted the request to send ARBITRARY mail (different recipient, - * different subject, different attachments) within the timestamp - * window. Hashing `${from}|${to}|${mimeBase64}` into the signed value - * pins the token to one specific message — replay still works for the - * same exact message, but that's the desired idempotency surface. - * - * Encoding choices: - * - `|` separator inside the content hash input is safe because no - * legal email address or base64 character is `|`. - * - SHA-256 hex (lowercase) is the bytes-on-the-wire format the - * proxy reproduces and compares against. base64url would save 22 - * bytes but loses nothing operationally; hex is easier to grep - * for in tail logs. - */ -async function signSentinelAtBound( - secret: string, - unixSeconds: number, - contentSha256Hex: string, -): Promise { - if (!cachedKey || cachedSecret !== secret) { - cachedKey = await crypto.subtle.importKey( - 'raw', - encoder.encode(secret), - { name: 'HMAC', hash: 'SHA-256' }, - false, - ['sign'], +function resolveFromAddress(env: ApiEnv['Bindings']): string { + const domain = env.EMAIL_SENDER_DOMAIN?.trim(); + if (!domain) { + throw new Error( + 'EMAIL_SENDER_DOMAIN is not configured on the api worker; refusing to send platform verification mail', ); - cachedSecret = secret; - } - const message = `${PLATFORM_INTERNAL_EMAIL_SENTINEL}.${unixSeconds}.${contentSha256Hex}`; - const sig = new Uint8Array(await crypto.subtle.sign('HMAC', cachedKey, encoder.encode(message))); - let binary = ''; - for (const b of sig) { - binary += String.fromCharCode(b); } - return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); -} - -/** - * Hash `${from}|${to}|${mimeBase64}` to lowercase hex. Exposed so the - * proxy verification helper can reproduce the same hash bit-for-bit. - */ -export async function hashSendContent( - from: string, - to: string, - mimeBase64: string, -): Promise { - const input = `${from}|${to}|${mimeBase64}`; - const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(input))); - let hex = ''; - for (const b of digest) { - hex += b.toString(16).padStart(2, '0'); - } - return hex; + return `noreply@${domain}`; } export async function sendPlatformVerificationEmail( @@ -202,61 +52,32 @@ export async function sendPlatformVerificationEmail( address: string, token: string, ): Promise { - // Resolved OUTSIDE the try: a missing `EMAIL_SENDER_DOMAIN` is a deploy - // misconfiguration, not a delivery failure, and must not be swallowed - // into a log line that reads like a transient proxy error. - const fromAddress = resolveFromAddress(env); - - try { - const apiHost = resolveApiHost(env); - const link = `https://${apiHost}/email/destinations/confirm?token=${encodeURIComponent(token)}`; - const subject = `[${project.slug}] wants permission to email you`; - const body = [ - `The Void project "${project.slug}" wants permission to send email to`, - `${address}.`, - '', - 'Click to confirm:', - link, - '', - 'This link expires in 24 hours and can only be used once.', - '', - "If you didn't expect this email, ignore it — no permission is granted", - 'until the link is clicked.', - ].join('\r\n'); - - const mimeBase64 = buildVerificationMime({ - from: fromAddress, - to: address, - subject, - body, - }); + // Resolve deployment configuration outside the delivery catch. A missing + // binding or identity is a persistent deployment error, not a transient + // send failure. + const from = resolveFromAddress(env); + const confirmationOrigin = resolveConfirmationOrigin(env); + if (!env.EMAIL) { + throw new Error('Platform email is not configured.'); + } - const platformTimestamp = Math.floor(Date.now() / 1000); - const contentSha256 = await hashSendContent(fromAddress, address, mimeBase64); - const platformToken = await signSentinelAtBound( - env.JWT_SECRET, - platformTimestamp, - contentSha256, - ); - const url = `${resolveProxyOrigin(env)}/email/internal/send`; - const res = await fetch(url, { - method: 'POST', - headers: { 'content-type': 'application/json' }, - body: JSON.stringify({ - platformToken, - platformTimestamp, - from: fromAddress, - to: address, - mimeBase64, - }), - }); + const link = `${confirmationOrigin}/email/destinations/confirm?token=${encodeURIComponent(token)}`; + const subject = `[${project.slug}] wants permission to email you`; + const text = [ + `The Void project "${project.slug}" wants permission to send email to`, + `${address}.`, + '', + 'Click to confirm:', + link, + '', + 'This link expires in 24 hours and can only be used once.', + '', + "If you didn't expect this email, ignore it — no permission is granted", + 'until the link is clicked.', + ].join('\r\n'); - if (!res.ok) { - const detail = await res.text().catch(() => ''); - console.error( - `[email-verify] proxy /email/internal/send returned ${res.status} for project=${project.id} address=${address}: ${detail.slice(0, 240)}`, - ); - } + try { + await env.EMAIL.send({ from, to: address, subject, text }); } catch (err) { console.error( `[email-verify] platform verification email failed for project=${project.id} address=${address}:`, diff --git a/platform/packages/api/src/env.ts b/platform/packages/api/src/env.ts index b79e0760c..32eabe3a1 100644 --- a/platform/packages/api/src/env.ts +++ b/platform/packages/api/src/env.ts @@ -169,7 +169,7 @@ export type ApiEnv = Env & { EMAIL_FROM?: string; /** * Platform mail domain for this environment (`mail.void.cloud` in - * production, `mail.staging.void.cloud` in staging). The proxy worker + * production, `mail.voidcloud.dev` in staging). The proxy worker * declares the SAME var and validates every sender against it, so the two * values must match or a correctly-signed send is rejected by its own * proxy. Optional on the type because the var is absent until the mail diff --git a/platform/packages/api/src/index.ts b/platform/packages/api/src/index.ts index 27e517ef4..6edddc48a 100644 --- a/platform/packages/api/src/index.ts +++ b/platform/packages/api/src/index.ts @@ -432,11 +432,10 @@ const app = new Hono() .route('/webhooks', webhookRoutes) .use('/github/*', capabilityMiddleware('managedBuilds')) .route('/github', githubRoutes) - // Public: the HMAC-signed token in `?token=` IS the auth. Mounted - // BEFORE the `/projects/*` auth middleware so recipients (third - // parties, not Void users) can click without logging in. Gated like - // `/webhooks/*`: a platform without email issued no confirmation link, - // so the standard 501 replaces verifying a token nobody can hold. + // The gateway relays this exact route through its API service binding. The + // HMAC-signed token is the credential, so recipients need no Void or Access + // session. A platform without email issued no token and returns the standard + // capability response. .use('/email/*', capabilityMiddleware('email')) .route('/email', emailConfirm) .use('/me', authMiddleware) diff --git a/platform/packages/api/src/middleware/platform-access.ts b/platform/packages/api/src/middleware/platform-access.ts index bfc913b9c..79172f0b5 100644 --- a/platform/packages/api/src/middleware/platform-access.ts +++ b/platform/packages/api/src/middleware/platform-access.ts @@ -4,21 +4,22 @@ import { readAuthSettings } from '../auth/configuration.ts'; import { verifyJwt } from '../auth/jwt.ts'; import type { ApiEnv } from '../env.ts'; -/** These service-binding routes independently validate purpose-bound platform HMACs. */ +/** These service-binding routes independently validate purpose-bound credentials. */ function internallyAuthenticated(method: string, path: string): boolean { return ( - method === 'POST' && - (/^\/internal\/(?:resolve-resource|resolve-worker|verify-owner|verify-prerender-build)\/[^/]+$/.test( - path, - ) || - 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( + (method === 'GET' && path === '/email/destinations/confirm') || + (method === 'POST' && + (/^\/internal\/(?:resolve-resource|resolve-worker|verify-owner|verify-prerender-build)\/[^/]+$/.test( path, ) || - path === '/internal/github-webhook') + 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')) ); } diff --git a/platform/packages/api/src/provisioning/provision.ts b/platform/packages/api/src/provisioning/provision.ts index 848448b77..41649b62f 100644 --- a/platform/packages/api/src/provisioning/provision.ts +++ b/platform/packages/api/src/provisioning/provision.ts @@ -53,7 +53,7 @@ export async function provisionBindings( /** * Platform mail domain for this environment (`EMAIL_SENDER_DOMAIN` on * the api worker — `mail.void.cloud` in production, - * `mail.staging.void.cloud` in staging). Never hard-coded: the proxy + * `mail.voidcloud.dev` in staging). Never hard-coded: the proxy * validates outbound senders against its own copy of the same value, * so a baked-in production domain would make staging unsendable. * diff --git a/platform/packages/api/src/reserved-slugs.ts b/platform/packages/api/src/reserved-slugs.ts index 5f3b800ae..830183859 100644 --- a/platform/packages/api/src/reserved-slugs.ts +++ b/platform/packages/api/src/reserved-slugs.ts @@ -4,8 +4,7 @@ * A project's outbound `from` is `[+tag]@` and * inbound mail to `[+tag]@` is dispatched into its worker, so owning a * slug owns that mailbox. `noreply` is the platform's own verification - * sender (the proxy's `/email/internal/send` allow-list is exactly - * `noreply@`), and `postmaster` / `abuse` / `bounce` / `security` + * sender, and `postmaster` / `abuse` / `bounce` / `security` * are the addresses recipients and mail providers treat as authoritative for * the whole domain. A project holding one of these could send mail that is * indistinguishable from ours, and would receive the bounces and replies to diff --git a/platform/packages/api/src/routes/email-confirm.ts b/platform/packages/api/src/routes/email-confirm.ts index 9b9e850f6..e50d79d09 100644 --- a/platform/packages/api/src/routes/email-confirm.ts +++ b/platform/packages/api/src/routes/email-confirm.ts @@ -1,16 +1,16 @@ /** - * Public, unauthenticated endpoint for clicking the platform-side - * destination verification link. The HMAC-signed token IS the auth — it + * Token-authenticated endpoint for the platform-side destination verification + * link. The HMAC-signed token IS the auth — it * embeds (project_id, destination_id, address, exp) and is validated * against JWT_SECRET. Single-use is enforced by DB state: the click * flips the destination row to 'verified', so a second click finds an * already-verified row and returns idempotent success. * - * Wired BEFORE the auth middleware in `index.ts` so recipients can click - * without logging in (they're not Void users — they're third parties - * being asked to consent). + * The email gateway exposes the public URL and relays this exact route through + * its API service binding. Access middleware recognizes only this token-auth + * route; project and operator routes remain protected. * - * See the email design doc (Option B follow-up) for design rationale. + * See the email design's recipient-consent section for the trust boundary. */ import { Hono } from 'hono'; diff --git a/platform/packages/api/src/routes/email.ts b/platform/packages/api/src/routes/email.ts index 9849cb213..feb86d4b1 100644 --- a/platform/packages/api/src/routes/email.ts +++ b/platform/packages/api/src/routes/email.ts @@ -738,14 +738,8 @@ async function dispatchPlatformVerification( address, token, ); - // Same shape the rest of the api uses for post-response work: the - // call STARTS synchronously so it cannot be skipped, and a test - // harness that invoked `app.request` without an ExecutionContext - // falls back to an inline await so the send still happens. - // `sendPlatformVerificationEmail` logs and swallows delivery - // failures itself — the only thing that escapes it is a missing - // `EMAIL_SENDER_DOMAIN`, which is a deploy-time misconfiguration - // and is deliberately left loud. + // Keep delivery alive after the response; contexts without waitUntil await it. + // Delivery failures are logged; missing platform-mail configuration still rejects. try { context.executionCtx.waitUntil(sendPromise); } catch { diff --git a/platform/packages/api/test/integration/api-email.test.ts b/platform/packages/api/test/integration/api-email.test.ts index 66e155645..54dcd6f1b 100644 --- a/platform/packages/api/test/integration/api-email.test.ts +++ b/platform/packages/api/test/integration/api-email.test.ts @@ -42,10 +42,6 @@ import { revokeOwnerVerifiedDestinationsForUserChange } from '../../src/db.ts'; import * as dbModule from '../../src/db.ts'; import { emailMonthlyUsage } from '../../src/email/admission-schema.ts'; import { setProjectEmailLimits, setProjectEmailSuspended } from '../../src/email/admission.ts'; -import { - hashSendContent, - PLATFORM_INTERNAL_EMAIL_SENTINEL, -} from '../../src/email/send-verification.ts'; import app from '../../src/index.ts'; import { reconcileEmailDestinationCleanups, @@ -77,11 +73,33 @@ let env: TestEnv; * that hard-coded production's would pass against a route that ignored the * var entirely. */ -const MAIL_DOMAIN = 'mail.staging.void.cloud'; +const MAIL_DOMAIN = 'mail.voidcloud.dev'; +const EMAIL_GATEWAY_ORIGIN = 'https://void-email-gateway-staging.voidzer0.workers.dev'; + +type VerificationSend = { + from: string; + to: string; + subject: string; + text: string; +}; -/** Bindings with the platform mail zone configured. */ +const verificationSends: Array = []; +let deliverVerification: () => void | Promise = () => {}; +const verificationEmailBinding = { + send: vi.fn(async (message: VerificationSend) => { + verificationSends.push(message); + await deliverVerification(); + }), +}; + +/** Bindings with platform verification mail configured. */ function emailEnv(domain: string = MAIL_DOMAIN): TestEnv { - return { ...env, EMAIL_SENDER_DOMAIN: domain }; + return { + ...env, + EMAIL: verificationEmailBinding as unknown as SendEmail, + EMAIL_GATEWAY_ORIGIN, + EMAIL_SENDER_DOMAIN: domain, + }; } beforeAll(async () => { @@ -93,6 +111,9 @@ afterAll(async () => { }); beforeEach(async () => { + verificationSends.length = 0; + verificationEmailBinding.send.mockClear(); + deliverVerification = () => {}; await clearTables(env.db); }); @@ -205,54 +226,17 @@ function cfCalls( }); } -/** - * `mockCfApi` plus a passthrough for the proxy's `/email/internal/send`. The - * CF mock throws on any unmocked URL, and the platform verification email is - * the one non-CF fetch the api makes. - */ -function mockCfWithProxy( +/** Configure the CF API mock and optional verification delivery behavior. */ +function mockCfWithEmail( overrides: Parameters[0] = {}, - respond: () => Response = () => Response.json({ ok: true }), + deliver: () => void | Promise = () => {}, ): ReturnType { - const cfMock = mockCfApi(overrides) as unknown as ( - input: string | URL | Request, - init?: RequestInit, - ) => Promise; - const wrapper = vi.fn(async (input: string | URL | Request, init?: RequestInit) => { - const url = - typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url; - if (url.includes('/email/internal/send')) { - return respond(); - } - return cfMock(input, init); - }); - vi.stubGlobal('fetch', wrapper); - return wrapper; + deliverVerification = deliver; + return mockCfApi(overrides); } -type ProxySend = { - url: string; - body: { - platformToken?: unknown; - platformTimestamp?: unknown; - from?: unknown; - to?: unknown; - mimeBase64?: unknown; - }; -}; - -function proxySends(fetchMock: ReturnType): Array { - return (fetchMock.mock.calls as Array>) - .filter((call) => { - const url = typeof call[0] === 'string' ? call[0] : String(call[0]); - return url.includes('/email/internal/send'); - }) - .map((call) => { - const url = typeof call[0] === 'string' ? call[0] : String(call[0]); - const init = call[1] as RequestInit | undefined; - const body = typeof init?.body === 'string' ? JSON.parse(init.body) : {}; - return { url, body } as ProxySend; - }); +function recordedVerificationSends(): Array { + return verificationSends; } /** @@ -409,9 +393,9 @@ describe('POST /projects/:id/email/destinations', () => { it('returns the existing row without calling CF when the address is already in the DB', async () => { const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); - // Proxy reachable and sender configured, so a platform send COULD + // Email binding and sender configured, so a platform send COULD // happen here — the assertion below is that it does not. - const fetchMock = mockCfWithProxy(); + const fetchMock = mockCfWithEmail(); const first = await addDestination(project.id, user.jwt, 'a@b.com', emailEnv()); expect(first.status).toBe(201); @@ -431,7 +415,7 @@ describe('POST /projects/:id/email/destinations', () => { expect(await rowsFor(project.id)).toHaveLength(1); // A CF-pending row waits on CLOUDFLARE's link, which CF mails on create // only — there is nothing for the platform to resend. - expect(proxySends(fetchMock)).toHaveLength(0); + expect(recordedVerificationSends()).toHaveLength(0); }); it('recovers via list when CF reports "already exists"', async () => { @@ -440,7 +424,7 @@ describe('POST /projects/:id/email/destinations', () => { // the row lands platform-pending. const user = await createTestUser(env.db); const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy(cfAlreadyVerified('recovered-tag', 'shared@example.com')); + const fetchMock = mockCfWithEmail(cfAlreadyVerified('recovered-tag', 'shared@example.com')); const res = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(res.status).toBe(201); @@ -450,7 +434,7 @@ describe('POST /projects/:id/email/destinations', () => { expect(rows[0]?.cf_destination_id).toBe('recovered-tag'); expect(rows[0]?.status).toBe('pending'); expect(rows[0]?.verification_source).toBe('platform'); - expect(proxySends(fetchMock)).toHaveLength(1); + expect(recordedVerificationSends()).toHaveLength(1); }); it('returns 502 when CF fails for any reason other than "already exists"', async () => { @@ -655,7 +639,7 @@ describe('GET refresh against a recreated Cloudflare destination', () => { // the next tag: step 1 gets T1, step 3 gets T2. let onAccount: ReturnType | null = null; const unissued = [tagT1, tagT2]; - const fetchMock = mockCfWithProxy({ + const fetchMock = mockCfWithEmail({ addEmailDestination: (_url, init) => { if (onAccount) { return cfError('address already exists'); @@ -712,7 +696,7 @@ describe('GET refresh against a recreated Cloudflare destination', () => { expect(rowB.status).toBe('pending'); expect(rowB.verification_source).toBe('cf'); expect((await rowsFor(projectB.id))[0]?.cf_destination_id).toBe(tagT2); - expect(proxySends(fetchMock)).toHaveLength(0); + expect(recordedVerificationSends()).toHaveLength(0); // 4. alice clicks CF's link. onAccount = cfRow(tagT2, options.address, '2026-09-15T00:00:00Z'); @@ -831,9 +815,9 @@ describe('GET refresh against a recreated Cloudflare destination', () => { expect(body.status).toBe('pending'); expect(body.verification_source).toBe('platform'); expect(body.platformVerificationPending).toBe(true); - const sends = proxySends(fetchMock); + const sends = recordedVerificationSends(); expect(sends).toHaveLength(1); - expect(sends[0]!.body.to).toBe('alice@example.com'); + expect(sends[0]!.to).toBe('alice@example.com'); expect((await rowsFor(projectA.id))[0]?.cf_destination_id).toBe(tagT2); // And the refresh keeps its hands off a platform-pending row. @@ -1110,7 +1094,7 @@ describe('per-project verification (Option C + Option B)', () => { const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy(cfAlreadyVerified('cf-tag-owner', 'owner@example.com')); + const fetchMock = mockCfWithEmail(cfAlreadyVerified('cf-tag-owner', 'owner@example.com')); const res = await addDestination(project.id, user.jwt, 'owner@example.com', emailEnv()); @@ -1121,7 +1105,7 @@ describe('per-project verification (Option C + Option B)', () => { 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); + expect(recordedVerificationSends()).toHaveLength(0); }); it('Option C: records who consented and which address they used', async () => { @@ -1146,7 +1130,7 @@ describe('per-project verification (Option C + Option B)', () => { const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); + const fetchMock = mockCfWithEmail(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); const res = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(res.status).toBe(201); @@ -1162,22 +1146,19 @@ describe('per-project verification (Option C + Option B)', () => { // Still pending, so SQL admission must refuse sends to it. expect(await readVerifiedDestinations(project.id)).toEqual([]); - const sends = proxySends(fetchMock); + const sends = recordedVerificationSends(); expect(sends).toHaveLength(1); - expect(sends[0]!.body.to).toBe('shared@example.com'); + expect(sends[0]!.to).toBe('shared@example.com'); // The sender is derived from the CONFIGURED domain, never a literal. - expect(sends[0]!.body.from).toBe(`noreply@${MAIL_DOMAIN}`); - // The proxy rejects a timestamp outside a 5-minute window. - const ts = sends[0]!.body.platformTimestamp; - expect(typeof ts).toBe('number'); - expect(Math.abs(Math.floor(Date.now() / 1000) - (ts as number))).toBeLessThan(60); + expect(sends[0]!.from).toBe(`noreply@${MAIL_DOMAIN}`); + expect(sends[0]!.text).toContain('/email/destinations/confirm?token='); }); it('Option B: does NOT populate the audit columns (consent was per-recipient)', async () => { const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - mockCfWithProxy(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); + mockCfWithEmail(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); const res = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(res.status).toBe(201); @@ -1201,7 +1182,7 @@ describe('per-project verification (Option C + Option B)', () => { await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); let cfVerifiedAt: string | null = null; - const fetchMock = mockCfWithProxy({ + const fetchMock = mockCfWithEmail({ addEmailDestination: () => cfError('address already exists'), listEmailDestinations: () => cfSuccess([cfRow('cf-tag-shared', 'shared@example.com', cfVerifiedAt)]), @@ -1219,9 +1200,9 @@ describe('per-project verification (Option C + Option B)', () => { expect(body.platformVerificationPending).toBe(true); // Our own link is the only one the recipient can receive for this project. - const sends = proxySends(fetchMock); + const sends = recordedVerificationSends(); expect(sends).toHaveLength(1); - expect(sends[0]!.body.to).toBe('shared@example.com'); + expect(sends[0]!.to).toBe('shared@example.com'); // The recipient now clicks the link CF sent for the OTHER project. That // consent is not ours to claim: the row stays pending and the proxy keeps @@ -1247,7 +1228,7 @@ describe('per-project verification (Option C + Option B)', () => { const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy({ + const fetchMock = mockCfWithEmail({ addEmailDestination: () => cfError('address already exists'), listEmailDestinations: () => cfSuccess([cfRow('cf-tag-owner', 'owner@example.com', null)]), }); @@ -1269,7 +1250,7 @@ describe('per-project verification (Option C + Option B)', () => { // Nothing went out: CF refused, and the platform has no link of its own // to mail for a CF-pending owner row. - expect(proxySends(fetchMock)).toHaveLength(0); + expect(recordedVerificationSends()).toHaveLength(0); const rows = await rowsFor(project.id); expect(rows).toHaveLength(1); expect(rows[0]?.cf_destination_id).toBe('cf-tag-owner'); @@ -1295,7 +1276,7 @@ describe('per-project verification (Option C + Option B)', () => { verification_source: 'cf', }); let onAccount = true; - const fetchMock = mockCfWithProxy({ + const fetchMock = mockCfWithEmail({ addEmailDestination: () => onAccount ? cfError('address already exists') @@ -1337,7 +1318,7 @@ describe('per-project verification (Option C + Option B)', () => { 'verificationSent', ); expect((await rowsFor(second.id))[0]?.cf_destination_id).toBe('cf-tag-owner-2'); - expect(proxySends(fetchMock)).toHaveLength(0); + expect(recordedVerificationSends()).toHaveLength(0); }); it('Option B: parallel POSTs for the same address send exactly one platform email', async () => { @@ -1354,7 +1335,7 @@ describe('per-project verification (Option C + Option B)', () => { release = resolve; }); const cfMocks = cfAlreadyVerified('cf-tag-shared', 'shared@example.com'); - const fetchMock = mockCfWithProxy({ + const fetchMock = mockCfWithEmail({ ...cfMocks, addEmailDestination: async () => { if (++arrived === 2) { @@ -1375,9 +1356,9 @@ describe('per-project verification (Option C + Option B)', () => { expect([200, 201]).toContain(resA.status); expect([200, 201]).toContain(resB.status); - const sends = proxySends(fetchMock); + const sends = recordedVerificationSends(); expect(sends).toHaveLength(1); - expect(sends[0]!.body.to).toBe('shared@example.com'); + expect(sends[0]!.to).toBe('shared@example.com'); expect(await rowsFor(project.id)).toHaveLength(1); }); @@ -1388,20 +1369,24 @@ describe('per-project verification (Option C + Option B)', () => { const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - let proxyStatus = 500; - const fetchMock = mockCfWithProxy( + let deliveryFails = true; + const fetchMock = mockCfWithEmail( cfAlreadyVerified('cf-tag-shared', 'shared@example.com'), - () => Response.json({ ok: proxyStatus === 200 }, { status: proxyStatus }), + () => { + if (deliveryFails) { + throw new Error('provider unavailable'); + } + }, ); // First add: the row lands, the delivery fails, and the failure is // swallowed — the recipient has nothing to click. const first = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(first.status).toBe(201); - expect(proxySends(fetchMock)).toHaveLength(1); + expect(recordedVerificationSends()).toHaveLength(1); // Repeat: no new CF registration, no new row — one more link. - proxyStatus = 200; + deliveryFails = false; const second = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(second.status).toBe(200); const body = (await second.json()) as { @@ -1413,9 +1398,9 @@ describe('per-project verification (Option C + Option B)', () => { expect(body.verification_source).toBe('platform'); expect(body.platformVerificationPending).toBe(true); - const sends = proxySends(fetchMock); + const sends = recordedVerificationSends(); expect(sends).toHaveLength(2); - expect(sends[1]!.body.to).toBe('shared@example.com'); + expect(sends[1]!.to).toBe('shared@example.com'); expect(cfCalls(fetchMock, 'POST', '/email/routing/addresses')).toHaveLength(1); expect(await rowsFor(project.id)).toHaveLength(1); }); @@ -1423,20 +1408,20 @@ describe('per-project verification (Option C + Option B)', () => { it('does not swallow a missing EMAIL_SENDER_DOMAIN into a delivery-failure log', async () => { // Every reader fails closed on the unset var. `sendPlatformVerificationEmail` // resolves the sender OUTSIDE its try, so the misconfiguration surfaces - // instead of looking like a transient proxy error. In this harness there + // instead of looking like a transient delivery error. In this harness there // is no ExecutionContext, so the inline-await fallback carries the throw // into the response — in production it lands in `waitUntil`. const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); + const fetchMock = mockCfWithEmail(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); // `env` as-is — EMAIL_SENDER_DOMAIN unset. const res = await addDestination(project.id, user.jwt, 'shared@example.com', env); expect(res.status).toBe(500); // Nothing was mailed, and the row remains pending. - expect(proxySends(fetchMock)).toHaveLength(0); + expect(recordedVerificationSends()).toHaveLength(0); // 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 @@ -1448,9 +1433,9 @@ describe('per-project verification (Option C + Option B)', () => { const retry = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(retry.status).toBe(200); - const sends = proxySends(fetchMock); + const sends = recordedVerificationSends(); expect(sends).toHaveLength(1); - expect(sends[0]!.body.to).toBe('shared@example.com'); + expect(sends[0]!.to).toBe('shared@example.com'); expect(await rowsFor(project.id)).toHaveLength(1); }); @@ -1940,17 +1925,14 @@ describe('GET /email/destinations/confirm', () => { const user = await createTestUser(env.db); await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); + const fetchMock = mockCfWithEmail(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); const added = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); expect(added.status).toBe(201); - const [send] = proxySends(fetchMock); - const mime = new TextDecoder().decode( - Uint8Array.from(atob(send!.body.mimeBase64 as string), (ch) => ch.charCodeAt(0)), - ); - const link = /https:\/\/\S*\/email\/destinations\/confirm\?token=(\S+)/.exec(mime); - expect(link, `no confirm link in the mail body:\n${mime}`).not.toBeNull(); + const [send] = recordedVerificationSends(); + const link = /https:\/\/\S*\/email\/destinations\/confirm\?token=(\S+)/.exec(send!.text); + expect(link, `no confirm link in the mail body:\n${send!.text}`).not.toBeNull(); // Stop mocking fetch before the confirm request — nothing outbound is // expected on that path. @@ -2173,50 +2155,6 @@ describe('GET /projects/:id/email/logs', () => { }); }); -// --------------------------------------------------------------------------- -// api <-> proxy platform-internal send contract -// --------------------------------------------------------------------------- - -describe('platform-internal send token (as produced by the route)', () => { - it('signs sentinel.timestamp.sha256(from|to|mimeBase64) with JWT_SECRET', async () => { - const user = await createTestUser(env.db); - await setUserEmail(user.id, 'owner@example.com'); - const project = await createTestProject(env.db, user.id); - const fetchMock = mockCfWithProxy(cfAlreadyVerified('cf-tag-shared', 'shared@example.com')); - - const res = await addDestination(project.id, user.jwt, 'shared@example.com', emailEnv()); - expect(res.status).toBe(201); - - const [send] = proxySends(fetchMock); - expect(send).toBeDefined(); - - const expectedHash = await hashSendContent( - `noreply@${MAIL_DOMAIN}`, - 'shared@example.com', - send!.body.mimeBase64 as string, - ); - expect(expectedHash).toMatch(/^[0-9a-f]{64}$/); - - const enc = new TextEncoder(); - const signed = `${PLATFORM_INTERNAL_EMAIL_SENTINEL}.${send!.body.platformTimestamp}.${expectedHash}`; - const key = await crypto.subtle.importKey( - 'raw', - enc.encode(env.JWT_SECRET), - { name: 'HMAC', hash: 'SHA-256' }, - false, - ['sign'], - ); - const sig = new Uint8Array(await crypto.subtle.sign('HMAC', key, enc.encode(signed))); - let binary = ''; - for (const b of sig) { - binary += String.fromCharCode(b); - } - const expectedToken = btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); - - expect(send!.body.platformToken).toBe(expectedToken); - }); -}); - // --------------------------------------------------------------------------- // Platform capability gate // --------------------------------------------------------------------------- @@ -2281,7 +2219,7 @@ describe('email platform capability', () => { await setUserEmail(user.id, 'owner@example.com'); const project = await createTestProject(env.db, user.id); await seedVerifiedPair(project.id); - const fetchMock = mockCfWithProxy(); + const fetchMock = mockCfWithEmail(); const kvPut = vi.spyOn(env.ROUTING, 'put'); const bindings = capabilityEnv(false, emailEnv()); diff --git a/platform/packages/api/test/integration/api-projects.test.ts b/platform/packages/api/test/integration/api-projects.test.ts index dcd09e844..ec9c33d5a 100644 --- a/platform/packages/api/test/integration/api-projects.test.ts +++ b/platform/packages/api/test/integration/api-projects.test.ts @@ -2872,7 +2872,11 @@ describe('GET /projects/:id/logs limit validation', () => { describe('POST /projects — owner email destination auto-add', () => { // The gate the route checks. Without a platform mail domain there is no // sender to allow-list a recipient for, so the auto-add stays inert. - const emailEnv = () => ({ ...env, EMAIL_SENDER_DOMAIN: 'mail.staging.void.cloud' }); + const emailEnv = () => ({ + ...env, + EMAIL_GATEWAY_ORIGIN: 'https://void-email-gateway-staging.voidzer0.workers.dev', + EMAIL_SENDER_DOMAIN: 'mail.voidcloud.dev', + }); // `respond` may be async so a test can commit a competing write (project // teardown's cascade) while the route is awaiting Cloudflare. The stub is 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 52d52e902..d90473f67 100644 --- a/platform/packages/api/test/integration/auth-email-verification.test.ts +++ b/platform/packages/api/test/integration/auth-email-verification.test.ts @@ -779,7 +779,11 @@ describe('email verification gating on account linking', () => { // routes run against the same PGlite session, so the login's transaction // has fully committed before the auto-add gets its answer — exactly the // ordering the reviewer described. - const emailEnv = () => ({ ...env, EMAIL_SENDER_DOMAIN: 'mail.staging.void.cloud' }); + const emailEnv = () => ({ + ...env, + EMAIL_GATEWAY_ORIGIN: 'https://void-email-gateway-staging.voidzer0.workers.dev', + EMAIL_SENDER_DOMAIN: 'mail.voidcloud.dev', + }); function stubEmailRoutingOver( base: typeof fetch, diff --git a/platform/packages/api/test/integration/email-admission.test.ts b/platform/packages/api/test/integration/email-admission.test.ts index 8b12269ed..662791b00 100644 --- a/platform/packages/api/test/integration/email-admission.test.ts +++ b/platform/packages/api/test/integration/email-admission.test.ts @@ -31,6 +31,7 @@ import { import { setEmailRecipientPolicy } from '../../src/email/settings.ts'; import { emailDestinations, projects, users } from '../../src/schema.ts'; import { + captureQueries, clearTables, createTestProject, createTestUser, @@ -81,6 +82,18 @@ async function fixture() { inbound_status: 'ready', }) .onConflictDoNothing(); + await env.db + .insert(emailDomainRoutes) + .values({ + id: 'shared-alias-route', + domain: 'shared-alias.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, @@ -522,6 +535,38 @@ describe('authoritative email admission', () => { expect((await getProjectEmailUsage(env.db, project.id)).attempts).toBe(1); }); + it('admits a multi-tag shared forward only for the project named by the first segment', async () => { + const project = await fixture(); + const receiptId = 'multi-tag-forward'; + await recordEmailReceipt(env.db, { + receiptId, + projectId: project.id, + status: 'handler_completed', + route: receiptRoute(), + }); + + const admitted = await admitEmailAction(env.db, { + ...input(project.id, 'owned-multi-tag-forward'), + kind: 'forward', + from: 'acme+support+forward.run@mail.example.com', + transport: 'native_forward', + receiptId, + }); + expect(admitted.recipients).toMatchObject([{ state: 'reserved', errorCode: null }]); + + const crossProject = await admitEmailAction(env.db, { + ...input(project.id, 'cross-project-multi-tag-forward'), + kind: 'forward', + from: 'other+support+forward.run@mail.example.com', + transport: 'native_forward', + receiptId, + }); + expect(crossProject.recipients).toMatchObject([ + { state: 'rejected', errorCode: 'INVALID_FROM' }, + ]); + expect((await getProjectEmailUsage(env.db, project.id)).attempts).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({ @@ -908,6 +953,73 @@ describe('authoritative email admission', () => { ).rejects.toMatchObject({ code: 'INVALID_STATE' }); }); + it('keeps admission database round trips constant at the maximum recipient batch', async () => { + const project = await fixture(); + await setEmailRecipientPolicy(env.db, env.ROUTING, { mode: 'any', domains: [] }); + await setProjectEmailLimits(env.db, project.id, { burst: 1_000, monthly: 1_000 }); + + const single = await captureQueries(env.db, () => + admitEmailAction(env.db, input(project.id, 'single-query-count', ['single@external.test'])), + ); + const recipients = Array.from( + { length: 50 }, + (_, index) => `recipient@external-${String(index).padStart(2, '0')}.test`, + ); + const maximum = await captureQueries(env.db, () => + admitEmailAction(env.db, input(project.id, 'maximum-query-count', recipients)), + ); + + expect(single.result.recipients).toHaveLength(1); + expect(maximum.result.recipients).toHaveLength(50); + expect(single.queries.length).toBeGreaterThan(0); + expect(maximum.queries).toHaveLength(single.queries.length); + }); + + it('preserves input priority when a maximum batch crosses the quota', async () => { + const project = await fixture(); + await setEmailRecipientPolicy(env.db, env.ROUTING, { mode: 'any', domains: [] }); + await setProjectEmailLimits(env.db, project.id, { burst: 25, monthly: 25 }); + const recipients = Array.from( + { length: 50 }, + (_, index) => `priority-${String(index).padStart(2, '0')}@external.test`, + ); + + const result = await admitEmailAction(env.db, input(project.id, 'maximum-quota', recipients)); + const byRecipient = new Map( + result.recipients.map((recipient) => [recipient.recipient, recipient]), + ); + for (const [index, recipient] of recipients.entries()) { + expect(byRecipient.get(recipient)).toMatchObject( + index < 25 + ? { state: 'reserved', errorCode: null } + : { state: 'rejected', errorCode: 'QUOTA_EXCEEDED' }, + ); + } + }); + + it('keeps shared platform domains consent-gated in a mixed batch', async () => { + const project = await fixture(); + await setEmailRecipientPolicy(env.db, env.ROUTING, { mode: 'any', domains: [] }); + + const result = await admitEmailAction( + env.db, + input(project.id, 'shared-domain-protection', [ + 'external@external.test', + 'other-project@shared-alias.example.com', + ]), + ); + expect(result.recipients).toEqual( + expect.arrayContaining([ + expect.objectContaining({ recipient: 'external@external.test', state: 'reserved' }), + expect.objectContaining({ + recipient: 'other-project@shared-alias.example.com', + state: 'rejected', + errorCode: 'UNVERIFIED_DESTINATION', + }), + ]), + ); + }); + 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); diff --git a/platform/packages/api/test/integration/helpers.ts b/platform/packages/api/test/integration/helpers.ts index 0b0604c6f..fdfe608a7 100644 --- a/platform/packages/api/test/integration/helpers.ts +++ b/platform/packages/api/test/integration/helpers.ts @@ -73,12 +73,15 @@ export type TestEnv = { AUTH_REDIRECT_URI?: string; DEV_AUTH_BYPASS?: string; SITE_DOMAIN?: string; + EMAIL?: SendEmail; + EMAIL_GATEWAY_ORIGIN?: string; /** * Platform mail zone for the environment (`mail.void.cloud` in production, - * `mail.staging.void.cloud` in staging). Left UNSET by `setupEnv` on + * `mail.voidcloud.dev` in staging). Left UNSET by `setupEnv` on * purpose: every reader fails closed without it, and a test that wants the * email paths must opt in with `{ ...env, EMAIL_SENDER_DOMAIN: '...' }` so - * the fail-closed branch stays reachable. + * the fail-closed branch stays reachable. Verification-mail tests also set + * `EMAIL_GATEWAY_ORIGIN` explicitly. */ EMAIL_SENDER_DOMAIN?: string; REQUESTS_DATASET?: string; @@ -396,6 +399,26 @@ class MemoryR2Bucket { let pglite: PGlite | undefined; let pgPool: pg.Pool | undefined; +type QueryCapture = { active: boolean; queries: Array }; +const queryCaptures = new WeakMap(); + +export async function captureQueries( + db: Db, + run: () => Promise, +): Promise<{ result: T; queries: Array }> { + const capture = queryCaptures.get(db); + if (!capture || capture.active) { + throw new Error('query capture is unavailable or already active'); + } + capture.active = true; + capture.queries = []; + try { + const result = await run(); + return { result, queries: [...capture.queries] }; + } finally { + capture.active = false; + } +} export async function setupEnv(): Promise { const kv = new MemoryKVNamespace(); @@ -404,17 +427,26 @@ export async function setupEnv(): Promise { const staticAssetsR2 = new MemoryR2Bucket(); const databaseUrl = process.env.VOID_TEST_DATABASE_URL; + const queryCapture: QueryCapture = { active: false, queries: [] }; + const logger = { + logQuery(query: string) { + if (queryCapture.active) { + queryCapture.queries.push(query); + } + }, + }; let db: Db; if (databaseUrl) { pgPool = new pg.Pool({ connectionString: databaseUrl }); - db = drizzlePg(pgPool, { schema }) as unknown as Db; + db = drizzlePg(pgPool, { schema, logger }) as unknown as Db; } else { pglite = new PGlite({ loadDataDir: await loadPGliteTemplateBundle(), relaxedDurability: true, }); - db = drizzle(pglite, { schema }) as unknown as Db; + db = drizzle(pglite, { schema, logger }) as unknown as Db; } + queryCaptures.set(db, queryCapture); // Register the test db so the vi.mock in setup.ts routes createDb() here setTestDb(db); 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 54fce3669..dfb9ce643 100644 --- a/platform/packages/api/test/integration/platform-access-protection.test.ts +++ b/platform/packages/api/test/integration/platform-access-protection.test.ts @@ -149,6 +149,16 @@ async function githubSignature(body: string): Promise { } describe('Access-protected platform requests', () => { + it('admits only the token-authenticated confirmation route without an Access assertion', async () => { + const confirmation = await request('/email/destinations/confirm?token=invalid.signature'); + expect(confirmation.status).toBe(400); + expect(confirmation.headers.get('cache-control')).toBe('no-store'); + expect(confirmation.headers.get('referrer-policy')).toBe('no-referrer'); + expect( + (await request('/email/destinations/confirm/extra?token=invalid.signature')).status, + ).toBe(403); + }); + it('admits the installer email probe only with both service Access and installation proof', async () => { const call = (access?: string, probe = 'probe-fixture') => app.fetch( 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 6941c3b7b..ea617fe61 100644 --- a/platform/packages/api/test/unit/email-cf-customer.test.ts +++ b/platform/packages/api/test/unit/email-cf-customer.test.ts @@ -40,7 +40,7 @@ describe('cf-customer client', () => { ); const client = createCfCustomerClient(CREDENTIAL); - const result = await client.verifyToken(); + const result = await client.verifyToken(ACCOUNT); const { url, init } = lastCall(fetchMock); expect(url).toBe(`${CF_CUSTOMER_API_BASE}/user/tokens/verify`); @@ -54,14 +54,44 @@ describe('cf-customer client', () => { }); it('throws CloudflareApiError carrying the HTTP status on envelope failure', async () => { - fetchMock.mockResolvedValueOnce(cfError('invalid token', 401)); + fetchMock.mockImplementation(async () => cfError('invalid token', 401)); const client = createCfCustomerClient(CREDENTIAL); - const error = await client.verifyToken().catch((err: unknown) => err); + const error = await client.verifyToken(ACCOUNT).catch((err: unknown) => err); expect(error).toBeInstanceOf(CloudflareApiError); expect((error as CloudflareApiError).status).toBe(401); expect((error as CloudflareApiError).message).toContain('invalid token'); }); + + it('verifies an account token when the user endpoint rejects it', async () => { + fetchMock + .mockResolvedValueOnce(cfError('invalid user token', 401)) + .mockResolvedValueOnce(cfSuccess({ id: 'account-token', status: 'active' })); + + await expect(createCfCustomerClient(CREDENTIAL).verifyToken(ACCOUNT)).resolves.toEqual({ + id: 'account-token', + status: 'active', + }); + expect(lastCall(fetchMock).url).toBe( + `${CF_CUSTOMER_API_BASE}/accounts/${ACCOUNT}/tokens/verify`, + ); + }); + + it('does not retry a provider outage as another token type', async () => { + fetchMock.mockResolvedValueOnce(cfError('unavailable', 503)); + await expect(createCfCustomerClient(CREDENTIAL).verifyToken(ACCOUNT)).rejects.toMatchObject({ + status: 503, + }); + expect(fetchMock).toHaveBeenCalledTimes(1); + }); + + it('retains an inactive user-token result without trying the account endpoint', async () => { + fetchMock.mockResolvedValueOnce(cfSuccess({ id: 'expired-token', status: 'expired' })); + await expect(createCfCustomerClient(CREDENTIAL).verifyToken(ACCOUNT)).resolves.toMatchObject({ + status: 'expired', + }); + expect(fetchMock).toHaveBeenCalledTimes(1); + }); }); describe('findZone', () => { diff --git a/platform/packages/api/test/unit/email-platform-token.test.ts b/platform/packages/api/test/unit/email-platform-token.test.ts deleted file mode 100644 index cd3ae199c..000000000 --- a/platform/packages/api/test/unit/email-platform-token.test.ts +++ /dev/null @@ -1,287 +0,0 @@ -/** - * Unit coverage for the two api-side crypto surfaces `void/email` depends on: - * - * - `auth/confirm-token.ts` — the HMAC token that IS the auth on the public - * destination-confirmation endpoint. - * - `email/send-verification.ts` — the content-bound HMAC the proxy's - * `POST /email/internal/send` requires: - * `sentinel.unixSeconds.sha256(from|to|mimeBase64)`. - * - * The api SIGNS and the proxy VERIFIES, in two separately-bundled workers, so - * the contract needs a test that runs both. That test lives on the proxy side - * (`packages/proxy/test/unit/email-platform-token.test.ts`): importing the - * proxy entry from here would drag `proxy/src/ai.ts` into the api typecheck, - * which runs with the default lib for Miniflare's DOM-compatible `URL` types - * and cannot compile the worker sources. What stays here is the api's own - * half — what it signs, and the mirrored sentinel it signs with. - */ - -import { describe, expect, it, vi } from 'vite-plus/test'; -import { signConfirmToken, verifyConfirmToken } from '../../src/auth/confirm-token.ts'; -import { - hashSendContent, - PLATFORM_INTERNAL_EMAIL_SENTINEL, - sendPlatformVerificationEmail, -} from '../../src/email/send-verification.ts'; -import type { ApiEnv } from '../../src/env.ts'; - -const SECRET = 'test-platform-secret'; - -/** - * The platform mail zone is a per-environment var, never a baked-in literal. - * Staging's value here on purpose: a test pinned to production's domain would - * pass against code that ignored the var entirely. - */ -const MAIL_DOMAIN = 'mail.staging.void.cloud'; - -const DAY = 24 * 60 * 60; - -function payload(overrides: Partial[0]> = {}) { - const now = Math.floor(Date.now() / 1000); - return { - v: 1 as const, - pid: 'proj_x', - did: 'edst_x', - addr: 'a@b.com', - iat: now, - exp: now + DAY, - ...overrides, - }; -} - -// --------------------------------------------------------------------------- -// confirm-token -// --------------------------------------------------------------------------- - -describe('signConfirmToken / verifyConfirmToken', () => { - it('round-trips a well-formed payload', async () => { - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken(payload({ iat: now, exp: now + DAY }), SECRET); - const decoded = await verifyConfirmToken(token, SECRET, now); - expect(decoded).toMatchObject({ v: 1, pid: 'proj_x', did: 'edst_x', addr: 'a@b.com' }); - }); - - it('rejects a token signed with a different secret', async () => { - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken(payload(), 'some-other-secret'); - expect(await verifyConfirmToken(token, SECRET, now)).toBeNull(); - }); - - it('rejects a tampered payload', async () => { - // Re-encode the payload with a different destination id but keep the - // original signature — the classic "confirm someone else's row" attempt. - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken(payload(), SECRET); - const [body, sig] = token.split('.'); - const decoded = JSON.parse( - new TextDecoder().decode( - Uint8Array.from(atob(body!.replace(/-/g, '+').replace(/_/g, '/')), (ch) => - ch.charCodeAt(0), - ), - ), - ) as Record; - decoded.did = 'edst_someone_else'; - const reencoded = btoa(JSON.stringify(decoded)) - .replace(/\+/g, '-') - .replace(/\//g, '_') - .replace(/=+$/, ''); - - expect(await verifyConfirmToken(`${reencoded}.${sig}`, SECRET, now)).toBeNull(); - }); - - it.each([ - ['no separator', 'notatoken'], - ['three parts', 'a.b.c'], - ['empty signature', 'abc.'], - ['empty body', '.abc'], - ])('rejects a structurally invalid token (%s)', async (_label, token) => { - expect(await verifyConfirmToken(token, SECRET)).toBeNull(); - }); - - it('rejects a payload with the wrong schema version', async () => { - const now = Math.floor(Date.now() / 1000); - // A future v2 token must not be accepted by a v1 verifier — the whole - // point of the version field is that a shape change invalidates old links. - const token = await signConfirmToken( - { ...payload(), v: 2 } as unknown as Parameters[0], - SECRET, - ); - expect(await verifyConfirmToken(token, SECRET, now)).toBeNull(); - }); - - it('rejects an expired token, including exactly at exp', async () => { - const now = Math.floor(Date.now() / 1000); - const expired = await signConfirmToken(payload({ iat: now - DAY, exp: now - 1 }), SECRET); - expect(await verifyConfirmToken(expired, SECRET, now)).toBeNull(); - - // `exp <= now` — the boundary second is already dead. - const atBoundary = await signConfirmToken(payload({ iat: now - DAY, exp: now }), SECRET); - expect(await verifyConfirmToken(atBoundary, SECRET, now)).toBeNull(); - - // One second of life left. - const alive = await signConfirmToken(payload({ iat: now - DAY, exp: now + 1 }), SECRET); - expect(await verifyConfirmToken(alive, SECRET, now)).not.toBeNull(); - }); - - it('accepts an iat up to 60s in the future (clock skew between workers)', async () => { - const now = Math.floor(Date.now() / 1000); - const token = await signConfirmToken(payload({ iat: now + 30, exp: now + DAY }), SECRET); - const decoded = await verifyConfirmToken(token, SECRET, now); - expect(decoded).not.toBeNull(); - expect(decoded?.iat).toBe(now + 30); - }); - - it('rejects an iat past the 60s skew tolerance', async () => { - const now = Math.floor(Date.now() / 1000); - // 61s: the boundary. Anything beyond it is a forged token or an issuing - // worker whose clock is wrong enough that its tokens should not be honored. - const atBoundary = await signConfirmToken(payload({ iat: now + 61, exp: now + DAY }), SECRET); - expect(await verifyConfirmToken(atBoundary, SECRET, now)).toBeNull(); - - const wayOut = await signConfirmToken(payload({ iat: now + 5 * 60, exp: now + DAY }), SECRET); - expect(await verifyConfirmToken(wayOut, SECRET, now)).toBeNull(); - }); -}); - -// --------------------------------------------------------------------------- -// hashSendContent -// --------------------------------------------------------------------------- - -describe('hashSendContent', () => { - const FROM = `noreply@${MAIL_DOMAIN}`; - - it('is a stable lowercase hex SHA-256', async () => { - const h = await hashSendContent(FROM, 'user@example.com', 'AAAA'); - expect(h).toMatch(/^[0-9a-f]{64}$/); - expect(await hashSendContent(FROM, 'user@example.com', 'AAAA')).toBe(h); - }); - - it('changes when any of the three bound fields changes', async () => { - const base = await hashSendContent(FROM, 'user@example.com', 'AAAA'); - expect(await hashSendContent(`noreply@mail.void.cloud`, 'user@example.com', 'AAAA')).not.toBe( - base, - ); - expect(await hashSendContent(FROM, 'other@example.com', 'AAAA')).not.toBe(base); - expect(await hashSendContent(FROM, 'user@example.com', 'AAAB')).not.toBe(base); - }); - - it('does not case-fold its inputs', async () => { - // The proxy recomputes the hash from the body VERBATIM, so the api must - // hash exactly what it puts on the wire — any normalization here would - // have to be mirrored there or every send would 403. - const lower = await hashSendContent('a@b.com', 'c@d.com', 'mime'); - expect(await hashSendContent('A@B.com', 'c@d.com', 'mime')).not.toBe(lower); - expect(await hashSendContent('a@b.com', 'C@D.com', 'mime')).not.toBe(lower); - }); - - it('is not blindly concatenation-collidable across the `|` separator', async () => { - // `a|b|c` must not hash the same as a shifted split of the same bytes. - // No legal address or base64 character is `|`, which is why the separator - // is safe — this pins that the fields are actually separated at all. - const a = await hashSendContent('x@y.com', 'p@q.com', 'MIME'); - const b = await hashSendContent('x@y.com|p@q.com', '', 'MIME'); - expect(a).not.toBe(b); - }); -}); - -// --------------------------------------------------------------------------- -// api -> proxy: the real signer against the real verifier -// --------------------------------------------------------------------------- - -describe('platform-internal send: what the api signs', () => { - type CapturedSend = { - url: string; - body: { - platformToken: string; - platformTimestamp: number; - from: string; - to: string; - mimeBase64: string; - }; - }; - - /** - * Run the REAL api sender with `fetch` stubbed, and hand back the exact - * request body it would have POSTed to the proxy. - */ - async function captureApiSend( - overrides: Partial = {}, - ): Promise { - const calls: Array = []; - vi.stubGlobal( - 'fetch', - vi.fn(async (input: string | URL | Request, init?: RequestInit) => { - const url = - typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url; - calls.push({ url, body: JSON.parse(String(init?.body)) }); - return Response.json({ ok: true }); - }), - ); - try { - await sendPlatformVerificationEmail( - { - JWT_SECRET: SECRET, - EMAIL_SENDER_DOMAIN: MAIL_DOMAIN, - ...overrides, - } as unknown as ApiEnv['Bindings'], - { id: 'proj_1', slug: 'acme' }, - 'recipient@example.com', - 'confirm-token-value', - ); - } finally { - vi.unstubAllGlobals(); - } - expect(calls).toHaveLength(1); - return calls[0]!; - } - - it('posts to the proxy with the configured sender and the full token tuple', async () => { - const send = await captureApiSend(); - expect(send.url).toMatch(/\/email\/internal\/send$/); - // Derived from EMAIL_SENDER_DOMAIN, not a literal. - expect(send.body.from).toBe(`noreply@${MAIL_DOMAIN}`); - expect(send.body.to).toBe('recipient@example.com'); - expect(typeof send.body.platformToken).toBe('string'); - expect(typeof send.body.platformTimestamp).toBe('number'); - expect(Math.abs(Math.floor(Date.now() / 1000) - send.body.platformTimestamp)).toBeLessThan(60); - // The signed hash is over the mime the proxy will actually be handed. - const mime = new TextDecoder().decode( - Uint8Array.from(atob(send.body.mimeBase64), (ch) => ch.charCodeAt(0)), - ); - expect(mime).toContain(`From: noreply@${MAIL_DOMAIN}`); - expect(mime).toContain('To: recipient@example.com'); - expect(mime).toContain('/email/destinations/confirm?token=confirm-token-value'); - }); - - it('throws rather than sending when EMAIL_SENDER_DOMAIN is unset', async () => { - // Nothing is defaulted: a fallback to the production zone would sign mail - // for a domain a staging worker has no business sending from, and the - // proxy would 403 it anyway — turning a config error into a silent - // per-send failure. - const outbound = vi.fn(); - vi.stubGlobal('fetch', outbound); - try { - await expect( - sendPlatformVerificationEmail( - { JWT_SECRET: SECRET } as unknown as ApiEnv['Bindings'], - { id: 'proj_1', slug: 'acme' }, - 'recipient@example.com', - 'tok', - ), - ).rejects.toThrow(/EMAIL_SENDER_DOMAIN/); - } finally { - vi.unstubAllGlobals(); - } - expect(outbound).not.toHaveBeenCalled(); - }); - - it('the sentinel literal is the one the proxy mirrors', async () => { - // The proxy cannot import from `packages/api`, so it re-declares the - // string. A rename on one side only would 403 every platform send. - expect(PLATFORM_INTERNAL_EMAIL_SENTINEL).toBe('void-platform-internal-email-v1'); - const proxySource = await import('node:fs').then((fs) => - fs.readFileSync(new URL('../../../proxy/src/index.ts', import.meta.url).pathname, 'utf8'), - ); - expect(proxySource).toContain(`'${PLATFORM_INTERNAL_EMAIL_SENTINEL}'`); - }); -}); diff --git a/platform/packages/api/test/unit/email-verification.test.ts b/platform/packages/api/test/unit/email-verification.test.ts new file mode 100644 index 000000000..85e9b8615 --- /dev/null +++ b/platform/packages/api/test/unit/email-verification.test.ts @@ -0,0 +1,247 @@ +/** Unit coverage for confirmation tokens and verification-email delivery. */ + +import { describe, expect, it, vi } from 'vite-plus/test'; +import { signConfirmToken, verifyConfirmToken } from '../../src/auth/confirm-token.ts'; +import { sendPlatformVerificationEmail } from '../../src/email/send-verification.ts'; +import type { ApiEnv } from '../../src/env.ts'; + +const SECRET = 'test-platform-secret'; + +/** + * The platform mail zone is a per-environment var, never a baked-in literal. + * Staging's value here on purpose: a test pinned to production's domain would + * pass against code that ignored the var entirely. + */ +const MAIL_DOMAIN = 'mail.voidcloud.dev'; +const GATEWAY_ORIGIN = 'https://void-email-gateway-staging.voidzer0.workers.dev'; + +const DAY = 24 * 60 * 60; + +function payload(overrides: Partial[0]> = {}) { + const now = Math.floor(Date.now() / 1000); + return { + v: 1 as const, + pid: 'proj_x', + did: 'edst_x', + addr: 'a@b.com', + iat: now, + exp: now + DAY, + ...overrides, + }; +} + +// --------------------------------------------------------------------------- +// confirm-token +// --------------------------------------------------------------------------- + +describe('signConfirmToken / verifyConfirmToken', () => { + it('round-trips a well-formed payload', async () => { + const now = Math.floor(Date.now() / 1000); + const token = await signConfirmToken(payload({ iat: now, exp: now + DAY }), SECRET); + const decoded = await verifyConfirmToken(token, SECRET, now); + expect(decoded).toMatchObject({ v: 1, pid: 'proj_x', did: 'edst_x', addr: 'a@b.com' }); + }); + + it('rejects a token signed with a different secret', async () => { + const now = Math.floor(Date.now() / 1000); + const token = await signConfirmToken(payload(), 'some-other-secret'); + expect(await verifyConfirmToken(token, SECRET, now)).toBeNull(); + }); + + it('rejects a tampered payload', async () => { + // Re-encode the payload with a different destination id but keep the + // original signature — the classic "confirm someone else's row" attempt. + const now = Math.floor(Date.now() / 1000); + const token = await signConfirmToken(payload(), SECRET); + const [body, sig] = token.split('.'); + const decoded = JSON.parse( + new TextDecoder().decode( + Uint8Array.from(atob(body!.replace(/-/g, '+').replace(/_/g, '/')), (ch) => + ch.charCodeAt(0), + ), + ), + ) as Record; + decoded.did = 'edst_someone_else'; + const reencoded = btoa(JSON.stringify(decoded)) + .replace(/\+/g, '-') + .replace(/\//g, '_') + .replace(/=+$/, ''); + + expect(await verifyConfirmToken(`${reencoded}.${sig}`, SECRET, now)).toBeNull(); + }); + + it.each([ + ['no separator', 'notatoken'], + ['three parts', 'a.b.c'], + ['empty signature', 'abc.'], + ['empty body', '.abc'], + ])('rejects a structurally invalid token (%s)', async (_label, token) => { + expect(await verifyConfirmToken(token, SECRET)).toBeNull(); + }); + + it('rejects a payload with the wrong schema version', async () => { + const now = Math.floor(Date.now() / 1000); + // A future v2 token must not be accepted by a v1 verifier — the whole + // point of the version field is that a shape change invalidates old links. + const token = await signConfirmToken( + { ...payload(), v: 2 } as unknown as Parameters[0], + SECRET, + ); + expect(await verifyConfirmToken(token, SECRET, now)).toBeNull(); + }); + + it('rejects an expired token, including exactly at exp', async () => { + const now = Math.floor(Date.now() / 1000); + const expired = await signConfirmToken(payload({ iat: now - DAY, exp: now - 1 }), SECRET); + expect(await verifyConfirmToken(expired, SECRET, now)).toBeNull(); + + // `exp <= now` — the boundary second is already dead. + const atBoundary = await signConfirmToken(payload({ iat: now - DAY, exp: now }), SECRET); + expect(await verifyConfirmToken(atBoundary, SECRET, now)).toBeNull(); + + // One second of life left. + const alive = await signConfirmToken(payload({ iat: now - DAY, exp: now + 1 }), SECRET); + expect(await verifyConfirmToken(alive, SECRET, now)).not.toBeNull(); + }); + + it('accepts an iat up to 60s in the future (clock skew between workers)', async () => { + const now = Math.floor(Date.now() / 1000); + const token = await signConfirmToken(payload({ iat: now + 30, exp: now + DAY }), SECRET); + const decoded = await verifyConfirmToken(token, SECRET, now); + expect(decoded).not.toBeNull(); + expect(decoded?.iat).toBe(now + 30); + }); + + it('rejects an iat past the 60s skew tolerance', async () => { + const now = Math.floor(Date.now() / 1000); + // 61s: the boundary. Anything beyond it is a forged token or an issuing + // worker whose clock is wrong enough that its tokens should not be honored. + const atBoundary = await signConfirmToken(payload({ iat: now + 61, exp: now + DAY }), SECRET); + expect(await verifyConfirmToken(atBoundary, SECRET, now)).toBeNull(); + + const wayOut = await signConfirmToken(payload({ iat: now + 5 * 60, exp: now + DAY }), SECRET); + expect(await verifyConfirmToken(wayOut, SECRET, now)).toBeNull(); + }); +}); + +// --------------------------------------------------------------------------- +// verification-email delivery +// --------------------------------------------------------------------------- + +type SentMessage = { + from: string; + to: string; + subject: string; + text: string; +}; + +function verificationEnv(overrides: Partial = {}) { + const sent: Array = []; + const send = vi.fn(async (message: SentMessage) => { + sent.push(message); + }); + return { + env: { + JWT_SECRET: SECRET, + EMAIL: { send } as unknown as SendEmail, + EMAIL_SENDER_DOMAIN: MAIL_DOMAIN, + EMAIL_GATEWAY_ORIGIN: GATEWAY_ORIGIN, + PLATFORM_ENV: 'staging', + ...overrides, + } as unknown as ApiEnv['Bindings'], + send, + sent, + }; +} + +async function sendVerification(env: ApiEnv['Bindings'], token = 'confirm-token.signature') { + await sendPlatformVerificationEmail( + env, + { id: 'proj_1', slug: 'acme' }, + 'recipient@example.com', + token, + ); +} + +describe('sendPlatformVerificationEmail', () => { + it('uses the API email binding with the configured sender and public gateway link', async () => { + const { env, sent } = verificationEnv(); + const outboundFetch = vi.fn(); + vi.stubGlobal('fetch', outboundFetch); + try { + await sendVerification(env); + } finally { + vi.unstubAllGlobals(); + } + + expect(outboundFetch).not.toHaveBeenCalled(); + expect(sent).toHaveLength(1); + expect(sent[0]).toMatchObject({ + from: `noreply@${MAIL_DOMAIN}`, + to: 'recipient@example.com', + subject: '[acme] wants permission to email you', + }); + expect(sent[0]!.text).toContain( + `${GATEWAY_ORIGIN}/email/destinations/confirm?token=confirm-token.signature`, + ); + expect(sent[0]!.text).not.toContain('api.staging.void.cloud'); + }); + + it('uses the configured self-hosted public gateway instead of its protected API origin', async () => { + const { env, sent } = verificationEnv({ + AUTH_REDIRECT_URI: 'https://control.example.com/auth/callback', + EMAIL_GATEWAY_ORIGIN: 'https://mail-gateway.example.workers.dev', + PLATFORM_ENV: 'production', + PLATFORM_INSTALLATION_ID: 'installation_1', + }); + + await sendVerification(env, 'token'); + + expect(sent[0]!.text).toContain( + 'https://mail-gateway.example.workers.dev/email/destinations/confirm?token=token', + ); + expect(sent[0]!.text).not.toContain('control.example.com'); + }); + + it.each([ + 'http://gateway.example.com', + 'https://gateway.example.com/path', + 'https://gateway.example.com/', + 'https://user@gateway.example.com', + 'https://gateway.example.com?next=https://attacker.example', + ])('rejects an invalid EMAIL_GATEWAY_ORIGIN before delivery: %s', async (origin) => { + const { env, send } = verificationEnv({ EMAIL_GATEWAY_ORIGIN: origin }); + await expect(sendVerification(env)).rejects.toThrow('EMAIL_GATEWAY_ORIGIN'); + expect(send).not.toHaveBeenCalled(); + }); + + it.each([ + ['EMAIL_SENDER_DOMAIN', { EMAIL_SENDER_DOMAIN: undefined }], + ['EMAIL_GATEWAY_ORIGIN', { EMAIL_GATEWAY_ORIGIN: undefined }], + ['EMAIL binding', { EMAIL: undefined }], + ])('fails before delivery when %s is missing', async (_label, overrides) => { + const { env, send } = verificationEnv(overrides as Partial); + await expect(sendVerification(env)).rejects.toThrow(); + expect(send).not.toHaveBeenCalled(); + }); + + it('logs and swallows a delivery failure so the destination stays pending', async () => { + const { env } = verificationEnv({ + EMAIL: { + send: vi.fn(async () => { + throw new Error('provider unavailable'); + }), + } as unknown as SendEmail, + }); + const error = vi.spyOn(console, 'error').mockImplementation(() => {}); + try { + await expect(sendVerification(env)).resolves.toBeUndefined(); + expect(error).toHaveBeenCalledWith( + expect.stringContaining('project=proj_1 address=recipient@example.com'), + expect.any(Error), + ); + } finally { + error.mockRestore(); + } + }); +}); 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 d8bef8c26..f6ce923b5 100644 --- a/platform/packages/api/test/unit/platform-worker-config.test.ts +++ b/platform/packages/api/test/unit/platform-worker-config.test.ts @@ -35,6 +35,7 @@ describe('platform Worker configuration', () => { }); expect(configs.api).not.toHaveProperty('containers'); + expect(configs.api).not.toHaveProperty('send_email'); expect(configs.emailGateway).not.toHaveProperty('send_email'); expect(configs.emailGateway.vars).not.toHaveProperty('EMAIL_SHARED_ZONE_ID'); expect(JSON.stringify(configs)).not.toContain('BuildManager'); diff --git a/platform/packages/api/test/unit/provision.test.ts b/platform/packages/api/test/unit/provision.test.ts index c62f79a7e..2d9165c33 100644 --- a/platform/packages/api/test/unit/provision.test.ts +++ b/platform/packages/api/test/unit/provision.test.ts @@ -354,7 +354,7 @@ describe('provisionBindings', () => { it('injects __VOID_EMAIL_DOMAIN from the configured platform mail domain', async () => { // Per-environment, never hard-coded: production is `mail.void.cloud` and - // staging `mail.staging.void.cloud`, and the proxy validates senders + // staging `mail.voidcloud.dev`, and the proxy validates senders // against its own copy of the same value. const manifest: DeployManifest = { version: 1, bindings: {} }; @@ -366,13 +366,13 @@ describe('provisionBindings', () => { manifest, JWT_SECRET, 'void-proxy', - { projectSlug: PROJECT_SLUG, emailSenderDomain: 'mail.staging.void.cloud' }, + { projectSlug: PROJECT_SLUG, emailSenderDomain: 'mail.voidcloud.dev' }, ); expect(bindings).toContainEqual({ type: 'plain_text', name: '__VOID_EMAIL_DOMAIN', - text: 'mail.staging.void.cloud', + text: 'mail.voidcloud.dev', }); }); diff --git a/platform/packages/api/test/unit/reserved-bindings.test.ts b/platform/packages/api/test/unit/reserved-bindings.test.ts index dca6ae2c1..8a1902204 100644 --- a/platform/packages/api/test/unit/reserved-bindings.test.ts +++ b/platform/packages/api/test/unit/reserved-bindings.test.ts @@ -32,7 +32,7 @@ async function platformBindingNames(): Promise> { EMPTY_MANIFEST, 'test-jwt-secret', 'void-proxy', - { projectSlug: 'my-app', emailSenderDomain: 'mail.staging.void.cloud' }, + { projectSlug: 'my-app', emailSenderDomain: 'mail.voidcloud.dev' }, ); return provisioned.map((binding) => binding.name); } @@ -47,7 +47,7 @@ describe('reserved binding names cover every platform-injected binding', () => { EMPTY_MANIFEST, 'test-jwt-secret', 'void-proxy', - { projectSlug: 'my-app', emailSenderDomain: 'mail.staging.void.cloud' }, + { projectSlug: 'my-app', emailSenderDomain: 'mail.voidcloud.dev' }, ); expect(provisioned.length).toBeGreaterThan(0); for (const binding of provisioned) { diff --git a/platform/packages/api/wrangler.jsonc b/platform/packages/api/wrangler.jsonc index 632a845e8..3eb61e04f 100644 --- a/platform/packages/api/wrangler.jsonc +++ b/platform/packages/api/wrangler.jsonc @@ -6,8 +6,10 @@ "observability": { "enabled": true, }, + // Both hosted PostgreSQL origins are in AWS us-east-2. "placement": { - "mode": "smart", + "mode": "targeted", + "region": "aws:us-east-2", }, "limits": { "cpu_ms": 300000, @@ -154,7 +156,11 @@ ], }, "send_email": [ - { "name": "EMAIL", "remote": true, "allowed_sender_addresses": ["noreply@void.cloud"] }, + { + "name": "EMAIL", + "remote": true, + "allowed_sender_addresses": ["noreply@void.cloud", "noreply@mail.void.cloud"], + }, ], "triggers": { "crons": ["0 * * * *", "*/2 * * * *"], @@ -168,6 +174,10 @@ "TAIL_SERVICE_NAME": "void-tail", // Must match packages/proxy/wrangler.jsonc — the proxy validates senders against its own copy. "EMAIL_SENDER_DOMAIN": "mail.void.cloud", + "EMAIL_GATEWAY_ORIGIN": "https://void-email-gateway.voidzer0.workers.dev", + "EMAIL_SHARED_ACCOUNT_ID": "f721b8e515fbab226f41e2807edaece7", + "EMAIL_SHARED_ZONE_ID": "5b66f5cb84fd7dcfdd0170515e622181", + "EMAIL_SHARED_INGRESS_NAME": "void-email-gateway", // Bucket name plumbing for the presigned R2 PUT URL path. Must match the // `r2_buckets[].bucket_name` value above — the binding surfaces an // R2Bucket object but not its name, and the presigner needs the name. @@ -293,7 +303,11 @@ ], }, "send_email": [ - { "name": "EMAIL", "remote": true, "allowed_sender_addresses": ["noreply@void.cloud"] }, + { + "name": "EMAIL", + "remote": true, + "allowed_sender_addresses": ["noreply@void.cloud", "noreply@mail.void.cloud"], + }, ], "routes": [{ "pattern": "api.void.cloud", "custom_domain": true }], "vars": { @@ -303,6 +317,10 @@ "REQUESTS_DATASET": "void_requests", "TAIL_SERVICE_NAME": "void-tail", "EMAIL_SENDER_DOMAIN": "mail.void.cloud", + "EMAIL_GATEWAY_ORIGIN": "https://void-email-gateway.voidzer0.workers.dev", + "EMAIL_SHARED_ACCOUNT_ID": "f721b8e515fbab226f41e2807edaece7", + "EMAIL_SHARED_ZONE_ID": "5b66f5cb84fd7dcfdd0170515e622181", + "EMAIL_SHARED_INGRESS_NAME": "void-email-gateway", "R2_STATIC_ASSETS_BUCKET": "void-static-assets-overflow", }, }, @@ -419,7 +437,12 @@ }, ], }, - "send_email": [{ "name": "EMAIL" }], + "send_email": [ + { + "name": "EMAIL", + "allowed_sender_addresses": ["noreply@void.cloud", "noreply@mail.voidcloud.dev"], + }, + ], "routes": [{ "pattern": "api.staging.void.cloud", "custom_domain": true }], "vars": { "CRON_FIRES_QUEUE_NAME": "void-cron-fires-staging", @@ -431,7 +454,11 @@ "AUTH_REDIRECT_URI": "https://api.staging.void.cloud/auth/callback", "LOGS_DATASET": "void_logs_staging", "REQUESTS_DATASET": "void_requests_staging", - "EMAIL_SENDER_DOMAIN": "mail.staging.void.cloud", + "EMAIL_SENDER_DOMAIN": "mail.voidcloud.dev", + "EMAIL_GATEWAY_ORIGIN": "https://void-email-gateway-staging.voidzer0.workers.dev", + "EMAIL_SHARED_ACCOUNT_ID": "f721b8e515fbab226f41e2807edaece7", + "EMAIL_SHARED_ZONE_ID": "57fc5c5286e74843013704368205de38", + "EMAIL_SHARED_INGRESS_NAME": "void-email-gateway-staging", "PLATFORM_ENV": "staging", "PROXY_URL": "https://proxy.staging.void.cloud", "TAIL_SERVICE_NAME": "void-tail-staging", diff --git a/platform/packages/dispatch/src/metering.ts b/platform/packages/dispatch/src/metering.ts index 255eef737..5cf8dcc95 100644 --- a/platform/packages/dispatch/src/metering.ts +++ b/platform/packages/dispatch/src/metering.ts @@ -156,8 +156,8 @@ export function recordPlatformLog( const message = `Void platform: your worker did not respond within ${data.timeoutMs} ms. ` + `${data.method} ${truncateUtf8(pathname, MAX_LOG_PATH_BYTES)} was cut short and ` + - `returned ${data.status}. Your code keeps running to completion; the platform ` + - `does not cancel it.`; + `returned ${data.status}. The operation may still have side effects; ` + + `check its outcome before retrying.`; try { env.LOGS.writeDataPoint({ diff --git a/platform/packages/email-gateway/src/index.ts b/platform/packages/email-gateway/src/index.ts index 6493479ff..44a648a29 100644 --- a/platform/packages/email-gateway/src/index.ts +++ b/platform/packages/email-gateway/src/index.ts @@ -22,6 +22,10 @@ const decoder = new TextDecoder(); const MAX_HEADER_BYTES = 128 * 1024; const MAX_ENVELOPE_HEADER = 320; const MAX_CONCURRENT_DELIVERIES = 2; +const CONFIRMATION_PATH = '/email/destinations/confirm'; +const MAX_CONFIRMATION_TOKEN_LENGTH = 4 * 1024; +const MAX_CONFIRMATION_RESPONSE_BYTES = 32 * 1024; +const CONFIRMATION_DEADLINE_MS = 5_000; let activeDeliveries = 0; class MimeHeaderError extends Error { @@ -575,6 +579,138 @@ async function probe(request: Request, env: Env): Promise { } } +function confirmationResponse( + body: BodyInit | null, + status: number, + contentType?: string | null, +): Response { + const headers = new Headers({ + 'cache-control': 'no-store', + 'referrer-policy': 'no-referrer', + 'x-content-type-options': 'nosniff', + }); + if (contentType) { + headers.set('content-type', contentType); + } + return new Response(body, { status, headers }); +} + +async function readConfirmationResponse( + response: Response, + deadline: number, + controller: AbortController, +): Promise { + const declared = Number(response.headers.get('content-length')); + if (Number.isFinite(declared) && declared > MAX_CONFIRMATION_RESPONSE_BYTES) { + throw new Error('confirmation response too large'); + } + const reader = response.body?.getReader(); + if (!reader) { + return null; + } + const result = new Uint8Array(MAX_CONFIRMATION_RESPONSE_BYTES); + let size = 0; + try { + while (true) { + const remaining = deadline - Date.now(); + if (remaining <= 0) { + throw new Error('confirmation response timeout'); + } + let timer: ReturnType | undefined; + const chunk = await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('confirmation response timeout')); + }, remaining); + }), + ]).finally(() => { + if (timer !== undefined) { + clearTimeout(timer); + } + }); + if (chunk.done) { + return result.slice(0, size); + } + size += chunk.value.byteLength; + if (size > result.byteLength) { + throw new Error('confirmation response too large'); + } + result.set(chunk.value, size - chunk.value.byteLength); + } + } finally { + void reader.cancel().catch(() => {}); + try { + reader.releaseLock(); + } catch { + // A timed-out read may still be settling after cancellation. + } + } +} + +async function confirmDestination(request: Request, env: Env): Promise { + const url = new URL(request.url); + const entries = [...url.searchParams.entries()]; + if ( + entries.length !== 1 || + entries[0]![0] !== 'token' || + !entries[0]![1] || + entries[0]![1].length > MAX_CONFIRMATION_TOKEN_LENGTH || + !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(entries[0]![1]) + ) { + return confirmationResponse(null, 400); + } + if (env.PLATFORM_TRAFFIC_STATE === 'staging' || env.PLATFORM_TRAFFIC_STATE === 'sandbox-drain') { + return confirmationResponse(null, 503); + } + + const deadline = Date.now() + CONFIRMATION_DEADLINE_MS; + const controller = new AbortController(); + let response: Response | undefined; + let timer: ReturnType | undefined; + try { + const target = new URL(`https://api${CONFIRMATION_PATH}`); + target.searchParams.set('token', entries[0]![1]); + const serviceRequest = env.API.fetch(target.toString(), { + method: 'GET', + redirect: 'manual', + signal: controller.signal, + }); + void serviceRequest.then( + (lateResponse) => { + if (controller.signal.aborted && lateResponse !== response) { + void lateResponse.body?.cancel().catch(() => {}); + } + }, + () => {}, + ); + response = await Promise.race([ + serviceRequest, + new Promise((_, reject) => { + timer = setTimeout(() => { + controller.abort(); + reject(new Error('confirmation request timeout')); + }, CONFIRMATION_DEADLINE_MS); + }), + ]); + if (timer !== undefined) { + clearTimeout(timer); + timer = undefined; + } + const body = await readConfirmationResponse(response, deadline, controller); + return confirmationResponse(body, response.status, response.headers.get('content-type')); + } catch { + return confirmationResponse(null, 503); + } finally { + controller.abort(); + if (timer !== undefined) { + clearTimeout(timer); + } + void response?.body?.cancel().catch(() => {}); + } +} + export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { const url = new URL(request.url); @@ -586,6 +722,9 @@ export default { emailProtocolVersion: 1, }); } + if (request.method === 'GET' && url.pathname === CONFIRMATION_PATH) { + return confirmDestination(request, env); + } if (request.method !== 'POST') { return new Response(null, { status: 404 }); } diff --git a/platform/packages/email-gateway/test/unit/gateway.test.ts b/platform/packages/email-gateway/test/unit/gateway.test.ts index e04c43b72..be9a0d493 100644 --- a/platform/packages/email-gateway/test/unit/gateway.test.ts +++ b/platform/packages/email-gateway/test/unit/gateway.test.ts @@ -101,6 +101,169 @@ describe('dedicated email gateway', () => { }); }); + it('relays the public confirmation route through the fixed API service path only', async () => { + const apiFetch = vi.fn(async (input: unknown, init?: RequestInit) => { + expect(String(input)).toBe('https://api/email/destinations/confirm?token=payload.signature'); + const forwarded = new Request(String(input), init); + expect(forwarded.method).toBe('GET'); + expect([...forwarded.headers]).toEqual([]); + return new Response('

Confirmed

', { + headers: { + 'content-type': 'text/html; charset=UTF-8', + 'set-cookie': 'must-not-leave-the-api=1', + }, + }); + }); + const response = await gateway.fetch( + new Request('https://gateway.example/email/destinations/confirm?token=payload.signature', { + headers: { + authorization: 'Bearer untrusted-client-value', + cookie: 'untrusted=1', + 'cf-access-jwt-assertion': 'untrusted-client-value', + }, + }), + env(apiFetch), + context, + ); + + expect(response.status).toBe(200); + expect(await response.text()).toContain('Confirmed'); + expect(response.headers.get('content-type')).toBe('text/html; charset=UTF-8'); + expect(response.headers.get('cache-control')).toBe('no-store'); + expect(response.headers.get('referrer-policy')).toBe('no-referrer'); + expect(response.headers.get('set-cookie')).toBeNull(); + expect(apiFetch).toHaveBeenCalledTimes(1); + }); + + it.each([ + ['missing', ''], + ['wrong key', '?other=payload.signature'], + ['extra key', '?token=payload.signature&next=https://attacker.example'], + ['repeated token', '?token=one.signature&token=two.signature'], + ['malformed token', '?token=not-a-signed-token'], + ['oversized token', `?token=${'a'.repeat(4097)}.signature`], + ])('rejects a %s confirmation query', async (_label, query) => { + const apiFetch = vi.fn(); + const response = await gateway.fetch( + new Request(`https://gateway.example/email/destinations/confirm${query}`), + env(apiFetch), + context, + ); + + expect(response.status).toBe(400); + expect(response.headers.get('cache-control')).toBe('no-store'); + expect(response.headers.get('referrer-policy')).toBe('no-referrer'); + expect(apiFetch).not.toHaveBeenCalled(); + }); + + it.each(['staging', 'sandbox-drain'])('gates confirmation traffic while %s', async (state) => { + const apiFetch = vi.fn(); + const response = await gateway.fetch( + new Request('https://gateway.example/email/destinations/confirm?token=payload.signature'), + { ...env(apiFetch), PLATFORM_TRAFFIC_STATE: state } as never, + context, + ); + + expect(response.status).toBe(503); + expect(response.headers.get('cache-control')).toBe('no-store'); + expect(apiFetch).not.toHaveBeenCalled(); + }); + + it('preserves the API capability response for an installation without email', async () => { + const response = await gateway.fetch( + new Request('https://gateway.example/email/destinations/confirm?token=payload.signature'), + env(async () => + Response.json( + { error: 'platform capability unavailable', capability: 'email' }, + { status: 501 }, + ), + ), + context, + ); + + expect(response.status).toBe(501); + expect(await response.json()).toMatchObject({ capability: 'email' }); + expect(response.headers.get('cache-control')).toBe('no-store'); + }); + + it('bounds the confirmation service request and response', async () => { + const oversized = await gateway.fetch( + new Request('https://gateway.example/email/destinations/confirm?token=payload.signature'), + env( + async () => + new Response('oversized', { headers: { 'content-length': String(32 * 1024 + 1) } }), + ), + context, + ); + expect(oversized.status).toBe(503); + + vi.useFakeTimers(); + try { + let signal: AbortSignal | undefined; + let markStarted!: () => void; + const started = new Promise((resolve) => { + markStarted = resolve; + }); + const pending = gateway.fetch( + new Request('https://gateway.example/email/destinations/confirm?token=payload.signature'), + env((_input, init) => { + signal = (init as RequestInit | undefined)?.signal ?? undefined; + markStarted(); + return new Promise(() => {}); + }), + context, + ); + await started; + await vi.advanceTimersByTimeAsync(5_001); + const timedOut = await pending; + expect(timedOut.status).toBe(503); + expect(timedOut.headers.get('cache-control')).toBe('no-store'); + expect(signal?.aborted).toBe(true); + } finally { + vi.useRealTimers(); + } + }); + + it('cancels a service response that arrives after the confirmation timeout', async () => { + vi.useFakeTimers(); + try { + let resolveApi!: (response: Response) => void; + let signal: AbortSignal | undefined; + const pending = gateway.fetch( + new Request('https://gateway.example/email/destinations/confirm?token=payload.signature'), + env((_input, init) => { + signal = (init as RequestInit | undefined)?.signal ?? undefined; + return new Promise((resolve) => { + resolveApi = resolve; + }); + }), + context, + ); + await vi.advanceTimersByTimeAsync(5_001); + expect((await pending).status).toBe(503); + expect(signal?.aborted).toBe(true); + + let cancelled = false; + resolveApi( + new Response( + new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode('late')); + }, + cancel() { + cancelled = true; + }, + }), + ), + ); + await vi.runAllTimersAsync(); + await Promise.resolve(); + expect(cancelled).toBe(true); + } finally { + vi.useRealTimers(); + } + }); + function receiptApi() { const receipts = new Map(); return vi.fn(async (url: unknown, init?: unknown) => { diff --git a/platform/packages/email-gateway/wrangler.jsonc b/platform/packages/email-gateway/wrangler.jsonc index ae8e20114..deee79fe6 100644 --- a/platform/packages/email-gateway/wrangler.jsonc +++ b/platform/packages/email-gateway/wrangler.jsonc @@ -8,25 +8,42 @@ "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" }, + "vars": { + "EMAIL_SENDER_DOMAIN": "mail.void.cloud", + "EMAIL_SHARED_ACCOUNT_ID": "f721b8e515fbab226f41e2807edaece7", + "EMAIL_SHARED_ZONE_ID": "5b66f5cb84fd7dcfdd0170515e622181", + "EMAIL_SHARED_INGRESS_NAME": "void-email-gateway", + }, "env": { "production": { "name": "void-email-gateway", "workers_dev": true, + "secrets": { "required": ["JWT_SECRET"] }, "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" }, + "vars": { + "EMAIL_SENDER_DOMAIN": "mail.void.cloud", + "EMAIL_SHARED_ACCOUNT_ID": "f721b8e515fbab226f41e2807edaece7", + "EMAIL_SHARED_ZONE_ID": "5b66f5cb84fd7dcfdd0170515e622181", + "EMAIL_SHARED_INGRESS_NAME": "void-email-gateway", + }, }, "staging": { "name": "void-email-gateway-staging", "workers_dev": true, + "secrets": { "required": ["JWT_SECRET"] }, "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" }, + "vars": { + "EMAIL_SENDER_DOMAIN": "mail.voidcloud.dev", + "EMAIL_SHARED_ACCOUNT_ID": "f721b8e515fbab226f41e2807edaece7", + "EMAIL_SHARED_ZONE_ID": "57fc5c5286e74843013704368205de38", + "EMAIL_SHARED_INGRESS_NAME": "void-email-gateway-staging", + }, }, }, } diff --git a/platform/packages/proxy/README.md b/platform/packages/proxy/README.md index 9ef69269e..dab6c6f8c 100644 --- a/platform/packages/proxy/README.md +++ b/platform/packages/proxy/README.md @@ -88,9 +88,7 @@ Cloudflare Email Routing → gateway (native or authenticated zone relay) → validate handler actions → same API admission and outcome ledger ``` -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. +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. Direct sends share one 50-second proxy budget, with the final 5 seconds reserved for finish or cancellation; inbound handler action batches retain a 60-second budget. 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. @@ -121,7 +119,7 @@ src/ d1.ts # D1 remote access kv.ts # KV remote access r2.ts # R2 remote access - email.ts # Outbound /email/send + platform-internal /email/internal/send + email.ts # Outbound /email/send email-router.ts # Shared native/relayed inbound routing and handler actions types.ts # Env and JWT types test/unit/ diff --git a/platform/packages/proxy/src/body.ts b/platform/packages/proxy/src/body.ts index d5f7b0786..6910992eb 100644 --- a/platform/packages/proxy/src/body.ts +++ b/platform/packages/proxy/src/body.ts @@ -8,10 +8,6 @@ export function asString(value: unknown): string | null { return typeof value === 'string' ? value : null; } -export function asNumber(value: unknown): number | null { - return typeof value === 'number' && Number.isFinite(value) ? value : null; -} - export function asRecord(value: unknown): Record { return isProxyBody(value) ? value : {}; } diff --git a/platform/packages/proxy/src/email-admission.ts b/platform/packages/proxy/src/email-admission.ts index 67d7242c1..7a0c87bf9 100644 --- a/platform/packages/proxy/src/email-admission.ts +++ b/platform/packages/proxy/src/email-admission.ts @@ -22,7 +22,9 @@ export type Admission = { const encoder = new TextEncoder(); const decoder = new TextDecoder(); -const ADMISSION_DEADLINE_MS = 5_000; +const EMAIL_DEFAULT_DEADLINE_MS = 5_000; +const EMAIL_ACTION_DEADLINE_MS = 15_000; +const EMAIL_ADMISSION_DEADLINE_MS = 15_000; const MAX_ADMISSION_RESPONSE_BYTES = 65_536; async function sign(data: string, secret: string): Promise { @@ -44,9 +46,10 @@ async function call( env: Pick, path: string, body: unknown, + deadlineMs = EMAIL_DEFAULT_DEADLINE_MS, ): Promise { const controller = new AbortController(); - const deadline = Date.now() + ADMISSION_DEADLINE_MS; + const deadline = Date.now() + deadlineMs; const beforeDeadline = async (run: () => Promise): Promise => { const remaining = deadline - Date.now(); if (remaining <= 0) { @@ -364,16 +367,23 @@ export function admitEmail( transport: 'binding' | 'send_raw' | 'native_forward' | 'native_reply'; receiptId?: string; }, + deadlineMs = EMAIL_ADMISSION_DEADLINE_MS, ): Promise { - return call(env, '/admit', body); + return call(env, '/admit', body, Math.min(deadlineMs, EMAIL_ADMISSION_DEADLINE_MS)); } export function startEmailAttempt( env: Pick, operationId: string, recipients: Array, + deadlineMs = EMAIL_ACTION_DEADLINE_MS, ): Promise<{ recipients: Array }> { - return call(env, `/${encodeURIComponent(operationId)}/start`, { recipients }); + return call( + env, + `/${encodeURIComponent(operationId)}/start`, + { recipients }, + Math.min(deadlineMs, EMAIL_ACTION_DEADLINE_MS), + ); } export function finishEmailAttempt( @@ -382,8 +392,14 @@ export function finishEmailAttempt( recipients: Array, state: 'provider_accepted' | 'failed' | 'outcome_unknown' | 'cancelled', details: { providerReference?: string; errorCode?: string } = {}, + deadlineMs = EMAIL_ACTION_DEADLINE_MS, ): Promise<{ recipients: Array }> { - return call(env, `/${encodeURIComponent(operationId)}/finish`, { recipients, state, ...details }); + return call( + env, + `/${encodeURIComponent(operationId)}/finish`, + { recipients, state, ...details }, + Math.min(deadlineMs, EMAIL_ACTION_DEADLINE_MS), + ); } export function recordEmailReceipt( diff --git a/platform/packages/proxy/src/email-lease.ts b/platform/packages/proxy/src/email-lease.ts index b44ea49af..2e07515d8 100644 --- a/platform/packages/proxy/src/email-lease.ts +++ b/platform/packages/proxy/src/email-lease.ts @@ -20,9 +20,10 @@ export async function leaseEmailDomainCredential( env: Pick, domain: string, projectId: string, + deadlineMs = LEASE_DEADLINE_MS, ): Promise { const controller = new AbortController(); - const deadline = Date.now() + LEASE_DEADLINE_MS; + const deadline = Date.now() + Math.min(deadlineMs, LEASE_DEADLINE_MS); const beforeDeadline = async (run: () => Promise): Promise => { const remaining = deadline - Date.now(); if (remaining <= 0) { diff --git a/platform/packages/proxy/src/email-provider-deadline.ts b/platform/packages/proxy/src/email-provider-deadline.ts index 572d0b029..36b2ed260 100644 --- a/platform/packages/proxy/src/email-provider-deadline.ts +++ b/platform/packages/proxy/src/email-provider-deadline.ts @@ -12,14 +12,14 @@ export class EmailProviderTimeoutError extends Error { export function createEmailProviderDeadline(totalMs = EMAIL_PROVIDER_BATCH_DEADLINE_MS) { const deadline = Date.now() + totalMs; return { - remainingMs(): number { - return Math.max(0, deadline - Date.now()); + remainingMs(reserveMs = 0): number { + return Math.max(0, deadline - Date.now() - reserveMs); }, - expired(): boolean { - return Date.now() >= deadline; + expired(reserveMs = 0): boolean { + return Date.now() >= deadline - reserveMs; }, - async run(submit: () => Promise): Promise { - const remaining = Math.min(EMAIL_PROVIDER_DEADLINE_MS, deadline - Date.now()); + async run(submit: () => Promise, reserveMs = 0): Promise { + const remaining = Math.min(EMAIL_PROVIDER_DEADLINE_MS, deadline - Date.now() - reserveMs); if (remaining <= 0) { throw new EmailProviderTimeoutError(); } diff --git a/platform/packages/proxy/src/email.ts b/platform/packages/proxy/src/email.ts index 102aa398e..5d6c2e566 100644 --- a/platform/packages/proxy/src/email.ts +++ b/platform/packages/proxy/src/email.ts @@ -14,10 +14,15 @@ import { EMAIL_PROVIDER_DEADLINE_MS, EmailProviderTimeoutError, createEmailProviderDeadline, + type EmailProviderDeadline, } from './email-provider-deadline.ts'; import type { Env, ProxyEnv } from './types.ts'; const app = new Hono(); +// The SDK aborts at 60s. Body/auth can precede this handler, and final ledger +// writes need time after provider work stops. +const EMAIL_SEND_DEADLINE_MS = 50_000; +const EMAIL_SEND_FINALIZATION_MARGIN_MS = 5_000; /** * Cap inbound MIME bytes well below CF's ~10 MB base64-inflated ceiling. The @@ -82,7 +87,7 @@ const MAX_RECIPIENTS = 50; * 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; +const MAX_RECIPIENT_LENGTH = 320; /** * Cap the envelope sender for the same reason. It is one string, so there @@ -92,20 +97,14 @@ export const MAX_RECIPIENT_LENGTH = 320; * is one — is then echoed verbatim into the MIME `From:` refusal and * 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 - * the pair into the content binding — the same reason and the same - * figures, on the one path that runs ahead of any credential check. */ -export const MAX_SENDER_LENGTH = 320; +const MAX_SENDER_LENGTH = 320; /** - * The platform mail domain for this environment — `mail.void.cloud` in - * production, `mail.staging.void.cloud` in staging. Configured as the - * `EMAIL_SENDER_DOMAIN` var on both the proxy and api workers, and mirrored - * into deployed user workers as the `__VOID_EMAIL_DOMAIN` plain-text binding - * so the framework builds its default `from` against the same zone. + * The platform mail domain for this environment. It is configured as the + * `EMAIL_SENDER_DOMAIN` var and mirrored into deployed user workers as the + * `__VOID_EMAIL_DOMAIN` plain-text binding so the framework builds its default + * `from` against the same zone. * * There is deliberately NO baked-in default. A staging proxy that fell back * to `mail.void.cloud` would accept a `from` on the production zone, and the @@ -143,8 +142,8 @@ const strictFromCache = new Map(); * this regex, a `from` like `slug+x\r\nX-Header: y@` would pass slug * pinning and then reach `new EmailMessage(from, ...)`, opening an SMTP * header injection primitive against the shared sender. The regex pins the - * entire string to: lowercase ASCII local-part, optional `+` - * (constrained to RFC-5321 dot-atom-text + `=` and `/`), then exactly + * entire string to: lowercase ASCII local-part, zero or more `+` + * segments (constrained to RFC-5321 dot-atom-text + `=` and `/`), then exactly * `@`. Display names, encoded-words, and angle brackets * are intentionally not supported — the framework doesn't emit them for a * default `from`, and explicit user-supplied names are already disallowed by @@ -161,7 +160,7 @@ export function strictFromRe(domain: string): RegExp { if (cached) { return cached; } - const re = new RegExp(`^[a-z0-9._-]+(?:\\+[a-z0-9._=/-]+)?@${escapeRegExp(domain)}$`); + const re = new RegExp(`^[a-z0-9._-]+(?:\\+[a-z0-9._=/-]+)*@${escapeRegExp(domain)}$`); strictFromCache.set(domain, re); return re; } @@ -500,6 +499,7 @@ function singleMailboxAddrSpec(value: string): string | null { * The user worker does not have a `send_email` binding. */ app.post('/send', async (context) => { + const sendDeadline = createEmailProviderDeadline(EMAIL_SEND_DEADLINE_MS); const projectId = context.get('projectId'); const body = context.get('body'); @@ -684,6 +684,7 @@ app.post('/send', async (context) => { raw, requestId, operationKey, + sendDeadline, ); } @@ -777,15 +778,19 @@ app.post('/send', async (context) => { // recipient consent, suspension, and attempt quotas. let admission; try { - admission = await admitEmail(context.env, { - projectId, - kind: 'direct', - key: operationKey, - digest: await emailPayloadDigest('direct', from, recipients, raw), - from, - recipients, - transport: 'binding', - }); + admission = await admitEmail( + context.env, + { + projectId, + kind: 'direct', + key: operationKey, + digest: await emailPayloadDigest('direct', from, recipients, raw), + from, + recipients, + transport: 'binding', + }, + sendDeadline.remainingMs(EMAIL_SEND_FINALIZATION_MARGIN_MS), + ); } catch (error) { const conflict = error instanceof Error && error.message === 'IDEMPOTENCY_CONFLICT'; return context.json( @@ -844,18 +849,17 @@ 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 (let index = 0; index < allowed.length; index++) { const r = allowed[index]; - if (providerDeadline.expired()) { + if (sendDeadline.expired(EMAIL_SEND_FINALIZATION_MARGIN_MS)) { const unstarted = allowed.slice(index); const cancelled = await cancelUnstartedRecipients( context.env, admission.operationId, unstarted, + sendDeadline.remainingMs(), ); for (const recipient of unstarted) { deliveries.push({ @@ -873,9 +877,19 @@ app.post('/send', async (context) => { break; } try { - await startEmailAttempt(context.env, admission.operationId, [r]); + await startEmailAttempt( + context.env, + admission.operationId, + [r], + sendDeadline.remainingMs(EMAIL_SEND_FINALIZATION_MARGIN_MS), + ); } catch { - const cancelled = await cancelUnstartedRecipients(context.env, admission.operationId, [r]); + const cancelled = await cancelUnstartedRecipients( + context.env, + admission.operationId, + [r], + sendDeadline.remainingMs(), + ); deliveries.push({ recipient: r, ok: false, @@ -896,12 +910,20 @@ 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 providerDeadline.run(() => sendBinding.send(msg)); + const result = await sendDeadline.run( + () => sendBinding.send(msg), + EMAIL_SEND_FINALIZATION_MARGIN_MS, + ); const providerReference = typeof result?.messageId === 'string' ? result.messageId : ''; try { - await finishEmailAttempt(context.env, admission.operationId, [r], 'provider_accepted', { - providerReference, - }); + await finishEmailAttempt( + context.env, + admission.operationId, + [r], + 'provider_accepted', + { providerReference }, + sendDeadline.remainingMs(), + ); } catch { deliveries.push({ recipient: r, @@ -922,9 +944,14 @@ app.post('/send', async (context) => { }); } catch { try { - await finishEmailAttempt(context.env, admission.operationId, [r], 'outcome_unknown', { - errorCode: 'OUTCOME_UNKNOWN', - }); + await finishEmailAttempt( + context.env, + admission.operationId, + [r], + 'outcome_unknown', + { errorCode: 'OUTCOME_UNKNOWN' }, + sendDeadline.remainingMs(), + ); } catch { /* persisted attempt_started remains unresolved */ } @@ -1007,13 +1034,13 @@ export async function requestSendRaw( }, deadlineMs = EMAIL_PROVIDER_DEADLINE_MS, ): Promise { + const controller = new AbortController(); + const deadline = Date.now() + Math.min(EMAIL_PROVIDER_DEADLINE_MS, deadlineMs); 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) { @@ -1181,6 +1208,7 @@ async function sendViaCustomDomain( raw: Uint8Array, requestId: string, operationKey: string, + sendDeadline: EmailProviderDeadline, ): 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 @@ -1230,15 +1258,19 @@ async function sendViaCustomDomain( 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', - }); + admission = await admitEmail( + context.env, + { + projectId, + kind: 'direct', + key: operationKey, + digest: await emailPayloadDigest('direct', from, recipients, raw), + from, + recipients, + transport: 'send_raw', + }, + sendDeadline.remainingMs(EMAIL_SEND_FINALIZATION_MARGIN_MS), + ); } catch (error) { const conflict = error instanceof Error && error.message === 'IDEMPOTENCY_CONFLICT'; return context.json( @@ -1301,11 +1333,21 @@ async function sendViaCustomDomain( // 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); + const lease = await leaseEmailDomainCredential( + context.env, + fromDomain, + projectId, + sendDeadline.remainingMs(EMAIL_SEND_FINALIZATION_MARGIN_MS), + ); if (!lease) { - await finishEmailAttempt(context.env, admission.operationId, recipients, 'cancelled').catch( - () => {}, - ); + await finishEmailAttempt( + context.env, + admission.operationId, + recipients, + 'cancelled', + {}, + sendDeadline.remainingMs(), + ).catch(() => {}); return context.json( { ok: false, @@ -1316,9 +1358,14 @@ async function sendViaCustomDomain( ); } if (admission.accountId !== lease.accountId) { - await finishEmailAttempt(context.env, admission.operationId, recipients, 'cancelled').catch( - () => {}, - ); + await finishEmailAttempt( + context.env, + admission.operationId, + recipients, + 'cancelled', + {}, + sendDeadline.remainingMs(), + ).catch(() => {}); return context.json( { ok: false, @@ -1329,12 +1376,18 @@ async function sendViaCustomDomain( ); } try { - await startEmailAttempt(context.env, admission.operationId, recipients); + await startEmailAttempt( + context.env, + admission.operationId, + recipients, + sendDeadline.remainingMs(EMAIL_SEND_FINALIZATION_MARGIN_MS), + ); } catch { const cancelled = await cancelUnstartedRecipients( context.env, admission.operationId, recipients, + sendDeadline.remainingMs(), ); for (const recipient of recipients) { deliveries.push({ @@ -1360,13 +1413,16 @@ async function sendViaCustomDomain( let sendRawResult: ParsedSendRawResult | null = null; let providerResponse: SendRawHttpResponse | null = null; try { - providerResponse = await requestSendRaw({ - accountId: lease.accountId, - bearer: leaseBearer(lease), - from, - recipients, - mimeMessage, - }); + providerResponse = await requestSendRaw( + { + accountId: lease.accountId, + bearer: leaseBearer(lease), + from, + recipients, + mimeMessage, + }, + sendDeadline.remainingMs(EMAIL_SEND_FINALIZATION_MARGIN_MS), + ); } catch { failure = { code: 'UPSTREAM_ERROR', message: 'email sending request failed' }; failureState = 'outcome_unknown'; @@ -1471,6 +1527,7 @@ async function sendViaCustomDomain( ? 'OUTCOME_UNKNOWN' : (failure?.code ?? delivery.error?.code), }, + sendDeadline.remainingMs(), ); delivery.state = delivery.ok ? 'provider_accepted' @@ -1551,9 +1608,17 @@ async function cancelUnstartedRecipients( env: Pick, operationId: string, recipients: Array, + deadlineMs?: number, ): Promise { try { - const result = await finishEmailAttempt(env, operationId, recipients, 'cancelled'); + const result = await finishEmailAttempt( + env, + operationId, + recipients, + 'cancelled', + {}, + deadlineMs, + ); return recipients.every((recipient) => result.recipients.some((row) => row.recipient === recipient && row.state === 'cancelled'), ); @@ -1615,115 +1680,4 @@ function base64Decode(b64: string): Uint8Array { return out; } -/** - * Platform-internal send endpoint. Used by the api worker to dispatch - * destination-verification emails: when project A adds an address that - * a different project already verified via CF, we issue our own - * confirmation email to the recipient instead of inheriting CF's - * verification flag. - * - * Auth: HMAC of a fixed sentinel string + timestamp + sha256 of - * (from|to|mimeBase64) under JWT_SECRET. The auth middleware in - * `index.ts` validates the sentinel + timestamp window; this handler - * additionally verifies the content-binding hash matches the body - * fields it actually intends to act on. Without the content binding, - * a captured platformToken inside the 5-minute skew window could be - * replayed against a different (from, to, mime) tuple — the timestamp - * alone has no relation to what the request asks the proxy to do. - * - * Token contract — the api worker MUST sign: - * `..` - * with HMAC-SHA-256 under `JWT_SECRET`, where `mimeBase64` is the - * EXACT string sent in the body and the three fields are joined by a - * literal `|`. The proxy reconstructs and verifies. Mirroring this - * format is required in `packages/api/src/email/send-verification.ts`. - * Bumping the contract requires a coordinated proxy + api deploy. - * - * Only the proxy and api hold JWT_SECRET — user workers do not, so this - * endpoint cannot be reached from a user worker. - * - * The `from` address is locked to a single allow-listed sender: - * `noreply@`. Earlier revisions trusted the body's - * `from` and would have let a compromised api worker (or - * misuse-via-coordinated-bug) send arbitrary platform-branded mail. - * The verification-email use case is the only legitimate caller and it - * always sends from `noreply@`; harden by allow-list rather than - * relying on downstream filters. - * - * Body shape (validated below): - * { platformToken, platformTimestamp, from, to, mimeBase64 }. - * - * Quotas, allowlists, and the suspend kill-switch DO NOT apply here: - * those are per-project guards, and platform verification mail is - * account-level. Volume is bounded by the api worker's per-project KV - * rate limit on `POST /destinations`, applied before tokens are issued. - */ - -/** The single allowed platform-internal `from` local-part. */ -const INTERNAL_FROM_LOCAL_PART = 'noreply'; - -app.post('/internal/send', async (context) => { - const body = context.get('body'); - - // Fail closed on missing sender configuration, exactly as `/send` does — - // otherwise the allow-list below would have no domain to pin against. - const senderDomain = readSenderDomain(context.env); - if (!senderDomain) { - return context.json({ ok: false, error: 'email sender domain is not configured' }, 502); - } - - const from = asString(body.from); - const to = asString(body.to); - const mimeBase64 = asString(body.mimeBase64); - if (!from || !to || !mimeBase64) { - return context.json({ ok: false, error: 'invalid body' }, 400); - } - - // Pin the platform-internal `from` to a single allow-listed envelope on - // the configured zone: `noreply@`. - // The envelope is forwarded verbatim, so validation 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 `from` can satisfy a lowercased regex and - // still reach the shared envelope sender intact. Refuse it before that. - if (!/^[\x21-\x7e]+$/.test(from)) { - return context.json({ ok: false, error: 'from not allowed for internal send' }, 403); - } - if (from.toLowerCase() !== `${INTERNAL_FROM_LOCAL_PART}@${senderDomain}`) { - return context.json({ ok: false, error: 'from not allowed for internal send' }, 403); - } - - const sendBinding = context.env.SEND_EMAIL; - if (typeof sendBinding?.send !== 'function') { - return context.json({ ok: false, error: 'email sending is not configured' }, 502); - } - - let raw: Uint8Array; - try { - raw = base64Decode(mimeBase64); - } catch { - return context.json({ ok: false, error: 'invalid base64 mime' }, 400); - } - if (raw.byteLength > MAX_MIME_BYTES) { - return context.json({ ok: false, error: 'too large' }, 413); - } - - try { - const msg = new EmailMessage(from, to, bytesToStream(raw)); - 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: err instanceof EmailProviderTimeoutError ? 'outcome unknown' : 'upstream error', - }, - err instanceof EmailProviderTimeoutError ? 504 : 502, - ); - } -}); - export { app as email }; diff --git a/platform/packages/proxy/src/index.ts b/platform/packages/proxy/src/index.ts index a07b2fd43..6b7fbe54f 100644 --- a/platform/packages/proxy/src/index.ts +++ b/platform/packages/proxy/src/index.ts @@ -2,11 +2,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 { 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 { email } 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'; @@ -69,40 +69,6 @@ app.all('/*', async (context, next) => { await next(); }); -// Sentinel string the api worker signs with JWT_SECRET for platform-internal -// calls (e.g. POST /email/internal/send). Only the proxy and api hold -// JWT_SECRET — user workers do not — so this gate keeps user code from -// reaching internal endpoints. Mirrors the same value in -// `packages/api/src/email/send-verification.ts`; bumping requires a -// coordinated proxy + api deploy. -const PLATFORM_INTERNAL_EMAIL_SENTINEL = 'void-platform-internal-email-v1'; - -// 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 -// platformToken would replay forever (the sentinel never changes). Five -// minutes covers normal clock skew without giving an attacker who -// observed a token a meaningful replay window. -const PLATFORM_TOKEN_MAX_SKEW_SECONDS = 5 * 60; - -/** - * Exact length of a well-formed `platformToken`. The only signer - * (`signSentinelAtBound` in `packages/api/src/email/send-verification.ts`) - * emits an HMAC-SHA256 tag — 32 bytes — as unpadded base64url, and - * ceil(32 * 4 / 3) = 43 characters is the only length that encodes to. Any - * other length can never verify, so it is refused before `verifyHmac` runs: - * `base64urlDecode` copies the token twice through global `replace` (V8 - * materializes one part per match) and then `Uint8Array.from` iterates - * `atob`'s output one character at a time — measured, a 30 MB token is - * ~1.5 GB of transient heap and ~2 s, and a 4 MB one kills a 128 MB heap, - * the shared proxy isolate's ceiling. This gate runs ahead of any - * credential check, so without the bound an unauthenticated caller chose - * that cost. - */ -const PLATFORM_TOKEN_LENGTH = 43; - async function hmacSign(data: string, secret: string): Promise { const key = await crypto.subtle.importKey( 'raw', @@ -182,99 +148,6 @@ app.post('/*', async (context, next) => { } context.set('body', body); - // Platform-internal endpoints (e.g. /email/internal/send) authenticate - // via an HMAC of `..` - // under JWT_SECRET. They have no projectId — they exist for api → proxy - // calls that don't belong to a user project (verification mail, etc.). - // User-token requests can never reach this path because the sentinel is - // not a projectId. - // - // **Content binding.** The hash binds the token to the (from, to, - // mimeBase64) tuple it authorizes. Without it, a captured platformToken - // inside the 5-minute skew window could be replayed against a different - // recipient or arbitrary MIME bytes — the timestamp alone has no relation - // to what the request actually asks the proxy to do. With it, an attacker - // who observes one verification email's token can only ever resend that - // exact email; recipient, content, and quota are all locked. - // - // The api worker MUST sign: - // `..` - // see `packages/api/src/email/send-verification.ts` for the reference - // signer. The fields are joined with a literal `|` so a tampering attempt - // can't slide bytes between them. - // - // The prefix is pinned to `/email/internal/` only. A bare `/internal/` - // prefix would be a footgun: any future handler mounted at root - // `/internal` would silently inherit sentinel-only auth with no projectId - // set. Today no such handler exists; if one ever does, it should be - // mounted under its own feature-prefixed namespace. - if (path.startsWith('/email/internal/')) { - const platformToken = asString(body.platformToken); - const platformTimestamp = asNumber(body.platformTimestamp); - if (!platformToken || platformTimestamp === null) { - return context.json({ error: 'platform token required' }, 403); - } - // A token of the wrong length is present but can never be valid, so it - // takes the same opaque refusal as the skew and size gates below — - // `required` is reserved for an absent token. Checked before anything - // else touches the token; see `PLATFORM_TOKEN_LENGTH`. - if (platformToken.length !== PLATFORM_TOKEN_LENGTH) { - return context.json({ error: 'invalid platform token' }, 403); - } - const nowSec = Math.floor(Date.now() / 1000); - if (Math.abs(nowSec - platformTimestamp) > PLATFORM_TOKEN_MAX_SKEW_SECONDS) { - // Stale or future-dated token. Don't distinguish for the caller — - // both look like an invalid token from outside. - return context.json({ error: 'invalid platform token' }, 403); - } - // Bind the token to the body's (from|to|mimeBase64). Pull the raw - // strings here (asString returns null for non-strings) and compute the - // same sha256 the api worker computes when signing. - const bindingFrom = asString(body.from); - const bindingTo = asString(body.to); - const bindingMime = asString(body.mimeBase64); - if (!bindingFrom || !bindingTo || !bindingMime) { - // No fields to bind — the request body is malformed for any - // /email/internal/* handler we expose today. Reject at the auth - // boundary so the handler doesn't have to re-decide what to do with a - // partially-authed request. - return context.json({ error: 'invalid platform token' }, 403); - } - // Bound the input BEFORE hashing it. This runs before the token is - // verified, so an unauthenticated caller would otherwise choose how much - // sha256 work we do. The bound is the base64 length of the same - // MAX_MIME_BYTES the handlers enforce; the handler still re-checks the - // decoded size, this only refuses to hash what can never be valid. - if (bindingMime.length > MAX_PLATFORM_MIME_BASE64_LENGTH) { - return context.json({ error: 'invalid platform token' }, 403); - } - // The two addresses are hashed alongside the MIME and were the only - // part of the input left unbounded. The template below flattens - // `from|to|mime` into one full-size string and `TextEncoder` copies it - // again (measured: +1x on the heap and +1x external for the pair), so - // without this an unauthenticated caller with a small MIME still chose - // two more full-size copies plus the sha256 over them. The bounds are - // the ones `/email/send` applies to its sender and recipients, and they - // refuse nothing the only signer sends: `/email/internal/send` accepts - // exactly `noreply@` as `from`, and `to` is one - // address the api worker already bounded at the same 320 when it was - // registered (`api/src/routes/email.ts`) — RFC 5321 caps a path at 256 - // octets anyway. Same opaque refusal: from outside, a body that cannot - // be signed and a body that was not are one case. - if (bindingFrom.length > MAX_SENDER_LENGTH || bindingTo.length > MAX_RECIPIENT_LENGTH) { - return context.json({ error: 'invalid platform token' }, 403); - } - const contentHash = await sha256Hex(`${bindingFrom}|${bindingTo}|${bindingMime}`); - const signed = `${PLATFORM_INTERNAL_EMAIL_SENTINEL}.${platformTimestamp}.${contentHash}`; - if (!(await verifyHmac(signed, platformToken, context.env.JWT_SECRET))) { - return context.json({ error: 'invalid platform token' }, 403); - } - // Internal endpoints don't operate on a project — leave projectId unset. - // Downstream handlers must not call context.get('projectId'). - await next(); - return; - } - let revalidateHuman: (() => Promise) | undefined; const authHeader = context.req.header('authorization'); if (authHeader?.startsWith('Bearer ')) { @@ -387,9 +260,7 @@ app.post('/sandbox/*', (context) => // the email module still holds `__VOID_PROXY` and a valid project token, so // an explicit-`from` `sendEmail()` reaches `/email/send` and would otherwise // answer with the sender-domain / send-binding configuration failures — or -// send, if the operator left the bindings in place. `/email/internal/send` -// is covered too: its only caller is the api's verification mail, which -// sits behind the api's own `email` capability gate. +// send, if the operator left the bindings in place. app.post('/email/*', async (context, next) => { if (!proxyCapabilityEnabled(context.env.PLATFORM_CAPABILITIES, 'email')) { return context.json( @@ -437,16 +308,6 @@ async function getVerifyKey(secret: string): Promise { return cachedVerifyKey; } -async function sha256Hex(input: string): Promise { - const digest = await crypto.subtle.digest('SHA-256', encoder.encode(input)); - const bytes = new Uint8Array(digest); - let out = ''; - for (const b of bytes) { - out += b.toString(16).padStart(2, '0'); - } - return out; -} - async function verifyHmac(data: string, signature: string, secret: string): Promise { try { const key = await getVerifyKey(secret); diff --git a/platform/packages/proxy/src/types.ts b/platform/packages/proxy/src/types.ts index f2f14231c..508d876e1 100644 --- a/platform/packages/proxy/src/types.ts +++ b/platform/packages/proxy/src/types.ts @@ -51,7 +51,7 @@ export type Env = Readonly<{ /** * Platform mail zone for this environment — `mail.void.cloud` in - * production, `mail.staging.void.cloud` in staging. Declared as a `vars` + * production, `mail.voidcloud.dev` in staging. Declared as a `vars` * entry in every `wrangler.jsonc` scope (wrangler does not inherit vars * into a named env) and mirrored into deployed user workers as the * `__VOID_EMAIL_DOMAIN` plain-text binding. Never defaulted in code: see diff --git a/platform/packages/proxy/test/unit/email-admission.test.ts b/platform/packages/proxy/test/unit/email-admission.test.ts index d748b82a6..e57de2665 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, vi } from 'vite-plus/test'; -import { admitEmail, emailPayloadDigest } from '../../src/email-admission.ts'; +import { admitEmail, emailPayloadDigest, finishEmailAttempt } from '../../src/email-admission.ts'; const encoder = new TextEncoder(); function message(date: string, id: string, boundary: string, body: string) { @@ -202,6 +202,97 @@ describe('email admission payload digest', () => { }); describe('email admission service deadline', () => { + it('allows an admission response after five seconds within the control deadline', async () => { + vi.useFakeTimers(); + try { + let signal: AbortSignal | undefined; + const fetch = vi.fn((_input: unknown, init?: RequestInit) => { + signal = init?.signal ?? undefined; + return new Promise((resolve) => { + setTimeout( + () => + resolve( + Response.json({ + operationId: 'emailact_1', + replay: false, + recipients: [ + { + recipient: 'recipient@example.com', + state: 'reserved', + errorCode: null, + providerReference: null, + }, + ], + }), + ), + 6_000, + ); + }); + }); + 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()); + await vi.advanceTimersByTimeAsync(6_000); + await expect(pending).resolves.toMatchObject({ operationId: 'emailact_1' }); + expect(signal?.aborted).toBe(false); + } finally { + vi.useRealTimers(); + } + }); + + it('allows a lifecycle checkpoint after five seconds within its control deadline', async () => { + vi.useFakeTimers(); + try { + const fetch = vi.fn( + () => + new Promise((resolve) => { + setTimeout( + () => + resolve( + Response.json({ + recipients: [ + { + recipient: 'recipient@example.com', + state: 'provider_accepted', + errorCode: null, + providerReference: 'message-1', + }, + ], + }), + ), + 6_000, + ); + }), + ); + const pending = finishEmailAttempt( + { API: { fetch } as never, JWT_SECRET: 'secret' }, + 'emailact_1', + ['recipient@example.com'], + 'provider_accepted', + { providerReference: 'message-1' }, + ); + + await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce()); + await vi.advanceTimersByTimeAsync(6_000); + await expect(pending).resolves.toMatchObject({ + recipients: [{ state: 'provider_accepted' }], + }); + } finally { + vi.useRealTimers(); + } + }); + it('settles when the service binding ignores its abort signal', async () => { vi.useFakeTimers(); try { @@ -221,7 +312,7 @@ describe('email admission service deadline', () => { await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce()); const rejection = expect(pending).rejects.toThrow('EMAIL_ADMISSION_TIMEOUT'); - await vi.advanceTimersByTimeAsync(5_000); + await vi.advanceTimersByTimeAsync(15_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 b78796ff6..72943cd78 100644 --- a/platform/packages/proxy/test/unit/email-custom-domain.test.ts +++ b/platform/packages/proxy/test/unit/email-custom-domain.test.ts @@ -15,6 +15,7 @@ vi.mock('cloudflare:email', () => ({ })); const worker = (await import('../../src/index.ts')).default; +const { requestSendRaw } = await import('../../src/email.ts'); const JWT_SECRET = 'test-secret-key'; const PROD_DOMAIN = 'mail.void.cloud'; @@ -217,6 +218,35 @@ afterEach(() => { }); describe('POST /email/send — custom sender domain', () => { + it('does not call send_raw when serialization exhausts the request deadline', async () => { + vi.useFakeTimers(); + vi.setSystemTime(0); + const providerFetch = vi.fn(); + vi.stubGlobal('fetch', providerFetch); + const stringify = JSON.stringify; + const stringifySpy = vi.spyOn(JSON, 'stringify').mockImplementation((value: unknown) => { + if (typeof value === 'object' && value !== null && 'mime_message' in value) { + vi.setSystemTime(5_001); + } + return stringify(value); + }); + + await expect( + requestSendRaw( + { + accountId: 'acct_customer', + bearer: LEASED, + from: CUSTOM_FROM, + recipients: ['dev@example.com'], + mimeMessage: 'mime', + }, + 5_000, + ), + ).rejects.toThrow('email sending request timed out'); + stringifySpy.mockRestore(); + expect(providerFetch).not.toHaveBeenCalled(); + }); + it('leases a credential and delivers through the customer account via send_raw', async () => { const { env, apiFetch, sendEmail } = createMockEnv(); const calls = stubCloudflare(); @@ -576,10 +606,29 @@ 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', + 'shares the request deadline with a send_raw %s and records an unknown outcome', async (stall) => { vi.useFakeTimers(); const { env, apiFetch } = createMockEnv(); + const normalFetch = apiFetch.getMockImplementation()!; + let markAdmissionStarted!: () => void; + const admissionStarted = new Promise((resolve) => { + markAdmissionStarted = resolve; + }); + let markStartStarted!: () => void; + const startStarted = new Promise((resolve) => { + markStartStarted = resolve; + }); + apiFetch.mockImplementation(async (url, init) => { + if (String(url).endsWith('/admit')) { + markAdmissionStarted(); + await new Promise((resolve) => setTimeout(resolve, 10_000)); + } else if (String(url).endsWith('/start')) { + markStartStarted(); + await new Promise((resolve) => setTimeout(resolve, 10_000)); + } + return normalFetch(url, init); + }); let markProviderStarted!: () => void; const providerStarted = new Promise((resolve) => { markProviderStarted = resolve; @@ -604,9 +653,13 @@ describe('POST /email/send — custom sender domain', () => { ); const pending = postSend(env, await sendBody()); + await admissionStarted; + await vi.advanceTimersByTimeAsync(10_000); + await startStarted; + await vi.advanceTimersByTimeAsync(10_000); await providerStarted; await vi.advanceTimersByTimeAsync(0); - await vi.advanceTimersByTimeAsync(30_000); + await vi.advanceTimersByTimeAsync(25_001); const body = await (await pending).json(); expect(body).toMatchObject({ diff --git a/platform/packages/proxy/test/unit/email-platform-token.test.ts b/platform/packages/proxy/test/unit/email-platform-token.test.ts deleted file mode 100644 index 3b02c606e..000000000 --- a/platform/packages/proxy/test/unit/email-platform-token.test.ts +++ /dev/null @@ -1,199 +0,0 @@ -/** - * The cross-package half of the platform-internal send contract. - * - * `packages/api` SIGNS the request (`email/send-verification.ts`) and this - * worker VERIFIES it (`POST /email/internal/send`). The two are separately - * bundled and share only `JWT_SECRET`, `EMAIL_SENDER_DOMAIN`, and a mirrored - * sentinel literal — nothing inside either package's own unit tests can catch - * a drift between them. So these cases sign with the REAL api code path and - * verify with the REAL proxy worker. - * - * They live on the PROXY side on purpose. The api package typechecks its - * `test/` directory with the default lib (it needs DOM-compatible `URL` types - * for Miniflare — see the tsconfig note in the repo README), and the proxy - * worker's sources do not compile under that lib. Importing the proxy entry - * from an api test drags `proxy/src/ai.ts` into the api typecheck and breaks - * it. The api-only half of this contract stays in - * `packages/api/test/unit/email-platform-token.test.ts`. - */ - -import { describe, expect, it, vi } from 'vite-plus/test'; -import { sendPlatformVerificationEmail } from '../../../api/src/email/send-verification.ts'; - -const SECRET = 'test-platform-secret'; - -/** - * The platform mail zone is a per-environment var, never a baked-in literal. - * Staging's value here on purpose: a test pinned to production's domain would - * pass against code that ignored the var entirely. - */ -const MAIL_DOMAIN = 'mail.staging.void.cloud'; - -type CapturedSend = { - url: string; - body: { - platformToken: string; - platformTimestamp: number; - from: string; - to: string; - mimeBase64: string; - }; -}; - -/** - * Run the REAL api sender with `fetch` stubbed, and hand back the exact - * request body it would have POSTed to this worker. - */ -async function captureApiSend(overrides: Record = {}): Promise { - const calls: Array = []; - vi.stubGlobal( - 'fetch', - vi.fn(async (input: string | URL | Request, init?: RequestInit) => { - const url = - typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url; - calls.push({ url, body: JSON.parse(String(init?.body)) }); - return Response.json({ ok: true }); - }), - ); - try { - await sendPlatformVerificationEmail( - { - JWT_SECRET: SECRET, - EMAIL_SENDER_DOMAIN: MAIL_DOMAIN, - ...overrides, - } as never, - { id: 'proj_1', slug: 'acme' }, - 'recipient@example.com', - 'confirm-token-value', - ); - } finally { - vi.unstubAllGlobals(); - } - expect(calls).toHaveLength(1); - return calls[0]!; -} - -function proxyEnv(overrides: Record = {}) { - return { - AI: {}, - JWT_SECRET: SECRET, - ROUTING: { - get: vi.fn(async () => null), - put: vi.fn(async () => {}), - delete: vi.fn(async () => {}), - }, - CF_ACCOUNT_ID: 'acct', - CF_API_TOKEN: 'cf-token', - API: { fetch: vi.fn() }, - DISPATCH: { get: vi.fn() }, - SEND_EMAIL: { send: vi.fn(async () => ({ messageId: 'msg_1' })) }, - EMAIL_SENDER_DOMAIN: MAIL_DOMAIN, - ...overrides, - }; -} - -async function postToProxy( - env: Record, - body: Record, -): Promise { - const worker = (await import('../../src/index.ts')).default; - return (worker.fetch as (req: Request, env: unknown) => Promise)( - new Request('https://proxy.void.cloud/email/internal/send', { - method: 'POST', - headers: { 'content-type': 'application/json' }, - body: JSON.stringify(body), - }), - env, - ); -} - -const sendMock = (env: Record) => - (env.SEND_EMAIL as { send: ReturnType }).send; - -describe('platform-internal send: api signature vs proxy verification', () => { - it('the proxy accepts the api-signed request unmodified', async () => { - // The contract test. Signer and verifier live in separately-bundled - // workers; if either side changes the sentinel, the timestamp encoding, - // or the `from|to|mimeBase64` hash, this is the only thing that notices. - const send = await captureApiSend(); - const env = proxyEnv(); - - const res = await postToProxy(env, send.body); - - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true }); - expect(sendMock(env)).toHaveBeenCalledTimes(1); - }); - - it('the proxy rejects the same token against a tampered recipient', async () => { - // Replay within the 5-minute window against a different recipient. The - // content binding is what makes this a 403 instead of a free send. - const send = await captureApiSend(); - const env = proxyEnv(); - - const res = await postToProxy(env, { ...send.body, to: 'attacker@example.com' }); - - expect(res.status).toBe(403); - expect(sendMock(env)).not.toHaveBeenCalled(); - }); - - it('the proxy rejects the same token against tampered mime bytes', async () => { - const send = await captureApiSend(); - const env = proxyEnv(); - const evilMime = btoa('Subject: hi\r\n\r\nnot the confirmation mail\r\n'); - - const res = await postToProxy(env, { ...send.body, mimeBase64: evilMime }); - - expect(res.status).toBe(403); - expect(sendMock(env)).not.toHaveBeenCalled(); - }); - - it('the proxy rejects a stale timestamp', async () => { - const send = await captureApiSend(); - const env = proxyEnv(); - - // Six minutes old — outside the proxy's 5-minute skew window. Moving the - // timestamp also breaks the signature, which is the point: the timestamp - // is inside the signed string. - const res = await postToProxy(env, { - ...send.body, - platformTimestamp: send.body.platformTimestamp - 6 * 60, - }); - - expect(res.status).toBe(403); - expect(sendMock(env)).not.toHaveBeenCalled(); - }); - - it('the proxy rejects an api signed with a different secret', async () => { - const send = await captureApiSend({ JWT_SECRET: 'a-different-secret' }); - const env = proxyEnv(); - - const res = await postToProxy(env, send.body); - - expect(res.status).toBe(403); - expect(sendMock(env)).not.toHaveBeenCalled(); - }); - - it('the proxy rejects a correctly-signed send for a domain it is not configured for', async () => { - // Both sides read their own `EMAIL_SENDER_DOMAIN`; the deploy contract is - // that they name the same zone. A mismatch must fail closed rather than - // let one environment sign mail for the other's zone. - const send = await captureApiSend({ EMAIL_SENDER_DOMAIN: 'mail.void.cloud' }); - const env = proxyEnv({ EMAIL_SENDER_DOMAIN: MAIL_DOMAIN }); - - const res = await postToProxy(env, send.body); - - expect(res.status).toBe(403); - expect(sendMock(env)).not.toHaveBeenCalled(); - }); - - it('the proxy fails closed when it has no sender domain of its own', async () => { - const send = await captureApiSend(); - const env = proxyEnv({ EMAIL_SENDER_DOMAIN: '' }); - - const res = await postToProxy(env, send.body); - - expect(res.status).toBe(502); - expect(sendMock(env)).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 a793020a5..11974ff89 100644 --- a/platform/packages/proxy/test/unit/email-router.test.ts +++ b/platform/packages/proxy/test/unit/email-router.test.ts @@ -804,6 +804,24 @@ describe('routeInbound — action enaction', () => { expect(replyCalls[0]?.raw).toBeInstanceOf(ReadableStream); }); + it('forwards from a shared recipient with multiple safe plus-tag segments', async () => { + const recipient = `myslug+support+forward.run@${PROD_DOMAIN}`; + const { env, apiFetch } = makeEnv({ + emailReturn: [{ type: 'forward', to: 'admin@example.com' }], + }); + const { message, forwardCalls } = createFakeMessage({ to: recipient }); + const { ctx } = createCtx(); + await routeInbound(message, env, ctx); + + expect(apiBodies(apiFetch, '/admit')[0]).toMatchObject({ + kind: 'forward', + from: recipient, + transport: 'native_forward', + }); + expect(forwardCalls).toMatchObject([{ to: 'admin@example.com' }]); + expect(apiBodies(apiFetch, '/finish')[0]?.state).toBe('provider_accepted'); + }); + it('stops native action dispatch at the 60-second batch deadline', async () => { vi.useFakeTimers(); let firstSubmit!: () => void; diff --git a/platform/packages/proxy/test/unit/email.test.ts b/platform/packages/proxy/test/unit/email.test.ts index d4dc4bb32..b4401684c 100644 --- a/platform/packages/proxy/test/unit/email.test.ts +++ b/platform/packages/proxy/test/unit/email.test.ts @@ -26,7 +26,7 @@ const { buildMime, normalizeEmail } = const JWT_SECRET = 'test-secret-key'; const PROD_DOMAIN = 'mail.void.cloud'; -const STAGING_DOMAIN = 'mail.staging.void.cloud'; +const STAGING_DOMAIN = 'mail.voidcloud.dev'; // --- HMAC helper (mirrors the worker's project token signing) --- @@ -52,17 +52,6 @@ async function signHmac(data: string, secret: string): Promise { ); } -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; -} - // --- Mock env --- type MockKv = ReturnType; @@ -336,6 +325,59 @@ describe('proxy wrangler config', () => { expect((env.production.vars as Record).EMAIL_SENDER_DOMAIN).toBe(PROD_DOMAIN); expect((env.staging.vars as Record).EMAIL_SENDER_DOMAIN).toBe(STAGING_DOMAIN); }); + + it('keeps each API and public gateway environment on the same email routing identity', () => { + const config = parseJsonc( + readFileSync(new URL('../../../api/wrangler.jsonc', import.meta.url), 'utf8'), + ); + const gatewayConfig = parseJsonc( + readFileSync(new URL('../../../email-gateway/wrangler.jsonc', import.meta.url), 'utf8'), + ); + const env = config.env as Record>; + const proxyEnv = wranglerConfig.env as Record>; + const gatewayEnv = gatewayConfig.env as Record>; + for (const [name, scope, proxy, gateway] of [ + ['top level', config, wranglerConfig, gatewayConfig], + ['env.production', env.production, proxyEnv.production, gatewayEnv.production], + ['env.staging', env.staging, proxyEnv.staging, gatewayEnv.staging], + ] as const) { + const vars = scope.vars as Record; + const domain = vars.EMAIL_SENDER_DOMAIN; + const binding = ( + scope.send_email as Array<{ + name?: string; + allowed_sender_addresses?: Array; + }> + ).find((entry) => entry.name === 'EMAIL'); + expect(domain, `${name} EMAIL_SENDER_DOMAIN`).toBeTruthy(); + expect(binding?.allowed_sender_addresses, `${name} EMAIL binding`).toContain( + `noreply@${domain}`, + ); + expect(gateway.workers_dev, `${name} public email gateway`).toBe(true); + const proxyVars = proxy.vars as Record; + const gatewayVars = gateway.vars as Record; + expect(proxyVars.EMAIL_SENDER_DOMAIN, `${name} proxy sender domain`).toBe(domain); + expect(gatewayVars.EMAIL_SENDER_DOMAIN, `${name} gateway sender domain`).toBe(domain); + for (const key of ['EMAIL_SHARED_ACCOUNT_ID', 'EMAIL_SHARED_ZONE_ID']) { + expect(vars[key], `${name} API ${key}`).toMatch(/^[0-9a-f]{32}$/); + expect(gatewayVars[key], `${name} gateway ${key}`).toBe(vars[key]); + } + expect(vars.EMAIL_GATEWAY_ORIGIN, `${name} confirmation gateway origin`).toBe( + `https://${String(gateway.name)}.voidzer0.workers.dev`, + ); + expect(vars.EMAIL_SHARED_INGRESS_NAME).toBe(gateway.name); + expect(gatewayVars.EMAIL_SHARED_INGRESS_NAME).toBe(gateway.name); + expect(proxy.services).toContainEqual({ binding: 'API', service: scope.name }); + expect(gateway.services).toContainEqual({ binding: 'API', service: scope.name }); + } + const productionVars = env.production.vars as Record; + const stagingVars = env.staging.vars as Record; + expect(stagingVars.EMAIL_SHARED_ACCOUNT_ID).toBe(productionVars.EMAIL_SHARED_ACCOUNT_ID); + expect(stagingVars.EMAIL_SHARED_ZONE_ID).not.toBe(productionVars.EMAIL_SHARED_ZONE_ID); + expect(stagingVars.EMAIL_SENDER_DOMAIN).not.toBe(productionVars.EMAIL_SENDER_DOMAIN); + expect(gatewayEnv.production.secrets).toEqual({ required: ['JWT_SECRET'] }); + expect(gatewayEnv.staging.secrets).toEqual({ required: ['JWT_SECRET'] }); + }); }); describe('POST /email/send — sender domain', () => { @@ -437,117 +479,6 @@ describe('POST /email/send — platform capability', () => { }); }); -describe('POST /email/internal/send', () => { - async function internalBody( - domain: string, - overrides: Record = {}, - ): Promise> { - const from = `noreply@${domain}`; - const to = 'dev@example.com'; - const mime = mimeBase64(); - const body = { from, to, mimeBase64: mime, ...overrides }; - const timestamp = Math.floor(Date.now() / 1000); - const hash = await sha256Hex( - `${body.from as string}|${body.to as string}|${body.mimeBase64 as string}`, - ); - return { - ...body, - platformTimestamp: timestamp, - platformToken: await signHmac( - `void-platform-internal-email-v1.${timestamp}.${hash}`, - JWT_SECRET, - ), - }; - } - - async function postInternal( - env: Record, - body: Record, - ): Promise { - return (worker.fetch as (req: Request, env: unknown) => Promise)( - new Request('https://proxy.void.cloud/email/internal/send', { - method: 'POST', - headers: { 'content-type': 'application/json' }, - body: JSON.stringify(body), - }), - env, - ); - } - - it('accepts noreply@ on the configured domain', async () => { - const env = createMockEnv(createMockKv()); - const res = await postInternal(env, await internalBody(PROD_DOMAIN)); - expect(res.status).toBe(200); - expect((env.SEND_EMAIL as { send: ReturnType }).send).toHaveBeenCalledTimes(1); - }); - - it('rejects noreply@ on a different domain than the one configured', async () => { - const env = createMockEnv(createMockKv(), { EMAIL_SENDER_DOMAIN: STAGING_DOMAIN }); - const res = await postInternal(env, await internalBody(PROD_DOMAIN)); - expect(res.status).toBe(403); - expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); - }); - - it('rejects a non-noreply local part on the configured domain', async () => { - const env = createMockEnv(createMockKv()); - const res = await postInternal( - env, - await internalBody(PROD_DOMAIN, { from: `billing@${PROD_DOMAIN}` }), - ); - expect(res.status).toBe(403); - }); - - it('rejects an unsigned request', async () => { - const env = createMockEnv(createMockKv()); - const body = await internalBody(PROD_DOMAIN); - const res = await postInternal(env, { ...body, platformToken: 'nope' }); - expect(res.status).toBe(403); - expect((env.SEND_EMAIL as { send: ReturnType }).send).not.toHaveBeenCalled(); - }); - - it('fails closed when EMAIL_SENDER_DOMAIN is unset', async () => { - const env = createMockEnv(createMockKv(), { EMAIL_SENDER_DOMAIN: '' }); - const res = await postInternal(env, await internalBody(PROD_DOMAIN)); - expect(res.status).toBe(502); - }); - - it('is behind the same email capability gate as /email/send', async () => { - const env = createMockEnv(createMockKv(), { - PLATFORM_CAPABILITIES: JSON.stringify({ email: false }), - }); - const res = await postInternal(env, await internalBody(PROD_DOMAIN)); - expect(res.status).toBe(501); - 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 { if (typeof raw === 'string') { return new TextEncoder().encode(raw); @@ -685,7 +616,7 @@ 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 () => { + it('shares one request deadline across admission and binding fan-out', async () => { vi.useFakeTimers(); try { const recipients = ['first@example.com', 'second@example.com', 'third@example.com']; @@ -707,12 +638,27 @@ describe('POST /email/send — request validation', () => { return new Promise(() => {}); }); const env = createMockEnv(kv, { SEND_EMAIL: { send } }); + const apiFetch = (env.API as { fetch: ReturnType }).fetch; + const normalFetch = apiFetch.getMockImplementation()!; + let markAdmissionStarted!: () => void; + const admissionStarted = new Promise((resolve) => { + markAdmissionStarted = resolve; + }); + apiFetch.mockImplementation(async (url, init) => { + if (String(url).endsWith('/admit')) { + markAdmissionStarted(); + await new Promise((resolve) => setTimeout(resolve, 10_000)); + } + return normalFetch(url, init); + }); const pending = postSend(env, await sendBody({ recipients })); + await admissionStarted; + await vi.advanceTimersByTimeAsync(10_000); await firstSubmitted; await vi.advanceTimersByTimeAsync(30_000); await secondSubmitted; - await vi.advanceTimersByTimeAsync(30_000); + await vi.advanceTimersByTimeAsync(5_000); const body = await readSend(await pending); expect(send).toHaveBeenCalledTimes(2); @@ -1282,6 +1228,16 @@ describe('POST /email/send — per-recipient fan-out', () => { }); describe('POST /email/send — sender domain is configuration, never a baked-in default', () => { + it('accepts multiple safe plus-tag segments on a shared sender', async () => { + const from = `acme+support+forward.run@${PROD_DOMAIN}`; + const sender = createSender(); + const env = createMockEnv(happyPathKv(), { SEND_EMAIL: sender.binding }); + const res = await postSend(env, await sendBody({ from })); + + expect((await readSend(res)).ok).toBe(true); + expect(sender.calls).toMatchObject([{ from }]); + }); + it.each([ ['unset', undefined], ['an empty string', ''], @@ -1312,485 +1268,6 @@ describe('POST /email/send — sender domain is configuration, never a baked-in }); }); -// --------------------------------------------------------------------------- -// Platform-internal endpoint. Auth is an HMAC of -// `..` under JWT_SECRET. -// The content binding is what stops a captured token inside the skew window -// from being replayed against a different recipient or different bytes. -// --------------------------------------------------------------------------- -describe('POST /email/internal/send — replay window + content binding', () => { - const SENTINEL = 'void-platform-internal-email-v1'; - const FROM = `noreply@${PROD_DOMAIN}`; - const TO = 'recipient@example.com'; - - async function signPlatform(opts: { - unixSeconds: number; - from: string; - to: string; - mimeBase64: string; - }): Promise { - const hash = await sha256Hex(`${opts.from}|${opts.to}|${opts.mimeBase64}`); - return signHmac(`${SENTINEL}.${opts.unixSeconds}.${hash}`, JWT_SECRET); - } - - async function post( - env: Record, - body: Record, - ): Promise { - return (worker.fetch as (req: Request, env: unknown) => Promise)( - new Request('https://proxy.void.cloud/email/internal/send', { - method: 'POST', - headers: { 'content-type': 'application/json' }, - body: JSON.stringify(body), - }), - env, - ); - } - - it('accepts a token signed for exactly this body', async () => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64('Subject: Confirm\r\n\r\nclick the link\r\n'); - const platformTimestamp = Math.floor(Date.now() / 1000); - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(200); - expect(sender.recipients()).toEqual([TO]); - expect(sender.texts()).toEqual(['Subject: Confirm\r\n\r\nclick the link\r\n']); - }); - - it.each([ - ['stale by more than the 5-minute window', -6 * 60], - ['future-dated by more than the 5-minute window', 6 * 60], - ])('rejects a token %s with 403', async (_label, offset) => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000) + offset; - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(403); - expect(sender.calls).toHaveLength(0); - }); - - it.each([ - ['4 minutes in the past', -4 * 60], - ['4 minutes in the future', 4 * 60], - ])('accepts a token %s (inside the skew window)', async (_label, offset) => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000) + offset; - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(200); - expect(sender.calls).toHaveLength(1); - }); - - it('rejects a captured token replayed with a different (in-window) timestamp', async () => { - // Extending a captured token's life by moving the timestamp forward must - // fail: the timestamp is part of the signed message. - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const signedAt = Math.floor(Date.now() / 1000); - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: signedAt, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp: signedAt + 60, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(403); - expect(sender.calls).toHaveLength(0); - }); - - it.each([ - ['the recipient', { to: 'attacker@evil.com' }], - ['the MIME bytes', { mimeBase64: mimeBase64('Subject: swapped\r\n\r\nB\r\n') }], - ['the envelope sender', { from: `noreply@${STAGING_DOMAIN}` }], - ])('rejects a token replayed after changing %s', async (_label, tamper) => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64('Subject: Confirm\r\n\r\nA\r\n'); - const platformTimestamp = Math.floor(Date.now() / 1000); - const platformToken = await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - const res = await post(env, { - platformToken, - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - ...tamper, - }); - expect(res.status).toBe(403); - expect(sender.calls).toHaveLength(0); - }); - - it.each([ - ['platformToken', 'platformToken'], - ['platformTimestamp', 'platformTimestamp'], - ['from', 'from'], - ['to', 'to'], - ['mimeBase64', 'mimeBase64'], - ])('rejects with 403 when `%s` is missing', async (_label, field) => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const body: Record = { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }; - delete body[field]; - const res = await post(env, body); - // Malformed bodies are rejected at the auth boundary, not by the handler, - // so nothing leaks about which field the verifier could not bind. - expect(res.status).toBe(403); - expect(sender.calls).toHaveLength(0); - }); - - it("refuses a user worker's own project HMAC aimed at the internal endpoint", async () => { - // A user worker holds HMAC(projectId); it does not hold JWT_SECRET and - // cannot produce HMAC(sentinel.ts.hash). - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const res = await post(env, { - platformToken: await signHmac('proj_1', JWT_SECRET), - platformTimestamp: Math.floor(Date.now() / 1000), - from: FROM, - to: TO, - mimeBase64: mimeBase64(), - }); - expect(res.status).toBe(403); - expect(sender.calls).toHaveLength(0); - }); - - it('allows exactly one `from` — noreply@ on the configured zone', async () => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - // Correctly signed for this exact body — auth passes, the allow-list is - // what refuses. Without it, a compromised api worker could send - // arbitrary platform-branded mail. - const from = `support@${PROD_DOMAIN}`; - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(403); - expect(sender.calls).toHaveLength(0); - }); - - it('rejects invalid base64 and oversized JSON bodies before sending', async () => { - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - - const badTs = Math.floor(Date.now() / 1000); - const bad = await post(env, { - platformToken: await signPlatform({ - unixSeconds: badTs, - from: FROM, - to: TO, - mimeBase64: '!!!not-base64!!!', - }), - platformTimestamp: badTs, - from: FROM, - to: TO, - mimeBase64: '!!!not-base64!!!', - }); - expect(bad.status).toBe(400); - - // 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({ - unixSeconds: bigTs, - from: FROM, - to: TO, - mimeBase64: oversized, - }), - platformTimestamp: bigTs, - from: FROM, - to: TO, - mimeBase64: oversized, - }); - 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); - }); - - it.each([ - ['from', { from: 'a'.repeat(321), to: TO }], - ['to', { from: FROM, to: 'a'.repeat(321) }], - ])('refuses an over-long `%s` at the auth boundary, before hashing it', async (_field, addrs) => { - // The MIME field was bounded before the content hash; `from` and `to` - // are hashed with it and were not. The template that joins the three - // flattens them into one full-size string and `TextEncoder` copies it - // again, both before the token is verified — so an unauthenticated - // caller with a small MIME still chose two full-size copies plus the - // sha256 over them. Same 320 as `/email/send`'s sender and recipient - // bounds, and the same opaque refusal as the other pre-auth gates: the - // body is `{ error: 'invalid platform token' }`, not the handler's - // `ok: false` shape, which is how this asserts the handler never ran. - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const res = await post(env, { - // Correctly signed for this exact body, so only the bound refuses it. - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - ...addrs, - mimeBase64: mime, - }), - platformTimestamp, - ...addrs, - mimeBase64: mime, - }); - expect(res.status).toBe(403); - expect(await res.json()).toEqual({ error: 'invalid platform token' }); - expect(sender.calls).toHaveLength(0); - }); - - it.each([ - ['one character short (42)', (t: string) => t.slice(0, 42)], - ['one character long (44)', (t: string) => `${t}A`], - ['4 MiB', () => 'ab-_'.repeat((4 * 1024 * 1024) / 4)], - ])('refuses a token that is %s before decoding it', async (_label, mutate) => { - // 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(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const platformToken = mutate( - await signPlatform({ unixSeconds: platformTimestamp, from: FROM, to: TO, mimeBase64: mime }), - ); - const verify = vi.spyOn(crypto.subtle, 'verify'); - try { - const res = await post(env, { - platformToken, - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(403); - expect(await res.json()).toEqual({ error: 'invalid platform token' }); - expect(verify).not.toHaveBeenCalled(); - expect(sender.calls).toHaveLength(0); - } finally { - verify.mockRestore(); - } - }); - - it('a 43-character token that is not the signature is still refused by the HMAC, not the length gate', async () => { - // Pins the gate to LENGTH only: a well-formed but wrong token must reach - // `crypto.subtle.verify` and fail there, so the length check cannot be - // mistaken for the credential check. - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const platformToken = await signHmac('not-the-sentinel', JWT_SECRET); - expect(platformToken).toHaveLength(43); - const verify = vi.spyOn(crypto.subtle, 'verify'); - try { - const res = await post(env, { - platformToken, - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(403); - expect(await res.json()).toEqual({ error: 'invalid platform token' }); - expect(verify).toHaveBeenCalledTimes(1); - expect(sender.calls).toHaveLength(0); - } finally { - verify.mockRestore(); - } - }); - - it('a 320-character `to` under a valid signature still reaches the handler', async () => { - // The bound sits exactly where `/email/send` puts its recipient bound. - // The handler applies no length rule of its own to `to`: it hands the - // address to `EmailMessage`, so the send goes through with it verbatim. - const sender = createSender(); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const to = `${'a'.repeat(320 - '@example.com'.length)}@example.com`; - expect(to).toHaveLength(320); - const platformTimestamp = Math.floor(Date.now() / 1000); - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to, - mimeBase64: mime, - }); - expect(res.status).toBe(200); - expect(await res.json()).toEqual({ ok: true }); - expect(sender.calls).toHaveLength(1); - expect(sender.calls[0].to).toBe(to); - }); - - it('fails closed with 502 when the SEND_EMAIL binding is missing', async () => { - const env = createMockEnv(createMockKv(), { SEND_EMAIL: undefined }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(502); - }); - - it('reports 502 without leaking the upstream message when CF rejects the send', async () => { - const sender = createSender({ fail: () => new Error('cf mta exploded') }); - const env = createMockEnv(createMockKv(), { SEND_EMAIL: sender.binding }); - const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); - try { - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(502); - expect(await res.json()).toEqual({ ok: false, error: 'upstream error' }); - } finally { - consoleError.mockRestore(); - } - }); - - it('applies no per-project gate: platform mail touches neither quota nor allowlist', async () => { - // Documented contract — verification mail is account-level, bounded by - // the api worker's own rate limit on POST /destinations. - const kv = happyPathKv({ 'email-suspended:proj_1': '1' }); - const sender = createSender(); - const env = createMockEnv(kv, { SEND_EMAIL: sender.binding }); - const mime = mimeBase64(); - const platformTimestamp = Math.floor(Date.now() / 1000); - const res = await post(env, { - platformToken: await signPlatform({ - unixSeconds: platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }), - platformTimestamp, - from: FROM, - to: TO, - mimeBase64: mime, - }); - expect(res.status).toBe(200); - expect(kv.get).not.toHaveBeenCalled(); - expect(kv.put).not.toHaveBeenCalled(); - expect(sender.calls).toHaveLength(1); - }); -}); - describe('POST /email/send — the envelope handed to CF', () => { /** * The regex is tested against `from.toLowerCase()` but `EmailMessage` diff --git a/platform/packages/proxy/test/unit/proxy.test.ts b/platform/packages/proxy/test/unit/proxy.test.ts index e08a8a067..890b7205e 100644 --- a/platform/packages/proxy/test/unit/proxy.test.ts +++ b/platform/packages/proxy/test/unit/proxy.test.ts @@ -373,7 +373,7 @@ describe('proxy worker', () => { expect(response.status).toBe(403); }); - it.each(['/email/send', '/email/internal/send', '/email/unknown'])( + it.each(['/email/send', '/email/unknown'])( 'rejects an oversized declared body before reading %s', async (path) => { const pull = vi.fn((controller: ReadableStreamDefaultController) => { diff --git a/platform/packages/proxy/wrangler.jsonc b/platform/packages/proxy/wrangler.jsonc index 13f778c10..0d53fd7c8 100644 --- a/platform/packages/proxy/wrangler.jsonc +++ b/platform/packages/proxy/wrangler.jsonc @@ -90,7 +90,7 @@ }, ], "send_email": [{ "name": "SEND_EMAIL" }], - "vars": { "EMAIL_SENDER_DOMAIN": "mail.staging.void.cloud" }, + "vars": { "EMAIL_SENDER_DOMAIN": "mail.voidcloud.dev" }, "routes": [{ "pattern": "proxy.staging.void.cloud", "custom_domain": true }], }, },