# sovite v0.2.0 - Table of Contents

> A modern, secure Mail Transfer Agent written in Elixir/OTP.

## Pages

- [Sovite](readme.md)
- [Sovite Roadmap](roadmap.md)
- [Sovite Structure](structure.md)
- [Configuration](configuration.md)
- [Logging and Telemetry](logging.md)
- [Security Model](security-1.md)
- [Security Policy](security-2.md)

## Modules

- Validators
  - [Sovite.Validators](Sovite.Validators.md): Syntax validators for the identifiers that appear in SMTP envelopes.

- Net
  - [Sovite.Net](Sovite.Net.md): IP address and CIDR network helpers.

- Message
  - [Sovite.Message.AddressList](Sovite.Message.AddressList.md): Rewrites the addresses in an RFC 5322 address list (the value of
`From:`, `To:`, `Cc:`, and similar fields) and keeps every other byte:
display names, comments, groups, and folding.
  - [Sovite.Message.Date](Sovite.Message.Date.md): RFC 5322 §3.3 date-time formatting, as used in `Date:` and `Received:`.

  - [Sovite.Message.Headers](Sovite.Message.Headers.md): The header section of a message (RFC 5322 §2.2), as a list of fields
that keeps every byte of the original, so unchanged fields are passed
through exactly (folding and all), which matters for signatures.
  - [Sovite.Message.MessageID](Sovite.Message.MessageID.md): Builds `Message-ID:` values (RFC 5322 §3.6.4).
  - [Sovite.Message.Received](Sovite.Message.Received.md): Builds `Received:` trace header fields (RFC 5321 §4.4).
  - [Sovite.Message.Trace](Sovite.Message.Trace.md): Trace header fields and the loop checks that read them.

- DNS
  - [Sovite.DNS](Sovite.DNS.md): DNS lookups through a pluggable `Sovite.DNS.Resolver`.

  - [Sovite.DNS.InetRes](Sovite.DNS.InetRes.md): Default `Sovite.DNS.Resolver`, built on OTP's `:inet_res`.
  - [Sovite.DNS.MX](Sovite.DNS.MX.md): Finds the hosts that accept mail for a domain (RFC 5321 §5.1).
  - [Sovite.DNS.Resolver](Sovite.DNS.Resolver.md): Behaviour for DNS resolvers.

- LDAP
  - [Sovite.LDAP](Sovite.LDAP.md): A small layer over OTP's `:eldap`: connecting with StartTLS or LDAPS,
binding, searching, and running all of it in a process of its own.
  - [Sovite.LDAP.Filter](Sovite.LDAP.Filter.md): Parses RFC 4515 LDAP search filters into `:eldap` filters, with
placeholders filled in after parsing.

- SASL
  - [Sovite.SASL](Sovite.SASL.md): SASL authentication (RFC 4422), server and client side.
  - [Sovite.SASL.Backend](Sovite.SASL.Backend.md): Behaviour for credential backends used by `Sovite.SASL.Server`.
  - [Sovite.SASL.Backend.Introspection](Sovite.SASL.Backend.Introspection.md): A `Sovite.SASL.Backend` for `OAUTHBEARER`: checks bearer tokens with
OAuth 2.0 token introspection (RFC 7662) at the identity provider.
  - [Sovite.SASL.Backend.LDAP](Sovite.SASL.Backend.LDAP.md): A `Sovite.SASL.Backend` that checks passwords by binding to an LDAP
directory as the user.
  - [Sovite.SASL.Backend.Static](Sovite.SASL.Backend.Static.md): A `Sovite.SASL.Backend` that reads users from a file, one per line
  - [Sovite.SASL.Dovecot](Sovite.SASL.Dovecot.md): Hands SASL authentication to a Dovecot auth server, over its client
protocol (version 1.2), like Postfix's `smtpd_sasl_type = dovecot`.
  - [Sovite.SASL.Login](Sovite.SASL.Login.md): The `LOGIN` mechanism (draft-murchison-sasl-login): the server asks for
