Add storage-only email primitives

docs/contributing/setup-manifest.md

@@ -11,6 +11,16 @@ This project uses the following resources:
 - KV namespace for OAuth/session storage
   - `binding`: `OAUTH_KV`
   - `title`: `<app-name>-oauth`
+- Cloudflare Email Sending / Email Service Worker binding
+  - `binding`: `EMAIL`
+  - `wrangler` key: `send_email`
+  - Production domains still need Cloudflare-side sender/domain verification
+    before sends succeed.
+- Cloudflare Email Routing for inbound mail
+  - Configure MX records and selected route aliases in the Cloudflare
+    dashboard.
+  - Route only test/storage aliases to the Worker until quarantine behavior is
+    verified.
 - Vectorize indexes for MCP capability search (`CAPABILITY_VECTOR_INDEX`)
   - Production: `kody-capabilities-prod`
   - Preview: `kody-capabilities-preview`
@@ -67,6 +77,9 @@ automatically:
 - `APP_COMMIT_SHA` (optional; set automatically by deploy workflows for
   version-aware `/health` checks)
 - `CLOUDFLARE_EMAIL_FROM` (optional; sender address for outbound email)
+  Existing app email uses this as a default sender. First-class MCP
+  `email_send` additionally requires a verified sender identity created through
+  the email capabilities.
 - `AI_GATEWAY_ID` (required when `AI_MODE=remote`; deploy workflows sync a
   gateway ID from GitHub Actions secrets so remote inference goes through
   Cloudflare AI Gateway)
@@ -114,6 +127,8 @@ Configure these GitHub Actions secrets and variables for workflows:
 - `AI_GATEWAY_ID_PREVIEW` (required for preview deploys that use remote AI
   inference)
 - `CLOUDFLARE_EMAIL_FROM` (optional, required to send app email)
