Files

Juergen Kunz f1071faf3d fix(docs/readme): update README: clarify APIs, document RustSecurityBridge, update examples and architecture diagram

2026-02-10 16:57:14 +00:00

20 KiB

Raw Blame History

@push.rocks/smartmta

A high-performance, enterprise-grade Mail Transfer Agent (MTA) built from scratch in TypeScript with Rust acceleration — no nodemailer, no shortcuts.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm install @push.rocks/smartmta
# or
npm install @push.rocks/smartmta

Overview

@push.rocks/smartmta is a complete mail server solution — SMTP server, SMTP client, email security, content scanning, and delivery management — all built with a custom SMTP implementation. No wrappers around nodemailer. No half-measures.

What's Inside

Module	What It Does
SMTP Server	RFC 5321-compliant server with TLS/STARTTLS, authentication, pipelining
SMTP Client	Outbound delivery with connection pooling, retry logic, TLS negotiation
DKIM	Key generation, signing, and verification — per domain
SPF	Full SPF record validation
DMARC	Policy enforcement and verification
Email Router	Pattern-based routing with priority, forward/deliver/reject/process actions
Bounce Manager	Automatic bounce detection, classification (hard/soft), and tracking
Content Scanner	Spam, phishing, malware, XSS, and suspicious link detection
IP Reputation	DNSBL checks, proxy/TOR/VPN detection, risk scoring
Rate Limiter	Hierarchical rate limiting (global, per-domain, per-IP)
Delivery Queue	Persistent queue with exponential backoff retry
Template Engine	Email templates with variable substitution
Domain Registry	Multi-domain management with per-domain configuration
DNS Manager	Automatic DNS record management with Cloudflare API integration
Rust Accelerator	Performance-critical operations (DKIM, MIME, validation) in Rust via IPC
Rust Security Bridge	Compound email security verification (DKIM+SPF+DMARC) via Rust binary

Architecture

┌─────────────────────────────────────────────────────────┐
│                   UnifiedEmailServer                     │
│   (orchestrates all components, emits events)            │
├──────────┬──────────┬────────────┬──────────────────────┤
│  SMTP    │  Email   │  Security  │    Delivery          │
│  Server  │  Router  │  Stack     │    System            │
│  ┌─────┐ │  ┌─────┐ │ ┌───────┐  │  ┌────────────────┐ │
│  │ TLS │ │  │Match│ │ │ DKIM  │  │  │ Queue          │ │
│  │ Auth│ │  │Route│ │ │ SPF   │  │  │ Rate Limit     │ │
│  │ Cmd │ │  │ Act │ │ │ DMARC │  │  │ SMTP Client    │ │
│  │ Data│ │  │     │ │ │ IPRep │  │  │ Retry Logic    │ │
│  └─────┘ │  └─────┘ │ │ Scan  │  │  └────────────────┘ │
│          │          │ └───────┘  │                      │
├──────────┴──────────┴────────────┴──────────────────────┤
│              Rust Security Bridge                        │
│  (RustSecurityBridge singleton via smartrust IPC)        │
├─────────────────────────────────────────────────────────┤
│              Rust Acceleration Layer                      │
│  (mailer-core, mailer-security, mailer-bin)              │
└─────────────────────────────────────────────────────────┘

Usage

Setting Up the Email Server

The central entry point is UnifiedEmailServer, which orchestrates SMTP, routing, security, and delivery:

import { UnifiedEmailServer } from '@push.rocks/smartmta';

const emailServer = new UnifiedEmailServer(dcRouterRef, {
  ports: [25, 587, 465],
  hostname: 'mail.example.com',
  domains: [
    {
      domain: 'example.com',
      dnsMode: 'external-dns',
      dkim: {
        selector: 'default',
        keySize: 2048,
        rotateKeys: true,
        rotationInterval: 90,
      },
      rateLimits: {
        maxMessagesPerMinute: 100,
        maxRecipientsPerMessage: 50,
      },
    },
  ],
  routes: [
    {
      name: 'catch-all-forward',
      priority: 10,
      match: {
        recipients: '*@example.com',
      },
      action: {
        type: 'forward',
        forward: {
          host: 'internal-mail.example.com',
          port: 25,
        },
      },
    },
    {
      name: 'reject-spam-senders',
      priority: 100,
      match: {
        senders: '*@spamdomain.com',
      },
      action: {
        type: 'reject',
        reject: {
          code: 550,
          message: 'Sender rejected by policy',
        },
      },
    },
  ],
  auth: {
    required: false,
    methods: ['PLAIN', 'LOGIN'],
    users: [{ username: 'outbound', password: 'secret' }],
  },
  tls: {
    certPath: '/etc/ssl/mail.crt',
    keyPath: '/etc/ssl/mail.key',
  },
  maxMessageSize: 25 * 1024 * 1024, // 25 MB
  maxClients: 500,
});

