Security#

Who should read this: anyone reviewing Ferroma before exposing it to the internet, anyone changing authentication, TLS, mail policy or the storage layer, and any operator who needs to know what a Ferroma deployment does and does not defend against.

This document is the threat model and the control inventory. It states the assumptions, then walks each control — password hashing, tokens and sessions, login throttling, relay prevention, sender and recipient validation, SPF/DKIM/ DMARC, TLS, rate and size limits, HTML handling, path traversal, log hygiene and secrets management — with the real type, function and config key that implements it. It ends with a table mapping every control to its implementation site, and a "known gaps" section listing what Ferroma v1 deliberately does not defend against.

Status: mixed. Everything under §2–§7 and §11–§12 is implemented in ferroma-core, ferroma-auth, ferroma-storage and ferroma-mail and can be read there. Everything under §8 (SPF/DKIM/DMARC), §9 (Received: policy on inbound), §10 (HTML sanitisation) and the API-level controls is (planned): ferroma-smtp and ferroma-api are crate skeletons. The configuration keys, limits and error variants those sections name do exist.

1. Threat model#

1.1 What Ferroma is protecting#

1.2 Who the adversaries are#

1.3 Explicit non-assumptions#

• The network is hostile. SMTP and IMAP on the public internet are plaintext
  by default and TLS is opportunistic, so message content is assumed readable by
  a passive observer on port 25. TLS on submission (587) and IMAP (993) is what
  protects credentials and content that matter.
• Received:, From:, HELO and every display name are attacker-controlled.
  They are parsed, stored and displayed, never used to make an authorisation
  decision.
• The database is trusted; the filesystem paths in it are not. Both stores
  re-validate every relative path they are handed — §12.
• One process, one host. Multi-node deployments are (planned) and the
  event bus does not cross processes (architecture.md §6).

2. Passwords#

2.1 Argon2id parameters#

crates/ferroma-auth/src/password.rs:

impl Default for Argon2Params {
    fn default() -> Self {
        // OWASP 2024: m=19456 KiB (19 MiB), t=2, p=1.
        Argon2Params { memory_kib: 19_456, iterations: 2, parallelism: 1 }
    }
}

The stored form is a PHC string, which is why the parameters travel with the hash:

$argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>

The requirement this satisfies is offline resistance: users.password_hash may end up in a backup, a database dump or a SQL injection result, and 19 MiB × 2 passes makes a dictionary attack cost real money per guess.

2.2 Verification#

pub fn verify(&self, password: &str, stored: &str) -> bool {
    match PasswordHash::new(stored) {
        Ok(parsed) => Argon2::default().verify_password(password.as_bytes(), &parsed).is_ok(),
        Err(_) => false,
    }
}

Two deliberate properties:

• A wrong password and an unparseable stored hash both return false. A
  corrupted row cannot be probed for information by comparing error messages.
• Verification is constant-time with respect to the hash, which is the
  argon2 crate's guarantee. The comparison of the derived key uses the
  constant-time subtle path inside the crate.

2.3 Transparent rehashing#

PasswordHasher::needs_rehash(stored) compares the parameters recorded in the PHC string with the current ones, and AuthService::login re-hashes the password while it holds the plaintext:

if self.hasher.needs_rehash(&user.password_hash) {
    match self.hash_password(password).await { … }
}

A failed upgrade is logged at warn and does not fail the login. So the parameter set can be raised later and the whole database upgrades itself over time, without a migration and without locking anyone out. Argon2Params::stored_params reads the parameters out of an existing hash, for auditing.

2.4 Password policy#

validate_password enforces the length bounds, and strength(password) -> u8 provides a score for the UI:

There is no composition rule (no "must contain a digit") because length is the property that matters and composition rules push users toward Password1!. There is no breach-corpus check — see §14.

AuthService::change_password revokes every other session: changing a password is the gesture a user makes when they suspect compromise, and leaving other sessions alive would defeat it.

2.5 Login failure accounting#

3. Access tokens, refresh tokens and rotation-based theft detection#

3.1 Two token types#

Why both: a stateless access token keeps the hot path free of a database round trip, and a short lifetime bounds the damage of a leaked one. An opaque refresh token is one the server can actually revoke, which a JWT fundamentally is not.

