feat(router): moderation, confirmation commands and VERP bounces

- Hold posts on moderated lists and release them on approval
- Add +join, +leave and +confirm-TOKEN command addresses
- Send one message per recipient with a signed bounce envelope sender
- Disable members after 3 hard bounces and skip them on delivery
- Reject forged bounce addresses and tokens from other lists
This commit is contained in:
tgiachi 2026-11-09 15:04:26 +01:00
commit 91c01bcb83
3 changed files with 570 additions and 6 deletions

174
internal/router/commands.go Normal file
View file

@ -0,0 +1,174 @@
package router
import (
"context"
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"mime"
"net/mail"
"regexp"
"strconv"
"strings"
"time"
"codeberg.org/squidd/parsimony/internal/outbound"
"codeberg.org/squidd/parsimony/internal/store"
)
// bounceThreshold is the number of hard bounces after which a member is disabled.
const bounceThreshold = 3
var statusRe = regexp.MustCompile(`(?mi)^Status:\s*([245])\.\d+\.\d+`)
func (r *Router) secret() ([]byte, error) {
r.secretOnce.Do(func() { r.secretVal, r.secretErr = r.store.Secret() })
return r.secretVal, r.secretErr
}
func (r *Router) mac(memberID int64) string {
key, err := r.secret()
if err != nil {
return ""
}
h := hmac.New(sha256.New, key)
fmt.Fprintf(h, "bounce:%d", memberID)
return hex.EncodeToString(h.Sum(nil))[:12]
}
// bounceAddress returns the VERP envelope sender for a member, or "" on error.
func (r *Router) bounceAddress(l store.List, memberID int64) string {
mac := r.mac(memberID)
if mac == "" {
return ""
}
return fmt.Sprintf("%s+bounce-%d-%s@%s", l.Name, memberID, mac, l.Domain)
}
// Command handles list command addresses such as dev+join@example.org.
// handled is false when rcpt is a plain list address (use Route for those).
func (r *Router) Command(ctx context.Context, out outbound.Sender, sender, rcpt string, data []byte) (handled bool, err error) {
local, domain, ok := strings.Cut(strings.ToLower(strings.TrimSpace(rcpt)), "@")
if !ok {
return false, nil
}
name, tag, hasTag := strings.Cut(local, "+")
if !hasTag {
return false, nil
}
l, err := r.store.FindList(name + "@" + domain)
if errors.Is(err, store.ErrNotFound) {
return true, ErrUnknownList
}
if err != nil {
return true, err
}
switch {
case tag == "join":
return true, r.join(ctx, out, l, sender)
case tag == "leave":
return true, r.leave(ctx, out, l, sender)
case strings.HasPrefix(tag, "confirm-"):
return true, r.confirm(l, strings.TrimPrefix(tag, "confirm-"))
case tag == "bounce":
return true, nil // system mail without a token: nothing to learn from it
case strings.HasPrefix(tag, "bounce-"):
return true, r.bounce(l, strings.TrimPrefix(tag, "bounce-"), data)
}
return true, ErrUnknownList
}
func (r *Router) join(ctx context.Context, out outbound.Sender, l store.List, sender string) error {
if sender == "" {
return nil
}
if l.JoinPolicy != store.JoinOpen {
return ErrJoinClosed
}
if ok, err := r.store.IsMember(l.ID, sender); err != nil || ok {
return err // members get no mail: it would leak membership
}
return r.askConfirmation(ctx, out, l, sender, store.ActionJoin)
}
func (r *Router) leave(ctx context.Context, out outbound.Sender, l store.List, sender string) error {
if sender == "" {
return nil
}
if ok, err := r.store.IsMember(l.ID, sender); err != nil || !ok {
return err
}
return r.askConfirmation(ctx, out, l, sender, store.ActionLeave)
}
func (r *Router) askConfirmation(ctx context.Context, out outbound.Sender, l store.List, addr, action string) error {
token, created, err := r.store.CreatePending(l.ID, addr, action)
if err != nil || !created {
return err
}
verb, subject := "join", "Confirm your subscription to "+l.Title
if action == store.ActionLeave {
verb, subject = "leave", "Confirm your unsubscription from "+l.Title
}
msg := fmt.Sprintf("From: %s\r\nTo: %s\r\nReply-To: %s+confirm-%s@%s\r\nSubject: %s\r\nDate: %s\r\n"+
"Message-ID: <%s.%s@%s>\r\nAuto-Submitted: auto-generated\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n"+
"Someone, probably you, asked to %s %s.\r\n\r\n"+
"To confirm, just reply to this message. The request expires in 72 hours.\r\n"+
"If you did not ask for this, ignore this message and nothing will happen.\r\n",
(&mail.Address{Name: l.Title, Address: l.Address()}).String(),
(&mail.Address{Address: addr}).String(),
l.Name, token, l.Domain,
mime.QEncoding.Encode("utf-8", subject),
time.Now().Format(time.RFC1123Z),
token[:8], strconv.FormatInt(time.Now().UnixNano(), 36), l.Domain,
verb, l.Address())
return out.Send(ctx, l.Name+"+bounce@"+l.Domain, []string{addr}, []byte(msg))
}
func (r *Router) confirm(l store.List, token string) error {
p, err := r.store.ConfirmPending(token)
if errors.Is(err, store.ErrNotFound) || (err == nil && p.ListID != l.ID) {
return ErrBadToken
}
if err != nil {
return err
}
switch p.Action {
case store.ActionJoin:
if l.JoinPolicy != store.JoinOpen {
return ErrJoinClosed
}
return r.store.AddMember(l.ID, p.Address, "")
case store.ActionLeave:
if err := r.store.RemoveMember(l.ID, p.Address); err != nil && !errors.Is(err, store.ErrNotFound) {
return err
}
}
return nil
}
func (r *Router) bounce(l store.List, tag string, data []byte) error {
idStr, mac, ok := strings.Cut(tag, "-")
id, err := strconv.ParseInt(idStr, 10, 64)
if !ok || err != nil {
return ErrBadToken
}
want := r.mac(id)
if want == "" || !hmac.Equal([]byte(mac), []byte(want)) {
return ErrBadToken
}
m, err := r.store.MemberByID(id)
if errors.Is(err, store.ErrNotFound) || (err == nil && m.ListID != l.ID) {
return ErrBadToken
}
if err != nil {
return err
}
if sm := statusRe.FindSubmatch(data); sm != nil && string(sm[1]) == "5" {
_, err = r.store.RecordHardBounce(m.ID, bounceThreshold)
}
return err
}

