smartmta/readme.md

# @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/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.

## Install

```bash
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-sender) |
| **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 |

### 🏗️ 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 Acceleration Layer                  │
│  (mailer-core, mailer-security via smartrust IPC)    │
└─────────────────────────────────────────────────────┘
```

## Usage

### 🔧 Setting Up the Email Server

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

```typescript
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:

```typescript
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

Automatic DKIM key generation, storage, and signing per domain:

```typescript
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=...' }

// Sign an email
const signedEmail = await dkimCreator.signEmail(email);
```

### 🛡️ Email Authentication (SPF, DKIM, DMARC)

Verify incoming emails against all three authentication standards:

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

// SPF verification
const spfVerifier = new SpfVerifier();
const spfResult = await spfVerifier.verify(senderIP, senderDomain, ehloHostname);
// → { result: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none' | 'temperror' | 'permerror' }

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

// DMARC verification
const dmarcVerifier = new DmarcVerifier();
const dmarcResult = await dmarcVerifier.verify(fromDomain, spfResult, dkimResult);
```

### 🔀 Email Routing

Pattern-based routing engine with priority ordering and flexible match criteria:

```typescript
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',
      },
    },
  },
]);

// Routes are evaluated by priority (highest first)
const matchedRoute = router.route(email, context);
```

### 🕵️ Content Scanning

Built-in content scanner for detecting spam, phishing, malware, and other threats:

```typescript
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.scan(email);
// → { isClean: false, threatScore: 85, threatType: 'phishing', scannedElements: [...] }
```

### 🌐 IP Reputation Checking

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

```typescript
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: [] }
```

### ⏱️ Rate Limiting

Hierarchical rate limiting to protect your server and maintain deliverability:

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

const rateLimiter = new UnifiedRateLimiter({
  global: {
    maxPerMinute: 1000,
    maxPerHour: 10000,
  },
  perDomain: {
    'example.com': {
      maxPerMinute: 100,
      maxPerHour: 1000,
    },
  },
  perSender: {
    maxPerMinute: 20,
    maxPerHour: 200,
  },
});
```

### 📬 Bounce Management

Automatic bounce detection, classification, and tracking:

```typescript
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 known to bounce
const shouldSuppress = bounceManager.shouldSuppressDelivery('recipient@example.com');
```

### 📝 Email Templates

Template engine with variable substitution for transactional and notification emails:

```typescript
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',
});

// Render and send
const email = templates.renderTemplate('welcome', {
  to: 'newuser@example.com',
  variables: { name: 'Alice' },
});
```

### 🌍 DNS Management with Cloudflare

Automatic DNS record setup for MX, SPF, DKIM, and DMARC via the Cloudflare API:

```typescript
import { DnsManager } from '@push.rocks/smartmta';

const dnsManager = new DnsManager({
  domains: [
    {
      domain: 'example.com',
      dnsMode: 'external-dns',  // managed via Cloudflare API
    },
  ],
});

// Auto-configure all required DNS records
await dnsManager.setupDnsForDomain('example.com', {
  serverIp: '203.0.113.10',
  mxHostname: 'mail.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):

- **mailer-core**: Email type validation, MIME building, bounce detection
- **mailer-security**: DKIM signing/verification, SPF checks, DMARC policy, IP reputation/DNSBL

The Rust workspace is at `rust/` with five crates:

| Crate | Status | Purpose |
|---|---|---|
| `mailer-core` | ✅ Complete | Email types, validation, MIME, bounce detection |
| `mailer-security` | ✅ Complete | DKIM, SPF, DMARC, IP reputation |
| `mailer-bin` | ✅ Complete | CLI + smartrust IPC bridge |
| `mailer-smtp` | 🔜 Phase 2 | SMTP protocol in Rust |
| `mailer-napi` | 🔜 Phase 2 | Native Node.js addon |

## 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, SecurityLogger
├── rust/                          # Rust workspace
│   └── crates/                    # mailer-core, mailer-security, mailer-bin, mailer-smtp, mailer-napi
├── test/                          # Comprehensive test suite (RFC compliance, security, performance, edge cases)
└── 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](./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.

### Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.