`Username:` then `Password:`. Obsolete, but some clients (older Outlook
versions) offer nothing else. Only safe over TLS.
  - [Sovite.SASL.OAuthBearer](Sovite.SASL.OAuthBearer.md): The `OAUTHBEARER` mechanism (RFC 7628): the client sends an OAuth 2.0
bearer token (RFC 6750) instead of a password.
  - [Sovite.SASL.Password](Sovite.SASL.Password.md): Stored password hashes: creating them and checking passwords against
them.
  - [Sovite.SASL.Plain](Sovite.SASL.Plain.md): The `PLAIN` mechanism (RFC 4616): `[authzid] NUL authcid NUL password`
in one message. Only safe over TLS.
  - [Sovite.SASL.ScramSHA256](Sovite.SASL.ScramSHA256.md): The `SCRAM-SHA-256` mechanism (RFC 5802, RFC 7677).
  - [Sovite.SASL.Server](Sovite.SASL.Server.md): Runs the server side of a SASL exchange against a `Sovite.SASL.Backend`.

- Queue
  - [Sovite.Queue.Backoff](Sovite.Queue.Backoff.md): Retry delays for deferred messages (RFC 5321 §4.5.4.1).
  - [Sovite.Queue.Entry](Sovite.Queue.Entry.md): The delivery state of a queued message: its envelope, plus the
`Sovite.Queue.Record`s appended so far, replayed in order.
  - [Sovite.Queue.Envelope](Sovite.Queue.Envelope.md): The envelope of a queued message: who sent it, to whom, and how it
arrived.
  - [Sovite.Queue.ID](Sovite.Queue.ID.md): Queue IDs: 14 characters from `[0-9A-Za-z]`, safe in file names.
  - [Sovite.Queue.Record](Sovite.Queue.Record.md): Delivery records, appended to a queue file after the message by
`Sovite.Queue.Spool.append/3`.
  - [Sovite.Queue.Spool](Sovite.Queue.Spool.md): Durable storage for queued messages.

- Listener
  - [Sovite.Listener](Sovite.Listener.md): A TCP listener with an acceptor pool and connection limits.
  - [Sovite.Listener.Handler](Sovite.Listener.Handler.md): Behaviour for the process that serves one accepted connection.

- SMTP
  - [Sovite.SMTP](Sovite.SMTP.md): SMTP (RFC 5321) building blocks.
  - [Sovite.SMTP.Client](Sovite.SMTP.Client.md): An SMTP client (RFC 5321) for relaying messages to another server.
  - [Sovite.SMTP.Command](Sovite.SMTP.Command.md): Parses SMTP command lines (RFC 5321 §4.1).
  - [Sovite.SMTP.DataDecoder](Sovite.SMTP.DataDecoder.md): Streaming decoder for SMTP `DATA` content (RFC 5321 §4.1.1.4, §4.5.2).
  - [Sovite.SMTP.DataEncoder](Sovite.SMTP.DataEncoder.md): Streaming encoder for SMTP `DATA` content, the inverse of
`Sovite.SMTP.DataDecoder`.
  - [Sovite.SMTP.Reply](Sovite.SMTP.Reply.md): An SMTP reply: a code, an optional enhanced status code (RFC 3463), and
one or more text lines.
  - [Sovite.SMTP.Server](Sovite.SMTP.Server.md): An SMTP server: a `Sovite.Listener` whose connections run
`Sovite.SMTP.Server.Session`.
  - [Sovite.SMTP.Server.Connection](Sovite.SMTP.Server.Connection.md): Runs a `Sovite.SMTP.Server.Session` on an accepted socket. Started by
`Sovite.Listener`; see `Sovite.SMTP.Server` for the public API.
  - [Sovite.SMTP.Server.Handler](Sovite.SMTP.Server.Handler.md): Behaviour for the application side of an SMTP server: policy decisions
and what happens to received messages.
  - [Sovite.SMTP.Server.Session](Sovite.SMTP.Server.Session.md): The SMTP server protocol as a state machine, without I/O.

