from-header-binding: the sender check, what it costs, its pages; guide, architecture, security

A message's From: line is held against the application that sends it, under
the rule Postfix holds the envelope sender to. OpenDKIM chooses the key by
that line, so until now an application could have mail signed as another
domain of the server or as the server itself.

The check (internal/milter/sender.go)
- A role of the panel on a socket of its own (SENDER_CHECK_SOCKET), first in
  smtpd_milters and strict: default_action=tempfail. The journal milter keeps
  its socket and stays fail-open. postfix-wrapper waits for the new socket.
- It reads no database: what an application may send as comes from Postfix's
  own sender_login_maps, what the server signs for from OpenDKIM's
  SigningTable. Both are read again when they change; one that cannot be
  read defers mail.
- One From: field, one address, allowed by the envelope's lookup; then no
  other name of the SigningTable may appear anywhere in the raw line.
  Refused: 550 5.7.1 naming the line, reduced to printable ASCII.
- A refusal is a send-log row with reason "from" and the header address
  (migration 0006), written by another goroutine and not waited for. The
  journal's refusals record their reason too (limit, client), and the
  notifier takes only a limit's.

What it costs (docs/plans/from-header-binding.md, Statistics)
- The role marks itself alive every 2 s; at start the gap since the mark is
  downtime, counted from Postfix's start if later and not at all when
  supervisord says Postfix is not running.
- The log tailer counts the connections Postfix turned away: a warning that
  names the socket, then milter-reject "Service unavailable" from the same
  smtpd. Seen on the stand: the client is refused from CONNECT on and leaves
  at AUTH (454), so no MAIL line is ever written.
- sender_check_days, a row per UTC day, kept a year.

Pages
- Health: the card "Sender check", the socket's row, and the cards layout -
  boxes numbered by importance in two stacks read in rows; the left stack
  polls, the three readings of the right one are swapped in by id.
- Outbound log: a refused row says why in its tag (wrong From, wrong client,
  rate-limited); the message's page shows the From: line and what the
  application may send as.
- Help: topic "Sender check", word for word the mockup's.

Found by the stand, fixed here: the names for the second look came from the
sender bindings, and a domain with a key and no application yet was not
among them.

e2e: negative_journal_milter_fail_open is gone - it proved that mail passes
with the panel down, which is no longer so. In its place
sender_check_holds_the_from_line (another domain's From:, the hostname's, a
stranger's, an address off the list, another sender in the display name -
refused; own addresses - delivered) and panel_down_defers_mail (4xx with the
panel stopped, the container alive, mail again after, downtime and one
deferred message on Health, the card warning).

