feat(email): constrain automated company mail submission

docs/adr/automated-mail-submission.md

@@ -0,0 +1,44 @@
+# Automated mail submission
+
+**Status:** Proposed
+
+## Context
+
+The business portal needs invitation messages with one enforced company sender.
+Application credentials must not grant mailbox access or unrestricted submission.
+An optional upstream content hook cannot be the only boundary: the application
+must remain restricted when that hook is absent or unavailable.
+
+## Decision
+
+Use a private SMTP submission component between the application and company Email.
+It authenticates the application over TLS, validates the configured envelope and
+single message author, and forwards synchronously over verified upstream TLS.
+Its application credential differs from the upstream send-only credential and is
+not accepted by the upstream service. No successful acknowledgement is returned
+before the upstream accepts the complete message.
+
+The executable has no default listener. It is not installed or enabled by this
+source delivery. Deployment, private credential custody and real delivery remain
+under the dedicated-sender issue. Existing mail, inbound routing and the agents'
+restricted sender are unchanged; no external relay or subscription is introduced.
+
+## Alternatives
+
+- A scoped native DATA hook can reject invalid authors, but omission can skip it.
+  Using it alone would make application restriction depend on optional upstream
+  configuration and a separate activation hold.
+- Replacing the company mail server would expand the work into mailbox migration
+  and recovery. That is unnecessary for an application submission boundary.
+
+## Consequences
+
+The component adds one maintained process and separate private credentials. It
+needs bounded concurrency, sizes, deadlines, authentication attempts and rate
+limits, with no message or credential logging. It performs no background retry.
+A lost upstream acknowledgement can leave delivery uncertain; callers must use
+bounded retries and replay-safe invitation links rather than infer non-delivery.
+
+Loopback protocol tests use a separately authenticated SMTP peer and generated
+certificates. They are not deployed Stalwart, external delivery, SPF/DKIM/DMARC,
+customer enrollment or portal-activation proof. Those remain explicit parent gates.

go.mod

