Commit `01856d444d`

01856d444da2d5d102113c67e35d1a477bae0541

parent: 90622795ab

Verified · cmc ci/build: success ci/test: success

cmc <hello@cleberg.net> · 2026-09-28 08:33 UTC

mail: require TLS to a non-local relay; implicit TLS option

Closes #280

Layout: unified · split

.gitbay/wiki/Admin.org +9 −2

   registration. Requires [mail].
 ** [mail]
-- =smtp_host= (host:port, 587 assumed), =from=, optional =smtp_user= /
+- =smtp_host= (host:port; 587 assumed, 465 with =tls = "implicit"=),
-  =smtp_pass=. STARTTLS when offered. Required for invite/open
+  =from=, optional =smtp_user= / =smtp_pass=. Required for invite/open
   registration and self-service =email add=; in closed mode you may omit
   it entirely and assert addresses by hand (below).
+- =tls= — =starttls= (default) or =implicit= (TLS from the first byte,
+  for relays on 465).
+- =require_tls= — with =starttls=, a relay that does not offer STARTTLS
+  gets no mail: delivery fails and retries, and the admin page's Mail
+  table shows the error. Unset, it is on for every relay except
+  =localhost= and loopback addresses; set =false= to allow plaintext
+  to a remote relay.
 ** [push]
 Push notifications to Apple devices, delivered by gitbayd talking to

.gitbay/wiki/Architecture/03-Deployment.org +1 −1

	@@ -57,7 +57,7 @@ a database check.
57	\| Destination \| Trigger \| TLS \| Guard \|	57	\| Destination \| Trigger \| TLS \| Guard \|
58	\|------------------------+-------------------------------+----------------------------------------------+----------------------------------------------------------------\|	58	\|------------------------+-------------------------------+----------------------------------------------+----------------------------------------------------------------\|
59	\| ACME directory \| certificate issue and renewal \| yes \| host policy limits names to the site and claimed pages domains (=main.go=) \|	59	\| ACME directory \| certificate issue and renewal \| yes \| host policy limits names to the site and claimed pages domains (=main.go=) \|
60	\| SMTP relay \| queued mail \| STARTTLS when offered \| Go's =PlainAuth= will not send credentials over plaintext to a non-local host (=internal/mail/mail.go=) \|	60	\| SMTP relay \| queued mail \| STARTTLS required for a non-local relay, or implicit TLS \| =mail.require_tls=; Go's =PlainAuth= will not send credentials over plaintext to a non-local host (=internal/mail/mail.go=) \|
61	\| APNs \| queued push \| yes, HTTP/2 \| provider token signed with the operator's .p8 key \|	61	\| APNs \| queued push \| yes, HTTP/2 \| provider token signed with the operator's .p8 key \|
62	\| Webhook URLs \| recorded events \| yes when https; certificate verified \| private, loopback and link-local targets refused at save and again at connect time; no redirects (=internal/webhook/webhook.go=) \|	62	\| Webhook URLs \| recorded events \| yes when https; certificate verified \| private, loopback and link-local targets refused at save and again at connect time; no redirects (=internal/webhook/webhook.go=) \|
63	\| Mirror URLs \| mirror schedule \| per URL \| the same address check at save time (=internal/control/mirrorcmd.go=); git makes the connection, so there is no connect-time re-check \|	63	\| Mirror URLs \| mirror schedule \| per URL \| the same address check at save time (=internal/control/mirrorcmd.go=); git makes the connection, so there is no connect-time re-check \|

.gitbay/wiki/Architecture/06-Data-and-Cryptography.org +1 −1

	@@ -60,7 +60,7 @@ secret, webhook secret and mirror token.
