@rivi-software/workers-mail 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,10 @@
 # @rivi-software/workers-mail
 
+[![npm version](https://img.shields.io/npm/v/@rivi-software/workers-mail?label=npm&color=0b6b3a)](https://www.npmjs.com/package/@rivi-software/workers-mail) [![CI status](https://img.shields.io/github/actions/workflow/status/rivi-software/tools/ci.yml?branch=main&label=CI)](https://github.com/rivi-software/tools/actions/workflows/ci.yml) [![MIT License](https://img.shields.io/badge/license-MIT-0b6b3a)](LICENSE)
+
 Mail from Cloudflare Workers through [Amazon SES](https://aws.amazon.com/ses/) once a Worker holds SES's key, and through [Cloudflare Email Service](https://developers.cloudflare.com/email-service/)'s `send_email` binding until then and whenever SES refuses a message. One call, `sendMail(env, mail)`, picks the transport, formats the addresses and headers for it, and answers with the `Message-ID` the message went out with, so a reply threads back.
 
-The binding needs no keys and sends from the day a domain is onboarded; SES takes larger messages and list mail, but needs a verified identity, production access and an IAM key first. With both set up, mail keeps going while SES is not ready yet, and when SES refuses a message (an identity not verified yet, a policy that does not allow the address, a throttle) the binding sends it instead. SES goes through the [Email SDK](https://email-sdk.dev/docs/adapters/ses) (`@opencoredev/email-sdk`), which signs SES's API v2 requests with `fetch` and Web Crypto, so the Worker needs no AWS SDK.
+The binding needs no keys and sends from the day a domain is onboarded; SES takes larger messages and list mail, but needs a verified identity, production access and an IAM key first. With both set up, mail keeps going while SES is not ready yet, and when SES refuses a message (an identity not verified yet, a policy that does not allow the address, a throttle) the binding sends it instead. SES goes through the [Email SDK](https://email-sdk.dev/docs/adapters/ses) (`@opencoredev/email-sdk`), which signs SES's API v2 requests with `fetch` and Web Crypto, so the Worker needs no AWS SDK. A message written out in full, such as signed or encrypted PGP/MIME, goes out unchanged through `sendRawMail` ([Raw mail](#raw-mail)).
 
 ## Install
 
@@ -86,6 +88,31 @@ What differs between the two transports, and what the package does about it:
 - **List mail.** Email Service takes transactional mail only, so newsletters and other list mail go through `sendWithSes`, which never falls back.
 - **Idempotency.** Neither has any; a caller that retries can deliver twice.
 
+## Raw mail
+
+`sendMail` hands the transport fields, and the transport writes the message. A message that has to go out byte for byte as it was written, such as PGP/MIME (RFC 3156: `multipart/signed`, `multipart/encrypted`), whose signature covers the bytes of a part, goes through `sendRawMail(env, mail)` instead. It chooses the transport as `sendMail` does, hands a message SES refused to the binding on the same terms, and writes the same `mail.ses_refused` line.
+
+```ts
+import { sendRawMail } from "@rivi-software/workers-mail";
+
+const sent = await sendRawMail(env, {
+  from: "jane@example.com",
+  // To, Cc and Bcc together: the message names no Bcc.
+  recipients: ["bob@example.org", "carol@example.org", "dave@example.org"],
+  // Its headers, a blank line, the body; CRLF line ends, 7-bit.
+  raw,
+  sesOnlyHeaders: { Autocrypt: "addr=jane@example.com; keydata=…" },
+});
+```
+
+- **The envelope.** `from` and `recipients` are bare addresses, and they are where the message goes: neither transport reads a recipient from the message's headers. A Bcc recipient is in `recipients` and nowhere in `raw`, or every recipient would see it. A message without recipients is refused.
+- **SES** takes the message as `Content.Raw` of API v2's `SendEmail`. The Email SDK's adapter sends structured content only, so the package signs this call itself, with Signature Version 4 in Web Crypto. SES writes its own `Message-ID` over the message's, and `SentMail.messageId` names it, as for `sendMail`.
+- **The binding** takes a message written out in full only as the `EmailMessage` of `cloudflare:email`, which has one envelope recipient. So the message goes once per recipient, in order, the same bytes each time, and each send counts as a message against Email Service's limits; `SentMail` names the first send's `messageId`. When a send fails after others went, the `MailError` has the binding's `code` and says how many of how many recipients took the message, counts and never addresses, since it reaches logs: sending it again would deliver it twice to those. The package imports `cloudflare:email` only when the binding sends, so it still loads outside the Workers runtime.
+- **SES-only headers.** Email Service takes only the headers on [its allowlist](https://developers.cloudflare.com/email-service/reference/headers/), so a header it refuses, such as `Autocrypt`, goes in `sesOnlyHeaders`: SES gets it on a line above the message, and the binding gets the message without it. PGP/MIME signs a part and never the message's own headers, so the signature still holds. A value may be folded (CRLF, then a space or tab, then more than white space: a line of white space alone reads as the end of the header to some parsers). A name of anything but letters, digits and hyphens, or a value with any other CR or LF, would write a header or a body of its own into the message, so it is refused before anything is sent, with a `MailError` that has no status, whichever transport is set up.
+- **Tags.** SES gets `tags` as for `sendMail`; the binding drops them.
+
+`sendRawWithSes(config, mail, { configurationSet })` and `sendRawWithBinding(binding, mail)` send through one transport alone, and never fall back.
+
 ## Exports
 
 From `@rivi-software/workers-mail`:
@@ -95,6 +122,9 @@ From `@rivi-software/workers-mail`:
 | `sendMail(env, mail)` | Transactional mail: SES when `env` holds its region and key, else `env.EMAIL`, and `env.EMAIL` when SES refuses the message ([How it works](#how-it-works)). Answers `SentMail`: the `transport`, the provider's `id` and the `messageId` header. |
 | `sendWithSes(config, mail, { configurationSet })` | SES alone, never the binding: list mail, which Email Service does not take, with the configuration set whose event destinations report its bounces and complaints. |
 | `sendWithBinding(binding, mail)` | The binding alone. |
+| `sendRawMail(env, mail)` | A message written out in full (`RawMail`), with `sendMail`'s choice of transport and fallback ([Raw mail](#raw-mail)). |
+| `sendRawWithSes(config, mail, { configurationSet })` | A raw message through SES alone. |
+| `sendRawWithBinding(binding, mail)` | A raw message through the binding alone: one send per recipient. |
 | `canSendMail(env)`, `sesConfig(env)` | Whether a Worker can send at all; SES's region and key, or null while one of them is missing. |
 | `MailError` | A message that was not sent: `transport`, SES's HTTP `status` (absent when SES was not reached or the binding failed), `code` (SES's error type such as `MessageRejected`, or the binding's such as `E_RATE_LIMIT_EXCEEDED`) and `refusedMessage`, true when SES refused the message itself, so that sending it again fails the same way. |
 | `sesError(response)` | The `MailError` for an error answer from SES's API, for calls the Email SDK does not make, such as reading the account's quota with `GetAccount`. |
@@ -102,10 +132,12 @@ From `@rivi-software/workers-mail`:
 | `formatSesAddress(address)` | The address as SES takes it: the name quoted, or MIME-encoded when it is not ASCII. |
 | `fitReferences(value, max = 986)` | A `References` value cut to `max` characters: the first message and the latest. |
 | `sesMessageId(region, id)` | The `Message-ID` header SES gives the message it answered `id` for. |
-| Types | `Mail`, `MailAddress`, `MailAttachment`, `MailEnv`, `MailTransport`, `SentMail`, `SesConfig`, `EmailBinding`. |
+| Types | `Mail`, `RawMail`, `MailAddress`, `MailAttachment`, `MailEnv`, `MailTransport`, `SentMail`, `SesConfig`, `EmailBinding`. |
 
 A `Mail` has `from`, `to` (one address or a list), `cc`, `bcc` and `replyTo`, each address as `jane@example.com`, `Jane <jane@example.com>` or `{ email, name }`; a `subject`; `text` and/or `html`; `headers`; `attachments` as base64 (`disposition` `attachment`, or `inline` with the `contentId` the HTML names as `cid:`); and SES message `tags`.
 
+A `RawMail` has the envelope's `from` and `recipients` as bare addresses, the message as `raw`, `sesOnlyHeaders` and SES message `tags`.
+
 From `@rivi-software/workers-mail/address`:
 
 | Export | What |
@@ -145,7 +177,7 @@ SES's account-level suppression list (SES → Configuration → Suppression list
 
 ## Testing a Worker that sends
 
-The package's own tests run in Node with Vitest: SES is answered by a spy on the global `fetch`, which the package looks up on each call, and the binding by an object that records what it was handed. A Worker's tests can do the same: leave the three SES values empty and pass an `EMAIL` that records the mail, or set them and spy on `fetch` to answer as SES does ([`tests/mail.test.ts`](https://github.com/rivi-software/tools/blob/main/packages/workers-mail/tests/mail.test.ts) has both).
+The package's own tests run in Node with Vitest: SES is answered by a spy on the global `fetch`, which the package looks up on each call, and the binding by an object that records what it was handed. A Worker's tests can do the same: leave the three SES values empty and pass an `EMAIL` that records the mail, or set them and spy on `fetch` to answer as SES does ([`tests/mail.test.ts`](https://github.com/rivi-software/tools/blob/main/packages/workers-mail/tests/mail.test.ts) has both). Raw mail through the binding needs `cloudflare:email`, which Node lacks: the package's `vitest.config.ts` points it at a stand-in `EmailMessage` that keeps the message readable ([`tests/raw.test.ts`](https://github.com/rivi-software/tools/blob/main/packages/workers-mail/tests/raw.test.ts)).
 
 ## Limits
 
@@ -154,11 +186,27 @@ The package's own tests run in Node with Vitest: SES is answered by a spy on the
 - `References` is fitted for SES alone; Email Service refuses a header value over 2,048 bytes ([Headers](#how-it-works)).
 - Attachments are base64 strings: Email Service's local simulator in `wrangler dev` cannot take an `ArrayBuffer`, and SES wants base64.
 - Through the binding, recipients' display names are dropped.
+- Raw mail through the binding goes once per recipient, and a failure partway leaves it sent to some of them ([Raw mail](#raw-mail)).
 
 ## Development
 
-The tests in `tests/` cover both transports and the fallback between them against a stand-in SES and binding, the addresses and headers each transport takes, the telemetry opt-out (`mail.test.ts`) and the address parser (`address.test.ts`). None of them sends mail. In this directory, run `pnpm run test`, `pnpm run check` and `pnpm run build`.
+The tests in `tests/` cover both transports and the fallback between them against a stand-in SES and binding, the addresses and headers each transport takes, the telemetry opt-out (`mail.test.ts`), raw mail and the Signature Version 4 signer against AWS's own example (`raw.test.ts`) and the address parser (`address.test.ts`). None of them sends mail. In this directory, run `pnpm run test`, `pnpm run check` and `pnpm run build`.
 
 ## License
 
-[MIT](LICENSE)
+Licensed under the [MIT License](LICENSE). Copyright © 2026 RIVI Software.
+
+<br>
+
+<p align="center">
+  <a href="https://rivi.software">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rivi-software/tools/main/assets/rivi-mark-on-dark.svg">
+      <img src="https://raw.githubusercontent.com/rivi-software/tools/main/assets/rivi-mark.svg" alt="RIVI Software" width="36" height="36">
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <sub>Part of <a href="https://github.com/rivi-software/tools#readme">RIVI tools</a>, the packages <a href="https://rivi.software">RIVI Software</a> builds its own apps with.</sub>
+</p>

package/dist/index.d.ts

@@ -99,6 +99,43 @@ export declare function sendWithSes(config: SesConfig, mail: Mail, options?: {
 }): Promise<SentMail>;
 /** Sends through Email Service's `send_email` binding alone. Recipients go as bare addresses, as it requires. */
 export declare function sendWithBinding(binding: EmailBinding, mail: Mail): Promise<SentMail>;
+/** A message already written out in full, for `sendRawMail`, `sendRawWithSes` or `sendRawWithBinding`. */
+export type RawMail = {
+    /** The envelope sender: a bare address on a domain the transport may send from. */
+    from: string;
+    /** The envelope recipients (To, Cc and Bcc together), bare addresses. The message itself names no Bcc. */
+    recipients: readonly string[];
+    /** The RFC 5322 message: its headers, a blank line, the body; CRLF line ends, 7-bit. */
+    raw: string;
+    /**
+     * Headers SES carries above `raw` that Email Service's allowlist refuses (`Autocrypt`): the binding sends the
+     * message without them. A value may be folded (CRLF, a space or tab, then more than white space); anything else
+     * with CR or LF is refused.
+     */
+    sesOnlyHeaders?: Record<string, string>;
+    /** SES message tags, as in `Mail`; the binding has none and drops them. */
+    tags?: Record<string, string>;
+};
+/**
+ * Sends a message the caller wrote out in full, such as signed or encrypted PGP/MIME, which has to go out byte for
+ * byte as it was written; `sendMail` builds its message from fields and cannot carry one. The transport is chosen
+ * as `sendMail` chooses it: SES when the Worker holds its key, else the `EMAIL` binding, and the binding when SES
+ * answers with a refusal, never after an SES call that got no answer.
+ */
+export declare function sendRawMail(env: MailEnv, mail: RawMail): Promise<SentMail>;
+/**
+ * Sends a raw message through Amazon SES (API v2) alone, `sesOnlyHeaders` above the message; `configurationSet`
+ * names the set whose event destinations see it.
+ */
+export declare function sendRawWithSes(config: SesConfig, mail: RawMail, options?: {
+    configurationSet?: string;
+}): Promise<SentMail>;
+/**
+ * Sends a raw message through Email Service's binding alone. The binding takes raw MIME only as the `EmailMessage`
+ * of `cloudflare:email`, which has one envelope recipient, so the message goes once per recipient, in order, the
+ * same bytes each time and without `sesOnlyHeaders`. Answers the first send's `messageId`.
+ */
+export declare function sendRawWithBinding(binding: EmailBinding, mail: RawMail): Promise<SentMail>;
 /** An address with its display name apart; `Jane <jane@example.com>` and `"Jane" <jane@example.com>` are read too. */
 export declare function addressParts(address: MailAddress): {
     email: string;

package/dist/index.js

@@ -2,6 +2,7 @@ import { createEmailClient, disableTelemetry, } from "@opencoredev/email-sdk";
 import { cloudflare } from "@opencoredev/email-sdk/cloudflare";
 import { ses } from "@opencoredev/email-sdk/ses";
 import { parseMailAddress } from "./address.js";
+import { signAwsRequest } from "./sigv4.js";
 // The SDK reports every client and send to its maker's PostHog unless told not to. Off for the whole process,
 // clients that other code creates included; every client here is created with `telemetry: false` as well.
 disableTelemetry();
@@ -48,10 +49,14 @@ export function canSendMail(env) {
  * transactional mail only.
  */
 export async function sendMail(env, mail) {
+    return sendThrough(env, (config) => sendWithSes(config, mail), (binding) => sendWithBinding(binding, mail));
+}
+/** The transport `sendMail` and `sendRawMail` both choose, and the fallback from SES to the binding. */
+async function sendThrough(env, withSes, withBinding) {
     const config = sesConfig(env);
     if (config) {
         try {
-            return await sendWithSes(config, mail);
+            return await withSes(config);
         }
         catch (err) {
             if (!(err instanceof MailError && err.status !== undefined && env.EMAIL))
@@ -64,7 +69,7 @@ export async function sendMail(env, mail) {
         throw new MailError("No mail transport: neither Amazon SES nor the EMAIL binding is set up.", {
             transport: "email-service",
         });
-    return sendWithBinding(env.EMAIL, mail);
+    return withBinding(env.EMAIL);
 }
 /** Sends through Amazon SES (API v2) alone; `configurationSet` names the set whose event destinations see it. */
 export async function sendWithSes(config, mail, options = {}) {
@@ -93,6 +98,119 @@ export async function sendWithBinding(binding, mail) {
     });
     return { transport: "email-service", id: result.id, messageId: result.id };
 }
+/**
+ * Sends a message the caller wrote out in full, such as signed or encrypted PGP/MIME, which has to go out byte for
+ * byte as it was written; `sendMail` builds its message from fields and cannot carry one. The transport is chosen
+ * as `sendMail` chooses it: SES when the Worker holds its key, else the `EMAIL` binding, and the binding when SES
+ * answers with a refusal, never after an SES call that got no answer.
+ */
+export async function sendRawMail(env, mail) {
+    // Refused whichever transport is set up, so a bad header fails where only the binding sends (local development)
+    // as it would through SES.
+    sesHeaderLines(mail.sesOnlyHeaders);
+    return sendThrough(env, (config) => sendRawWithSes(config, mail), (binding) => sendRawWithBinding(binding, mail));
+}
+/**
+ * Sends a raw message through Amazon SES (API v2) alone, `sesOnlyHeaders` above the message; `configurationSet`
+ * names the set whose event destinations see it.
+ */
+export async function sendRawWithSes(config, mail, options = {}) {
+    const headerLines = sesHeaderLines(mail.sesOnlyHeaders);
+    needsRecipients(mail, "ses");
+    const url = new URL("/v2/email/outbound-emails", `https://email.${config.region}.amazonaws.com`);
+    const body = JSON.stringify({
+        FromEmailAddress: mail.from,
+        // The envelope: SES delivers to these and reads no recipient from the message's headers.
+        Destination: { ToAddresses: mail.recipients },
+        Content: { Raw: { Data: base64(headerLines + mail.raw) } },
+        ConfigurationSetName: options.configurationSet?.trim() || undefined,
+        EmailTags: mail.tags && Object.entries(mail.tags).map(([Name, Value]) => ({ Name, Value })),
+    });
+    let answer;
+    try {
+        // The headers the Email SDK's SES adapter sends, and no timeout, as it has none.
+        const headers = await signAwsRequest({ method: "POST", url, headers: { "content-type": "application/json" }, body }, { ...config, service: "ses" });
+        const res = await sesFetch(url, { method: "POST", headers, body });
+        // SES took the message once it answered with success, so a body that does not read is no failure.
+        answer = (await res.json().catch(() => ({})));
+    }
+    catch (err) {
+        throw mailError(err, "ses");
+    }
+    const id = typeof answer.MessageId === "string" ? answer.MessageId : null;
+    return { transport: "ses", id, messageId: id ? sesMessageId(config.region, id) : null };
+}
+/**
+ * Sends a raw message through Email Service's binding alone. The binding takes raw MIME only as the `EmailMessage`
+ * of `cloudflare:email`, which has one envelope recipient, so the message goes once per recipient, in order, the
+ * same bytes each time and without `sesOnlyHeaders`. Answers the first send's `messageId`.
+ */
+export async function sendRawWithBinding(binding, mail) {
+    needsRecipients(mail, "email-service");
+    // Imported here rather than with the package, so the package still loads outside the Workers runtime.
+    const { EmailMessage } = await import("cloudflare:email").catch((err) => {
+        throw mailError(err, "email-service");
+    });
+    let first = null;
+    for (const [sent, to] of mail.recipients.entries()) {
+        let answer;
+        try {
+            answer = await binding.send(new EmailMessage(mail.from, to, mail.raw));
+        }
+        catch (err) {
+            const error = mailError(err, "email-service");
+            if (sent === 0)
+                throw error;
+            // Counts only, never the addresses: the message reaches logs.
+            throw new MailError(`The EMAIL binding sent the message to ${sent} of ${mail.recipients.length} recipients, then failed` +
+                `${error.code ? ` with ${error.code}` : ""}; sending it again would deliver it twice to those ${sent}.`, { transport: "email-service", code: error.code, cause: err });
+        }
+        if (sent === 0) {
+            const id = answer?.messageId;
+            first = typeof id === "string" ? id : null;
+        }
+    }
+    return { transport: "email-service", id: first, messageId: first };
+}
+const HEADER_NAME = /^[A-Za-z0-9-]+$/;
+// No CR or LF but in a fold: CRLF, then a space or tab, and a line that is more than white space. A line of
+// white space alone is obsolete syntax (RFC 5322 §4.2) that some parsers read as the end of the header.
+const HEADER_VALUE = /^[^\r\n]*(?:\r\n[ \t]+[^\r\n \t][^\r\n]*)*$/;
+/**
+ * `sesOnlyHeaders` as the lines that go above the message. A line break that is not a fold would end the header
+ * and write headers or a body of its own into the message, so it is refused before anything is sent, and without
+ * a status, which would let the binding send the message instead.
+ */
+function sesHeaderLines(headers) {
+    let lines = "";
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (!HEADER_NAME.test(name))
+            throw new MailError("A header name in sesOnlyHeaders is not letters, digits and hyphens.", {
+                transport: "ses",
+                code: "validation_error",
+            });
+        if (!HEADER_VALUE.test(value))
+            throw new MailError(`The ${name} header in sesOnlyHeaders has a line break that is not a fold (CRLF, then a space or tab).`, { transport: "ses", code: "validation_error" });
+        lines += `${name}: ${value}\r\n`;
+    }
+    return lines;
+}
+// Without one, SES would read the recipients from the message's headers and the binding would send nothing.
+function needsRecipients(mail, transport) {
+    if (mail.recipients.length === 0)
+        throw new MailError("A raw message needs at least one recipient.", {
+            transport,
+            code: "validation_error",
+        });
+}
+/** The UTF-8 bytes of `text` in base64, a slice at a time: a message of megabytes is too many arguments at once. */
+function base64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
 async function send(adapter, transport, message) {
     try {
         const client = createEmailClient({ adapters: [adapter], telemetry: false });

package/dist/sigv4.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AWS Signature Version 4 with Web Crypto alone, for the SES calls the Email SDK does not make. The SDK has a
+ * signer of its own but does not export it. This one signs the same headers the SDK's SES adapter sends, so a
+ * request signed here reaches SES as one from the adapter does.
+ */
+/** An AWS access key, and the region and service a request is signed for. */
+export type AwsSigning = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    service: string;
+};
+/** A request to sign: the body as the string that is sent, the headers besides `host` and the `x-amz-*` ones. */
+export type AwsRequest = {
+    method: string;
+    url: URL;
+    headers: Record<string, string>;
+    body: string;
+};
+/**
+ * The headers to send `request` with: its own, `x-amz-content-sha256`, `x-amz-date` and `Authorization`. `host`
+ * is signed but left out, since `fetch` sets it from the URL. `now` is for a test's fixed clock.
+ */
+export declare function signAwsRequest(request: AwsRequest, signing: AwsSigning, now?: Date): Promise<Record<string, string>>;

package/dist/sigv4.js

@@ -0,0 +1,72 @@
+/**
+ * AWS Signature Version 4 with Web Crypto alone, for the SES calls the Email SDK does not make. The SDK has a
+ * signer of its own but does not export it. This one signs the same headers the SDK's SES adapter sends, so a
+ * request signed here reaches SES as one from the adapter does.
+ */
+/**
+ * The headers to send `request` with: its own, `x-amz-content-sha256`, `x-amz-date` and `Authorization`. `host`
+ * is signed but left out, since `fetch` sets it from the URL. `now` is for a test's fixed clock.
+ */
+export async function signAwsRequest(request, signing, now = new Date()) {
+    const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+    const dateStamp = amzDate.slice(0, 8);
+    const payloadHash = await sha256Hex(request.body);
+    const headers = {
+        ...request.headers,
+        "x-amz-content-sha256": payloadHash,
+        "x-amz-date": amzDate,
+    };
+    const canonicalHeaders = Object.entries({ ...headers, host: request.url.host })
+        .map(([name, value]) => [name.toLowerCase(), value.trim().replace(/\s+/g, " ")])
+        .sort(([a], [b]) => byCodeUnit(a, b));
+    const signedHeaders = canonicalHeaders.map(([name]) => name).join(";");
+    const scope = `${dateStamp}/${signing.region}/${signing.service}/aws4_request`;
+    const canonicalRequest = [
+        request.method.toUpperCase(),
+        // As the URL holds it, encoded once: what S3 signs, and the same as twice for a path of unreserved
+        // characters alone, such as SES's.
+        request.url.pathname || "/",
+        canonicalQuery(request.url.searchParams),
+        canonicalHeaders.map(([name, value]) => `${name}:${value}\n`).join(""),
+        signedHeaders,
+        payloadHash,
+    ].join("\n");
+    const stringToSign = ["AWS4-HMAC-SHA256", amzDate, scope, await sha256Hex(canonicalRequest)].join("\n");
+    let key = await hmac(utf8(`AWS4${signing.secretAccessKey}`), dateStamp);
+    for (const part of [signing.region, signing.service, "aws4_request"])
+        key = await hmac(key, part);
+    const signature = hex(await hmac(key, stringToSign));
+    return {
+        ...headers,
+        Authorization: `AWS4-HMAC-SHA256 Credential=${signing.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    };
+}
+/** The query as SigV4 signs it: each name and value encoded as RFC 3986 says, sorted by name, then by value. */
+function canonicalQuery(params) {
+    return [...params]
+        .map(([name, value]) => [uriEncode(name), uriEncode(value)])
+        .sort(([an, av], [bn, bv]) => byCodeUnit(an, bn) || byCodeUnit(av, bv))
+        .map(([name, value]) => `${name}=${value}`)
+        .join("&");
+}
+// SigV4 sorts by character code; localeCompare would follow the runtime's locale.
+function byCodeUnit(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+// encodeURIComponent leaves !'()* alone, which SigV4 wants encoded.
+function uriEncode(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+async function sha256Hex(value) {
+    return hex(new Uint8Array(await crypto.subtle.digest("SHA-256", utf8(value))));
+}
+async function hmac(key, value) {
+    const cryptoKey = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    return new Uint8Array(await crypto.subtle.sign("HMAC", cryptoKey, utf8(value)));
+}
+function utf8(value) {
+    return new TextEncoder().encode(value);
+}
+function hex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivi-software/workers-mail",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Mail from Cloudflare Workers: Amazon SES once the Worker holds its key, Cloudflare Email Service's send_email binding until then and whenever SES refuses a message",
   "keywords": [
     "cloudflare",