3.2 The access token's claims and their checks#

Claims / AccessClaims in crates/ferroma-auth/src/token.rs:

{ "sub": "7", "sid": 12, "typ": "access", "iss": "mail.example.com",
  "iat": 1789000000, "exp": 1789003600, "jti": "9f2c41…" }

TokenService::verify_access_at checks, in this order:

The ordering is the point: the signature is verified before any attacker-controlled claim is deserialised into a struct, and the HMAC comparison is constant-time (mac.verify_slice, backed by subtle). There is no alg-driven dispatch to confuse.

jti is a per-token UUID, so an individual token can be identified in a log without logging the token.

3.3 Rotation-based theft detection#

Every refresh rotates: the presented session is revoked and a replacement of the same kind is opened.

// crates/ferroma-auth/src/service.rs
if session.revoked_at.is_some() {
    // Reuse of a revoked token: assume compromise and burn the family.
    let revoked = self.repos.sessions.revoke_all_for_user(user_id).await?;
    tracing::warn!(user_id = …, session_id = session.id, revoked,
                   "revoked refresh token reused; all sessions revoked");
    return Err(FerromaError::Unauthorized(
        "refresh token was already used; all sessions have been revoked".into(),
    ));
}

The reasoning: an honest client presents a refresh token exactly once and throws it away. If a token is presented twice, either the client is buggy or two parties hold it — and the server cannot tell which. Revoking the whole family is the conservative answer, and it is the standard refresh-token-rotation pattern.

  login      ──► refresh_1 (stored as a hash in sessions)
  refresh    ──► refresh_1 revoked, refresh_2 issued
  refresh_2  ──► fine
  attacker presents refresh_1
             ──► "already used" ⇒ revoke every session of the user
             ──► the legitimate client's refresh_2 stops working too
             ──► the user is forced to log in again, and the theft is visible in the log

AuthService::refresh also refuses an expired session (unauthorized("refresh token expired")) and a disabled account (unauthorized("account disabled")).

3.4 Why the hash, not the token#

sessions.token_hash holds hash_token(raw) — SHA-256, lower-case hex, from crates/ferroma-auth/src/token.rs:

SHA-256 of a raw token, lower-case hex. The only form ever written to the database.

A plain SHA-256 rather than Argon2 is correct here and not a shortcut: the input is 32 bytes of CSPRNG output, so there is no dictionary to attack and no work-factor to add. What matters is that a database dump does not contain a directly usable refresh token.

looks_like_opaque_token(value) exists so log scrubbing can recognise a token by its prefix (rt_ or st_) without knowing its value.

3.5 api.jwt_secret#

TokenService::from_config uses api.jwt_secret when it is set and non-blank. When it is not:

tracing::warn!(
    "api.jwt_secret is not configured: generating an ephemeral secret. \
     Every restart will invalidate all sessions. Set FERROMA_JWT_SECRET in production."
);

and has_ephemeral_secret() returns true so a caller can refuse to serve in that state. docker-compose.yml and docker-compose.prod.yml both require it (${FERROMA_JWT_SECRET:?set FERROMA_JWT_SECRET in .env}), and .env.example gives the generation command:

openssl rand -base64 48

HS256 is a symmetric signature, so the secret is as sensitive as every session it signs. See §13.

4. Sessions and device revocation#

4.1 The sessions row#

kind is one of web, api, client, imap, smtp (enforced by sessions_kind_known), so an IMAP session and a Webmail session are distinguishable and independently revocable. SessionKind::is_refreshable() marks the kinds that may use /auth/refresh.

Lifecycle:

A valid signature is not enough. authenticate checks the session row after verifying the token, which is what makes revocation take effect immediately rather than when the access token expires. sessions_expiry_idx is partial on revoked_at IS NULL so the sweeper does not scan dead rows.

4.2 Devices#

devices is per installation, keyed (user_id, device_uid) where device_uid is client-generated and stable. device_uid is validated: non-empty and at most 128 characters (AuthService::register_device).

Revoking a device is the remote-wipe gesture from specification §33:

pub async fn revoke_device(&self, device_id: DeviceId) -> Result<u64>

