Encrypted Queue and Audit

Encrypted Queue and Audit

Mailbridge maintains two separate SQLite concerns:

• data/mailbridge.db: audit events and their integrity chain
• secrets/secrets.db: active retry-queue metadata and per-message secret material

Raw queued mail is never stored in either database.

Encrypted retry files

Queued messages are serialized and encrypted under data/queue/:

1. Generate a random 32-byte per-message secret.
2. Derive an AES-256 key with HKDF-SHA256 using QUEUE_MASTER_KEY, the per-message secret, and the queue ID.
3. Encrypt the envelope sender, recipient, raw message, and target with AES-256-GCM.
4. Store the encrypted file with mode 0600.
5. Store the per-message secret and non-content metadata in secrets/secrets.db.

Decryption therefore requires both the queue file, the secrets database, and the configured master key.

Generate the master key with the interactive setup or:

openssl rand -base64 32 | tr -d '\n'

Changing QUEUE_MASTER_KEY while messages remain queued makes those messages unrecoverable.

Retry behavior

The queue processor handles up to 50 oldest messages per pass and prevents overlapping runs. For every attempt it records an audit event, delivers to either local SMTP or the selected outbound provider, and then:

• deletes the queue row and encrypted file after success
• deletes permanent failures after recording the failure
• increments attempts and stops the current batch after a temporary failure
• drops items that reached QUEUE_MAX_ATTEMPTS after recording the outcome

Audit privacy and integrity

Audit records include event type, direction, target, outcome, attempt number, status/error metadata, and HMAC-derived hashes of sender, recipient, and source IP. They do not store full raw message content.

Events form a signed chain derived from the queue master key, allowing the application to link successive audit entries. Old audit records are pruned according to AUDIT_LOG_RETENTION_DAYS.

Legacy migration

On startup, Mailbridge migrates older queue tables and databases into the encrypted file-backed design. Legacy plaintext queue rows are encrypted before the old table is removed. Current queue metadata found in the audit database is moved into secrets/secrets.db.

Back up data/, secrets/, and the master key together when queued-message recovery matters. Protect secrets/ more strictly than ordinary runtime data.