await emailServer.start();

Sending Emails with the SMTP Client

Create and send emails using the built-in SMTP client with connection pooling:

import { Email, createSmtpClient } from '@push.rocks/smartmta';

// Create a client with connection pooling
const client = createSmtpClient({
  host: 'smtp.example.com',
  port: 587,
  secure: false,     // will upgrade via STARTTLS
  pool: true,
  maxConnections: 5,
  auth: {
    user: 'sender@example.com',
    pass: 'your-password',
  },
});

// Build an email
const email = new Email({
  from: 'sender@example.com',
  to: ['recipient@example.com'],
  cc: ['cc@example.com'],
  subject: 'Hello from smartmta!',
  text: 'Plain text body',
  html: '<h1>Hello!</h1><p>HTML body with <strong>formatting</strong></p>',
  priority: 'high',
  attachments: [
    {
      filename: 'report.pdf',
      content: pdfBuffer,
      contentType: 'application/pdf',
    },
  ],
});

// Send it
const result = await client.sendMail(email);
console.log(`Message sent: ${result.messageId}`);

DKIM Signing

DKIM key management is handled by DKIMCreator, which generates, stores, and rotates keys per domain. Signing is performed automatically by UnifiedEmailServer during outbound delivery — there is no standalone signEmail() call:

import { DKIMCreator } from '@push.rocks/smartmta';

const dkimCreator = new DKIMCreator('/path/to/keys');

// Auto-generate keys if they don't exist
await dkimCreator.handleDKIMKeysForDomain('example.com');

// Get the DNS record you need to publish
const dnsRecord = await dkimCreator.getDNSRecordForDomain('example.com');
console.log(dnsRecord);
// -> { type: 'TXT', name: 'default._domainkey.example.com', value: 'v=DKIM1; k=rsa; p=...' }

// Check if keys need rotation
const needsRotation = await dkimCreator.needsRotation('example.com', 'default', 90);
if (needsRotation) {
  const newSelector = await dkimCreator.rotateDkimKeys('example.com', 'default', 2048);
  console.log(`Rotated to selector: ${newSelector}`);
}

When UnifiedEmailServer.start() is called, DKIM signing is applied to all outbound mail automatically using the keys managed by DKIMCreator. The RustSecurityBridge can also perform DKIM signing via its signDkim() method for high-performance scenarios.

Email Authentication (SPF, DKIM, DMARC)

Verify incoming emails against all three authentication standards. Note that the first argument to SpfVerifier.verify() and DmarcVerifier.verify() is an Email object:

import { DKIMVerifier, SpfVerifier, DmarcVerifier } from '@push.rocks/smartmta';

// SPF verification — first arg is an Email object
const spfVerifier = new SpfVerifier();
const spfResult = await spfVerifier.verify(email, senderIP, heloDomain);
// -> { result: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none' | 'temperror' | 'permerror',
//      domain: string, ip: string }

// DKIM verification
const dkimVerifier = new DKIMVerifier();
const dkimResult = await dkimVerifier.verify(rawEmailContent);

// DMARC verification — first arg is an Email object
const dmarcVerifier = new DmarcVerifier();
const dmarcResult = await dmarcVerifier.verify(email, spfResult, dkimResult);
// -> { action: 'pass' | 'quarantine' | 'reject', hasDmarc: boolean,
//      spfDomainAligned: boolean, dkimDomainAligned: boolean, ... }

Email Routing

Pattern-based routing engine with priority ordering and flexible match criteria. Routes are evaluated by priority (highest first) using evaluateRoutes():

import { EmailRouter } from '@push.rocks/smartmta';

const router = new EmailRouter([
  {
    name: 'admin-mail',
    priority: 100,
    match: {
      recipients: 'admin@example.com',
      authenticated: true,
    },
    action: {
      type: 'deliver',
    },
  },
  {
    name: 'external-forward',
    priority: 50,
    match: {
      recipients: '*@example.com',
      sizeRange: { max: 10 * 1024 * 1024 },  // under 10MB
    },
    action: {
      type: 'forward',
      forward: {
        host: 'backend-mail.internal',
        port: 25,
        preserveHeaders: true,
      },
    },
  },
  {
    name: 'process-with-scanning',
    priority: 10,
    match: {
      recipients: '*@*',
    },
    action: {
      type: 'process',
      process: {
        scan: true,
        dkim: true,
        queue: 'normal',
      },
    },
  },
]);

