Email for professionals and teams
update notification
Hieu Nguyen (Jack)4bcccc37d3e9
diff --git a/CLAUDE.md b/CLAUDE.mdindex 2befb26..53b9562 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -109,6 +109,8 @@ States are positions in a change log (`changes.ts`): the `jmap_changes_*` trigge`POST /api/auth/device` signs a mobile app in with email + password (+ MFA via the login challenge) and returns a `jmap`-scoped API key of `kind = 'device'`, named after the device. It has its own rate limit (`DEVICE_LOGIN_RATE_LIMIT`) since it skips Turnstile. Device keys are listed and revoked under Settings → Security (`/api/devices`), hidden from the API keys list, and `deleteUserSessions` revokes them all (password change, reset, MFA change). Apps register their APNs token with `PUT /api/mobile/push` using the device key; `push_devices` rows cascade with the key. `notifyUsersOfNewMessage` fans out to `sendNativePush` (`src/lib/push/native.ts`), which needs the `APNS_KEY_ID`, `APNS_TEAM_ID` and `APNS_PRIVATE_KEY` secrets and encrypts sender and subject to each device's P-256 key (`native-crypto.ts`), or sends a content-free alert when the device turned previews off.+Native push goes straight to APNs when the server has `APNS_KEY_ID`/`APNS_TEAM_ID`/`APNS_PRIVATE_KEY`, or through a push relay (`mailflare-relay`, set `APNS_RELAY_URL`) when it has none. The app decides per registration: it trades its APNs token for a relay handle (`mfr1.…`, `src/lib/push/relay.ts`) and registers that as `token`; `sendNativePush` routes handles to the relay and hex tokens to Apple. `push_devices` is unique per (platform, token, user), and a device key keeps one registration (`registerPushDevice` deletes the one it replaces). The PUT response's `deliverable` says whether this server can send for that token, so the app can fall back from a handle to the raw token.+`Email/set` create and `Email/import` share one insert (`insertDraft` in `emails.ts`) and one target rule (`resolveDraftsMailbox` in `email-import-utils.ts`): a new message goes into exactly one Drafts mailbox, never Inbox or a folder, because delivered mail is the inbound pipeline's job. `Email/import` parses the uploaded blob with `parseRawMime`, stores the `Message-ID` in `providerMessageId` with its angle brackets (as inbound rows do) and keeps the uploaded bytes at `drafts/<messageId>.eml` in `rawR2Key`, so `readBlob` serves the client's own MIME back instead of the rebuilt minimal message; the `jmap-uploads/` object is deleted once claimed. `Email/copy` and `Email/parse` are still `emailUnsupported`.`email-query.ts` answers the `header` filter from columns — `Message-ID` from `providerMessageId` (compared with and without angle brackets, since inbound rows store them and outbound rows do not), `In-Reply-To` from `inReplyTo`, `References` by a padded `LIKE` on the space-joined chain. Any other header name throws `unsupportedFilter` (RFC 8620 §5.5). Filter conditions must never be silently dropped: a client that de-duplicates with `header` would otherwise match every message in the mailbox.diff --git a/env.d.ts b/env.d.tsindex 6a4cb82..2e878e5 100644--- a/env.d.ts+++ b/env.d.ts@@ -27,6 +27,8 @@ interface CloudflareEnv {APNS_TEAM_ID?: string;/** The .p8 file contents (PKCS#8 PEM). */APNS_PRIVATE_KEY?: string;+ /** Origin of a Mailflare push relay (mailflare-relay); lets this server push without APNS_* keys. */+ APNS_RELAY_URL?: string;AGENT_RATE_LIMIT?: RateLimit;/*** Backblaze B2 storage. When all four are set, B2 replaces the R2 binding for raw mail, attachments, Drive,diff --git a/src/app/api/mobile/avatar/route.ts b/src/app/api/mobile/avatar/route.tsindex f92c1a0..af1d520 100644--- a/src/app/api/mobile/avatar/route.ts+++ b/src/app/api/mobile/avatar/route.ts@@ -1,5 +1,10 @@import { NextResponse } from "next/server";import { getEnv } from "@/lib/cloudflare";+import { eq } from "drizzle-orm";+import { getDb } from "@/db";+import { domains, mailboxes, users } from "@/db/schema";+import { getMailboxAccessLevel } from "@/lib/mailboxes/access";+import { tracksAccountIdentity } from "@/lib/profile/identity-utils";import { authenticateApiRequest, hasScope } from "@/lib/api/key-auth";import { getAvatarImageResponse } from "@/lib/avatar-images";@@ -7,12 +12,37 @@ import { getAvatarImageResponse } from "@/lib/avatar-images";* The signed-in user's profile picture for the mobile app. `GET /api/profile/avatar`* needs a session cookie, which a device key is not, so this takes the same* `jmap`-scoped key the app uses everywhere else. `?variant=preview` is the small one.+ * `?mailbox=<id>` returns that mailbox's picture instead (the account's own when it is+ * the primary mailbox), for the app's inbox switcher.*/export async function GET(request: Request) {const env = getEnv();const auth = await authenticateApiRequest(env, request);if (!auth) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });if (!hasScope(auth.scopes, "jmap")) return NextResponse.json({ error: "This key does not have the jmap scope" }, { status: 403 });+ const mailboxId = new URL(request.url).searchParams.get("mailbox");+ if (mailboxId) {+ const db = getDb(env);+ const access = await getMailboxAccessLevel(db, auth.user, mailboxId);+ if (!access?.canRead) return new Response("Not found", { status: 404 });+ const [mailbox] = await db+ .select({+ avatarKey: mailboxes.avatarKey,+ type: mailboxes.type,+ localPart: mailboxes.localPart,+ hostname: domains.hostname,+ ownerEmail: users.email,+ ownerAvatarKey: users.avatarKey,+ })+ .from(mailboxes)+ .innerJoin(domains, eq(mailboxes.domainId, domains.id))+ .innerJoin(users, eq(mailboxes.userId, users.id))+ .where(eq(mailboxes.id, mailboxId))+ .limit(1);+ const key = mailbox && tracksAccountIdentity(mailbox, mailbox.ownerEmail) ? mailbox.ownerAvatarKey : mailbox?.avatarKey;+ if (!key) return new Response("Not found", { status: 404 });+ return getAvatarImageResponse(request, env.BUCKET, key);+ }if (!auth.user.avatarKey) return new Response("Not found", { status: 404 });return getAvatarImageResponse(request, env.BUCKET, auth.user.avatarKey);}diff --git a/src/app/api/mobile/push/route.ts b/src/app/api/mobile/push/route.tsindex a6a2fae..0b95f9d 100644--- a/src/app/api/mobile/push/route.ts+++ b/src/app/api/mobile/push/route.ts@@ -3,12 +3,14 @@ import { z } from "zod";import { getEnv } from "@/lib/cloudflare";import { authenticateApiRequest, hasScope } from "@/lib/api/key-auth";import { readJsonBody } from "@/lib/http/request";-import { registerPushDevice, unregisterPushDevice } from "@/lib/push/native";+import { canDeliverTo, registerPushDevice, unregisterPushDevice } from "@/lib/push/native";+import { isRelayHandle } from "@/lib/push/relay";import { isValidDevicePublicKey } from "@/lib/push/native-crypto";const registrationSchema = z.object({platform: z.literal("apns"),- token: z.string().regex(/^[0-9a-fA-F]{32,200}$/),+ // An APNs token (hex) or a handle issued by a push relay.+ token: z.string().regex(/^(?:[0-9a-fA-F]{32,200}|mfr1\.[A-Za-z0-9_-]{20,1000})$/),environment: z.enum(["production", "sandbox"]).default("production"),topic: z.string().min(3).max(200),publicKey: z.string().max(200).nullable().default(null),@@ -37,8 +39,9 @@ export async function PUT(request: Request) {return NextResponse.json({ error: "publicKey must be a raw uncompressed P-256 point" }, { status: 400 });}const { accountRef, ...registration } = parsed.data;- await registerPushDevice(env, auth.userId, auth.keyId, { ...registration, token: registration.token.toLowerCase(), clientRef: accountRef ?? null });- return NextResponse.json({ ok: true });+ await registerPushDevice(env, auth.userId, auth.keyId, { ...registration, token: isRelayHandle(registration.token) ? registration.token : registration.token.toLowerCase(), clientRef: accountRef ?? null });+ // Registrations are kept without APNs secrets, but nothing is sent; the app shows that instead of "On".+ return NextResponse.json({ ok: true, deliverable: canDeliverTo(env, registration.token) });}export async function DELETE(request: Request) {diff --git a/src/lib/email/inbound.ts b/src/lib/email/inbound.tsindex 78c4685..aeffbc1 100644--- a/src/lib/email/inbound.ts+++ b/src/lib/email/inbound.ts@@ -235,7 +235,9 @@ export async function processInboundMessage(}}- if (status !== "spam") {+ if (status === "spam") {+ console.info(`No notification for ${messageId}: filed as spam`);+ } else {const notificationUserIds = await getMailboxNotificationUserIds(env,decision.mailbox.mailboxId,diff --git a/src/lib/push/native-crypto.ts b/src/lib/push/native-crypto.tsindex 6ddd60a..d1d8270 100644--- a/src/lib/push/native-crypto.ts+++ b/src/lib/push/native-crypto.ts@@ -74,7 +74,12 @@ export async function encryptPreview(devicePublicKey: string, plaintext: Uint8Ar/** Imports an APNs auth key (the .p8 file: PKCS#8 PEM). */export async function importApnsKey(pem: string): Promise<CryptoKey> {- const body = pem.replace(/-----(BEGIN|END) PRIVATE KEY-----/g, "").replace(/\s+/g, "");+ // Secrets pasted into dashboards often carry quotes, literal "\n" or CRLFs.+ const body = pem+ .replace(/-----(BEGIN|END) PRIVATE KEY-----/g, "")+ .replace(/\\n/g, "")+ .replace(/["']/g, "")+ .replace(/\s+/g, "");return crypto.subtle.importKey("pkcs8", buffer(fromBase64(body)), { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);}diff --git a/src/lib/push/native.ts b/src/lib/push/native.tsindex d277a92..1c4bf91 100644--- a/src/lib/push/native.ts+++ b/src/lib/push/native.ts@@ -1,9 +1,10 @@-import { eq, inArray } from "drizzle-orm";+import { and, eq, inArray, ne } from "drizzle-orm";import { getDb } from "@/db";import { pushDevices } from "@/db/schema";import { newId } from "@/lib/ids";import type { NewMessageNotification } from "@/lib/realtime/types";import { encryptPreview, importApnsKey, signApnsJwt } from "./native-crypto";+import { isRelayHandle, relayBaseUrl, sendViaRelay } from "./relay";/*** Native push relay for the mobile apps (APNs). Configured with the@@ -19,8 +20,14 @@ function apnsConfig(env: CloudflareEnv): ApnsConfig | null {return keyId && teamId && privateKey ? { keyId, teamId, privateKey } : null;}+/** Whether this server can deliver a push at all: with its own APNs key or through a relay. */export function isNativePushConfigured(env: CloudflareEnv): boolean {- return apnsConfig(env) !== null;+ return apnsConfig(env) !== null || relayBaseUrl(env) !== null;+}++/** Whether a registration with this token can be delivered: a relay handle needs the relay, an APNs token needs a key. */+export function canDeliverTo(env: CloudflareEnv, token: string): boolean {+ return isRelayHandle(token) ? relayBaseUrl(env) !== null : apnsConfig(env) !== null;}/** APNs accepts a provider token for up to an hour; refresh well before. */@@ -49,6 +56,8 @@ export type PushRegistration = {/** Registers a device token for the user (and key) that authenticated; other accounts on the same device keep theirs. */export async function registerPushDevice(env: CloudflareEnv, userId: string, apiKeyId: string, registration: PushRegistration): Promise<void> {const now = new Date();+ // One registration per device key: a token (or relay handle) replaces the one it superseded.+ await getDb(env).delete(pushDevices).where(and(eq(pushDevices.apiKeyId, apiKeyId), ne(pushDevices.token, registration.token)));await getDb(env).insert(pushDevices).values({ id: newId("pdev"), userId, apiKeyId, ...registration, createdAt: now, updatedAt: now })@@ -66,51 +75,88 @@ export async function unregisterPushDevice(env: CloudflareEnv, apiKeyId: string)export async function buildApnsPayload(device: { publicKey: string | null; previews: boolean }, accountId: string, message: NewMessageNotification) {const base = { v: 1, accountId, mailboxId: message.mailboxId };if (!device.previews || !device.publicKey) {- return { aps: { alert: { title: "Mailflare", body: "New message" }, "mutable-content": 1, sound: "default", "thread-id": message.mailboxId }, mf: base };+ return { aps: { alert: { title: "Mailflare", body: "New message" }, "mutable-content": 1, "content-available": 1, sound: "default", "thread-id": message.mailboxId }, mf: base };}const preview = new TextEncoder().encode(JSON.stringify({ from: message.from, fromName: message.fromName, subject: message.subject, messageId: message.messageId }),);return {// Shown only if the extension cannot decrypt in time.- aps: { alert: { title: "Mailflare", body: "New message" }, "mutable-content": 1, sound: "default", "thread-id": message.mailboxId },+ aps: { alert: { title: "Mailflare", body: "New message" }, "mutable-content": 1, "content-available": 1, sound: "default", "thread-id": message.mailboxId },mf: { ...base, enc: await encryptPreview(device.publicKey, preview) },};}/** Sends a new-message push to every registered device of `userIds`. Expired tokens are dropped. */export async function sendNativePush(env: CloudflareEnv, userIds: string[], message: NewMessageNotification): Promise<void> {- const config = apnsConfig(env);- if (!config || userIds.length === 0) return;+ if (userIds.length === 0) return;const db = getDb(env);const devices = await db.select().from(pushDevices).where(inArray(pushDevices.userId, userIds));- if (devices.length === 0) return;- const token = await providerToken(config);+ if (devices.length === 0) {+ console.info(`Native push: no registered devices for ${userIds.length} user(s)`);+ return;+ }+ const config = apnsConfig(env);+ const relay = relayBaseUrl(env);+ let apnsToken: string | null = null;+ if (config && devices.some((device) => !isRelayHandle(device.token))) {+ try {+ apnsToken = await providerToken(config);+ } catch (error) {+ console.error("Native push: the APNs key could not be read. Check APNS_PRIVATE_KEY is the full .p8 contents.", error);+ }+ }const stale: string[] = [];- await Promise.allSettled(+ const results = await Promise.allSettled(devices.map(async (device) => {- const host = device.environment === "sandbox" ? "api.sandbox.push.apple.com" : "api.push.apple.com";const payload = await buildApnsPayload(device, device.clientRef ?? device.userId, message);+ const collapseId = message.messageId.slice(0, 64);+ if (isRelayHandle(device.token)) {+ if (!relay) {+ console.warn("Native push skipped: a device registered through a push relay but APNS_RELAY_URL is not set");+ return;+ }+ const result = await sendViaRelay(relay, device.token, payload, collapseId);+ if (result.kind === "sent") console.info(`Push sent through the relay (${device.environment}, topic ${device.topic})`);+ else if (result.kind === "gone") {+ console.warn(`Relay dropped a device (${result.status}, ${device.environment}, topic ${device.topic})`);+ stale.push(device.id);+ } else console.warn(`Relay push ${result.kind} (${result.status}${result.kind === "failed" ? ` ${result.error}` : ""})`);+ return;+ }+ if (!config) {+ console.warn("Native push skipped: no APNS_KEY_ID, APNS_TEAM_ID and APNS_PRIVATE_KEY for a directly registered device");+ return;+ }+ if (!apnsToken) return;+ const host = device.environment === "sandbox" ? "api.sandbox.push.apple.com" : "api.push.apple.com";const response = await fetch(`https://${host}/3/device/${device.token}`, {method: "POST",headers: {- authorization: `bearer ${token}`,+ authorization: `bearer ${apnsToken}`,"apns-topic": device.topic,"apns-push-type": "alert","apns-priority": "10",- "apns-collapse-id": message.messageId.slice(0, 64),+ "apns-collapse-id": collapseId,"content-type": "application/json",},body: JSON.stringify(payload),});- if (response.ok) return;+ if (response.ok) {+ console.info(`APNs push sent (${device.environment}, topic ${device.topic})`);+ return;+ }const reason = ((await response.json().catch(() => ({}))) as { reason?: string }).reason;if (response.status === 410 || reason === "BadDeviceToken" || reason === "Unregistered" || reason === "DeviceTokenNotForTopic") {+ console.warn(`APNs dropped a device (${response.status} ${reason ?? ""}, ${device.environment}, topic ${device.topic})`);stale.push(device.id);} else {console.warn(`APNs push failed (${response.status} ${reason ?? ""})`);}}),);+ for (const result of results) {+ if (result.status === "rejected") console.error("Native push errored", result.reason);+ }if (stale.length) await db.delete(pushDevices).where(inArray(pushDevices.id, stale));}diff --git a/src/lib/push/relay.ts b/src/lib/push/relay.tsnew file mode 100644index 0000000..7a5d441--- /dev/null+++ b/src/lib/push/relay.ts@@ -0,0 +1,58 @@+/**+ * Push through a Mailflare push relay (the `mailflare-relay` Worker) instead of+ * holding an APNs key. The app trades its APNs token for an opaque handle at+ * the relay and registers the handle here in place of the token; sending is+ * then one POST to the relay, which signs and forwards it to Apple.+ */++/** Handles the relay issues start with this; APNs tokens are plain hex. */+export const RELAY_HANDLE_PREFIX = "mfr1.";++export function isRelayHandle(token: string): boolean {+ return token.startsWith(RELAY_HANDLE_PREFIX);+}++/** The relay this server pushes through (`APNS_RELAY_URL`), as an origin without a trailing slash; null when unset or not https. */+export function relayBaseUrl(env: { APNS_RELAY_URL?: string }): string | null {+ const raw = env.APNS_RELAY_URL?.trim();+ if (!raw) return null;+ try {+ const url = new URL(raw);+ if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) return null;+ return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;+ } catch {+ return null;+ }+}++export type RelayResult =+ | { kind: "sent" }+ /** The relay no longer knows the device (404/410): forget the registration. */+ | { kind: "gone"; status: number }+ /** Worth trying again later (429, 5xx, network). */+ | { kind: "retry"; status: number }+ | { kind: "failed"; status: number; error: string };++export async function sendViaRelay(+ baseUrl: string,+ handle: string,+ payload: unknown,+ collapseId: string | undefined,+ fetchImpl: typeof fetch = fetch,+): Promise<RelayResult> {+ let response: Response;+ try {+ response = await fetchImpl(`${baseUrl}/api/v1/push`, {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ handle, payload, ...(collapseId ? { collapseId } : {}) }),+ });+ } catch {+ return { kind: "retry", status: 0 };+ }+ if (response.ok) return { kind: "sent" };+ if (response.status === 404 || response.status === 410) return { kind: "gone", status: response.status };+ if (response.status === 429 || response.status >= 500) return { kind: "retry", status: response.status };+ const error = ((await response.json().catch(() => ({}))) as { error?: string }).error ?? "";+ return { kind: "failed", status: response.status, error };+}diff --git a/src/lib/realtime/utils.ts b/src/lib/realtime/utils.tsindex da030a4..6149291 100644--- a/src/lib/realtime/utils.ts+++ b/src/lib/realtime/utils.ts@@ -57,7 +57,7 @@ export async function notifyUsersOfNewMessage(): Promise<void> {// Next dev uses a bindings-only proxy; realtime delivery runs in worker.ts.if (!env.REALTIME) return;- await Promise.allSettled([+ const results = await Promise.allSettled([...userIds.map((userId) => {const hub = env.REALTIME.getByName(userId);return hub.fetch("https://mailflare-realtime/notify", {@@ -68,4 +68,7 @@ export async function notifyUsersOfNewMessage(}),...(payload.type === "agent_draft" ? [] : [sendPushNotifications(env, userIds, payload), sendNativePush(env, userIds, payload)]),]);+ for (const result of results) {+ if (result.status === "rejected") console.error("New-message notification failed", result.reason);+ }}diff --git a/tests/apns-key-import.test.mjs b/tests/apns-key-import.test.mjsnew file mode 100644index 0000000..0ac52d7--- /dev/null+++ b/tests/apns-key-import.test.mjs@@ -0,0 +1,17 @@+import assert from "node:assert/strict";+import { generateKeyPairSync } from "node:crypto";+import test from "node:test";+import { importApnsKey } from "../src/lib/push/native-crypto.ts";++const pem = generateKeyPairSync("ec", { namedCurve: "P-256" }).privateKey.export({ type: "pkcs8", format: "pem" });++test("the .p8 imports as pasted, with CRLFs, quotes or literal \\n", async () => {+ await importApnsKey(pem);+ await importApnsKey(pem.replace(/\n/g, "\r\n"));+ await importApnsKey(`"${pem.replace(/\n/g, "\\n")}"`);+ await importApnsKey(pem.trim().replace(/\n/g, "\\n"));+});++test("garbage is rejected", async () => {+ await assert.rejects(importApnsKey("not a key"));+});diff --git a/tests/push-relay.test.mjs b/tests/push-relay.test.mjsnew file mode 100644index 0000000..9c68b05--- /dev/null+++ b/tests/push-relay.test.mjs@@ -0,0 +1,41 @@+import assert from "node:assert/strict";+import test from "node:test";+import { isRelayHandle, relayBaseUrl, sendViaRelay } from "../src/lib/push/relay.ts";++test("relay handles are told apart from APNs tokens", () => {+ assert.equal(isRelayHandle("mfr1.abc"), true);+ assert.equal(isRelayHandle("ab".repeat(32)), false);+});++test("the relay URL is an https origin without a trailing slash", () => {+ assert.equal(relayBaseUrl({ APNS_RELAY_URL: "https://ios-relay.mailflare.co" }), "https://ios-relay.mailflare.co");+ assert.equal(relayBaseUrl({ APNS_RELAY_URL: " https://ios-relay.mailflare.co/ " }), "https://ios-relay.mailflare.co");+ assert.equal(relayBaseUrl({ APNS_RELAY_URL: "http://localhost:3100" }), "http://localhost:3100");+ assert.equal(relayBaseUrl({ APNS_RELAY_URL: "http://relay.example.com" }), null);+ assert.equal(relayBaseUrl({ APNS_RELAY_URL: "not a url" }), null);+ assert.equal(relayBaseUrl({}), null);+});++test("a push is one POST to /api/v1/push with the handle", async () => {+ let seen;+ const fetchImpl = async (url, init) => {+ seen = { url, init };+ return new Response("{}", { status: 200 });+ };+ const payload = { aps: { alert: "x" } };+ assert.deepEqual(await sendViaRelay("https://r.example", "mfr1.h", payload, "c1", fetchImpl), { kind: "sent" });+ assert.equal(seen.url, "https://r.example/api/v1/push");+ assert.deepEqual(JSON.parse(seen.init.body), { handle: "mfr1.h", payload, collapseId: "c1" });+});++test("the relay's answers map to what the server should do", async () => {+ const reply = (status, body = {}) => async () => new Response(JSON.stringify(body), { status });+ const send = (fetchImpl) => sendViaRelay("https://r.example", "mfr1.h", {}, undefined, fetchImpl);+ assert.deepEqual(await send(reply(404)), { kind: "gone", status: 404 });+ assert.deepEqual(await send(reply(410)), { kind: "gone", status: 410 });+ assert.deepEqual(await send(reply(429)), { kind: "retry", status: 429 });+ assert.deepEqual(await send(reply(503)), { kind: "retry", status: 503 });+ assert.deepEqual(await send(reply(502, { error: "Apple rejected" })), { kind: "retry", status: 502 });+ assert.deepEqual(await send(reply(400, { error: "bad payload" })), { kind: "failed", status: 400, error: "bad payload" });+ assert.deepEqual(await send(async () => { throw new Error("offline"); }), { kind: "retry", status: 0 });+});