1. marks the device revoked (devices.revoked_at),
2. revokes every session belonging to it,
3. publishes Event::device_revoked(device_id, user_id) so a live WebSocket for
   that device disconnects (fcp.md §9).

The revoked client's next request is 401. Revoking the device you are calling from is allowed and takes effect immediately — a user who has lost a laptop must be able to cut it off from any other device, including one that looks like it.

4.3 Idle sessions#

client.session_idle_days (90) is the policy for how long a device session may go unused before it is revoked. It is enforced by a periodic sweep, not by the expires_at column: the refresh token's own api.refresh_token_ttl_secs (30 days) is the hard bound, and the idle policy catches a device that refreshes forever but is never actually used.

5. Login throttling and lockout#

Two independent mechanisms, checked in this order in AuthService::login.

5.1 Per-source-IP, checked before any expensive work#

if let Some(ref ip_text) = ip_str {
    let failures = self.repos.login_attempts
        .count_failures_for_ip(ip_text, now - self.failure_window).await?;
    if failures >= i64::from(self.limits.max_failed_logins) * 3 {
        tracing::warn!(ip = %ip_text, failures, "login throttled by source address");
        self.record_attempt(&email, ip_str.as_deref(), "password", false).await;
        return Err(FerromaError::RateLimited);
    }
}

The threshold is three times the per-account threshold, because one NAT or office egress address can legitimately contain more than ten users. The check happens before the user lookup and before Argon2, so a credential flood cannot spend 19 MiB and two passes per request from a single source. That ordering is the whole reason this block is first.

failure_window is set by AuthService::with_failure_window, so tests can pin it.

5.2 Per-account lockout#

Both are 429 rate_limited over HTTP (api.md §1.3) and 454 4.7.0 over SMTP (smtp.md §8).

5.3 What is deliberately identical#

The comment in the code is explicit: "Unknown account: same message and same cost profile as a wrong password." An attacker cannot enumerate accounts through the login endpoint, and each attempt costs one Argon2 verification either way — which is also why the throttle above has to exist.

The one place the server does distinguish is the audit log, where a disabled account produces "login refused: account disabled". That is for the operator, not for the caller.

5.4 Retention#

login_attempts grows with every attempt. login_attempts_created_idx on (created_at) exists for the retention sweep that deletes by age. Without it the table is the largest in the schema on a busy server.

6. Open-relay prevention, sender and recipient validation#

6.1 Relay policy#

Stated in ../AGENTS.md §4.6 and specification §9.4, and specified in full in smtp.md §6:

  recipient domain is local  →  accept (quota and limits apply)
  recipient domain is remote →  a successful AUTH is required first

There is no configuration key that turns relaying on. The safe behaviour is unreachable-by-typo, which is the difference between a policy and a suggestion.

6.2 Recipient validation#

RCPT TO is resolved through the database, not through a filesystem guess:

1. Domain: DomainsRepository::find_by_name(normalise_domain(domain)), and
   domains.enabled must be true. Unknown or disabled ⇒ 550 5.1.2.
2. Local part: MailboxesRepository::find_by_address(domain, local_part) —
   mailboxes_address_key (domain_id, local_part) is the index. Missing ⇒ try
   AliasesRepository, then domains.catch_all; still missing ⇒ 550 5.1.1.
3. mailboxes.enabled must be true; a disabled address is 550 5.1.1.
4. Recipient count against limits.max_recipients ⇒ 452 4.5.3 when exceeded.

Both lookups use the lower-cased form (EmailAddress::to_lowercase, normalise_domain), and the schema enforces it: mailboxes_local_lowercase CHECK (local_part = lower(local_part)), domains_name_lowercase CHECK (name = lower(name)), users_email_lowercase CHECK (email = lower(email)). Case-insensitivity is a correctness requirement and a security one: two rows differing only in case would make "who is this address" ambiguous.

6.3 Sender validation and address syntax#

MAIL FROM is parsed by ferroma_core::EmailAddress::parse, which is strict on purpose. validate_local_part and validate_domain reject, among others:

Length bounds: MAX_LOCAL_PART_LEN 64, MAX_DOMAIN_LABEL_LEN 63, MAX_DOMAIN_LEN 255.