// Evaluate routes against an email context
const matchedRoute = await router.evaluateRoutes(emailContext);

Content Scanning

Built-in content scanner for detecting spam, phishing, malware, and other threats. Use the scanEmail() method:

import { ContentScanner } from '@push.rocks/smartmta';

const scanner = new ContentScanner({
  scanSubject: true,
  scanBody: true,
  scanAttachments: true,
  blockExecutables: true,
  blockMacros: true,
  minThreatScore: 30,
  highThreatScore: 70,
  customRules: [
    {
      pattern: /bitcoin.*wallet/i,
      type: 'scam',
      score: 80,
      description: 'Cryptocurrency scam pattern',
    },
  ],
});

const result = await scanner.scanEmail(email);
// -> { isClean: false, threatScore: 85, threatType: 'phishing', scannedElements: [...] }

IP Reputation Checking

Check sender IP addresses against DNSBL blacklists and classify IP types:

import { IPReputationChecker } from '@push.rocks/smartmta';

const ipChecker = new IPReputationChecker({
  enableDNSBL: true,
  dnsblServers: ['zen.spamhaus.org', 'bl.spamcop.net'],
  cacheTTL: 24 * 60 * 60 * 1000,  // 24 hours
});

const reputation = await ipChecker.checkReputation('192.168.1.1');
// -> { score: 85, isSpam: false, isProxy: false, isTor: false, blacklists: [] }

When the RustSecurityBridge is running, IPReputationChecker automatically delegates DNSBL lookups to the Rust binary for improved performance.

Rate Limiting

Hierarchical rate limiting to protect your server and maintain deliverability. Configuration uses maxMessagesPerMinute and organizes domain-level limits under the domains key:

import { UnifiedRateLimiter } from '@push.rocks/smartmta';

const rateLimiter = new UnifiedRateLimiter({
  global: {
    maxMessagesPerMinute: 1000,
    maxRecipientsPerMessage: 500,
    maxConnectionsPerIP: 20,
    maxErrorsPerIP: 10,
    maxAuthFailuresPerIP: 5,
    blockDuration: 600000, // 10 minutes
  },
  domains: {
    'example.com': {
      maxMessagesPerMinute: 100,
      maxRecipientsPerMessage: 50,
    },
  },
});

// Check before sending
const allowed = rateLimiter.checkMessageLimit(
  'sender@example.com',
  '192.168.1.1',
  recipientCount,
  undefined,
  'example.com'
);

if (!allowed.allowed) {
  console.log(`Rate limited: ${allowed.reason}`);
}

Bounce Management

Automatic bounce detection, classification, and suppression tracking. Use isEmailSuppressed() to check if an address should be suppressed:

import { BounceManager } from '@push.rocks/smartmta';

const bounceManager = new BounceManager();

// Process an SMTP failure
const bounce = await bounceManager.processSmtpFailure(
  'recipient@example.com',
  '550 5.1.1 User unknown',
  { originalEmailId: 'msg-123' }
);
// -> { bounceType: 'invalid_recipient', bounceCategory: 'hard', ... }

// Check if an address is suppressed due to bounces
const suppressed = bounceManager.isEmailSuppressed('recipient@example.com');

// Manually manage the suppression list
bounceManager.addToSuppressionList('bad@example.com', 'repeated hard bounces');
bounceManager.removeFromSuppressionList('recovered@example.com');

Email Templates

Template engine with variable substitution for transactional and notification emails. Use createEmail() to produce a ready-to-send Email from a registered template:

import { TemplateManager } from '@push.rocks/smartmta';

const templates = new TemplateManager({
  from: 'noreply@example.com',
  footerHtml: '<p>2026 Example Corp</p>',
});

// Register a template
templates.registerTemplate({
  id: 'welcome',
  name: 'Welcome Email',
  description: 'Sent to new users',
  from: 'welcome@example.com',
  subject: 'Welcome, {{name}}!',
  bodyHtml: '<h1>Welcome, {{name}}!</h1><p>Your account is ready.</p>',
  bodyText: 'Welcome, {{name}}! Your account is ready.',
  category: 'transactional',
});

// Create an Email object from the template
const email = await templates.createEmail('welcome', {
  to: 'newuser@example.com',
  variables: { name: 'Alice' },
});

DNS Management

