@push.rocks/smartjmap 1.0.0 → 2.0.0

package/ts/classes.jmapserver.ts

@@ -1,69 +1,130 @@
 import * as plugins from './smartjmap.plugins.js';
-import type { IJmapEmailAddress } from './classes.jmapclient.js';
-
-export interface IJmapServerMailbox {
-  id: string;
-  name: string;
-  role: string | null;
-  parentId: string | null;
-  sortOrder: number;
-}
+import {
+  JMAP_CORE_CAPABILITY,
+  JMAP_MAIL_CAPABILITY,
+  JMAP_SUBMISSION_CAPABILITY,
+  type IJmapEmailBodyValue,
+  type TJmapMethodResponse,
+} from './classes.jmapclient.js';
+import {
+  type IJmapAccountInfo,
+  type IJmapEmailCreate,
+  type IJmapEmailFilter,
+  type IJmapEmailRecord,
+  type IJmapEmailSetRequest,
+  type IJmapEmailUpdate,
+  type IJmapEnvelope,
+  type IJmapMailBackend,
+  type IJmapSetError,
+  type TJmapPrincipal,
+} from './interfaces.backend.js';
+import { MemoryMailBackend } from './classes.memorymailbackend.js';
 
-export interface IJmapServerBlob {
-  data: Buffer;
-  type: string;
-  name?: string;
+/** Options for constructing a JmapServer. */
+export interface IJmapServerOptions {
+  /** The storage backend; defaults to a fresh in-memory `MemoryMailBackend`. */
+  backend?: IJmapMailBackend;
+  /**
+   * Resolves an incoming Request to an authenticated principal (return null
+   * to reject with 401). Defaults to a static Basic/Bearer registry fed via
+   * `addUser`/`addBearerToken`.
+   */
+  authenticate?: (request: Request) => Promise<TJmapPrincipal | null>;
+  /**
+   * Absolute base URL (e.g. `https://mail.example.com`) prefixed to the URLs
+   * advertised in the session object. Defaults to relative URLs, which JMAP
+   * clients resolve against the session resource URL.
+   */
+  baseUrl?: string;
 }
 
-export interface IJmapServerChangeEntry {
-  state: number;
-  created: string[];
-  updated: string[];
-  destroyed: string[];
-}
+/** The advertised — and enforced — RFC 8620 core limits. */
+export const JMAP_SERVER_LIMITS = {
+  maxSizeUpload: 50_000_000,
+  maxConcurrentUpload: 4,
+  maxSizeRequest: 10_000_000,
+  maxConcurrentRequests: 4,
+  maxCallsInRequest: 16,
+  maxObjectsInGet: 500,
+  maxObjectsInSet: 500,
+};
 
-export interface IJmapServerIdentity {
-  id: string;
-  name: string;
-  email: string;
-  mayDelete: boolean;
-}
+/** The session object never changes at runtime, so its state is constant. */
+const SESSION_STATE = '0';
 
-export interface IJmapServerSubmission {
-  id: string;
-  emailId: string;
-  identityId: string;
-  undoStatus: string;
-  sendAt: string;
-}
+/** Default Email/get properties per RFC 8621 §4.2. */
+const DEFAULT_EMAIL_PROPERTIES = [
+  'id',
+  'blobId',
+  'threadId',
+  'mailboxIds',
+  'keywords',
+  'size',
+  'receivedAt',
+  'messageId',
+  'inReplyTo',
+  'references',
+  'sender',
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'replyTo',
+  'subject',
+  'sentAt',
+  'hasAttachment',
+  'preview',
+  'bodyValues',
+  'textBody',
+  'htmlBody',
+  'attachments',
+];
+const KNOWN_EMAIL_PROPERTIES = new Set(DEFAULT_EMAIL_PROPERTIES);
 
-export interface IJmapServerUser {
-  username: string;
-  password: string;
-  bearerTokens: Set<string>;
-  accountId: string;
-  mailboxes: Map<string, IJmapServerMailbox>;
-  emails: Map<string, Record<string, any>>;
-  blobs: Map<string, IJmapServerBlob>;
-  submissions: Map<string, IJmapServerSubmission>;
-  identities: IJmapServerIdentity[];
-  state: number;
-  changes: IJmapServerChangeEntry[];
-  idCounter: number;
-}
+const MAILBOX_PROPERTIES = [
+  'id',
+  'name',
+  'parentId',
+  'role',
+  'sortOrder',
+  'totalEmails',
+  'unreadEmails',
+  'totalThreads',
+  'unreadThreads',
+  'myRights',
+  'isSubscribed',
+];
+const KNOWN_MAILBOX_PROPERTIES = new Set(MAILBOX_PROPERTIES);
 
-export interface IJmapServerEmailInput {
-  from: IJmapEmailAddress | IJmapEmailAddress[];
-  to: IJmapEmailAddress | IJmapEmailAddress[];
-  cc?: IJmapEmailAddress[];
-  bcc?: IJmapEmailAddress[];
-  subject?: string;
-  textBody?: string;
-  htmlBody?: string;
-  keywords?: Record<string, boolean>;
-  receivedAt?: string;
-  attachments?: Array<{ name: string; type: string; content: string | Uint8Array }>;
-}
+const SUPPORTED_EMAIL_FILTER_KEYS = new Set([
+  'inMailbox',
+  'text',
+  'subject',
+  'from',
+  'to',
+  'before',
+  'after',
+  'hasKeyword',
+  'notKeyword',
+]);
+
+const DEFAULT_MAILBOX_RIGHTS = {
+  mayReadItems: true,
+  mayAddItems: true,
+  mayRemoveItems: true,
+  maySetSeen: true,
+  maySetKeywords: true,
+  mayCreateChild: true,
+  mayRename: true,
+  mayDelete: true,
+  maySubmit: true,
+};
+
+const textEncoder = new TextEncoder();
+
+/** Ensures bytes are backed by a plain ArrayBuffer so they satisfy BodyInit. */
+const asBodyBytes = (data: Uint8Array): Uint8Array<ArrayBuffer> =>
+  data.buffer instanceof ArrayBuffer ? (data as Uint8Array<ArrayBuffer>) : new Uint8Array(data);
 
 /** Error type used inside method dispatch; rendered as a JMAP `error` method response. */
 class JmapServerMethodError extends Error {
@@ -72,262 +133,236 @@ class JmapServerMethodError extends Error {
   }
 }
 
+/** One live event-source stream (SSE) with its filters and keepalive timer. */
+interface IEventStreamState {
+  accountId: string;
+  /** null = all types ('*'). */
+  types: Set<string> | null;
+  closeAfterState: boolean;
+  controller: ReadableStreamDefaultController<Uint8Array> | null;
+  pingTimer: ReturnType<typeof setInterval> | null;
+  /** Last state pushed per type, used to deduplicate double notifications. */
+  lastSent: Map<string, string>;
+  closed: boolean;
+}
+
+/** UTF-8-safe truncation: cuts at a codepoint boundary at or below maxBytes. */
+const truncateUtf8 = (value: string, maxBytes: number): string => {
+  const bytes = textEncoder.encode(value);
+  if (bytes.length <= maxBytes) {
+    return value;
+  }
+  let end = maxBytes;
+  while (end > 0 && (bytes[end]! & 0b1100_0000) === 0b1000_0000) {
+    end--;
+  }
+  return new TextDecoder().decode(bytes.subarray(0, end));
+};
+
+/**
+ * Evaluates an RFC 6901 JSON pointer with the RFC 8620 §3.7 extension: a `*`
+ * token applied to an array maps the rest of the pointer over every item,
+ * flattening one array level. Throws on any unresolvable path.
+ */
+const evalJsonPointer = (root: any, pointer: string): any => {
+  if (pointer === '') {
+    return root;
+  }
+  if (!pointer.startsWith('/')) {
+    throw new Error(`Invalid JSON pointer "${pointer}".`);
+  }
+  const tokens = pointer.slice(1).split('/');
+  const evaluate = (value: any, index: number): any => {
+    if (index === tokens.length) {
+      return value;
+    }
+    const token = tokens[index]!.replaceAll('~1', '/').replaceAll('~0', '~');
+    if (Array.isArray(value)) {
+      if (token === '*') {
+        const results = value.map((item) => evaluate(item, index + 1));
+        return results.some((result) => Array.isArray(result))
+          ? results.flatMap((result) => (Array.isArray(result) ? result : [result]))
+          : results;
+      }
+      const arrayIndex = Number(token);
+      if (!Number.isInteger(arrayIndex) || arrayIndex < 0 || arrayIndex >= value.length) {
+        throw new Error(`JSON pointer index "${token}" is out of range.`);
+      }
+      return evaluate(value[arrayIndex], index + 1);
+    }
+    if (value !== null && typeof value === 'object' && token in value) {
+      return evaluate(value[token], index + 1);
+    }
+    throw new Error(`JSON pointer token "${token}" does not resolve.`);
+  };
+  return evaluate(root, 0);
+};
+
 /**
- * A minimal in-memory JMAP server (RFC 8620 core + RFC 8621 mail subset)
- * for offline testing. Serves the session resource at /.well-known/jmap and
- * /jmap/session, the API at /jmap/api, blob downloads at /jmap/download/...,
- * and StateChange pushes via SSE at /jmap/eventsource.
+ * A JMAP server core (RFC 8620) with the RFC 8621 mail method surface,
+ * dispatching all storage into a pluggable `IJmapMailBackend`.
+ *
+ * The primary API is the web-standard `fetchHandler(request)` — mount it in
+ * any Request/Response runtime (Deno, Bun, service workers, Node ≥18). The
+ * `start(port)`/`stop()` pair wraps it in a node:http server for convenience.
+ *
+ * Endpoints: session (`/.well-known/jmap`, `/jmap/session`), API
+ * (`/jmap/api`), upload (`/jmap/upload/{accountId}`), download
+ * (`/jmap/download/{accountId}/{blobId}/{name}?type=`), and event source
+ * (`/jmap/eventsource` — SSE StateChange pushes per RFC 8620 §7.3).
+ *
+ * With no options this behaves as the offline test helper: an in-memory
+ * backend plus a static credential registry (`addUser`/`addBearerToken`).
  */
 export class JmapServer {
-  public users: Map<string, IJmapServerUser> = new Map();
-  private server: plugins.http.Server;
+  public readonly backend: IJmapMailBackend;
+  private options: IJmapServerOptions;
+  private registry: Map<string, { password: string; bearerTokens: Set<string> }> = new Map();
+  private httpServer: plugins.http.Server | null = null;
   private sockets: Set<plugins.net.Socket> = new Set();
-  private eventStreams: Map<plugins.http.ServerResponse, IJmapServerUser> = new Map();
+  private eventStreams: Set<IEventStreamState> = new Set();
+  private changeFeedUnsubscribe: (() => void) | null = null;
+  private activeApiRequests = 0;
 
-  constructor() {
-    this.server = plugins.http.createServer((req, res) => {
-      this.handleRequest(req, res);
-    });
-    this.server.on('connection', (socket) => {
-      this.sockets.add(socket);
-      socket.on('close', () => {
-        this.sockets.delete(socket);
-      });
-    });
+  constructor(options: IJmapServerOptions = {}) {
+    this.options = options;
+    this.backend = options.backend ?? new MemoryMailBackend();
   }
 
   // ======================
-  // store management
+  // default auth registry
   // ======================
 
+  /**
+   * Registers Basic credentials in the default authenticator's registry.
+   * Only consulted when no custom `authenticate` option is set. Account data
+   * itself lives in the backend (the memory backend auto-creates accounts).
+   */
   public addUser(username: string, password: string): void {
-    if (this.users.has(username)) {
+    if (this.registry.has(username)) {
       throw new Error(`User "${username}" already exists.`);
     }
-    const email = username.includes('@') ? username : `${username}@example.com`;
-    this.users.set(username, {
-      username,
-      password,
-      bearerTokens: new Set(),
-      accountId: `account_${username}`,
-      mailboxes: new Map(),
-      emails: new Map(),
-      blobs: new Map(),
-      submissions: new Map(),
-      identities: [{ id: 'identity_1', name: username, email, mayDelete: false }],
-      state: 0,
-      changes: [],
-      idCounter: 0,
-    });
+    this.registry.set(username, { password, bearerTokens: new Set() });
   }
 
-  /** Registers a valid Bearer token for a user. */
+  /** Registers a valid Bearer token for a user in the default authenticator. */
   public addBearerToken(username: string, token: string): void {
-    const user = this.requireUser(username);
-    user.bearerTokens.add(token);
-  }
-
-  public createMailbox(username: string, name: string, role?: string): string {
-    const user = this.requireUser(username);
-    for (const mailbox of user.mailboxes.values()) {
-      if (mailbox.name === name) {
-        throw new Error(`Mailbox "${name}" already exists for user "${username}".`);
-      }
-    }
-    const id = `mailbox_${++user.idCounter}`;
-    user.mailboxes.set(id, {
-      id,
-      name,
-      role: role ?? null,
-      parentId: null,
-      sortOrder: user.mailboxes.size,
-    });
-    return id;
-  }
-
-  /** Seeds an email into a user's mailbox; bumps state and pushes a StateChange. Returns the email id. */
-  public addEmail(username: string, mailboxName: string, input: IJmapServerEmailInput): string {
-    const user = this.requireUser(username);
-    const mailbox = Array.from(user.mailboxes.values()).find(
-      (candidate) => candidate.name === mailboxName || candidate.role === mailboxName
-    );
-    if (!mailbox) {
-      throw new Error(`Mailbox "${mailboxName}" does not exist for user "${username}".`);
-    }
-
-    const from = Array.isArray(input.from) ? input.from : [input.from];
-    const to = Array.isArray(input.to) ? input.to : [input.to];
-    const id = `email_${++user.idCounter}`;
-    const receivedAt = input.receivedAt ?? new Date().toISOString();
-    const textBody = input.textBody ?? '';
-
-    // raw message blob for Email/get blobId + downloads
-    const blobId = `blob_${id}`;
-    const rawLines = [
-      `From: ${from.map((address) => address.email).join(', ')}`,
-      `To: ${to.map((address) => address.email).join(', ')}`,
-      `Subject: ${input.subject ?? ''}`,
-      `Date: ${receivedAt}`,
-      '',
-      textBody,
-    ];
-    user.blobs.set(blobId, {
-      data: Buffer.from(rawLines.join('\r\n'), 'utf8'),
-      type: 'message/rfc822',
-      name: `${id}.eml`,
-    });
-
-    const bodyValues: Record<string, { value: string; isTruncated: boolean }> = {
-      text: { value: textBody, isTruncated: false },
-    };
-    const textBodyParts = [{ partId: 'text', type: 'text/plain', size: textBody.length }];
-    const htmlBodyParts: Array<Record<string, any>> = [];
-    if (typeof input.htmlBody === 'string') {
-      bodyValues.html = { value: input.htmlBody, isTruncated: false };
-      htmlBodyParts.push({ partId: 'html', type: 'text/html', size: input.htmlBody.length });
-    }
-
-    const attachmentParts: Array<Record<string, any>> = [];
-    for (const [index, attachment] of (input.attachments ?? []).entries()) {
-      const attachmentBlobId = `blob_${id}_att${index + 1}`;
-      const data = Buffer.from(attachment.content as any);
-      user.blobs.set(attachmentBlobId, {
-        data,
-        type: attachment.type,
-        name: attachment.name,
-      });
-      attachmentParts.push({
-        partId: null,
-        blobId: attachmentBlobId,
-        name: attachment.name,
-        type: attachment.type,
-        size: data.length,
-        disposition: 'attachment',
-      });
+    const entry = this.registry.get(username);
+    if (!entry) {
+      throw new Error(`User "${username}" does not exist.`);
     }
-
-    const email: Record<string, any> = {
-      id,
-      blobId,
-      threadId: `thread_${id}`,
-      mailboxIds: { [mailbox.id]: true },
-      keywords: input.keywords ?? {},
-      size: textBody.length,
-      receivedAt,
-      sentAt: receivedAt,
-      subject: input.subject ?? null,
-      from,
-      to,
-      cc: input.cc ?? null,
-      bcc: input.bcc ?? null,
-      replyTo: null,
-      hasAttachment: attachmentParts.length > 0,
-      preview: textBody.slice(0, 100),
-      bodyValues,
-      textBody: textBodyParts,
-      htmlBody: htmlBodyParts,
-      attachments: attachmentParts,
-    };
-    user.emails.set(id, email);
-    this.bumpState(user, { created: [id] });
-    return id;
+    entry.bearerTokens.add(token);
   }
 
   // ======================
-  // lifecycle
+  // lifecycle (node wrapper)
   // ======================
 
-  /** Starts the server. Resolves with the bound port (pass 0 for an ephemeral port). */
+  /** Starts a node:http server around fetchHandler. Resolves with the bound port (pass 0 for ephemeral). */
   public start(port: number): Promise<number> {
+    if (this.httpServer) {
+      throw new Error('JmapServer is already started.');
+    }
+    const server = plugins.http.createServer((req, res) => {
+      void this.handleNodeRequest(req, res);
+    });
+    server.on('connection', (socket) => {
+      this.sockets.add(socket);
+      socket.on('close', () => {
+        this.sockets.delete(socket);
+      });
+    });
+    this.httpServer = server;
     return new Promise((resolve, reject) => {
-      this.server.once('error', reject);
-      this.server.listen(port, () => {
-        const address = this.server.address();
-        const boundPort =
-          typeof address === 'object' && address ? address.port : port;
+      server.once('error', reject);
+      server.listen(port, () => {
+        const address = server.address();
+        const boundPort = typeof address === 'object' && address ? address.port : port;
         resolve(boundPort);
       });
     });
   }
 
-  /** Stops the server, ending open event streams and destroying open connections. */
-  public stop(): Promise<void> {
-    for (const response of this.eventStreams.keys()) {
-      try {
-        response.end();
-      } catch {
-        // response already gone
-      }
+  /**
+   * Stops the server: closes all event streams (clearing their ping timers
+   * and the backend change-feed subscription), destroys open connections,
+   * and closes the node listener when one was started.
+   */
+  public async stop(): Promise<void> {
+    for (const stream of Array.from(this.eventStreams)) {
+      this.closeStream(stream);
     }
-    this.eventStreams.clear();
     for (const socket of this.sockets) {
       socket.destroy();
     }
     this.sockets.clear();
-    return new Promise((resolve) => {
-      this.server.close(() => {
-        resolve();
+    const server = this.httpServer;
+    this.httpServer = null;
+    if (server) {
+      await new Promise<void>((resolve) => {
+        server.close(() => {
+          resolve();
+        });
       });
-    });
+    }
   }
 
   // ======================
-  // http handling
+  // web-standard core
   // ======================
 
-  private handleRequest(req: plugins.http.IncomingMessage, res: plugins.http.ServerResponse): void {
+  /**
+   * Handles a JMAP request end to end and returns the Response. This is the
+   * runtime-agnostic core — mount it directly as a Deno/Bun fetch handler.
+   */
+  public async fetchHandler(request: Request): Promise<Response> {
     try {
-      const user = this.authenticate(req);
-      if (!user) {
-        res.writeHead(401, {
+      const principal = await this.authenticatePrincipal(request);
+      if (!principal) {
+        return this.problemResponse(401, 'about:blank', 'Authentication required', {
           'www-authenticate': 'Bearer realm="jmap", Basic realm="jmap"',
-          'content-type': 'application/problem+json',
         });
-        res.end(
-          JSON.stringify({ type: 'about:blank', status: 401, detail: 'Authentication required' })
-        );
-        return;
+      }
+      const account = await this.backend.resolveAccount(principal);
+      if (!account) {
+        return this.problemResponse(403, 'about:blank', 'No account for this principal');
       }
 
-      const url = new URL(req.url ?? '/', 'http://localhost');
+      const url = new URL(request.url);
       const pathname = url.pathname;
+      const method = request.method.toUpperCase();
 
-      if (req.method === 'GET' && (pathname === '/.well-known/jmap' || pathname === '/jmap/session')) {
-        this.handleSession(user, res);
-        return;
+      if (method === 'GET' && (pathname === '/.well-known/jmap' || pathname === '/jmap/session')) {
+        return this.handleSession(account, principal);
       }
-      if (req.method === 'POST' && pathname === '/jmap/api') {
-        let body = '';
-        req.on('data', (chunk) => {
-          body += chunk;
-        });
-        req.on('end', () => {
-          this.handleApi(user, body, res);
-        });
-        return;
+      if (method === 'POST' && pathname === '/jmap/api') {
+        return this.handleApi(account, request);
       }
-      if (req.method === 'GET' && pathname === '/jmap/eventsource') {
-        this.handleEventSource(user, req, res);
-        return;
+      if (method === 'POST' && pathname.startsWith('/jmap/upload/')) {
+        return this.handleUpload(account, pathname, request);
       }
-      if (req.method === 'GET' && pathname.startsWith('/jmap/download/')) {
-        this.handleDownload(user, pathname, url, res);
-        return;
+      if (method === 'GET' && pathname.startsWith('/jmap/download/')) {
+        return this.handleDownload(account, pathname, url);
       }
-
-      res.writeHead(404, { 'content-type': 'application/problem+json' });
-      res.end(JSON.stringify({ type: 'about:blank', status: 404, detail: 'Not found' }));
+      if (method === 'GET' && pathname === '/jmap/eventsource') {
+        return this.handleEventSource(account, url);
+      }
+      return this.problemResponse(404, 'about:blank', 'Not found');
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      if (!res.headersSent) {
-        res.writeHead(500, { 'content-type': 'application/problem+json' });
-      }
-      res.end(JSON.stringify({ type: 'about:blank', status: 500, detail: message }));
+      return this.problemResponse(500, 'about:blank', message);
     }
   }
 
-  private authenticate(req: plugins.http.IncomingMessage): IJmapServerUser | null {
-    const header = req.headers.authorization;
+  // ======================
+  // authentication
+  // ======================
+
+  private async authenticatePrincipal(request: Request): Promise<TJmapPrincipal | null> {
+    if (this.options.authenticate) {
+      return this.options.authenticate(request);
+    }
+    const header = request.headers.get('authorization');
     if (!header) {
       return null;
     }
@@ -338,478 +373,855 @@ export class JmapServer {
     const scheme = header.slice(0, spaceIndex).toLowerCase();
     const value = header.slice(spaceIndex + 1).trim();
     if (scheme === 'bearer') {
-      for (const user of this.users.values()) {
-        if (user.bearerTokens.has(value)) {
-          return user;
+      for (const [username, entry] of this.registry) {
+        if (entry.bearerTokens.has(value)) {
+          return { username };
         }
       }
       return null;
     }
     if (scheme === 'basic') {
-      const decoded = Buffer.from(value, 'base64').toString('utf8');
+      let decoded: string;
+      try {
+        const binary = atob(value);
+        decoded = new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+      } catch {
+        return null;
+      }
       const colonIndex = decoded.indexOf(':');
       if (colonIndex === -1) {
         return null;
       }
       const username = decoded.slice(0, colonIndex);
       const password = decoded.slice(colonIndex + 1);
-      const user = this.users.get(username);
-      if (user && user.password === password) {
-        return user;
+      const entry = this.registry.get(username);
+      if (entry && entry.password === password) {
+        return { username };
       }
       return null;
     }
     return null;
   }
 
-  private handleSession(user: IJmapServerUser, res: plugins.http.ServerResponse): void {
+  // ======================
+  // session
+  // ======================
+
+  private handleSession(account: IJmapAccountInfo, principal: TJmapPrincipal): Response {
     const session = {
       capabilities: {
-        'urn:ietf:params:jmap:core': {
-          maxSizeUpload: 50_000_000,
-          maxConcurrentUpload: 4,
-          maxSizeRequest: 10_000_000,
-          maxConcurrentRequests: 4,
-          maxCallsInRequest: 16,
-          maxObjectsInGet: 500,
-          maxObjectsInSet: 500,
-          collationAlgorithms: ['i;ascii-numeric', 'i;ascii-casemap'],
+        [JMAP_CORE_CAPABILITY]: {
+          ...JMAP_SERVER_LIMITS,
+          collationAlgorithms: ['i;ascii-casemap'],
         },
-        'urn:ietf:params:jmap:mail': {},
-        'urn:ietf:params:jmap:submission': {},
+        [JMAP_MAIL_CAPABILITY]: {},
+        [JMAP_SUBMISSION_CAPABILITY]: {},
       },
       accounts: {
-        [user.accountId]: {
-          name: user.username,
-          isPersonal: true,
-          isReadOnly: false,
+        [account.accountId]: {
+          name: account.name,
+          isPersonal: account.isPersonal ?? true,
+          isReadOnly: account.isReadOnly ?? false,
           accountCapabilities: {
-            'urn:ietf:params:jmap:mail': {},
-            'urn:ietf:params:jmap:submission': {},
+            [JMAP_MAIL_CAPABILITY]: {
+              maxMailboxesPerEmail: null,
+              maxMailboxDepth: null,
+              maxSizeMailboxName: 490,
+              maxSizeAttachmentsPerEmail: JMAP_SERVER_LIMITS.maxSizeUpload,
+              emailQuerySortOptions: ['receivedAt'],
+              mayCreateTopLevelMailbox: false,
+            },
+            [JMAP_SUBMISSION_CAPABILITY]: {
+              maxDelayedSend: 0,
+              submissionExtensions: {},
+            },
           },
         },
       },
       primaryAccounts: {
-        'urn:ietf:params:jmap:core': user.accountId,
-        'urn:ietf:params:jmap:mail': user.accountId,
-        'urn:ietf:params:jmap:submission': user.accountId,
+        [JMAP_CORE_CAPABILITY]: account.accountId,
+        [JMAP_MAIL_CAPABILITY]: account.accountId,
+        [JMAP_SUBMISSION_CAPABILITY]: account.accountId,
       },
-      username: user.username,
-      apiUrl: '/jmap/api',
-      downloadUrl: '/jmap/download/{accountId}/{blobId}/{name}?type={type}',
-      uploadUrl: '/jmap/upload/{accountId}',
-      eventSourceUrl: '/jmap/eventsource?types={types}&closeafter={closeafter}&ping={ping}',
-      state: String(user.state),
+      username: principal.username,
+      apiUrl: this.buildUrl('/jmap/api'),
+      downloadUrl: this.buildUrl('/jmap/download/{accountId}/{blobId}/{name}?type={type}'),
+      uploadUrl: this.buildUrl('/jmap/upload/{accountId}'),
+      eventSourceUrl: this.buildUrl(
+        '/jmap/eventsource?types={types}&closeafter={closeafter}&ping={ping}'
+      ),
+      state: SESSION_STATE,
     };
-    res.writeHead(200, { 'content-type': 'application/json' });
-    res.end(JSON.stringify(session));
+    return this.jsonResponse(200, session);
   }
 
-  private handleApi(user: IJmapServerUser, body: string, res: plugins.http.ServerResponse): void {
-    let parsed: any;
-    try {
-      parsed = JSON.parse(body);
-    } catch {
-      res.writeHead(400, { 'content-type': 'application/problem+json' });
-      res.end(
-        JSON.stringify({
-          type: 'urn:ietf:params:jmap:error:notJSON',
-          status: 400,
-          detail: 'The request body is not valid JSON.',
-        })
-      );
-      return;
-    }
-    if (!Array.isArray(parsed?.methodCalls)) {
-      res.writeHead(400, { 'content-type': 'application/problem+json' });
-      res.end(
-        JSON.stringify({
-          type: 'urn:ietf:params:jmap:error:notRequest',
-          status: 400,
-          detail: 'The request body is not a valid JMAP request object.',
-        })
-      );
-      return;
-    }
+  private buildUrl(path: string): string {
+    const base = this.options.baseUrl;
+    return base ? `${base.replace(/\/+$/, '')}${path}` : path;
+  }
 
-    const createdIds = new Map<string, string>();
-    const methodResponses: Array<[string, Record<string, any>, string]> = [];
-    for (const call of parsed.methodCalls) {
-      const [methodName, args, callId] = call as [string, Record<string, any>, string];
+  // ======================
+  // api endpoint
+  // ======================
+
+  private async handleApi(account: IJmapAccountInfo, request: Request): Promise<Response> {
+    if (this.activeApiRequests >= JMAP_SERVER_LIMITS.maxConcurrentRequests) {
+      return this.limitResponse(429, 'maxConcurrentRequests', 'Too many concurrent requests.');
+    }
+    this.activeApiRequests++;
+    try {
+      const bytes = new Uint8Array(await request.arrayBuffer());
+      if (bytes.length > JMAP_SERVER_LIMITS.maxSizeRequest) {
+        return this.limitResponse(
+          400,
+          'maxSizeRequest',
+          `The request is larger than ${JMAP_SERVER_LIMITS.maxSizeRequest} bytes.`
+        );
+      }
+      let parsed: any;
       try {
-        const result = this.dispatchMethod(user, methodName, args ?? {}, createdIds);
-        methodResponses.push([methodName, result, callId]);
-      } catch (error) {
-        if (error instanceof JmapServerMethodError) {
-          methodResponses.push([
-            'error',
-            { type: error.type, description: error.message },
-            callId,
-          ]);
-        } else {
-          const message = error instanceof Error ? error.message : String(error);
-          methodResponses.push(['error', { type: 'serverFail', description: message }, callId]);
+        parsed = JSON.parse(new TextDecoder().decode(bytes));
+      } catch {
+        return this.problemResponse(
+          400,
+          'urn:ietf:params:jmap:error:notJSON',
+          'The request body is not valid JSON.'
+        );
+      }
+      if (
+        !parsed ||
+        typeof parsed !== 'object' ||
+        !Array.isArray(parsed.using) ||
+        !Array.isArray(parsed.methodCalls)
+      ) {
+        return this.problemResponse(
+          400,
+          'urn:ietf:params:jmap:error:notRequest',
+          'The request body is not a valid JMAP request object.'
+        );
+      }
+      const knownCapabilities = new Set([
+        JMAP_CORE_CAPABILITY,
+        JMAP_MAIL_CAPABILITY,
+        JMAP_SUBMISSION_CAPABILITY,
+      ]);
+      const using = new Set<string>(parsed.using);
+      for (const capability of using) {
+        if (!knownCapabilities.has(capability)) {
+          return this.problemResponse(
+            400,
+            'urn:ietf:params:jmap:error:unknownCapability',
+            `The capability "${capability}" is not supported by this server.`
+          );
         }
       }
-    }
+      if (parsed.methodCalls.length > JMAP_SERVER_LIMITS.maxCallsInRequest) {
+        return this.limitResponse(
+          400,
+          'maxCallsInRequest',
+          `The request has more than ${JMAP_SERVER_LIMITS.maxCallsInRequest} method calls.`
+        );
+      }
 
-    res.writeHead(200, { 'content-type': 'application/json' });
-    res.end(JSON.stringify({ methodResponses, sessionState: String(user.state) }));
-  }
+      const createdIds = new Map<string, string>(
+        Object.entries((parsed.createdIds ?? {}) as Record<string, string>)
+      );
+      const methodResponses: TJmapMethodResponse[] = [];
+      let mutated = false;
+      for (const call of parsed.methodCalls) {
+        if (!Array.isArray(call) || typeof call[0] !== 'string' || typeof call[2] !== 'string') {
+          return this.problemResponse(
+            400,
+            'urn:ietf:params:jmap:error:notRequest',
+            'Each method call must be a [name, arguments, callId] tuple.'
+          );
+        }
+        const [methodName, rawArgs, callId] = call as [string, Record<string, any>, string];
+        try {
+          const args = this.resolveBackReferences(rawArgs ?? {}, methodResponses);
+          const results = await this.dispatchMethod(account, methodName, args, using, createdIds);
+          for (const entry of results) {
+            methodResponses.push([entry.name, entry.result, callId]);
+            if (entry.mutated) {
+              mutated = true;
+            }
+          }
+        } catch (error) {
+          if (error instanceof JmapServerMethodError) {
+            methodResponses.push([
+              'error',
+              { type: error.type, description: error.message },
+              callId,
+            ]);
+          } else {
+            const message = error instanceof Error ? error.message : String(error);
+            methodResponses.push(['error', { type: 'serverFail', description: message }, callId]);
+          }
+        }
+      }
 
-  private handleEventSource(
-    user: IJmapServerUser,
-    req: plugins.http.IncomingMessage,
-    res: plugins.http.ServerResponse
-  ): void {
-    res.writeHead(200, {
-      'content-type': 'text/event-stream',
-      'cache-control': 'no-cache',
-      connection: 'keep-alive',
-    });
-    res.write(': jmap event stream\n\n');
-    this.eventStreams.set(res, user);
-    req.on('close', () => {
-      this.eventStreams.delete(res);
-    });
-  }
+      if (mutated) {
+        await this.pushAfterMutation(account);
+      }
 
-  private handleDownload(
-    user: IJmapServerUser,
-    pathname: string,
-    url: URL,
-    res: plugins.http.ServerResponse
-  ): void {
-    // /jmap/download/{accountId}/{blobId}/{name}
-    const segments = pathname.split('/').filter((segment) => segment.length > 0);
-    const accountId = decodeURIComponent(segments[2] ?? '');
-    const blobId = decodeURIComponent(segments[3] ?? '');
-    if (accountId !== user.accountId) {
-      res.writeHead(404, { 'content-type': 'application/problem+json' });
-      res.end(JSON.stringify({ type: 'about:blank', status: 404, detail: 'Unknown account' }));
-      return;
+      const responseBody: Record<string, any> = {
+        methodResponses,
+        sessionState: SESSION_STATE,
+      };
+      if (parsed.createdIds !== undefined) {
+        responseBody.createdIds = Object.fromEntries(createdIds);
+      }
+      return this.jsonResponse(200, responseBody);
+    } finally {
+      this.activeApiRequests--;
     }
-    const blob = user.blobs.get(blobId);
-    if (!blob) {
-      res.writeHead(404, { 'content-type': 'application/problem+json' });
-      res.end(JSON.stringify({ type: 'about:blank', status: 404, detail: 'Unknown blob' }));
-      return;
+  }
+
+  /**
+   * Resolves `#argument` ResultReference objects (RFC 8620 §3.7) against the
+   * responses of earlier method calls in the same request.
+   */
+  private resolveBackReferences(
+    args: Record<string, any>,
+    priorResponses: TJmapMethodResponse[]
+  ): Record<string, any> {
+    const resolved: Record<string, any> = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (!key.startsWith('#')) {
+        resolved[key] = value;
+        continue;
+      }
+      const name = key.slice(1);
+      if (name in args) {
+        throw new JmapServerMethodError(
+          'invalidArguments',
+          `The arguments contain both "${name}" and "#${name}".`
+        );
+      }
+      if (
+        !value ||
+        typeof value !== 'object' ||
+        typeof value.resultOf !== 'string' ||
+        typeof value.name !== 'string' ||
+        typeof value.path !== 'string'
+      ) {
+        throw new JmapServerMethodError(
+          'invalidResultReference',
+          `"#${name}" is not a valid ResultReference object.`
+        );
+      }
+      const source = priorResponses.find(
+        (entry) => entry[2] === value.resultOf && entry[0] === value.name
+      );
+      if (!source) {
+        throw new JmapServerMethodError(
+          'invalidResultReference',
+          `No response found for resultOf "${value.resultOf}" and name "${value.name}".`
+        );
+      }
+      try {
+        resolved[name] = evalJsonPointer(source[1], value.path);
+      } catch (error) {
+        throw new JmapServerMethodError(
+          'invalidResultReference',
+          error instanceof Error ? error.message : String(error)
+        );
+      }
     }
-    const type = url.searchParams.get('type') ?? blob.type;
-    res.writeHead(200, { 'content-type': type, 'content-length': blob.data.length });
-    res.end(blob.data);
+    return resolved;
   }
 
   // ======================
-  // jmap method dispatch
+  // method dispatch
   // ======================
 
-  private dispatchMethod(
-    user: IJmapServerUser,
+  private async dispatchMethod(
+    account: IJmapAccountInfo,
     methodName: string,
     args: Record<string, any>,
+    using: Set<string>,
     createdIds: Map<string, string>
-  ): Record<string, any> {
+  ): Promise<Array<{ name: string; result: Record<string, any>; mutated?: boolean }>> {
+    const requiredCapability: Record<string, string> = {
+      'Core/echo': JMAP_CORE_CAPABILITY,
+      'Mailbox/get': JMAP_MAIL_CAPABILITY,
+      'Mailbox/query': JMAP_MAIL_CAPABILITY,
+      'Mailbox/changes': JMAP_MAIL_CAPABILITY,
+      'Thread/get': JMAP_MAIL_CAPABILITY,
+      'Email/get': JMAP_MAIL_CAPABILITY,
+      'Email/query': JMAP_MAIL_CAPABILITY,
+      'Email/changes': JMAP_MAIL_CAPABILITY,
+      'Email/queryChanges': JMAP_MAIL_CAPABILITY,
+      'Email/set': JMAP_MAIL_CAPABILITY,
+      'Identity/get': JMAP_SUBMISSION_CAPABILITY,
+      'EmailSubmission/set': JMAP_SUBMISSION_CAPABILITY,
+    };
+    const capability = requiredCapability[methodName];
+    if (!capability) {
+      throw new JmapServerMethodError('unknownMethod', `Unknown method "${methodName}".`);
+    }
+    if (!using.has(capability)) {
+      throw new JmapServerMethodError(
+        'unknownMethod',
+        `Method "${methodName}" requires the capability "${capability}" in "using".`
+      );
+    }
+    if (methodName !== 'Core/echo') {
+      this.requireAccountId(account, args);
+    }
+
     switch (methodName) {
       case 'Core/echo':
-        return args;
+        return [{ name: methodName, result: args }];
       case 'Mailbox/get':
-        return this.methodMailboxGet(user, args);
+        return [{ name: methodName, result: await this.methodMailboxGet(account, args) }];
       case 'Mailbox/query':
-        return this.methodMailboxQuery(user, args);
+        return [{ name: methodName, result: await this.methodMailboxQuery(account, args) }];
+      case 'Mailbox/changes':
+        return [{ name: methodName, result: await this.methodMailboxChanges(account, args) }];
+      case 'Thread/get':
+        return [{ name: methodName, result: await this.methodThreadGet(account, args) }];
       case 'Email/get':
-        return this.methodEmailGet(user, args);
+        return [{ name: methodName, result: await this.methodEmailGet(account, args) }];
       case 'Email/query':
-        return this.methodEmailQuery(user, args);
+        return [{ name: methodName, result: await this.methodEmailQuery(account, args) }];
       case 'Email/changes':
-        return this.methodEmailChanges(user, args);
-      case 'Email/set':
-        return this.methodEmailSet(user, args, createdIds);
+        return [{ name: methodName, result: await this.methodEmailChanges(account, args) }];
+      case 'Email/queryChanges':
+        // Explicitly unsupported in phase 1: clients fall back to Email/query.
+        throw new JmapServerMethodError(
+          'cannotCalculateChanges',
+          'Email/queryChanges is not supported; re-run the query instead.'
+        );
+      case 'Email/set': {
+        const result = await this.methodEmailSet(account, args, createdIds);
+        return [{ name: methodName, result, mutated: result.newState !== result.oldState }];
+      }
       case 'Identity/get':
-        return this.methodIdentityGet(user);
+        return [{ name: methodName, result: await this.methodIdentityGet(account, args) }];
       case 'EmailSubmission/set':
-        return this.methodEmailSubmissionSet(user, args, createdIds);
+        return this.methodEmailSubmissionSet(account, args, createdIds);
       default:
         throw new JmapServerMethodError('unknownMethod', `Unknown method "${methodName}".`);
     }
   }
 
-  private methodMailboxGet(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
-    const all = Array.from(user.mailboxes.values());
-    let list: IJmapServerMailbox[];
-    const notFound: string[] = [];
-    if (args.ids == null) {
-      list = all;
-    } else {
-      list = [];
-      for (const id of args.ids as string[]) {
-        const mailbox = user.mailboxes.get(id);
-        if (mailbox) {
-          list.push(mailbox);
-        } else {
-          notFound.push(id);
-        }
-      }
+  private requireAccountId(account: IJmapAccountInfo, args: Record<string, any>): void {
+    if (typeof args.accountId !== 'string') {
+      throw new JmapServerMethodError('invalidArguments', 'accountId is required.');
     }
-    const augmented = list.map((mailbox) => {
-      const emails = Array.from(user.emails.values()).filter(
-        (email) => email.mailboxIds?.[mailbox.id]
+    if (args.accountId !== account.accountId) {
+      throw new JmapServerMethodError(
+        'accountNotFound',
+        `Account "${args.accountId}" is not accessible with these credentials.`
       );
-      return {
+    }
+  }
+
+  // ======================
+  // mailbox methods
+  // ======================
+
+  private async methodMailboxGet(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    let ids: string[] | null = null;
+    if (args.ids !== null && args.ids !== undefined) {
+      if (!Array.isArray(args.ids)) {
+        throw new JmapServerMethodError('invalidArguments', 'ids must be an array of ids or null.');
+      }
+      if (args.ids.length > JMAP_SERVER_LIMITS.maxObjectsInGet) {
+        throw new JmapServerMethodError(
+          'requestTooLarge',
+          `ids exceeds maxObjectsInGet (${JMAP_SERVER_LIMITS.maxObjectsInGet}).`
+        );
+      }
+      ids = args.ids as string[];
+    }
+    const properties = this.validateProperties(args.properties, KNOWN_MAILBOX_PROPERTIES);
+    const result = await this.backend.getMailboxes(account.accountId, ids);
+    const list = result.list.map((mailbox) => {
+      const full: Record<string, any> = {
         ...mailbox,
-        totalEmails: emails.length,
-        unreadEmails: emails.filter((email) => !email.keywords?.$seen).length,
-        totalThreads: emails.length,
-        unreadThreads: emails.filter((email) => !email.keywords?.$seen).length,
-        myRights: {
-          mayReadItems: true,
-          mayAddItems: true,
-          mayRemoveItems: true,
-          maySetSeen: true,
-          maySetKeywords: true,
-          mayCreateChild: true,
-          mayRename: true,
-          mayDelete: true,
-          maySubmit: true,
-        },
-        isSubscribed: true,
+        isSubscribed: mailbox.isSubscribed ?? true,
+        myRights: mailbox.myRights ?? { ...DEFAULT_MAILBOX_RIGHTS },
       };
+      return this.projectObject(full, properties ?? MAILBOX_PROPERTIES);
     });
     return {
-      accountId: user.accountId,
-      state: String(user.state),
-      list: augmented,
-      notFound,
+      accountId: account.accountId,
+      state: result.state,
+      list,
+      notFound: result.notFound,
     };
   }
 
-  private methodMailboxQuery(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
-    const filter = args.filter ?? {};
-    let mailboxes = Array.from(user.mailboxes.values());
-    if (typeof filter.role === 'string') {
-      mailboxes = mailboxes.filter((mailbox) => mailbox.role === filter.role);
-    }
-    if (typeof filter.name === 'string') {
-      mailboxes = mailboxes.filter((mailbox) => mailbox.name === filter.name);
+  private async methodMailboxQuery(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    const filter = (args.filter ?? {}) as Record<string, any>;
+    if ('operator' in filter) {
+      throw new JmapServerMethodError(
+        'unsupportedFilter',
+        'FilterOperator is not supported for Mailbox/query.'
+      );
     }
-    const ids = mailboxes.map((mailbox) => mailbox.id);
-    return {
-      accountId: user.accountId,
-      queryState: String(user.state),
-      canCalculateChanges: false,
-      position: 0,
-      ids,
-      total: ids.length,
-    };
-  }
-
-  private methodEmailGet(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
-    if (!Array.isArray(args.ids)) {
-      throw new JmapServerMethodError('invalidArguments', 'Email/get requires an ids array.');
+    for (const key of Object.keys(filter)) {
+      if (!['role', 'name', 'parentId'].includes(key)) {
+        throw new JmapServerMethodError(
+          'unsupportedFilter',
+          `Mailbox filter condition "${key}" is not supported.`
+        );
+      }
     }
-    const list: Array<Record<string, any>> = [];
-    const notFound: string[] = [];
-    for (const id of args.ids as string[]) {
-      const email = user.emails.get(id);
-      if (email) {
-        // Returned as a full superset of the requestable properties;
-        // property projection is intentionally not implemented.
-        list.push({ ...email });
-      } else {
-        notFound.push(id);
+    for (const comparator of (args.sort ?? []) as Array<Record<string, any>>) {
+      if (!['name', 'sortOrder'].includes(comparator.property)) {
+        throw new JmapServerMethodError(
+          'unsupportedSort',
+          `Mailbox sort property "${comparator.property}" is not supported.`
+        );
       }
     }
-    return {
-      accountId: user.accountId,
-      state: String(user.state),
-      list,
-      notFound,
-    };
-  }
-
-  private methodEmailQuery(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
-    const filter = args.filter ?? {};
-    let emails = Array.from(user.emails.values());
-    if (typeof filter.inMailbox === 'string') {
-      emails = emails.filter((email) => email.mailboxIds?.[filter.inMailbox]);
+    const result = await this.backend.getMailboxes(account.accountId, null);
+    let mailboxes = result.list;
+    if (typeof filter.role === 'string') {
+      mailboxes = mailboxes.filter((mailbox) => mailbox.role === filter.role);
     }
-    if (typeof filter.subject === 'string') {
-      emails = emails.filter((email) =>
-        String(email.subject ?? '').toLowerCase().includes(filter.subject.toLowerCase())
-      );
+    if (typeof filter.name === 'string') {
+      mailboxes = mailboxes.filter((mailbox) => mailbox.name === filter.name);
     }
-    if (typeof filter.text === 'string') {
-      const needle = filter.text.toLowerCase();
-      emails = emails.filter(
-        (email) =>
-          String(email.subject ?? '').toLowerCase().includes(needle) ||
-          String(email.bodyValues?.text?.value ?? '').toLowerCase().includes(needle)
-      );
+    if ('parentId' in filter) {
+      mailboxes = mailboxes.filter((mailbox) => mailbox.parentId === filter.parentId);
     }
-    const sort = Array.isArray(args.sort) && args.sort.length ? args.sort[0] : null;
-    if (sort?.property === 'receivedAt') {
-      emails.sort((a, b) => {
-        const comparison = String(a.receivedAt ?? '').localeCompare(String(b.receivedAt ?? ''));
-        return sort.isAscending === false ? -comparison : comparison;
+    const comparators = (args.sort ?? []) as Array<Record<string, any>>;
+    if (comparators.length) {
+      mailboxes = [...mailboxes].sort((a, b) => {
+        for (const comparator of comparators) {
+          const direction = comparator.isAscending === false ? -1 : 1;
+          const property = comparator.property as 'name' | 'sortOrder';
+          const left = a[property] ?? 0;
+          const right = b[property] ?? 0;
+          if (left < right) {
+            return -direction;
+          }
+          if (left > right) {
+            return direction;
+          }
+        }
+        return 0;
       });
     }
-    const position = typeof args.position === 'number' ? args.position : 0;
-    let ids = emails.map((email) => email.id as string).slice(position);
-    const total = emails.length;
+    const position = this.validatePosition(args);
+    let ids = mailboxes.map((mailbox) => mailbox.id).slice(position);
     if (typeof args.limit === 'number') {
       ids = ids.slice(0, args.limit);
     }
-    return {
-      accountId: user.accountId,
-      queryState: String(user.state),
+    const response: Record<string, any> = {
+      accountId: account.accountId,
+      queryState: result.state,
       canCalculateChanges: false,
       position,
       ids,
-      total,
     };
+    if (args.calculateTotal === true) {
+      response.total = mailboxes.length;
+    }
+    return response;
   }
 
-  private methodEmailChanges(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
-    const since = Number(args.sinceState);
-    if (!Number.isFinite(since) || since < 0 || since > user.state) {
+  private async methodMailboxChanges(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    const { sinceState, maxChanges } = this.validateChangesArgs(args);
+    const changes = await this.backend.getMailboxChanges(account.accountId, sinceState, maxChanges);
+    if (!changes) {
       throw new JmapServerMethodError(
         'cannotCalculateChanges',
-        `Cannot calculate changes since state "${args.sinceState}".`
+        `Cannot calculate mailbox changes since state "${sinceState}".`
       );
     }
-    const created = new Set<string>();
-    const updated = new Set<string>();
-    const destroyed = new Set<string>();
-    for (const entry of user.changes) {
-      if (entry.state <= since) {
-        continue;
-      }
-      for (const id of entry.created) {
-        created.add(id);
-      }
-      for (const id of entry.updated) {
-        updated.add(id);
-      }
-      for (const id of entry.destroyed) {
-        if (created.has(id)) {
-          // created and destroyed within the window: omit entirely
-          created.delete(id);
-        } else {
-          destroyed.add(id);
-        }
-        updated.delete(id);
-      }
+    return { accountId: account.accountId, ...changes };
+  }
+
+  // ======================
+  // thread methods
+  // ======================
+
+  private async methodThreadGet(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    if (!Array.isArray(args.ids)) {
+      throw new JmapServerMethodError('invalidArguments', 'Thread/get requires an ids array.');
     }
-    for (const id of created) {
-      updated.delete(id);
+    if (args.ids.length > JMAP_SERVER_LIMITS.maxObjectsInGet) {
+      throw new JmapServerMethodError(
+        'requestTooLarge',
+        `ids exceeds maxObjectsInGet (${JMAP_SERVER_LIMITS.maxObjectsInGet}).`
+      );
     }
+    // Result-reference chains like Email/get -> /list/*/threadId commonly
+    // contain duplicates; deduplicate so each thread is returned once.
+    const ids = Array.from(new Set(args.ids as string[]));
+    const result = await this.backend.getThreads(account.accountId, ids);
     return {
-      accountId: user.accountId,
-      oldState: String(since),
-      newState: String(user.state),
-      hasMoreChanges: false,
-      created: Array.from(created),
-      updated: Array.from(updated),
-      destroyed: Array.from(destroyed),
+      accountId: account.accountId,
+      state: result.state,
+      list: result.list,
+      notFound: result.notFound,
     };
   }
 
-  private methodEmailSet(
-    user: IJmapServerUser,
-    args: Record<string, any>,
-    createdIds: Map<string, string>
-  ): Record<string, any> {
-    const oldState = String(user.state);
-    const created: Record<string, any> = {};
-    const notCreated: Record<string, any> = {};
-    const updated: Record<string, any> = {};
-    const notUpdated: Record<string, any> = {};
-    const destroyed: string[] = [];
-    const notDestroyed: Record<string, any> = {};
-    const changedCreated: string[] = [];
-    const changedUpdated: string[] = [];
-    const changedDestroyed: string[] = [];
+  // ======================
+  // email methods
+  // ======================
 
-    for (const [creationId, spec] of Object.entries((args.create ?? {}) as Record<string, any>)) {
-      try {
-        const email = this.createEmailFromSpec(user, spec);
-        user.emails.set(email.id, email);
-        createdIds.set(creationId, email.id);
-        changedCreated.push(email.id);
-        created[creationId] = {
-          id: email.id,
-          blobId: email.blobId,
-          threadId: email.threadId,
-          size: email.size,
-        };
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        notCreated[creationId] = { type: 'invalidProperties', description: message };
-      }
+  private async methodEmailGet(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    if (args.ids === null || args.ids === undefined) {
+      // RFC 8621 allows rejecting "fetch all" for the potentially huge Email type.
+      throw new JmapServerMethodError(
+        'requestTooLarge',
+        'Email/get requires an explicit ids array on this server.'
+      );
     }
+    if (!Array.isArray(args.ids)) {
+      throw new JmapServerMethodError('invalidArguments', 'Email/get requires an ids array.');
+    }
+    if (args.ids.length > JMAP_SERVER_LIMITS.maxObjectsInGet) {
+      throw new JmapServerMethodError(
+        'requestTooLarge',
+        `ids exceeds maxObjectsInGet (${JMAP_SERVER_LIMITS.maxObjectsInGet}).`
+      );
+    }
+    const properties = this.validateProperties(args.properties, KNOWN_EMAIL_PROPERTIES);
+    const result = await this.backend.getEmails(account.accountId, args.ids as string[], properties);
+    const effectiveProperties = properties ?? DEFAULT_EMAIL_PROPERTIES;
+    const list = result.list.map((record) => {
+      const projected = this.projectObject(record as any, effectiveProperties);
+      if (effectiveProperties.includes('bodyValues')) {
+        projected.bodyValues = this.buildBodyValues(record, args);
+      }
+      return projected;
+    });
+    return {
+      accountId: account.accountId,
+      state: result.state,
+      list,
+      notFound: result.notFound,
+    };
+  }
 
-    for (const [id, patch] of Object.entries((args.update ?? {}) as Record<string, any>)) {
-      const email = user.emails.get(id);
-      if (!email) {
-        notUpdated[id] = { type: 'notFound', description: `Email "${id}" does not exist.` };
+  /** Applies the Email/get body-value fetch flags and maxBodyValueBytes truncation. */
+  private buildBodyValues(
+    record: IJmapEmailRecord,
+    args: Record<string, any>
+  ): Record<string, IJmapEmailBodyValue> {
+    const wanted = new Set<string>();
+    if (args.fetchAllBodyValues === true) {
+      for (const partId of Object.keys(record.bodyValues)) {
+        wanted.add(partId);
+      }
+    }
+    if (args.fetchTextBodyValues === true) {
+      for (const part of record.textBody) {
+        if (part.partId != null) {
+          wanted.add(part.partId);
+        }
+      }
+    }
+    if (args.fetchHTMLBodyValues === true) {
+      for (const part of record.htmlBody) {
+        if (part.partId != null) {
+          wanted.add(part.partId);
+        }
+      }
+    }
+    const maxBytes =
+      typeof args.maxBodyValueBytes === 'number' && args.maxBodyValueBytes > 0
+        ? args.maxBodyValueBytes
+        : null;
+    const result: Record<string, IJmapEmailBodyValue> = {};
+    for (const partId of wanted) {
+      const bodyValue = record.bodyValues[partId];
+      if (!bodyValue) {
         continue;
       }
-      try {
-        this.applyPatch(email, patch);
-        changedUpdated.push(id);
-        updated[id] = null;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        notUpdated[id] = { type: 'invalidPatch', description: message };
+      let value = bodyValue.value;
+      let isTruncated = bodyValue.isTruncated === true;
+      if (maxBytes !== null) {
+        const truncated = truncateUtf8(value, maxBytes);
+        if (truncated.length < value.length) {
+          value = truncated;
+          isTruncated = true;
+        }
       }
+      result[partId] = { value, isTruncated };
     }
+    return result;
+  }
 
-    for (const id of (args.destroy ?? []) as string[]) {
-      if (user.emails.delete(id)) {
-        changedDestroyed.push(id);
-        destroyed.push(id);
-      } else {
-        notDestroyed[id] = { type: 'notFound', description: `Email "${id}" does not exist.` };
+  private async methodEmailQuery(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    const filter = (args.filter ?? {}) as Record<string, any>;
+    if ('operator' in filter) {
+      throw new JmapServerMethodError(
+        'unsupportedFilter',
+        'FilterOperator is not supported; use a flat FilterCondition.'
+      );
+    }
+    for (const key of Object.keys(filter)) {
+      if (!SUPPORTED_EMAIL_FILTER_KEYS.has(key)) {
+        throw new JmapServerMethodError(
+          'unsupportedFilter',
+          `Email filter condition "${key}" is not supported.`
+        );
+      }
+    }
+    const sort = (args.sort ?? []) as Array<Record<string, any>>;
+    for (const comparator of sort) {
+      if (comparator.property !== 'receivedAt') {
+        throw new JmapServerMethodError(
+          'unsupportedSort',
+          `Email sort property "${comparator.property}" is not supported.`
+        );
+      }
+    }
+    if (args.anchor !== undefined && args.anchor !== null) {
+      throw new JmapServerMethodError('invalidArguments', 'anchor is not supported.');
+    }
+    const position = this.validatePosition(args);
+    const result = await this.backend.queryEmails(account.accountId, {
+      filter: filter as IJmapEmailFilter,
+      sort: sort as Array<{ property: string; isAscending?: boolean }>,
+      position,
+      limit: typeof args.limit === 'number' ? args.limit : null,
+      calculateTotal: args.calculateTotal === true,
+    });
+    const response: Record<string, any> = {
+      accountId: account.accountId,
+      queryState: result.queryState,
+      canCalculateChanges: false,
+      position: result.position,
+      ids: result.ids,
+    };
+    if (args.calculateTotal === true) {
+      response.total = result.total ?? 0;
+    }
+    return response;
+  }
+
+  private async methodEmailChanges(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    const { sinceState, maxChanges } = this.validateChangesArgs(args);
+    const changes = await this.backend.getEmailChanges(account.accountId, sinceState, maxChanges);
+    if (!changes) {
+      throw new JmapServerMethodError(
+        'cannotCalculateChanges',
+        `Cannot calculate changes since state "${sinceState}".`
+      );
+    }
+    return { accountId: account.accountId, ...changes };
+  }
+
+  private async methodEmailSet(
+    account: IJmapAccountInfo,
+    args: Record<string, any>,
+    createdIds: Map<string, string>
+  ): Promise<Record<string, any>> {
+    const createEntries = Object.entries((args.create ?? {}) as Record<string, any>);
+    const updateEntries = Object.entries((args.update ?? {}) as Record<string, any>);
+    const destroyIds = (args.destroy ?? []) as string[];
+    if (
+      createEntries.length + updateEntries.length + destroyIds.length >
+      JMAP_SERVER_LIMITS.maxObjectsInSet
+    ) {
+      throw new JmapServerMethodError(
+        'requestTooLarge',
+        `The set request exceeds maxObjectsInSet (${JMAP_SERVER_LIMITS.maxObjectsInSet}).`
+      );
+    }
+    if (typeof args.ifInState === 'string') {
+      const current = await this.backend.getEmails(account.accountId, []);
+      if (current.state !== args.ifInState) {
+        throw new JmapServerMethodError(
+          'stateMismatch',
+          `ifInState "${args.ifInState}" does not match the current state "${current.state}".`
+        );
       }
     }
 
-    if (changedCreated.length || changedUpdated.length || changedDestroyed.length) {
-      this.bumpState(user, {
-        created: changedCreated,
-        updated: changedUpdated,
-        destroyed: changedDestroyed,
-      });
+    const backendRequest: IJmapEmailSetRequest = {};
+    const notUpdatedEarly: Record<string, IJmapSetError> = {};
+
+    if (createEntries.length) {
+      backendRequest.create = {};
+      for (const [creationId, spec] of createEntries) {
+        backendRequest.create[creationId] = spec as IJmapEmailCreate;
+      }
+    }
+    if (updateEntries.length) {
+      backendRequest.update = {};
+      for (const [id, patch] of updateEntries) {
+        try {
+          backendRequest.update[id] = this.parseEmailUpdatePatch(patch as Record<string, any>);
+        } catch (error) {
+          notUpdatedEarly[id] =
+            error instanceof JmapServerMethodError
+              ? { type: error.type, description: error.message }
+              : { type: 'invalidPatch', description: String(error) };
+        }
+      }
+    }
+    if (destroyIds.length) {
+      backendRequest.destroy = destroyIds;
     }
 
+    const result = await this.backend.setEmails(account.accountId, backendRequest);
+
+    const created: Record<string, any> = {};
+    for (const [creationId, record] of Object.entries(result.created)) {
+      createdIds.set(creationId, record.id);
+      created[creationId] = {
+        id: record.id,
+        blobId: record.blobId,
+        threadId: record.threadId,
+        size: record.size,
+      };
+    }
+    const updated: Record<string, null> = {};
+    for (const id of result.updated) {
+      updated[id] = null;
+    }
     return {
-      accountId: user.accountId,
-      oldState,
-      newState: String(user.state),
+      accountId: account.accountId,
+      oldState: result.oldState,
+      newState: result.newState,
       created,
-      notCreated,
+      notCreated: result.notCreated,
       updated,
-      notUpdated,
-      destroyed,
-      notDestroyed,
+      notUpdated: { ...result.notUpdated, ...notUpdatedEarly },
+      destroyed: result.destroyed,
+      notDestroyed: result.notDestroyed,
     };
   }
 
-  private methodIdentityGet(user: IJmapServerUser): Record<string, any> {
-    return {
-      accountId: user.accountId,
-      state: '0',
-      list: user.identities,
-      notFound: [],
-    };
+  /**
+   * Normalizes an Email/set update patch (RFC 8620 §5.3): full `keywords`/
+   * `mailboxIds` replacements and single-key JSON-pointer patches
+   * (`keywords/$seen`, `mailboxIds/<id>`). Email properties other than these
+   * two are immutable (RFC 8621 §4.6).
+   */
+  private parseEmailUpdatePatch(patch: Record<string, any>): IJmapEmailUpdate {
+    const update: IJmapEmailUpdate = {};
+    const unescape = (token: string): string => token.replaceAll('~1', '/').replaceAll('~0', '~');
+    for (const [path, value] of Object.entries(patch)) {
+      if (path === 'keywords' || path === 'mailboxIds') {
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+          throw new JmapServerMethodError('invalidProperties', `"${path}" must be an object.`);
+        }
+        const normalized: Record<string, boolean> = {};
+        for (const [key, entryValue] of Object.entries(value as Record<string, any>)) {
+          if (entryValue !== true) {
+            throw new JmapServerMethodError(
+              'invalidProperties',
+              `Values in "${path}" must be true; remove entries instead of setting them false.`
+            );
+          }
+          normalized[key] = true;
+        }
+        update[path] = normalized;
+        continue;
+      }
+      const slashIndex = path.indexOf('/');
+      if (slashIndex === -1) {
+        throw new JmapServerMethodError(
+          'invalidProperties',
+          `Email property "${path}" is immutable or unknown.`
+        );
+      }
+      const property = path.slice(0, slashIndex);
+      const rest = path.slice(slashIndex + 1);
+      if ((property !== 'keywords' && property !== 'mailboxIds') || rest.includes('/') || !rest) {
+        throw new JmapServerMethodError('invalidPatch', `Unsupported patch path "${path}".`);
+      }
+      const key = unescape(rest);
+      const normalizedValue = value === true ? true : value === null || value === false ? null : undefined;
+      if (normalizedValue === undefined) {
+        throw new JmapServerMethodError(
+          'invalidPatch',
+          `Patch value for "${path}" must be true or null.`
+        );
+      }
+      if (property === 'keywords') {
+        update.keywordsPatch = update.keywordsPatch ?? {};
+        update.keywordsPatch[key] = normalizedValue;
+      } else {
+        update.mailboxIdsPatch = update.mailboxIdsPatch ?? {};
+        update.mailboxIdsPatch[key] = normalizedValue;
+      }
+    }
+    if (update.keywords && update.keywordsPatch) {
+      throw new JmapServerMethodError(
+        'invalidPatch',
+        'A patch must not set "keywords" and patch "keywords/..." at the same time.'
+      );
+    }
+    if (update.mailboxIds && update.mailboxIdsPatch) {
+      throw new JmapServerMethodError(
+        'invalidPatch',
+        'A patch must not set "mailboxIds" and patch "mailboxIds/..." at the same time.'
+      );
+    }
+    return update;
+  }
+
+  // ======================
+  // identity + submission methods
+  // ======================
+
+  private async methodIdentityGet(
+    account: IJmapAccountInfo,
+    args: Record<string, any>
+  ): Promise<Record<string, any>> {
+    const result = await this.backend.getIdentities(account.accountId);
+    let list = result.list;
+    const notFound: string[] = [];
+    if (Array.isArray(args.ids)) {
+      const wanted = new Set(args.ids as string[]);
+      list = list.filter((identity) => wanted.has(identity.id));
+      for (const id of wanted) {
+        if (!list.some((identity) => identity.id === id)) {
+          notFound.push(id);
+        }
+      }
+    }
+    return { accountId: account.accountId, state: result.state, list, notFound };
   }
 
-  private methodEmailSubmissionSet(
-    user: IJmapServerUser,
+  private async methodEmailSubmissionSet(
+    account: IJmapAccountInfo,
     args: Record<string, any>,
     createdIds: Map<string, string>
-  ): Record<string, any> {
+  ): Promise<Array<{ name: string; result: Record<string, any>; mutated?: boolean }>> {
     const created: Record<string, any> = {};
-    const notCreated: Record<string, any> = {};
+    const notCreated: Record<string, IJmapSetError> = {};
+    const notUpdated: Record<string, IJmapSetError> = {};
+    const notDestroyed: Record<string, IJmapSetError> = {};
+    /** creationId -> { submissionId, emailId } for onSuccess* resolution. */
+    const createdSubmissions = new Map<string, { submissionId: string; emailId: string }>();
+
+    const identitiesResult = await this.backend.getIdentities(account.accountId);
+
     for (const [creationId, spec] of Object.entries((args.create ?? {}) as Record<string, any>)) {
       let emailId: string = spec.emailId;
       if (typeof emailId === 'string' && emailId.startsWith('#')) {
@@ -823,14 +1235,18 @@ export class JmapServer {
         }
         emailId = resolved;
       }
-      if (!user.emails.has(emailId)) {
+      const emailResult = await this.backend.getEmails(account.accountId, [emailId]);
+      const email = emailResult.list[0];
+      if (!email) {
         notCreated[creationId] = {
           type: 'invalidProperties',
           description: `Email "${emailId}" does not exist.`,
         };
         continue;
       }
-      const identity = user.identities.find((candidate) => candidate.id === spec.identityId);
+      const identity = identitiesResult.list.find(
+        (candidate) => candidate.id === spec.identityId
+      );
       if (!identity) {
         notCreated[creationId] = {
           type: 'invalidProperties',
@@ -838,182 +1254,562 @@ export class JmapServer {
         };
         continue;
       }
-      const id = `submission_${++user.idCounter}`;
-      const submission: IJmapServerSubmission = {
-        id,
-        emailId,
-        identityId: identity.id,
-        undoStatus: 'final',
-        sendAt: new Date().toISOString(),
+      const envelope = this.resolveEnvelope(spec.envelope, identity.email, email);
+      if (!envelope.rcptTo.length) {
+        notCreated[creationId] = {
+          type: 'noRecipients',
+          description: 'The email has no to/cc/bcc recipients and no envelope was given.',
+        };
+        continue;
+      }
+      const blob = await this.backend.getBlob(account.accountId, email.blobId);
+      if (!blob) {
+        notCreated[creationId] = {
+          type: 'invalidProperties',
+          description: `Raw message blob "${email.blobId}" does not exist.`,
+        };
+        continue;
+      }
+      try {
+        const submission = await this.backend.submitEmail(account.accountId, {
+          emailId,
+          identityId: identity.id,
+          envelope,
+          message: blob.data,
+        });
+        createdSubmissions.set(creationId, { submissionId: submission.id, emailId });
+        created[creationId] = {
+          id: submission.id,
+          undoStatus: submission.undoStatus,
+          sendAt: submission.sendAt,
+        };
+      } catch (error) {
+        notCreated[creationId] = {
+          type: 'forbiddenToSend',
+          description: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    for (const id of Object.keys((args.update ?? {}) as Record<string, any>)) {
+      notUpdated[id] = {
+        type: 'forbidden',
+        description: 'EmailSubmission updates are not supported.',
       };
-      user.submissions.set(id, submission);
-      created[creationId] = { id, undoStatus: submission.undoStatus, sendAt: submission.sendAt };
+    }
+    for (const id of (args.destroy ?? []) as string[]) {
+      notDestroyed[id] = {
+        type: 'forbidden',
+        description: 'EmailSubmission destroys are not supported.',
+      };
+    }
+
+    const responses: Array<{ name: string; result: Record<string, any>; mutated?: boolean }> = [
+      {
+        name: 'EmailSubmission/set',
+        result: {
+          accountId: account.accountId,
+          oldState: null,
+          newState: '0',
+          created,
+          notCreated,
+          updated: {},
+          notUpdated,
+          destroyed: [],
+          notDestroyed,
+        },
+        mutated: createdSubmissions.size > 0,
+      },
+    ];
+
+    // onSuccessUpdateEmail / onSuccessDestroyEmail (RFC 8621 §7.5): apply an
+    // implicit Email/set for successfully created submissions and append its
+    // response after the EmailSubmission/set response.
+    const resolveSubmissionRef = (reference: string): { submissionId: string; emailId: string } | null => {
+      if (reference.startsWith('#')) {
+        return createdSubmissions.get(reference.slice(1)) ?? null;
+      }
+      for (const entry of createdSubmissions.values()) {
+        if (entry.submissionId === reference) {
+          return entry;
+        }
+      }
+      return null;
+    };
+    const implicitSet: Record<string, any> = { accountId: account.accountId };
+    let hasImplicitSet = false;
+    if (args.onSuccessUpdateEmail && typeof args.onSuccessUpdateEmail === 'object') {
+      const update: Record<string, any> = {};
+      for (const [reference, patch] of Object.entries(
+        args.onSuccessUpdateEmail as Record<string, any>
+      )) {
+        const entry = resolveSubmissionRef(reference);
+        if (entry) {
+          update[entry.emailId] = patch;
+          hasImplicitSet = true;
+        }
+      }
+      implicitSet.update = update;
+    }
+    if (Array.isArray(args.onSuccessDestroyEmail)) {
+      const destroy: string[] = [];
+      for (const reference of args.onSuccessDestroyEmail as string[]) {
+        const entry = resolveSubmissionRef(reference);
+        if (entry) {
+          destroy.push(entry.emailId);
+          hasImplicitSet = true;
+        }
+      }
+      implicitSet.destroy = destroy;
+    }
+    if (hasImplicitSet) {
+      const result = await this.methodEmailSet(account, implicitSet, createdIds);
+      responses.push({
+        name: 'Email/set',
+        result,
+        mutated: result.newState !== result.oldState,
+      });
+    }
+    return responses;
+  }
+
+  /** Uses the client-provided envelope or derives it from the email's addresses. */
+  private resolveEnvelope(
+    specEnvelope: any,
+    identityEmail: string,
+    email: IJmapEmailRecord
+  ): IJmapEnvelope {
+    if (
+      specEnvelope &&
+      typeof specEnvelope === 'object' &&
+      specEnvelope.mailFrom?.email &&
+      Array.isArray(specEnvelope.rcptTo)
+    ) {
+      return {
+        mailFrom: { email: String(specEnvelope.mailFrom.email) },
+        rcptTo: specEnvelope.rcptTo
+          .filter((recipient: any) => typeof recipient?.email === 'string')
+          .map((recipient: any) => ({ email: recipient.email })),
+      };
+    }
+    const recipients = new Set<string>();
+    for (const list of [email.to, email.cc, email.bcc]) {
+      for (const address of list ?? []) {
+        recipients.add(address.email);
+      }
     }
     return {
-      accountId: user.accountId,
-      oldState: String(user.state),
-      newState: String(user.state),
-      created,
-      notCreated,
-      updated: {},
-      notUpdated: {},
-      destroyed: [],
-      notDestroyed: {},
+      mailFrom: { email: email.from?.[0]?.email ?? identityEmail },
+      rcptTo: Array.from(recipients).map((address) => ({ email: address })),
     };
   }
 
   // ======================
-  // internal helpers
+  // upload + download
   // ======================
 
-  private requireUser(username: string): IJmapServerUser {
-    const user = this.users.get(username);
-    if (!user) {
-      throw new Error(`User "${username}" does not exist.`);
+  private async handleUpload(
+    account: IJmapAccountInfo,
+    pathname: string,
+    request: Request
+  ): Promise<Response> {
+    const segments = pathname.split('/').filter((segment) => segment.length > 0);
+    const accountId = decodeURIComponent(segments[2] ?? '');
+    if (accountId !== account.accountId) {
+      return this.problemResponse(404, 'about:blank', 'Unknown account');
     }
-    return user;
-  }
-
-  private createEmailFromSpec(user: IJmapServerUser, spec: Record<string, any>): Record<string, any> {
-    const mailboxIds = spec.mailboxIds as Record<string, boolean> | undefined;
-    if (!mailboxIds || !Object.keys(mailboxIds).length) {
-      throw new Error('Email create requires mailboxIds.');
-    }
-    for (const mailboxId of Object.keys(mailboxIds)) {
-      if (!user.mailboxes.has(mailboxId)) {
-        throw new Error(`Mailbox "${mailboxId}" does not exist.`);
-      }
-    }
-    const id = `email_${++user.idCounter}`;
-    const receivedAt = new Date().toISOString();
-    const bodyValues = (spec.bodyValues ?? {}) as Record<string, { value: string }>;
-    const resolvePart = (part: Record<string, any>): string =>
-      part?.partId != null ? bodyValues[part.partId]?.value ?? '' : '';
-    const textBodyParts = ((spec.textBody ?? []) as Array<Record<string, any>>).map((part) => ({
-      partId: part.partId ?? null,
-      type: part.type ?? 'text/plain',
-      size: resolvePart(part).length,
-    }));
-    const htmlBodyParts = ((spec.htmlBody ?? []) as Array<Record<string, any>>).map((part) => ({
-      partId: part.partId ?? null,
-      type: part.type ?? 'text/html',
-      size: resolvePart(part).length,
-    }));
-    const textValue = textBodyParts.map((part) => bodyValues[part.partId ?? '']?.value ?? '').join('\n');
-
-    const from = (spec.from ?? []) as IJmapEmailAddress[];
-    const to = (spec.to ?? []) as IJmapEmailAddress[];
-    const blobId = `blob_${id}`;
-    const rawLines = [
-      `From: ${from.map((address) => address.email).join(', ')}`,
-      `To: ${to.map((address) => address.email).join(', ')}`,
-      `Subject: ${spec.subject ?? ''}`,
-      `Date: ${receivedAt}`,
-      '',
-      textValue,
-    ];
-    user.blobs.set(blobId, {
-      data: Buffer.from(rawLines.join('\r\n'), 'utf8'),
-      type: 'message/rfc822',
-      name: `${id}.eml`,
-    });
+    const data = new Uint8Array(await request.arrayBuffer());
+    if (data.length > JMAP_SERVER_LIMITS.maxSizeUpload) {
+      return this.limitResponse(
+        400,
+        'maxSizeUpload',
+        `The upload is larger than ${JMAP_SERVER_LIMITS.maxSizeUpload} bytes.`
+      );
+    }
+    const type = request.headers.get('content-type') ?? 'application/octet-stream';
+    const { blobId, size } = await this.backend.uploadBlob(account.accountId, data, type);
+    return this.jsonResponse(200, { accountId: account.accountId, blobId, type, size });
+  }
 
-    const normalizedBodyValues: Record<string, { value: string; isTruncated: boolean }> = {};
-    for (const [partId, bodyValue] of Object.entries(bodyValues)) {
-      normalizedBodyValues[partId] = { value: bodyValue.value ?? '', isTruncated: false };
+  private async handleDownload(
+    account: IJmapAccountInfo,
+    pathname: string,
+    url: URL
+  ): Promise<Response> {
+    // /jmap/download/{accountId}/{blobId}/{name}
+    const segments = pathname.split('/').filter((segment) => segment.length > 0);
+    const accountId = decodeURIComponent(segments[2] ?? '');
+    const blobId = decodeURIComponent(segments[3] ?? '');
+    const name = decodeURIComponent(segments[4] ?? 'blob');
+    if (accountId !== account.accountId) {
+      return this.problemResponse(404, 'about:blank', 'Unknown account');
+    }
+    const blob = await this.backend.getBlob(account.accountId, blobId);
+    if (!blob) {
+      return this.problemResponse(404, 'about:blank', 'Unknown blob');
     }
+    const type = url.searchParams.get('type') ?? blob.type;
+    return new Response(asBodyBytes(blob.data), {
+      status: 200,
+      headers: {
+        'content-type': type,
+        'content-length': String(blob.data.length),
+        'content-disposition': `attachment; filename="${name.replaceAll('"', '')}"`,
+      },
+    });
+  }
 
-    return {
-      id,
-      blobId,
-      threadId: `thread_${id}`,
-      mailboxIds: { ...mailboxIds },
-      keywords: spec.keywords ?? {},
-      size: textValue.length,
-      receivedAt,
-      sentAt: receivedAt,
-      subject: spec.subject ?? null,
-      from,
-      to,
-      cc: spec.cc ?? null,
-      bcc: spec.bcc ?? null,
-      replyTo: spec.replyTo ?? null,
-      hasAttachment: false,
-      preview: textValue.slice(0, 100),
-      bodyValues: normalizedBodyValues,
-      textBody: textBodyParts,
-      htmlBody: htmlBodyParts,
-      attachments: [],
+  // ======================
+  // event source (SSE)
+  // ======================
+
+  private handleEventSource(account: IJmapAccountInfo, url: URL): Response {
+    const typesParam = url.searchParams.get('types') ?? '*';
+    const types =
+      typesParam === '*' || typesParam === ''
+        ? null
+        : new Set(
+            typesParam
+              .split(',')
+              .map((entry) => entry.trim())
+              .filter((entry) => entry.length > 0)
+          );
+    const closeAfterState = url.searchParams.get('closeafter') === 'state';
+    const pingRaw = Number(url.searchParams.get('ping') ?? '0');
+    const pingSeconds =
+      Number.isFinite(pingRaw) && pingRaw > 0 ? Math.max(1, Math.floor(pingRaw)) : 0;
+
+    const state: IEventStreamState = {
+      accountId: account.accountId,
+      types,
+      closeAfterState,
+      controller: null,
+      pingTimer: null,
+      lastSent: new Map(),
+      closed: false,
     };
+    const stream = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        state.controller = controller;
+        controller.enqueue(textEncoder.encode(': jmap event stream\n\n'));
+        if (pingSeconds > 0) {
+          state.pingTimer = setInterval(() => {
+            this.writeToStream(state, `event: ping\ndata: {"interval":${pingSeconds}}\n\n`);
+          }, pingSeconds * 1000);
+        }
+        try {
+          this.registerStream(state);
+        } catch (error) {
+          // a throwing backend.subscribeToChanges must not strand the ping timer
+          this.unregisterStream(state);
+          throw error;
+        }
+      },
+      cancel: () => {
+        this.unregisterStream(state);
+      },
+    });
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+      },
+    });
+  }
+
+  private registerStream(state: IEventStreamState): void {
+    if (!this.changeFeedUnsubscribe) {
+      this.changeFeedUnsubscribe = this.backend.subscribeToChanges((change) => {
+        this.pushStateChange(change.accountId, change.changed);
+      });
+    }
+    this.eventStreams.add(state);
+  }
+
+  private unregisterStream(state: IEventStreamState): void {
+    state.closed = true;
+    if (state.pingTimer) {
+      clearInterval(state.pingTimer);
+      state.pingTimer = null;
+    }
+    this.eventStreams.delete(state);
+    if (!this.eventStreams.size && this.changeFeedUnsubscribe) {
+      this.changeFeedUnsubscribe();
+      this.changeFeedUnsubscribe = null;
+    }
+  }
+
+  private closeStream(state: IEventStreamState): void {
+    this.unregisterStream(state);
+    try {
+      state.controller?.close();
+    } catch {
+      // already closed or errored
+    }
+  }
+
+  private writeToStream(state: IEventStreamState, payload: string): void {
+    if (state.closed || !state.controller) {
+      return;
+    }
+    try {
+      state.controller.enqueue(textEncoder.encode(payload));
+    } catch {
+      this.closeStream(state);
+    }
   }
 
   /**
-   * Applies an Email/set update patch: either whole properties (e.g. keywords)
-   * or JSON-pointer style paths like "keywords/$seen" (RFC 8620 §5.3).
+   * Pushes a StateChange to matching event streams. Per-type states are
+   * deduplicated per stream, so a mutation notified both by the backend
+   * change feed and by the post-request push is delivered once.
    */
-  private applyPatch(email: Record<string, any>, patch: Record<string, any>): void {
-    for (const [path, value] of Object.entries(patch)) {
-      const segments = path.split('/');
-      if (segments.length === 1) {
-        if (value === null) {
-          delete email[path];
-        } else {
-          email[path] = value;
-        }
+  private pushStateChange(accountId: string, changed: Record<string, string>): void {
+    for (const state of Array.from(this.eventStreams)) {
+      if (state.accountId !== accountId) {
         continue;
       }
-      let target = email;
-      for (const segment of segments.slice(0, -1)) {
-        if (typeof target[segment] !== 'object' || target[segment] === null) {
-          target[segment] = {};
+      const filtered: Record<string, string> = {};
+      for (const [type, typeState] of Object.entries(changed)) {
+        if (state.types && !state.types.has(type)) {
+          continue;
+        }
+        if (state.lastSent.get(type) === typeState) {
+          continue;
         }
-        target = target[segment];
+        filtered[type] = typeState;
       }
-      const leaf = segments[segments.length - 1];
-      if (value === null || value === false) {
-        delete target[leaf];
-      } else {
-        target[leaf] = value;
+      if (!Object.keys(filtered).length) {
+        continue;
+      }
+      for (const [type, typeState] of Object.entries(filtered)) {
+        state.lastSent.set(type, typeState);
+      }
+      const stateChange = {
+        '@type': 'StateChange',
+        changed: { [accountId]: filtered },
+      };
+      this.writeToStream(state, `event: state\ndata: ${JSON.stringify(stateChange)}\n\n`);
+      if (state.closeAfterState) {
+        this.closeStream(state);
       }
     }
   }
 
-  /** Increments the account state, records the change, and pushes a StateChange to open event streams. */
-  private bumpState(
-    user: IJmapServerUser,
-    change: { created?: string[]; updated?: string[]; destroyed?: string[] }
-  ): void {
-    user.state += 1;
-    user.changes.push({
-      state: user.state,
-      created: change.created ?? [],
-      updated: change.updated ?? [],
-      destroyed: change.destroyed ?? [],
+  /**
+   * Emits a StateChange after a mutating JMAP request, covering backends
+   * whose change feed only reports out-of-band mutations. Deduplicated
+   * against feed-driven pushes via the per-stream state tracking.
+   */
+  private async pushAfterMutation(account: IJmapAccountInfo): Promise<void> {
+    if (!this.eventStreams.size) {
+      return;
+    }
+    const [emails, mailboxes, threads] = await Promise.all([
+      this.backend.getEmails(account.accountId, []),
+      this.backend.getMailboxes(account.accountId, []),
+      this.backend.getThreads(account.accountId, []),
+    ]);
+    this.pushStateChange(account.accountId, {
+      Email: emails.state,
+      Thread: threads.state,
+      Mailbox: mailboxes.state,
     });
-    this.notifyStateChange(user);
   }
 
-  private notifyStateChange(user: IJmapServerUser): void {
-    const stateChange = {
-      '@type': 'StateChange',
-      changed: {
-        [user.accountId]: {
-          Email: String(user.state),
-          Mailbox: String(user.state),
-          Thread: String(user.state),
-        },
-      },
-    };
-    const payload = `event: state\ndata: ${JSON.stringify(stateChange)}\n\n`;
-    for (const [response, streamUser] of this.eventStreams) {
-      if (streamUser !== user) {
-        continue;
+  // ======================
+  // node req/res adapter
+  // ======================
+
+  private async handleNodeRequest(
+    req: plugins.http.IncomingMessage,
+    res: plugins.http.ServerResponse
+  ): Promise<void> {
+    try {
+      const method = (req.method ?? 'GET').toUpperCase();
+      let body: Uint8Array | undefined;
+      if (method !== 'GET' && method !== 'HEAD') {
+        const chunks: Buffer[] = [];
+        let total = 0;
+        // Cap request buffering at maxSizeUpload; larger requests never make
+        // it to fetchHandler (which enforces the JMAP per-endpoint limits).
+        const maxBuffered = JMAP_SERVER_LIMITS.maxSizeUpload + 1;
+        for await (const chunk of req) {
+          const buffer = chunk as Buffer;
+          total += buffer.length;
+          if (total > maxBuffered) {
+            res.writeHead(413, { 'content-type': 'application/problem+json' });
+            res.end(
+              JSON.stringify({
+                type: 'urn:ietf:params:jmap:error:limit',
+                limit: 'maxSizeUpload',
+                status: 413,
+                detail: 'Request body too large.',
+              })
+            );
+            req.destroy();
+            return;
+          }
+          chunks.push(buffer);
+        }
+        body = Buffer.concat(chunks);
+      }
+
+      const headers = new Headers();
+      const skippedHeaders = new Set([
+        'connection',
+        'content-length',
+        'expect',
+        'keep-alive',
+        'proxy-connection',
+        'transfer-encoding',
+        'upgrade',
+      ]);
+      for (const [key, value] of Object.entries(req.headers)) {
+        if (value === undefined || skippedHeaders.has(key.toLowerCase())) {
+          continue;
+        }
+        headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+      }
+      const host = req.headers.host ?? '127.0.0.1';
+      const request = new Request(`http://${host}${req.url ?? '/'}`, {
+        method,
+        headers,
+        body: body ? asBodyBytes(body) : undefined,
+      });
+
+      const response = await this.fetchHandler(request);
+
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+      res.writeHead(response.status, responseHeaders);
+      if (!response.body) {
+        res.end();
+        return;
       }
+      const reader = response.body.getReader();
+      let clientClosed = false;
+      res.on('close', () => {
+        clientClosed = true;
+        // Cancelling the reader triggers the stream's cancel handler, which
+        // releases any per-stream resources (SSE registration, ping timer).
+        void reader.cancel().catch(() => {});
+      });
       try {
-        response.write(payload);
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done || clientClosed || res.destroyed) {
+            break;
+          }
+          res.write(value);
+        }
       } catch {
-        this.eventStreams.delete(response);
+        // stream cancelled or connection gone
+      }
+      if (!res.destroyed) {
+        res.end();
       }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'content-type': 'application/problem+json' });
+      }
+      res.end(JSON.stringify({ type: 'about:blank', status: 500, detail: message }));
     }
   }
+
+  // ======================
+  // shared validators + responses
+  // ======================
+
+  private validateProperties(
+    requested: any,
+    known: Set<string>
+  ): string[] | null {
+    if (requested === null || requested === undefined) {
+      return null;
+    }
+    if (!Array.isArray(requested)) {
+      throw new JmapServerMethodError('invalidArguments', 'properties must be an array or null.');
+    }
+    for (const property of requested) {
+      if (typeof property !== 'string' || !known.has(property)) {
+        throw new JmapServerMethodError(
+          'invalidArguments',
+          `Unknown property "${String(property)}".`
+        );
+      }
+    }
+    return requested.includes('id') ? requested : ['id', ...requested];
+  }
+
+  private projectObject(source: Record<string, any>, properties: string[]): Record<string, any> {
+    const projected: Record<string, any> = {};
+    for (const property of properties) {
+      projected[property] = source[property] === undefined ? null : source[property];
+    }
+    return projected;
+  }
+
+  private validatePosition(args: Record<string, any>): number {
+    if (args.position === undefined || args.position === null) {
+      return 0;
+    }
+    if (!Number.isInteger(args.position) || args.position < 0) {
+      throw new JmapServerMethodError(
+        'invalidArguments',
+        'position must be a non-negative integer.'
+      );
+    }
+    return args.position as number;
+  }
+
+  private validateChangesArgs(args: Record<string, any>): {
+    sinceState: string;
+    maxChanges?: number;
+  } {
+    if (typeof args.sinceState !== 'string') {
+      throw new JmapServerMethodError('invalidArguments', 'sinceState is required.');
+    }
+    let maxChanges: number | undefined;
+    if (args.maxChanges !== undefined && args.maxChanges !== null) {
+      if (!Number.isInteger(args.maxChanges) || args.maxChanges <= 0) {
+        throw new JmapServerMethodError(
+          'invalidArguments',
+          'maxChanges must be a positive integer.'
+        );
+      }
+      maxChanges = args.maxChanges as number;
+    }
+    return { sinceState: args.sinceState, maxChanges };
+  }
+
+  private jsonResponse(status: number, body: unknown): Response {
+    return new Response(JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    });
+  }
+
+  private problemResponse(
+    status: number,
+    type: string,
+    detail: string,
+    extraHeaders: Record<string, string> = {}
+  ): Response {
+    return new Response(JSON.stringify({ type, status, detail }), {
+      status,
+      headers: { 'content-type': 'application/problem+json', ...extraHeaders },
+    });
+  }
+
+  private limitResponse(status: number, limit: string, detail: string): Response {
+    return new Response(
+      JSON.stringify({ type: 'urn:ietf:params:jmap:error:limit', limit, status, detail }),
+      { status, headers: { 'content-type': 'application/problem+json' } }
+    );
+  }
 }