A local From must be owned by the authenticated user. An authenticated submission with a MAIL FROM in a local domain may only name a mailboxes row whose user_id is the session's; otherwise 550 5.7.1 Sender address rejected: not owned by user. Without that check, any user could send as any other user in the domain, which is the sender-forgery problem that SPF and DMARC exist to detect at the receiving end.

6.4 Aliases and catch-all#

aliases.target is a full address, or a bare local part meaning "same domain". domains.catch_all is a local part that receives mail addressed to a non-existent mailbox. Both are admin-controlled, never user-controlled, and both are resolved after the direct mailbox lookup so that a catch-all can never shadow a real address.

The catch-all is a spam-amplification surface by nature: it accepts mail for arbitrary local parts. It is off by default (catch_all is NULL) and should be turned on only with a reason.

7. TLS#

7.1 Policy#

tls.enabled gates all of it. Config::validate() refuses to start when smtp.smtps_port != 0 or imap.imaps_port != 0 or api.tls_port != 0 while tls.enabled = false — a configured TLS port with TLS off is a listener that would serve plaintext on a port clients believe is encrypted.

7.2 rustls only#

Every TLS-capable dependency in the workspace is pinned to rustls: rustls, tokio-rustls, rustls-pemfile, rustls-pki-types, webpki-roots, and reqwest with default-features = false, features = ["rustls-tls", …]. AGENTS.md §1.1 forbids adding a crate that pulls in native-tls, openssl or schannel, and gives two reasons that agree: the Windows schannel stack on this development host fails with SEC_E_NO_CREDENTIALS, and a memory-safe TLS implementation with an explicit cipher-suite policy is the right choice for a server that terminates SMTP, IMAP and HTTPS itself.

7.3 Certificate handling#

self_signed_fallback is explicitly local-development and CI only. It is generated with rcgen, and it is gated twice: tls.allow_insecure_dev_mode must be true, and Config::validate() refuses the combination otherwise:

tls.self_signed_fallback requires tls.allow_insecure_dev_mode = true

An MX with a self-signed certificate cannot be validated by any sending server, so every outbound TLS handshake fails and — worse — the operator may be tempted to turn verification off somewhere else.

7.4 What TLS does and does not buy#

• Submission (587/465) and IMAP (993): credentials and content are protected
  on the wire. This is the security boundary for user data.
• Inbound port 25: opportunistic. A sending MTA that does not do TLS sends
  plaintext, and Ferroma must accept it or lose the mail. Message content on port
  25 should be assumed readable by a network observer. End-to-end encryption is
  the only defence, and Ferroma does not implement it.
• MTA-STS raises the bar for senders that honour it; the DNS record and the
  policy file are specified in deployment.md §2.

7.5 require_tls_for_auth and require_tls_for_login#

Both default to false so a bare cargo run works without certificates, and both are set to true in docker-compose.prod.yml:

FERROMA__SMTP__REQUIRE_TLS_FOR_AUTH: 'true'
FERROMA__IMAP__REQUIRE_TLS_FOR_LOGIN: 'true'

AUTH PLAIN, AUTH LOGIN and IMAP LOGIN all send the password in base64 or plaintext. Over an unencrypted socket, a passive observer reads it. A production deployment that leaves these false is one tcpdump away from an account takeover, and the refusal is explicit rather than silent: 538 5.7.11 Encryption required for requested authentication mechanism over SMTP, NO [PRIVACYREQUIRED] over IMAP.

Config::allows_plaintext_auth() answers the question for the whole config without re-deriving it.

8. SPF, DKIM and DMARC#

(planned) — ferroma-smtp's spf, dkim and dmarc modules are specified but not implemented. The configuration keys and their defaults exist in [dkim] and [policy] of config/ferroma.toml and in DkimConfig / PolicyConfig in crates/ferroma-core/src/config.rs.

8.1 Inbound#

dmarc_failure_action defaults to quarantine rather than reject for a specific reason: a DMARC p=reject evaluated against a forwarded message — a mailing list, an alumni forwarder — routinely fails SPF and DKIM and is legitimate. Quarantine puts it in Junk where the user can find it; reject loses it. An operator who has measured their forwarding tolerance can raise it.

policy.spf_max_lookups (10) is the RFC 7208 §4.6.4 limit; it exists because an SPF record can be built to force an unbounded number of DNS lookups, which is a denial-of-service vector against both Ferroma and the resolver.

