Skip to content

Email for professionals and teams

Add support for AWS S3, BackBlaze B2 as storage

Hieu Nguyen (Jack)83ade981e588
diff --git a/.dev.vars.example b/.dev.vars.example
index b9ea97d..8caffb5 100644
--- a/.dev.vars.example
+++ b/.dev.vars.example
@@ -21,3 +21,18 @@ CF_TOKEN=your_api_token_with_zone_email_permissions
# AWS_REGION=us-east-1
# Receiving through Resend or SES needs a public HTTPS address.
# APP_URL=https://mail.example.com
+
+# Optional: store raw mail, attachments, Drive files, avatars and backups in Backblaze B2 instead of R2.
+# Set all four. Create an application key restricted to one bucket (read and write files), and use the
+# S3-compatible endpoint shown on the bucket page.
+# B2_KEY_ID=004...
+# B2_APPLICATION_KEY=K004...
+# B2_BUCKET=mailflare
+# B2_ENDPOINT=s3.us-west-004.backblazeb2.com
+
+# Or AWS S3 (used when B2 is not set). Credentials fall back to AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.
+# The IAM user needs s3:GetObject, PutObject, DeleteObject, AbortMultipartUpload on arn:aws:s3:::BUCKET/*.
+# S3_BUCKET=mailflare
+# S3_REGION=us-east-1
+# S3_ACCESS_KEY_ID=AKIA...
+# S3_SECRET_ACCESS_KEY=your_secret_access_key
diff --git a/CLAUDE.md b/CLAUDE.md
index c07875f..2bad16c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -89,6 +89,10 @@ Schema lives in one file: `src/db/schema/index.ts` (21 tables). Migrations are g
The setup path only ever initializes an empty database — it refuses to touch one that already has tables.
+### Object storage is `env.BUCKET`, from R2, Backblaze B2 or AWS S3
+
+Every blob (raw MIME, attachments, Drive, avatars, branding icon, JMAP uploads, backups) goes through `env.BUCKET` with the R2 API. `withStorage` (`src/lib/storage/index.ts`) swaps `BUCKET` for `B2Bucket` (`b2-bucket.ts`, S3 API signed with the shared SigV4 client; it serves AWS S3 too) when `getObjectStorageConfig` finds all of `B2_*` (Backblaze, wins) or `S3_BUCKET`/`S3_REGION`/credentials (AWS S3, credentials falling back to `AWS_*`); otherwise the R2 binding (or the Node file bucket) is untouched. It is applied in `getEnv()`, at the top of each `worker.ts` handler (which receive the raw env) and in the Node runtime env. `B2Bucket` implements only what the app calls (`get` with range, `head`, `put`, `delete`, multipart); if new code needs another R2 method, add it there. Do not read `cloudflare:workers` env directly for storage. `GET/POST /api/v1/storage` and the `manage_storage` MCP tool (admin scope `storage`) report and test it.
+
### Two runtimes, one code path
The Node build aliases `cloudflare:workers` to `server/runtime/cloudflare-workers.ts`, allowing the shared helper to use its existing `getNodeEnv()` fallback. That alias only applies when `MAILFLARE_RUNTIME=node`; vinext uses the native Workers module. Next outputs to `.next-node` so its generated types do not collide with vinext's `.next/types`.
diff --git a/README.md b/README.md
index d75ffaa..691e0c2 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ Want to support the mailflare? <a target="_blank" href="https://store.paymug.co/
Mailflare runs in your Cloudflare account. By default, Cloudflare Email Routing delivers incoming mail to the app, and Cloudflare's email service sends outgoing mail. Each domain can also receive or send through Resend or Amazon SES. Cloudflare still manages the DNS.
-Your mail stays in your own D1 database, and attachments stay in your own R2 bucket, whichever provider you use. See [Sending and receiving providers](docs/providers.md).
+Your mail stays in your own D1 database, and attachments stay in your own R2, Backblaze B2 or AWS S3 bucket, whichever provider you use. See [Sending and receiving providers](docs/providers.md).
## Cost
@@ -104,7 +104,7 @@ See the [deployment guide](docs/deployment.md) for permissions, manual deploymen
### Self-host with Docker
-Mailflare also runs as one container on any server. It uses SQLite and local files instead of D1 and R2.
+Mailflare also runs as one container on any server. It uses SQLite and local files instead of D1 and R2 (Backblaze B2 can replace the local files).
- **Inbound mail**: a built-in SMTP listener, or a small Cloudflare relay Worker if you want to keep MX on Cloudflare.
- **Outbound mail**: any SMTP relay, Cloudflare Email Sending, Resend, or Amazon SES.
diff --git a/docs/api.md b/docs/api.md
index a6327a5..daff78c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -85,9 +85,11 @@ On a Team license an administrator can add other users as hosts of a booking eve
## Account and mailbox management
-Admin > API keys can also grant the `accounts` and `mailboxes` scopes independently. These routes use `Authorization: Bearer <key>` and require the key owner to retain the admin role. Account management requires a Team license; creating a shared mailbox also requires a Team license. Each key can access only accounts created by its owner and mailboxes owned by those accounts or the admin.
+Admin > API keys can also grant the `accounts`, `mailboxes` and `storage` scopes independently. These routes use `Authorization: Bearer <key>` and require the key owner to retain the admin role. Account management requires a Team license; creating a shared mailbox also requires a Team license. Each key can access only accounts created by its owner and mailboxes owned by those accounts or the admin.
-Admin API keys cannot read or send mail. Enable **Allow MCP access** when creating an admin key to use its selected `domains`, `accounts`, and `mailboxes` permissions through `/mcp`. The `manage_domains`, `manage_accounts`, and `manage_mailboxes` tools expose the corresponding management actions below. Admin MCP keys do not expose mail tools. Use Settings > API keys for mail and mail MCP access.
+The `storage` scope reports and tests object storage: `GET /api/v1/storage` returns `{ storage: { provider: "backblaze" | "s3" | "r2" | "files", configured, bucket, endpoint }, warning }` (credentials are never returned; `warning` explains a half-set `B2_*` configuration), and `POST /api/v1/storage` round-trips a small object and returns `{ ok, error?, latencyMs, storage }` (HTTP 502 on failure). Backblaze B2 (`B2_KEY_ID`, `B2_APPLICATION_KEY`, `B2_BUCKET`, `B2_ENDPOINT`) or AWS S3 (`S3_BUCKET`, `S3_REGION`, credentials) replaces R2 for all stored objects when configured.
+
+Admin API keys cannot read or send mail. Enable **Allow MCP access** when creating an admin key to use its selected `domains`, `accounts`, `mailboxes`, and `storage` permissions through `/mcp`. The `manage_domains`, `manage_accounts`, `manage_mailboxes`, and `manage_storage` (`status`, `test`) tools expose the corresponding management actions below. Admin MCP keys do not expose mail tools. Use Settings > API keys for mail and mail MCP access.
| Scope | Mailflare route | Purpose |
| --- | --- | --- |
@@ -100,6 +102,8 @@ Admin API keys cannot read or send mail. Enable **Allow MCP access** when creati
| `mailboxes` | `GET /api/v1/mailboxes/[id]` | Get a managed mailbox |
| `mailboxes` | `PATCH /api/v1/mailboxes/[id]` | Update mailbox settings |
| `mailboxes` | `DELETE /api/v1/mailboxes/[id]` | Delete a mailbox and its routing rule |
+| `storage` | `GET /api/v1/storage` | Active object storage (R2, Backblaze B2, AWS S3 or local files) |
+| `storage` | `POST /api/v1/storage` | Write, read and delete a test object to verify storage |
### Choose aliases when creating an account
diff --git a/docs/deployment.md b/docs/deployment.md
index c8a1276..767eb20 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -94,13 +94,40 @@ npm run db:migrate:remote
Remote migrations require the target account's `database_id` in your local `wrangler.jsonc`. Do not commit an account-specific database ID to a reusable repository.
+## Object storage (R2, Backblaze B2 or AWS S3)
+
+Raw mail, attachments, Drive files, avatars, branding icons, JMAP uploads and backups all live in one bucket. By default that is the `BUCKET` R2 binding in `wrangler.jsonc`. To use Backblaze B2 instead, set four Worker variables (as secrets, or in `.dev.vars` locally):
+
+| Variable | Example | Purpose |
+| --- | --- | --- |
+| `B2_KEY_ID` | `004abc...` | Application key ID |
+| `B2_APPLICATION_KEY` | `K004...` | Application key secret |
+| `B2_BUCKET` | `mailflare` | Bucket name |
+| `B2_ENDPOINT` | `s3.us-west-004.backblazeb2.com` | S3-compatible endpoint from the bucket page; the region is read from it |
+
+```bash
+npx wrangler secret put B2_KEY_ID
+npx wrangler secret put B2_APPLICATION_KEY
+npx wrangler secret put B2_BUCKET
+npx wrangler secret put B2_ENDPOINT
+```
+
+To use AWS S3 instead, set `S3_BUCKET`, `S3_REGION` and credentials: `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY`, which fall back to `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` so one IAM user can serve SES and storage. The bucket must be private and in the named region; the IAM user needs `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject` and `s3:AbortMultipartUpload` on `arn:aws:s3:::<bucket>/*`. If both are configured, B2 wins.
+
+When all four B2 variables (or the S3 ones) are present that storage replaces R2 everywhere; with any missing, R2 stays in use (a partial setup is reported by `GET /api/v1/storage`). The R2 binding can stay in `wrangler.jsonc` and is simply unused. Use a bucket-restricted application key with read and write access, and keep the bucket private. Notes:
+
+- **Switching does not copy data.** Objects already in R2 are not moved; copy them to the bucket first (for example with `rclone`, keeping the same keys) or old mail bodies, attachments and Drive files will report as missing.
+- **Drive upload parts** are buffered one at a time in the Worker (64 MB each). B2 and S3 require every part but the last to be at least 5 MB, which holds.
+- **Lifecycle.** Set the bucket's lifecycle rule to keep only the last version and to delete unfinished large files after a few days, as R2 would abort incomplete multipart uploads.
+- **Test it** with `POST /api/v1/storage` (admin key with the `storage` scope), or the `manage_storage` MCP tool with `action: "test"`; it writes, reads and deletes a small object.
+
## Database backups
-Mailflare exports its D1 records as JSON and stores the backup files in the configured R2 bucket. A cron trigger in `wrangler.jsonc` runs daily at 02:00 UTC and applies the schedule selected under **Admin → Backups**. Manual backups run the same record export directly from the admin API.
+Mailflare exports its D1 records as JSON and stores the backup files in the configured storage bucket (R2, or Backblaze B2 when configured). A cron trigger in `wrangler.jsonc` runs daily at 02:00 UTC and applies the schedule selected under **Admin → Backups**. Manual backups run the same record export directly from the admin API.
Deploy the complete Worker with `npm run deploy` whenever the cron trigger is added or changed.
-After upgrading an existing installation and confirming the cron trigger is active, the old Workflow can be removed with `npx wrangler workflows delete mailflare-database-backup`. Deleting it also removes its historical Workflow instances; backup files in R2 and rows in Mailflare's backup history are unaffected.
+After upgrading an existing installation and confirming the cron trigger is active, the old Workflow can be removed with `npx wrangler workflows delete mailflare-database-backup`. Deleting it also removes its historical Workflow instances; backup files in storage and rows in Mailflare's backup history are unaffected.
## Email assistant and MCP
diff --git a/docs/providers.md b/docs/providers.md
index bacec68..cdc58ae 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -1,6 +1,6 @@
# Sending and receiving providers
-Mailflare keeps your mail data in your own D1 database and R2 bucket (or SQLite and local files when self-hosted). What carries mail over the wire is a choice you make **per domain**, separately for receiving and for sending:
+Mailflare keeps your mail data in your own D1 database and R2 bucket, Backblaze B2 or AWS S3 (or SQLite and local files when self-hosted). What carries mail over the wire is a choice you make **per domain**, separately for receiving and for sending:
| | Cloudflare | Resend | Amazon SES |
|---|---|---|---|
@@ -82,7 +82,7 @@ You cannot clean up the provider that is currently selected.
## Behavior that differs from Cloudflare
- **Routing rules.** Reject and forward rules need to act on the live SMTP session, which only Cloudflare's email handler can do. For mail received through Resend or SES, a reject rule drops the message and forward rules are not applied. Store and categorize rules, mailbox rules, spam handling and webhooks work as usual.
-- **Attachments.** Cloudflare sends large files as R2 download links to stay under its 5 MiB limit. Resend and SES send attachments directly, within the administrator's outgoing limit (up to 25 MB).
+- **Attachments.** Cloudflare sends large files as download links from your storage bucket to stay under its 5 MiB limit. Resend and SES send attachments directly, within the administrator's outgoing limit (up to 25 MB).
- **Size.** Inbound mail from any provider is capped at 25 MiB and the same attachment limits apply; larger messages are dropped.
## Configuration reference
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index e39bae5..599e01b 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -101,6 +101,8 @@ and the DNS page shows what to set by hand.
| `SMTP_URL` | unset | Outbound relay |
| `SMTP_TLS_REJECT_UNAUTHORIZED` | `true` | Trust self-signed relay certificates when `false` |
| `CF_ACCOUNT_ID`, `CF_TOKEN` | unset | Cloudflare Email Sending, and zone management if the token allows |
+| `B2_KEY_ID`, `B2_APPLICATION_KEY`, `B2_BUCKET`, `B2_ENDPOINT` | unset | Store blobs in Backblaze B2 (all four required) instead of files under `/data/blobs`; see [Deployment](deployment.md#object-storage-r2-or-backblaze-b2) |
+| `S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | unset | Store blobs in AWS S3; the keys fall back to `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. Backblaze wins if both are set |
| `RESEND_API_KEY` | unset | Resend key, used when none is saved in the app |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` | unset | Amazon SES credentials, used when none are saved in the app |
| `INBOUND_WEBHOOK_SECRET` | unset | Enables `/api/inbound` for the relay Worker |
diff --git a/env.d.ts b/env.d.ts
index 2d7a4df..dfe42e2 100644
--- a/env.d.ts
+++ b/env.d.ts
@@ -21,6 +21,22 @@ interface CloudflareEnv {
>;
LOGIN_RATE_LIMIT?: RateLimit;
AGENT_RATE_LIMIT?: RateLimit;
+ /**
+ * Backblaze B2 storage. When all four are set, B2 replaces the R2 binding for raw mail, attachments, Drive,
+ * avatars, branding and backups. B2_ENDPOINT is the S3-compatible host, e.g. s3.us-west-004.backblazeb2.com.
+ */
+ B2_KEY_ID?: string;
+ B2_APPLICATION_KEY?: string;
+ B2_BUCKET?: string;
+ B2_ENDPOINT?: string;
+ /**
+ * AWS S3 storage, used when B2 is not configured. Credentials fall back to AWS_ACCESS_KEY_ID /
+ * AWS_SECRET_ACCESS_KEY (read from the environment), so an existing SES key can serve both.
+ */
+ S3_BUCKET?: string;
+ S3_REGION?: string;
+ S3_ACCESS_KEY_ID?: string;
+ S3_SECRET_ACCESS_KEY?: string;
CF_TOKEN?: string;
CF_API_KEY?: string;
CF_EMAIL?: string;
diff --git a/server/runtime/env.ts b/server/runtime/env.ts
index 98587b6..5770cac 100644
--- a/server/runtime/env.ts
+++ b/server/runtime/env.ts
@@ -1,5 +1,6 @@
import { mkdirSync } from "node:fs";
import { join, resolve } from "node:path";
+import { withStorage } from "@/lib/storage";
import { openFileBucket } from "./file-bucket";
import { openMailer, type Mailer, type MailerConfig } from "./mailer";
import { openAssets, openRateLimiter } from "./misc";
@@ -56,6 +57,14 @@ export function createNodeRuntime(): NodeRuntime {
WORKER_SELF_REFERENCE: undefined as unknown as CloudflareEnv["WORKER_SELF_REFERENCE"],
LOGIN_RATE_LIMIT: openRateLimiter(20, 60),
AGENT_RATE_LIMIT: openRateLimiter(120, 60),
+ B2_KEY_ID: optional("B2_KEY_ID"),
+ B2_APPLICATION_KEY: optional("B2_APPLICATION_KEY"),
+ B2_BUCKET: optional("B2_BUCKET"),
+ B2_ENDPOINT: optional("B2_ENDPOINT"),
+ S3_BUCKET: optional("S3_BUCKET"),
+ S3_REGION: optional("S3_REGION") ?? optional("AWS_REGION"),
+ S3_ACCESS_KEY_ID: optional("S3_ACCESS_KEY_ID") ?? optional("AWS_ACCESS_KEY_ID"),
+ S3_SECRET_ACCESS_KEY: optional("S3_SECRET_ACCESS_KEY") ?? optional("AWS_SECRET_ACCESS_KEY"),
CF_TOKEN: optional("CF_TOKEN"),
CF_API_KEY: optional("CF_API_KEY"),
CF_EMAIL: optional("CF_EMAIL"),
@@ -71,10 +80,11 @@ export function createNodeRuntime(): NodeRuntime {
VAPID_PRIVATE_KEY: optional("VAPID_PRIVATE_KEY"),
VAPID_SUBJECT: optional("VAPID_SUBJECT"),
} as unknown as CloudflareEnv;
- realtime.bindEnv(env);
+ const storageEnv = withStorage(env);
+ realtime.bindEnv(storageEnv);
return {
- env,
+ env: storageEnv,
dataDir,
database: database as unknown as SqliteDatabase,
mailer: mailer as unknown as Mailer,
diff --git a/src/app/(admin)/api-keys/utils.ts b/src/app/(admin)/api-keys/utils.ts
index c8d5354..94b8b52 100644
--- a/src/app/(admin)/api-keys/utils.ts
+++ b/src/app/(admin)/api-keys/utils.ts
@@ -5,6 +5,7 @@ export const ADMIN_KEY_PERMISSIONS: { value: AdminApiKeyScope; labelKey: Transla
{ value: "domains", labelKey: "adminKeys.perm.domains", descriptionKey: "adminKeys.perm.domainsDesc" },
{ value: "accounts", labelKey: "adminKeys.perm.accounts", descriptionKey: "adminKeys.perm.accountsDesc" },
{ value: "mailboxes", labelKey: "adminKeys.perm.mailboxes", descriptionKey: "adminKeys.perm.mailboxesDesc" },
+ { value: "storage", labelKey: "adminKeys.perm.storage", descriptionKey: "adminKeys.perm.storageDesc" },
];
export function parseApiKeyScopes(scopes: string): string[] {
diff --git a/src/app/api/api-keys/route.ts b/src/app/api/api-keys/route.ts
index 3b08788..4864dc7 100644
--- a/src/app/api/api-keys/route.ts
+++ b/src/app/api/api-keys/route.ts
@@ -8,6 +8,7 @@ import { requireUser } from "@/lib/auth/cookies";
import { generateApiKey, parseScopes, scopesToJson } from "@/lib/api-keys";
import { API_KEY_SCOPES } from "@/lib/api/scopes";
import { newId } from "@/lib/ids";
+import { ADMIN_API_KEY_SCOPES } from "@/lib/api/scopes";
import { getMailboxAccessLevel } from "@/lib/mailboxes/access";
import { hasValidSessionMutationOrigin } from "@/lib/auth/origin";
@@ -36,7 +37,7 @@ export async function GET(request: Request) {
.where(eq(apiKeys.userId, user.id));
const keyIds = rows.map((row) => row.id);
const allowed = keyIds.length ? await db.select().from(mcpKeyMailboxes).where(inArray(mcpKeyMailboxes.keyId, keyIds)) : [];
- return NextResponse.json({ apiKeys: rows.filter((row) => !parseScopes(row.scopes).some((scope) => ["domains", "accounts", "mailboxes"].includes(scope))).map((row) => ({ ...row, mailboxIds: allowed.filter((item) => item.keyId === row.id).map((item) => item.mailboxId) })) });
+ return NextResponse.json({ apiKeys: rows.filter((row) => !parseScopes(row.scopes).some((scope) => (ADMIN_API_KEY_SCOPES as readonly string[]).includes(scope))).map((row) => ({ ...row, mailboxIds: allowed.filter((item) => item.keyId === row.id).map((item) => item.mailboxId) })) });
}
export async function POST(request: Request) {
@@ -77,7 +78,7 @@ export async function DELETE(request: Request) {
const db = getDb(env);
const [key] = await db.select({ id: apiKeys.id, scopes: apiKeys.scopes }).from(apiKeys).where(and(eq(apiKeys.id, id), eq(apiKeys.userId, user.id))).limit(1);
if (!key) return NextResponse.json({ error: "Key not found" }, { status: 404 });
- if (parseScopes(key.scopes).some((scope) => ["domains", "accounts", "mailboxes"].includes(scope))) return NextResponse.json({ error: "Manage this key in Admin API keys" }, { status: 403 });
+ if (parseScopes(key.scopes).some((scope) => (ADMIN_API_KEY_SCOPES as readonly string[]).includes(scope))) return NextResponse.json({ error: "Manage this key in Admin API keys" }, { status: 403 });
await db.update(agentSendApprovals).set({ status: "cancelled" }).where(and(eq(agentSendApprovals.requestKeyId, id), eq(agentSendApprovals.status, "pending")));
await db.delete(apiKeys).where(and(eq(apiKeys.id, id), eq(apiKeys.userId, user.id)));
return NextResponse.json({ ok: true });
diff --git a/src/app/api/v1/storage/route.ts b/src/app/api/v1/storage/route.ts
new file mode 100644
index 0000000..19b64e5
--- /dev/null
+++ b/src/app/api/v1/storage/route.ts
@@ -0,0 +1,22 @@
+import { NextResponse } from "next/server";
+import { getEnv } from "@/lib/cloudflare";
+import { authenticateAdminApiKey } from "@/lib/api/admin-auth";
+import { describeB2Problem, getStorageStatus } from "@/lib/storage/b2-config";
+import { testStorage } from "@/lib/storage/health";
+
+/** Which object storage is active. Credentials are never returned. */
+export async function GET(request: Request) {
+ const env = getEnv();
+ const auth = await authenticateAdminApiKey(env, request, "storage");
+ if (!auth) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ return NextResponse.json({ storage: getStorageStatus(env), warning: describeB2Problem(env) });
+}
+
+/** Round-trips a small object through the active storage. */
+export async function POST(request: Request) {
+ const env = getEnv();
+ const auth = await authenticateAdminApiKey(env, request, "storage");
+ if (!auth) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+ const result = await testStorage(env);
+ return NextResponse.json({ storage: getStorageStatus(env), ...result }, { status: result.ok ? 200 : 502 });
+}
diff --git a/src/lib/api/scopes-types.d.ts b/src/lib/api/scopes-types.d.ts
index 9fd0d7b..4dafc64 100644
--- a/src/lib/api/scopes-types.d.ts
+++ b/src/lib/api/scopes-types.d.ts
@@ -1 +1 @@
-export type AdminApiKeyScope = "domains" | "accounts" | "mailboxes";
+export type AdminApiKeyScope = "domains" | "accounts" | "mailboxes" | "storage";
diff --git a/src/lib/api/scopes.ts b/src/lib/api/scopes.ts
index b712823..0a55ad4 100644
--- a/src/lib/api/scopes.ts
+++ b/src/lib/api/scopes.ts
@@ -7,4 +7,4 @@ export const API_KEY_SCOPES = ["send", "read", "jmap", "calendar:read", "calenda
export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
-export const ADMIN_API_KEY_SCOPES = ["domains", "accounts", "mailboxes"] as const;
+export const ADMIN_API_KEY_SCOPES = ["domains", "accounts", "mailboxes", "storage"] as const;
diff --git a/src/lib/cloudflare.ts b/src/lib/cloudflare.ts
index 3f1ce53..140aa5a 100644
--- a/src/lib/cloudflare.ts
+++ b/src/lib/cloudflare.ts
@@ -1,8 +1,9 @@
import { env } from "cloudflare:workers";
import { getNodeEnv } from "@/lib/runtime";
+import { withStorage } from "@/lib/storage";
export function getEnv(): CloudflareEnv {
- return getNodeEnv() ?? (env as CloudflareEnv);
+ return withStorage(getNodeEnv() ?? (env as CloudflareEnv));
}
export async function getEnvAsync(): Promise<CloudflareEnv> {
diff --git a/src/lib/drive/utils.ts b/src/lib/drive/utils.ts
index fd018b9..13a15b4 100644
--- a/src/lib/drive/utils.ts
+++ b/src/lib/drive/utils.ts
@@ -1,12 +1,13 @@
import type { DriveCrumb, DriveRole, DriveRow } from "./types";
/**
- * Files upload in parts straight into an R2 multipart upload, so no file is ever buffered in the Worker. A part must stay
+ * Files upload in parts into a multipart upload (R2, or Backblaze B2 when configured), so no whole file is ever buffered in the Worker;
+ * with B2 one part at a time is held in memory to be signed, so keep this well under the 128 MB Worker limit. A part must stay
* under the 100 MB request limit of Cloudflare's Free and Pro plans, and R2 allows 10,000 parts per object, which caps a
* file at about 640 GB. Lowering the part size shrinks that cap; raising it needs a plan with larger request bodies.
*/
export const DRIVE_PART_BYTES = 64 * 1024 * 1024;
-/** How long an interrupted upload can be resumed. R2 should be set to abort incomplete multipart uploads after about as long. */
+/** How long an interrupted upload can be resumed. The bucket should be set to abort incomplete multipart uploads after about as long. */
export const DRIVE_UPLOAD_RESUME_MS = 3 * 24 * 60 * 60 * 1000;
export const DRIVE_MAX_PARTS = 10_000;
export const DRIVE_MAX_FILE_BYTES = DRIVE_PART_BYTES * DRIVE_MAX_PARTS;
diff --git a/src/lib/email/cloud-attachment-utils.ts b/src/lib/email/cloud-attachment-utils.ts
index d4fbf07..12d9b65 100644
--- a/src/lib/email/cloud-attachment-utils.ts
+++ b/src/lib/email/cloud-attachment-utils.ts
@@ -26,7 +26,7 @@ export async function prepareCloudflareAttachments(
estimatedSize += encodedSize;
continue;
}
- if (!attachment.storageId) throw new Error("Large attachment was not stored in R2");
+ if (!attachment.storageId) throw new Error("Large attachment was not stored in object storage");
linked.push({ filename: attachment.filename, size, url: await getOrCreateSharedAttachmentUrl(env, attachment.storageId, message.publicOrigin) });
}
if (!linked.length) {
diff --git a/src/lib/i18n/en.json b/src/lib/i18n/en.json
index 63d897e..dab37f4 100644
--- a/src/lib/i18n/en.json
+++ b/src/lib/i18n/en.json
@@ -183,8 +183,8 @@
"compose.sent": "Message sent",
"compose.carriedOver": "Carried over from the forwarded message",
"compose.removeAttachment": "Remove attachment",
- "compose.cloudWarning.will": "Cloudflare limits general email messages to 5 MiB including encoding. Files over 3 MB here will be sent as 30-day R2 download links.",
- "compose.cloudWarning.may": "Cloudflare limits general email messages to 5 MiB including encoding. Files over 3 MB or files that exceed the message budget may be sent as 30-day R2 download links.",
+ "compose.cloudWarning.will": "Cloudflare limits general email messages to 5 MiB including encoding. Files over 3 MB here will be sent as 30-day download links.",
+ "compose.cloudWarning.may": "Cloudflare limits general email messages to 5 MiB including encoding. Files over 3 MB or files that exceed the message budget may be sent as 30-day download links.",
"compose.dialogLabel": "Compose message",
"compose.dropFiles": "Drop files to attach",
"compose.title.loading": "Loading draft",
@@ -212,7 +212,7 @@
"compose.schedule": "Schedule",
"compose.reviewSend": "Review send",
"compose.send": "Send",
- "compose.attachTooltip": "Attach files (up to {max} MB total). Files over 3 MB are sent as 30-day R2 download links.",
+ "compose.attachTooltip": "Attach files (up to {max} MB total). Files over 3 MB are sent as 30-day download links.",
"compose.attachFiles": "Attach files",
"compose.deleteDraft": "Delete draft",
"editor.bold": "Bold (⌘B)",
@@ -875,7 +875,7 @@
"general.maxAttachments": "Maximum attachments per email (MB)",
"general.appliesTo": "Applies to each file and all files combined. Maximum: 25 MB; up to 10 files.",
"general.cloudflareLimit": "Cloudflare Email Sending limits the complete email, including attachments and encoding, to 5 MiB for general recipients. The 25 MiB exception applies only to verified destination addresses.",
- "general.largeFiles": "Files over 3 MB, and smaller files that would make the email exceed Cloudflare’s 5 MiB limit, are stored in R2 and sent as download links. Links expire after 30 days. Anyone with a link can download the file until it expires. Set APP_URL to your public HTTPS address when sending through API or background workflows.",
+ "general.largeFiles": "Files over 3 MB, and smaller files that would make the email exceed Cloudflare’s 5 MiB limit, are stored in your storage bucket and sent as download links. Links expire after 30 days. Anyone with a link can download the file until it expires. Set APP_URL to your public HTTPS address when sending through API or background workflows.",
"general.drive": "Drive storage",
"general.driveUnlimited": "Unlimited storage",
"general.driveLimit": "Storage limit per user (GB)",
@@ -1305,7 +1305,7 @@
"backups.status.failed": "failed",
"backups.restoreConfirm": "Restore this backup? This replaces all current database records and may sign you out.",
"backups.title": "Database Backups",
- "backups.description": "Export database records and store them in the configured R2 bucket.",
+ "backups.description": "Export database records and store them in the configured storage bucket.",
"backups.starting": "Starting...",
"backups.backUp": "Back up",
"backups.actions": "Backup actions",
@@ -1353,6 +1353,8 @@
"adminKeys.perm.accountsDesc": "Create and update accounts. Requires a Pro or Team license.",
"adminKeys.perm.mailboxes": "Manage mailboxes",
"adminKeys.perm.mailboxesDesc": "Create, update, and remove mailboxes.",
+ "adminKeys.perm.storage": "Check storage",
+ "adminKeys.perm.storageDesc": "See which object storage is in use (R2, Backblaze B2, AWS S3 or local files) and test that it works.",
"adminKeys.namePlaceholder": "Production app",
"adminKeys.allowMcpHint": "Use this key with an MCP client to manage only the admin areas selected below. It cannot read or send mail.",
"adminKeys.createKey": "Create key",
diff --git a/src/lib/mcp/admin-tools.ts b/src/lib/mcp/admin-tools.ts
index 63b3211..d7ab050 100644
--- a/src/lib/mcp/admin-tools.ts
+++ b/src/lib/mcp/admin-tools.ts
@@ -8,6 +8,7 @@ import { GET as listAccounts, POST as createAccount } from "@/app/api/v1/account
import { GET as getAccount, PATCH as updateAccount } from "@/app/api/v1/accounts/[id]/route";
import { GET as listMailboxes, POST as createMailbox } from "@/app/api/v1/mailboxes/route";
import { GET as getMailbox, PATCH as updateMailbox, DELETE as deleteMailbox } from "@/app/api/v1/mailboxes/[id]/route";
+import { GET as getStorage, POST as testStorage } from "@/app/api/v1/storage/route";
import type { McpPrincipal } from "./types";
const adminInput = z.object({
@@ -90,4 +91,18 @@ export function registerAdminMcpTools(server: McpServer, principal: McpPrincipal
}
} catch (error) { return result({ error: error instanceof Error ? error.message : "Mailbox action failed" }, true); }
});
+
+ if (principal.scopes.includes("storage")) server.registerTool("manage_storage", {
+ description: "Show which object storage holds raw mail, attachments, Drive files, avatars and backups, and test it. Actions: status (provider, bucket, endpoint), test (writes, reads and deletes a small object to prove the credentials work). Backblaze B2 (B2_* variables) or AWS S3 (S3_* variables) replaces R2 when configured in the Worker environment; credentials are never returned.",
+ inputSchema: adminInput,
+ }, async ({ action }) => {
+ if (!principal.scopes.includes("storage")) return result({ error: "Permission denied" }, true);
+ try {
+ switch (action) {
+ case "status": return responseResult(await getStorage(adminRequest(baseUrl, "/api/v1/storage", authorization)));
+ case "test": return responseResult(await testStorage(adminRequest(baseUrl, "/api/v1/storage", authorization, "POST", {})));
+ default: return result({ error: "Unknown action" }, true);
+ }
+ } catch (error) { return result({ error: error instanceof Error ? error.message : "Storage action failed" }, true); }
+ });
}
diff --git a/src/lib/storage/b2-bucket.ts b/src/lib/storage/b2-bucket.ts
new file mode 100644
index 0000000..1de4533
--- /dev/null
+++ b/src/lib/storage/b2-bucket.ts
@@ -0,0 +1,177 @@
+import { awsRequest, AwsError } from "@/lib/aws/client";
+import { xmlTag } from "@/lib/aws/xml";
+import type { AwsConfig } from "@/lib/aws/aws-types";
+import type { B2Config, B2HttpMetadata } from "@/lib/storage/b2-types";
+
+/**
+ * The slice of the R2 bucket API the app uses (get with a range, put, head, delete, multipart uploads),
+ * served by Backblaze B2 over its S3-compatible API. Signing reuses the SigV4 client, so it runs on Workers and Node.
+ */
+type PutValue = ArrayBuffer | ArrayBufferView | string | ReadableStream | Blob | null;
+type PutOptions = { httpMetadata?: B2HttpMetadata | Headers; customMetadata?: Record<string, string> };
+
+const META_PREFIX = "x-amz-meta-";
+
+const encodePath = (key: string) => `/${key.split("/").map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join("/")}`;
+const escapeXml = (value: string) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+async function toBuffer(value: PutValue): Promise<ArrayBuffer> {
+ if (value === null) return new ArrayBuffer(0);
+ if (typeof value === "string") return new TextEncoder().encode(value).buffer as ArrayBuffer;
+ if (value instanceof ArrayBuffer) return value;
+ if (ArrayBuffer.isView(value)) return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) as ArrayBuffer;
+ if (value instanceof Blob) return value.arrayBuffer();
+ return new Response(value).arrayBuffer();
+}
+
+function readMetadata(headers: Headers): { httpMetadata: B2HttpMetadata; customMetadata: Record<string, string> } {
+ const customMetadata: Record<string, string> = {};
+ headers.forEach((value, name) => { if (name.startsWith(META_PREFIX)) customMetadata[name.slice(META_PREFIX.length)] = value; });
+ return {
+ httpMetadata: {
+ contentType: headers.get("content-type") ?? undefined,
+ contentDisposition: headers.get("content-disposition") ?? undefined,
+ cacheControl: headers.get("cache-control") ?? undefined,
+ },
+ customMetadata,
+ };
+}
+
+function objectSize(headers: Headers): number {
+ const total = /\/(\d+)$/.exec(headers.get("content-range") ?? "")?.[1];
+ return Number(total ?? headers.get("content-length") ?? 0);
+}
+
+export class B2Object {
+ readonly size: number;
+ readonly etag: string;
+ readonly uploaded: Date;
+ readonly httpMetadata: B2HttpMetadata;
+ readonly customMetadata: Record<string, string>;
+
+ constructor(readonly key: string, private readonly response: Response, size?: number) {
+ const headers = response.headers;
+ this.size = size ?? objectSize(headers);
+ this.etag = (headers.get("etag") ?? "").replace(/"/g, "");
+ this.uploaded = new Date(headers.get("last-modified") ?? Date.now());
+ const meta = readMetadata(headers);
+ this.httpMetadata = meta.httpMetadata;
+ this.customMetadata = meta.customMetadata;
+ }
+
+ get httpEtag() { return `"${this.etag}"`; }
+ get version() { return this.etag; }
+ get body(): ReadableStream<Uint8Array> { return (this.response.body ?? new Blob([]).stream()) as ReadableStream<Uint8Array>; }
+ get bodyUsed() { return this.response.bodyUsed; }
+ arrayBuffer() { return this.response.arrayBuffer(); }
+ text() { return this.response.text(); }
+ json<T>() { return this.response.json() as Promise<T>; }
+ blob() { return this.response.blob(); }
+
+ writeHttpMetadata(headers: Headers) {
+ if (this.httpMetadata.contentType) headers.set("Content-Type", this.httpMetadata.contentType);
+ if (this.httpMetadata.contentDisposition) headers.set("Content-Disposition", this.httpMetadata.contentDisposition);
+ if (this.httpMetadata.cacheControl) headers.set("Cache-Control", this.httpMetadata.cacheControl);
+ }
+}
+
+export class B2Bucket {
+ private readonly credentials: AwsConfig;
+ private readonly host: string;
+
+ constructor(private readonly config: B2Config) {
+ this.credentials = { accessKeyId: config.keyId, secretAccessKey: config.applicationKey, region: config.region };
+ this.host = `${config.bucket}.${config.endpoint}`;
+ }
+
+ private request(key: string | null, init: { method?: string; query?: Record<string, string>; body?: string | ArrayBuffer; headers?: Record<string, string> } = {}) {
+ return awsRequest({ config: this.credentials, service: "s3", host: this.host, path: key === null ? "/" : encodePath(key), ...init });
+ }
+
+ private metadataHeaders(options?: PutOptions): Record<string, string> {
+ const headers: Record<string, string> = {};
+ const meta = options?.httpMetadata;
+ const http: B2HttpMetadata = meta instanceof Headers
+ ? { contentType: meta.get("content-type") ?? undefined, contentDisposition: meta.get("content-disposition") ?? undefined, cacheControl: meta.get("cache-control") ?? undefined }
+ : meta ?? {};
+ if (http.contentType) headers["Content-Type"] = http.contentType;
+ if (http.contentDisposition) headers["Content-Disposition"] = http.contentDisposition;
+ if (http.cacheControl) headers["Cache-Control"] = http.cacheControl;
+ for (const [name, value] of Object.entries(options?.customMetadata ?? {})) headers[`${META_PREFIX}${name.toLowerCase()}`] = value;
+ return headers;
+ }
+
+ async get(key: string, options?: { range?: { offset?: number; length?: number; suffix?: number } }): Promise<B2Object | null> {
+ const range = options?.range;
+ const headers: Record<string, string> = {};
+ if (range) {
+ if (range.suffix != null) headers.Range = `bytes=-${range.suffix}`;
+ else {
+ const start = range.offset ?? 0;
+ headers.Range = range.length != null ? `bytes=${start}-${start + range.length - 1}` : `bytes=${start}-`;
+ }
+ }
+ try { return new B2Object(key, await this.request(key, { headers })); }
+ catch (error) { if (error instanceof AwsError && (error.status === 404 || error.code === "NoSuchKey")) return null; throw error; }
+ }
+
+ async head(key: string): Promise<B2Object | null> {
+ try { return new B2Object(key, await this.request(key, { method: "HEAD" })); }
+ catch (error) { if (error instanceof AwsError && error.status === 404) return null; throw error; }
+ }
+
+ async put(key: string, value: PutValue, options?: PutOptions): Promise<B2Object> {
+ const body = await toBuffer(value);
+ const response = await this.request(key, { method: "PUT", body, headers: this.metadataHeaders(options) });
+ return new B2Object(key, new Response(null, { headers: response.headers }), body.byteLength);
+ }
+
+ async delete(keys: string | string[]): Promise<void> {
+ const list = Array.isArray(keys) ? keys : [keys];
+ for (let index = 0; index < list.length; index += 10) {
+ await Promise.all(list.slice(index, index + 10).map(async (key) => {
+ try { await this.request(key, { method: "DELETE" }); }
+ catch (error) { if (!(error instanceof AwsError && error.status === 404)) throw error; }
+ }));
+ }
+ }
+
+ async list(): Promise<never> {
+ throw new Error("B2Bucket.list is not implemented");
+ }
+
+ async createMultipartUpload(key: string, options?: { httpMetadata?: B2HttpMetadata; customMetadata?: Record<string, string> }) {
+ const response = await this.request(key, { method: "POST", query: { uploads: "" }, headers: this.metadataHeaders(options) });
+ const uploadId = xmlTag(await response.text(), "UploadId");
+ if (!uploadId) throw new Error("Backblaze did not return an upload id");
+ return this.resumeMultipartUpload(key, uploadId);
+ }
+
+ resumeMultipartUpload(key: string, uploadId: string) {
+ return {
+ key,
+ uploadId,
+ uploadPart: async (partNumber: number, value: PutValue) => {
+ if (!Number.isInteger(partNumber) || partNumber < 1) throw new Error("Invalid part number");
+ const response = await this.request(key, { method: "PUT", query: { partNumber: String(partNumber), uploadId }, body: await toBuffer(value) });
+ return { partNumber, etag: (response.headers.get("etag") ?? "").replace(/"/g, "") };
+ },
+ abort: async () => { await this.request(key, { method: "DELETE", query: { uploadId } }); },
+ complete: async (parts: { partNumber: number; etag: string }[]) => {
+ const body = `<CompleteMultipartUpload>${[...parts].sort((a, b) => a.partNumber - b.partNumber)
+ .map((part) => `<Part><PartNumber>${part.partNumber}</PartNumber><ETag>"${escapeXml(part.etag)}"</ETag></Part>`).join("")}</CompleteMultipartUpload>`;
+ const response = await this.request(key, { method: "POST", query: { uploadId }, body, headers: { "Content-Type": "application/xml" } });
+ // A 200 can still carry an <Error> document.
+ const text = await response.text();
+ if (/<Error>/.test(text)) throw new Error(xmlTag(text, "Message") ?? "Multipart upload failed");
+ const head = await this.head(key);
+ if (!head) throw new Error("Uploaded object not found");
+ return head;
+ },
+ };
+ }
+}
+
+export function openB2Bucket(config: B2Config): R2Bucket {
+ return new B2Bucket(config) as unknown as R2Bucket;
+}
diff --git a/src/lib/storage/b2-config.ts b/src/lib/storage/b2-config.ts
new file mode 100644
index 0000000..89a3b17
--- /dev/null
+++ b/src/lib/storage/b2-config.ts
@@ -0,0 +1,71 @@
+import type { B2Config, StorageStatus } from "@/lib/storage/b2-types";
+
+type B2Env = Partial<Pick<CloudflareEnv, "B2_KEY_ID" | "B2_APPLICATION_KEY" | "B2_BUCKET" | "B2_ENDPOINT" | "S3_BUCKET" | "S3_REGION" | "S3_ACCESS_KEY_ID" | "S3_SECRET_ACCESS_KEY" | "MAILFLARE_RUNTIME">> &
+ Partial<Record<"AWS_ACCESS_KEY_ID" | "AWS_SECRET_ACCESS_KEY" | "AWS_REGION" | "AWS_DEFAULT_REGION", string>>;
+
+const ENDPOINT_PATTERN = /^s3\.([a-z0-9-]+)\.backblazeb2\.com$/;
+
+/** Accepts `s3.us-west-004.backblazeb2.com` with or without a scheme or trailing slash. */
+export function normalizeB2Endpoint(value: string): string {
+ return value.trim().replace(/^https?:\/\//i, "").replace(/\/+$/, "").toLowerCase();
+}
+
+export function b2RegionFromEndpoint(endpoint: string): string | null {
+ return ENDPOINT_PATTERN.exec(endpoint)?.[1] ?? null;
+}
+
+/**
+ * Backblaze B2 settings from the Worker environment (B2_KEY_ID, B2_APPLICATION_KEY, B2_BUCKET, B2_ENDPOINT).
+ * Returns null when any is missing, which leaves the R2 binding (or local files) in use.
+ */
+export function getB2Config(env: B2Env): B2Config | null {
+ const keyId = env.B2_KEY_ID?.trim();
+ const applicationKey = env.B2_APPLICATION_KEY?.trim();
+ const bucket = env.B2_BUCKET?.trim();
+ const endpoint = env.B2_ENDPOINT ? normalizeB2Endpoint(env.B2_ENDPOINT) : "";
+ if (!keyId || !applicationKey || !bucket || !endpoint) return null;
+ const region = b2RegionFromEndpoint(endpoint);
+ if (!region) return null;
+ return { keyId, applicationKey, bucket, endpoint, region };
+}
+
+const S3_REGION_PATTERN = /^[a-z]{2}(-gov|-iso[a-z]?)?-[a-z]+-\d$/;
+
+/**
+ * AWS S3 settings: S3_BUCKET and S3_REGION, with S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY falling back to the
+ * AWS_* variables the SES integration already uses. Backblaze wins when both are configured.
+ */
+export function getS3Config(env: B2Env): B2Config | null {
+ const bucket = env.S3_BUCKET?.trim();
+ const region = (env.S3_REGION ?? env.AWS_REGION ?? env.AWS_DEFAULT_REGION)?.trim();
+ const keyId = (env.S3_ACCESS_KEY_ID ?? env.AWS_ACCESS_KEY_ID)?.trim();
+ const applicationKey = (env.S3_SECRET_ACCESS_KEY ?? env.AWS_SECRET_ACCESS_KEY)?.trim();
+ if (!bucket || !region || !keyId || !applicationKey || !S3_REGION_PATTERN.test(region)) return null;
+ return { keyId, applicationKey, bucket, region, endpoint: `s3.${region}.amazonaws.com` };
+}
+
+/** The S3-compatible bucket in use, if any. */
+export function getObjectStorageConfig(env: B2Env): (B2Config & { provider: "backblaze" | "s3" }) | null {
+ const b2 = getB2Config(env);
+ if (b2) return { ...b2, provider: "backblaze" };
+ const s3 = getS3Config(env);
+ return s3 ? { ...s3, provider: "s3" } : null;
+}
+
+export function getStorageStatus(env: B2Env): StorageStatus {
+ const configured = getObjectStorageConfig(env);
+ if (configured) return { provider: configured.provider, configured: true, bucket: configured.bucket, endpoint: configured.endpoint };
+ return { provider: env.MAILFLARE_RUNTIME === "node" ? "files" : "r2", configured: true, bucket: null, endpoint: null };
+}
+
+/** Names the variables that are set without exposing values, so a half-finished setup can be diagnosed. */
+export function describeB2Problem(env: B2Env): string | null {
+ if (!getB2Config(env) && !(env.B2_KEY_ID || env.B2_APPLICATION_KEY || env.B2_BUCKET || env.B2_ENDPOINT) && env.S3_BUCKET && !getS3Config(env)) {
+ return "AWS S3 needs S3_BUCKET, S3_REGION and credentials (S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY, or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY).";
+ }
+ const present = [env.B2_KEY_ID, env.B2_APPLICATION_KEY, env.B2_BUCKET, env.B2_ENDPOINT].filter((value) => value?.trim()).length;
+ if (present === 0 || getB2Config(env)) return null;
+ if (getS3Config(env)) return null;
+ if (present < 4) return "Backblaze B2 needs B2_KEY_ID, B2_APPLICATION_KEY, B2_BUCKET and B2_ENDPOINT together.";
+ return "B2_ENDPOINT must look like s3.us-west-004.backblazeb2.com.";
+}
diff --git a/src/lib/storage/b2-types.d.ts b/src/lib/storage/b2-types.d.ts
new file mode 100644
index 0000000..eff7ae2
--- /dev/null
+++ b/src/lib/storage/b2-types.d.ts
@@ -0,0 +1,19 @@
+/** Connection to an S3-compatible bucket: Backblaze B2 or AWS S3. The fields keep their B2 names. */
+export type B2Config = {
+ keyId: string;
+ applicationKey: string;
+ bucket: string;
+ /** S3-compatible endpoint host without scheme, e.g. s3.us-west-004.backblazeb2.com. */
+ endpoint: string;
+ /** Signing region, the second label of the endpoint (us-west-004). */
+ region: string;
+};
+
+export type StorageStatus = {
+ provider: "backblaze" | "s3" | "r2" | "files";
+ configured: boolean;
+ bucket: string | null;
+ endpoint: string | null;
+};
+
+export type B2HttpMetadata = { contentType?: string; contentDisposition?: string; cacheControl?: string };
diff --git a/src/lib/storage/health.ts b/src/lib/storage/health.ts
new file mode 100644
index 0000000..ee50643
--- /dev/null
+++ b/src/lib/storage/health.ts
@@ -0,0 +1,21 @@
+import { newId } from "@/lib/ids";
+
+export type StorageTestResult = { ok: boolean; error?: string; latencyMs: number };
+
+/** Writes, reads back and deletes a small object, so a wrong key, bucket or endpoint shows up before real mail does. */
+export async function testStorage(env: CloudflareEnv): Promise<StorageTestResult> {
+ const started = Date.now();
+ const key = `healthcheck/${newId("chk")}`;
+ const payload = `mailflare ${new Date().toISOString()}`;
+ try {
+ await env.BUCKET.put(key, payload, { httpMetadata: { contentType: "text/plain" } });
+ const object = await env.BUCKET.get(key);
+ const text = object ? await object.text() : null;
+ await env.BUCKET.delete(key);
+ if (text !== payload) return { ok: false, error: "Object read back did not match what was written", latencyMs: Date.now() - started };
+ return { ok: true, latencyMs: Date.now() - started };
+ } catch (error) {
+ await env.BUCKET.delete(key).catch(() => undefined);
+ return { ok: false, error: error instanceof Error ? error.message : "Storage test failed", latencyMs: Date.now() - started };
+ }
+}
diff --git a/src/lib/storage/index.ts b/src/lib/storage/index.ts
new file mode 100644
index 0000000..5d2dc58
--- /dev/null
+++ b/src/lib/storage/index.ts
@@ -0,0 +1,23 @@
+import { getObjectStorageConfig } from "@/lib/storage/b2-config";
+import { openB2Bucket } from "@/lib/storage/b2-bucket";
+
+const wrapped = new WeakMap<object, CloudflareEnv>();
+const proxies = new WeakSet<object>();
+
+/**
+ * Returns env with BUCKET served by Backblaze B2 (B2_*) or AWS S3 (S3_*) when configured; otherwise env unchanged
+ * (the R2 binding on Workers, the file bucket when self-hosted). Every caller reads `env.BUCKET`, so this one
+ * place decides where objects live. Proxied rather than spread because Worker bindings are not enumerable.
+ */
+export function withStorage(env: CloudflareEnv): CloudflareEnv {
+ if (proxies.has(env)) return env;
+ const cached = wrapped.get(env);
+ if (cached) return cached;
+ const config = getObjectStorageConfig(env);
+ if (!config) return env;
+ const bucket = openB2Bucket(config);
+ const proxy = new Proxy(env, { get: (target, property) => (property === "BUCKET" ? bucket : Reflect.get(target, property)) });
+ wrapped.set(env, proxy);
+ proxies.add(proxy);
+ return proxy;
+}
diff --git a/tests/b2-bucket.test.mjs b/tests/b2-bucket.test.mjs
new file mode 100644
index 0000000..5b1dfc0
--- /dev/null
+++ b/tests/b2-bucket.test.mjs
@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test, { after } from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { build } from "esbuild";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = mkdtempSync(join(tmpdir(), "mailflare-b2-"));
+after(() => rmSync(outDir, { recursive: true, force: true }));
+
+async function bundle(entry, outfile) {
+ await build({ entryPoints: [join(root, entry)], outfile: join(outDir, outfile), bundle: true, platform: "node", format: "esm", target: "node22", logLevel: "silent", alias: { "@": join(root, "src") } });
+ return import(pathToFileURL(join(outDir, outfile)).href);
+}
+
+const { getB2Config, getS3Config, describeB2Problem } = await bundle("src/lib/storage/b2-config.ts", "config.mjs");
+const { B2Bucket } = await bundle("src/lib/storage/b2-bucket.ts", "bucket.mjs");
+const { withStorage } = await bundle("src/lib/storage/index.ts", "index.mjs");
+
+test("getB2Config needs all four variables and a backblaze endpoint", () => {
+ assert.equal(getB2Config({}), null);
+ assert.equal(getB2Config({ B2_KEY_ID: "k", B2_APPLICATION_KEY: "s", B2_BUCKET: "b", B2_ENDPOINT: "example.com" }), null);
+ const config = getB2Config({ B2_KEY_ID: "k", B2_APPLICATION_KEY: "s", B2_BUCKET: "b", B2_ENDPOINT: "https://s3.us-west-004.backblazeb2.com/" });
+ assert.equal(config?.region, "us-west-004");
+ assert.equal(config?.endpoint, "s3.us-west-004.backblazeb2.com");
+ assert.match(describeB2Problem({ B2_KEY_ID: "k" }), /together/);
+ assert.equal(describeB2Problem({}), null);
+});
+
+test("withStorage swaps BUCKET only when B2 is configured", () => {
+ const plain = { BUCKET: "r2", DB: "d1" };
+ assert.equal(withStorage(plain), plain);
+ const configured = { BUCKET: "r2", DB: "d1", B2_KEY_ID: "k", B2_APPLICATION_KEY: "s", B2_BUCKET: "b", B2_ENDPOINT: "s3.us-west-004.backblazeb2.com" };
+ const env = withStorage(configured);
+ assert.equal(env.DB, "d1");
+ assert.notEqual(env.BUCKET, "r2");
+ assert.equal(withStorage(env), env);
+});
+
+test("B2Bucket speaks S3: put, get, range, head, delete, multipart", async () => {
+ const objects = new Map();
+ const uploads = new Map();
+ const requests = [];
+ const server = createServer(async (req, res) => {
+ const chunks = [];
+ for await (const chunk of req) chunks.push(chunk);
+ const body = Buffer.concat(chunks);
+ const url = new URL(req.url, "http://x");
+ const key = decodeURIComponent(url.pathname.slice(1));
+ requests.push({ method: req.method, key, auth: req.headers.authorization, host: req.headers["x-orig-host"] });
+ const send = (status, payload = "", headers = {}) => { res.writeHead(status, headers); res.end(payload); };
+ if (req.method === "POST" && url.searchParams.has("uploads")) { uploads.set("u1", { parts: new Map(), type: req.headers["content-type"] }); return send(200, "<InitiateMultipartUploadResult><UploadId>u1</UploadId></InitiateMultipartUploadResult>"); }
+ if (req.method === "PUT" && url.searchParams.has("partNumber")) { uploads.get("u1").parts.set(Number(url.searchParams.get("partNumber")), body); return send(200, "", { ETag: `"etag-${url.searchParams.get("partNumber")}"` }); }
+ if (req.method === "POST" && url.searchParams.has("uploadId")) {
+ const parts = [...uploads.get("u1").parts.entries()].sort(([a], [b]) => a - b).map(([, value]) => value);
+ objects.set(key, { body: Buffer.concat(parts), type: uploads.get("u1").type });
+ return send(200, "<CompleteMultipartUploadResult></CompleteMultipartUploadResult>");
+ }
+ if (req.method === "DELETE" && url.searchParams.has("uploadId")) { uploads.delete("u1"); return send(204); }
+ if (req.method === "PUT") { objects.set(key, { body, type: req.headers["content-type"], meta: req.headers["x-amz-meta-note"] }); return send(200, "", { ETag: '"abc"' }); }
+ if (req.method === "DELETE") { objects.delete(key); return send(204); }
+ const object = objects.get(key);
+ if (!object) return send(404, "<Error><Code>NoSuchKey</Code><Message>missing</Message></Error>");
+ const headers = { "Content-Type": object.type ?? "application/octet-stream", ETag: '"abc"', "Last-Modified": new Date().toUTCString(), ...(object.meta ? { "x-amz-meta-note": object.meta } : {}) };
+ if (req.method === "HEAD") return send(200, "", { ...headers, "Content-Length": String(object.body.length) });
+ const range = /bytes=(\d+)-(\d+)/.exec(req.headers.range ?? "");
+ if (range) return send(206, object.body.subarray(Number(range[1]), Number(range[2]) + 1), { ...headers, "Content-Range": `bytes ${range[1]}-${range[2]}/${object.body.length}` });
+ return send(200, object.body, { ...headers, "Content-Length": String(object.body.length) });
+ });
+ await new Promise((done) => server.listen(0, "127.0.0.1", done));
+ const origFetch = globalThis.fetch;
+ globalThis.fetch = (input, init) => {
+ const url = new URL(typeof input === "string" ? input : input.href ?? input.url);
+ const target = new URL(url.pathname + url.search, `http://127.0.0.1:${server.address().port}`);
+ return origFetch(target, { ...init, headers: { ...init?.headers, "x-orig-host": url.host } });
+ };
+ try {
+ const bucket = new B2Bucket({ keyId: "k", applicationKey: "s", bucket: "mail", endpoint: "s3.us-west-004.backblazeb2.com", region: "us-west-004" });
+
+ const put = await bucket.put("raw/a b.eml", "hello world", { httpMetadata: { contentType: "message/rfc822" }, customMetadata: { note: "hi" } });
+ assert.equal(put.size, 11);
+ const got = await bucket.get("raw/a b.eml");
+ assert.equal(await got.text(), "hello world");
+ assert.equal(got.size, 11);
+ assert.equal(got.httpMetadata.contentType, "message/rfc822");
+ assert.equal(got.customMetadata.note, "hi");
+ assert.match(requests[0].auth, /^AWS4-HMAC-SHA256 Credential=k\/\d{8}\/us-west-004\/s3\/aws4_request/);
+ assert.equal(requests[0].host, "mail.s3.us-west-004.backblazeb2.com");
+
+ const ranged = await bucket.get("raw/a b.eml", { range: { offset: 6, length: 5 } });
+ assert.equal(await ranged.text(), "world");
+ assert.equal(ranged.size, 11);
+
+ assert.equal(await bucket.get("missing"), null);
+ assert.equal((await bucket.head("raw/a b.eml")).size, 11);
+ assert.equal(await bucket.head("missing"), null);
+
+ await bucket.delete(["raw/a b.eml", "never-existed"]);
+ assert.equal(await bucket.get("raw/a b.eml"), null);
+
+ const upload = await bucket.createMultipartUpload("drive/big", { httpMetadata: { contentType: "video/mp4" } });
+ const p1 = await upload.uploadPart(1, new Uint8Array([1, 2, 3]));
+ const p2 = await upload.uploadPart(2, new Uint8Array([4, 5]));
+ assert.equal(p1.etag, "etag-1");
+ const done = await bucket.resumeMultipartUpload("drive/big", upload.uploadId).complete([p2, p1]);
+ assert.equal(done.size, 5);
+ assert.deepEqual([...Buffer.from(await (await bucket.get("drive/big")).arrayBuffer())], [1, 2, 3, 4, 5]);
+ await bucket.createMultipartUpload("drive/other").then((u) => u.abort());
+ } finally {
+ globalThis.fetch = origFetch;
+ server.close();
+ }
+});
+
+test("AWS S3 config uses S3_* with AWS_* credential fallback, and B2 wins", () => {
+ assert.equal(getS3Config({ S3_BUCKET: "b", S3_REGION: "us-east-1" }), null);
+ const config = getS3Config({ S3_BUCKET: "b", S3_REGION: "eu-west-2", AWS_ACCESS_KEY_ID: "AK", AWS_SECRET_ACCESS_KEY: "sk" });
+ assert.deepEqual(config, { keyId: "AK", applicationKey: "sk", bucket: "b", region: "eu-west-2", endpoint: "s3.eu-west-2.amazonaws.com" });
+ assert.equal(getS3Config({ S3_BUCKET: "b", S3_REGION: "nope", S3_ACCESS_KEY_ID: "a", S3_SECRET_ACCESS_KEY: "b" }), null);
+ assert.match(describeB2Problem({ S3_BUCKET: "b" }), /AWS S3 needs/);
+ const both = withStorage({ BUCKET: "r2", S3_BUCKET: "b", S3_REGION: "us-east-1", S3_ACCESS_KEY_ID: "a", S3_SECRET_ACCESS_KEY: "s" });
+ assert.notEqual(both.BUCKET, "r2");
+});
diff --git a/worker.ts b/worker.ts
index 2f22697..3477723 100644
--- a/worker.ts
+++ b/worker.ts
@@ -1,3 +1,4 @@
+import { withStorage } from "./src/lib/storage";
import vinextHandler from "vinext/server/fetch-handler";
import {
processInboundMessage,
@@ -24,7 +25,8 @@ import { runDriveTrashRetention } from "./src/lib/drive/retention";
export { RealtimeHub } from "./src/lib/realtime/hub";
export default {
- async fetch(request: Request, env: CloudflareEnv, ctx: ExecutionContext) {
+ async fetch(request: Request, rawEnv: CloudflareEnv, ctx: ExecutionContext) {
+ const env = withStorage(rawEnv);
const url = new URL(request.url);
if (url.pathname === "/api/realtime") {
if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
@@ -48,7 +50,8 @@ export default {
return vinextHandler.fetch(request, env, ctx);
},
- async email(message: ForwardableEmailMessage, env: CloudflareEnv, ctx: ExecutionContext) {
+ async email(message: ForwardableEmailMessage, rawEnv: CloudflareEnv, ctx: ExecutionContext) {
+ const env = withStorage(rawEnv);
try {
if (message.rawSize > 25 * 1024 * 1024) {
message.setReject("Message rejected: raw email exceeds the 25 MiB receiving limit. Send a download link instead.");
@@ -96,7 +99,8 @@ export default {
}
},
- async queue(batch: MessageBatch, env: CloudflareEnv): Promise<void> {
+ async queue(batch: MessageBatch, rawEnv: CloudflareEnv): Promise<void> {
+ const env = withStorage(rawEnv);
for (const msg of batch.messages) {
try {
if (isInboundQueueMessage(msg.body)) {
@@ -123,7 +127,8 @@ export default {
}
},
- async scheduled(controller: ScheduledController, env: CloudflareEnv, ctx: ExecutionContext) {
+ async scheduled(controller: ScheduledController, rawEnv: CloudflareEnv, ctx: ExecutionContext) {
+ const env = withStorage(rawEnv);
if (controller.cron === "0 2 * * *") ctx.waitUntil(runScheduledDatabaseBackup(env, new Date(controller.scheduledTime)));
ctx.waitUntil(runAgentMaintenance(env));
ctx.waitUntil(runTrashRetention(env, new Date(controller.scheduledTime)));