@push.rocks/smartjmap 1.0.0

package/ts/classes.jmapserver.ts

@@ -0,0 +1,1019 @@
+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;
+}
+
+export interface IJmapServerBlob {
+  data: Buffer;
+  type: string;
+  name?: string;
+}
+
+export interface IJmapServerChangeEntry {
+  state: number;
+  created: string[];
+  updated: string[];
+  destroyed: string[];
+}
+
+export interface IJmapServerIdentity {
+  id: string;
+  name: string;
+  email: string;
+  mayDelete: boolean;
+}
+
+export interface IJmapServerSubmission {
+  id: string;
+  emailId: string;
+  identityId: string;
+  undoStatus: string;
+  sendAt: string;
+}
+
+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;
+}
+
+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 }>;
+}
+
+/** Error type used inside method dispatch; rendered as a JMAP `error` method response. */
+class JmapServerMethodError extends Error {
+  constructor(public type: string, description?: string) {
+    super(description ?? type);
+  }
+}
+
+/**
+ * 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.
+ */
+export class JmapServer {
+  public users: Map<string, IJmapServerUser> = new Map();
+  private server: plugins.http.Server;
+  private sockets: Set<plugins.net.Socket> = new Set();
+  private eventStreams: Map<plugins.http.ServerResponse, IJmapServerUser> = new Map();
+
+  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);
+      });
+    });
+  }
+
+  // ======================
+  // store management
+  // ======================
+
+  public addUser(username: string, password: string): void {
+    if (this.users.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,
+    });
+  }
+
+  /** Registers a valid Bearer token for a user. */
+  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 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;
+  }
+
+  // ======================
+  // lifecycle
+  // ======================
+
+  /** Starts the server. Resolves with the bound port (pass 0 for an ephemeral port). */
+  public start(port: number): Promise<number> {
+    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;
+        resolve(boundPort);
+      });
+    });
+  }
+
+  /** Stops the server, ending open event streams and destroying open connections. */
+  public stop(): Promise<void> {
+    for (const response of this.eventStreams.keys()) {
+      try {
+        response.end();
+      } catch {
+        // response already gone
+      }
+    }
+    this.eventStreams.clear();
+    for (const socket of this.sockets) {
+      socket.destroy();
+    }
+    this.sockets.clear();
+    return new Promise((resolve) => {
+      this.server.close(() => {
+        resolve();
+      });
+    });
+  }
+
+  // ======================
+  // http handling
+  // ======================
+
+  private handleRequest(req: plugins.http.IncomingMessage, res: plugins.http.ServerResponse): void {
+    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' })
+        );
+        return;
+      }
+
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      const pathname = url.pathname;
+
+      if (req.method === 'GET' && (pathname === '/.well-known/jmap' || pathname === '/jmap/session')) {
+        this.handleSession(user, res);
+        return;
+      }
+      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 (req.method === 'GET' && pathname === '/jmap/eventsource') {
+        this.handleEventSource(user, req, res);
+        return;
+      }
+      if (req.method === 'GET' && pathname.startsWith('/jmap/download/')) {
+        this.handleDownload(user, pathname, url, res);
+        return;
+      }
+
+      res.writeHead(404, { 'content-type': 'application/problem+json' });
+      res.end(JSON.stringify({ type: 'about:blank', status: 404, detail: '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 }));
+    }
+  }
+
+  private authenticate(req: plugins.http.IncomingMessage): IJmapServerUser | null {
+    const header = req.headers.authorization;
+    if (!header) {
+      return null;
+    }
+    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;
+        }
+      }
+      return null;
+    }
+    if (scheme === 'basic') {
+      const decoded = Buffer.from(value, 'base64').toString('utf8');
+      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;
+      }
+      return null;
+    }
+    return null;
+  }
+
+  private handleSession(user: IJmapServerUser, res: plugins.http.ServerResponse): void {
+    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'],
+        },
+        'urn:ietf:params:jmap:mail': {},
+        'urn:ietf:params:jmap:submission': {},
+      },
+      accounts: {
+        [user.accountId]: {
+          name: user.username,
+          isPersonal: true,
+          isReadOnly: false,
+          accountCapabilities: {
+            'urn:ietf:params:jmap:mail': {},
+            'urn:ietf:params:jmap:submission': {},
+          },
+        },
+      },
+      primaryAccounts: {
+        'urn:ietf:params:jmap:core': user.accountId,
+        'urn:ietf:params:jmap:mail': user.accountId,
+        'urn:ietf:params:jmap:submission': user.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),
+    };
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(session));
+  }
+
+  private handleApi(user: IJmapServerUser, body: string, res: plugins.http.ServerResponse): void {
+    let parsed: any;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      res.writeHead(400, { 'content-type': 'application/problem+json' });
+      res.end(
+        JSON.stringify({
+          type: 'urn:ietf:params:jmap:error:notJSON',
+          status: 400,
+          detail: 'The request body is not valid JSON.',
+        })
+      );
+      return;
+    }
+    if (!Array.isArray(parsed?.methodCalls)) {
+      res.writeHead(400, { 'content-type': 'application/problem+json' });
+      res.end(
+        JSON.stringify({
+          type: 'urn:ietf:params:jmap:error:notRequest',
+          status: 400,
+          detail: 'The request body is not a valid JMAP request object.',
+        })
+      );
+      return;
+    }
+
+    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];
+      try {
+        const result = this.dispatchMethod(user, methodName, args ?? {}, createdIds);
+        methodResponses.push([methodName, result, callId]);
+      } catch (error) {
+        if (error instanceof JmapServerMethodError) {
+          methodResponses.push([
+            'error',
+            { type: error.type, description: error.message },
+            callId,
+          ]);
+        } else {
+          const message = error instanceof Error ? error.message : String(error);
+          methodResponses.push(['error', { type: 'serverFail', description: message }, callId]);
+        }
+      }
+    }
+
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ methodResponses, sessionState: String(user.state) }));
+  }
+
+  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);
+    });
+  }
+
+  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 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;
+    }
+    const type = url.searchParams.get('type') ?? blob.type;
+    res.writeHead(200, { 'content-type': type, 'content-length': blob.data.length });
+    res.end(blob.data);
+  }
+
+  // ======================
+  // jmap method dispatch
+  // ======================
+
+  private dispatchMethod(
+    user: IJmapServerUser,
+    methodName: string,
+    args: Record<string, any>,
+    createdIds: Map<string, string>
+  ): Record<string, any> {
+    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);
+      default:
+        throw new JmapServerMethodError('unknownMethod', `Unknown method "${methodName}".`);
+    }
+  }
+
+  private methodMailboxGet(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
+    const all = Array.from(user.mailboxes.values());
+    let list: IJmapServerMailbox[];
+    const notFound: string[] = [];
+    if (args.ids == null) {
+      list = all;
+    } else {
+      list = [];
+      for (const id of args.ids as string[]) {
+        const mailbox = user.mailboxes.get(id);
+        if (mailbox) {
+          list.push(mailbox);
+        } else {
+          notFound.push(id);
+        }
+      }
+    }
+    const augmented = list.map((mailbox) => {
+      const emails = Array.from(user.emails.values()).filter(
+        (email) => email.mailboxIds?.[mailbox.id]
+      );
+      return {
+        ...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,
+      };
+    });
+    return {
+      accountId: user.accountId,
+      state: String(user.state),
+      list: augmented,
+      notFound,
+    };
+  }
+
+  private methodMailboxQuery(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
+    const filter = args.filter ?? {};
+    let mailboxes = Array.from(user.mailboxes.values());
+    if (typeof filter.role === 'string') {
+      mailboxes = mailboxes.filter((mailbox) => mailbox.role === filter.role);
+    }
+    if (typeof filter.name === 'string') {
+      mailboxes = mailboxes.filter((mailbox) => mailbox.name === filter.name);
+    }
+    const ids = mailboxes.map((mailbox) => mailbox.id);
+    return {
+      accountId: user.accountId,
+      queryState: String(user.state),
+      canCalculateChanges: false,
+      position: 0,
+      ids,
+      total: ids.length,
+    };
+  }
+
+  private methodEmailGet(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
+    if (!Array.isArray(args.ids)) {
+      throw new JmapServerMethodError('invalidArguments', 'Email/get requires an ids array.');
+    }
+    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: user.accountId,
+      state: String(user.state),
+      list,
+      notFound,
+    };
+  }
+
+  private methodEmailQuery(user: IJmapServerUser, args: Record<string, any>): Record<string, any> {
+    const filter = args.filter ?? {};
+    let emails = Array.from(user.emails.values());
+    if (typeof filter.inMailbox === 'string') {
+      emails = emails.filter((email) => email.mailboxIds?.[filter.inMailbox]);
+    }
+    if (typeof filter.subject === 'string') {
+      emails = emails.filter((email) =>
+        String(email.subject ?? '').toLowerCase().includes(filter.subject.toLowerCase())
+      );
+    }
+    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)
+      );
+    }
+    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);
+    }
+    return {
+      accountId: user.accountId,
+      queryState: String(user.state),
+      canCalculateChanges: false,
+      position,
+      ids,
+      total,
+    };
+  }
+
+  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}".`
+      );
+    }
+    const created = new Set<string>();
+    const updated = new Set<string>();
+    const destroyed = new Set<string>();
+    for (const entry of user.changes) {
+      if (entry.state <= since) {
+        continue;
+      }
+      for (const id of entry.created) {
+        created.add(id);
+      }
+      for (const id of entry.updated) {
+        updated.add(id);
+      }
+      for (const id of entry.destroyed) {
+        if (created.has(id)) {
+          // created and destroyed within the window: omit entirely
+          created.delete(id);
+        } else {
+          destroyed.add(id);
+        }
+        updated.delete(id);
+      }
+    }
+    for (const id of created) {
+      updated.delete(id);
+    }
+    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),
+    };
+  }
+
+  private methodEmailSet(
+    user: IJmapServerUser,
+    args: Record<string, any>,
+    createdIds: Map<string, string>
+  ): Record<string, any> {
+    const oldState = String(user.state);
+    const created: Record<string, any> = {};
+    const notCreated: Record<string, any> = {};
+    const updated: Record<string, any> = {};
+    const notUpdated: Record<string, any> = {};
+    const destroyed: string[] = [];
+    const notDestroyed: Record<string, any> = {};
+    const changedCreated: string[] = [];
+    const changedUpdated: string[] = [];
+    const changedDestroyed: string[] = [];
+
+    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 };
+      }
+    }
+
+    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 };
+      }
+    }
+
+    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.` };
+      }
+    }
+
+    if (changedCreated.length || changedUpdated.length || changedDestroyed.length) {
+      this.bumpState(user, {
+        created: changedCreated,
+        updated: changedUpdated,
+        destroyed: changedDestroyed,
+      });
+    }
+
+    return {
+      accountId: user.accountId,
+      oldState,
+      newState: String(user.state),
+      created,
+      notCreated,
+      updated,
+      notUpdated,
+      destroyed,
+      notDestroyed,
+    };
+  }
+
+  private methodIdentityGet(user: IJmapServerUser): Record<string, any> {
+    return {
+      accountId: user.accountId,
+      state: '0',
+      list: user.identities,
+      notFound: [],
+    };
+  }
+
+  private methodEmailSubmissionSet(
+    user: IJmapServerUser,
+    args: Record<string, any>,
+    createdIds: Map<string, string>
+  ): Record<string, any> {
+    const created: Record<string, any> = {};
+    const notCreated: Record<string, any> = {};
+    for (const [creationId, spec] of Object.entries((args.create ?? {}) as Record<string, any>)) {
+      let emailId: string = spec.emailId;
+      if (typeof emailId === 'string' && emailId.startsWith('#')) {
+        const resolved = createdIds.get(emailId.slice(1));
+        if (!resolved) {
+          notCreated[creationId] = {
+            type: 'invalidProperties',
+            description: `Unknown creation id reference "${emailId}".`,
+          };
+          continue;
+        }
+        emailId = resolved;
+      }
+      if (!user.emails.has(emailId)) {
+        notCreated[creationId] = {
+          type: 'invalidProperties',
+          description: `Email "${emailId}" does not exist.`,
+        };
+        continue;
+      }
+      const identity = user.identities.find((candidate) => candidate.id === spec.identityId);
+      if (!identity) {
+        notCreated[creationId] = {
+          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(),
+      };
+      user.submissions.set(id, submission);
+      created[creationId] = { id, undoStatus: submission.undoStatus, sendAt: submission.sendAt };
+    }
+    return {
+      accountId: user.accountId,
+      oldState: String(user.state),
+      newState: String(user.state),
+      created,
+      notCreated,
+      updated: {},
+      notUpdated: {},
+      destroyed: [],
+      notDestroyed: {},
+    };
+  }
+
+  // ======================
+  // internal helpers
+  // ======================
+
+  private requireUser(username: string): IJmapServerUser {
+    const user = this.users.get(username);
+    if (!user) {
+      throw new Error(`User "${username}" does not exist.`);
+    }
+    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 };
+    }
+
+    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: [],
+    };
+  }
+
+  /**
+   * Applies an Email/set update patch: either whole properties (e.g. keywords)
+   * or JSON-pointer style paths like "keywords/$seen" (RFC 8620 §5.3).
+   */
+  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;
+        }
+        continue;
+      }
+      let target = email;
+      for (const segment of segments.slice(0, -1)) {
+        if (typeof target[segment] !== 'object' || target[segment] === null) {
+          target[segment] = {};
+        }
+        target = target[segment];
+      }
+      const leaf = segments[segments.length - 1];
+      if (value === null || value === false) {
+        delete target[leaf];
+      } else {
+        target[leaf] = value;
+      }
+    }
+  }
+
+  /** 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 ?? [],
+    });
+    this.notifyStateChange(user);
+  }
+
+  private notifyStateChange(user: IJmapServerUser): void {
+    const stateChange = {
+      '@type': 'StateChange',
+      changed: {
+        [user.accountId]: {
+          Email: String(user.state),
+          Mailbox: String(user.state),
+          Thread: String(user.state),
+        },
+      },
+    };
+    const payload = `event: state\ndata: ${JSON.stringify(stateChange)}\n\n`;
+    for (const [response, streamUser] of this.eventStreams) {
+      if (streamUser !== user) {
+        continue;
+      }
+      try {
+        response.write(payload);
+      } catch {
+        this.eventStreams.delete(response);
+      }
+    }
+  }
+}