diff --git a/README.md b/README.md index 042171c..f3ab39e 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,10 @@ A modern, single-binary mailing list manager: an evolution of Mailman. - Postfix delivers to parsimony over LMTP; parsimony relays through SMTP. - Discussion lists with member-only posting, `List-*` headers, one-click unsubscribe and DMARC-safe `From` rewriting. +- Self-service subscribe and unsubscribe by email with double opt-in: + send to `list+join@domain` or `list+leave@domain`, then reply to the confirmation. +- Moderated lists: posts wait in a queue that the API can approve or discard. +- VERP bounces: every recipient gets a signed return address; 3 hard bounces disable a member. - SQLite storage, one YAML config file. - Admin REST API under `/api/v1` (see `docs/openapi.yaml`). @@ -20,3 +24,13 @@ The API is disabled when `PARSIMONY_API_TOKEN` is not set. ``` curl -H "Authorization: Bearer $PARSIMONY_API_TOKEN" -d '{"name":"dev","domain":"example.org","title":"Dev"}' localhost:8080/api/v1/lists ``` + +## Postfix + +Deliver the list domains to parsimony over LMTP and keep the `+` extensions intact, for example: + +``` +transport_maps = hash:/etc/postfix/transport +# /etc/postfix/transport +lists.example.org lmtp:inet:127.0.0.1:2424 +``` diff --git a/docs/openapi.yaml b/docs/openapi.yaml index ad0a4db..16c2b82 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -20,11 +20,23 @@ components: domain: {type: string} title: {type: string} address: {type: string} + post_policy: {type: string, enum: [members, moderated]} + join_policy: {type: string, enum: [open, closed]} Member: type: object properties: address: {type: string} display_name: {type: string} + disabled: {type: boolean, description: Disabled after 3 hard bounces; re-adding the member re-enables it} + bounce_count: {type: integer} + Held: + type: object + properties: + id: {type: integer} + sender: {type: string} + subject: {type: string} + size: {type: integer} + created_at: {type: string, format: date-time} Error: type: object properties: @@ -85,16 +97,17 @@ paths: schema: {$ref: '#/components/schemas/List'} '404': {$ref: '#/components/responses/Error'} patch: - summary: Update the list title + summary: Update title and policies (send only the fields to change) requestBody: required: true content: application/json: schema: type: object - required: [title] properties: title: {type: string} + post_policy: {type: string, enum: [members, moderated]} + join_policy: {type: string, enum: [open, closed]} responses: '200': description: OK @@ -149,3 +162,32 @@ paths: responses: '204': {description: Removed} '404': {$ref: '#/components/responses/Error'} + /lists/{id}/held: + parameters: + - {name: id, in: path, required: true, schema: {type: integer}} + get: + summary: Messages waiting for moderation + responses: + '200': + description: OK + content: + application/json: + schema: {type: array, items: {$ref: '#/components/schemas/Held'}} + '404': {$ref: '#/components/responses/Error'} + /held/{id}/approve: + parameters: + - {name: id, in: path, required: true, schema: {type: integer}} + post: + summary: Approve and deliver a held message + responses: + '204': {description: Delivered} + '404': {$ref: '#/components/responses/Error'} + '501': {$ref: '#/components/responses/Error'} + /held/{id}: + parameters: + - {name: id, in: path, required: true, schema: {type: integer}} + delete: + summary: Discard a held message + responses: + '204': {description: Discarded} + '404': {$ref: '#/components/responses/Error'} diff --git a/internal/api/api.go b/internal/api/api.go index 9dbb9d8..1d027bf 100644 --- a/internal/api/api.go +++ b/internal/api/api.go @@ -2,26 +2,37 @@ package api import ( + "bytes" + "context" "crypto/subtle" "encoding/json" "errors" + "mime" "net/http" "net/mail" "strconv" "strings" + "time" "codeberg.org/squidd/parsimony/internal/store" ) +// Releaser approves a held message: it delivers it to the list. +type Releaser interface { + Release(ctx context.Context, heldID int64) error +} + type server struct { - store *store.Store - token string + store *store.Store + token string + releaser Releaser } // New returns the API handler. Every route except /api/v1/health needs // "Authorization: Bearer ". An empty token rejects all requests. -func New(s *store.Store, token string) http.Handler { - srv := &server{store: s, token: token} +// rel may be nil: approving held messages then answers 501. +func New(s *store.Store, token string, rel Releaser) http.Handler { + srv := &server{store: s, token: token, releaser: rel} mux := http.NewServeMux() mux.HandleFunc("GET /api/v1/health", func(w http.ResponseWriter, _ *http.Request) { writeJSON(w, http.StatusOK, map[string]string{"status": "ok"}) @@ -34,6 +45,9 @@ func New(s *store.Store, token string) http.Handler { mux.Handle("GET /api/v1/lists/{id}/members", srv.auth(srv.listMembers)) mux.Handle("POST /api/v1/lists/{id}/members", srv.auth(srv.addMember)) mux.Handle("DELETE /api/v1/lists/{id}/members/{address}", srv.auth(srv.removeMember)) + mux.Handle("GET /api/v1/lists/{id}/held", srv.auth(srv.listHeld)) + mux.Handle("POST /api/v1/held/{id}/approve", srv.auth(srv.approveHeld)) + mux.Handle("DELETE /api/v1/held/{id}", srv.auth(srv.discardHeld)) return mux } @@ -57,15 +71,21 @@ type listDTO struct { Domain string `json:"domain"` Title string `json:"title"` Address string `json:"address"` + + PostPolicy string `json:"post_policy"` + JoinPolicy string `json:"join_policy"` } func toListDTO(l store.List) listDTO { - return listDTO{ID: l.ID, Name: l.Name, Domain: l.Domain, Title: l.Title, Address: l.Address()} + return listDTO{ID: l.ID, Name: l.Name, Domain: l.Domain, Title: l.Title, Address: l.Address(), + PostPolicy: l.PostPolicy, JoinPolicy: l.JoinPolicy} } type memberDTO struct { Address string `json:"address"` DisplayName string `json:"display_name"` + Disabled bool `json:"disabled"` + BounceCount int `json:"bounce_count"` } // Helpers. @@ -138,8 +158,8 @@ func (s *server) createList(w http.ResponseWriter, r *http.Request) { return } in.Name, in.Domain = strings.TrimSpace(in.Name), strings.TrimSpace(in.Domain) - if in.Name == "" || in.Domain == "" || strings.ContainsAny(in.Name+in.Domain, "@ \r\n") { - writeError(w, http.StatusBadRequest, "name and domain are required and must not contain '@' or spaces") + if in.Name == "" || in.Domain == "" || strings.ContainsAny(in.Name+in.Domain, "@+ \r\n") { + writeError(w, http.StatusBadRequest, "name and domain are required and must not contain '@', '+' or spaces") return } if in.Title == "" { @@ -172,18 +192,15 @@ func (s *server) updateList(w http.ResponseWriter, r *http.Request) { return } var in struct { - Title string `json:"title"` + Title *string `json:"title"` + PostPolicy *string `json:"post_policy"` + JoinPolicy *string `json:"join_policy"` } if !decodeBody(w, r, &in) { return } - title := strings.TrimSpace(in.Title) - if title == "" || strings.ContainsAny(title, "\r\n") { - writeError(w, http.StatusBadRequest, "title is required and must be a single line") - return - } - if err := s.store.UpdateList(id, title); err != nil { - storeError(w, err) + if in.Title == nil && in.PostPolicy == nil && in.JoinPolicy == nil { + writeError(w, http.StatusBadRequest, "nothing to update") return } l, err := s.store.GetList(id) @@ -191,6 +208,34 @@ func (s *server) updateList(w http.ResponseWriter, r *http.Request) { storeError(w, err) return } + if in.Title != nil { + title := strings.TrimSpace(*in.Title) + if title == "" || strings.ContainsAny(title, "\r\n") { + writeError(w, http.StatusBadRequest, "title must be a non-empty single line") + return + } + l.Title = title + } + if in.PostPolicy != nil { + l.PostPolicy = *in.PostPolicy + } + if in.JoinPolicy != nil { + l.JoinPolicy = *in.JoinPolicy + } + // Validate before writing anything. + if (l.PostPolicy != store.PostMembers && l.PostPolicy != store.PostModerated) || + (l.JoinPolicy != store.JoinOpen && l.JoinPolicy != store.JoinClosed) { + writeError(w, http.StatusBadRequest, "post_policy must be members or moderated; join_policy must be open or closed") + return + } + if err := s.store.UpdateList(id, l.Title); err != nil { + storeError(w, err) + return + } + if err := s.store.SetPolicies(id, l.PostPolicy, l.JoinPolicy); err != nil { + storeError(w, err) + return + } writeJSON(w, http.StatusOK, toListDTO(l)) } @@ -224,7 +269,7 @@ func (s *server) listMembers(w http.ResponseWriter, r *http.Request) { } out := make([]memberDTO, 0, len(ms)) for _, m := range ms { - out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName}) + out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName, Disabled: m.Disabled, BounceCount: m.BounceCount}) } writeJSON(w, http.StatusOK, out) } @@ -269,3 +314,74 @@ func (s *server) removeMember(w http.ResponseWriter, r *http.Request) { } w.WriteHeader(http.StatusNoContent) } + +// Handlers: held messages. + +type heldDTO struct { + ID int64 `json:"id"` + Sender string `json:"sender"` + Subject string `json:"subject"` + Size int `json:"size"` + CreatedAt time.Time `json:"created_at"` +} + +func subjectOf(data []byte) string { + m, err := mail.ReadMessage(bytes.NewReader(data)) + if err != nil { + return "" + } + subj := m.Header.Get("Subject") + if dec, err := new(mime.WordDecoder).DecodeHeader(subj); err == nil { + return dec + } + return subj +} + +func (s *server) listHeld(w http.ResponseWriter, r *http.Request) { + id, ok := listID(w, r) + if !ok { + return + } + if _, err := s.store.GetList(id); err != nil { + storeError(w, err) + return + } + hs, err := s.store.ListHeld(id) + if err != nil { + storeError(w, err) + return + } + out := make([]heldDTO, 0, len(hs)) + for _, h := range hs { + out = append(out, heldDTO{ID: h.ID, Sender: h.Sender, Subject: subjectOf(h.Data), Size: len(h.Data), CreatedAt: h.CreatedAt}) + } + writeJSON(w, http.StatusOK, out) +} + +func (s *server) approveHeld(w http.ResponseWriter, r *http.Request) { + id, ok := listID(w, r) + if !ok { + return + } + if s.releaser == nil { + writeError(w, http.StatusNotImplemented, "delivery is not configured") + return + } + if err := s.releaser.Release(r.Context(), id); err != nil { + storeError(w, err) + return + } + w.WriteHeader(http.StatusNoContent) +} + +func (s *server) discardHeld(w http.ResponseWriter, r *http.Request) { + id, ok := listID(w, r) + if !ok { + return + } + if err := s.store.DeleteHeld(id); err != nil { + storeError(w, err) + return + } + w.WriteHeader(http.StatusNoContent) +} diff --git a/internal/api/api_test.go b/internal/api/api_test.go index 5d583e4..92382a7 100644 --- a/internal/api/api_test.go +++ b/internal/api/api_test.go @@ -1,6 +1,7 @@ package api import ( + "context" "encoding/json" "net/http" "net/http/httptest" @@ -19,7 +20,7 @@ func newServer(t *testing.T) http.Handler { t.Fatal(err) } t.Cleanup(func() { s.Close() }) - return New(s, token) + return New(s, token, nil) } func do(t *testing.T, h http.Handler, method, path, body string, auth bool) *httptest.ResponseRecorder { @@ -68,7 +69,7 @@ func TestAuthRequired(t *testing.T) { func TestEmptyTokenRejectsEverything(t *testing.T) { s, _ := store.Open(":memory:") defer s.Close() - h := New(s, "") + h := New(s, "", nil) req := httptest.NewRequest("GET", "/api/v1/lists", nil) req.Header.Set("Authorization", "Bearer ") rec := httptest.NewRecorder() @@ -77,11 +78,13 @@ func TestEmptyTokenRejectsEverything(t *testing.T) { } type listJSON struct { - ID int64 `json:"id"` - Name string `json:"name"` - Domain string `json:"domain"` - Title string `json:"title"` - Address string `json:"address"` + ID int64 `json:"id"` + Name string `json:"name"` + Domain string `json:"domain"` + Title string `json:"title"` + Address string `json:"address"` + PostPolicy string `json:"post_policy"` + JoinPolicy string `json:"join_policy"` } func createList(t *testing.T, h http.Handler) listJSON { @@ -141,6 +144,7 @@ func TestCreateListValidation(t *testing.T) { `{}`, `{"name":"","domain":"example.org"}`, `{"name":"a@b","domain":"example.org"}`, + `{"name":"a+b","domain":"example.org"}`, `{"name":"dev","domain":""}`, `{"name":"dev","domain":"example.org","bogus":1}`, } { @@ -159,6 +163,8 @@ func TestCreateListValidation(t *testing.T) { type memberJSON struct { Address string `json:"address"` DisplayName string `json:"display_name"` + Disabled bool `json:"disabled"` + BounceCount int `json:"bounce_count"` } func TestMembers(t *testing.T) { @@ -194,3 +200,118 @@ func TestMembers(t *testing.T) { expect(t, do(t, h, "DELETE", "/api/v1/lists/1/members/alice%40example.com", "", true), 204) expect(t, do(t, h, "DELETE", "/api/v1/lists/1/members/alice%40example.com", "", true), 404) } + +func TestListPoliciesViaAPI(t *testing.T) { + h := newServer(t) + l := createList(t, h) + if l.PostPolicy != "members" || l.JoinPolicy != "open" { + t.Fatalf("defaults: %+v", l) + } + rec := do(t, h, "PATCH", "/api/v1/lists/1", `{"post_policy":"moderated"}`, true) + expect(t, rec, 200) + var u listJSON + decode(t, rec, &u) + if u.PostPolicy != "moderated" || u.JoinPolicy != "open" || u.Title != "Dev" { + t.Fatalf("patched: %+v", u) + } + expect(t, do(t, h, "PATCH", "/api/v1/lists/1", `{"join_policy":"closed","title":"New"}`, true), 200) + rec = do(t, h, "GET", "/api/v1/lists/1", "", true) + decode(t, rec, &u) + if u.JoinPolicy != "closed" || u.Title != "New" || u.PostPolicy != "moderated" { + t.Fatalf("after: %+v", u) + } + expect(t, do(t, h, "PATCH", "/api/v1/lists/1", `{"post_policy":"bogus"}`, true), 400) +} + +func TestMemberBounceState(t *testing.T) { + s, _ := store.Open(":memory:") + defer s.Close() + h := New(s, token, nil) + l, _ := s.CreateList("dev", "example.org", "Dev") + s.AddMember(l.ID, "a@x.com", "A") + ms, _ := s.Members(l.ID) + for i := 0; i < 3; i++ { + s.RecordHardBounce(ms[0].ID, 3) + } + rec := do(t, h, "GET", "/api/v1/lists/1/members", "", true) + var out []memberJSON + decode(t, rec, &out) + if len(out) != 1 || !out[0].Disabled || out[0].BounceCount != 3 { + t.Fatalf("members: %+v", out) + } + // Re-adding re-enables. + expect(t, do(t, h, "POST", "/api/v1/lists/1/members", `{"address":"a@x.com"}`, true), 201) + rec = do(t, h, "GET", "/api/v1/lists/1/members", "", true) + decode(t, rec, &out) + if out[0].Disabled || out[0].BounceCount != 0 { + t.Fatalf("after re-add: %+v", out) + } +} + +type fakeReleaser struct{ released []int64 } + +func (f *fakeReleaser) Release(_ context.Context, id int64) error { + f.released = append(f.released, id) + return nil +} + +func heldServer(t *testing.T) (http.Handler, *store.Store, *fakeReleaser) { + t.Helper() + s, _ := store.Open(":memory:") + t.Cleanup(func() { s.Close() }) + l, _ := s.CreateList("dev", "example.org", "Dev") + s.HoldMessage(l.ID, "Bob@x.com", []byte("From: Bob \r\nSubject: Hello there\r\n\r\nbody")) + rel := &fakeReleaser{} + return New(s, token, rel), s, rel +} + +type heldJSON struct { + ID int64 `json:"id"` + Sender string `json:"sender"` + Subject string `json:"subject"` + Size int `json:"size"` +} + +func TestHeldQueueAPI(t *testing.T) { + h, _, rel := heldServer(t) + rec := do(t, h, "GET", "/api/v1/lists/1/held", "", true) + expect(t, rec, 200) + var hs []heldJSON + decode(t, rec, &hs) + if len(hs) != 1 || hs[0].Sender != "bob@x.com" || hs[0].Subject != "Hello there" || hs[0].Size == 0 { + t.Fatalf("held: %+v", hs) + } + expect(t, do(t, h, "GET", "/api/v1/lists/99/held", "", true), 404) + + expect(t, do(t, h, "POST", "/api/v1/held/1/approve", "", true), 204) + if len(rel.released) != 1 || rel.released[0] != 1 { + t.Fatalf("released: %v", rel.released) + } + expect(t, do(t, h, "DELETE", "/api/v1/held/1", "", true), 204) + expect(t, do(t, h, "DELETE", "/api/v1/held/1", "", true), 404) + expect(t, do(t, h, "DELETE", "/api/v1/held/abc", "", true), 404) +} + +func TestHeldRequiresAuth(t *testing.T) { + h, _, _ := heldServer(t) + expect(t, do(t, h, "POST", "/api/v1/held/1/approve", "", false), 401) + expect(t, do(t, h, "GET", "/api/v1/lists/1/held", "", false), 401) +} + +func TestApproveWithoutReleaser(t *testing.T) { + s, _ := store.Open(":memory:") + defer s.Close() + h := New(s, token, nil) + expect(t, do(t, h, "POST", "/api/v1/held/1/approve", "", true), 501) +} + +func TestApproveUnknownHeld(t *testing.T) { + s, _ := store.Open(":memory:") + defer s.Close() + h := New(s, token, errReleaser{store.ErrNotFound}) + expect(t, do(t, h, "POST", "/api/v1/held/5/approve", "", true), 404) +} + +type errReleaser struct{ err error } + +func (e errReleaser) Release(context.Context, int64) error { return e.err }