- TLS
  - [Sovite.TLS](Sovite.TLS.md): TLS settings for mail servers and clients, following BCP 195 (RFC 9325).
  - [Sovite.TLS.ACME](Sovite.TLS.ACME.md): An ACME client (RFC 8555) for getting certificates from a CA such as
Let's Encrypt, with HTTP-01 challenges.
  - [Sovite.TLS.ACME.CSR](Sovite.TLS.ACME.CSR.md): Builds PKCS #10 certificate signing requests (RFC 2986) for ACME: the
first name as the subject's common name, and every name in a
subjectAltName extension request.

  - [Sovite.TLS.ACME.HTTPChallenge](Sovite.TLS.ACME.HTTPChallenge.md): Answers ACME HTTP-01 challenges (RFC 8555 §8.3): a `Sovite.Listener`
handler that serves `GET /.well-known/acme-challenge/<token>` from an
ETS table of `{token, key_authorization}` and answers everything else
with 404.
  - [Sovite.TLS.CertStore](Sovite.TLS.CertStore.md): Holds server certificates, picks one per connection by SNI (RFC 6066),
and reloads them when their files change.
  - [Sovite.TLS.Certificate](Sovite.TLS.Certificate.md): A certificate chain and its private key, loaded from PEM files.
  - [Sovite.TLS.DANE](Sovite.TLS.DANE.md): DANE certificate verification for SMTP (RFC 6698, RFC 7671, RFC 7672).

- Abuse
  - [Sovite.Abuse.Penalty](Sovite.Abuse.Penalty.md): Counts failures per key (for example failed logins per client address)
and bans a key for a while after too many of them.