60	\| HTTP port 80 \| ACME challenges and redirect only \|	60	\| HTTP port 80 \| ACME challenges and redirect only \|
61	\| git:// \| none (public data only; off by default) \|	61	\| git:// \| none (public data only; off by default) \|
62	\| Runner ↔ server \| SSH \|	62	\| Runner ↔ server \| SSH \|
63	\| SMTP \| STARTTLS when the relay offers it \|	63	\| SMTP \| STARTTLS required unless the relay is local (=mail.require_tls=), or implicit TLS (=mail.tls=) \|
64	\| APNs \| TLS, HTTP/2 \|	64	\| APNs \| TLS, HTTP/2 \|
65	\| Webhooks \| TLS when the URL is https; HMAC-SHA256 body signature in =X-Gitbay-Signature-256= (=internal/webhook/webhook.go=) \|	65	\| Webhooks \| TLS when the URL is https; HMAC-SHA256 body signature in =X-Gitbay-Signature-256= (=internal/webhook/webhook.go=) \|
66	\| Mirrors \| per URL; token passed through =GIT_ASKPASS=, never argv (=internal/mirror/mirror.go=) \|	66	\| Mirrors \| per URL; token passed through =GIT_ASKPASS=, never argv (=internal/mirror/mirror.go=) \|

.gitbay/wiki/Architecture/09-Controls.org +1 −1

	@@ -77,7 +77,7 @@ chapter names of OWASP ASVS 4.0 where one fits.
