feat(router): archive accepted posts and add per-recipient unsubscribe links

- Archive the original message on delivery and on release, never when held or rejected
- Log archive failures instead of blocking delivery
- Add List-Unsubscribe per recipient: signed one-click URL and the +leave address
- Add signed unsubscribe tokens bound to their purpose
- Fix the mailto unsubscribe address, +unsubscribe was not a known command
This commit is contained in:
tgiachi 2026-11-09 15:20:01 +01:00
commit 8253dd608e
6 changed files with 313 additions and 34 deletions

View file

@ -28,19 +28,21 @@ func (r *Router) secret() ([]byte, error) {
return r.secretVal, r.secretErr
}
func (r *Router) mac(memberID int64) string {
// mac signs a member id for one purpose ("bounce" or "unsub"), so a token
// made for one use cannot be replayed for another.
func (r *Router) mac(purpose string, memberID int64) string {
key, err := r.secret()
if err != nil {
return ""
}
h := hmac.New(sha256.New, key)
fmt.Fprintf(h, "bounce:%d", memberID)
fmt.Fprintf(h, "%s:%d", purpose, 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)
mac := r.mac("bounce", memberID)
if mac == "" {
return ""
}
@ -156,7 +158,7 @@ func (r *Router) bounce(l store.List, tag string, data []byte) error {
if !ok || err != nil {
return ErrBadToken
}
want := r.mac(id)
want := r.mac("bounce", id)
if want == "" || !hmac.Equal([]byte(mac), []byte(want)) {
return ErrBadToken
}
@ -172,3 +174,57 @@ func (r *Router) bounce(l store.List, tag string, data []byte) error {
}
return err
}
// UnsubscribeToken returns the signed token used in one-click unsubscribe links
// for a member, or "" if the secret is unavailable.
func (r *Router) UnsubscribeToken(memberID int64) string {
mac := r.mac("unsub", memberID)
if mac == "" {
return ""
}
return fmt.Sprintf("%d-%s", memberID, mac)
}
// parseUnsubscribe verifies a token and returns the member id.
func (r *Router) parseUnsubscribe(token string) (int64, error) {
idStr, mac, ok := strings.Cut(token, "-")
id, err := strconv.ParseInt(idStr, 10, 64)
if !ok || err != nil || id <= 0 {
return 0, ErrBadToken
}
want := r.mac("unsub", id)
if want == "" || !hmac.Equal([]byte(mac), []byte(want)) {
return 0, ErrBadToken
}
return id, nil
}
// CheckUnsubscribe validates a token and returns the list it belongs to,
// without changing anything. ErrGone means the member is already unsubscribed.
func (r *Router) CheckUnsubscribe(token string) (store.List, error) {
id, err := r.parseUnsubscribe(token)
if err != nil {
return store.List{}, err
}
m, err := r.store.MemberByID(id)
if errors.Is(err, store.ErrNotFound) {
return store.List{}, ErrGone
}
if err != nil {
return store.List{}, err
}
return r.store.GetList(m.ListID)
}
// Unsubscribe removes the member behind a valid token. Repeating it succeeds,
// because mail clients may send the one-click request more than once.
func (r *Router) Unsubscribe(token string) error {
id, err := r.parseUnsubscribe(token)
if err != nil {
return err
}
if err := r.store.DeleteMember(id); err != nil && !errors.Is(err, store.ErrNotFound) {
return err
}
return nil
}

View file

@ -6,16 +6,15 @@ import (
"fmt"
"io"
"net/mail"
"strings"
"github.com/emersion/go-message/textproto"
"codeberg.org/squidd/parsimony/internal/store"
)
// rewrite adds list headers and rewrites From so DMARC alignment holds.
// rewrite adds the list headers shared by every recipient and rewrites From so DMARC alignment holds.
// The body is copied byte for byte.
func rewrite(l store.List, baseURL string, data []byte) ([]byte, error) {
func rewrite(l store.List, data []byte) ([]byte, error) {
br := bufio.NewReader(bytes.NewReader(data))
h, err := textproto.ReadHeader(br)
if err != nil {
@ -30,12 +29,7 @@ func rewrite(l store.List, baseURL string, data []byte) ([]byte, error) {
id := l.Name + "." + l.Domain
h.Set("List-Id", fmt.Sprintf("%s <%s>", l.Title, id))
h.Set("List-Post", "<mailto:"+l.Address()+">")
unsub := "<mailto:" + l.Name + "+unsubscribe@" + l.Domain + ">"
if baseURL != "" {
unsub = "<" + strings.TrimRight(baseURL, "/") + "/unsubscribe/" + id + ">, " + unsub
h.Set("List-Unsubscribe-Post", "List-Unsubscribe=One-Click")
}
h.Set("List-Unsubscribe", unsub)
// List-Unsubscribe is per recipient: Router.Send adds it.
h.Set("Precedence", "list")
if orig := h.Get("From"); orig != "" {

203
internal/router/m3_test.go Normal file
View file

@ -0,0 +1,203 @@
package router
import (
"errors"
"fmt"
"regexp"
"strings"
"testing"
"codeberg.org/squidd/parsimony/internal/store"
)
const post = "From: Alice Smith <alice@example.com>\r\nTo: dev@example.org\r\nSubject: Hello list\r\n" +
"Message-ID: <hello@example.com>\r\nContent-Type: text/plain\r\n\r\nthe body\r\n"
func TestAcceptedPostIsArchivedFromTheOriginal(t *testing.T) {
e := newEnv(t)
if _, err := e.r.Route("alice@example.com", "dev@example.org", []byte(post)); err != nil {
t.Fatal(err)
}
ms, total, _ := e.s.ListMessages(e.list.ID, 10, 0)
if total != 1 {
t.Fatalf("archived = %d", total)
}
m, _ := e.s.GetMessage(ms[0].ID)
if m.Subject != "Hello list" || m.Body != "the body\n" || m.MessageID != "<hello@example.com>" {
t.Fatalf("message: %+v", m)
}
if m.Sender != "Alice Smith" {
t.Fatalf("sender must be the original author, not the list rewrite: %q", m.Sender)
}
}
func TestArchivePolicyOffStoresNothing(t *testing.T) {
e := newEnv(t)
e.s.SetPolicies(e.list.ID, store.PostMembers, store.JoinOpen, store.ArchiveOff)
e.r.Route("alice@example.com", "dev@example.org", []byte(post))
if _, total, _ := e.s.ListMessages(e.list.ID, 10, 0); total != 0 {
t.Fatalf("archived = %d", total)
}
}
func TestRetryDoesNotDuplicateTheArchive(t *testing.T) {
e := newEnv(t)
e.r.Route("alice@example.com", "dev@example.org", []byte(post))
e.r.Route("alice@example.com", "dev@example.org", []byte(post))
if _, total, _ := e.s.ListMessages(e.list.ID, 10, 0); total != 1 {
t.Fatalf("archived = %d", total)
}
}
func TestRejectedAndHeldPostsAreNotArchived(t *testing.T) {
e := newEnv(t)
e.r.Route("mallory@evil.com", "dev@example.org", []byte(post)) // rejected
e.s.SetPolicies(e.list.ID, store.PostModerated, store.JoinOpen, store.ArchivePrivate)
e.r.Route("alice@example.com", "dev@example.org", []byte(post)) // held
if _, total, _ := e.s.ListMessages(e.list.ID, 10, 0); total != 0 {
t.Fatalf("archived = %d", total)
}
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 _, total, _ := e.s.ListMessages(e.list.ID, 10, 0); total != 1 {
t.Fatalf("released post must be archived, got %d", total)
}
}
func TestUnparseablePostIsStillDelivered(t *testing.T) {
e := newEnv(t)
res, err := e.r.Route("alice@example.com", "dev@example.org", []byte("\r\nno headers at all\r\n"))
if err != nil {
t.Fatalf("archive failures must not block delivery: %v", err)
}
if len(res.Recipients) != 2 {
t.Fatalf("recipients: %+v", res.Recipients)
}
}
var unsubURL = regexp.MustCompile(`<https://lists\.example\.org/unsubscribe/([0-9]+-[0-9a-f]{12})>`)
func sendPost(t *testing.T, e *env) {
t.Helper()
res, err := e.r.Route("alice@example.com", "dev@example.org", []byte(post))
if err != nil {
t.Fatal(err)
}
if err := e.r.Send(e.ctx, e.out, res); err != nil {
t.Fatal(err)
}
}
func TestEachRecipientGetsItsOwnUnsubscribeLink(t *testing.T) {
e := newEnv(t)
e.r.BaseURL = "https://lists.example.org"
sendPost(t, e)
tokens := map[string]bool{}
for _, m := range e.out.Sent {
h := header(t, m.Data)
lu := h.Get("List-Unsubscribe")
sub := unsubURL.FindStringSubmatch(lu)
if sub == nil || !strings.Contains(lu, "<mailto:dev+leave@example.org>") {
t.Fatalf("List-Unsubscribe = %q", lu)
}
tokens[sub[1]] = true
if h.Get("List-Unsubscribe-Post") != "List-Unsubscribe=One-Click" {
t.Errorf("List-Unsubscribe-Post = %q", h.Get("List-Unsubscribe-Post"))
}
if n := len(h["List-Unsubscribe"]); n != 1 {
t.Errorf("want one List-Unsubscribe header, got %d", n)
}
if h.Get("List-Id") == "" || !strings.HasSuffix(string(m.Data), "\r\n\r\nthe body\r\n") {
t.Errorf("rest of the message was damaged: %q", m.Data)
}
}
if len(tokens) != 2 {
t.Fatalf("each recipient needs a distinct link, got %v", tokens)
}
}
func TestNoOneClickWithoutBaseURL(t *testing.T) {
e := newEnv(t)
sendPost(t, e)
h := header(t, e.out.Sent[0].Data)
if h.Get("List-Unsubscribe-Post") != "" {
t.Error("one-click needs a base URL")
}
if got := h.Get("List-Unsubscribe"); got != "<mailto:dev+leave@example.org>" {
t.Errorf("List-Unsubscribe = %q", got)
}
}
func TestSpoofedUnsubscribeHeadersNeverReachRecipients(t *testing.T) {
e := newEnv(t)
msg := "From: Alice <alice@example.com>\r\nList-Unsubscribe: <https://evil.example/u>\r\nList-Unsubscribe-Post: List-Unsubscribe=One-Click\r\n\r\nx\r\n"
res, _ := e.r.Route("alice@example.com", "dev@example.org", []byte(msg))
e.r.Send(e.ctx, e.out, res)
for _, m := range e.out.Sent {
h := header(t, m.Data)
if strings.Contains(h.Get("List-Unsubscribe"), "evil") || h.Get("List-Unsubscribe-Post") != "" {
t.Fatalf("spoofed header survived: %v", h)
}
}
}
func tokenFor(t *testing.T, e *env, memberID int64) string {
t.Helper()
e.r.BaseURL = "https://lists.example.org"
return e.r.UnsubscribeToken(memberID)
}
func TestUnsubscribeToken(t *testing.T) {
e := newEnv(t)
tok := tokenFor(t, e, e.alice)
l, err := e.r.CheckUnsubscribe(tok)
if err != nil || l.ID != e.list.ID {
t.Fatalf("check: %+v %v", l, err)
}
if ok, _ := e.s.IsMember(e.list.ID, "alice@example.com"); !ok {
t.Fatal("checking must not unsubscribe")
}
if err := e.r.Unsubscribe(tok); err != nil {
t.Fatal(err)
}
if ok, _ := e.s.IsMember(e.list.ID, "alice@example.com"); ok {
t.Fatal("alice must be gone")
}
if ok, _ := e.s.IsMember(e.list.ID, "bob@example.com"); !ok {
t.Fatal("bob must stay")
}
// Mail clients may repeat the request.
if err := e.r.Unsubscribe(tok); err != nil {
t.Fatalf("repeat must succeed: %v", err)
}
if _, err := e.r.CheckUnsubscribe(tok); !errors.Is(err, ErrGone) {
t.Fatalf("want ErrGone, got %v", err)
}
}
func TestUnsubscribeRejectsForgedTokens(t *testing.T) {
e := newEnv(t)
for _, tok := range []string{"", "x", "1", "1-", "-1", fmt.Sprintf("%d-000000000000", e.alice), "abc-123456789012",
fmt.Sprintf("%d-%s", e.alice+1, strings.TrimPrefix(tokenFor(t, e, e.alice), fmt.Sprintf("%d-", e.alice)))} {
if err := e.r.Unsubscribe(tok); !errors.Is(err, ErrBadToken) {
t.Errorf("token %q: want ErrBadToken, got %v", tok, err)
}
}
if ok, _ := e.s.IsMember(e.list.ID, "alice@example.com"); !ok {
t.Fatal("forged tokens must not unsubscribe anyone")
}
}
func TestBounceAndUnsubscribeTokensAreNotInterchangeable(t *testing.T) {
e := newEnv(t)
bounceMAC := e.r.mac("bounce", e.alice)
unsubMAC := e.r.mac("unsub", e.alice)
if bounceMAC == unsubMAC {
t.Fatal("MACs must be bound to their purpose")
}
if err := e.r.Unsubscribe(fmt.Sprintf("%d-%s", e.alice, bounceMAC)); !errors.Is(err, ErrBadToken) {
t.Fatalf("a bounce MAC must not unsubscribe: %v", err)
}
}

View file

@ -6,8 +6,11 @@ import (
"errors"
"fmt"
"log"
"strings"
"sync"
"time"
"codeberg.org/squidd/parsimony/internal/archive"
"codeberg.org/squidd/parsimony/internal/outbound"
"codeberg.org/squidd/parsimony/internal/store"
)
@ -21,6 +24,8 @@ var (
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")
// ErrGone means the member behind a valid token is already unsubscribed.
ErrGone = errors.New("already unsubscribed")
// ErrJoinClosed means the list does not accept self-service subscriptions.
ErrJoinClosed = errors.New("list is closed")
)
@ -88,7 +93,8 @@ func (r *Router) prepare(l store.List, data []byte) (Result, error) {
for i, m := range members {
rcpts[i] = Recipient{ID: m.ID, Address: m.Address}
}
out, err := rewrite(l, r.BaseURL, data)
r.archive(l, data)
out, err := rewrite(l, data)
if err != nil {
return Result{}, err
}
@ -105,7 +111,8 @@ func (r *Router) Send(ctx context.Context, out outbound.Sender, res Result) erro
if from == "" {
return errors.New("cannot create bounce address")
}
if err := out.Send(ctx, from, []string{rc.Address}, res.Data); err != nil {
data := append(r.unsubscribeHeaders(res.List, rc.ID), res.Data...)
if err := out.Send(ctx, from, []string{rc.Address}, data); err != nil {
failed++
log.Printf("deliver %s to %s: %v", res.List.Address(), rc.Address, err)
}
@ -116,6 +123,39 @@ func (r *Router) Send(ctx context.Context, out outbound.Sender, res Result) erro
return nil
}
// unsubscribeHeaders builds the per-recipient List-Unsubscribe headers: a signed
// one-click link (RFC 8058) when BaseURL is set, and the +leave address.
func (r *Router) unsubscribeHeaders(l store.List, memberID int64) []byte {
value := "<mailto:" + l.Name + "+leave@" + l.Domain + ">"
var b strings.Builder
if tok := r.UnsubscribeToken(memberID); r.BaseURL != "" && tok != "" {
value = "<" + strings.TrimRight(r.BaseURL, "/") + "/unsubscribe/" + tok + ">, " + value
b.WriteString("List-Unsubscribe-Post: List-Unsubscribe=One-Click\r\n")
}
b.WriteString("List-Unsubscribe: " + value + "\r\n")
return []byte(b.String())
}
// archive stores the original message. Failures are logged, never fatal: the
// post must be delivered even if the archive is unavailable.
func (r *Router) archive(l store.List, data []byte) {
if l.ArchivePolicy == store.ArchiveOff {
return
}
en, err := archive.Parse(data, time.Now())
if err != nil {
log.Printf("archive %s: %v", l.Address(), err)
return
}
_, _, err = r.store.ArchiveMessage(l.ID, store.Message{
MessageID: en.MessageID, InReplyTo: en.InReplyTo, Subject: en.Subject,
Sender: en.Sender, Date: en.Date, Body: en.Body,
})
if err != nil {
log.Printf("archive %s: %v", l.Address(), err)
}
}
// 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)

View file

@ -85,13 +85,6 @@ func TestRewriteHeaders(t *testing.T) {
if got := h.Get("List-Post"); got != "<mailto:dev@example.org>" {
t.Errorf("List-Post = %q", got)
}
if got := h.Get("List-Unsubscribe"); !strings.Contains(got, "<https://lists.example.org/unsubscribe/dev.example.org>") ||
!strings.Contains(got, "<mailto:dev+unsubscribe@example.org>") {
t.Errorf("List-Unsubscribe = %q", got)
}
if got := h.Get("List-Unsubscribe-Post"); got != "List-Unsubscribe=One-Click" {
t.Errorf("List-Unsubscribe-Post = %q", got)
}
if got := h.Get("From"); got != `"Alice via Dev" <dev@example.org>` {
t.Errorf("From = %q", got)
}
@ -114,15 +107,3 @@ func TestRewriteKeepsExistingReplyTo(t *testing.T) {
t.Errorf("Reply-To = %q", got)
}
}
func TestNoOneClickWithoutBaseURL(t *testing.T) {
r := setup(t)
res, _ := r.Route("alice@example.com", "dev@example.org", []byte(sample))
h := header(t, res.Data)
if h.Get("List-Unsubscribe-Post") != "" {
t.Error("one-click header needs a base URL")
}
if got := h.Get("List-Unsubscribe"); got != "<mailto:dev+unsubscribe@example.org>" {
t.Errorf("List-Unsubscribe = %q", got)
}
}

View file

@ -394,6 +394,11 @@ func (s *Store) RemoveMember(listID int64, addr string) error {
return affected(s.db.Exec(`DELETE FROM members WHERE list_id=? AND address=?`, listID, norm(addr)))
}
// DeleteMember unsubscribes a member by id.
func (s *Store) DeleteMember(id int64) error {
return affected(s.db.Exec(`DELETE FROM members WHERE id=?`, id))
}
// RecordHardBounce counts a hard bounce and disables the member once the count
// reaches threshold. It reports whether the member is now disabled.
func (s *Store) RecordHardBounce(memberID int64, threshold int) (bool, error) {