// Package api exposes Levee over HTTP: ad-hoc determinations (public), and // portfolio, monitoring and event endpoints (bearer-token protected). package api import ( "context" "crypto/subtle" "embed" "encoding/json" "errors" "fmt" "io" "log/slog" "net/http" "strconv" "strings" "sync" "time" "github.com/go-chi/chi/v5" "github.com/go-chi/chi/v5/middleware" "levee/internal/determine" "levee/internal/disclaimer" "levee/internal/monitor" "levee/internal/sfhdf" "levee/internal/store" "levee/internal/version" ) //go:embed ui/index.html var uiFS embed.FS // Server is the HTTP API. type Server struct { Store *store.Store Engine *determine.Engine Monitor *monitor.Monitor Batch monitor.BatchGeocoder Token string Preparer sfhdf.Info Log *slog.Logger mu sync.Mutex running bool lastReport *monitor.Report lastImport *monitor.ImportReport } // Handler returns the router. func (s *Server) Handler() http.Handler { r := chi.NewRouter() r.Use(middleware.RealIP, middleware.Recoverer, middleware.Timeout(5*time.Minute)) r.Use(func(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { w.Header().Set("X-Content-Type-Options", "nosniff") w.Header().Set("Referrer-Policy", "no-referrer") next.ServeHTTP(w, req) }) }) r.Get("/", s.ui) r.Get("/healthz", func(w http.ResponseWriter, _ *http.Request) { writeJSON(w, 200, map[string]string{"status": "ok", "version": version.Version}) }) r.Route("/v1", func(r chi.Router) { r.Group(func(r chi.Router) { r.Use(middleware.Throttle(8)) r.Get("/determine", s.determine) r.Get("/determine.pdf", s.determinePDF) }) r.Group(func(r chi.Router) { r.Use(s.auth) r.Get("/summary", s.summary) r.Get("/loans", s.listLoans) r.Post("/loans", s.createLoans) r.Post("/loans/import", s.importCSV) r.Get("/loans/{id}", s.getLoan) r.Delete("/loans/{id}", s.deleteLoan) r.Post("/loans/{id}/determine", s.redetermine) r.Get("/loans/{id}/determination", s.latest) r.Get("/loans/{id}/history", s.history) r.Get("/loans/{id}/sfhdf.pdf", s.loanPDF) r.Get("/events", s.events) r.Get("/monitor", s.monitorStatus) r.Post("/monitor/run", s.monitorRun) r.Get("/audit/verify", s.verify) }) }) return r } func (s *Server) auth(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if s.Token == "" { next.ServeHTTP(w, r) return } got := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer ") if subtle.ConstantTimeCompare([]byte(got), []byte(s.Token)) != 1 { w.Header().Set("WWW-Authenticate", `Bearer realm="levee"`) writeErr(w, http.StatusUnauthorized, errors.New("missing or invalid bearer token")) return } next.ServeHTTP(w, r) }) } func writeJSON(w http.ResponseWriter, code int, v any) { w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(code) enc := json.NewEncoder(w) enc.SetEscapeHTML(false) enc.SetIndent("", " ") enc.Encode(v) } func writeErr(w http.ResponseWriter, code int, err error) { writeJSON(w, code, map[string]string{"error": err.Error()}) } func (s *Server) ui(w http.ResponseWriter, _ *http.Request) { b, _ := uiFS.ReadFile("ui/index.html") w.Header().Set("Content-Type", "text/html; charset=utf-8") w.Header().Set("Content-Security-Policy", "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; img-src 'self' data:") w.Write(b) } func requestFrom(r *http.Request) (determine.Request, error) { q := r.URL.Query() req := determine.Request{Address: strings.TrimSpace(q.Get("address"))} if q.Get("lat") != "" || q.Get("lon") != "" { lat, err1 := strconv.ParseFloat(q.Get("lat"), 64) lon, err2 := strconv.ParseFloat(q.Get("lon"), 64) if err1 != nil || err2 != nil { return req, errors.New("lat and lon must both be numbers") } req.Lat, req.Lon = &lat, &lon } if req.Address == "" && req.Lat == nil { return req, errors.New("provide address=... or lat=...&lon=...") } if len(req.Address) > 300 { return req, errors.New("address too long") } return req, nil } func (s *Server) run(ctx context.Context, req determine.Request) (*determine.Determination, int, error) { d, err := s.Engine.Determine(ctx, req) if errors.Is(err, determine.ErrNoLocation) { return nil, http.StatusUnprocessableEntity, err } if err != nil { return nil, http.StatusBadGateway, err } return d, 200, nil } func (s *Server) determine(w http.ResponseWriter, r *http.Request) { req, err := requestFrom(r) if err != nil { writeErr(w, 400, err) return } d, code, err := s.run(r.Context(), req) if err != nil { writeErr(w, code, err) return } writeJSON(w, 200, map[string]any{"determination": d, "needs_review": d.NeedsReview(), "blocked": d.Blocked(), "disclaimer": disclaimer.Text}) } func (s *Server) determinePDF(w http.ResponseWriter, r *http.Request) { req, err := requestFrom(r) if err != nil { writeErr(w, 400, err) return } d, code, err := s.run(r.Context(), req) if err != nil { writeErr(w, code, err) return } q := r.URL.Query() info := s.Preparer info.LenderName, info.LenderAddress, info.LoanNumber = q.Get("lender_name"), q.Get("lender_address"), q.Get("loan_number") info.Collateral = req.Address writePDF(w, "sfhdf.pdf", sfhdf.Render(d, info)) } func writePDF(w http.ResponseWriter, name string, b []byte) { w.Header().Set("Content-Type", "application/pdf") w.Header().Set("Content-Disposition", fmt.Sprintf(`inline; filename=%q`, name)) w.Write(b) } func (s *Server) summary(w http.ResponseWriter, r *http.Request) { c, err := s.Store.Counts(r.Context()) if err != nil { writeErr(w, 500, err) return } last, _ := s.Store.Get(r.Context(), "last_monitor_run") writeJSON(w, 200, map[string]any{"counts": c, "last_monitor_run": last, "version": version.Version}) } func boolParam(r *http.Request, k string) *bool { v := r.URL.Query().Get(k) if v == "" { return nil } b := v == "1" || strings.EqualFold(v, "true") return &b } func (s *Server) listLoans(w http.ResponseWriter, r *http.Request) { limit, _ := strconv.Atoi(r.URL.Query().Get("limit")) offset, _ := strconv.Atoi(r.URL.Query().Get("offset")) if limit <= 0 || limit > 1000 { limit = 100 } loans, err := s.Store.ListLoans(r.Context(), store.LoanFilter{InSFHA: boolParam(r, "sfha"), NeedsReview: boolParam(r, "review"), Limit: limit, Offset: offset}) if err != nil { writeErr(w, 500, err) return } if loans == nil { loans = []store.Loan{} } writeJSON(w, 200, map[string]any{"loans": loans, "limit": limit, "offset": offset}) } // createLoans accepts one loan object or {"loans": [...]}; up to 25 loans are // determined synchronously, larger batches in the background. func (s *Server) createLoans(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(io.LimitReader(r.Body, 8<<20)) if err != nil { writeErr(w, 400, err) return } var many struct { Loans []store.Loan `json:"loans"` } var loans []store.Loan if json.Unmarshal(body, &many) == nil && len(many.Loans) > 0 { loans = many.Loans } else { var one store.Loan if err := json.Unmarshal(body, &one); err != nil { writeErr(w, 400, fmt.Errorf("invalid JSON: %w", err)) return } loans = []store.Loan{one} } for i := range loans { loans[i].ID = "" if strings.TrimSpace(loans[i].Address) == "" && loans[i].Lat == nil { writeErr(w, 400, fmt.Errorf("loan %d: address or lat/lon required", i)) return } if loans[i].Address == "" { loans[i].Address = fmt.Sprintf("%.6f, %.6f", *loans[i].Lat, *loans[i].Lon) } } if len(loans) > 25 { s.startImport(loans) writeJSON(w, http.StatusAccepted, map[string]any{"accepted": len(loans), "status": "/v1/monitor"}) return } rep, err := s.Monitor.Import(r.Context(), loans, nil, nil) if err != nil { writeErr(w, 500, err) return } writeJSON(w, 200, map[string]any{"report": rep, "loans": loans}) } func (s *Server) importCSV(w http.ResponseWriter, r *http.Request) { loans, errs := monitor.ParseCSV(io.LimitReader(r.Body, 64<<20)) if len(loans) == 0 { msgs := []string{} for _, e := range errs { msgs = append(msgs, e.Error()) } writeJSON(w, 400, map[string]any{"error": "no loans parsed", "details": msgs}) return } s.startImport(loans) msgs := []string{} for _, e := range errs { msgs = append(msgs, e.Error()) } writeJSON(w, http.StatusAccepted, map[string]any{"accepted": len(loans), "skipped": msgs, "status": "/v1/monitor"}) } func (s *Server) startImport(loans []store.Loan) { go func() { ctx, cancel := context.WithTimeout(context.Background(), 12*time.Hour) defer cancel() rep, err := s.Monitor.Import(ctx, loans, s.Batch, nil) if err != nil && s.Log != nil { s.Log.Error("import failed", "err", err) } s.mu.Lock() s.lastImport = rep s.mu.Unlock() }() } func (s *Server) loan(w http.ResponseWriter, r *http.Request) (*store.Loan, bool) { l, err := s.Store.GetLoan(r.Context(), chi.URLParam(r, "id")) if errors.Is(err, store.ErrNotFound) { writeErr(w, 404, errors.New("loan not found")) return nil, false } if err != nil { writeErr(w, 500, err) return nil, false } return l, true } func (s *Server) getLoan(w http.ResponseWriter, r *http.Request) { if l, ok := s.loan(w, r); ok { writeJSON(w, 200, l) } } func (s *Server) deleteLoan(w http.ResponseWriter, r *http.Request) { l, ok := s.loan(w, r) if !ok { return } if err := s.Store.DeactivateLoan(r.Context(), l.ID); err != nil { writeErr(w, 500, err) return } writeJSON(w, 200, map[string]string{"status": "deactivated", "id": l.ID}) } func (s *Server) redetermine(w http.ResponseWriter, r *http.Request) { l, ok := s.loan(w, r) if !ok { return } res, err := s.Monitor.Redetermine(r.Context(), l.ID) if err != nil { writeErr(w, http.StatusBadGateway, err) return } writeJSON(w, 200, map[string]any{"determination_id": res.DeterminationID, "saved": res.Saved, "changes": res.Changes, "determination": res.Determination}) } func (s *Server) latest(w http.ResponseWriter, r *http.Request) { l, ok := s.loan(w, r) if !ok { return } d, err := s.Store.LatestDetermination(r.Context(), l.ID) if errors.Is(err, store.ErrNotFound) { writeErr(w, 404, errors.New("loan has not been determined yet")) return } if err != nil { writeErr(w, 500, err) return } writeJSON(w, 200, d) } func (s *Server) history(w http.ResponseWriter, r *http.Request) { l, ok := s.loan(w, r) if !ok { return } h, err := s.Store.History(r.Context(), l.ID) if err != nil { writeErr(w, 500, err) return } if h == nil { h = []store.StoredDetermination{} } writeJSON(w, 200, map[string]any{"loan_id": l.ID, "determinations": h}) } // LoanInfo builds the SFHDF loan/preparer block for a stored loan. func LoanInfo(preparer sfhdf.Info, l *store.Loan, d *store.StoredDetermination) sfhdf.Info { info := preparer info.LenderName, info.LenderAddress, info.LenderID = l.LenderName, l.LenderAddress, l.LenderID info.LoanNumber, info.AmountRequired, info.Collateral = l.LoanNumber, l.AmountRequired, l.Address info.DeterminationID = strconv.FormatInt(d.ID, 10) info.Hash = d.Hash return info } func (s *Server) loanPDF(w http.ResponseWriter, r *http.Request) { l, ok := s.loan(w, r) if !ok { return } d, err := s.Store.LatestDetermination(r.Context(), l.ID) if errors.Is(err, store.ErrNotFound) { writeErr(w, 404, errors.New("loan has not been determined yet")) return } if err != nil { writeErr(w, 500, err) return } name := "sfhdf-" + strings.Map(func(r rune) rune { if r == '-' || r == '_' || (r >= '0' && r <= '9') || (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') { return r } return '_' }, nonEmpty(l.LoanNumber, l.ID)) + ".pdf" writePDF(w, name, sfhdf.Render(d.Body, LoanInfo(s.Preparer, l, d))) } func nonEmpty(a, b string) string { if a != "" { return a } return b } func (s *Server) events(w http.ResponseWriter, r *http.Request) { since, _ := strconv.ParseInt(r.URL.Query().Get("since"), 10, 64) limit, _ := strconv.Atoi(r.URL.Query().Get("limit")) ev, err := s.Store.ListEvents(r.Context(), since, r.URL.Query().Get("loan"), limit) if err != nil { writeErr(w, 500, err) return } if ev == nil { ev = []store.Event{} } next := since if len(ev) > 0 { next = ev[len(ev)-1].ID } writeJSON(w, 200, map[string]any{"events": ev, "next_since": next}) } func (s *Server) monitorStatus(w http.ResponseWriter, _ *http.Request) { s.mu.Lock() defer s.mu.Unlock() writeJSON(w, 200, map[string]any{"running": s.running, "last_report": s.lastReport, "last_import": s.lastImport}) } // RunMonitor runs one monitoring pass unless one is already running. func (s *Server) RunMonitor(ctx context.Context) (*monitor.Report, error) { s.mu.Lock() if s.running { s.mu.Unlock() return nil, errors.New("a monitoring run is already in progress") } s.running = true s.mu.Unlock() rep, err := s.Monitor.Run(ctx) s.mu.Lock() s.running = false s.lastReport = rep s.mu.Unlock() return rep, err } func (s *Server) monitorRun(w http.ResponseWriter, _ *http.Request) { s.mu.Lock() busy := s.running s.mu.Unlock() if busy { writeErr(w, http.StatusConflict, errors.New("a monitoring run is already in progress")) return } go func() { ctx, cancel := context.WithTimeout(context.Background(), 12*time.Hour) defer cancel() if _, err := s.RunMonitor(ctx); err != nil && s.Log != nil { s.Log.Error("monitor run failed", "err", err) } }() writeJSON(w, http.StatusAccepted, map[string]string{"status": "started", "poll": "/v1/monitor"}) } func (s *Server) verify(w http.ResponseWriter, r *http.Request) { n, err := s.Store.VerifyChain(r.Context()) if err != nil { writeJSON(w, 409, map[string]any{"ok": false, "verified": n, "error": err.Error()}) return } writeJSON(w, 200, map[string]any{"ok": true, "verified": n}) }