DNS record management for email authentication is handled internally by UnifiedEmailServer. The DnsManager is not instantiated directly — it receives its configuration from the dcRouter reference and automatically ensures MX, SPF, DKIM, and DMARC records are in place for all configured domains:

// DNS management is automatic when using UnifiedEmailServer.
// When the server starts, it calls ensureDnsRecords() internally
// for all configured domains, setting up:
//   - MX records pointing to your mail server
//   - SPF TXT records authorizing your server IP
//   - DKIM TXT records with public keys from DKIMCreator
//   - DMARC TXT records with your policy

const emailServer = new UnifiedEmailServer(dcRouterRef, {
  hostname: 'mail.example.com',
  domains: [
    {
      domain: 'example.com',
      dnsMode: 'external-dns',  // managed via Cloudflare API
    },
  ],
  // ... other config
});

// DNS records are set up automatically on start
await emailServer.start();

For DNS lookups and record verification outside of the server lifecycle, the DNSManager class (note the capital N) can be used directly:

import { DNSManager, DKIMCreator } from '@push.rocks/smartmta';

const dkimCreator = new DKIMCreator('/path/to/keys');
const dnsManager = new DNSManager(dkimCreator);

// Verify all email authentication records for a domain
const results = await dnsManager.verifyEmailAuthRecords('example.com', 'default');
console.log(results.spf);   // { valid: boolean, record: string, ... }
console.log(results.dkim);  // { valid: boolean, record: string, ... }
console.log(results.dmarc); // { valid: boolean, record: string, ... }

// Generate recommended DNS records
const records = await dnsManager.generateAllRecommendedRecords('example.com');

Rust Acceleration

Performance-critical operations are implemented in Rust and communicate with the TypeScript runtime via @push.rocks/smartrust (JSON-over-stdin/stdout IPC).

Rust Crates

The Rust workspace is at rust/ with five crates:

Crate	Status	Purpose
`mailer-core`	Complete (26 tests)	Email types, validation, MIME building, bounce detection
`mailer-security`	Complete (12 tests)	DKIM signing/verification, SPF checks, DMARC policy, IP reputation/DNSBL
`mailer-bin`	Complete	CLI + smartrust IPC bridge (handles `verifyEmail` compound method)
`mailer-smtp`	Planned (Phase 3)	SMTP protocol in Rust
`mailer-napi`	Planned (Phase 3)	Native Node.js addon

RustSecurityBridge

The RustSecurityBridge is a singleton that manages the Rust binary process and provides high-performance security verification. It is automatically started and stopped with UnifiedEmailServer:

import { RustSecurityBridge } from '@push.rocks/smartmta';

const bridge = RustSecurityBridge.getInstance();
await bridge.start();

// Compound verification: DKIM + SPF + DMARC in a single IPC call
const securityResult = await bridge.verifyEmail({
  rawMessage: rawEmailString,
  ip: '203.0.113.10',
  heloDomain: 'sender.example.com',
  mailFrom: 'user@example.com',
});
// -> { dkim: [...], spf: { result, explanation }, dmarc: { result, policy } }

// Individual operations
const dkimResults = await bridge.verifyDkim(rawEmailString);
const spfResult = await bridge.checkSpf({
  ip: '203.0.113.10',
  heloDomain: 'sender.example.com',
  mailFrom: 'user@example.com',
});
const reputationResult = await bridge.checkIpReputation('203.0.113.10');

await bridge.stop();

When the bridge is running, the TypeScript security components (SpfVerifier, DKIMVerifier, IPReputationChecker) automatically delegate to the Rust binary. If the binary is unavailable, the system falls back gracefully to TypeScript-only verification.

Project Structure

smartmta/
├── ts/                            # TypeScript source
│   ├── mail/
│   │   ├── core/                  # Email, EmailValidator, BounceManager, TemplateManager
│   │   ├── delivery/              # DeliverySystem, Queue, RateLimiter
│   │   │   ├── smtpclient/        # SMTP client with connection pooling
│   │   │   └── smtpserver/        # SMTP server with TLS, auth, pipelining
│   │   ├── routing/               # UnifiedEmailServer, EmailRouter, DomainRegistry, DnsManager
│   │   └── security/              # DKIMCreator, DKIMVerifier, SpfVerifier, DmarcVerifier
│   └── security/                  # ContentScanner, IPReputationChecker, RustSecurityBridge
├── rust/                          # Rust workspace
│   └── crates/                    # mailer-core, mailer-security, mailer-bin, mailer-smtp, mailer-napi
├── test/                          # Comprehensive test suite
└── dist_ts/                       # Compiled output

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

20 KiB Raw Blame History