8.2 Outbound#

From being signed is not optional: a DKIM signature that does not cover From can be replayed with a different sender, which is exactly what DMARC alignment checks. headers_to_sign includes it first, and the list matches the specification §16 flow (canonicalise → header hash → body hash → sign → DKIM-Signature).

The private key must never be logged, exported in an API response beyond the public record, or included in a backup that is less protected than the database. GET /api/v1/domains/:id/dkim returns only the public record:

{ "selector": "default", "record_name": "default._domainkey.example.com", "record_type": "TXT", "record_value": "v=DKIM1; k=rsa; p=MIIBIjANBg…" }

8.3 DNS security relevant to mail#

[dns] configures the resolver Ferroma itself uses: explicit resolvers, timeout_secs (5), attempts (3), cache_ttl_secs (300), negative_ttl_secs (60), tcp_fallback. Use a resolver you trust: an attacker who controls the resolver can forge the MX record for a recipient domain and receive the mail you are delivering.

9. Limits and the request surface#

Full per-limit tables are in smtp.md §7, imap.md §10 and api.md §1.6. Summary of the security-relevant ones:

Malformed input must be a limit failure, not a panic. ParseLimits:

pub struct ParseLimits { pub max_depth: usize, pub max_parts: usize,
                        pub max_part_size: usize, pub max_message_size: usize }
// defaults: 20 / 200 / 26214400 / 26214400

ParsedMessage::parse_with_limits returns FerromaError::LimitExceeded rather than recursing without bound, and ParseLimits::from_limits(&Limits) derives the values from the platform configuration so there is one place to change them. AGENTS.md §4.4 forbids unwrap() on peer input, and the parsers are the reason.

10. Message handling: MIME, HTML and escape hatches#

10.1 Total parsing#

Parsing is total: any byte string produces a ParsedMessage. The only errors are the explicit resource limits in ParseLimits, because a mail server that rejects a message it cannot render drops real mail.

— crates/ferroma-mail/src/message.rs

This is a security property as much as a usability one. A parser that can fail on a class of input creates a class of mail that is silently dropped, which an attacker can use to suppress a message (a password reset, say) by appending a byte sequence. MIME decoding is likewise permissive: decode_base64, decode_quoted_printable and decode_charset return best-effort results with explicit errors only for genuinely undecodable input.

10.2 HTML sanitisation#

_(planned)_ — html_body is promised as sanitised server-side by api.md §5.4, and the requirement that a client still render it in a sandbox is stated there too. There is no sanitisation code in ferroma-mail or ferroma-api yet, and no security.sanitize_html key exists in config/ferroma.toml. Every statement in this section is therefore an obligation on the implementation, not a description of it.

Until it exists, the rules are:

• Never render raw html_body into a privileged origin. The Webmail and
  Admin SPAs are served from the same origin as the API, so an unsanitised HTML
  body is a stored XSS against a session that can call the admin API.
• Render in a sandboxed iframe with sandbox="allow-popups" and no
  allow-scripts/allow-same-origin, and block remote content by default so a
  tracking pixel cannot confirm that a message was read.
• The official client is not a browser. Its reader should not execute
  anything from a message; HTML rendering goes through the same sanitiser, and
  when the sanitiser is absent it falls back to the text part.
• Attachments are never rendered inline as HTML. Content-Type is
  attacker-controlled; text/html on an attachment is not a reason to run it.
  attachments.is_inline and content_id are display hints, not trust.

The sanitiser, when it lands, must strip <script>, <style> with expression, <iframe>, <object>, <embed>, <form>, <base>, <meta http-equiv>, all on* attributes and all javascript:/data: URLs, and it must run server-side (the client cannot be trusted to do it and the API feeds several clients).

10.3 What Ferroma does not do with message content#

• It does not execute anything from a message.
• It does not follow a link from a message, ever — no prefetching, no link
  unfurling, no image proxying that fetches remote content.
• It does not deserialise a message into a type that can construct a path, a SQL
  fragment or a shell argument. Message content reaches the database as bound
  parameters (sqlx::query_as, never sqlx::query! and never string
  interpolation) and the filesystem only through sanitize_component (§12).
