// Package api exposes the administration REST API. 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 releaser Releaser } // 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 { 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"}) }) mux.Handle("GET /api/v1/lists", srv.auth(srv.listLists)) mux.Handle("POST /api/v1/lists", srv.auth(srv.createList)) mux.Handle("GET /api/v1/lists/{id}", srv.auth(srv.getList)) mux.Handle("PATCH /api/v1/lists/{id}", srv.auth(srv.updateList)) mux.Handle("DELETE /api/v1/lists/{id}", srv.auth(srv.deleteList)) 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 } func (s *server) auth(next http.HandlerFunc) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { got, ok := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer ") if !ok || s.token == "" || subtle.ConstantTimeCompare([]byte(got), []byte(s.token)) != 1 { w.Header().Set("WWW-Authenticate", `Bearer realm="parsimony"`) writeError(w, http.StatusUnauthorized, "invalid or missing token") return } 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"` } 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} } 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) } 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 } 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") return } if in.Title == "" { in.Title = in.Name } 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"` } if !decodeBody(w, r, &in) { return } if in.Title == nil && in.PostPolicy == nil && in.JoinPolicy == 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 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)) } 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"` } 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) }