release: 0.5.0: Pre-1.0 security review, domain-admin role, doc consolidation

A bounce could be recorded as a successful delivery. The log-tailer's
Fixed:
  - A bounce could be recorded as a successful delivery. The log-tailer's
  - Log-tailer resumes where it stopped instead of jumping to end-of-file on
  - Level-2 rate limit no longer overshoots under concurrency: messages that
Changed:
  - The project has a single public home: `github.com/mixeme/selfpost`. Codeberg
  - Code comments no longer cite the archived specification. References like
  - `docs/code-review.md` is gone. Its plan is finished — phases 0 (bar the
  - `docs/architecture.md` gained a *Code layers* section: a diagram of
  - Phase 1 doc/code hygiene (`docs/code-review.md`): removed ~30 stale
  … (1 more in CHANGELOG)
Security:
  - Pre-release security review (plan § D, model Fable, 2026-08-06): full pass
  - `saslpasswd2` argv: the application login is now passed after a `--`
Added:
  - Optional password encryption for the two secret-bearing downloads (plan
  - Domain import accepts an encrypted export: the envelope is detected by its
  - `selfpost-backup` writes encrypted archives and reads them back:
  - `TestParseDelivery` covers the exotic mail.log shapes the review asked for
  - docs: README *Encrypting a backup or export*; `docs/security.md` §
  … (14 more in CHANGELOG)
Removed:
  - docs: `security.md` — accepted risk «restore old backup revives session rows»
Changed:
  - docs: `implementation-plan.md` trimmed to the sole open v1.x gate — pre-release
  - docs: `architecture.md` — sessions (SQLite, idle renew, password change),
  - docs: `development.md` — expanded e2e stack and `release.yml` matrix workflow.
  - docs: `security.md` — accepted risk for send-log rows stuck at `queued` after
  - docs: `roadmap.md` — optional send-log / `mail.log` follow-ups under v1.x tail.
  … (10 more in CHANGELOG)

Full detail: CHANGELOG.md (0.5.0).

internal/app/password.go

@@ -8,12 +8,12 @@ import (
 
 // passwordBytes is the number of random bytes behind a generated application
 // password. 24 bytes = 192 bits of entropy, well above any brute-force concern
-// for a SASL credential the panel shows exactly once (spec 7.6.1).
+// for a SASL credential the panel shows exactly once (security.md).
 const passwordBytes = 24
 
 // generatePassword returns a strong, URL-safe random password for an
 // application's SASL account. The panel generates it, shows it once and never
-// stores the plaintext (spec 7.6.1); sasldb2 keeps only the hashed form.
+// stores the plaintext (security.md); sasldb2 keeps only the hashed form.
 //
 // base64url output keeps the password to a safe ASCII alphabet with no shell or
 // SMTP-special characters, so it survives being typed into client configuration

internal/app/sasl.go

@@ -10,11 +10,12 @@ import (
 )
 
 // SASLDB manages the Cyrus SASL account database (sasldb2) the panel maintains
-// for application credentials (spec 5.1). The panel is the only writer; Postfix
-// reads it to authenticate SMTP clients. Accounts are created and removed with
-// the standard saslpasswd2 tool ("эквивалент saslpasswd2", per the plan).
+// for application credentials (architecture.md § Mail path). The panel is the
+// only writer; Postfix reads it to authenticate SMTP clients. Accounts are
+// created and removed with the standard saslpasswd2 tool ("эквивалент
+// saslpasswd2", per the plan).
 type SASLDB struct {
-	path  string // sasldb2 file, under /data so it survives restarts (spec 9)
+	path  string // sasldb2 file, under /data so it survives restarts
 	realm string // SASL realm, so lookups match what Postfix's SASL uses
 
 	// run executes saslpasswd2. It is a field so tests can substitute a fake;
@@ -28,20 +29,20 @@ type SASLDB struct {
 
 // NewSASLDB builds a manager for the sasldb2 at path with the given realm. The
 // realm should match SELFPOST_HOSTNAME so the account identity lines up with
-// Postfix's SASL configuration in Phase 5.
+// Postfix's SASL configuration.
 func NewSASLDB(path, realm string) *SASLDB {
 	return &SASLDB{path: path, realm: realm, run: runSaslpasswd2, dump: dumpSASLDB}
 }
 
 // Set creates or updates an application's SASL account with the given password
-// (spec 5.1, 7.2.9). Used both at creation and when a password is regenerated;
-// saslpasswd2 overwrites an existing entry in place.
+// (architecture.md § Mail path). Used both at creation and when a password is
+// regenerated; saslpasswd2 overwrites an existing entry in place.
 //
 // The password is passed to saslpasswd2 on stdin (never as an argument, so it
 // cannot leak through the process table or logs). The login is passed as a
 // separate argv element after being whitelisted by validateLogin — it never
-// goes through a shell and is never interpolated into a command string (spec
-// 7.6.3).
+// goes through a shell and is never interpolated into a command string
+// (security.md).
 func (s *SASLDB) Set(login, password string) error {
 	if err := validateLogin(login); err != nil {
 		return err
@@ -50,21 +51,24 @@ func (s *SASLDB) Set(login, password string) error {
 	// -c: create the account / set the password.
 	// -f: operate on our sasldb2 rather than the system default path.
 	// -u: the realm the account lives under.
-	args := []string{"-p", "-c", "-f", s.path, "-u", s.realm, login}
+	// --: end of options, so a login can never be parsed as a flag (the
+	//     whitelist already forbids nothing that getopt would eat, but a login
+	//     starting with '-' is legal there — this keeps it an operand).
+	args := []string{"-p", "-c", "-f", s.path, "-u", s.realm, "--", login}
 	if err := s.run(args, []byte(password)); err != nil {
 		return fmt.Errorf("saslpasswd2 set %q: %w", login, err)
 	}
 	return nil
 }
 
-// Delete removes an application's SASL account (spec 7.2.8). A missing account
+// Delete removes an application's SASL account (product.md). A missing account
 // is not treated as an error, so deletion is idempotent and safe to retry.
 func (s *SASLDB) Delete(login string) error {
 	if err := validateLogin(login); err != nil {
 		return err
 	}
-	// -d: delete the account.
-	args := []string{"-d", "-f", s.path, "-u", s.realm, login}
+	// -d: delete the account. "--" as in Set: the login is always an operand.
+	args := []string{"-d", "-f", s.path, "-u", s.realm, "--", login}
 	if err := s.run(args, nil); err != nil {
 		return fmt.Errorf("saslpasswd2 delete %q: %w", login, err)
 	}
@@ -76,15 +80,16 @@ func (s *SASLDB) Delete(login string) error {
 var ErrSecretNotFound = fmt.Errorf("sasl secret not found")
 
 // Secret returns an application's stored password so it can be carried in a
-// domain export and re-created verbatim on another instance (spec 7.5.B). This
-// is possible because sasldb2 keeps the SASL secret in a password-equivalent
-// form (the plaintext userPassword property, to serve challenge-response
-// mechanisms) — unlike the admin's one-way bcrypt hash (spec 7.6). The value is
-// realm-independent, so the importer can re-key it under its own realm.
+// domain export and re-created verbatim on another instance (architecture.md §
+// Persistence). This is possible because sasldb2 keeps the SASL secret in a
+// password-equivalent form (the plaintext userPassword property, to serve
+// challenge-response mechanisms) — unlike the admin's one-way bcrypt hash
+// (security.md). The value is realm-independent, so the importer can re-key it
+// under its own realm.
 //
 // It reads the database with db_dump (Berkeley DB), passing only our own file
-// path as a fixed argument (no shell, no user input — spec 7.6.3), and returns
-// ErrSecretNotFound if the login has no entry.
+// path as a fixed argument (no shell, no user input — security.md), and
+// returns ErrSecretNotFound if the login has no entry.
 func (s *SASLDB) Secret(login string) (string, error) {
 	if err := validateLogin(login); err != nil {
 		return "", err
@@ -155,7 +160,7 @@ func parseSASLSecret(dump []byte, login, realm string) (string, bool, error) {
 
 // runSaslpasswd2 executes the real saslpasswd2 with the given arguments and
 // stdin. Arguments are passed as a fixed argv (no shell), so no user input is
-// ever interpreted as a command (spec 7.6.3).
+// ever interpreted as a command (security.md).
 func runSaslpasswd2(args []string, stdin []byte) error {
 	cmd := exec.Command("saslpasswd2", args...)
 	if stdin != nil {
@@ -170,7 +175,7 @@ func runSaslpasswd2(args []string, stdin []byte) error {
 
 // dumpSASLDB runs db_dump to export the sasldb2 as key/value hex pairs. The path
 // is our own sasldb2 file (never user input) and is passed as a fixed argument
-// with no shell (spec 7.6.3).
+// with no shell (security.md).
 func dumpSASLDB(path string) ([]byte, error) {
 	cmd := exec.Command("db_dump", path)
 	out, err := cmd.CombinedOutput()

internal/app/sasl_test.go

@@ -39,8 +39,9 @@ func TestSASLSetPassesPasswordOnStdinNotArgv(t *testing.T) {
 	if strings.Contains(joined, secret) {
 		t.Errorf("password leaked into argv: %q", joined)
 	}
-	// Expected fixed flags and the login as its own trailing argument.
-	want := []string{"-p", "-c", "-f", "/data/sasl/sasldb2", "-u", "mail.example.com", "alerts"}
+	// Expected fixed flags and the login as its own trailing argument, behind
+	// "--" so it can never be parsed as an option.
+	want := []string{"-p", "-c", "-f", "/data/sasl/sasldb2", "-u", "mail.example.com", "--", "alerts"}
 	if len(fr.args) != len(want) {
 		t.Fatalf("args = %v, want %v", fr.args, want)
 	}
@@ -56,7 +57,7 @@ func TestSASLDeleteArgs(t *testing.T) {
 	if err := s.Delete("alerts"); err != nil {
 		t.Fatalf("Delete: %v", err)
 	}
-	want := []string{"-d", "-f", "/data/sasl/sasldb2", "-u", "mail.example.com", "alerts"}
+	want := []string{"-d", "-f", "/data/sasl/sasldb2", "-u", "mail.example.com", "--", "alerts"}
 	if strings.Join(fr.args, " ") != strings.Join(want, " ") {
 		t.Errorf("delete args = %v, want %v", fr.args, want)
 	}

internal/app/service.go

@@ -1,13 +1,13 @@
-// Package app owns application accounts (spec 4.1, 5.1): the SASL credentials in
-// sasldb2, the per-application sender address mode, and the
-// smtpd_sender_login_maps bindings that tie each login to the addresses it may
-// send from. It keeps those three stores — the SQLite registry, sasldb2 and the
-// Postfix map — in agreement and drives the Postfix reload.
+// Package app owns application accounts (product.md § Multi-domain model): the
+// SASL credentials in sasldb2, the per-application sender address mode, and
+// the smtpd_sender_login_maps bindings that tie each login to the addresses it
+// may send from. It keeps those three stores — the SQLite registry, sasldb2
+// and the Postfix map — in agreement and drives the Postfix reload.
 package app
 
 import (
-	"codeberg.org/mix/selfpost/internal/postfix"
-	"codeberg.org/mix/selfpost/internal/store"
+	"github.com/mixeme/selfpost/internal/postfix"
+	"github.com/mixeme/selfpost/internal/store"
 )
 
 // SenderMaps is the slice of the Postfix manager the application service needs:
@@ -19,7 +19,7 @@ type SenderMaps interface {
 
 // Service coordinates application state across SQLite, sasldb2 and the Postfix
 // sender_login_maps. Web handlers validate raw input first; the Service performs
-// the domain-ownership checks that must not be skipped (spec 7.6.2) and keeps
+// the domain-ownership checks that must not be skipped (security.md) and keeps
 // the stores consistent.
 type Service struct {
 	store *store.Store
@@ -33,7 +33,7 @@ func NewService(st *store.Store, sasl *SASLDB, pf SenderMaps) *Service {
 	return &Service{store: st, sasl: sasl, pf: pf}
 }
 
-// List returns a domain's applications with their address lists (spec 7.2.6).
+// List returns a domain's applications with their address lists (product.md).
 func (s *Service) List(domainID int64) ([]store.Application, error) {
 	return s.store.ListApplicationsByDomain(domainID)
 }
@@ -44,10 +44,10 @@ func (s *Service) Get(id int64) (store.Application, error) {
 }
 
 // Create adds an application to a domain: it validates the login and (in list
-// mode) that every address belongs to the domain (spec 7.6.2), generates a
+// mode) that every address belongs to the domain (security.md), generates a
 // strong password, writes the SASL account and rebuilds the sender map (spec
 // 7.2.5). The generated password is returned so the caller can show it exactly
-// once (spec 7.6.1) — it is never persisted in plaintext.
+// once (security.md) — it is never persisted in plaintext.
 //
 // The registry row is written first so its UNIQUE constraint is the sole arbiter
 // of a duplicate login (avoiding a check-then-act race and, crucially, avoiding
@@ -92,13 +92,14 @@ func (s *Service) rollbackCreate(id int64, login string) {
 	_, _ = s.store.DeleteApplication(id)
 }
 
-// ImportApplication re-creates an application from a domain-export file (spec
-// 7.5.B): it validates the login and (in list mode) that every address belongs
-// to the domain, inserts the registry row and writes the SASL account with the
-// imported password verbatim, re-keyed under this instance's realm so the
-// credential keeps working without regeneration. It deliberately does not
-// rebuild the sender map — the caller (domain import) does that once after all
-// applications are in — and returns store.ErrLoginExists if the login collides.
+// ImportApplication re-creates an application from a domain-export file
+// (architecture.md § Persistence): it validates the login and (in list mode)
+// that every address belongs to the domain, inserts the registry row and
+// writes the SASL account with the imported password verbatim, re-keyed under
+// this instance's realm so the credential keeps working without regeneration.
+// It deliberately does not rebuild the sender map — the caller (domain import)
+// does that once after all applications are in — and returns
+// store.ErrLoginExists if the login collides.
 func (s *Service) ImportApplication(domainID int64, login, mode string, rawAddresses []string, password string) error {
 	addresses, err := s.validateForDomain(domainID, login, mode, rawAddresses)
 	if err != nil {
@@ -118,14 +119,15 @@ func (s *Service) ImportApplication(domainID int64, login, mode string, rawAddre
 	return nil
 }
 
-// Secret returns an application's stored password for a domain export (spec
-// 7.5.B). See SASLDB.Secret for why this is possible and safe.
+// Secret returns an application's stored password for a domain export
+// (architecture.md § Persistence). See SASLDB.Secret for why this is possible
+// and safe.
 func (s *Service) Secret(login string) (string, error) {
 	return s.sasl.Secret(login)
 }
 
 // UpdateMode switches an application's address mode / list and rebuilds the
-// sender map (spec 7.2.7). The login and password are untouched. Addresses are
+// sender map (product.md). The login and password are untouched. Addresses are
 // re-validated against the application's domain.
 func (s *Service) UpdateMode(id int64, mode string, rawAddresses []string) error {
 	a, err := s.store.GetApplication(id)
@@ -172,22 +174,23 @@ func (s *Service) Delete(id int64) error {
 	if err := s.sasl.Delete(a.Login); err != nil {
 		return err
 	}
-	// Drop the application's level-2 limit, if any (spec 7.4); rate_limits has no
-	// cascade of its own.
+	// Drop the application's level-2 limit, if any (README § Rate limiting);
+	// rate_limits has no cascade of its own.
 	if err := s.store.DeleteRateLimit(store.RateLimitScopeApp, id); err != nil {
 		return err
 	}
 	return s.Resync()
 }
 
-// RateLimit returns the application-level differentiated rate limit (spec 7.4),
-// and whether one is configured, for the application's edit form.
+// RateLimit returns the application-level differentiated rate limit (README §
+// Rate limiting), and whether one is configured, for the application's edit
+// form.
 func (s *Service) RateLimit(appID int64) (store.RateLimit, bool, error) {
 	return s.store.GetRateLimit(store.RateLimitScopeApp, appID)
 }
 
 // SaveRateLimit stores the application-level rate limit. The caller has validated
-// the IPs and numbers (spec 7.6.2); the milter reads the row live, so no reload
+// the IPs and numbers (security.md); the milter reads the row live, so no reload
 // is needed.
 func (s *Service) SaveRateLimit(appID int64, ips []string, maxMessages, windowSeconds int) error {
 	return s.store.SetRateLimit(store.RateLimit{
@@ -199,14 +202,15 @@ func (s *Service) SaveRateLimit(appID int64, ips []string, maxMessages, windowSe
 	})
 }
 
-// ClearRateLimit removes the application-level rate limit (spec 7.4).
+// ClearRateLimit removes the application-level rate limit (README § Rate
+// limiting).
 func (s *Service) ClearRateLimit(appID int64) error {
 	return s.store.DeleteRateLimit(store.RateLimitScopeApp, appID)
 }
 
 // PurgeDomainSASL removes the SASL accounts of every application bound to a
 // domain. It must be called before the domain's registry rows are cascade-
-// deleted, while the logins are still known (spec 7.2.4). The registry rows and
+// deleted, while the logins are still known (product.md). The registry rows and
 // the sender map are handled by the domain deletion path; this only clears
 // sasldb2, which has no cascade of its own.
 func (s *Service) PurgeDomainSASL(domainID int64) error {
@@ -223,10 +227,10 @@ func (s *Service) PurgeDomainSASL(domainID int64) error {
 }
 
 // Resync rebuilds smtpd_sender_login_maps from the full set of application
-// bindings and reloads Postfix (spec 5.1). It is the single idempotent apply
-// path shared by create/edit/delete and is also reachable from the manual
-// reload button; it doubles as recovery if the map ever drifts from the
-// database.
+// bindings and reloads Postfix (architecture.md § Mail path). It is the single
+// idempotent apply path shared by create/edit/delete and is also reachable
+// from the manual reload button; it doubles as recovery if the map ever drifts
+// from the database.
 func (s *Service) Resync() error {
 	bindings, err := s.store.ListBindings()
 	if err != nil {
@@ -241,7 +245,7 @@ func (s *Service) Resync() error {
 
 // validateForDomain resolves the domain, validates the login and address mode,
 // and — in list mode — validates that every address belongs to the domain
-// (spec 7.6.2). It returns the cleaned address list, which is empty in wildcard
+// (security.md). It returns the cleaned address list, which is empty in wildcard
 // mode. Resolving the domain here also confirms it exists before any write.
 func (s *Service) validateForDomain(domainID int64, login, mode string, rawAddresses []string) ([]string, error) {
 	d, err := s.store.GetDomain(domainID)

internal/app/service_test.go

@@ -5,8 +5,8 @@ import (
 	"path/filepath"
 	"testing"
 
-	"codeberg.org/mix/selfpost/internal/postfix"
-	"codeberg.org/mix/selfpost/internal/store"
+	"github.com/mixeme/selfpost/internal/postfix"
+	"github.com/mixeme/selfpost/internal/store"
 )
 
 // fakeMaps records the last set of bindings passed to a rebuild and can be told

internal/app/validate.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"strings"
 
-	"codeberg.org/mix/selfpost/internal/store"
+	"github.com/mixeme/selfpost/internal/store"
 )
 
 const (
@@ -13,12 +13,12 @@ const (
 )
 
 // validateLogin enforces a strict server-side whitelist for the SASL login
-// (spec 7.6.2). It intentionally excludes '@': the login is stored in sasldb2,
+// (security.md). It intentionally excludes '@': the login is stored in sasldb2,
 // where '@' separates the user from the realm, so allowing it would change the
 // account's identity. Client validation is never trusted.
 //
 // The login is the one piece of user input that is passed to saslpasswd2 as a
-// command argument (never through a shell, spec 7.6.3); this whitelist is what
+// command argument (never through a shell, security.md); this whitelist is what
 // makes that safe.
 func validateLogin(login string) error {
 	if len(login) < minLoginLen || len(login) > maxLoginLen {
@@ -36,10 +36,11 @@ func validateLogin(login string) error {
 }
 
 // validateImportedPassword guards a password taken from a domain-export file
-// (spec 7.5.B) before it is written to sasldb2. Our own exports carry base64url
-// passwords, but the file is untrusted input, so we reject an empty value or one
-// containing control characters — saslpasswd2 reads the passphrase from stdin
-// and a newline would silently truncate it (spec 7.6.2).
+// (architecture.md § Persistence) before it is written to sasldb2. Our own
+// exports carry base64url passwords, but the file is untrusted input, so we
+// reject an empty value or one containing control characters — saslpasswd2
+// reads the passphrase from stdin and a newline would silently truncate it
+// (security.md).
 func validateImportedPassword(password string) error {
 	if password == "" {
 		return fmt.Errorf("imported application password is empty")
@@ -71,7 +72,7 @@ func normalizeAddress(addr string) string {
 }
 
 // validateSenderAddress enforces that a list-mode address is well-formed and,
-// critically, belongs to the application's own domain (spec 7.6.2). The domain
+// critically, belongs to the application's own domain (security.md). The domain
 // check is done here, before anything is written to a config file — not left to
 // smtpd_sender_login_maps to catch at delivery time. domain must already be a
 // validated, normalised domain name.
@@ -92,7 +93,7 @@ func validateSenderAddress(addr, domain string) error {
 
 // validateLocalPart applies a conservative whitelist to the part before '@'.
 // This is deliberately stricter than RFC 5321 (no quoted local parts) so the
-// value is always safe to write verbatim into the Postfix map (spec 7.6.4).
+// value is always safe to write verbatim into the Postfix map (security.md).
 func validateLocalPart(local string) error {
 	if local == "" {
 		return fmt.Errorf("missing the part before '@'")

internal/app/validate_test.go

@@ -25,7 +25,7 @@ func TestValidateLogin(t *testing.T) {
 }
 
 func TestValidateSenderAddressDomainOwnership(t *testing.T) {
-	// The critical check (spec 7.6.2): an address must belong to the app's domain.
+	// The critical check (security.md): an address must belong to the app's domain.
 	if err := validateSenderAddress("alerts@example.com", "example.com"); err != nil {
 		t.Errorf("same-domain address rejected: %v", err)
 	}