Email Security

All outbound email passes through multi-layered security scanning before delivery. The @owlat/email-scanner package provides all scanning logic as a shared library, consumed by both apps/api (Convex) and apps/mta.

Content Scanning

Analyzes email subject and HTML body for malicious or unwanted content. All scanners are pure TypeScript with zero dependencies, safe for the Convex serverless runtime.

Spam Keywords

40+ weighted patterns detect common spam phrases:

Phishing URL Detection

• URL shortener detection (bit.ly, t.co, goo.gl, etc.)
• Anchor/href domain mismatch (link text says paypal.com but links to evil.com)
• Suspicious URL patterns (IP addresses in URLs, excessive subdomains)

Homoglyph / Unicode Spoofing

Detects mixed-script characters used to impersonate legitimate domains:

• ~50 confusable character mappings (Cyrillic а U+0430 vs Latin a U+0061, Greek ο U+03BF vs Latin o, etc.)
• Mixed-script detection in link text and URL hostnames
• Severity: high (20 pts) — homoglyph spoofing is a strong phishing indicator

Prohibited Content

Pattern matching for high-severity scam content:

• Advance fee fraud patterns ("beneficiary", "next of kin", "unclaimed funds")
• Credential phishing ("verify your account", "confirm your password", "update your payment")

Subject Line Analysis

• ALL CAPS abuse (>50% uppercase characters)
• Excessive punctuation (3+ consecutive ! or ?)

Scoring

All flags contribute to a composite score:

Thresholds:

File Validation

Validates attachments and media uploads before storage or sending. Pure TypeScript, no external dependencies.

Magic Bytes Detection

Identifies real file type from binary headers (first 16 bytes), regardless of file extension:

Double Extension Detection

Catches attacks that hide executable extensions after document extensions:

• invoice.pdf.exe — detected and blocked
• report.docx.js — detected and blocked
• photo.jpg.scr — detected and blocked

Extension Allowlist

Permitted file types (everything else is blocked):

MIME Type Allowlist

Validates declared content types against an allowlist of safe MIME types (e.g., image/*, application/pdf, text/plain).

Integration Points

• emailWorker.ts — validates each attachment buffer before sending
• mediaAssets.ts — validates uploads before storing to Convex file storage

URL Reputation

Checks URLs in email content against the Google Safe Browsing API v4.

How It Works

1. Extract all URLs from the email HTML content
2. Normalize and hash URLs (SHA-256)
3. Check cache (urlReputationCache table) for known verdicts
4. Batch-check uncached URLs against Safe Browsing API (up to 500 per request)
5. Cache results (24h for clean, 1h for flagged)
6. Convert flagged URLs to ContentFlag entries with severity 'high'

Threat Types

Campaign vs Transactional

Configuration

Requires the GOOGLE_SAFE_BROWSING_API_KEY environment variable set in the Convex dashboard. The free tier allows 10,000 requests per day. When the API key is not configured, URL reputation checking is silently skipped.

ClamAV Malware Scanning

Scans attachment binary data for known malware signatures using ClamAV running as a Docker sidecar alongside the MTA.

Architecture

Convex emailWorker
    │
    │  POST /scan/attachment
    │  (binary data + X-Filename header)
    ▼
MTA scan endpoint (src/routes/scan.ts)
    │
    ├─ File type validation (magic bytes, extensions)
    │
    └─ ClamAV scan (TCP INSTREAM protocol)
        │
        ▼
    clamd (port 3310)

INSTREAM Protocol

The @owlat/email-scanner ClamAV client communicates with clamd over TCP using the INSTREAM protocol:

1. Send zINSTREAM\0
2. Send chunked binary data (4-byte big-endian length prefix + data)
3. Send zero-length terminator
4. Read verdict: stream: OK\0 or stream: <virus_name> FOUND\0

Fail-Open Design

If ClamAV is unavailable (container not running, network error, timeout), the scan returns { clean: true, skipped: true } and logs a warning. This prevents ClamAV outages from blocking all email delivery.

Health Check

GET /scan/health returns the ClamAV connection status:

{ "clamav": "connected", "version": "ClamAV 1.3.0" }

or

{ "clamav": "unavailable", "error": "Connection refused" }

Configuration

See MTA System > ClamAV Sidecar for Docker setup and environment variables.

Feedback Loops

Spam complaints from ISP feedback loops are linked back to campaign content scan results:

1. Resend/MTA webhook delivers a complaint event
2. resendWebhook.ts processes the complaint and looks up the campaign's content scan result
3. Complaint count is incremented on the contentScanResults record
4. This data enables future pattern learning and complaint rate tracking per campaign

Integration Summary

Package Structure

packages/email-scanner/src/
├── content/              # Content analysis (pure TS, Convex-safe)
│   ├── index.ts          # scanContent() orchestrator
│   ├── spamKeywords.ts   # 40+ weighted spam patterns
│   ├── phishingUrls.ts   # URL shorteners, anchor/href mismatch
│   ├── homoglyphs.ts     # Unicode spoofing detection
│   ├── prohibitedContent.ts  # Advance fee fraud, credential phishing
│   └── subjectAnalysis.ts    # ALL CAPS, excessive punctuation
├── files/                # File type validation (pure TS)
│   ├── index.ts          # validateFile() orchestrator
│   ├── magicBytes.ts     # Binary header detection
│   ├── doubleExtension.ts    # invoice.pdf.exe detection
│   └── filePolicy.ts     # Allowlist/blocklist engine
├── urls/                 # URL reputation (uses fetch)
│   ├── index.ts          # checkUrlReputation() orchestrator
│   ├── safeBrowsing.ts   # Google Safe Browsing API v4 client
│   └── cache.ts          # Abstract cache interface
├── clamav/               # ClamAV TCP client (Node.js net, MTA only)
│   ├── index.ts          # createClamClient() factory
│   ├── client.ts         # clamd INSTREAM protocol implementation
│   └── pool.ts           # Connection pooling
├── types.ts              # Shared types (ContentFlag, ScanResult, etc.)
└── index.ts              # Barrel export (excludes clamav/)

Key Files