Test server, this tree before the last cosmetic edits (a fixture row, a
fact's size, docs): go vet ok, go test 23 packages ok, make e2e ok (337 s).
Locally after them: internal/web/view ok.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

cmd/panel/envdoc_test.go

@@ -32,6 +32,7 @@ var documentedInternal = []string{
 	"SELFPOST_SETUP_TOKEN_FILE",
 	"PANEL_HTTP_ADDR",
 	"JOURNAL_MILTER_SOCKET",
+	"SENDER_CHECK_SOCKET",
 	"MAIL_LOG",
 	"PANEL_COOKIE_SECURE",
 	"OPENDKIM_SOCKET",
@@ -70,6 +71,7 @@ var loadConfigKeys = []string{
 	"SELFPOST_DATA_DIR",
 	"PANEL_HTTP_ADDR",
 	"JOURNAL_MILTER_SOCKET",
+	"SENDER_CHECK_SOCKET",
 	"MAIL_LOG",
 	"SEND_LOG_RETENTION_DAYS",
 	"SELFPOST_DB_PATH",
@@ -104,6 +106,7 @@ var buildScriptKeys = []string{
 	"RATE_LIMIT_WINDOW_SECONDS",
 	"OPENDKIM_SOCKET",
 	"JOURNAL_MILTER_SOCKET",
+	"SENDER_CHECK_SOCKET",
 	"MAIL_LOG",
 	"POSTFIX_SENDER_LOGIN_MAPS",
 	"POSTFIX_QUEUE_DIR",

cmd/panel/httpserver.go

@@ -114,6 +114,7 @@ func newPanel(cfg config, st *store.Store) (*web.Server, error) {
 		TLSCertFile:                cfg.tlsCertFile,
 		OpenDKIMSocket:             cfg.opendkimSocket,
 		JournalSocket:              cfg.journalSocket,
+		SenderSocket:               cfg.senderSocket,
 		SessionIdleDays:            cfg.sessionIdleDays,
 		DNSResolvers:               cfg.dnsResolvers,
 		RateLimitMessagesPerIP:     cfg.rateLimitMessagesPerIP,

cmd/panel/main.go

@@ -60,6 +60,8 @@ func main() {
 type config struct {
 	httpAddr      string
 	journalSocket string
+	// The sender check's socket; the default mirrors build/postfix-config.sh.
+	senderSocket  string
 	mailLog       string
 	retentionDays int
 
@@ -113,6 +115,7 @@ func loadConfig() config {
 	return config{
 		httpAddr:      envDefault("PANEL_HTTP_ADDR", ":8080"),
 		journalSocket: envDefault("JOURNAL_MILTER_SOCKET", "/run/selfpost/journal.sock"),
+		senderSocket:  envDefault("SENDER_CHECK_SOCKET", "/run/selfpost/sender.sock"),
 		// Postfix's delivery log, under /data so the lines that resolve a
 		// "queued" send-log row outlive the container. The default must match
 		// maillog_file in build/postfix-config.sh.
@@ -341,8 +344,8 @@ func run() error {
 	}
 
 	var wg sync.WaitGroup
-	// Room for every role to report a failure without blocking: six at most.
-	errc := make(chan error, 6)
+	// Room for every role to report a failure without blocking: seven at most.
+	errc := make(chan error, 7)
 
 	roles := []struct {
 		name string
@@ -350,6 +353,7 @@ func run() error {
 	}{
 		{"http", func(ctx context.Context) error { return serveHTTP(ctx, cfg, st) }},
 		{"journal-milter", func(ctx context.Context) error { return serveJournal(ctx, cfg, st) }},
+		{"sender-check", func(ctx context.Context) error { return serveSenderCheck(ctx, cfg, st) }},
 		{"log-tailer", func(ctx context.Context) error {
 			return logtail.Run(ctx, cfg.mailLog, st, func() int {
 				days, err := st.GetSendLogRetentionDays(cfg.retentionDays)
@@ -358,7 +362,7 @@ func run() error {
 					return cfg.retentionDays
 				}
 				return days
-			}, inboundTail)
+			}, inboundTail, &logtail.SenderCheck{Store: st, Socket: cfg.senderSocket})
 		}},
 		{"rate-limit-recalc", func(ctx context.Context) error {
 			runAutoRateLimitRecalc(ctx, cfg, st)

cmd/panel/sendercheck.go

@@ -0,0 +1,124 @@
+package main
+
+import (
+	"context"
+	"log"
+	"os"
+	"time"
+
+	"github.com/mixeme/selfpost/internal/domain"
+	"github.com/mixeme/selfpost/internal/health"
+	"github.com/mixeme/selfpost/internal/milter"
+	"github.com/mixeme/selfpost/internal/postfix"
+	"github.com/mixeme/selfpost/internal/store"
+)
+
+// aliveEvery is how often the sender check marks itself alive. The gap a
+// restart finds since the last mark is the check's downtime, so the mark's
+// age is the error of that figure.
+const aliveEvery = 2 * time.Second
+
+// serveSenderCheck runs the sender check (internal/milter/sender.go) on a
+// socket of its own. Postfix attaches that socket strictly, so while this
+// role is not serving, mail is deferred: what that costs is counted here and
+// by the log tailer, and shown on Server > Health
+// (docs/plans/from-header-binding.md § Statistics).
+func serveSenderCheck(ctx context.Context, cfg config, st *store.Store) error {
+	ln, err := listenMilter(cfg.senderSocket)
+	if err != nil {
+		return err
+	}
+	log.Printf("sender-check listening on %s", cfg.senderSocket)
+
+	// Statistics are the database's business and the check is not: none of
+	// this may keep the check from serving.
+	now := time.Now()
+	mark := cfg.senderSocket + ".alive"
+	if err := st.StartSenderCheckStats(now); err != nil {
+		log.Printf("sender-check: statistics: %v", err)
+	}
+	if down := senderCheckDowntime(mark, now, postfixStarted); down > 0 {
+		log.Printf("sender-check: was not answering for %s while Postfix was running", down.Round(time.Second))
+		if err := st.AddSenderCheckDown(now, down); err != nil {
+			log.Printf("sender-check: statistics: %v", err)
+		}
+	}
+	go keepAlive(ctx, mark, st)
+
+	// The two tables the mail path itself goes by: whom Postfix lets send as
+	// what, and what OpenDKIM signs.
+	bind := milter.NewBindings(postfix.New(cfg.postfixDir).SenderLoginMapsPath())
+	signers := milter.NewSigners(domain.NewOpenDKIM(cfg.opendkimDir).SigningTablePath())
+	return milter.ServeSender(ctx, ln, bind, signers, st)
+}
+
+// senderCheckDowntime is for how long the check was not serving before now
+// while Postfix was: the time since the mark at path was last set, or since
+// Postfix started if that was later. No mark means the container is new, and
+// a Postfix that is not running means mail was stopped for another reason -
+// a rollout, a reboot - and neither is the check's downtime.
+func senderCheckDowntime(path string, now time.Time, postfixStarted func() (time.Time, bool)) time.Duration {
+	fi, err := os.Stat(path)
+	if err != nil {
+		return 0
+	}
+	from := fi.ModTime()
+	started, running := postfixStarted()
+	if !running {
+		return 0
+	}
+	if started.After(from) {
+		from = started
+	}
+	if d := now.Sub(from); d > 0 {
+		return d
+	}
+	return 0
+}
+
+// postfixStarted asks supervisord since when Postfix has been running.
+func postfixStarted() (time.Time, bool) {
+	procs, err := health.Processes()
+	if err != nil {
+		return time.Time{}, false
+	}
+	for _, p := range procs {
+		if p.Name != "postfix" || p.State != "RUNNING" {
+			continue
+		}
+		if up, ok := health.Uptime(p.Detail); ok {
+			return time.Now().Add(-up), true
+		}
+	}
+	return time.Time{}, false
+}
+
+// keepAlive sets the mark until ctx ends, and once a day drops the days of
+// the statistics that are older than a year.
+func keepAlive(ctx context.Context, path string, st *store.Store) {
+	touch := func() {
+		now := time.Now()
+		if err := os.Chtimes(path, now, now); err != nil {
+			if err := os.WriteFile(path, nil, 0o644); err != nil {
+				log.Printf("sender-check: alive mark: %v", err)
+			}
+		}
+	}
+	touch()
+	tick := time.NewTicker(aliveEvery)
+	defer tick.Stop()
+	prune := time.NewTicker(24 * time.Hour)
+	defer prune.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-tick.C:
+			touch()
+		case <-prune.C:
+			if err := st.PruneSenderCheckDays(time.Now()); err != nil {
+				log.Printf("sender-check: statistics: %v", err)
+			}
+		}
+	}
+}

cmd/panel/sendercheck_test.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// The check's downtime is the time since its last mark, under a Postfix that
+// was running: a new container has no mark, and a Postfix that is not up, or
+// came up later than the mark, was not kept waiting by the check for all of
+// that time.
+func TestSenderCheckDowntime(t *testing.T) {
+	now := time.Date(2026, 10, 12, 18, 0, 0, 0, time.UTC)
+	mark := filepath.Join(t.TempDir(), "sender.sock.alive")
+	set := func(at time.Time) {
+		t.Helper()
+		if err := os.WriteFile(mark, nil, 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Chtimes(mark, at, at); err != nil {
+			t.Fatal(err)
+		}
+	}
+	postfix := func(started time.Time, running bool) func() (time.Time, bool) {
+		return func() (time.Time, bool) { return started, running }
+	}
+
+	if d := senderCheckDowntime(mark, now, postfix(now.Add(-time.Hour), true)); d != 0 {
+		t.Errorf("no mark: %s", d)
+	}
+	set(now.Add(-40 * time.Second))
+	if d := senderCheckDowntime(mark, now, postfix(now.Add(-time.Hour), true)); d != 40*time.Second {
+		t.Errorf("Postfix up throughout: %s, want 40s", d)
+	}
+	if d := senderCheckDowntime(mark, now, postfix(now.Add(-10*time.Second), true)); d != 10*time.Second {
+		t.Errorf("Postfix started within the gap: %s, want 10s", d)
+	}
+	if d := senderCheckDowntime(mark, now, postfix(time.Time{}, false)); d != 0 {
+		t.Errorf("Postfix not running: %s", d)
+	}
+	set(now.Add(time.Minute)) // a clock set back
+	if d := senderCheckDowntime(mark, now, postfix(now.Add(-time.Hour), true)); d != 0 {
+		t.Errorf("a mark in the future: %s", d)
+	}
+}