• It does not store attachments under a name the sender chose. The blob path is
  the SHA-256 of the content; attachments.filename is metadata for display and
  is sanitised before it reaches a Content-Disposition header.

11. Path-traversal defences in the Maildir and the blob store#

They exist and they are the reason a compromised database row cannot read /etc/passwd. Full detail in storage.md §7.

11.1 sanitize_component#

// crates/ferroma-storage/src/maildir.rs
pub fn sanitize_component(component: &str) -> Result<String> {
    let trimmed = component.trim();
    if trimmed.is_empty() { return Err(StorageError::Invalid("empty path component".into())); }
    if trimmed == "." || trimmed == ".." {
        return Err(StorageError::Invalid(format!("invalid path component: {trimmed}")));
    }
    if trimmed.contains('/') || trimmed.contains('\\') || trimmed.contains('\0') {
        return Err(StorageError::Invalid(format!("path component contains a separator: {trimmed}")));
    }
    if trimmed.contains(':') {
        return Err(StorageError::Invalid(format!("path component contains a colon: {trimmed}")));
    }
    Ok(trimmed.to_string())
}

Applied to the domain, the local part (in Maildir::mailbox_dir), the hostname (in Maildir::new) and every segment of a folder name (in maildir_folder_name). A test enumerates the interesting inputs: ["..", ".", "a/b", "a\\b", "", " ", "a:b", "x\0y"] must all be rejected.

The : rejection is not cosmetic: it is the Maildir info separator, and on Windows it introduces an NTFS alternate data stream (imap.md §10).

11.2 absolute#

Both stores expose one, and it is the only function that turns a stored storage_path into a real path:

// Maildir::absolute and AttachmentStore::absolute
if candidate.is_absolute() {
    return Err(StorageError::Invalid(format!("storage path must be relative: {relative_path}")));
}
for component in candidate.components() {
    match component {
        std::path::Component::ParentDir
        | std::path::Component::RootDir
        | std::path::Component::Prefix(_) => {
            return Err(StorageError::Invalid(format!(
                "storage path escapes the mail root: {relative_path}"
            )));
        }
        _ => {}
    }
}
Ok(self.root.join(candidate))

Every read, write, delete, set_flags and exists calls it first. Tested:

assert!(m.absolute("../../etc/passwd").is_err());
assert!(m.absolute("/etc/passwd").is_err());
assert!(s.absolute("../../secret").is_err());
assert!(!s.exists("../../secret"));

Component::Prefix(_) is what stops C:\Windows\... on Windows from being treated as relative and joined onto the root.

11.3 The residual risk#

Both gates validate the string. A symlink placed inside the mail root by another process is not detected, because std::fs follows symlinks. Ferroma does not create symlinks anywhere, and the mail root should be owned by the service user with no other writer — Dockerfile runs as uid 10001 (ferroma) and chown -R ferroma:ferroma /var/lib/ferroma. An attacker who can write into the mail root has already won by other means, but it is worth stating that this control is about a compromised database, not a compromised host.

12. Logging: what is and is never recorded#

12.1 Never logged#

AGENTS.md §4.7 and specification §40:

crates/ferroma-core/src/logging.rs states it in the crate documentation:

Passwords, AUTH tokens, private keys and full message bodies are never logged.

12.2 What is logged#

The SMTP session fields from specification §40 are the ones that make an incident investigable without reading anyone's mail:

connection_id   remote_ip   helo   authenticated_user
sender          recipient   message_id   result   duration

connection_id is a UUID that also appears in the Received: header Ferroma prepends, so a log line and a header can be joined (smtp.md §10) — an operator can answer "where did this message come from" without opening the message.

12.3 Log configuration#

logging::build_filter keeps the operator's directive and appends the noisy-crate defaults only for targets the directive does not already mention, so sqlx=debug is honoured rather than overridden.

12.4 Audit trail#

audit_logs is separate from the operational log and is meant to be durable: actor_user_id (FK ON DELETE SET NULL, so the row survives the account), action, target_type, target_id, ip, user_agent, details JSONB, created_at. Admin actions — creating a user, deleting a domain, revoking a device, changing a setting — belong here, not in a tracing line that rotates away.

