@inbrx/cli 0.0.1-alpha.3 → 0.0.1-alpha.4

package/README.md

@@ -0,0 +1,78 @@
+# @inbrx/cli
+
+CLI for capturing local SMTP mail with inbrx. Start it, point your application at the local SMTP endpoint, and inspect captured emails in the browser.
+
+## Quick Start
+
+```bash
+npx @inbrx/cli
+```
+
+Defaults:
+
+- SMTP server: `127.0.0.1:2525`
+- Web UI: `http://127.0.0.1:3000`
+- Storage: file-backed, using the standard user data directory for your operating system
+
+Use memory-only storage for throwaway sessions:
+
+```bash
+npx @inbrx/cli --storage memory
+```
+
+## Options
+
+```bash
+inbrx start \
+  --smtp-host 127.0.0.1 \
+  --smtp-port 2525 \
+  --smtp-starttls \
+  --smtp-tls-key ./smtp.key \
+  --smtp-tls-cert ./smtp.crt \
+  --http-host 127.0.0.1 \
+  --http-port 3000 \
+  --max-messages 500 \
+  --storage file
+```
+
+Environment variables:
+
+- `SMTP_TEST_SMTP_HOST`
+- `SMTP_TEST_SMTP_PORT`
+- `INBRX_SMTP_STARTTLS=true|false`
+- `INBRX_SMTP_TLS_KEY`
+- `INBRX_SMTP_TLS_CERT`
+- `SMTP_TEST_HTTP_HOST`
+- `SMTP_TEST_HTTP_PORT`
+- `SMTP_TEST_MAX_MESSAGES`
+- `INBRX_STORAGE=file|memory`
+
+## STARTTLS
+
+Enable STARTTLS with an automatically generated in-memory self-signed certificate:
+
+```bash
+inbrx start --smtp-starttls
+```
+
+Use your own certificate by providing both paths. Providing both paths also enables STARTTLS:
+
+```bash
+inbrx start --smtp-tls-key ./smtp.key --smtp-tls-cert ./smtp.crt
+```
+
+Self-signed certificates usually require test clients to disable certificate verification:
+
+```bash
+swaks --to recipient@example.com \
+  --from sender@example.com \
+  --server 127.0.0.1 \
+  --port 2525 \
+  --tls \
+  --tls-verify false \
+  --auth LOGIN \
+  --auth-user sender@example.com \
+  --auth-password 'your_password' \
+  --header "Subject: test email" \
+  --body "Hello from SMTP"
+```

package/dist/cli.js

