Add file-based audit logging and reports API

Introduce file-based audit logging and reporting support.

- Add internal/audit: file logger (OpenFile/Close) that fans audit lines to stderr and daily .jsonl files; ReadEntries to query entries by time, stage and limit (default 200, max 1000).
- Wire audit into cmd/gateway: open audit files on startup and pass audit dir to REST server; default GATEWAY_AUDIT_DIR is .local/audit.
- Extend internal/api/rest: Server.WithAuditDir, and new endpoints GET /api/v1/audit (list audit entries) and GET /api/v1/reports (store-backed summary).
- Extend internal/config to include AuditDir and load from env.
- Add reporting types and interface to internal/store (DaySummary, ReportSummary, Reporter) and implement Summary for SQLite backend (internal/store/sqlite/reports.go).
- Update web client and types: add AuditEntry and ReportSummary types and client methods to call the new audit and reports endpoints.

These changes enable persisting audit trails to disk and querying aggregated message reports from the store.

Author: vagnercazarotto

cmd/gateway/main.go

@@ -34,6 +34,13 @@ func main() {
 	}
 	defer st.Close()
 
+	// File-based audit logger (fan-out: stderr + daily .jsonl).
+	auditCloser, err := audit.OpenFile(cfg.AuditDir)
+	if err != nil {
+		log.Fatalf("[gateway] audit: %v", err)
+	}
+	defer auditCloser.Close()
+
 	// Channel registry — load from YAML if configured.
 	reg := channel.NewRegistry()
 	if cfg.ChannelsFile != "" {
@@ -48,7 +55,7 @@ func main() {
 	// HTTP REST API
 	httpSrv := &http.Server{
 		Addr:    ":" + cfg.HTTPPort,
-		Handler: rest.New(st, reg),
+		Handler: rest.New(st, reg).WithAuditDir(cfg.AuditDir),
 	}
 	go func() {
 		log.Printf("[gateway] REST API listening on :%s", cfg.HTTPPort)

internal/api/rest/server.go

@@ -26,6 +26,7 @@ import (
 	"strconv"
 	"time"
 
+	"github.com/vagnercazarotto/verifhir-gateway/internal/audit"
 	"github.com/vagnercazarotto/verifhir-gateway/internal/channel"
 	"github.com/vagnercazarotto/verifhir-gateway/internal/store"
 )
@@ -57,6 +58,7 @@ type MessageResponse struct {
 type Server struct {
 	store    store.Store
 	channels *channel.Registry
+	auditDir string
 	mux      *http.ServeMux
 }
 
@@ -73,12 +75,22 @@ func New(st store.Store, reg *channel.Registry) *Server {
 	s.mux.HandleFunc("GET /api/v1/channels/{id}", s.getChannel)
 	s.mux.HandleFunc("PUT /api/v1/channels/{id}", s.updateChannel)
 	s.mux.HandleFunc("DELETE /api/v1/channels/{id}", s.deleteChannel)
+	// audit + reports routes
+	s.mux.HandleFunc("GET /api/v1/audit", s.listAudit)
+	s.mux.HandleFunc("GET /api/v1/reports", s.getReports)
 	// health routes
 	s.mux.HandleFunc("GET /healthz", s.healthz)
 	s.mux.HandleFunc("GET /readyz", s.readyz)
 	return s
 }
 
+// WithAuditDir sets the directory from which audit log entries are served.
+// Call before the server starts accepting requests.
+func (s *Server) WithAuditDir(dir string) *Server {
+	s.auditDir = dir
+	return s
+}
+
 // ServeHTTP implements http.Handler.
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	s.mux.ServeHTTP(w, r)
@@ -246,6 +258,62 @@ func (s *Server) deleteChannel(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusNoContent)
 }
 
+// listAudit handles GET /api/v1/audit
+//
+// Query parameters:
+//   - from   — RFC3339 lower bound (inclusive)
+//   - to     — RFC3339 upper bound (inclusive)
+//   - stage  — filter by pipeline stage (ingest|parse|map|score|route)
+//   - limit  — max records (default 200, max 1000)
+func (s *Server) listAudit(w http.ResponseWriter, r *http.Request) {
+	if s.auditDir == "" {
+		writeError(w, http.StatusNotImplemented, "audit log directory not configured")
+		return
+	}
+	q := r.URL.Query()
+	limit := 200
+	if raw := q.Get("limit"); raw != "" {
+		n, err := strconv.Atoi(raw)
+		if err != nil || n <= 0 {
+			writeError(w, http.StatusBadRequest, "limit must be a positive integer")
+			return
+		}
+		if n > 1000 {
+			n = 1000
+		}
+		limit = n
+	}
+	entries, err := audit.ReadEntries(s.auditDir, q.Get("from"), q.Get("to"), q.Get("stage"), limit)
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	if entries == nil {
+		entries = []audit.Entry{}
+	}
+	writeJSON(w, http.StatusOK, entries)
+}
+
+// getReports handles GET /api/v1/reports
+//
+// Query parameters:
+//   - from — RFC3339 lower bound (inclusive)
+//   - to   — RFC3339 upper bound (inclusive)
+func (s *Server) getReports(w http.ResponseWriter, r *http.Request) {
+	rep, ok := s.store.(store.Reporter)
+	if !ok {
+		writeError(w, http.StatusNotImplemented, "reporting not supported by this store backend")
+		return
+	}
+	q := r.URL.Query()
+	summary, err := rep.Summary(r.Context(), q.Get("from"), q.Get("to"))
+	if err != nil {
+		writeError(w, http.StatusBadRequest, err.Error())
+		return
+	}
+	writeJSON(w, http.StatusOK, summary)
+}
+
 func writeJSON(w http.ResponseWriter, status int, v any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)

internal/audit/file.go

@@ -0,0 +1,172 @@
+package audit
+
+import (
+	"bufio"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+// fileLogger fans audit lines out to stderr and a daily .jsonl file.
+type fileLogger struct {
+	dir     string
+	current *os.File
+	day     string // "YYYY-MM-DD" of the currently open file
+	prev    io.Writer
+}
+
+// OpenFile configures the audit package to write JSON lines to both stderr
+// and a daily file under dir (created if absent).
+// Call Close on the returned io.Closer during shutdown.
+func OpenFile(dir string) (io.Closer, error) {
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return nil, fmt.Errorf("audit: mkdir %q: %w", dir, err)
+	}
+	fl := &fileLogger{dir: dir, prev: out}
+	if err := fl.rotate(); err != nil {
+		return nil, err
+	}
+	out = io.MultiWriter(os.Stderr, fl)
+	return fl, nil
+}
+
+func (fl *fileLogger) rotate() error {
+	day := time.Now().UTC().Format("2006-01-02")
+	if fl.day == day && fl.current != nil {
+		return nil
+	}
+	if fl.current != nil {
+		fl.current.Close()
+	}
+	path := filepath.Join(fl.dir, day+".jsonl")
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		return fmt.Errorf("audit: open %q: %w", path, err)
+	}
+	fl.current = f
+	fl.day = day
+	return nil
+}
+
+func (fl *fileLogger) Write(p []byte) (int, error) {
+	_ = fl.rotate() // best-effort daily rotation
+	if fl.current == nil {
+		return len(p), nil
+	}
+	return fl.current.Write(p)
+}
+
+// Close restores the previous audit sink and closes the open file.
+func (fl *fileLogger) Close() error {
+	out = fl.prev
+	if fl.current != nil {
+		return fl.current.Close()
+	}
+	return nil
+}
+
+// ReadEntries reads and filters audit entries from all .jsonl files in dir.
+// from/to must be RFC3339 timestamps (empty = no bound).
+// stage filters by entry stage field (empty = all stages).
+// Results are newest-first, capped at limit (0 = 200).
+func ReadEntries(dir, from, to, stage string, limit int) ([]Entry, error) {
+	des, err := os.ReadDir(dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []Entry{}, nil
+		}
+		return nil, fmt.Errorf("audit: readdir %q: %w", dir, err)
+	}
+
+	// sort filenames descending so we read newest days first
+	sort.Slice(des, func(i, j int) bool {
+		return des[i].Name() > des[j].Name()
+	})
+
+	var fromT, toT time.Time
+	if from != "" {
+		fromT, err = time.Parse(time.RFC3339, from)
+		if err != nil {
+			return nil, fmt.Errorf("audit: invalid from: %w", err)
+		}
+	}
+	if to != "" {
+		toT, err = time.Parse(time.RFC3339, to)
+		if err != nil {
+			return nil, fmt.Errorf("audit: invalid to: %w", err)
+		}
+	}
+	if limit <= 0 {
+		limit = 200
+	}
+
+	var results []Entry
+	for _, de := range des {
+		if !strings.HasSuffix(de.Name(), ".jsonl") {
+			continue
+		}
+		// quick range prune using the filename date
+		day := strings.TrimSuffix(de.Name(), ".jsonl")
+		if !fromT.IsZero() && day < fromT.Format("2006-01-02") {
+			continue
+		}
+		if !toT.IsZero() && day > toT.Format("2006-01-02") {
+			continue
+		}
+		got, err := readJSONL(filepath.Join(dir, de.Name()), fromT, toT, stage)
+		if err != nil {
+			continue // best-effort: skip corrupted files
+		}
+		results = append(results, got...)
+		if len(results) >= limit {
+			break
+		}
+	}
+	if len(results) > limit {
+		results = results[:limit]
+	}
+	return results, nil
+}
+
+func readJSONL(path string, from, to time.Time, stage string) ([]Entry, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	var entries []Entry
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		var e Entry
+		if err := json.Unmarshal(sc.Bytes(), &e); err != nil {
+			continue
+		}
+		if stage != "" && e.Stage != stage {
+			continue
+		}
+		if !from.IsZero() || !to.IsZero() {
+			t, err := time.Parse(time.RFC3339, e.Timestamp)
+			if err != nil {
+				continue
+			}
+			if !from.IsZero() && t.Before(from) {
+				continue
+			}
+			if !to.IsZero() && t.After(to) {
+				continue
+			}
+		}
+		entries = append(entries, e)
+	}
+	// reverse so newest lines in the file come first
+	for i, j := 0, len(entries)-1; i < j; i, j = i+1, j-1 {
+		entries[i], entries[j] = entries[j], entries[i]
+	}
+	return entries, sc.Err()
+}

internal/config/config.go

@@ -10,6 +10,7 @@ type Config struct {
 	MLLPAddr     string
 	DBPath       string // SQLite file path; ignored when DATABASE_URL is set
 	ChannelsFile string // optional YAML file with channel definitions
+	AuditDir     string // directory for daily .jsonl audit files
 }
 
 func Load() Config {
@@ -28,10 +29,16 @@ func Load() Config {
 		dbPath = ".local/verifhir.db"
 	}
 
+	auditDir := os.Getenv("GATEWAY_AUDIT_DIR")
+	if auditDir == "" {
+		auditDir = ".local/audit"
+	}
+
 	return Config{
 		HTTPPort:     port,
 		MLLPAddr:     mllp,
 		DBPath:       dbPath,
 		ChannelsFile: os.Getenv("GATEWAY_CHANNELS_FILE"),
+		AuditDir:     auditDir,
 	}
 }