316
internal/router/m2_test.go Normal file
View file

@ -0,0 +1,316 @@
package router
import (
"context"
"errors"
"fmt"
"strings"
"testing"
"codeberg.org/squidd/parsimony/internal/outbound"
"codeberg.org/squidd/parsimony/internal/store"
)
type env struct {
r *Router
s *store.Store
out *outbound.Fake
list store.List
ctx context.Context
alice int64
}
func newEnv(t *testing.T) *env {
t.Helper()
s, err := store.Open(":memory:")
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { s.Close() })
l, _ := s.CreateList("dev", "example.org", "Dev")
s.AddMember(l.ID, "alice@example.com", "Alice")
s.AddMember(l.ID, "bob@example.com", "Bob")
ms, _ := s.Members(l.ID)
return &env{r: New(s), s: s, out: &outbound.Fake{}, list: l, ctx: context.Background(), alice: ms[0].ID}
}
func lastMail(t *testing.T, out *outbound.Fake) outbound.Sent {
t.Helper()
if len(out.Sent) == 0 {
t.Fatal("no mail was sent")
}
return out.Sent[len(out.Sent)-1]
}
func TestSendUsesVERPPerRecipient(t *testing.T) {
e := newEnv(t)
res, err := e.r.Route("alice@example.com", "dev@example.org", []byte(sample))
if err != nil {
t.Fatal(err)
}
if err := e.r.Send(e.ctx, e.out, res); err != nil {
t.Fatal(err)
}
if len(e.out.Sent) != 2 {
t.Fatalf("want one send per recipient, got %d", len(e.out.Sent))
}
seen := map[string]bool{}
for _, m := range e.out.Sent {
if len(m.To) != 1 {
t.Fatalf("to = %v", m.To)
}
if !strings.HasPrefix(m.From, "dev+bounce-") || !strings.HasSuffix(m.From, "@example.org") {
t.Fatalf("envelope from = %q", m.From)
}
seen[m.From] = true
}
if len(seen) != 2 {
t.Fatal("each recipient needs a distinct bounce address")
}
}
func TestDisabledMembersAreSkipped(t *testing.T) {
e := newEnv(t)
for i := 0; i < 3; i++ {
e.s.RecordHardBounce(e.alice, 3)
}
res, err := e.r.Route("bob@example.com", "dev@example.org", []byte(sample))
if err != nil {
t.Fatal(err)
}
if len(res.Recipients) != 1 || res.Recipients[0].Address != "bob@example.com" {
t.Fatalf("recipients: %+v", res.Recipients)
}
}
func TestModeratedListHoldsPosts(t *testing.T) {
e := newEnv(t)
e.s.SetPolicies(e.list.ID, store.PostModerated, store.JoinOpen)
for _, sender := range []string{"alice@example.com", "stranger@x.com"} {
_, err := e.r.Route(sender, "dev@example.org", []byte(sample))
if !errors.Is(err, ErrHeld) {
t.Fatalf("%s: want ErrHeld, got %v", sender, err)
}
}
held, _ := e.s.ListHeld(e.list.ID)
if len(held) != 2 {
t.Fatalf("held: %d", len(held))
}
if len(e.out.Sent) != 0 {
t.Fatal("nothing may be sent while held")
}
}
func TestReleaseHeld(t *testing.T) {
e := newEnv(t)
e.s.SetPolicies(e.list.ID, store.PostModerated, store.JoinOpen)
e.r.Route("stranger@x.com", "dev@example.org", []byte(sample))
held, _ := e.s.ListHeld(e.list.ID)
if err := e.r.Release(e.ctx, e.out, held[0].ID); err != nil {
t.Fatal(err)
}
if len(e.out.Sent) != 2 {
t.Fatalf("sent = %d", len(e.out.Sent))
}
if !strings.Contains(string(e.out.Sent[0].Data), "List-Id: Dev <dev.example.org>") {
t.Error("released mail must carry list headers")
}
if rest, _ := e.s.ListHeld(e.list.ID); len(rest) != 0 {
t.Fatal("released message must leave the queue")
}
if err := e.r.Release(e.ctx, e.out, held[0].ID); !errors.Is(err, store.ErrNotFound) {
t.Fatalf("want ErrNotFound, got %v", err)
}
}
func token(t *testing.T, m outbound.Sent) string {
t.Helper()
const marker = "Reply-To: dev+confirm-"
i := strings.Index(string(m.Data), marker)
if i < 0 {
t.Fatalf("no confirm address in %q", m.Data)
}
rest := string(m.Data)[i+len(marker):]
return rest[:strings.Index(rest, "@")]
}
func TestJoinFlow(t *testing.T) {
e := newEnv(t)
handled, err := e.r.Command(e.ctx, e.out, "carol@x.com", "dev+join@example.org", nil)
if !handled || err != nil {
t.Fatalf("join: %v %v", handled, err)
}
m := lastMail(t, e.out)
if len(m.To) != 1 || m.To[0] != "carol@x.com" {
t.Fatalf("confirmation must go to the requester: %+v", m.To)
}
if ok, _ := e.s.IsMember(e.list.ID, "carol@x.com"); ok {
t.Fatal("not a member before confirming")
}
tok := token(t, m)
handled, err = e.r.Command(e.ctx, e.out, "carol@x.com", "dev+confirm-"+tok+"@example.org", nil)
if !handled || err != nil {
t.Fatalf("confirm: %v %v", handled, err)
}
if ok, _ := e.s.IsMember(e.list.ID, "carol@x.com"); !ok {
t.Fatal("carol must be a member after confirming")
}
_, err = e.r.Command(e.ctx, e.out, "carol@x.com", "dev+confirm-"+tok+"@example.org", nil)
if !errors.Is(err, ErrBadToken) {
t.Fatalf("reused token: want ErrBadToken, got %v", err)
}
}
func TestJoinRateLimitedAndSilentForMembers(t *testing.T) {
e := newEnv(t)
e.r.Command(e.ctx, e.out, "carol@x.com", "dev+join@example.org", nil)
e.r.Command(e.ctx, e.out, "carol@x.com", "dev+join@example.org", nil)
if len(e.out.Sent) != 1 {
t.Fatalf("second request must not send mail, sent %d", len(e.out.Sent))
}
e.r.Command(e.ctx, e.out, "alice@example.com", "dev+join@example.org", nil)
if len(e.out.Sent) != 1 {
t.Fatal("existing members get no mail")
}
e.r.Command(e.ctx, e.out, "", "dev+join@example.org", nil)
if len(e.out.Sent) != 1 {
t.Fatal("empty sender is ignored")
}
}
func TestJoinClosed(t *testing.T) {
e := newEnv(t)
e.s.SetPolicies(e.list.ID, store.PostMembers, store.JoinClosed)
_, err := e.r.Command(e.ctx, e.out, "carol@x.com", "dev+join@example.org", nil)
if !errors.Is(err, ErrJoinClosed) {
t.Fatalf("want ErrJoinClosed, got %v", err)
}
if len(e.out.Sent) != 0 {
t.Fatal("no mail for closed lists")
}
}
func TestConfirmAfterListClosed(t *testing.T) {
e := newEnv(t)
e.r.Command(e.ctx, e.out, "carol@x.com", "dev+join@example.org", nil)
tok := token(t, lastMail(t, e.out))
e.s.SetPolicies(e.list.ID, store.PostMembers, store.JoinClosed)
_, err := e.r.Command(e.ctx, e.out, "carol@x.com", "dev+confirm-"+tok+"@example.org", nil)
if !errors.Is(err, ErrJoinClosed) {
t.Fatalf("want ErrJoinClosed, got %v", err)
}
if ok, _ := e.s.IsMember(e.list.ID, "carol@x.com"); ok {
t.Fatal("must not join a closed list")
}
}
func TestLeaveFlow(t *testing.T) {
e := newEnv(t)
e.r.Command(e.ctx, e.out, "alice@example.com", "dev+leave@example.org", nil)
m := lastMail(t, e.out)
if m.To[0] != "alice@example.com" {
t.Fatalf("to = %v", m.To)
}
if ok, _ := e.s.IsMember(e.list.ID, "alice@example.com"); !ok {
t.Fatal("still a member before confirming")
}
e.r.Command(e.ctx, e.out, "alice@example.com", "dev+confirm-"+token(t, m)+"@example.org", nil)
if ok, _ := e.s.IsMember(e.list.ID, "alice@example.com"); ok {
t.Fatal("alice must be gone")
}
// Leaving when not a member sends nothing.
n := len(e.out.Sent)
e.r.Command(e.ctx, e.out, "zed@x.com", "dev+leave@example.org", nil)
if len(e.out.Sent) != n {
t.Fatal("non-members get no mail")
}
}
func TestConfirmTokenFromOtherList(t *testing.T) {
e := newEnv(t)
e.s.CreateList("ops", "example.org", "Ops")
e.r.Command(e.ctx, e.out, "carol@x.com", "dev+join@example.org", nil)
tok := token(t, lastMail(t, e.out))
_, err := e.r.Command(e.ctx, e.out, "carol@x.com", "ops+confirm-"+tok+"@example.org", nil)
if !errors.Is(err, ErrBadToken) {
t.Fatalf("want ErrBadToken, got %v", err)
}
}
func TestCommandNotHandledForPlainAddress(t *testing.T) {
e := newEnv(t)
handled, err := e.r.Command(e.ctx, e.out, "a@x.com", "dev@example.org", nil)
if handled || err != nil {
t.Fatalf("plain address: %v %v", handled, err)
}
}
func TestUnknownCommandAndList(t *testing.T) {
e := newEnv(t)
for _, rcpt := range []string{"dev+bogus@example.org", "nope+join@example.org"} {
handled, err := e.r.Command(e.ctx, e.out, "a@x.com", rcpt, nil)
if !handled || !errors.Is(err, ErrUnknownList) {
t.Errorf("%s: %v %v", rcpt, handled, err)
}
}
}
func bounceMsg(status string) []byte {
return []byte(fmt.Sprintf("Subject: Undelivered Mail\r\nContent-Type: text/plain\r\n\r\nAction: failed\r\nStatus: %s\r\nDiagnostic-Code: smtp; 550 no such user\r\n", status))
}
func TestHardBouncesDisableMember(t *testing.T) {
e := newEnv(t)
addr := e.r.bounceAddress(e.list, e.alice)
for i := 0; i < 3; i++ {
handled, err := e.r.Command(e.ctx, e.out, "", addr, bounceMsg("5.1.1"))
if !handled || err != nil {
t.Fatalf("bounce: %v %v", handled, err)
}
}
m, _ := e.s.MemberByID(e.alice)
if !m.Disabled || m.BounceCount != 3 {
t.Fatalf("member: %+v", m)
}
}
func TestSoftBounceIgnored(t *testing.T) {
e := newEnv(t)
e.r.Command(e.ctx, e.out, "", e.r.bounceAddress(e.list, e.alice), bounceMsg("4.2.2"))
if m, _ := e.s.MemberByID(e.alice); m.BounceCount != 0 {
t.Fatalf("soft bounce counted: %+v", m)
}
}
func TestForgedBounceRejected(t *testing.T) {
e := newEnv(t)
addr := fmt.Sprintf("dev+bounce-%d-000000000000@example.org", e.alice)
_, err := e.r.Command(e.ctx, e.out, "", addr, bounceMsg("5.1.1"))
if !errors.Is(err, ErrBadToken) {
t.Fatalf("want ErrBadToken, got %v", err)
}
if m, _ := e.s.MemberByID(e.alice); m.BounceCount != 0 {
t.Fatal("forged bounce must not count")
}
}
func TestBounceFromOtherListRejected(t *testing.T) {
e := newEnv(t)
e.s.CreateList("ops", "example.org", "Ops")
ops, _ := e.s.FindList("ops@example.org")
addr := e.r.bounceAddress(ops, e.alice) // valid MAC but alice is not in ops
_, err := e.r.Command(e.ctx, e.out, "", addr, bounceMsg("5.1.1"))
if !errors.Is(err, ErrBadToken) {
t.Fatalf("want ErrBadToken, got %v", err)
}
}
func TestSystemBounceAddressDiscarded(t *testing.T) {
e := newEnv(t)
handled, err := e.r.Command(e.ctx, e.out, "", "dev+bounce@example.org", bounceMsg("5.1.1"))
if !handled || err != nil {
t.Fatalf("%v %v", handled, err)
}
}

