docs-audit: architecture, schema, security and the rest against the code

The owner's "проверь, что документация актуальна с кодом" (2026-10-16).
Read-only reviews checked every present-tense claim against the code;
each finding was read in the source before it was fixed here.

architecture.md: held inbound mail has its row from the journal milter,
not the tailer; the antispam action is accept or tempfail, anything else
stops the start; tls-internal's certificate is 0644; the signer logs to
stderr; the log's fingerprint is the inode, not the device; a mail.log
postlogd makes is 0640 (maillog_file_permissions); an unreadable stored
place starts at end-of-file too; the test-message route; no map in page
data; design-first compares whitespace aside; the queue and sasldb2.new
are not backed up; antispam/ under /data; POSTFIX_QUEUE_DIR's desync;
SELFPOST_BACKUP_PASSWORD (the CLI's).
schema-migrations.md: inbound_spam_log's upstream columns (v12),
send_log's sender reason, row 9's client_ip.
security.md: /data/opendkim since 2.9.0 (removed, or the start refused),
sasldb2 under /data/sasl, the trigger for mandatory encryption, the
password minimum counted in characters.
development.md: Staticcheck in CI, the e2e ports 20025 and 20053/udp.
README: the client IP list refuses at MAIL FROM, overrides are per
application. product.md: the optional rspamd sidecar.

Code: validate.AdminPassword counted bytes, so six Cyrillic letters
passed for twelve characters; it counts runes, as the backup password
always did (TestAdminPasswordCountsCharacters). envdoc reads
cmd/selfpost-backup too, and a name kept in a constant. A stale comment
of cmd/panel's run ("three roles").

go vet + go test (26 packages) and make e2e on the test server for this
tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mix
2026-10-17 02:07:55 +03:00
co-authored by Claude Opus 5.5
parent 2dded921f5
commit be98efa549
11 changed files with 104 additions and 57 deletions
+13 -13
View File
@@ -229,8 +229,8 @@ operator can act on it.
`selfpost` for files and does not reach it (`2.6.0`; OpenDKIM shared
`selfpost` too until `2.8.0`).
- **Group `selfpost` (gid 10998) has two members, `panel` and `postfix`.**
Through it Postfix reads what the panel writes - `sasldb2` and the maps
under `/data/postfix` (2750, files 0640) - and connects to the panel's
Through it Postfix reads what the panel writes - `sasldb2` under
`/data/sasl` and the maps under `/data/postfix` (both 2750, files 0640) - and connects to the panel's
milter sockets in `/run/selfpost` (2750, sockets 0660); the panel reads
`mail.log`, which `postfix` writes, through it the other way
([build/Dockerfile](../build/Dockerfile), `build/entrypoint.sh`). The DKIM
@@ -286,14 +286,12 @@ operator can act on it.
signer reads them and never the database. The entrypoint sets these modes
at every start (e2e `checkDKIMTree` holds the tree to them). Until `2.8.0`
the keys were under `/data/opendkim`, 2750/0640 in group `selfpost` so
that OpenDKIM could read them - and so could every `postfix` process. That
tree is kept for a rollback to 2.7.x until the next release; since `2.8.0`
the entrypoint makes it the panel's alone as well (0700/0600, panel:panel)
at every start, copies its keys as the panel user (`setpriv`) while
`/data/dkim` holds none, and a backup leaves it out (§ Backup and domain
export). A root step of the entrypoint follows no symbolic link the panel
could plant in either tree (`drop_links`; `cp -RP`; `chown -R` and `find`
do not follow one).
that OpenDKIM could read them - and so could every `postfix` process.
2.8.x kept that tree, the panel's alone, for a rollback to 2.7.x and copied
its keys over; since `2.9.0` the entrypoint removes it at start, and refuses
to start when the keys are only there (start 2.8.x once first). A root step
of the entrypoint follows no symbolic link the panel could plant in the
tree (`drop_links`; `rm -rf`, `chown -R` and `find` do not follow one).
- **An application signs only as itself (`2.4.0`).** The signature's `d=` is
the login's domain, and a receiver holds it to the domain of the `From:`
line (DMARC, RFC 7489 § 3.1.1): without a check of that line an
@@ -498,7 +496,8 @@ operator can act on it.
CLI the password comes only from `SELFPOST_BACKUP_PASSWORD` or
`-password-file`, never as an argument (the process list is readable by any
process in the container).
- Minimum password length matches the administrator password (12): the file
- Minimum password length matches the administrator password (12
characters, counted as characters, not bytes, in both): the file
sits offline and can be attacked without a time limit. The panel's forms and,
since `2.5.3`, the CLI hold an encrypting password to it; decrypting takes
any.
@@ -550,8 +549,9 @@ deferred item from the roadmap.
keep a password would lose the ability to take a backup at all, and a
permanently undecryptable archive is worse than an unencrypted one:
SelfPost does not store the password. The trigger to make encryption
mandatory is a second administrator (at which point "who downloaded it"
stops being one person).
mandatory is a second person who takes backups or exports - a second
global user, or a domain user exporting their domain - at which point "who
downloaded it" stops being one person.
- **A journal row left without delivery lines is closed as `bounced` rather
than left as it is.** The "forever `queued`" risk is gone: `mail.log` moved to
`/data/log/` and survives container recreation, and the log tailer keeps its