// Package api exposes the administration REST API. package api import ( "context" "crypto/subtle" "encoding/json" "errors" "fmt" "net/http" "net/mail" "strconv" "strings" "time" "unicode" "unicode/utf8" "codeberg.org/squidd/parsimony/internal/archive" "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 releaser Releaser lim *limiter } // New returns the API handler. Every route except /api/v1/health needs // "Authorization: Bearer ". An empty token rejects all requests. // rel may be nil: approving held messages then answers 501. func New(s *store.Store, token string, rel Releaser) http.Handler { return newHandler(s, token, rel, time.Now) } // newHandler is New with an injectable clock for the tests. func newHandler(s *store.Store, token string, rel Releaser, now func() time.Time) http.Handler { srv := &server{store: s, token: token, releaser: rel, lim: newLimiter(now)} mux := http.NewServeMux() for _, rt := range srv.routes() { mux.Handle(rt.pattern, rt.handler) } return mux } type route struct { pattern string handler http.Handler } // routes is the only place routes are declared. Everything but the health check goes through auth. func (s *server) routes() []route { public := func(h http.HandlerFunc) http.Handler { return h } return []route{ {"GET /api/v1/health", public(func(w http.ResponseWriter, _ *http.Request) { writeJSON(w, http.StatusOK, map[string]string{"status": "ok"}) })}, {"GET /api/v1/lists", s.auth(s.listLists)}, {"POST /api/v1/lists", s.auth(s.createList)}, {"GET /api/v1/lists/{id}", s.auth(s.getList)}, {"PATCH /api/v1/lists/{id}", s.auth(s.updateList)}, {"DELETE /api/v1/lists/{id}", s.auth(s.deleteList)}, {"GET /api/v1/lists/{id}/members", s.auth(s.listMembers)}, {"POST /api/v1/lists/{id}/members", s.auth(s.addMember)}, {"DELETE /api/v1/lists/{id}/members/{address}", s.auth(s.removeMember)}, {"GET /api/v1/lists/{id}/archive", s.auth(s.listArchive)}, {"POST /api/v1/lists/{id}/archive/import", s.auth(s.importArchive)}, {"GET /api/v1/archive/{id}", s.auth(s.getArchived)}, {"DELETE /api/v1/archive/{id}", s.auth(s.deleteArchived)}, {"GET /api/v1/queue", s.auth(s.getQueue)}, {"DELETE /api/v1/queue/{id}", s.auth(s.discardQueued)}, {"GET /api/v1/lists/{id}/held", s.auth(s.listHeld)}, {"POST /api/v1/held/{id}/approve", s.auth(s.approveHeld)}, {"DELETE /api/v1/held/{id}", s.auth(s.discardHeld)}, } } func (s *server) auth(next http.HandlerFunc) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { ip := clientIP(r) if wait, locked := s.lim.blocked(ip); locked { w.Header().Set("Retry-After", strconv.Itoa(int((wait+time.Second-1)/time.Second))) writeError(w, http.StatusTooManyRequests, "too many failed attempts, try again later") return } got, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ") if !ok || s.token == "" || subtle.ConstantTimeCompare([]byte(got), []byte(s.token)) != 1 { s.lim.fail(ip) w.Header().Set("WWW-Authenticate", `Bearer realm="parsimony"`) writeError(w, http.StatusUnauthorized, "invalid or missing token") return } s.lim.succeed(ip) next(w, r) }) } // JSON shapes. type listDTO struct { 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"` ArchivePolicy string `json:"archive_policy"` } func toListDTO(l store.List) listDTO { return listDTO{ID: l.ID, Name: l.Name, Domain: l.Domain, Title: l.Title, Address: l.Address(), PostPolicy: l.PostPolicy, JoinPolicy: l.JoinPolicy, ArchivePolicy: l.ArchivePolicy} } type memberDTO struct { Address string `json:"address"` DisplayName string `json:"display_name"` Disabled bool `json:"disabled"` BounceCount int `json:"bounce_count"` } // Helpers. func writeJSON(w http.ResponseWriter, code int, v any) { w.Header().Set("Content-Type", "application/json") w.WriteHeader(code) json.NewEncoder(w).Encode(v) } func writeError(w http.ResponseWriter, code int, msg string) { writeJSON(w, code, map[string]string{"error": msg}) } // storeError maps store errors to HTTP responses. func storeError(w http.ResponseWriter, err error) { switch { case errors.Is(err, store.ErrNotFound): writeError(w, http.StatusNotFound, "not found") case errors.Is(err, store.ErrExists): writeError(w, http.StatusConflict, "already exists") default: writeError(w, http.StatusInternalServerError, "internal error") } } func decodeBody(w http.ResponseWriter, r *http.Request, v any) bool { r.Body = http.MaxBytesReader(w, r.Body, 1<<20) dec := json.NewDecoder(r.Body) dec.DisallowUnknownFields() if err := dec.Decode(v); err != nil { writeError(w, http.StatusBadRequest, "invalid JSON body") return false } return true } // listID parses the {id} path value. Anything unusable is a 404. func listID(w http.ResponseWriter, r *http.Request) (int64, bool) { id, err := strconv.ParseInt(r.PathValue("id"), 10, 64) if err != nil { writeError(w, http.StatusNotFound, "not found") return 0, false } return id, true } // Handlers: lists. func (s *server) listLists(w http.ResponseWriter, _ *http.Request) { ls, err := s.store.ListLists() if err != nil { storeError(w, err) return } out := make([]listDTO, 0, len(ls)) for _, l := range ls { out = append(out, toListDTO(l)) } writeJSON(w, http.StatusOK, out) } const ( maxNameLen = 30 // keeps list+confirm- and list+bounce-- within 64 characters maxTitleLen = 200 titleHint = "title must be a non-empty single line of at most 200 characters, without control characters" ) // validName reports whether name (already lowercased) works as the local part of a list address. func validName(name string) bool { if name == "" || len(name) > maxNameLen || strings.HasPrefix(name, ".") || strings.HasSuffix(name, ".") || strings.Contains(name, "..") { return false } for _, c := range name { if (c < 'a' || c > 'z') && (c < '0' || c > '9') && c != '.' && c != '_' && c != '-' { return false } } return true } // validDomain reports whether d (already lowercased) is an ASCII host name: dot-separated labels of // 1 to 63 letters, digits and hyphens, none starting or ending with a hyphen. func validDomain(d string) bool { if d == "" || len(d) > 253 { return false } for _, label := range strings.Split(d, ".") { if label == "" || len(label) > 63 || label[0] == '-' || label[len(label)-1] == '-' { return false } for _, c := range label { if (c < 'a' || c > 'z') && (c < '0' || c > '9') && c != '-' { return false } } } return true } // validTitle reports whether t is a usable list title: not empty, at most maxTitleLen characters, // no line breaks or other control characters (it goes into mail headers). func validTitle(t string) bool { if t == "" || utf8.RuneCountInString(t) > maxTitleLen { return false } return !strings.ContainsFunc(t, unicode.IsControl) } func (s *server) createList(w http.ResponseWriter, r *http.Request) { var in struct { Name string `json:"name"` Domain string `json:"domain"` Title string `json:"title"` } if !decodeBody(w, r, &in) { return } typedName := strings.TrimSpace(in.Name) in.Name, in.Domain = strings.ToLower(typedName), strings.ToLower(strings.TrimSpace(in.Domain)) if !validName(in.Name) { writeError(w, http.StatusBadRequest, "name must be 1 to 30 characters of a-z, 0-9, '.', '_' or '-', without a dot at either end or two dots in a row") return } if !validDomain(in.Domain) { writeError(w, http.StatusBadRequest, "domain must be a host name such as lists.example.org") return } if in.Title = strings.TrimSpace(in.Title); in.Title == "" { in.Title = typedName } if !validTitle(in.Title) { writeError(w, http.StatusBadRequest, titleHint) return } l, err := s.store.CreateList(in.Name, in.Domain, in.Title) if err != nil { storeError(w, err) return } writeJSON(w, http.StatusCreated, toListDTO(l)) } func (s *server) getList(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } l, err := s.store.GetList(id) if err != nil { storeError(w, err) return } writeJSON(w, http.StatusOK, toListDTO(l)) } func (s *server) updateList(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } var in struct { Title *string `json:"title"` PostPolicy *string `json:"post_policy"` JoinPolicy *string `json:"join_policy"` ArchivePolicy *string `json:"archive_policy"` } if !decodeBody(w, r, &in) { return } if in.Title == nil && in.PostPolicy == nil && in.JoinPolicy == nil && in.ArchivePolicy == nil { writeError(w, http.StatusBadRequest, "nothing to update") return } l, err := s.store.GetList(id) if err != nil { storeError(w, err) return } if in.Title != nil { title := strings.TrimSpace(*in.Title) if !validTitle(title) { writeError(w, http.StatusBadRequest, titleHint) return } l.Title = title } if in.PostPolicy != nil { l.PostPolicy = *in.PostPolicy } if in.JoinPolicy != nil { l.JoinPolicy = *in.JoinPolicy } if in.ArchivePolicy != nil { l.ArchivePolicy = *in.ArchivePolicy } // Validate before writing anything. if (l.PostPolicy != store.PostMembers && l.PostPolicy != store.PostModerated) || (l.JoinPolicy != store.JoinOpen && l.JoinPolicy != store.JoinClosed) || (l.ArchivePolicy != store.ArchivePublic && l.ArchivePolicy != store.ArchivePrivate && l.ArchivePolicy != store.ArchiveOff) { writeError(w, http.StatusBadRequest, "post_policy must be members or moderated; join_policy open or closed; archive_policy public, private or off") 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, l.ArchivePolicy); err != nil { storeError(w, err) return } writeJSON(w, http.StatusOK, toListDTO(l)) } func (s *server) deleteList(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } if err := s.store.DeleteList(id); err != nil { storeError(w, err) return } w.WriteHeader(http.StatusNoContent) } // Handlers: members. func (s *server) listMembers(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 } ms, err := s.store.Members(id) if err != nil { storeError(w, err) return } out := make([]memberDTO, 0, len(ms)) for _, m := range ms { out = append(out, memberDTO{Address: m.Address, DisplayName: m.DisplayName, Disabled: m.Disabled, BounceCount: m.BounceCount}) } writeJSON(w, http.StatusOK, out) } func (s *server) addMember(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } var in memberDTO if !decodeBody(w, r, &in) { return } a, err := mail.ParseAddress(strings.TrimSpace(in.Address)) if err != nil || a.Name != "" { writeError(w, http.StatusBadRequest, "a valid email address is required") return } if strings.ContainsAny(in.DisplayName, "\r\n") { writeError(w, http.StatusBadRequest, "display_name must be a single line") return } if _, err := s.store.GetList(id); err != nil { storeError(w, err) return } if err := s.store.AddMember(id, a.Address, in.DisplayName); err != nil { storeError(w, err) return } writeJSON(w, http.StatusCreated, memberDTO{Address: strings.ToLower(a.Address), DisplayName: in.DisplayName}) } func (s *server) removeMember(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } if err := s.store.RemoveMember(id, r.PathValue("address")); err != nil { storeError(w, err) return } 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"` Reason string `json:"reason"` // why the message was held // The From header as received, and whether it names someone other than the envelope sender: // what recipients will see as the author, against who really sent it. From string `json:"from"` Mismatch bool `json:"mismatch"` } // fromMismatch reports whether the From header names an address other than the envelope sender, or // no usable address at all. func fromMismatch(fromHeader, sender string) bool { a, err := mail.ParseAddress(fromHeader) return err != nil || !strings.EqualFold(a.Address, sender) } 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: h.Subject, Size: h.Size, CreatedAt: h.CreatedAt, Reason: h.Reason, From: h.FromHeader, Mismatch: fromMismatch(h.FromHeader, h.Sender)}) } 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) } // Handlers: archive. const ( defaultPageSize = 50 maxPageSize = 200 ) type messageDTO struct { ID int64 `json:"id"` ThreadID int64 `json:"thread_id"` MessageID string `json:"message_id"` InReplyTo string `json:"in_reply_to,omitempty"` Subject string `json:"subject"` Sender string `json:"sender"` Date time.Time `json:"date"` Size int `json:"size"` Body string `json:"body,omitempty"` } func toMessageDTO(m store.Message) messageDTO { return messageDTO{ID: m.ID, ThreadID: m.ThreadID, MessageID: m.MessageID, InReplyTo: m.InReplyTo, Subject: m.Subject, Sender: m.Sender, Date: m.Date, Size: m.Size, Body: m.Body} } // intParam reads a non-negative integer query parameter. func intParam(r *http.Request, name string, def int) (int, bool) { v := r.URL.Query().Get(name) if v == "" { return def, true } n, err := strconv.Atoi(v) return n, err == nil && n >= 0 } func (s *server) listArchive(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } limit, ok1 := intParam(r, "limit", defaultPageSize) offset, ok2 := intParam(r, "offset", 0) if !ok1 || !ok2 { writeError(w, http.StatusBadRequest, "limit and offset must be non-negative integers") return } limit = min(max(limit, 1), maxPageSize) if _, err := s.store.GetList(id); err != nil { storeError(w, err) return } var ( ms []store.Message total int err error ) if q := strings.TrimSpace(r.URL.Query().Get("q")); q != "" { ms, total, err = s.store.SearchMessages(id, q, limit, offset) } else { ms, total, err = s.store.ListMessages(id, limit, offset) } if err != nil { storeError(w, err) return } out := make([]messageDTO, 0, len(ms)) for _, m := range ms { out = append(out, toMessageDTO(m)) } writeJSON(w, http.StatusOK, map[string]any{"total": total, "messages": out}) } func (s *server) getArchived(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } m, err := s.store.GetMessage(id) if err != nil { storeError(w, err) return } writeJSON(w, http.StatusOK, toMessageDTO(m)) } func (s *server) deleteArchived(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } if err := s.store.DeleteMessage(id); err != nil { storeError(w, err) return } w.WriteHeader(http.StatusNoContent) } // Handlers: outbound queue. const queueListLimit = 100 type queuedDTO struct { ID int64 `json:"id"` Recipient string `json:"recipient"` Attempts int `json:"attempts"` LastError string `json:"last_error"` NextAttempt time.Time `json:"next_attempt"` CreatedAt time.Time `json:"created_at"` Failed bool `json:"failed"` // given up for good: never retried } func (s *server) getQueue(w http.ResponseWriter, _ *http.Request) { st, err := s.store.OutboxStats() if err != nil { storeError(w, err) return } items, err := s.store.ListOutbox(queueListLimit) if err != nil { storeError(w, err) return } out := make([]queuedDTO, 0, len(items)) for _, it := range items { out = append(out, queuedDTO{ID: it.ID, Recipient: it.Rcpt, Attempts: it.Attempts, LastError: it.LastError, NextAttempt: it.NextAt, CreatedAt: it.CreatedAt, Failed: it.Failed}) } var oldest *time.Time if !st.Oldest.IsZero() { oldest = &st.Oldest } writeJSON(w, http.StatusOK, map[string]any{ "pending": st.Pending, "retrying": st.Retrying, "failed": st.Failed, "oldest": oldest, "items": out, }) } func (s *server) discardQueued(w http.ResponseWriter, r *http.Request) { id, ok := listID(w, r) if !ok { return } if err := s.store.CompleteOutbox(id); err != nil { storeError(w, err) return } w.WriteHeader(http.StatusNoContent) } // importTimeout is how long one archive import may read its body and write its // summary, in place of the server's default read and write timeouts. const importTimeout = 30 * time.Minute // importArchive reads an mbox from the request body, streaming, and archives it. // Failed messages are reported in the summary; the request itself succeeds. func (s *server) importArchive(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 } // A big mbox streams for longer than the server's default timeouts. Errors // are ignored: a ResponseWriter that cannot extend deadlines has none. rc := http.NewResponseController(w) _ = rc.SetReadDeadline(time.Now().Add(importTimeout)) _ = rc.SetWriteDeadline(time.Now().Add(importTimeout)) sum, err := archive.ImportMbox(s.store, id, r.Body, time.Now()) if err != nil { writeError(w, http.StatusBadRequest, fmt.Sprintf("import stopped after %d message(s): %v", sum.Imported, err)) return } writeJSON(w, http.StatusOK, sum) }