13. Secrets management#

Practices the repository already enforces:

• Compose fails fast on a missing secret. ${FERROMA_JWT_SECRET:?set FERROMA_JWT_SECRET in .env} and ${POSTGRES_PASSWORD:?…} mean a deployment with no secret does not start, rather than starting with a default.
• The config archive excludes credentials. tar … --exclude='*.env' --exclude='credentials*'.
• .env.example carries placeholders and the generation command, never a real value.
• The database container is not published. docker-compose.yml uses expose: ['5432'] on the internal network, not a host port mapping.
• Configuration is mounted read-only. ./config/ferroma.toml:/etc/ferroma/ferroma.toml:ro.
• The container runs unprivileged. USER ferroma, uid 10001, with /var/lib/ferroma chowned to it.

Rotation, when it is needed:

14. Control → implementation map#

Rows marked (planned) follow from the same source (FerromaError, Limits, ApiConfig) and are described in api.md and smtp.md.

15. Known gaps#

Deliberate omissions from Ferroma v1. Each is a decision, not an oversight; the mitigation is what an operator should do instead.

15.1 No antivirus or malware scanning#

Ferroma does not scan attachments. There is no ClamAV integration, no clamd socket, no virus_scan config key. An attachment is stored because it arrived; whether it is malicious is the recipient's problem.

Why it is acceptable for v1: an antivirus engine is a large, stateful dependency with its own update channel and its own failure modes, and a scanner that silently stops updating is worse than no scanner because it creates false confidence. It is on the extensibility list (specification §57, "病毒扫描").

Operator mitigation: run a clamd and scan the mail root out of band, or route inbound through a gateway. Block executable attachment types at the receiving client, which is where the user actually opens them.

15.2 No Bayesian or heuristic spam filter#

There is no content classifier, no X-Spam-Score, no spamassassin integration. The only inbound filtering is:

• SPF/DKIM/DMARC verdicts (planned) — these authenticate the sender, they do not
  classify content;
• Junk as a folder with special_use = \Junk, and DMARC quarantine filing
  into it;
• rate limits and connection limits, which bound volume but not content.

Why: a Bayesian filter needs a corpus, per-user training and a tuning loop, and a badly tuned one produces false positives that lose real mail — which specification §54 identifies as the risk. Shipping a filter that silently eats invoices is worse than shipping none.

Operator mitigation: put a filtering gateway in front, or use a hosted filtering service. The Junk folder and the \Junk special-use marker are already in the schema (special_use CHECK), so a filter can be added later without a migration.

15.3 No OIDC, no OAuth2, no 2FA#

Specification §15 lists OAuth2, OIDC and 2FA under "后续" (later) and §57 repeats them. Ferroma v1 supports password authentication only, over:

• POST /api/v1/auth/login and /api/v1/client/auth/login,
• SMTP AUTH PLAIN / AUTH LOGIN,
• IMAP LOGIN / AUTHENTICATE PLAIN / AUTHENTICATE LOGIN.

There is no TOTP, no WebAuthn, no recovery codes, no mfa_required flag. A phished password is a full account takeover, bounded only by the login throttle and by limits.max_failed_logins.

Operator mitigation: for the Webmail surface, put an SSO proxy in front that performs 2FA and passes an authenticated identity; for SMTP/IMAP there is no honest mitigation other than app passwords managed outside Ferroma. Do not describe a Ferroma deployment as "2FA-protected".

15.4 No cross-process event bus#

EventBus is one in-process object (crates/ferroma-events/src/bus.rs). There is no Redis, NATS or PostgreSQL-LISTEN/NOTIFY backend.

Consequences:

So the failure mode is a delayed notification, not lost data — and that is the property that makes a single-process bus acceptable for v1. But it means horizontal scaling is not a configuration change: running two replicas behind a load balancer gives users a realtime experience that depends on which replica they landed on.

Why: a broker is another stateful service to operate, secure and monitor, and the specification's first-version Docker stack (§41) is explicitly Ferroma plus PostgreSQL, with Redis under "后期".

Operator mitigation: run one ferroma process. If you need more capacity, scale the database and the storage first; both are likelier bottlenecks than the event fan-out.

15.5 Smaller gaps, stated plainly#

16. Related documents#