imapkit 5.0.1 → 5.1.0

package/dist/esm/server.d.ts

@@ -6,6 +6,7 @@ import type { ResolvedCommandOptions } from './command-states.js';
 import { Control } from './control.js';
 import type { RestServer } from './rest.js';
 import type { SessionInfo } from './control.js';
+import type { MemorySocket } from './memory-socket.js';
 import { ServerScript } from './script.js';
 import type { DeferredOutput, OutputOperation, ScriptContext, ScriptEvent, ScriptRule } from './script.js';
 import type { AppendCheck, AppendCheckOptions, AppendDataHandler, AppendMessage, CapabilityCheck, CheckResult, ClosedCheck, CommandCheck, CommandContext, CommandOptions, CommandHandler, ConnectionHandler, ConnectionState, CopyHandler, FetchHandler, IMAPResponse, IMAPServerOptions, ListedMailbox, LiteralFilter, Mailbox, MailboxHandler, MailboxStatus, Message, MessageFilter, MessageHandler, MessageRange, Namespace, Notification, NotifyEvent, NotifyFilter, OutputHandler, ParsedCommand, RangeLimit, Refusal, SearchAccessCheck, SearchHandler, SearchLimit, ServerStorage, StatusHandler, StorageMailbox, StorageMessage, StoreHandler, SubscriptionStandIn, Transport, UrlAccessCheck, UserData } from './types.js';
@@ -158,6 +159,18 @@ declare class IMAPServer extends Stream {
     };
     address(): ReturnType<net.Server['address']>;
     createClient(socket: net.Socket): void;
+    /**
+     * Opens a connection to the server in memory, without a network socket (no `listen()` needed). This is how the
+     * server runs in a browser, see the README "Run in a browser"
+     *
+     * @param {Object} [options] `{ secure }`: false makes the connection a plaintext one, where STARTTLS turns on the
+     *   encryption (nothing is encrypted, the session only counts as encrypted). By default the connection counts as
+     *   one over TLS
+     * @return {MemorySocket} the client end, write commands to it and read the responses from its `data` events
+     */
+    connect(options?: {
+        secure?: boolean | undefined;
+    }): MemorySocket;
     registerCapability(keyword: string, handler?: CapabilityCheck | null): void;
     /**
      * Sets the handler of a command

package/dist/esm/server.js

@@ -19,6 +19,7 @@ import { resolveQuirks } from './quirks.js';
 import { validateStorage } from './storage-schema.js';
 import { createRestServer } from './rest.js';
 import * as bundledCert from './cert.js';
+import { createSocketPair } from './memory-socket.js';
 import { ServerScript, sendOutput, handleLine, handleQuiet, literalResponse, releaseDeferred } from './script.js';
 // longest command line (not counting literals) accepted from a client
 const MAX_LINE_LENGTH = 1024 * 1024;
@@ -359,6 +360,21 @@ class IMAPServer extends Stream {
             handler(connection);
         });
     }
+    /**
+     * Opens a connection to the server in memory, without a network socket (no `listen()` needed). This is how the
+     * server runs in a browser, see the README "Run in a browser"
+     *
+     * @param {Object} [options] `{ secure }`: false makes the connection a plaintext one, where STARTTLS turns on the
+     *   encryption (nothing is encrypted, the session only counts as encrypted). By default the connection counts as
+     *   one over TLS
+     * @return {MemorySocket} the client end, write commands to it and read the responses from its `data` events
+     */
+    connect(options) {
+        const [serverSocket, clientSocket] = createSocketPair();
+        serverSocket.encrypted = clientSocket.encrypted = !options || options.secure !== false;
+        this.createClient(serverSocket);
+        return clientSocket;
+    }
     registerCapability(keyword, handler) {
         this.capabilities[keyword] =
             handler ||
@@ -1396,7 +1412,8 @@ class IMAPConnection {
         this._outputQueue = null;
         this._outputTimer = null;
         this._deferredOutput = null;
-        this.secureConnection = !!this.options.secureConnection;
+        // a TLS socket is encrypted, and so can be an in-memory connection of server.connect()
+        this.secureConnection = !!this.options.secureConnection || socket.encrypted === true;
         this._remainder = '';
         this._command = '';
         this._literalRemaining = 0;
@@ -1414,7 +1431,7 @@ class IMAPConnection {
         this.messageGlobal = false;
         this._commandQueue = [];
         this._processing = false;
-        if (this.options.debug) {
+        if (this.options.debug && typeof this.socket.pipe === 'function') {
             this.socket.pipe(process.stdout);
         }
         this.socket.on('data', this.receive.bind(this));
@@ -1653,7 +1670,8 @@ class IMAPConnection {
                 this.watchQuiet(quiet);
             }
         }, Math.max(0, next - (Date.now() - last)));
-        this._quietTimer.unref();
+        // browsers have no unref
+        this._quietTimer.unref?.();
     }
     /**
      * Handles data from the socket, through the transport layer if there is one
@@ -2323,6 +2341,16 @@ class IMAPConnection {
         // section 6.2.1). STARTTLS is refused when input is waiting (the noPipelining command option), this only
         // guards against plugins that upgrade the connection otherwise
         this.discardInput();
+        // STARTTLS runs on a live connection
+        const socket = this.socket;
+        if (typeof socket.startTls === 'function') {
+            // a socket without a TLS layer that can count as encrypted (MemorySocket of server.connect())
+            return socket.startTls(() => {
+                this.secureConnection = true;
+                this.upgrading = false;
+                callback();
+            });
+        }
         const secureContext = tls.createSecureContext(this.server.getCredentials());
         const socketOptions = {
             secureContext: secureContext,
@@ -2333,8 +2361,6 @@ class IMAPConnection {
                 cb(null, secureContext);
             }
         };
-        // STARTTLS runs on a live connection
-        const socket = this.socket;
         // the RST of a script rule goes to the TCP socket under the TLS layer, see resetSocket. Node also has it as the
         // _parent of the TLS socket, Bun does not
         this.tcpSocket = socket;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapkit",
-    "version": "5.0.1",
+    "version": "5.1.0",
     "description": "Scriptable, strictly RFC compliant in-memory IMAP server for testing IMAP clients",
     "type": "module",
     "main": "./dist/cjs/index.js",
@@ -18,6 +18,10 @@
             "import": "./dist/esm/index.js",
             "require": "./dist/cjs/index.js"
         },
+        "./browser": {
+            "types": "./dist/esm/index.d.ts",
+            "default": "./dist/browser/imapkit.js"
+        },
         "./lib/server": {
             "import": "./dist/esm/index.js",
             "require": "./dist/cjs/index.js"
@@ -89,8 +93,11 @@
         "@eslint/js": "10.0.1",
         "@types/node": "20.19.43",
         "@types/smtp-server": "3.5.13",
+        "buffer": "6.0.3",
+        "esbuild": "0.28.2",
         "eslint": "10.12.0",
         "eslint-config-prettier": "10.1.8",
+        "events": "3.3.0",
         "globals": "17.13.0",
         "imapflow": "2.2.9",
         "prettier": "3.9.9",