- Local delivery
  - [Sovite.Maildir](Sovite.Maildir.md): Delivers messages into Maildir folders (https://cr.yp.to/proto/maildir.html).
  - [Sovite.Pipe](Sovite.Pipe.md): Runs an external command with a file as its standard input, for
delivery to programs such as `procmail`, `dovecot-lda`, or a list
manager.

- DSN
  - [Sovite.DSN](Sovite.DSN.md): Builds delivery status notifications (RFC 3464), the messages that tell
a sender their mail was not delivered (or not yet).

- Core
  - [Sovite](Sovite.md): Sovite, a Mail Transfer Agent written in Elixir/OTP.
  - [Sovite.Core.ACME](Sovite.Core.ACME.md): Keeps an ACME certificate (`[tls.acme]`) issued and renewed.
  - [Sovite.Core.Bounce](Sovite.Core.Bounce.md): The bounce service: tells senders about failed and delayed delivery.
  - [Sovite.Core.CLI](Sovite.Core.CLI.md): The `sovitectl` command line.
  - [Sovite.Core.Config](Sovite.Core.Config.md): Loads, validates, and stores the Sovite configuration file.
  - [Sovite.Core.Config.Error](Sovite.Core.Config.Error.md): A single configuration problem.
  - [Sovite.Core.Delivery](Sovite.Core.Delivery.md): Delivers one job (a message to a group of recipients with the same
destination). Runs in a task started by `Sovite.Core.QueueManager`.
  - [Sovite.Core.Logging](Sovite.Core.Logging.md): Configures logging from the `[log]` config section.
  - [Sovite.Core.Logging.FileHandler](Sovite.Core.Logging.FileHandler.md): `:logger` handler that writes to rotating log files, in the style of
pino-roll.
  - [Sovite.Core.Logging.JSONFormatter](Sovite.Core.Logging.JSONFormatter.md): `:logger` formatter that writes one JSON object per line.
  - [Sovite.Core.Lookup](Sovite.Core.Lookup.md): The interface routing uses to read Sovite's database tables
(`Sovite.Core.Repo.Tables.*`): a key goes in, a string value or nothing
comes out.
  - [Sovite.Core.QueueManager](Sovite.Core.QueueManager.md): Schedules queued messages for delivery, like Postfix's `qmgr`.
  - [Sovite.Core.Recipients](Sovite.Core.Recipients.md): Recipient expansion and validation.
  - [Sovite.Core.Repo](Sovite.Core.Repo.md): Sovite's database, through Ecto.
  - [Sovite.Core.Repo.Schemas.AccessRule](Sovite.Core.Repo.Schemas.AccessRule.md): An access rule for the restriction chains (`Sovite.Core.Restrictions`):
when the client address, `EHLO` name, sender, or recipient (`kind`)
matches `pattern`, take `action` (`ACCEPT`, `CONTINUE`, `REJECT`,
`DEFER`, `DISCARD`, `HOLD`, `WARN`, or a `4NN`/`5NN` reply code) with
optional `text`.

  - [Sovite.Core.Repo.Schemas.AddressRewrite](Sovite.Core.Repo.Schemas.AddressRewrite.md): An address rewrite: addresses matching `pattern` (a full address,
`@domain`, or a local part) become `replacement` (a full address,
`@domain` to change only the domain, or a local part to change only the
local part). `kind` says which addresses: `:sender`, `:recipient`, or
`:both`.

  - [Sovite.Core.Repo.Schemas.Alias](Sovite.Core.Repo.Schemas.Alias.md): An alias: mail for `address` goes to its destinations instead.
`address` is a full address, `@domain` (every address of the domain
that has no alias of its own), or a bare local part (for local domains).

  - [Sovite.Core.Repo.Schemas.AliasDestination](Sovite.Core.Repo.Schemas.AliasDestination.md): One address an alias delivers to.
  - [Sovite.Core.Repo.Schemas.BccRule](Sovite.Core.Repo.Schemas.BccRule.md): A BCC rule: messages whose sender (`kind: :sender`) or one of whose
recipients (`kind: :recipient`) matches `pattern` (a full address, or
`@domain`) are also sent to `address`.

  - [Sovite.Core.Repo.Schemas.Domain](Sovite.Core.Repo.Schemas.Domain.md): A domain this server handles, and its class (see
`Sovite.Core.Routing`): `:local`, `:aliased`, `:hosted`, or `:relay`.

  - [Sovite.Core.Repo.Schemas.Mailbox](Sovite.Core.Repo.Schemas.Mailbox.md): A mailbox in a virtual mailbox domain: `address`, or `@domain` to
accept every address of the domain.

  - [Sovite.Core.Repo.Schemas.RelocatedUser](Sovite.Core.Repo.Schemas.RelocatedUser.md): A user who moved: mail for `address` is rejected with `5.1.6` and
`new_location` (usually the new address).

  - [Sovite.Core.Repo.Schemas.SenderLogin](Sovite.Core.Repo.Schemas.SenderLogin.md): A sender address a user may use in `MAIL FROM`: a full address
(`sales@example.com`), every address at a domain (`@example.com`), or
any address (`*`).

  - [Sovite.Core.Repo.Schemas.SenderRelay](Sovite.Core.Repo.Schemas.SenderRelay.md): How mail from `sender` (an address, or `@domain`) leaves: through
`relayhost`, from `source_address`, logging in with `username` and
`password`. Each part is optional.
  - [Sovite.Core.Repo.Schemas.Transport](Sovite.Core.Repo.Schemas.Transport.md): A transport map entry: mail for `pattern` (an address, a domain,
`.domain` for its subdomains, or `*`) goes through `transport`, a
`Sovite.Core.Transport` specification.

  - [Sovite.Core.Repo.Schemas.User](Sovite.Core.Repo.Schemas.User.md): A user who can authenticate (SMTP AUTH), with the sender addresses
they may use.

  - [Sovite.Core.Repo.Tables.AccessRules](Sovite.Core.Repo.Tables.AccessRules.md): Access rules for the restriction chains, stored in Sovite's database
and managed with `sovitectl access`.
  - [Sovite.Core.Repo.Tables.AddressRewrites](Sovite.Core.Repo.Tables.AddressRewrites.md): Address rewrites stored in Sovite's database, managed with `sovitectl
rewrite` (see `Sovite.Core.Rewrite`).
  - [Sovite.Core.Repo.Tables.Aliases](Sovite.Core.Repo.Tables.Aliases.md): Aliases stored in Sovite's database, managed with `sovitectl alias`.
  - [Sovite.Core.Repo.Tables.BccRules](Sovite.Core.Repo.Tables.BccRules.md): BCC rules stored in Sovite's database, managed with `sovitectl bcc`
(see `Sovite.Core.Recipients.bcc/3`).
  - [Sovite.Core.Repo.Tables.DomainCache](Sovite.Core.Repo.Tables.DomainCache.md): Keeps the domains of `Sovite.Core.Repo.Tables.Domains` in `:persistent_term`, so
every recipient check can read them without a database query.
  - [Sovite.Core.Repo.Tables.Domains](Sovite.Core.Repo.Tables.Domains.md): Domains stored in Sovite's database, managed with `sovitectl domain`.
They add to the domains in the `[domains]` config section; a domain in
the config file wins over the same domain in the database.
  - [Sovite.Core.Repo.Tables.Mailboxes](Sovite.Core.Repo.Tables.Mailboxes.md): Mailboxes of virtual mailbox domains, stored in Sovite's database and
managed with `sovitectl mailbox`.
  - [Sovite.Core.Repo.Tables.RelocatedUsers](Sovite.Core.Repo.Tables.RelocatedUsers.md): Users who moved, stored in Sovite's database and managed with
`sovitectl moved`. Mail for them is rejected with `5.1.6` and
their new location.
  - [Sovite.Core.Repo.Tables.SenderRelays](Sovite.Core.Repo.Tables.SenderRelays.md): Sender-dependent relaying, stored in Sovite's database and managed
with `sovitectl sender-relay`: for a sender address or `@domain`, the
relay host, the source address to connect from, and the credentials
for the relay host.
  - [Sovite.Core.Repo.Tables.Transports](Sovite.Core.Repo.Tables.Transports.md): Transports stored in Sovite's database, managed with
`sovitectl transport`.
  - [Sovite.Core.Repo.Tables.Users](Sovite.Core.Repo.Tables.Users.md): Users stored in Sovite's database (`Sovite.Core.Repo`), and a
`Sovite.SASL.Backend` that authenticates against them.
  - [Sovite.Core.Restrictions](Sovite.Core.Restrictions.md): Restriction chains (`[restrictions]`): lists of checks run at each
stage of an SMTP session.
  - [Sovite.Core.Rewrite](Sovite.Core.Rewrite.md): Address rewriting.
  - [Sovite.Core.Router](Sovite.Core.Router.md): Decides, at delivery time, where each recipient's mail goes.
  - [Sovite.Core.Routing](Sovite.Core.Routing.md): The routing configuration (`[domains]`, `[routing]`, and the next-hop
settings of `[delivery]`) together with Sovite's routing tables in the
database, and the address helpers shared by rewriting
(`Sovite.Core.Rewrite`), recipient expansion (`Sovite.Core.Recipients`),
and next-hop selection (`Sovite.Core.Router`).
  - [Sovite.Core.SMTPHandler](Sovite.Core.SMTPHandler.md): The MTA's `Sovite.SMTP.Server.Handler`: relay control, restrictions,
authentication, recipient checks and expansion, and durable spooling.
  - [Sovite.Core.SenderCheck](Sovite.Core.SenderCheck.md): Sender login maps: which `MAIL FROM` addresses an authenticated user
may use.
  - [Sovite.Core.Supervisor](Sovite.Core.Supervisor.md): Root supervisor of the Sovite MTA.
  - [Sovite.Core.Telemetry](Sovite.Core.Telemetry.md): The catalog of `:telemetry` events emitted by Sovite, and the default
handler that turns them into log lines.
  - [Sovite.Core.Transport](Sovite.Core.Transport.md): Transport specifications: `transport:nexthop`.