View file

@ -2,23 +2,40 @@
package router
import (
"context"
"errors"
"fmt"
"log"
"sync"
"codeberg.org/squidd/parsimony/internal/outbound"
"codeberg.org/squidd/parsimony/internal/store"
)
var (
// ErrUnknownList means the recipient address is not a list.
// ErrUnknownList means the recipient address is not a list or a list command.
ErrUnknownList = errors.New("unknown list")
// ErrNotMember means the sender may not post to the list.
ErrNotMember = errors.New("sender is not a member")
// ErrHeld means the message was queued for moderation. It is not a failure.
ErrHeld = errors.New("held for moderation")
// ErrBadToken means a confirmation or bounce token is invalid, used or expired.
ErrBadToken = errors.New("invalid or expired token")
// ErrJoinClosed means the list does not accept self-service subscriptions.
ErrJoinClosed = errors.New("list is closed")
)
// Recipient is a subscriber that receives a message.
type Recipient struct {
ID int64 // member id, used for the VERP bounce address
Address string
}
// Result describes how to deliver an accepted message.
type Result struct {
List store.List
Recipients []string // subscriber addresses
Data []byte // message to send
Recipients []Recipient
Data []byte // message to send, with list headers
}
// Router applies list policy to incoming messages.
@ -26,12 +43,17 @@ type Router struct {
store *store.Store
// BaseURL is the public web URL; enables one-click unsubscribe when set.
BaseURL string
secretOnce sync.Once
secretVal []byte
secretErr error
}
// New creates a Router backed by s.
func New(s *store.Store) *Router { return &Router{store: s} }
// Route validates a message from sender to the list address rcpt.
// Moderated lists queue the message and return ErrHeld.
func (r *Router) Route(sender, rcpt string, data []byte) (Result, error) {
l, err := r.store.FindList(rcpt)
if errors.Is(err, store.ErrNotFound) {
@ -40,6 +62,12 @@ func (r *Router) Route(sender, rcpt string, data []byte) (Result, error) {
if err != nil {
return Result{}, err
}
if l.PostPolicy == store.PostModerated {
if _, err := r.store.HoldMessage(l.ID, sender, data); err != nil {
return Result{}, err
}
return Result{}, ErrHeld
}
ok, err := r.store.IsMember(l.ID, sender)
if err != nil {
return Result{}, err
@ -47,13 +75,18 @@ func (r *Router) Route(sender, rcpt string, data []byte) (Result, error) {
if !ok {
return Result{}, ErrNotMember
}
members, err := r.store.Members(l.ID)
return r.prepare(l, data)
}
// prepare builds the delivery plan for a list.
func (r *Router) prepare(l store.List, data []byte) (Result, error) {
members, err := r.store.ActiveMembers(l.ID)
if err != nil {
return Result{}, err
}
rcpts := make([]string, len(members))
rcpts := make([]Recipient, len(members))
for i, m := range members {
rcpts[i] = m.Address
rcpts[i] = Recipient{ID: m.ID, Address: m.Address}
}
out, err := rewrite(l, r.BaseURL, data)
if err != nil {
@ -61,3 +94,44 @@ func (r *Router) Route(sender, rcpt string, data []byte) (Result, error) {
}
return Result{List: l, Recipients: rcpts, Data: out}, nil
}
// Send delivers the message to every recipient, each with its own signed
// bounce address (VERP). Individual failures are logged and skipped; an error is
// returned only when nobody could be reached, so a retry cannot duplicate mail.
func (r *Router) Send(ctx context.Context, out outbound.Sender, res Result) error {
failed := 0
for _, rc := range res.Recipients {
from := r.bounceAddress(res.List, rc.ID)
if from == "" {
return errors.New("cannot create bounce address")
}
if err := out.Send(ctx, from, []string{rc.Address}, res.Data); err != nil {
failed++
log.Printf("deliver %s to %s: %v", res.List.Address(), rc.Address, err)
}
}
if failed > 0 && failed == len(res.Recipients) {
return fmt.Errorf("delivery failed for all %d recipients", failed)
}
return nil
}
// Release approves a held message and delivers it.
func (r *Router) Release(ctx context.Context, out outbound.Sender, heldID int64) error {
h, err := r.store.GetHeld(heldID)
if err != nil {
return err
}
l, err := r.store.GetList(h.ListID)
if err != nil {
return err
}
res, err := r.prepare(l, h.Data)
if err != nil {
return err
}
if err := r.Send(ctx, out, res); err != nil {
return err
}
return r.store.DeleteHeld(heldID)
}