@@ -125,6 +125,8 @@ require (
 	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cloudflare/circl v1.6.4 // indirect
 	github.com/cosi-project/runtime v1.17.0
+	github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6
+	github.com/emersion/go-smtp v0.25.1
 	github.com/gertd/go-pluralize v0.2.1 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.33.0 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect

go.sum

@@ -84,6 +84,10 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/edsrzf/mmap-go v1.2.0 h1:hXLYlkbaPzt1SaQk+anYwKSRNhufIDCchSPkUD6dD84=
 github.com/edsrzf/mmap-go v1.2.0/go.mod h1:19H/e8pUPLicwkyNgOykDXkJ9F0MHE+Z52B8EIth78Q=
+github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 h1:oP4q0fw+fOSWn3DfFi4EXdT+B+gTtzx8GC9xsc26Znk=
+github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6/go.mod h1:iL2twTeMvZnrg54ZoPDNfJaJaqy0xIQFuBdrLsmspwQ=
+github.com/emersion/go-smtp v0.25.1 h1:y6nzefT6PtFeMItFw97GX/ZCkVbh0rqSXG8b3ang8/w=
+github.com/emersion/go-smtp v0.25.1/go.mod h1:ZtRRkbTyp2XTHCA+BmyTFTrj8xY4I+b4McvHxCU2gsQ=
 github.com/emicklei/go-restful/v3 v3.13.0 h1:C4Bl2xDndpU6nJ4bc1jXd+uTmYPVUwkD6bFY/oTyCes=
 github.com/emicklei/go-restful/v3 v3.13.0/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=
 github.com/frankban/quicktest v1.13.1 h1:xVm/f9seEhZFL9+n5kv5XLrGwy6elc4V9v/XFY2vmd8=

scripts/mail-submission/README.md

@@ -0,0 +1,75 @@
+# Automated mail submission
+
+This internal SMTP component constrains an application's automated mail before
+submitting it to company mail. It is not a mailbox, delivery queue or relay
+subscription. Nothing starts without an explicit command and private inputs.
+
+The application authenticates to this component over implicit TLS. Only its
+configured envelope sender and one matching `From` author are accepted. The
+component authenticates separately to the upstream SMTP service, using mandatory
+STARTTLS with an explicit CA and server name. The application credential must
+have no upstream account. Upstream credentials must belong to a dedicated,
+send-only identity; deployment must verify that restriction on the real MTA.
+
+Success means the upstream service acknowledged the final DATA command. It does
+not mean external delivery. A lost acknowledgement returns a temporary failure;
+the application must tolerate possible duplicates and use stable invitation
+identifiers. Permanent upstream submission refusals remain permanent failures.
+No protocol body, recipient, password or peer error is logged.
+
+## Private configuration
+
+Build from the repository root with `go build -o <output> ./scripts/mail-submission`.
+Use `mail-submission check --config-dir <directory>` to validate inputs without
+starting a listener. `mail-submission serve --config-dir <directory>` starts the
+explicitly configured listener. There is no default address, credential, sender
+or development mode.
+
+The directory contains these regular files, owned by root or the service user,
+with mode `0600`, `0400`, `0640` or `0440`:
+
+- `settings.json`: one JSON object with string members `listenAddress`, `sender`,
+  `senderName`, `clientUser`, `upstreamAddress`, `upstreamServerName`,
+  `upstreamUser` and optional `replyTo`.
+- `client-password` and `upstream-password`: distinct printable secrets of
+  32–256 bytes, without a trailing newline. Usernames must also be distinct.
+- `server.crt` and `server.key`: the receiving certificate chain and private key.
+- `upstream-ca.pem`: only PEM CA certificates for the upstream trust boundary.
+
+Unknown or duplicate JSON members, unresolved substitutions, malformed trust,
+leaf symlinks and unsafe file permissions are refused. Kubernetes Secret
+projections are read through one anchored `..data` generation. Rotate inputs by
+restarting the component; existing processes intentionally retain their selected
+generation. Do not put actual settings, passwords or certificates in Git.
+
+`listenAddress` is an explicit numeric IP and unprivileged port. The server
+requires TLS 1.2 or newer, bounds active connections to 16 and each connection to
+30 seconds, accepts at most three authentication attempts per connection and one
+recipient per message. Messages are limited to 1 MiB and headers to 64 KiB.
+Authentication has a shared burst allowance of sixteen attempts and replenishes\none allowance per second. Submission has a shared burst allowance of ten messages and replenishes one
+allowance every six seconds. RSET does not reset these budgets. The upstream
+connection has an absolute ten-second lifetime. Shutdown allows five seconds for
+active sessions, then closes them.
+
+A missing `replyTo` refuses all Reply-To headers. When configured, exactly one
+matching address is required. Sender, Return-Path and Resent headers are refused.
+The original accepted message bytes are submitted unchanged.
+
+## Validation and deployment boundary
+
+Run `go test -race ./scripts/mail-submission` and `go vet ./scripts/mail-submission`.
+Tests use generated fictional certificates and native Go SMTP peers on loopback.
+They cover author and envelope refusals, credential separation, receiving and
+upstream TLS, unavailable peers, permanent refusals, lost acknowledgements,
+resource bounds, private input validation and credential replacement.
+
+These peers are not the production MTA. This change creates no Deployment,
+listener in the live platform, mailbox, real credential or external message.
+Issue #5400 retains deployment, credential custody, protected recovery,
+upstream send-only policy and actual invitation-delivery acceptance. Its
+prerequisite recovery hold must remain intact. The portal remains closed until
+its separate end-to-end sign-in and invitation checks pass.
+
+The SMTP and SASL libraries are MIT-licensed (`github.com/emersion/go-smtp` and
+`github.com/emersion/go-sasl`). The repository's existing terms apply to this
+component's own source; no new license grant is introduced.

scripts/mail-submission/configuration.go

@@ -0,0 +1,171 @@
+package main
+
+import (
+	"bytes"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/json"
+	"encoding/pem"
+	"errors"
+	"io"
+	"os"
+	"syscall"
+	"time"
+)
+
+// privateFile only reads regular, non-executable files in the selected directory.
+// The root anchors all member reads; leaf symlinks are never followed.
+func privateFile(root *os.Root, name string, limit int64) ([]byte, error) {
+	file, err := root.OpenFile(name, os.O_RDONLY|syscall.O_NOFOLLOW, 0)
+	if err != nil {
+		return nil, errConfiguration
+	}
+	defer func() { _ = file.Close() }()
+	info, err := file.Stat()
+	if err != nil || !info.Mode().IsRegular() || info.Mode().Perm()&0o137 != 0 || info.Size() > limit {
+		return nil, errConfiguration
+	}
+	owner, ok := info.Sys().(*syscall.Stat_t)
+	if !ok || (owner.Uid != 0 && int64(owner.Uid) != int64(os.Geteuid())) {
+		return nil, errConfiguration
+	}
+	raw, err := io.ReadAll(io.LimitReader(file, limit+1))
+	if err != nil || int64(len(raw)) > limit {
+		return nil, errConfiguration
+	}
+	if err = file.Close(); err != nil {
+		return nil, errConfiguration
+	}
+	return raw, nil
+}
+
+func parseSettings(raw []byte) (settings, error) {
+	var result settings
+	fields := map[string]*string{"listenAddress": &result.ListenAddress, "sender": &result.Sender, "senderName": &result.SenderName, "clientUser": &result.ClientUser, "upstreamAddress": &result.UpstreamAddress, "upstreamServerName": &result.UpstreamServerName, "upstreamUser": &result.UpstreamUser, "replyTo": &result.ReplyTo}
+	decoder := json.NewDecoder(bytes.NewReader(raw))
+	token, err := decoder.Token()
+	if err != nil || token != json.Delim('{') {
+		return result, errConfiguration
+	}
+	seen := make(map[string]bool)
+	for decoder.More() {
+		token, err = decoder.Token()
+		if err != nil {
+			return result, errConfiguration
+		}
+		key, ok := token.(string)
+		destination, known := fields[key]
+		if !ok || !known || seen[key] {
+			return result, errConfiguration
+		}
+		seen[key] = true
+		value, valueErr := decoder.Token()
+		text, stringValue := value.(string)
+		if valueErr != nil || !stringValue {
+			return result, errConfiguration
+		}
+		*destination = text
+	}
+	token, err = decoder.Token()
+	if err != nil || token != json.Delim('}') {
+		return result, errConfiguration
+	}
+	if _, err = decoder.Token(); !errors.Is(err, io.EOF) {
+		return result, errConfiguration
+	}
+	return result, nil
+}
+
+func trustCertificates(raw []byte) (*x509.CertPool, error) {
+	pool := x509.NewCertPool()
+	count := 0
+	for len(bytes.TrimSpace(raw)) > 0 {
+		// pem.Decode otherwise silently skips a non-PEM prefix.
+		raw = bytes.TrimSpace(raw)
+		if !bytes.HasPrefix(raw, []byte("-----BEGIN CERTIFICATE-----")) {
+			return nil, errConfiguration
+		}
+		block, remaining := pem.Decode(raw)
+		if block == nil || block.Type != "CERTIFICATE" || len(block.Headers) != 0 {
+			return nil, errConfiguration
+		}
+		cert, err := x509.ParseCertificate(block.Bytes)
+		if err != nil || !cert.IsCA {
+			return nil, errConfiguration
+		}
+		pool.AddCert(cert)
+		count++
+		raw = remaining
+	}
+	if count == 0 {
+		return nil, errConfiguration
+	}
+	return pool, nil
+}
+
+func loadConfiguration(directory string) (cfg configuration, resultErr error) {
+	if directory == "" {
+		return cfg, errConfiguration
+	}
+	root, err := os.OpenRoot(directory)
+	if err != nil {
+		return cfg, errConfiguration
+	}
+	defer func(opened *os.Root) {
+		if closeErr := opened.Close(); closeErr != nil {
+			resultErr = errConfiguration
+		}
+	}(root)
+	// Kubernetes projects each Secret generation under ..data. Pin that directory
+	// once, before reading any members, rather than mixing two generations.
+	if _, err = root.Lstat("..data"); err == nil {
+		snapshot, e := root.OpenRoot("..data")
+		if e != nil {
+			return cfg, errConfiguration
+		}
+		defer func(opened *os.Root) {
+			if closeErr := opened.Close(); closeErr != nil {
+				resultErr = errConfiguration
+			}
+		}(snapshot)
+		root = snapshot
+	} else if !errors.Is(err, os.ErrNotExist) {
+		return cfg, errConfiguration
+	}
+	members := make(map[string][]byte)
+	for _, name := range []string{"settings.json", "client-password", "upstream-password", "server.crt", "server.key", "upstream-ca.pem"} {
+		limit := int64(64 << 10)
+		if name == "settings.json" {
+			limit = 4 << 10
+		}
+		members[name], err = privateFile(root, name, limit)
+		if err != nil {
+			return cfg, errConfiguration
+		}
+	}
+	cfg.Settings, err = parseSettings(members["settings.json"])
+	if err != nil {
+		return cfg, errConfiguration
+	}
+	cfg.ClientPassword = string(members["client-password"])
+	cfg.UpstreamPassword = string(members["upstream-password"])
+	pair, err := tls.X509KeyPair(members["server.crt"], members["server.key"])
+	if err != nil {
+		return cfg, errConfiguration
+	}
+	leaf, err := x509.ParseCertificate(pair.Certificate[0])
+	if err != nil {
+		return cfg, errConfiguration
+	}
+	now := time.Now()
+	if now.Before(leaf.NotBefore) || !now.Before(leaf.NotAfter) {
+		return cfg, errConfiguration
+	}
+	roots, err := trustCertificates(members["upstream-ca.pem"])
+	if err != nil {
+		return cfg, errConfiguration
+	}
+	cfg.ServerTLS = &tls.Config{MinVersion: tls.VersionTLS12, Certificates: []tls.Certificate{pair}}
+	cfg.UpstreamTLS = &tls.Config{MinVersion: tls.VersionTLS12, RootCAs: roots, ServerName: cfg.Settings.UpstreamServerName}
+	return cfg, cfg.validate()
+}