@push.rocks/smartjmap 1.0.0 → 2.1.0

package/ts/classes.jmapserver.ts

@@ -1,69 +1,173 @@
-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 * as plugins from "./smartjmap.plugins.js";
+import {
+  type IJmapEmailBodyValue,
+  JMAP_CORE_CAPABILITY,
+  JMAP_MAIL_CAPABILITY,
+  JMAP_SUBMISSION_CAPABILITY,
+  type TJmapMethodResponse,
+} from "./classes.jmapclient.js";
+import {
+  type IJmapAccountInfo,
+  type IJmapBlobUploadStream,
+  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;
-}
+/**
+ * Semantic capability marker for the bounded streaming-upload server surface.
+ * Consumers must check this exact value before relying on streaming backend
+ * uploads, upload concurrency limits, Bearer-only challenges, or error mapping.
+ */
+export const JMAP_SERVER_STREAMING_API_VERSION = 1 as const;
 
-export interface IJmapServerChangeEntry {
-  state: number;
-  created: string[];
-  updated: string[];
-  destroyed: 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>;
+  /**
+   * WWW-Authenticate challenges advertised on a 401 response. Defaults to
+   * Bearer and Basic for the built-in registry. Custom authenticators should
+   * list only the schemes they actually accept.
+   */
+  authenticationChallenges?: string[];
+  /**
+   * 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;
+  /** Overrides for the limits advertised in the JMAP session and enforced by this server. */
+  limits?: Partial<IJmapServerLimits>;
+  /**
+   * Process-wide upload ceiling across authenticated principals. Must be at
+   * least the advertised per-principal maxConcurrentUpload value.
+   */
+  maxConcurrentUploadServer?: number;
+  /** Maps backend upload failures to an RFC 7807 response instead of a generic 500. */
+  mapUploadError?: (error: unknown) => IJmapUploadProblem | null | undefined;
 }
 