+  First-class Kody email also requires the `EMAIL` send binding plus
+  Cloudflare Email Service sender/domain verification.
 - `SENTRY_DSN` (optional; create a JavaScript/Cloudflare project in Sentry and
   paste the DSN; syncs to the Worker as a secret when set in GitHub Actions)
 - `CAPABILITY_REINDEX_SECRET` (optional; triggers post-deploy Vectorize reindex

docs/use/email-primitives.md

@@ -0,0 +1,51 @@
+# Email primitives
+
+Kody has a storage-only email surface for Cloudflare Email Service and Email
+Routing. It can send from verified identities, receive routed mail, store parsed
+messages, and quarantine unknown senders.
+
+## Capabilities
+
+Use the MCP `email` domain:
+
+- `email_inbox_create` creates an inbox and routable alias.
+- `email_inbox_list` lists inboxes and aliases for the signed-in user.
+- `email_sender_approve` verifies an outbound sender identity or allowlists an
+  inbound sender/domain for an inbox.
+- `email_sender_revoke` disables an allow rule.
+- `email_policy_get` inspects effective sender policy.
+- `email_send` sends outbound mail from a verified sender identity.
+- `email_reply` replies to a stored inbound message.
+- `email_message_list` lists stored sent, accepted, quarantined, or failed
+  messages.
+- `email_message_get` returns parsed bodies, headers, thread metadata, and
+  attachment metadata.
+
+## Safety model
+
+- Unknown inbound senders are quarantined.
+- Display names are not trusted. Kody stores envelope sender, parsed `From`, and
+  authentication headers separately.
+- Outbound sending requires a verified sender identity.
+- Inbound package handlers are intentionally disabled in this first slice. Mail
+  is stored and audited only.
+- Attachments are metadata-only for now; raw MIME for small messages is stored so
+  the first pass can be tested locally.
+
+## Local inbound testing
+
+Run the worker locally, create an inbox alias, then post raw MIME to Wrangler's
+email test endpoint:
+
+```sh
+curl --request POST \
+  'http://localhost:8787/cdn-cgi/handler/email?from=sender@example.com&to=alias@example.com' \
+  --data-raw 'From: Sender <sender@example.com>
+To: Alias <alias@example.com>
+Subject: Hello
+Message-ID: <hello@example.com>
+
+Hello from local email routing.'
+```
+
+Then inspect the message with `email_message_list` and `email_message_get`.

packages/mock-servers/cloudflare/src/worker.ts

@@ -589,6 +589,8 @@ async function handleEmailSend(
 	return envelope(
 		{
 			delivered: Array.isArray(payload.to) ? payload.to : [payload.to],
+			message_id: messageId,
+			messageId,
 			permanent_bounces: [],
 			queued: [],
 		},

packages/shared/src/outbound-email.ts

@@ -1,5 +1,7 @@
 import {
 	array,
+	createSchema,
+	fail,
 	object,
 	optional,
 	string,
@@ -10,12 +12,38 @@ import { minLength } from 'remix/data-schema/checks'
 
 const nonEmptyStringSchema = string().pipe(minLength(1))
 
+const optionalHeadersSchema = createSchema<
+	unknown,
+	Record<string, string> | undefined
+>((value, context) => {
+	if (value === undefined) return { value: undefined }
+	if (
+		!value ||
+		typeof value !== 'object' ||
+		Array.isArray(value) ||
+		(Object.getPrototypeOf(value) !== Object.prototype &&
+			Object.getPrototypeOf(value) !== null)
+	) {
+		return fail('Expected headers object', context.path)
+	}
+	const headers: Record<string, string> = {}
+	for (const [key, headerValue] of Object.entries(value)) {
+		if (typeof headerValue !== 'string') {
+			return fail(`Expected string header value for "${key}"`, context.path)
+		}
+		headers[key] = headerValue
+	}
+	return { value: headers }
+})
+
 const outboundEmailSchema = object({
 	from: nonEmptyStringSchema,
 	to: union([nonEmptyStringSchema, array(nonEmptyStringSchema)]),
 	subject: nonEmptyStringSchema,
 	html: nonEmptyStringSchema,
 	text: optional(nonEmptyStringSchema),
+	replyTo: optional(nonEmptyStringSchema),
+	headers: optionalHeadersSchema,
 })
 
 export type OutboundEmail = InferOutput<typeof outboundEmailSchema>

packages/worker/migrations/0030-email-primitives.sql

@@ -0,0 +1,200 @@
+CREATE TABLE IF NOT EXISTS email_sender_identities (
+	id TEXT PRIMARY KEY,
+	user_id TEXT NOT NULL,
+	package_id TEXT,
+	email TEXT NOT NULL,
+	domain TEXT,
+	display_name TEXT NOT NULL DEFAULT '',
+	status TEXT NOT NULL CHECK (status IN ('pending', 'verified', 'disabled')),
+	verified_at TEXT,
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_sender_identities_user_email
+ON email_sender_identities(user_id, email);
+
+CREATE INDEX IF NOT EXISTS idx_email_sender_identities_user_domain
+ON email_sender_identities(user_id, domain);
+
+CREATE TABLE IF NOT EXISTS email_inboxes (
+	id TEXT PRIMARY KEY,
+	user_id TEXT NOT NULL,
+	package_id TEXT,
+	name TEXT NOT NULL,
+	description TEXT NOT NULL DEFAULT '',
+	mode TEXT NOT NULL CHECK (mode IN ('quarantine', 'accept')),
+	enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)),
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_inboxes_user_name
+ON email_inboxes(user_id, name);
+
+CREATE INDEX IF NOT EXISTS idx_email_inboxes_user_created_at
+ON email_inboxes(user_id, created_at);
+
+CREATE TABLE IF NOT EXISTS email_inbox_addresses (
+	id TEXT PRIMARY KEY,
+	inbox_id TEXT NOT NULL,
+	user_id TEXT NOT NULL,
+	address TEXT NOT NULL,
+	local_part TEXT NOT NULL,
+	domain TEXT NOT NULL,
+	reply_token_hash TEXT,
+	enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)),
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL,
+	FOREIGN KEY (inbox_id) REFERENCES email_inboxes(id) ON DELETE CASCADE
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_inbox_addresses_address
+ON email_inbox_addresses(address);
+
+CREATE INDEX IF NOT EXISTS idx_email_inbox_addresses_inbox_id
+ON email_inbox_addresses(inbox_id);
+
+CREATE INDEX IF NOT EXISTS idx_email_inbox_addresses_reply_token
+ON email_inbox_addresses(reply_token_hash);
+
+CREATE TABLE IF NOT EXISTS email_threads (
+	id TEXT PRIMARY KEY,
+	user_id TEXT NOT NULL,
+	inbox_id TEXT,
+	subject_normalized TEXT NOT NULL DEFAULT '',
+	root_message_id_header TEXT,
+	last_message_at TEXT NOT NULL,
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_email_threads_user_last_message_at
+ON email_threads(user_id, last_message_at);
+
+CREATE INDEX IF NOT EXISTS idx_email_threads_root_message_id
+ON email_threads(root_message_id_header);
+
+CREATE TABLE IF NOT EXISTS email_messages (
+	id TEXT PRIMARY KEY,
+	direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+	user_id TEXT NOT NULL,
+	inbox_id TEXT,
+	thread_id TEXT,
+	sender_identity_id TEXT,
+	from_address TEXT NOT NULL,
+	envelope_from TEXT,
+	to_addresses_json TEXT NOT NULL DEFAULT '[]',
+	cc_addresses_json TEXT NOT NULL DEFAULT '[]',
+	bcc_addresses_json TEXT NOT NULL DEFAULT '[]',
+	reply_to_addresses_json TEXT NOT NULL DEFAULT '[]',
+	subject TEXT NOT NULL DEFAULT '',
+	message_id_header TEXT,
+	in_reply_to_header TEXT,
+	references_json TEXT NOT NULL DEFAULT '[]',
+	headers_json TEXT NOT NULL DEFAULT '{}',
+	auth_results TEXT,
+	text_body TEXT,
+	html_body TEXT,
+	raw_mime TEXT,
+	raw_size INTEGER NOT NULL DEFAULT 0,
+	policy_decision TEXT NOT NULL CHECK (policy_decision IN ('accepted', 'quarantined', 'rejected')),
+	processing_status TEXT NOT NULL CHECK (processing_status IN ('stored', 'sent', 'failed', 'rejected')),
+	provider_message_id TEXT,
+	error TEXT,
+	received_at TEXT,
+	sent_at TEXT,
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL,
+	FOREIGN KEY (inbox_id) REFERENCES email_inboxes(id) ON DELETE SET NULL,
+	FOREIGN KEY (thread_id) REFERENCES email_threads(id) ON DELETE SET NULL,
+	FOREIGN KEY (sender_identity_id) REFERENCES email_sender_identities(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_email_messages_user_created_at
+ON email_messages(user_id, created_at);
+
+CREATE INDEX IF NOT EXISTS idx_email_messages_inbox_created_at
+ON email_messages(inbox_id, created_at);
+
+CREATE INDEX IF NOT EXISTS idx_email_messages_thread_created_at
+ON email_messages(thread_id, created_at);
+
+CREATE INDEX IF NOT EXISTS idx_email_messages_policy_created_at
+ON email_messages(policy_decision, created_at);
+
+CREATE INDEX IF NOT EXISTS idx_email_messages_message_id_header
+ON email_messages(message_id_header);
+
+CREATE TABLE IF NOT EXISTS email_attachments (
+	id TEXT PRIMARY KEY,
+	message_id TEXT NOT NULL,
+	filename TEXT,
+	content_type TEXT NOT NULL,
+	content_id TEXT,
+	disposition TEXT,
+	size INTEGER NOT NULL DEFAULT 0,
+	storage_kind TEXT NOT NULL CHECK (storage_kind IN ('raw-mime', 'external', 'unavailable')),
+	storage_key TEXT,
+	created_at TEXT NOT NULL,
+	FOREIGN KEY (message_id) REFERENCES email_messages(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_email_attachments_message_id
+ON email_attachments(message_id);
+
+CREATE TABLE IF NOT EXISTS email_sender_policies (
+	id TEXT PRIMARY KEY,
+	user_id TEXT NOT NULL,
+	inbox_id TEXT,
+	package_id TEXT,
+	kind TEXT NOT NULL CHECK (kind IN ('sender', 'domain', 'reply_token')),
+	value TEXT NOT NULL,
+	effect TEXT NOT NULL CHECK (effect IN ('allow', 'quarantine', 'reject')),
+	enabled INTEGER NOT NULL DEFAULT 1 CHECK (enabled IN (0, 1)),
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL,
+	FOREIGN KEY (inbox_id) REFERENCES email_inboxes(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_email_sender_policies_inbox_kind_value
+ON email_sender_policies(inbox_id, kind, value);
+
+CREATE INDEX IF NOT EXISTS idx_email_sender_policies_user_kind_value
+ON email_sender_policies(user_id, kind, value);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_sender_policies_user_kind_value_inbox_null_package_null
+ON email_sender_policies(user_id, kind, value)
+WHERE inbox_id IS NULL AND package_id IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_sender_policies_user_kind_value_inbox_package_null
+ON email_sender_policies(user_id, kind, value, inbox_id)
+WHERE inbox_id IS NOT NULL AND package_id IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_sender_policies_user_kind_value_package_inbox_null
+ON email_sender_policies(user_id, kind, value, package_id)
+WHERE inbox_id IS NULL AND package_id IS NOT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_email_sender_policies_user_kind_value_inbox_package
+ON email_sender_policies(user_id, kind, value, inbox_id, package_id)
+WHERE inbox_id IS NOT NULL AND package_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS email_delivery_events (
+	id TEXT PRIMARY KEY,
+	message_id TEXT,
+	user_id TEXT,
+	inbox_id TEXT,
+	event_type TEXT NOT NULL CHECK (event_type IN ('receive_started', 'received', 'quarantined', 'rejected', 'send_requested', 'sent', 'failed', 'policy_matched')),
+	provider TEXT NOT NULL DEFAULT 'kody',
+	provider_message_id TEXT,
+	detail_json TEXT NOT NULL DEFAULT '{}',
+	created_at TEXT NOT NULL,
+	FOREIGN KEY (message_id) REFERENCES email_messages(id) ON DELETE SET NULL,
+	FOREIGN KEY (inbox_id) REFERENCES email_inboxes(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_email_delivery_events_message_id
+ON email_delivery_events(message_id);
+
+CREATE INDEX IF NOT EXISTS idx_email_delivery_events_user_created_at
+ON email_delivery_events(user_id, created_at);

packages/worker/package.json

@@ -22,6 +22,7 @@
     "acorn": "^8.16.0",
     "agents": "^0.11.1",
     "croner": "^10.0.1",
+    "postal-mime": "^2.7.4",
     "remix": "3.0.0-alpha.3",
     "workers-ai-provider": "^3.1.11",
     "zod": "^4.3.6"

packages/worker/src/app/email/cloudflare-email.node.test.ts

@@ -99,9 +99,10 @@ test('sendCloudflareEmail posts to the mock Cloudflare email API', async () => {
 		},
 	)
 
-	expect(sendResult).toEqual({
+	expect(sendResult).toMatchObject({
 		ok: true,
 	})
+	expect(sendResult.messageId).toMatch(/^email_/)
 
 	const response = await fetch(`${mock.origin}/__mocks/messages?token=${token}`)
 	expect(response.status).toBe(200)
@@ -156,7 +157,7 @@ test('sendCloudflareEmail defaults the API base URL when it is unset', async ()
 			},
 		)
 
-		expect(result).toEqual({
+		expect(result).toMatchObject({
 			ok: true,
 		})
 		expect(fetchSpy).toHaveBeenCalledTimes(1)