@x12i/email-service 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,71 @@
1
- # Temporary Holding Version
1
+ # @x12i/email-service
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Send mail through Cloudflare Email Sending from a Node.js application and handle incoming Cloudflare Email Routing events in a Worker. Bring the mail store, recipient permissions, and job queue your application uses. The package has ESM and TypeScript entry points.
4
+
5
+ This is the low-level transport API. For an authenticated durable outbound HTTP service, approved templates, workload scopes, encrypted jobs, idempotency, cancellation, delivery events and delegated composed mail, use the separate [notification service](../../docs/notification-service.md). It reuses this provider and leaves mailbox/identity ownership with the consumer.
6
+
7
+ ```sh
8
+ npm install @x12i/email-service
9
+ ```
10
+
11
+ ## Send from Node.js
12
+
13
+ Set `CF_ACCOUNT_ID`, `CF_ZONE_ID`, `CF_ZONE_NAME`, `CF_CONTROL_API_TOKEN`, `CF_SEND_DOMAIN`, and `CF_SEND_API_TOKEN` in the environment or a secret manager. Use an onboarded sending domain with message previews disabled and a dedicated send credential. Omit `CF_ROUTE_DOMAIN` for a send-only application.
14
+
15
+ For a pilot on Workers Free, set `CF_SEND_MODE=verified-destinations`. The sending domain must have Email Routing enabled with Cloudflare MX records. Give the control token Email Routing Addresses Read for the account so the adapter can check every To, Cc, and Bcc address against the live list of verified destinations. [Cloudflare sending limits](https://developers.cloudflare.com/email-service/platform/limits/#verified-destination-addresses)
16
+
17
+ ```ts
18
+ import { createCloudflareProvider, readCloudflareConfig } from "@x12i/email-service";
19
+
20
+ const config = readCloudflareConfig(process.env);
21
+ const mail = createCloudflareProvider(config);
22
+ const result = await mail.send({
23
+ correlationId: "receipt-42",
24
+ idempotencyKey: "receipt-42",
25
+ secretRef: config.secretRef,
26
+ class: "transactional",
27
+ from: "receipts@example.com",
28
+ fromName: "Example",
29
+ replyTo: null,
30
+ to: ["customer@example.net"],
31
+ cc: [],
32
+ bcc: [],
33
+ subject: "Your receipt",
34
+ text: "Payment received.",
35
+ html: null,
36
+ headers: {},
37
+ attachments: [],
38
+ recipientRefs: { "customer@example.net": "recipient-42" },
39
+ });
40
+ ```
41
+
42
+ `accepted` means Cloudflare processed the request. When Cloudflare reports an immediate delivery, bounce, or rejection, the result includes evidence keyed to the supplied recipient references. You can provide `recordEvidence` to persist those events before the result returns. Use `capabilities()` to check limits and supported classes. Cloudflare does not guarantee idempotency for this endpoint, so a timeout or an `unknown` outcome needs investigation before any resend. [Cloudflare Email Sending API](https://developers.cloudflare.com/email-service/api/send-emails/rest-api/)
43
+
44
+ ## Receive in a Cloudflare Worker
45
+
46
+ Route the intended email addresses to the Worker. The `/worker` entry point uses Web APIs and keeps the SMTP envelope separate from the raw message.
47
+
48
+ The adapter recognizes its rules by `CF_RULE_NAMESPACE` and the Worker name. The default namespace is `email-service`. Use the existing namespace when migrating an installation or rotating its credentials.
49
+
50
+ ```ts
51
+ import { receiveCloudflareEmail } from "@x12i/email-service/worker";
52
+
53
+ export default {
54
+ email(message, env) {
55
+ return receiveCloudflareEmail(message, {
56
+ allowedDomains: ["example.com"],
57
+ async deliver({ id, envelope, raw }) {
58
+ // Persist to your own store. This example uses a private R2 binding.
59
+ await env.MAIL_BUCKET.put(id, raw, { customMetadata: envelope });
60
+ return "stored";
61
+ },
62
+ });
63
+ },
64
+ };
65
+ ```
66
+
67
+ Use the delivery ID as the idempotency key. Return `stored` after the bytes and envelope are durable, or return a typed rejection when the recipient or message cannot be accepted. A failed persistence operation should throw. The adapter computes the ID from the envelope and message bytes, so replaying the same delivery keeps its ID. [Cloudflare Email Routing Workers API](https://developers.cloudflare.com/email-service/api/route-emails/email-handler/)
68
+
69
+ ## Pull from a hosted relay
70
+
71
+ When the application runs locally, use `createInboxRelayClient({ origin, token })` to pull mail from a deployed relay. Call `list(cursor)` to page through delivery IDs, `get(id)` to fetch the envelope and MIME bytes, and `acknowledge(id)` after the local store commits the receipt. Keep the token in the local application process. The relay retains any item whose acknowledgement fails, so the delivery ID must be unique in the local store.
@@ -0,0 +1,8 @@
1
+ export declare const MAX_MESSAGE_BYTES: number;
2
+ /** Canonical ASCII DNS name; international names must be supplied as IDNA A-labels. */
3
+ export declare function domainName(value: string): string | null;
4
+ /** Pilot transport supports SMTP dot-atom addresses; no SMTPUTF8, display name, or header syntax. */
5
+ export declare function smtpAddress(value: string): {
6
+ address: string;
7
+ domain: string;
8
+ } | null;
@@ -0,0 +1,21 @@
1
+ export const MAX_MESSAGE_BYTES = 25 * 1024 * 1024;
2
+ const label = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
3
+ const dotAtom = /^[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*$/i;
4
+ /** Canonical ASCII DNS name; international names must be supplied as IDNA A-labels. */
5
+ export function domainName(value) {
6
+ const name = value.toLowerCase().replace(/\.$/, "");
7
+ const labels = name.split(".");
8
+ return name.length <= 253 && labels.length >= 2 && labels.every((p) => label.test(p)) ? name : null;
9
+ }
10
+ /** Pilot transport supports SMTP dot-atom addresses; no SMTPUTF8, display name, or header syntax. */
11
+ export function smtpAddress(value) {
12
+ if (value.length > 254 || /[^\x21-\x7e]/.test(value))
13
+ return null;
14
+ const at = value.indexOf("@");
15
+ if (at < 1 || at > 64)
16
+ return null;
17
+ const local = value.slice(0, at);
18
+ const domain = domainName(value.slice(at + 1));
19
+ return dotAtom.test(local) && domain ? { address: `${local}@${domain}`, domain } : null;
20
+ }
21
+ //# sourceMappingURL=address.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD,MAAM,KAAK,GAAG,wCAAwC,CAAC;AACvD,MAAM,OAAO,GAAG,sEAAsE,CAAC;AAEvF,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACtG,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,IAAI,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1F,CAAC"}
package/dist/api.d.ts ADDED
@@ -0,0 +1,11 @@
1
+ export declare class CloudflareError extends Error {
2
+ readonly status: number;
3
+ readonly explicitFailure: boolean;
4
+ readonly retryAfterSeconds?: number | undefined;
5
+ constructor(status: number, explicitFailure?: boolean, retryAfterSeconds?: number | undefined);
6
+ }
7
+ export declare function cloudflareApi(token: string, request: typeof fetch, timeoutMs?: number): {
8
+ result<T>(path: string, method?: string, body?: unknown): Promise<T>;
9
+ list<T>(path: string, params?: Record<string, string>): Promise<T[]>;
10
+ };
11
+ export type CloudflareApi = ReturnType<typeof cloudflareApi>;
package/dist/api.js ADDED
@@ -0,0 +1,66 @@
1
+ export class CloudflareError extends Error {
2
+ status;
3
+ explicitFailure;
4
+ retryAfterSeconds;
5
+ constructor(status, explicitFailure = false, retryAfterSeconds) {
6
+ super(status ? `Cloudflare API request failed (HTTP ${status}).` : "Cloudflare API is unavailable.");
7
+ this.status = status;
8
+ this.explicitFailure = explicitFailure;
9
+ this.retryAfterSeconds = retryAfterSeconds;
10
+ this.name = "CloudflareError";
11
+ }
12
+ }
13
+ function retryAfter(value) {
14
+ if (!value)
15
+ return undefined;
16
+ const seconds = /^\d+$/.test(value) ? Number(value) : Math.ceil((Date.parse(value) - Date.now()) / 1000);
17
+ return Number.isFinite(seconds) ? Math.max(1, Math.min(seconds, 3600)) : undefined;
18
+ }
19
+ export function cloudflareApi(token, request, timeoutMs = 8_000) {
20
+ async function call(path, method = "GET", body) {
21
+ // Every path is built from validated IDs or URLSearchParams. Never redirect
22
+ // a credential or a payload away from the Cloudflare API.
23
+ if (!path.startsWith("/") || path.startsWith("//"))
24
+ throw new CloudflareError(0);
25
+ let res;
26
+ try {
27
+ res = await request(`https://api.cloudflare.com/client/v4${path}`, {
28
+ method,
29
+ headers: { authorization: `Bearer ${token}`, accept: "application/json", ...(body !== undefined && { "content-type": "application/json" }) },
30
+ ...(body !== undefined && { body: JSON.stringify(body) }),
31
+ // Workers support manual/follow, not error. Manual never forwards credentials to a redirect.
32
+ redirect: "manual",
33
+ signal: AbortSignal.timeout(timeoutMs),
34
+ });
35
+ }
36
+ catch {
37
+ throw new CloudflareError(0);
38
+ }
39
+ const parsed = await res.json().catch(() => null);
40
+ if (!res.ok || parsed?.success !== true || parsed.result === undefined) {
41
+ throw new CloudflareError(res.status, parsed?.success === false && (parsed.result === null || parsed.result === undefined) &&
42
+ Array.isArray(parsed.errors) && parsed.errors.length > 0, retryAfter(res.headers.get("retry-after")));
43
+ }
44
+ return { result: parsed.result, totalPages: parsed.result_info?.total_pages };
45
+ }
46
+ return {
47
+ async result(path, method, body) {
48
+ return (await call(path, method, body)).result;
49
+ },
50
+ async list(path, params = {}) {
51
+ const all = [];
52
+ const size = 50;
53
+ for (let page = 1; page <= 30; page++) {
54
+ const query = new URLSearchParams({ ...params, page: String(page), per_page: String(size) });
55
+ const { result, totalPages } = await call(`${path}?${query}`);
56
+ if (!Array.isArray(result))
57
+ throw new CloudflareError(200);
58
+ all.push(...result);
59
+ if (totalPages !== undefined ? page >= totalPages : result.length < size)
60
+ return all;
61
+ }
62
+ throw new CloudflareError(200); // an incomplete view is unsafe for routing decisions
63
+ },
64
+ };
65
+ }
66
+ //# sourceMappingURL=api.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B;IACA;IACA;IAHX,YACW,MAAc,EACd,kBAAkB,KAAK,EACvB,iBAA0B;QAEnC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,uCAAuC,MAAM,IAAI,CAAC,CAAC,CAAC,gCAAgC,CAAC,CAAC;QAJ5F,WAAM,GAAN,MAAM,CAAQ;QACd,oBAAe,GAAf,eAAe,CAAQ;QACvB,sBAAiB,GAAjB,iBAAiB,CAAS;QAGnC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,SAAS,UAAU,CAAC,KAAoB;IACtC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IACzG,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,OAAqB,EAAE,SAAS,GAAG,KAAK;IACnF,KAAK,UAAU,IAAI,CAAI,IAAY,EAAE,MAAM,GAAG,KAAK,EAAE,IAAc;QACjE,4EAA4E;QAC5E,0DAA0D;QAC1D,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;QACjF,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,OAAO,CAAC,uCAAuC,IAAI,EAAE,EAAE;gBACjE,MAAM;gBACN,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,EAAE;gBAC5I,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzD,6FAA6F;gBAC7F,QAAQ,EAAE,QAAQ;gBAClB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;QAC/B,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAuB,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,MAAM,EAAE,OAAO,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACvE,MAAM,IAAI,eAAe,CACvB,GAAG,CAAC,MAAM,EACV,MAAM,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,CAAC;gBAClF,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAC1D,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAC3C,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC;IAChF,CAAC;IACD,OAAO;QACL,KAAK,CAAC,MAAM,CAAI,IAAY,EAAE,MAAe,EAAE,IAAc;YAC3D,OAAO,CAAC,MAAM,IAAI,CAAI,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;QACpD,CAAC;QACD,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,SAAiC,EAAE;YAC7D,MAAM,GAAG,GAAQ,EAAE,CAAC;YACpB,MAAM,IAAI,GAAG,EAAE,CAAC;YAChB,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC;gBACtC,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC7F,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,IAAI,CAAM,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC;gBACnE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;oBAAE,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;gBAC3D,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;gBACpB,IAAI,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI;oBAAE,OAAO,GAAG,CAAC;YACvF,CAAC;YACD,MAAM,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,qDAAqD;QACvF,CAAC;KACF,CAAC;AACJ,CAAC"}
@@ -0,0 +1 @@
1
+ export declare function readExact(stream: ReadableStream<Uint8Array>, size: number): Promise<Uint8Array<ArrayBuffer> | null>;
package/dist/bytes.js ADDED
@@ -0,0 +1,22 @@
1
+ export async function readExact(stream, size) {
2
+ const bytes = new Uint8Array(size);
3
+ const reader = stream.getReader();
4
+ try {
5
+ let offset = 0;
6
+ for (;;) {
7
+ const part = await reader.read();
8
+ if (part.done)
9
+ return offset === size ? bytes : null;
10
+ if (offset + part.value.byteLength > size) {
11
+ await reader.cancel();
12
+ return null;
13
+ }
14
+ bytes.set(part.value, offset);
15
+ offset += part.value.byteLength;
16
+ }
17
+ }
18
+ finally {
19
+ reader.releaseLock();
20
+ }
21
+ }
22
+ //# sourceMappingURL=bytes.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bytes.js","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAkC,EAAE,IAAY;IAC9E,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,SAAS,CAAC;YACR,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACjC,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;YACrD,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,EAAE,CAAC;gBAC1C,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;gBACtB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC9B,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;QAClC,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}
@@ -0,0 +1,20 @@
1
+ export interface CloudflareConfig {
2
+ accountId: string;
3
+ zoneId: string;
4
+ zone: string;
5
+ secretRef: string;
6
+ controlToken: string;
7
+ sending: {
8
+ domain: string;
9
+ token: string;
10
+ mode?: "onboarded-domain" | "verified-destinations";
11
+ } | null;
12
+ routing: {
13
+ domain: string;
14
+ worker: string;
15
+ ruleNamespace?: string;
16
+ } | null;
17
+ maxMessageBytes: number;
18
+ }
19
+ export declare const cfId: (value: unknown) => value is string;
20
+ export declare function readCloudflareConfig(env: Record<string, string | undefined>): CloudflareConfig;
package/dist/config.js ADDED
@@ -0,0 +1,59 @@
1
+ import { domainName, MAX_MESSAGE_BYTES } from "./address.js";
2
+ export const cfId = (value) => typeof value === "string" && /^[a-f0-9]{32}$/i.test(value);
3
+ export function readCloudflareConfig(env) {
4
+ const required = (key) => {
5
+ const value = env[key]?.trim();
6
+ if (!value)
7
+ throw new Error(`${key} is required.`);
8
+ return value;
9
+ };
10
+ const accountId = required("CF_ACCOUNT_ID"), zoneId = required("CF_ZONE_ID");
11
+ if (!cfId(accountId) || !cfId(zoneId))
12
+ throw new Error("Cloudflare account and zone IDs must be 32 hexadecimal characters.");
13
+ const zone = domainName(required("CF_ZONE_NAME"));
14
+ if (!zone)
15
+ throw new Error("CF_ZONE_NAME must be a DNS name.");
16
+ const inZone = (value, key) => {
17
+ const domain = domainName(value);
18
+ if (!domain || (domain !== zone && !domain.endsWith(`.${zone}`)))
19
+ throw new Error(`${key} must be inside CF_ZONE_NAME.`);
20
+ return domain;
21
+ };
22
+ const token = (key) => {
23
+ const value = required(key);
24
+ if (!/^[A-Za-z0-9_-]{20,256}$/.test(value))
25
+ throw new Error(`${key} is not a Cloudflare API token.`);
26
+ return value;
27
+ };
28
+ const sendDomain = env["CF_SEND_DOMAIN"]?.trim();
29
+ const sendMode = env["CF_SEND_MODE"]?.trim() || undefined;
30
+ if (sendMode !== undefined && sendMode !== "onboarded-domain" && sendMode !== "verified-destinations") {
31
+ throw new Error("CF_SEND_MODE must be onboarded-domain or verified-destinations.");
32
+ }
33
+ const routeDomain = env["CF_ROUTE_DOMAIN"]?.trim();
34
+ if (!sendDomain && !routeDomain)
35
+ throw new Error("Set CF_SEND_DOMAIN and/or CF_ROUTE_DOMAIN.");
36
+ const worker = routeDomain ? required("CF_WORKER_NAME") : "";
37
+ if (routeDomain && !/^[a-z0-9][a-z0-9-]{0,62}$/.test(worker))
38
+ throw new Error("CF_WORKER_NAME is invalid.");
39
+ const ruleNamespace = env.CF_RULE_NAMESPACE?.trim();
40
+ if (ruleNamespace && !/^[a-z0-9][a-z0-9-]{0,31}$/.test(ruleNamespace))
41
+ throw new Error("CF_RULE_NAMESPACE is invalid.");
42
+ const secretRef = env["CF_SECRET_REF"]?.trim() || "secret:cloudflare/primary";
43
+ if (!/^secret:cloudflare\/[a-z0-9][a-z0-9-]{0,63}$/.test(secretRef))
44
+ throw new Error("CF_SECRET_REF must be a Cloudflare credential alias.");
45
+ const maxMessageBytes = Number(env["CF_MAX_SEND_BYTES"]?.trim() || MAX_MESSAGE_BYTES);
46
+ if (!Number.isSafeInteger(maxMessageBytes) || maxMessageBytes < 1024 || maxMessageBytes > MAX_MESSAGE_BYTES) {
47
+ throw new Error("CF_MAX_SEND_BYTES must be between 1 KiB and 25 MiB.");
48
+ }
49
+ return {
50
+ accountId: accountId.toLowerCase(), zoneId: zoneId.toLowerCase(), zone, secretRef, maxMessageBytes,
51
+ controlToken: token("CF_CONTROL_API_TOKEN"),
52
+ sending: sendDomain ? {
53
+ domain: inZone(sendDomain, "CF_SEND_DOMAIN"), token: token("CF_SEND_API_TOKEN"),
54
+ ...(sendMode !== undefined && { mode: sendMode }),
55
+ } : null,
56
+ routing: routeDomain ? { domain: inZone(routeDomain, "CF_ROUTE_DOMAIN"), worker, ...(ruleNamespace && { ruleNamespace }) } : null,
57
+ };
58
+ }
59
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAa7D,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAEpH,MAAM,UAAU,oBAAoB,CAAC,GAAuC;IAC1E,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE;QACvC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC7E,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IAC7H,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC;IAClD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,GAAW,EAAU,EAAE;QACpD,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,+BAA+B,CAAC,CAAC;QACzH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IACF,MAAM,KAAK,GAAG,CAAC,GAAW,EAAU,EAAE;QACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,iCAAiC,CAAC,CAAC;QACrG,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,MAAM,UAAU,GAAG,GAAG,CAAC,gBAAgB,CAAC,EAAE,IAAI,EAAE,CAAC;IACjD,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC1D,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,kBAAkB,IAAI,QAAQ,KAAK,uBAAuB,EAAE,CAAC;QACtG,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,WAAW,GAAG,GAAG,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC;IACnD,IAAI,CAAC,UAAU,IAAI,CAAC,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC/F,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,IAAI,WAAW,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC5G,MAAM,aAAa,GAAG,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACpD,IAAI,aAAa,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC,aAAa,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACxH,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,IAAI,2BAA2B,CAAC;IAC9E,IAAI,CAAC,8CAA8C,CAAC,IAAI,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC7I,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,IAAI,iBAAiB,CAAC,CAAC;IACtF,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,IAAI,eAAe,GAAG,IAAI,IAAI,eAAe,GAAG,iBAAiB,EAAE,CAAC;QAC5G,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe;QAClG,YAAY,EAAE,KAAK,CAAC,sBAAsB,CAAC;QAC3C,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;YACpB,MAAM,EAAE,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,mBAAmB,CAAC;YAC/E,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;SAClD,CAAC,CAAC,CAAC,IAAI;QACR,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,aAAa,IAAI,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;KAClI,CAAC;AACJ,CAAC"}
@@ -0,0 +1,14 @@
1
+ import type { CloudflareApi } from "./api.js";
2
+ import { type CloudflareConfig } from "./config.js";
3
+ import type { DomainVerification } from "./ports.js";
4
+ export declare const ROUTING_MX: readonly ["route1.mx.cloudflare.net", "route2.mx.cloudflare.net", "route3.mx.cloudflare.net"];
5
+ export declare const incumbentMx: (mx: string[]) => string[];
6
+ export declare const routingMxReady: (mx: string[]) => boolean;
7
+ export declare function domainsApi(cfg: CloudflareConfig, api: CloudflareApi): {
8
+ hasZone: () => Promise<boolean>;
9
+ readMx: (domain: string) => Promise<string[]>;
10
+ routingEnabled: () => Promise<boolean>;
11
+ verifiedDestinations: () => Promise<Set<string>>;
12
+ verifySenderDomain: (domain: string) => Promise<DomainVerification>;
13
+ };
14
+ export type DomainsApi = ReturnType<typeof domainsApi>;
@@ -0,0 +1,95 @@
1
+ import { domainName, smtpAddress } from "./address.js";
2
+ import { cfId } from "./config.js";
3
+ export const ROUTING_MX = ["route1.mx.cloudflare.net", "route2.mx.cloudflare.net", "route3.mx.cloudflare.net"];
4
+ const isRoutingMx = (name) => ROUTING_MX.some((mx) => mx === name);
5
+ export const incumbentMx = (mx) => mx.filter((name) => !isRoutingMx(name));
6
+ export const routingMxReady = (mx) => mx.length === ROUTING_MX.length && ROUTING_MX.every((name) => mx.includes(name));
7
+ const lowerDns = (s) => s.toLowerCase().replace(/\.$/, "");
8
+ const txt = (s) => s.replace(/^"(.*)"$/, "$1");
9
+ const recordValue = (r) => r.type === "TXT" ? txt(r.content) : lowerDns(r.content);
10
+ export function domainsApi(cfg, api) {
11
+ const zonePath = `/zones/${cfg.zoneId}`;
12
+ const routingPath = `${zonePath}/email/routing`;
13
+ const sendingPath = `${zonePath}/email/sending/subdomains`;
14
+ async function hasZone() {
15
+ const zone = await api.result(zonePath);
16
+ return zone?.id === cfg.zoneId && domainName(zone.name) === cfg.zone &&
17
+ zone.account?.id === cfg.accountId && zone.status === "active";
18
+ }
19
+ async function dnsRecords(name, type) {
20
+ const records = await api.list(`${zonePath}/dns_records`, { "name.exact": name, type });
21
+ return records.filter((r) => r.type === type && lowerDns(r.name) === name);
22
+ }
23
+ async function readMx(domain) {
24
+ return (await dnsRecords(domain, "MX")).map((r) => lowerDns(r.content)).sort();
25
+ }
26
+ async function routingEnabled() {
27
+ const settings = await api.result(routingPath);
28
+ return settings?.enabled === true;
29
+ }
30
+ async function verifiedDestinations() {
31
+ const rows = await api.list(`/accounts/${cfg.accountId}/email/routing/addresses`, { verified: "true" });
32
+ const addresses = new Set();
33
+ for (const row of rows) {
34
+ const address = typeof row.email === "string" ? smtpAddress(row.email) : null;
35
+ if (address && typeof row.verified === "string" && Number.isFinite(Date.parse(row.verified))) {
36
+ addresses.add(address.address.toLowerCase());
37
+ }
38
+ }
39
+ return addresses;
40
+ }
41
+ async function verifySenderDomain(domain) {
42
+ const empty = { required: [], observed: [] };
43
+ if (cfg.sending?.domain !== domain || !await hasZone())
44
+ return { state: "failed", ...empty };
45
+ if (cfg.sending.mode === "verified-destinations") {
46
+ const [enabled, mx] = await Promise.all([routingEnabled(), readMx(domain)]);
47
+ return { state: enabled && routingMxReady(mx) ? "verified" : "pending", ...empty };
48
+ }
49
+ const rows = await api.result(sendingPath);
50
+ if (!Array.isArray(rows))
51
+ return { state: "failed", ...empty };
52
+ const match = rows.find((r) => domainName(r.name) === domain);
53
+ if (!match || !match.enabled || !cfId(match.tag))
54
+ return { state: "pending", ...empty };
55
+ const records = await api.result(`${sendingPath}/${match.tag}/dns`);
56
+ if (!Array.isArray(records))
57
+ return { state: "failed", ...empty };
58
+ const entries = records.flatMap((r) => {
59
+ if (r.type !== "TXT" && r.type !== "MX" && r.type !== "CNAME")
60
+ return [];
61
+ if (typeof r.name !== "string" || typeof r.content !== "string")
62
+ return [];
63
+ const name = r.name === "@" ? cfg.zone : lowerDns(r.name), value = recordValue(r);
64
+ const purpose = r.type === "MX" ? "return-path"
65
+ : name.includes("._domainkey.") ? "dkim"
66
+ : r.type === "TXT" && name.startsWith("_dmarc.") ? "dmarc"
67
+ : value.startsWith("v=spf1") ? "spf"
68
+ : "ownership";
69
+ return [{ record: { name, value, type: r.type, purpose }, ...(r.priority !== undefined && { priority: r.priority }) }];
70
+ });
71
+ const required = entries.map((e) => e.record);
72
+ // Only query names that belong to the pinned zone. A record from another zone is never proof.
73
+ const observed = (await Promise.all(entries.map(async ({ record, priority }) => {
74
+ if (record.name !== cfg.zone && !record.name.endsWith(`.${cfg.zone}`))
75
+ return null;
76
+ const actual = await dnsRecords(record.name, record.type);
77
+ if (record.purpose === "dmarc") {
78
+ // A valid existing DMARC policy is sufficient; never require weakening
79
+ // p=reject or p=quarantine to a provider's default p=none.
80
+ const policy = actual.map(recordValue).filter((v) => /^v=DMARC1\s*;/i.test(v));
81
+ const value = policy[0];
82
+ return policy.length === 1 && value && /;\s*p=(?:none|quarantine|reject)\s*(?:;|$)/i.test(value)
83
+ ? { ...record, value } : null;
84
+ }
85
+ return actual.some((r) => !r.proxied && recordValue(r) === record.value && (priority == null || r.priority === priority)) ? record : null;
86
+ }))).filter((r) => r !== null);
87
+ const hasRequiredKinds = ["dkim", "spf", "return-path"].every((kind) => required.some((r) => r.purpose === kind));
88
+ // Provider previews may expose message bodies and one-time codes to dashboard users.
89
+ const state = match.preview_enabled !== false ? "failed"
90
+ : hasRequiredKinds && required.length === observed.length ? "verified" : "pending";
91
+ return { state, required, observed };
92
+ }
93
+ return { hasZone, readMx, routingEnabled, verifiedDestinations, verifySenderDomain };
94
+ }
95
+ //# sourceMappingURL=domains.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"domains.js","sourceRoot":"","sources":["../src/domains.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ import { type RelayPage } from "./relay.js";
2
+ import type { InboundDelivery } from "./worker.js";
3
+ export interface RelayDelivery extends InboundDelivery {
4
+ readonly receivedAt: string;
5
+ }
6
+ export declare function createInboxRelayClient(options: {
7
+ origin: string;
8
+ token: string;
9
+ fetch?: typeof fetch;
10
+ }): {
11
+ list(cursor?: string, limit?: number): Promise<RelayPage>;
12
+ get(id: string): Promise<RelayDelivery | null>;
13
+ /** Acknowledge after the local mail store commits the delivery. */
14
+ acknowledge(id: string): Promise<void>;
15
+ };
@@ -0,0 +1,67 @@
1
+ import { MAX_MESSAGE_BYTES, smtpAddress } from "./address.js";
2
+ import { readExact } from "./bytes.js";
3
+ import { DELIVERY_ID_PATTERN, MAX_RELAY_PAGE_SIZE, RELAY_PATH, RELAY_TOKEN_PATTERN, relayCursor } from "./relay.js";
4
+ export function createInboxRelayClient(options) {
5
+ const origin = new URL(options.origin);
6
+ if (origin.protocol !== "https:" || origin.username || origin.password ||
7
+ origin.pathname !== "/" || origin.search || origin.hash || !RELAY_TOKEN_PATTERN.test(options.token)) {
8
+ throw new Error("Inbox relay requires an HTTPS origin and a 32-byte base64url token.");
9
+ }
10
+ const request = options.fetch ?? fetch;
11
+ const call = (path, method) => request(new URL(path, origin), {
12
+ method,
13
+ headers: { authorization: `Bearer ${options.token}` },
14
+ redirect: "error",
15
+ signal: AbortSignal.timeout(20_000),
16
+ });
17
+ const deliveryPath = (id) => {
18
+ if (!DELIVERY_ID_PATTERN.test(id))
19
+ throw new Error("Invalid delivery ID.");
20
+ return `${RELAY_PATH}/${id}`;
21
+ };
22
+ return {
23
+ async list(cursor, limit = 10) {
24
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAX_RELAY_PAGE_SIZE ||
25
+ (cursor !== undefined && relayCursor(cursor) === null))
26
+ throw new Error("Invalid inbox page.");
27
+ const query = new URLSearchParams({ limit: String(limit), ...(cursor !== undefined && { cursor }) });
28
+ const response = await call(`${RELAY_PATH}?${query}`, "GET");
29
+ if (response.status !== 200)
30
+ throw new Error("Inbox relay could not list deliveries.");
31
+ const page = await response.json();
32
+ if (!page || !Array.isArray(page.ids) || page.ids.length > limit ||
33
+ !page.ids.every((id) => typeof id === "string" && DELIVERY_ID_PATTERN.test(id)) ||
34
+ (page.cursor !== undefined && (typeof page.cursor !== "string" || relayCursor(page.cursor) === null))) {
35
+ throw new Error("Inbox relay returned an invalid page.");
36
+ }
37
+ return { ids: page.ids, ...(page.cursor !== undefined && { cursor: page.cursor }) };
38
+ },
39
+ async get(id) {
40
+ const response = await call(deliveryPath(id), "GET");
41
+ if (response.status === 404)
42
+ return null;
43
+ if (response.status !== 200 || response.headers.get("content-type") !== "message/rfc822") {
44
+ throw new Error("Inbox relay could not return a delivery.");
45
+ }
46
+ const from = response.headers.get("x-mail-from") ?? "";
47
+ const to = response.headers.get("x-mail-rcpt") ?? "";
48
+ const receivedAt = response.headers.get("x-mail-received-at") ?? "";
49
+ const size = Number(response.headers.get("x-mail-size"));
50
+ if ((from !== "<>" && !smtpAddress(from)) || !smtpAddress(to) || !Number.isFinite(Date.parse(receivedAt)) ||
51
+ !Number.isSafeInteger(size) || size < 1 || size > MAX_MESSAGE_BYTES || !response.body) {
52
+ throw new Error("Inbox relay returned invalid delivery headers.");
53
+ }
54
+ const raw = await readExact(response.body, size);
55
+ if (!raw)
56
+ throw new Error("Inbox relay returned incomplete message bytes.");
57
+ return { id, envelope: { from, to }, raw, receivedAt };
58
+ },
59
+ /** Acknowledge after the local mail store commits the delivery. */
60
+ async acknowledge(id) {
61
+ const response = await call(deliveryPath(id), "DELETE");
62
+ if (response.status !== 204)
63
+ throw new Error("Inbox relay could not acknowledge a delivery.");
64
+ },
65
+ };
66
+ }
67
+ //# sourceMappingURL=inbox-client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"inbox-client.js","sourceRoot":"","sources":["../src/inbox-client.ts"],"names":[],"mappings":"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"}