@@ -19,6 +19,9 @@ export function createCliProgram() {
         .description('Start the SMTP server and HTTP API/UI.')
         .option('--smtp-host <host>', `SMTP bind host. Default: ${defaults.smtpHost}`)
         .option('--smtp-port <port>', `SMTP port. Default: ${defaults.smtpPort}`)
+        .option('--smtp-starttls', 'Advertise and support STARTTLS. Generates a temporary self-signed certificate unless TLS paths are provided.')
+        .option('--smtp-tls-key <path>', 'TLS private key path for STARTTLS. Enables STARTTLS when paired with --smtp-tls-cert.')
+        .option('--smtp-tls-cert <path>', 'TLS certificate path for STARTTLS. Enables STARTTLS when paired with --smtp-tls-key.')
         .option('--http-host <host>', `HTTP bind host. Default: ${defaults.httpHost}`)
         .option('--http-port <port>', `HTTP port. Default: ${defaults.httpPort}`)
         .option('--max-messages <count>', `Maximum retained messages. Default: ${defaults.maxMessages}`)
@@ -28,6 +31,9 @@ export function createCliProgram() {
 Environment:
   SMTP_TEST_SMTP_HOST
   SMTP_TEST_SMTP_PORT
+  INBRX_SMTP_STARTTLS
+  INBRX_SMTP_TLS_KEY
+  INBRX_SMTP_TLS_CERT
   SMTP_TEST_HTTP_HOST
   SMTP_TEST_HTTP_PORT
   SMTP_TEST_MAX_MESSAGES
@@ -42,6 +48,7 @@ async function startServer(options) {
     const app = await startApp(config);
     console.log('SMTP test server ready');
     console.log(`SMTP: smtp://${config.smtpHost}:${config.smtpPort}`);
+    console.log(`SMTP STARTTLS: ${config.smtpStartTls ? 'enabled' : 'disabled'}`);
     console.log(`Web UI: http://${config.httpHost}:${config.httpPort}`);
     console.log(`Storage: ${config.storage}${config.storage === 'file' ? ` (${getDefaultDataDir()})` : ''}`);
     console.log('Press Ctrl+C to stop.');

package/dist/config.js

@@ -1,15 +1,25 @@
 const DEFAULTS = {
     smtpHost: '127.0.0.1',
     smtpPort: 2525,
+    smtpStartTls: false,
+    smtpTlsKeyPath: null,
+    smtpTlsCertPath: null,
     httpHost: '127.0.0.1',
     httpPort: 3000,
     maxMessages: 500,
     storage: 'file'
 };
 export function loadConfig(overrides = {}) {
+    const smtpTlsKeyPath = readOptionalString(overrides.smtpTlsKeyPath, process.env.INBRX_SMTP_TLS_KEY, DEFAULTS.smtpTlsKeyPath);
+    const smtpTlsCertPath = readOptionalString(overrides.smtpTlsCertPath, process.env.INBRX_SMTP_TLS_CERT, DEFAULTS.smtpTlsCertPath);
     const config = {
         smtpHost: readString(overrides.smtpHost, process.env.SMTP_TEST_SMTP_HOST, DEFAULTS.smtpHost),
         smtpPort: readNumber(overrides.smtpPort, process.env.SMTP_TEST_SMTP_PORT, DEFAULTS.smtpPort),
+        smtpStartTls: readBoolean(overrides.smtpStartTls ?? overrides.smtpStarttls, process.env.INBRX_SMTP_STARTTLS, DEFAULTS.smtpStartTls) ||
+            Boolean(smtpTlsKeyPath) ||
+            Boolean(smtpTlsCertPath),
+        smtpTlsKeyPath,
+        smtpTlsCertPath,
         httpHost: readString(overrides.httpHost, process.env.SMTP_TEST_HTTP_HOST, DEFAULTS.httpHost),
         httpPort: readNumber(overrides.httpPort, process.env.SMTP_TEST_HTTP_PORT, DEFAULTS.httpPort),
         maxMessages: readNumber(overrides.maxMessages, process.env.SMTP_TEST_MAX_MESSAGES, DEFAULTS.maxMessages),
@@ -17,6 +27,9 @@ export function loadConfig(overrides = {}) {
     };
     assertPort(config.smtpPort, 'SMTP port');
     assertPort(config.httpPort, 'HTTP port');
+    if (Boolean(config.smtpTlsKeyPath) !== Boolean(config.smtpTlsCertPath)) {
+        throw new Error('SMTP TLS key and certificate paths must be provided together.');
+    }
     if (!Number.isInteger(config.maxMessages) || config.maxMessages < 1) {
         throw new Error('Max messages must be a positive integer.');
     }
@@ -34,6 +47,15 @@ function readString(override, envValue, fallback) {
     }
     return fallback;
 }
+function readOptionalString(override, envValue, fallback) {
+    if (override !== undefined && override !== null && override !== '') {
+        return String(override);
+    }
+    if (envValue !== undefined && envValue !== '') {
+        return envValue;
+    }
+    return fallback;
+}
 function readNumber(override, envValue, fallback) {
     const value = override ?? envValue;
     if (value === undefined || value === '') {
@@ -45,6 +67,23 @@ function readNumber(override, envValue, fallback) {
     }
     return parsed;
 }
+function readBoolean(override, envValue, fallback) {
+    const value = override ?? envValue;
+    if (value === undefined || value === null || value === '') {
+        return fallback;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = String(value).toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(normalized)) {
+        return true;
+    }
+    if (['0', 'false', 'no', 'off'].includes(normalized)) {
+        return false;
+    }
+    throw new Error(`Expected a boolean, received "${value}".`);
+}
 function assertPort(value, label) {
     if (!Number.isInteger(value) || value < 1 || value > 65535) {
         throw new Error(`${label} must be an integer between 1 and 65535.`);

package/dist/events/mailbox-events.js

@@ -0,0 +1,16 @@
+export function createMailboxEvents() {
+    const listeners = new Set();
+    return {
+        emit(event) {
+            for (const listener of listeners) {
+                listener(event);
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        }
+    };
+}

package/dist/http/server.js

@@ -5,10 +5,11 @@ import { Readable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
+import { createMailboxEvents } from '../events/mailbox-events.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const WEB_ROOT = path.resolve(__dirname, '../../..', 'web/dist');
-export function createHttpServer({ store, attachmentStore }) {
-    const app = createHttpApp({ store, attachmentStore });
+export function createHttpServer({ store, attachmentStore, events = createMailboxEvents() }) {
+    const app = createHttpApp({ store, attachmentStore, events });
     let server = null;
     return {
         listen(port, host) {
@@ -43,18 +44,20 @@ export function createHttpServer({ store, attachmentStore }) {
         }
     };
 }
-export function createHttpApp({ store, attachmentStore }) {
+export function createHttpApp({ store, attachmentStore, events = createMailboxEvents() }) {
     const app = new Hono();
     app.onError((error, c) => {
         console.error(error);
         return c.json({ error: 'Internal server error' }, 500);
     });
     app.get('/api/health', (c) => c.json({ status: 'ok' }));
+    app.get('/api/events', (c) => sseResponse(events, c.req.raw.signal));
     app.get('/api/messages', async (c) => c.json({
         messages: (await store.list()).map(toMessageSummary)
     }));
     app.delete('/api/messages', async (c) => {
         const deleted = await store.clear();
+        events.emit({ type: 'messages.cleared', deleted });
         return c.json({ deleted });
     });
     app.get('/api/messages/:id', async (c) => {
@@ -84,12 +87,80 @@ export function createHttpApp({ store, attachmentStore }) {
         });
     });
     app.delete('/api/messages/:id', async (c) => {
-        const deleted = await store.delete(c.req.param('id'));
+        const messageId = c.req.param('id');
+        const deleted = await store.delete(messageId);
+        if (deleted) {
+            events.emit({ type: 'message.deleted', id: messageId });
+        }
         return c.json({ deleted }, deleted ? 200 : 404);
     });
     app.all('*', (c) => serveStatic(new URL(c.req.url).pathname));
     return app;
 }
+function sseResponse(events, signal) {
+    const encoder = new TextEncoder();
+    let unsubscribe = null;
+    let keepalive = null;
+    let closed = false;
+    const stream = new ReadableStream({
+        start(controller) {
+            const send = (event, data) => {
+                if (closed) {
+                    return;
+                }
+                controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+            };
+            const cleanup = () => {
+                if (closed) {
+                    return;
+                }
+                closed = true;
+                unsubscribe?.();
+                unsubscribe = null;
+                if (keepalive) {
+                    clearInterval(keepalive);
+                    keepalive = null;
+                }
+            };
+            send('ready', { version: 1 });
+            unsubscribe = events.subscribe((event) => {
+                send(event.type, eventData(event));
+            });
+            keepalive = setInterval(() => {
+                if (!closed) {
+                    controller.enqueue(encoder.encode(': keepalive\n\n'));
+                }
+            }, 30000);
+            signal.addEventListener('abort', cleanup, { once: true });
+        },
+        cancel() {
+            closed = true;
+            unsubscribe?.();
+            unsubscribe = null;
+            if (keepalive) {
+                clearInterval(keepalive);
+                keepalive = null;
+            }
+        }
+    });
+    return new Response(stream, {
+        headers: {
+            'content-type': 'text/event-stream; charset=utf-8',
+            'cache-control': 'no-cache, no-transform',
+            connection: 'keep-alive'
+        }
+    });
+}
+function eventData(event) {
+    switch (event.type) {
+        case 'message.created':
+            return { id: event.id, receivedAt: event.receivedAt };
+        case 'message.deleted':
+            return { id: event.id };
+        case 'messages.cleared':
+            return { deleted: event.deleted };
+    }
+}
 function toMessageSummary(message) {
     return {
         id: message.id,

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createMailboxEvents } from './events/mailbox-events.js';
 import { createHttpServer } from './http/server.js';
 import { createFileAttachmentStore, createMemoryAttachmentStore } from './store/attachment-store.js';
 import { getDefaultDataDir } from './store/data-dir.js';
@@ -5,9 +6,17 @@ import { createFileMessageStore } from './store/file-store.js';
 import { createMemoryStore } from './store/memory-store.js';
 import { createSmtpServer } from './smtp/server.js';
 export async function startApp(config) {
-    const { store, attachmentStore } = createStores(config);
-    const smtpServer = createSmtpServer({ store, attachmentStore });
-    const httpServer = createHttpServer({ store, attachmentStore });
+    const events = createMailboxEvents();
+    const { store, attachmentStore } = createStores(config, events);
+    const smtpServer = await createSmtpServer({
+        store,
+        attachmentStore,
+        events,
+        startTls: config.smtpStartTls,
+        tlsKeyPath: config.smtpTlsKeyPath,
+        tlsCertPath: config.smtpTlsCertPath
+    });
+    const httpServer = createHttpServer({ store, attachmentStore, events });
     await Promise.all([
         smtpServer.listen(config.smtpPort, config.smtpHost),
         httpServer.listen(config.httpPort, config.httpHost)
@@ -19,14 +28,14 @@ export async function startApp(config) {
         }
     };
 }
-function createStores(config) {
+function createStores(config, events) {
     if (config.storage === 'memory') {
         const attachmentStore = createMemoryAttachmentStore();
         return {
             attachmentStore,
             store: createMemoryStore({
                 maxMessages: config.maxMessages,
-                onDelete: (messageId) => attachmentStore.deleteForMessage(messageId)
+                onDelete: createDeleteHandler(attachmentStore, events)
             })
         };
     }
@@ -37,7 +46,15 @@ function createStores(config) {
         store: createFileMessageStore({
             rootDir: dataDir,
             maxMessages: config.maxMessages,
-            onDelete: (messageId) => attachmentStore.deleteForMessage(messageId)
+            onDelete: createDeleteHandler(attachmentStore, events)
         })
     };
 }
+function createDeleteHandler(attachmentStore, events) {
+    return async (messageId, reason) => {
+        await attachmentStore.deleteForMessage(messageId);
+        if (reason === 'evicted') {
+            events.emit({ type: 'message.deleted', id: messageId });
+        }
+    };
+}

package/dist/smtp/server.js

@@ -1,13 +1,21 @@
+import { readFile } from 'node:fs/promises';
 import { SMTPServer } from 'smtp-server';
+import { generate } from 'selfsigned';
 import { parseMessage } from '../mail/parser.js';
-export function createSmtpServer({ store, attachmentStore }) {
+export async function createSmtpServer({ store, attachmentStore, events, startTls = false, tlsKeyPath = null, tlsCertPath = null }) {
+    const tlsConfig = startTls ? await createTlsConfig({ keyPath: tlsKeyPath, certPath: tlsCertPath }) : null;
     const server = new SMTPServer({
         name: 'inbrx',
         banner: 'inbrx ready',
+        ...(tlsConfig ?? {}),
         authOptional: true,
-        disabledCommands: ['AUTH', 'STARTTLS'],
+        allowInsecureAuth: true,
+        disabledCommands: startTls ? [] : ['STARTTLS'],
         hidePIPELINING: true,
         logger: false,
+        onAuth(auth, _session, callback) {
+            callback(null, { user: auth.username || 'anonymous' });
+        },
         onMailFrom(_address, _session, callback) {
             callback();
         },
@@ -16,7 +24,10 @@ export function createSmtpServer({ store, attachmentStore }) {
         },
         onData(stream, session, callback) {
             void handleData(stream, session, store, attachmentStore)
-                .then((messageId) => callback(null, `OK captured as ${messageId}`))
+                .then((message) => {
+                events?.emit({ type: 'message.created', id: message.id, receivedAt: message.receivedAt });
+                callback(null, `OK captured as ${message.id}`);
+            })
                 .catch((error) => callback(error instanceof Error ? error : new Error(String(error))));
         }
     });
@@ -37,6 +48,42 @@ export function createSmtpServer({ store, attachmentStore }) {
         }
     };
 }
+async function createTlsConfig({ keyPath, certPath }) {
+    if (keyPath || certPath) {
+        if (!keyPath || !certPath) {
+            throw new Error('SMTP TLS key and certificate paths must be provided together.');
+        }
+        const [key, cert] = await Promise.all([readFile(keyPath), readFile(certPath)]);
+        return { key, cert };
+    }
+    const pems = await generate([{ name: 'commonName', value: 'localhost' }], {
+        keySize: 2048,
+        algorithm: 'sha256',
+        extensions: [
+            {
+                name: 'basicConstraints',
+                cA: false
+            },
+            {
+                name: 'keyUsage',
+                digitalSignature: true,
+                keyEncipherment: true
+            },
+            {
+                name: 'subjectAltName',
+                altNames: [
+                    { type: 2, value: 'localhost' },
+                    { type: 7, ip: '127.0.0.1' },
+                    { type: 7, ip: '::1' }
+                ]
+            }
+        ]
+    });
+    return {
+        key: pems.private,
+        cert: pems.cert
+    };
+}
 async function handleData(stream, session, store, attachmentStore) {
     const raw = await readStream(stream);
     const smtp = toCapturedSmtpSession(session);
@@ -49,7 +96,7 @@ async function handleData(stream, session, store, attachmentStore) {
         await attachmentStore.deleteForMessage(message.id);
         throw error;
     }
-    return message.id;
+    return message;
 }
 function readStream(stream) {
     return new Promise((resolve, reject) => {

package/dist/store/file-store.js

@@ -21,13 +21,13 @@ export function createFileMessageStore({ rootDir, maxMessages, onDelete }) {
                 return false;
             }
             await rm(messagePath(messagesDir, id), { force: true });
-            await onDelete?.(id);
+            await onDelete?.(id, 'deleted');
             return true;
         },
         async clear() {
             const messages = await listMessages(messagesDir);
             await rm(messagesDir, { recursive: true, force: true });
-            await Promise.all(messages.map((message) => onDelete?.(message.id)));
+            await Promise.all(messages.map((message) => onDelete?.(message.id, 'cleared')));
             return messages.length;
         }
     };
@@ -37,7 +37,7 @@ async function trimMessages({ messagesDir, maxMessages, onDelete }) {
     const removed = messages.slice(maxMessages);
     await Promise.all(removed.map(async (message) => {
         await rm(messagePath(messagesDir, message.id), { force: true });
-        await onDelete?.(message.id);
+        await onDelete?.(message.id, 'evicted');
     }));
 }
 async function listMessages(messagesDir) {

package/dist/store/memory-store.js

@@ -9,7 +9,7 @@ export function createMemoryStore({ maxMessages, onDelete }) {
                 const removedId = order.pop();
                 if (removedId) {
                     messages.delete(removedId);
-                    await onDelete?.(removedId);
+                    await onDelete?.(removedId, 'evicted');
                 }
             }
             return message;
@@ -27,7 +27,7 @@ export function createMemoryStore({ maxMessages, onDelete }) {
                 order.splice(index, 1);
             }
             if (existed) {
-                await onDelete?.(id);
+                await onDelete?.(id, 'deleted');
             }
             return existed;
         },
@@ -36,7 +36,7 @@ export function createMemoryStore({ maxMessages, onDelete }) {
             const ids = [...messages.keys()];
             messages.clear();
             order.length = 0;
-            await Promise.all(ids.map((id) => onDelete?.(id)));
+            await Promise.all(ids.map((id) => onDelete?.(id, 'cleared')));
             return count;
         }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inbrx/cli",
-  "version": "0.0.1-alpha.3",
+  "version": "0.0.1-alpha.4",
   "description": "CLI for capturing local SMTP mail with inbrx.",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   "type": "module",
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "README.md"
   ],
   "bin": {
     "inbrx": "./bin/inbrx.js"
@@ -28,10 +29,11 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.8",
-    "@inbrx/web": "0.0.1-alpha.3",
+    "@inbrx/web": "0.0.1-alpha.4",
     "commander": "^15.0.0",
     "hono": "^4.12.27",
     "mailparser": "^3.9.14",
+    "selfsigned": "^5.5.0",
     "smtp-server": "^3.19.2"
   },
   "devDependencies": {