-export interface IJmapServerIdentity {
-  id: string;
-  name: string;
-  email: string;
-  mayDelete: boolean;
+export interface IJmapServerLimits {
+  maxSizeUpload: number;
+  maxConcurrentUpload: number;
+  maxSizeRequest: number;
+  maxConcurrentRequests: number;
+  maxCallsInRequest: number;
+  maxObjectsInGet: number;
+  maxObjectsInSet: number;
 }
 
-export interface IJmapServerSubmission {
-  id: string;
-  emailId: string;
-  identityId: string;
-  undoStatus: string;
-  sendAt: string;
+export interface IJmapUploadProblem {
+  status: number;
+  type?: string;
+  detail: string;
+  limit?: string;
+  retryAfterSeconds?: number;
 }
 
-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;
-}
+/** The advertised — and enforced — RFC 8620 core limits. */
+export const JMAP_SERVER_LIMITS: IJmapServerLimits = {
+  maxSizeUpload: 50_000_000,
+  maxConcurrentUpload: 4,
+  maxSizeRequest: 10_000_000,
+  maxConcurrentRequests: 4,
+  maxCallsInRequest: 16,
+  maxObjectsInGet: 500,
+  maxObjectsInSet: 500,
+};
 
-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 }>;
-}
+/** The session object never changes at runtime, so its state is constant. */
+const SESSION_STATE = "0";
+
+/** 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);
+
+const MAILBOX_PROPERTIES = [
+  "id",
+  "name",
+  "parentId",
+  "role",
+  "sortOrder",
+  "totalEmails",
+  "unreadEmails",
+  "totalThreads",
+  "unreadThreads",
+  "myRights",
+  "isSubscribed",
+];
+const KNOWN_MAILBOX_PROPERTIES = new Set(MAILBOX_PROPERTIES);
+
+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,948 +176,2472 @@ class JmapServerMethodError extends Error {
   }
 }
 
+class JmapRequestBodyError extends Error {
+  constructor(
+    public readonly reason: "invalidLength" | "lengthMismatch" | "tooLarge",
+  ) {
+    super(reason);
+  }
+}
+
+/** 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 readonly limits: IJmapServerLimits;
+  private readonly maxConcurrentUploadServer: number;
+  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 cleanupErrors: unknown[] = [];
+  private activeApiRequests = 0;
+  private activeUploadRequests = 0;
+  private activeUploadsByPrincipal = new Map<string, number>();
+  private activeNodeRequests = new Set<Promise<void>>();
+  private nodeRequestControllers = new Set<AbortController>();
+  private stopping = false;
+  private authenticationChallenges: string;
 
-  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();
+    const authenticationChallenges = options.authenticationChallenges ?? [
+      'Bearer realm="jmap"',
+      'Basic realm="jmap"',
+    ];
+    if (
+      authenticationChallenges.length === 0 ||
+      authenticationChallenges.some((challenge) =>
+        typeof challenge !== "string" || !challenge.trim() ||
+        /[\r\n]/.test(challenge)
+      )
+    ) {
+      throw new Error(
+        "authenticationChallenges must contain safe non-empty challenge values.",
+      );
+    }
+    this.authenticationChallenges = authenticationChallenges
+      .map((value) => value.trim())
+      .join(", ");
+    this.limits = { ...JMAP_SERVER_LIMITS, ...options.limits };
+    for (const [name, value] of Object.entries(this.limits)) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`JMAP limit ${name} must be a positive safe integer.`);
+      }
+    }
+    this.maxConcurrentUploadServer = options.maxConcurrentUploadServer ??
+      this.limits.maxConcurrentUpload;
+    if (
+      !Number.isSafeInteger(this.maxConcurrentUploadServer) ||
+      this.maxConcurrentUploadServer < this.limits.maxConcurrentUpload
+    ) {
+      throw new Error(
+        "maxConcurrentUploadServer must be a safe integer at least as large as maxConcurrentUpload.",
+      );
+    }
   }
 
   // ======================
-  // 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.");
+    }
+    this.stopping = false;
+    const server = plugins.http.createServer((req, res) => {
+      if (this.stopping) {
+        res.writeHead(503, {
+          "content-type": "application/problem+json",
+          "connection": "close",
+        });
+        res.end(JSON.stringify({
+          type: "about:blank",
+          status: 503,
+          detail: "JMAP server is shutting down.",
+        }));
+        return;
+      }
+      const requestAbortController = new AbortController();
+      this.nodeRequestControllers.add(requestAbortController);
+      let requestTask!: Promise<void>;
+      requestTask = this.handleNodeRequest(req, res, requestAbortController)
+        .finally(() => {
+          this.nodeRequestControllers.delete(requestAbortController);
+          this.activeNodeRequests.delete(requestTask);
+        });
+      this.activeNodeRequests.add(requestTask);
+      void requestTask;
+    });
+    const onConnection = (socket: plugins.net.Socket): void => {
+      this.sockets.add(socket);
+      socket.on("close", () => {
+        this.sockets.delete(socket);
+      });
+    };
+    server.on("connection", onConnection);
+    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;
+      const onStartupError = (error: Error): void => {
+        server.off("listening", onListening);
+        server.off("connection", onConnection);
+        if (this.httpServer === server) {
+          this.httpServer = null;
+        }
+        try {
+          server.close(() => undefined);
+        } catch {
+          // The failed listener never reached the listening state.
+        }
+        reject(error);
+      };
+      const onListening = (): void => {
+        server.off("error", onStartupError);
+        server.on("error", (error) => {
+          this.cleanupErrors.push(error);
+        });
+        const address = server.address();
+        const boundPort = typeof address === "object" && address
+          ? address.port
+          : port;
         resolve(boundPort);
-      });
+      };
+      server.once("error", onStartupError);
+      server.once("listening", onListening);
+      server.listen(port);
     });
   }
 
-  /** 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> {
+    this.stopping = true;
+    const server = this.httpServer;
+    this.httpServer = null;
+    const listenerClosed = server
+      ? new Promise<void>((resolve) => {
+        try {
+          server.close(() => resolve());
+        } catch {
+          resolve();
+        }
+      })
+      : Promise.resolve();
+    for (const stream of Array.from(this.eventStreams)) {
+      this.closeStream(stream);
+    }
+    for (const controller of this.nodeRequestControllers) {
+      if (!controller.signal.aborted) {
+        controller.abort(new Error("JMAP server is shutting down."));
       }
     }
-    this.eventStreams.clear();
     for (const socket of this.sockets) {
       socket.destroy();
     }
     this.sockets.clear();
-    return new Promise((resolve) => {
-      this.server.close(() => {
-        resolve();
-      });
-    });
+    await listenerClosed;
+    while (this.activeNodeRequests.size) {
+      await Promise.allSettled([...this.activeNodeRequests]);
+    }
+    if (this.cleanupErrors.length) {
+      const errors = this.cleanupErrors.splice(0);
+      throw new AggregateError(errors, "JmapServer cleanup failed");
+    }
   }
 
   // ======================
-  // 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, {
-          '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' })
+      const principal = await this.authenticatePrincipal(request);
+      if (!principal) {
+        await this.cancelRequestBody(request, "authentication rejected");
+        return this.problemResponse(
+          401,
+          "about:blank",
+          "Authentication required",
+          {
+            "www-authenticate": this.authenticationChallenges,
+          },
+        );
+      }
+      const account = await this.backend.resolveAccount(principal);
+      if (!account) {
+        await this.cancelRequestBody(request, "account rejected");
+        return this.problemResponse(
+          403,
+          "about:blank",
+          "No account for this principal",
         );
-        return;
       }
 
-      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, principal, 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);
+      }
+      await this.cancelRequestBody(request, "route rejected");
+      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;
     }
-    const spaceIndex = header.indexOf(' ');
+    const spaceIndex = header.indexOf(" ");
     if (spaceIndex === -1) {
       return null;
     }
     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;
+    if (scheme === "bearer") {
+      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');
-      const colonIndex = decoded.indexOf(':');
+    if (scheme === "basic") {
+      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]: {
+          ...this.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: this.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.',
-        })
+  private buildUrl(path: string): string {
+    const base = this.options.baseUrl;
+    return base ? `${base.replace(/\/+$/, "")}${path}` : path;
+  }
+
+  // ======================
+  // api endpoint
+  // ======================
+
+  private async handleApi(
+    account: IJmapAccountInfo,
+    request: Request,
+  ): Promise<Response> {
+    if (this.activeApiRequests >= this.limits.maxConcurrentRequests) {
+      await this.cancelRequestBody(
+        request,
+        "request concurrency limit reached",
       );
-      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 this.limitResponse(
+        429,
+        "maxConcurrentRequests",
+        "Too many concurrent requests.",
       );
-      return;
     }
-
-    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];
+    this.activeApiRequests++;
+    try {
+      let bytes: Uint8Array;
       try {
-        const result = this.dispatchMethod(user, methodName, args ?? {}, createdIds);
-        methodResponses.push([methodName, result, callId]);
+        bytes = await this.readRequestBodyBounded(
+          request,
+          this.limits.maxSizeRequest,
+        );
       } 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]);
+        if (error instanceof JmapRequestBodyError) {
+          if (error.reason === "invalidLength") {
+            return this.problemResponse(
+              400,
+              "about:blank",
+              "Invalid Content-Length header.",
+            );
+          }
+          return this.limitResponse(
+            400,
+            "maxSizeRequest",
+            `The request is larger than ${this.limits.maxSizeRequest} bytes.`,
+          );
         }
+        throw error;
+      }
+      let parsed: any;
+      try {
+        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 > this.limits.maxCallsInRequest) {
+        return this.limitResponse(
+          400,
+          "maxCallsInRequest",
+          `The request has more than ${this.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>,
-    createdIds: Map<string, string>
-  ): Record<string, any> {
+    using: Set<string>,
+    createdIds: Map<string, string>,
+  ): 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;
-      case 'Mailbox/get':
-        return this.methodMailboxGet(user, args);
-      case 'Mailbox/query':
-        return this.methodMailboxQuery(user, args);
-      case 'Email/get':
-        return this.methodEmailGet(user, args);
-      case 'Email/query':
-        return this.methodEmailQuery(user, args);
-      case 'Email/changes':
-        return this.methodEmailChanges(user, args);
-      case 'Email/set':
-        return this.methodEmailSet(user, args, createdIds);
-      case 'Identity/get':
-        return this.methodIdentityGet(user);
-      case 'EmailSubmission/set':
-        return this.methodEmailSubmissionSet(user, args, createdIds);
+      case "Core/echo":
+        return [{ name: methodName, result: args }];
+      case "Mailbox/get":
+        return [{
+          name: methodName,
+          result: await this.methodMailboxGet(account, args),
+        }];
+      case "Mailbox/query":
+        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 [{
+          name: methodName,
+          result: await this.methodEmailGet(account, args),
+        }];
+      case "Email/query":
+        return [{
+          name: methodName,
+          result: await this.methodEmailQuery(account, args),
+        }];
+      case "Email/changes":
+        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 [{
+          name: methodName,
+          result: await this.methodIdentityGet(account, args),
+        }];
+      case "EmailSubmission/set":
+        return this.methodEmailSubmissionSet(account, args, createdIds);
       default:
-        throw new JmapServerMethodError('unknownMethod', `Unknown method "${methodName}".`);
+        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 > this.limits.maxObjectsInGet) {
+        throw new JmapServerMethodError(
+          "requestTooLarge",
+          `ids exceeds maxObjectsInGet (${this.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') {
+  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.",
+      );
+    }
+    for (const key of Object.keys(filter)) {
+      if (!["role", "name", "parentId"].includes(key)) {
+        throw new JmapServerMethodError(
+          "unsupportedFilter",
+          `Mailbox filter condition "${key}" is not supported.`,
+        );
+      }
+    }
+    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.`,
+        );
+      }
+    }
+    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.name === 'string') {
+    if (typeof filter.name === "string") {
       mailboxes = mailboxes.filter((mailbox) => mailbox.name === filter.name);
     }
-    const ids = mailboxes.map((mailbox) => mailbox.id);
-    return {
-      accountId: user.accountId,
-      queryState: String(user.state),
+    if ("parentId" in filter) {
+      mailboxes = mailboxes.filter((mailbox) =>
+        mailbox.parentId === filter.parentId
+      );
+    }
+    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 = this.validatePosition(args);
+    let ids = mailboxes.map((mailbox) => mailbox.id).slice(position);
+    if (typeof args.limit === "number") {
+      ids = ids.slice(0, args.limit);
+    }
+    const response: Record<string, any> = {
+      accountId: account.accountId,
+      queryState: result.state,
       canCalculateChanges: false,
-      position: 0,
+      position,
       ids,
-      total: ids.length,
     };
+    if (args.calculateTotal === true) {
+      response.total = mailboxes.length;
+    }
+    return response;
   }
 
-  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.');
+  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 mailbox changes since state "${sinceState}".`,
+      );
     }
-    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);
-      }
+    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.",
+      );
+    }
+    if (args.ids.length > this.limits.maxObjectsInGet) {
+      throw new JmapServerMethodError(
+        "requestTooLarge",
+        `ids exceeds maxObjectsInGet (${this.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,
-      state: String(user.state),
-      list,
-      notFound,
+      accountId: account.accountId,
+      state: result.state,
+      list: result.list,
+      notFound: result.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]);
-    }
-    if (typeof filter.subject === 'string') {
-      emails = emails.filter((email) =>
-        String(email.subject ?? '').toLowerCase().includes(filter.subject.toLowerCase())
+  // ======================
+  // email methods
+  // ======================
+
+  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 (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 (!Array.isArray(args.ids)) {
+      throw new JmapServerMethodError(
+        "invalidArguments",
+        "Email/get requires an ids array.",
       );
     }
-    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 position = typeof args.position === 'number' ? args.position : 0;
-    let ids = emails.map((email) => email.id as string).slice(position);
-    const total = emails.length;
-    if (typeof args.limit === 'number') {
-      ids = ids.slice(0, args.limit);
+    if (args.ids.length > this.limits.maxObjectsInGet) {
+      throw new JmapServerMethodError(
+        "requestTooLarge",
+        `ids exceeds maxObjectsInGet (${this.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: user.accountId,
-      queryState: String(user.state),
-      canCalculateChanges: false,
-      position,
-      ids,
-      total,
+      accountId: account.accountId,
+      state: result.state,
+      list,
+      notFound: result.notFound,
     };
   }
 
-  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) {
-      throw new JmapServerMethodError(
-        'cannotCalculateChanges',
-        `Cannot calculate changes since state "${args.sinceState}".`
-      );
+  /** 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);
+      }
     }
-    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;
+    if (args.fetchTextBodyValues === true) {
+      for (const part of record.textBody) {
+        if (part.partId != null) {
+          wanted.add(part.partId);
+        }
       }
-      for (const id of entry.created) {
-        created.add(id);
+    }
+    if (args.fetchHTMLBodyValues === true) {
+      for (const part of record.htmlBody) {
+        if (part.partId != null) {
+          wanted.add(part.partId);
+        }
       }
-      for (const id of entry.updated) {
-        updated.add(id);
+    }
+    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;
       }
-      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);
+      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;
         }
-        updated.delete(id);
       }
+      result[partId] = { value, isTruncated };
     }
-    for (const id of created) {
-      updated.delete(id);
+    return result;
+  }
+
+  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.",
+      );
     }
-    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),
+    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 methodEmailSet(
-    user: IJmapServerUser,
+  private async methodEmailChanges(
+    account: IJmapAccountInfo,
     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[] = [];
-
-    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 };
-      }
+  ): 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 };
+  }
 
-    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.` };
-        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 };
+  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 >
+        this.limits.maxObjectsInSet
+    ) {
+      throw new JmapServerMethodError(
+        "requestTooLarge",
+        `The set request exceeds maxObjectsInSet (${this.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}".`,
+        );
       }
     }
 
-    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.` };
+    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 (changedCreated.length || changedUpdated.length || changedDestroyed.length) {
-      this.bumpState(user, {
-        created: changedCreated,
-        updated: changedUpdated,
-        destroyed: changedDestroyed,
-      });
+    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> {
+  /**
+   * 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: user.accountId,
-      state: '0',
-      list: user.identities,
-      notFound: [],
+      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> {
+    createdIds: Map<string, string>,
+  ): Promise<
+    Array<{ name: string; result: Record<string, any>; mutated?: boolean }>
+  > {
     const created: Record<string, any> = {};
-    const notCreated: Record<string, any> = {};
-    for (const [creationId, spec] of Object.entries((args.create ?? {}) as 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('#')) {
+      if (typeof emailId === "string" && emailId.startsWith("#")) {
         const resolved = createdIds.get(emailId.slice(1));
         if (!resolved) {
           notCreated[creationId] = {
-            type: 'invalidProperties',
+            type: "invalidProperties",
             description: `Unknown creation id reference "${emailId}".`,
           };
           continue;
         }
         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',
+          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',
+          type: "invalidProperties",
           description: `Identity "${spec.identityId}" does not exist.`,
         };
         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 cancelRequestBody(
+    request: Request,
+    reason: string,
+  ): Promise<void> {
+    try {
+      if (request.body && !request.body.locked) {
+        await request.body.cancel(reason);
+      }
+    } catch {
+      // The runtime or peer may already have closed the transport stream.
     }
-    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 normalizedBodyValues: Record<string, { value: string; isTruncated: boolean }> = {};
-    for (const [partId, bodyValue] of Object.entries(bodyValues)) {
-      normalizedBodyValues[partId] = { value: bodyValue.value ?? '', isTruncated: false };
+  private async readRequestBodyBounded(
+    request: Request,
+    maxBytes: number,
+  ): Promise<Uint8Array> {
+    const declaredLength = request.headers.get("content-length");
+    if (declaredLength !== null) {
+      if (
+        !/^\d+$/.test(declaredLength) ||
+        !Number.isSafeInteger(Number(declaredLength))
+      ) {
+        await this.cancelRequestBody(request, "invalid content length");
+        throw new JmapRequestBodyError("invalidLength");
+      }
+      if (Number(declaredLength) > maxBytes) {
+        await this.cancelRequestBody(request, "request body too large");
+        throw new JmapRequestBodyError("tooLarge");
+      }
+    }
+    if (!request.body) {
+      return new Uint8Array();
     }
 
+    const reader = request.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+          await reader.cancel("request body too large");
+          throw new JmapRequestBodyError("tooLarge");
+        }
+        chunks.push(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+
+    const data = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      data.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return data;
+  }
+
+  private createExactUploadBody(
+    request: Request,
+    expectedSize: number,
+  ): {
+    stream: ReadableStream<Uint8Array>;
+    signal: AbortSignal;
+    isComplete(): boolean;
+    cancel(reason: unknown): Promise<void>;
+    dispose(): void;
+  } {
+    const abortController = new AbortController();
+    let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+    let bytesRead = 0;
+    let complete = false;
+    let cancelled = false;
+
+    const cancel = async (reason: unknown): Promise<void> => {
+      if (cancelled || complete) return;
+      cancelled = true;
+      abortController.abort(reason);
+      try {
+        if (reader) {
+          await reader.cancel(reason);
+        } else if (request.body && !request.body.locked) {
+          await request.body.cancel(reason);
+        }
+      } catch {
+        // The peer or consumer may already have closed the stream.
+      }
+    };
+    const onRequestAbort = (): void => {
+      void cancel(request.signal.reason ?? new Error("Request aborted."));
+    };
+    request.signal.addEventListener("abort", onRequestAbort, { once: true });
+    if (request.signal.aborted) onRequestAbort();
+
+    const stream = new ReadableStream<Uint8Array>({
+      async pull(controller) {
+        if (cancelled) {
+          controller.error(
+            abortController.signal.reason ?? new Error("Upload cancelled."),
+          );
+          return;
+        }
+        if (!request.body) {
+          if (expectedSize === 0) {
+            complete = true;
+            controller.close();
+          } else {
+            const error = new JmapRequestBodyError("lengthMismatch");
+            abortController.abort(error);
+            controller.error(error);
+          }
+          return;
+        }
+        reader ??= request.body.getReader();
+        const { done, value } = await reader.read();
+        if (done) {
+          if (bytesRead !== expectedSize) {
+            const error = new JmapRequestBodyError("lengthMismatch");
+            abortController.abort(error);
+            controller.error(error);
+            return;
+          }
+          complete = true;
+          controller.close();
+          return;
+        }
+        bytesRead += value.byteLength;
+        if (bytesRead > expectedSize) {
+          const error = new JmapRequestBodyError("lengthMismatch");
+          await cancel(error);
+          controller.error(error);
+          return;
+        }
+        controller.enqueue(value);
+      },
+      cancel,
+    }, { highWaterMark: 0 });
+
     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: [],
+      stream,
+      signal: abortController.signal,
+      isComplete: () => complete,
+      cancel,
+      dispose: () =>
+        request.signal.removeEventListener("abort", onRequestAbort),
+    };
+  }
+
+  private mappedUploadErrorResponse(error: unknown): Response | null {
+    const problem = this.options.mapUploadError?.(error);
+    if (!problem) return null;
+    if (
+      !Number.isInteger(problem.status) || problem.status < 400 ||
+      problem.status > 599 ||
+      !problem.detail
+    ) {
+      throw new Error("mapUploadError returned an invalid upload problem.");
+    }
+    const body = {
+      type: problem.type ?? "about:blank",
+      status: problem.status,
+      detail: problem.detail,
+      ...(problem.limit ? { limit: problem.limit } : {}),
+    };
+    const headers: Record<string, string> = {
+      "content-type": "application/problem+json",
+    };
+    if (problem.retryAfterSeconds !== undefined) {
+      headers["retry-after"] = String(problem.retryAfterSeconds);
+    }
+    return new Response(JSON.stringify(body), {
+      status: problem.status,
+      headers,
+    });
+  }
+
+  private requestBodyErrorResponse(
+    error: JmapRequestBodyError,
+    limit: string,
+  ): Response {
+    if (error.reason === "invalidLength") {
+      return this.problemResponse(
+        400,
+        "about:blank",
+        "Invalid Content-Length header.",
+      );
+    }
+    if (error.reason === "lengthMismatch") {
+      return this.problemResponse(
+        400,
+        "about:blank",
+        "The request body does not match Content-Length.",
+      );
+    }
+    const maximum = limit === "maxSizeUpload"
+      ? this.limits.maxSizeUpload
+      : this.limits.maxSizeRequest;
+    return this.limitResponse(
+      400,
+      limit,
+      `The request is larger than ${maximum} bytes.`,
+    );
+  }
+
+  private async handleStreamingUpload(
+    account: IJmapAccountInfo,
+    request: Request,
+    type: string,
+  ): Promise<Response> {
+    const contentLength = request.headers.get("content-length");
+    if (contentLength === null) {
+      await this.cancelRequestBody(request, "content length required");
+      return this.problemResponse(
+        411,
+        "about:blank",
+        "Content-Length is required.",
+      );
+    }
+    if (
+      !/^\d+$/.test(contentLength) ||
+      !Number.isSafeInteger(Number(contentLength))
+    ) {
+      await this.cancelRequestBody(request, "invalid content length");
+      return this.problemResponse(
+        400,
+        "about:blank",
+        "Invalid Content-Length header.",
+      );
+    }
+    const declaredSize = Number(contentLength);
+    if (declaredSize > this.limits.maxSizeUpload) {
+      await this.cancelRequestBody(request, "request body too large");
+      return this.limitResponse(
+        400,
+        "maxSizeUpload",
+        `The upload is larger than ${this.limits.maxSizeUpload} bytes.`,
+      );
+    }
+    if (!request.body && declaredSize !== 0) {
+      return this.problemResponse(
+        400,
+        "about:blank",
+        "The request body does not match Content-Length.",
+      );
+    }
+
+    const body = this.createExactUploadBody(request, declaredSize);
+    const upload: IJmapBlobUploadStream = {
+      stream: body.stream,
+      size: declaredSize,
+      type,
+      signal: body.signal,
+    };
+    try {
+      const result = await this.backend.uploadBlobStream!(
+        account.accountId,
+        upload,
+      );
+      if (!body.isComplete()) {
+        await body.cancel(new JmapRequestBodyError("lengthMismatch"));
+        return this.problemResponse(
+          400,
+          "about:blank",
+          "The upload backend did not consume the exact request body.",
+        );
+      }
+      if (result.size !== declaredSize) {
+        throw new Error(
+          `Upload backend reported ${result.size} bytes for a ${declaredSize}-byte request.`,
+        );
+      }
+      return this.jsonResponse(200, {
+        accountId: account.accountId,
+        blobId: result.blobId,
+        type,
+        size: result.size,
+      });
+    } catch (error) {
+      await body.cancel(error);
+      if (error instanceof JmapRequestBodyError) {
+        return this.requestBodyErrorResponse(error, "maxSizeUpload");
+      }
+      const mapped = this.mappedUploadErrorResponse(error);
+      if (mapped) return mapped;
+      throw error;
+    } finally {
+      body.dispose();
+    }
+  }
+
+  private async handleUpload(
+    account: IJmapAccountInfo,
+    principal: TJmapPrincipal,
+    pathname: string,
+    request: Request,
+  ): Promise<Response> {
+    const segments = pathname.split("/").filter((segment) =>
+      segment.length > 0
+    );
+    const accountId = decodeURIComponent(segments[2] ?? "");
+    if (accountId !== account.accountId) {
+      await this.cancelRequestBody(request, "unknown account");
+      return this.problemResponse(404, "about:blank", "Unknown account");
+    }
+
+    const principalUploads =
+      this.activeUploadsByPrincipal.get(principal.username) ?? 0;
+    if (
+      principalUploads >= this.limits.maxConcurrentUpload ||
+      this.activeUploadRequests >= this.maxConcurrentUploadServer
+    ) {
+      await this.cancelRequestBody(request, "upload concurrency limit reached");
+      return this.limitResponse(
+        429,
+        "maxConcurrentUpload",
+        "Too many concurrent uploads.",
+      );
+    }
+
+    this.activeUploadRequests++;
+    this.activeUploadsByPrincipal.set(principal.username, principalUploads + 1);
+    try {
+      const type = request.headers.get("content-type") ??
+        "application/octet-stream";
+      if (typeof this.backend.uploadBlobStream === "function") {
+        return await this.handleStreamingUpload(account, request, type);
+      }
+      let data: Uint8Array;
+      try {
+        data = await this.readRequestBodyBounded(
+          request,
+          this.limits.maxSizeUpload,
+        );
+      } catch (error) {
+        if (error instanceof JmapRequestBodyError) {
+          return this.requestBodyErrorResponse(error, "maxSizeUpload");
+        }
+        throw error;
+      }
+      try {
+        const { blobId, size } = await this.backend.uploadBlob(
+          account.accountId,
+          data,
+          type,
+        );
+        return this.jsonResponse(200, {
+          accountId: account.accountId,
+          blobId,
+          type,
+          size,
+        });
+      } catch (error) {
+        const mapped = this.mappedUploadErrorResponse(error);
+        if (mapped) return mapped;
+        throw error;
+      }
+    } finally {
+      this.activeUploadRequests--;
+      const remainingPrincipalUploads =
+        (this.activeUploadsByPrincipal.get(principal.username) ?? 1) - 1;
+      if (remainingPrincipalUploads <= 0) {
+        this.activeUploadsByPrincipal.delete(principal.username);
+      } else {
+        this.activeUploadsByPrincipal.set(
+          principal.username,
+          remainingPrincipalUploads,
+        );
+      }
+    }
+  }
+
+  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('"', "")
+        }"`,
+      },
+    });
+  }
+
+  // ======================
+  // 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) {
+      const unsubscribe = this.changeFeedUnsubscribe;
+      this.changeFeedUnsubscribe = null;
+      try {
+        unsubscribe();
+      } catch (error) {
+        this.cleanupErrors.push(error);
+      }
+    }
+  }
+
+  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),
-        },
+  // ======================
+  // node req/res adapter
+  // ======================
+
+  private nodeRequestBody(
+    req: plugins.http.IncomingMessage,
+  ): ReadableStream<Uint8Array> {
+    let closed = false;
+    let cleanup = (): void => {};
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        req.pause();
+        const onData = (chunk: Buffer): void => {
+          if (closed) return;
+          controller.enqueue(
+            new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength),
+          );
+          if ((controller.desiredSize ?? 0) <= 0) req.pause();
+        };
+        const onEnd = (): void => {
+          if (closed) return;
+          closed = true;
+          cleanup();
+          controller.close();
+        };
+        const onAborted = (): void => {
+          if (closed) return;
+          closed = true;
+          cleanup();
+          controller.error(new Error("Request body stream was aborted."));
+        };
+        const onError = (error: Error): void => {
+          if (closed) return;
+          closed = true;
+          cleanup();
+          controller.error(error);
+        };
+        cleanup = () => {
+          req.off("data", onData);
+          req.off("end", onEnd);
+          req.off("aborted", onAborted);
+          req.off("error", onError);
+        };
+        req.on("data", onData);
+        req.once("end", onEnd);
+        req.once("aborted", onAborted);
+        req.once("error", onError);
+      },
+      pull() {
+        if (!closed) req.resume();
       },
+      cancel() {
+        if (closed) return;
+        closed = true;
+        cleanup();
+        // Drain without buffering so the response can reuse the connection.
+        req.resume();
+      },
+    });
+  }
+
+  private async handleNodeRequest(
+    req: plugins.http.IncomingMessage,
+    res: plugins.http.ServerResponse,
+    requestAbortController: AbortController,
+  ): Promise<void> {
+    const abortRequest = (reason: unknown): void => {
+      if (!requestAbortController.signal.aborted) {
+        requestAbortController.abort(reason);
+      }
     };
-    const payload = `event: state\ndata: ${JSON.stringify(stateChange)}\n\n`;
-    for (const [response, streamUser] of this.eventStreams) {
-      if (streamUser !== user) {
-        continue;
+    const onRequestAborted = (): void => {
+      abortRequest(new Error("Node request was aborted by the client."));
+    };
+    const onRequestError = (error: Error): void => {
+      abortRequest(error);
+    };
+    const onRequestClose = (): void => {
+      // IncomingMessage emits close after normal completion too. Only a
+      // close before the complete HTTP message is a transport abort.
+      if (!req.complete) onRequestAborted();
+    };
+    const onResponseClose = (): void => {
+      if (!res.writableEnded) {
+        abortRequest(
+          new Error("Node response connection closed before completion."),
+        );
+      }
+    };
+    req.once("aborted", onRequestAborted);
+    req.once("error", onRequestError);
+    req.once("close", onRequestClose);
+    res.once("close", onResponseClose);
+    try {
+      const method = (req.method ?? "GET").toUpperCase();
+      const headers = new Headers();
+      const skippedHeaders = new Set([
+        "connection",
+        "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 requestInit: RequestInit & { duplex?: "half" } = {
+        method,
+        headers,
+        signal: requestAbortController.signal,
+      };
+      if (method !== "GET" && method !== "HEAD") {
+        requestInit.body = this.nodeRequestBody(req);
+        requestInit.duplex = "half";
       }
+      const request = new Request(
+        `http://${host}${req.url ?? "/"}`,
+        requestInit,
+      );
+
+      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 }),
+      );
+    } finally {
+      req.off("aborted", onRequestAborted);
+      req.off("error", onRequestError);
+      req.off("close", onRequestClose);
+      res.off("close", onResponseClose);
+    }
+  }
+
+  // ======================
+  // 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" } },
+    );
   }
 }