77	\|---------------------------------------------+----------+------------------------------------------------------------------\|	77	\|---------------------------------------------+----------+------------------------------------------------------------------\|
78	\| SSRF protection on user-supplied URLs \| partial \| webhooks at save and connect; mirrors at save only (#279) \|	78	\| SSRF protection on user-supplied URLs \| partial \| webhooks at save and connect; mirrors at save only (#279) \|
79	\| Webhook payload integrity \| in place \| HMAC-SHA256 header \|	79	\| Webhook payload integrity \| in place \| HMAC-SHA256 header \|
80	\| SMTP credentials protected in transit \| partial \| STARTTLS opportunistic (#280); Go refuses PLAIN auth without TLS to a remote host \|	80	\| SMTP credentials protected in transit \| in place \| STARTTLS required for non-local relays, implicit TLS optional (=internal/mail/mail.go=) \|
81	\| Upload size limits \| in place \| per-owner storage quota at push (=internal/sshd/sshd.go=); API body 1 MiB \|	81	\| Upload size limits \| in place \| per-owner storage quota at push (=internal/sshd/sshd.go=); API body 1 MiB \|
82		82
83	** CI and build isolation	83	** CI and build isolation

.gitbay/wiki/Architecture/10-Known-Gaps.org −1

	@@ -20,7 +20,6 @@ what the 2026-09-27 review found; remove a row when its issue closes.
20	\| #274 \| Backups \| The local backup archive is not encrypted \| medium \|	20	\| #274 \| Backups \| The local backup archive is not encrypted \| medium \|
21	\| #275 \| Audit \| Refused writes are not audited; the audit table is writable by the daemon user \| medium \|	21	\| #275 \| Audit \| Refused writes are not audited; the audit table is writable by the daemon user \| medium \|
22	\| #279 \| SSRF \| Mirror URLs are checked when saved, not when git connects \| medium \|	22	\| #279 \| SSRF \| Mirror URLs are checked when saved, not when git connects \| medium \|
23	\| #280 \| Mail \| STARTTLS only when the relay offers it \| medium \|
24	\| #282 \| Hook socket \| Anything that can open =hook.sock= can act as any user \| medium \|	23	\| #282 \| Hook socket \| Anything that can open =hook.sock= can act as any user \| medium \|
25	\| #297 \| Credentials \| A browser session can mint tokens and keys that outlive it \| low \|	24	\| #297 \| Credentials \| A browser session can mint tokens and keys that outlive it \| low \|
26		25

CHANGELOG.org +4

   the login page's mailed links have (#278).
 - The HTTPS listener refuses TLS below 1.2, in both certificate modes
   (#281).
+- Mail to a non-local relay requires TLS by default; a relay that does
+  not offer STARTTLS gets no mail unless =mail.require_tls = false=
+  restores the old behaviour. =mail.tls = "implicit"= speaks TLS from
+  the first byte, for relays on port 465 (#280).
 * v1.36.0 — 2026-09-23

internal/mail/mail.go +41 −7

 // Package mail sends transactional email over SMTP: verification codes and
-// invites. STARTTLS is used when the server offers it; PLAIN auth when
+// invites. The connection is encrypted with STARTTLS, or with TLS from the
-// credentials are configured.
+// first byte when mail.tls = "implicit"; a relay that offers neither gets
+// nothing unless mail.require_tls is off. PLAIN auth when credentials are
+// configured.
 package mail
 import (
 	"crypto/tls"
+	"crypto/x509"
 	"fmt"
 	"net"
 	"net/smtp"
 	"gitbay.org/gitbay/internal/config"
 )
+// rootCAs verifies the relay's certificate; nil is the system pool.
+var rootCAs *x509.CertPool
 // Send delivers one plain-text message. cfg.Mail.SMTPHost is host:port.
 func Send(cfg config.Config, to, subject, body string) error {
 	m := cfg.Mail
 	if m.SMTPHost == "" || m.From == "" {
 		return fmt.Errorf("[mail] smtp_host and from must be configured")
 	}
+	implicit := m.TLS == "implicit"
 	host := m.SMTPHost
 	if !strings.Contains(host, ":") {
-		host += ":587"
+		if implicit {
+			host += ":465"
+		} else {
+			host += ":587"
+		}
 	}
 	hostname, _, _ := net.SplitHostPort(host)
+	tlsCfg := &tls.Config{ServerName: hostname, RootCAs: rootCAs}
 	msg := strings.NewReplacer("\n", "\r\n").Replace(fmt.Sprintf(
 		"From: %s\nTo: %s\nSubject: %s\nDate: %s\nMIME-Version: 1.0\nContent-Type: text/plain; charset=utf-8\n\n%s\n",
 		m.From, to, subject, time.Now().Format(time.RFC1123Z), body))
-	c, err := smtp.Dial(host)
+	c, err := dial(host, hostname, implicit, tlsCfg)
 	if err != nil {
 		return fmt.Errorf("smtp dial %s: %w", host, err)
 	}
 	defer c.Close()
-	if ok, _ := c.Extension("STARTTLS"); ok {
+	if !implicit {
-		if err := c.StartTLS(&tls.Config{ServerName: hostname}); err != nil {
+		if ok, _ := c.Extension("STARTTLS"); ok {
-			return fmt.Errorf("starttls: %w", err)
+			if err := c.StartTLS(tlsCfg); err != nil {
+				return fmt.Errorf("starttls: %w", err)
+			}
+		} else if m.TLSRequired() {
+			return fmt.Errorf("%s does not offer STARTTLS and mail.require_tls is on; not sending in clear", host)
 		}
 	}
 	if m.SMTPUser != "" {
 	}
 	return c.Quit()
 }
+// dial opens the SMTP session: plain TCP for STARTTLS, or TLS from the
+// first byte.
+func dial(addr, hostname string, implicit bool, tlsCfg *tls.Config) (*smtp.Client, error) {
+	if !implicit {
+		return smtp.Dial(addr)
+	}
+	conn, err := tls.Dial("tcp", addr, tlsCfg)
+	if err != nil {
+		return nil, err
+	}
+	c, err := smtp.NewClient(conn, hostname)
+	if err != nil {
+		conn.Close()
+		return nil, err
+	}
+	return c, nil
+}

internal/mail/mail_test.go added +142

@@ -0,0 +1,142 @@
	1	package mail
	2
	3	import (
	4	"bufio"
	5	"crypto/tls"
	6	"crypto/x509"
	7	"fmt"
	8	"net"
	9	"net/http"
	10	"net/http/httptest"
	11	"strings"
	12	"sync"
	13	"testing"
	14
	15	"gitbay.org/gitbay/internal/config"
	16	)
	17
	18	// fakeRelay is an SMTP server that never offers STARTTLS. Given a TLS
	19	// config it speaks TLS from the first byte, as a port-465 relay does.
	20	type fakeRelay struct {
	21	addr string
	22	mu sync.Mutex
	23	data []string
	24	}
	25
	26	func startRelay(t testing.T, tlsCfg tls.Config) *fakeRelay {
	27	t.Helper()
	28	ln, err := net.Listen("tcp", "127.0.0.1:0")
	29	if err != nil {
	30	t.Fatal(err)
	31	}
	32	if tlsCfg != nil {
	33	ln = tls.NewListener(ln, tlsCfg)
	34	}
	35	t.Cleanup(func() { ln.Close() })
	36	f := &fakeRelay{addr: ln.Addr().String()}
	37	go func() {
	38	for {
	39	conn, err := ln.Accept()
	40	if err != nil {
	41	return
	42	}
	43	go f.serve(conn)
	44	}
	45	}()
	46	return f
	47	}
	48
	49	func (f *fakeRelay) serve(conn net.Conn) {
	50	defer conn.Close()
	51	r := bufio.NewReader(conn)
	52	fmt.Fprint(conn, "220 fake\r\n")
	53	var body strings.Builder
	54	inData := false
	55	for {
	56	line, err := r.ReadString('\n')
	57	if err != nil {
	58	return
	59	}
	60	line = strings.TrimRight(line, "\r\n")
	61	switch {
	62	case inData && line == ".":
	63	f.mu.Lock()
	64	f.data = append(f.data, body.String())
	65	f.mu.Unlock()
	66	inData = false
	67	fmt.Fprint(conn, "250 ok\r\n")
	68	case inData:
	69	body.WriteString(line + "\n")
	70	case strings.HasPrefix(line, "EHLO"), strings.HasPrefix(line, "HELO"):
	71	fmt.Fprint(conn, "250-fake\r\n250 SIZE 1000000\r\n")
	72	case line == "DATA":
	73	inData = true
	74	fmt.Fprint(conn, "354 go\r\n")
	75	case line == "QUIT":
	76	fmt.Fprint(conn, "221 bye\r\n")
	77	return
	78	default:
	79	fmt.Fprint(conn, "250 ok\r\n")
	80	}
	81	}
	82	}
	83
	84	func (f *fakeRelay) delivered() int {
	85	f.mu.Lock()
	86	defer f.mu.Unlock()
	87	return len(f.data)
	88	}
	89
	90	func mailCfg(host string) config.Config {
	91	var cfg config.Config
	92	cfg.Mail.SMTPHost, cfg.Mail.From = host, "gitbay@example.test"
	93	return cfg
	94	}
	95
	96	func TestRequireTLSRefusesPlaintextRelay(t *testing.T) {
	97	relay := startRelay(t, nil)
	98	cfg := mailCfg(relay.addr)
	99	on := true
	100	cfg.Mail.RequireTLS = &on
	101	err := Send(cfg, "a@example.test", "subject", "body")
	102	if err == nil \|\| !strings.Contains(err.Error(), "STARTTLS") {
	103	t.Fatalf("Send = %v, want a refusal naming STARTTLS", err)
	104	}
	105	if n := relay.delivered(); n != 0 {
	106	t.Fatalf("%d message(s) sent in clear", n)
	107	}
	108	}
	109
	110	// A loopback relay has no network to cross; the default leaves it in
	111	// clear, which is what the e2e suite's fake relay relies on.
	112	func TestLoopbackRelayDefaultsToPlaintext(t *testing.T) {
	113	relay := startRelay(t, nil)
	114	if err := Send(mailCfg(relay.addr), "a@example.test", "subject", "body"); err != nil {
	115	t.Fatal(err)
	116	}
	117	if n := relay.delivered(); n != 1 {
	118	t.Fatalf("delivered %d, want 1", n)
	119	}
	120	}
	121
	122	func TestImplicitTLS(t *testing.T) {
	123	ts := httptest.NewTLSServer(http.NotFoundHandler())
	124	defer ts.Close()
	125	pool := x509.NewCertPool()
	126	pool.AddCert(ts.Certificate())
	127	prev := rootCAs
	128	rootCAs = pool
	129	defer func() { rootCAs = prev }()
	130
	131	relay := startRelay(t, &tls.Config{Certificates: ts.TLS.Certificates})
	132	cfg := mailCfg(relay.addr)
	133	cfg.Mail.TLS = "implicit"
	134	on := true
	135	cfg.Mail.RequireTLS = &on
	136	if err := Send(cfg, "a@example.test", "subject", "body"); err != nil {
	137	t.Fatal(err)
	138	}
	139	if n := relay.delivered(); n != 1 {
	140	t.Fatalf("delivered %d, want 1", n)
	141	}
	142	}

Commit 01856d444d

Commit `01856d444d`