package webui import ( "context" "encoding/csv" "encoding/json" "errors" "fmt" "io" "maps" "mime" "net/http" "net/url" "strconv" "strings" "time" "google.golang.org/grpc/codes" "google.golang.org/grpc/status" controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" "github.com/samcharles93/archie-core/internal/domain/access" "github.com/samcharles93/archie-core/internal/domain/audit" "github.com/samcharles93/archie-core/internal/ratelimit" ) // auditExportPageSize is the largest page the feed serves. An export walks // pages this size. const auditExportPageSize = audit.MaxLimit // The export budget: six exports an hour per identity, one at a time. The // caller's explicit range bounds the work, the deadline bounds the request, // and the page cap bounds the stream even if the range is dense. const ( auditExportPerHour = 6 auditExportWindow = time.Hour auditExportMaxRange = 366 * 24 * time.Hour auditExportDeadline = 5 * time.Minute auditExportMaxPages = 2000 // auditExportMaxRows bounds one download. The preflight refuses a larger // match before any byte is written, so a client never gets a truncated // file it cannot tell from a complete one. auditExportMaxRows = 100_000 ) var ( errAuditExportTooLarge = errors.New("audit export exceeded its page cap") errAuditExportCursor = errors.New("audit export cursor unreadable") ) type auditActorView struct { ID string `json:"id"` Name string `json:"name"` Kind string `json:"kind"` PrincipalID string `json:"principal_id"` } type auditTargetView struct { Kind string `json:"kind"` ID string `json:"id"` Label string `json:"label"` Href string `json:"href,omitempty"` } type auditFieldView struct { Field string `json:"field"` Old json.RawMessage `json:"old"` New json.RawMessage `json:"new"` } type auditDetailView struct { Fields []auditFieldView `json:"fields"` Data json.RawMessage `json:"data"` Version int64 `json:"version"` RequestID string `json:"request_id"` Source string `json:"source"` Table string `json:"table"` } type auditRecordView struct { ID string `json:"id"` At time.Time `json:"at"` Category string `json:"category"` Action string `json:"action"` Kind string `json:"kind"` Severity string `json:"severity"` Outcome string `json:"outcome"` Actor auditActorView `json:"actor"` Target auditTargetView `json:"target"` Summary string `json:"summary"` Detail auditDetailView `json:"detail"` } // auditSettingsKind is one control-plane resource kind and the title the // catalog gives it, so the dashboard labels a settings row without carrying // its own copy of the vocabulary. type auditSettingsKind struct { Kind string `json:"kind"` Title string `json:"title"` } type auditFacetsView struct { Categories []string `json:"categories"` Severities []string `json:"severities"` Outcomes []string `json:"outcomes"` TargetKinds []string `json:"target_kinds"` SettingsKinds []auditSettingsKind `json:"settings_kinds"` } type auditResponse struct { Records []auditRecordView `json:"records"` NextCursor string `json:"next_cursor"` HasMore bool `json:"has_more"` // Facets is supplied on the first page only: it is the closed vocabulary // the UI needs once, not a field to repeat on every page. Facets *auditFacetsView `json:"facets,omitempty"` } // handleAudit is GET /api/audit: one page of the org-scoped feed. The org and // the reader's authority come from the authenticated principal in the request // context; the query string never names an org. func (s *Server) handleAudit(w http.ResponseWriter, r *http.Request) { if s.Audit == nil { http.Error(w, "audit feed unavailable", http.StatusServiceUnavailable) return } filter, cursor, limit, err := auditRequest(r) if err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } if err := filter.Normalize(); err != nil { http.Error(w, firstLine(err.Error()), http.StatusBadRequest) return } page, err := s.Audit.ListAudit(r.Context(), filter, cursor, limit) if err != nil { writeAuditError(w, err) return } labels, settings := s.auditLabels(r.Context()) records := make([]auditRecordView, 0, len(page.Entries)) for _, entry := range page.Entries { records = append(records, auditRecord(entry, labels)) } response := auditResponse{Records: records, NextCursor: page.NextCursor, HasMore: page.HasMore} if cursor.IsZero() { response.Facets = &auditFacetsView{ Categories: audit.Categories(), Severities: audit.Severities(), Outcomes: audit.Outcomes(), TargetKinds: audit.TargetKinds(), SettingsKinds: settings, } } writeJSON(w, response) } // handleAuditExport is GET /api/audit/export?format=csv|json with the feed's // filters. It requires an explicit range of at most a year and streams rows // page by page. func (s *Server) handleAuditExport(w http.ResponseWriter, r *http.Request) { if s.Audit == nil { http.Error(w, "audit feed unavailable", http.StatusServiceUnavailable) return } format, ok := auditExportFormat(r) if !ok { http.Error(w, "format must be csv or json", http.StatusBadRequest) return } filter, _, _, err := auditRequest(r) if err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } if err := filter.Normalize(); err != nil { http.Error(w, firstLine(err.Error()), http.StatusBadRequest) return } if err := auditExportRange(filter); err != nil { http.Error(w, err.Error(), http.StatusBadRequest) return } identity := auditExportIdentity(r.Context()) // Take the guard before charging the budget: a request rejected because // the same identity is already exporting must cost no allowance. if !s.beginAuditExport(identity) { http.Error(w, "an audit export is already running for this identity", http.StatusTooManyRequests) return } defer s.endAuditExport(identity) if !s.auditExportLimiter().Allow("audit-export", identity) { http.Error(w, "too many audit exports; try again later", http.StatusTooManyRequests) return } ctx, cancel := context.WithTimeout(r.Context(), auditExportDeadline) defer cancel() // Count before any header is written: a match over the cap is the // caller's problem to narrow, not a download that ends early. if !s.auditExportWithinBudget(ctx, w, filter) { return } // Fetch the first page before setting download headers: a failure here is // still a normal error response, not a truncated file. first, err := s.Audit.ListAudit(ctx, filter, audit.Cursor{}, auditExportPageSize) if err != nil { writeAuditError(w, err) return } writeAuditExportHeaders(w, format) labels, _ := s.auditLabels(ctx) flush := func() {} if flusher, ok := w.(http.Flusher); ok { flush = flusher.Flush } var rows int64 if format == "csv" { rows, err = s.exportAuditCSV(ctx, filter, first, labels, w, flush) } else { rows, err = s.exportAuditJSON(ctx, filter, first, labels, w, flush) } if err != nil { // Headers and status are already on the wire, so no error status is // left to send. Abort the connection so the client sees a failed // download rather than a silently short file. s.logf("audit export failed", "format", format, "err", err) panic(http.ErrAbortHandler) } // The file is complete; the trail row is bookkeeping, so a failed write // is logged rather than turning a delivered export into a failed one. if err := s.Audit.RecordAuditExport(r.Context(), format, filter.Hash(), rows); err != nil { s.logf("record audit export", "format", format, "err", err) } } // auditExportWithinBudget refuses an export whose filter matches more than the // cap, answering before any header is written so the client never receives a // truncated file it cannot tell from a complete one. A feed error is written // with the same status mapping as a page read. func (s *Server) auditExportWithinBudget(ctx context.Context, w http.ResponseWriter, filter audit.Filter) bool { count, err := s.Audit.CountAudit(ctx, filter) if err != nil { writeAuditError(w, err) return false } if count > auditExportMaxRows { http.Error(w, fmt.Sprintf( "%d rows match; narrow the time range to at most %d", count, auditExportMaxRows, ), http.StatusBadRequest) return false } return true } // auditExportFormat resolves the download format. An absent format means JSON. func auditExportFormat(r *http.Request) (string, bool) { format := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("format"))) switch format { case "": return "json", true case "csv", "json": return format, true } return "", false } // auditExportAllTime is the "any time" sentinel the dashboard sends for // from. An export from the epoch is bounded by the page cap and deadline // instead of the usual year. var auditExportAllTime = time.Unix(0, 0).UTC() // auditExportRange requires an explicit window of at most a year: an unbounded // export would stream the instance's whole history. func auditExportRange(filter audit.Filter) error { if filter.From.IsZero() || filter.To.IsZero() { return errors.New("choose an export time range of 366 days or less") } if filter.From.Equal(auditExportAllTime) { return nil } if filter.To.Sub(filter.From) > auditExportMaxRange { return errors.New("choose an export time range of 366 days or less") } return nil } func writeAuditExportHeaders(w http.ResponseWriter, format string) { filename := "audit-" + time.Now().UTC().Format("20060102-150405") + "." + format contentType := "application/json" if format == "csv" { contentType = "text/csv; charset=utf-8" } w.Header().Set("Content-Type", contentType) w.Header().Set("Content-Disposition", mime.FormatMediaType("attachment", map[string]string{"filename": filename})) w.Header().Set("Cache-Control", "no-store") w.Header().Set("X-Content-Type-Options", "nosniff") } func (s *Server) exportAuditCSV(ctx context.Context, filter audit.Filter, first audit.Page, labels *auditLabels, w io.Writer, flush func()) (int64, error) { writer := csv.NewWriter(w) if err := writer.Write(auditCSVHeader); err != nil { return 0, err } rows, err := s.walkAudit(ctx, filter, first, func(entry audit.Entry) error { return writer.Write(auditCSVRow(auditRecord(entry, labels))) }, func() { writer.Flush() flush() }) writer.Flush() if flushErr := writer.Error(); err == nil { err = flushErr } return rows, err } func (s *Server) exportAuditJSON(ctx context.Context, filter audit.Filter, first audit.Page, labels *auditLabels, w io.Writer, flush func()) (int64, error) { if _, err := io.WriteString(w, "["); err != nil { return 0, err } encoder := json.NewEncoder(w) firstRecord := true rows, err := s.walkAudit(ctx, filter, first, func(entry audit.Entry) error { if !firstRecord { if _, err := io.WriteString(w, ","); err != nil { return err } } firstRecord = false return encoder.Encode(auditRecord(entry, labels)) }, flush) if err != nil { // Leave the array open: the handler aborts the connection, and a // closed array would masquerade as a complete download. return rows, err } _, err = io.WriteString(w, "]\n") return rows, err } // walkAudit streams every entry of the window in feed order and returns how // many it emitted. It starts from the already-fetched first page so the caller // could answer an error before any byte of the download was written. func (s *Server) walkAudit(ctx context.Context, filter audit.Filter, first audit.Page, emit func(audit.Entry) error, afterPage func()) (int64, error) { page := first pages := 1 var rows int64 for { for _, entry := range page.Entries { if err := emit(entry); err != nil { return rows, err } rows++ } if afterPage != nil { afterPage() } if !page.HasMore || page.NextCursor == "" { return rows, nil } if pages >= auditExportMaxPages { return rows, errAuditExportTooLarge } pages++ cursor, ok := audit.ParseCursor(page.NextCursor) if !ok { return rows, errAuditExportCursor } next, err := s.Audit.ListAudit(ctx, filter, cursor, auditExportPageSize) if err != nil { return rows, err } page = next } } // auditRequest parses the shared filter query. Multi-valued parameters accept // both repeated keys and comma-separated values, so the dashboard can send // either encoding. func auditRequest(r *http.Request) (audit.Filter, audit.Cursor, int, error) { query := r.URL.Query() filter := audit.Filter{ Categories: auditList(query, "categories"), Actions: auditList(query, "actions"), Kinds: auditList(query, "kind"), Actor: query.Get("actor"), TargetKinds: auditList(query, "target_kind"), TargetIDs: auditList(query, "target_id"), Severities: auditList(query, "severity"), Outcomes: auditList(query, "outcome"), Query: query.Get("q"), } from, err := auditTime(query.Get("from")) if err != nil { return audit.Filter{}, audit.Cursor{}, 0, fmt.Errorf("invalid from: %w", err) } to, err := auditTime(query.Get("to")) if err != nil { return audit.Filter{}, audit.Cursor{}, 0, fmt.Errorf("invalid to: %w", err) } filter.From, filter.To = from, to cursor := audit.Cursor{} if raw := strings.TrimSpace(query.Get("cursor")); raw != "" { // A malformed cursor means newest, matching the feed's own rule. if parsed, ok := audit.ParseCursor(raw); ok { cursor = parsed } } limit := 0 if raw := strings.TrimSpace(query.Get("limit")); raw != "" { parsed, err := strconv.Atoi(raw) if err != nil || parsed < 0 { return audit.Filter{}, audit.Cursor{}, 0, fmt.Errorf("invalid limit") } limit = parsed } return filter, cursor, limit, nil } func auditList(query url.Values, key string) []string { var out []string for _, value := range query[key] { for part := range strings.SplitSeq(value, ",") { if part = strings.TrimSpace(part); part != "" { out = append(out, part) } } } return out } // auditTime accepts the RFC3339 the dashboard sends and the local-style value // a datetime control produces, treated as UTC rather than guessing a zone. func auditTime(value string) (time.Time, error) { value = strings.TrimSpace(value) if value == "" { return time.Time{}, nil } for _, layout := range []string{time.RFC3339Nano, "2006-01-02T15:04:05", "2006-01-02T15:04", "2006-01-02"} { if parsed, err := time.Parse(layout, value); err == nil { return parsed.UTC(), nil } } return time.Time{}, fmt.Errorf("want an RFC3339 time") } // auditLabels resolves the display names one response needs. Actor names and // catalog titles are fetched once; workflow names are loaded only when a row // actually targets a workflow. type auditLabels struct { actorName func(string) string titles map[string]string workflowFn func() map[string]string workflows map[string]string } func (l *auditLabels) workflow(id string) string { if l.workflows == nil { l.workflows = map[string]string{} if l.workflowFn != nil { maps.Copy(l.workflows, l.workflowFn()) } } return l.workflows[id] } // auditLabels builds the label resolver and the settings-kind facet in one // catalog read. A failed catalog read degrades labels to their ids; it never // fails the feed. func (s *Server) auditLabels(ctx context.Context) (*auditLabels, []auditSettingsKind) { labels := &auditLabels{actorName: s.actorNames(ctx), titles: map[string]string{}} settings := []auditSettingsKind{} for _, resource := range s.auditCatalogResources(ctx) { if resource.GetTitle() != "" { labels.titles[resource.GetKind()] = resource.GetTitle() } // Domain-managed kinds are read through their own service, so they // never appear as a stored settings document. if resource.GetQueryService() == "" { settings = append(settings, auditSettingsKind{Kind: resource.GetKind(), Title: resource.GetTitle()}) } } labels.workflowFn = func() map[string]string { definitions, err := s.workflowDefinitions(ctx) if err != nil { return nil } names := make(map[string]string, len(definitions)) for _, definition := range definitions { names[definition.ID] = definition.Name } return names } return labels, settings } // auditCatalogResources reads the control-plane catalogue once. A missing // control plane or a failed read leaves labels at their ids rather than // failing the feed. func (s *Server) auditCatalogResources(ctx context.Context) []*controlpb.ResourceDescriptor { if s.ControlPlane == nil { return nil } catalog, err := s.ControlPlane.Catalog(ctx, &controlpb.CatalogRequest{}) if err != nil { return nil } return catalog.GetResources() } func auditRecord(entry audit.Entry, labels *auditLabels) auditRecordView { fields := make([]auditFieldView, 0, len(entry.Fields)) for _, field := range entry.Fields { fields = append(fields, auditFieldView{Field: field.Name, Old: jsonOrNull(field.Old), New: jsonOrNull(field.New)}) } return auditRecordView{ ID: entry.ID(), At: entry.At, Category: string(entry.Category), Action: entry.Action, Kind: entry.Kind, Severity: string(entry.Severity), Outcome: string(entry.Outcome), Actor: auditActorView{ ID: entry.Actor, Name: labels.actorName(entry.Actor), Kind: entry.ActorKind, PrincipalID: entry.PrincipalID, }, Target: auditTarget(entry, labels), Summary: entry.Summary(), Detail: auditDetailView{ Fields: fields, Data: jsonOrNull(entry.Data), Version: entry.RecordVersion, RequestID: entry.RequestID, Source: entry.Source, Table: auditEntryTable(entry), }, } } func auditTarget(entry audit.Entry, labels *auditLabels) auditTargetView { view := auditTargetView{Kind: entry.TargetKind, ID: entry.TargetID} switch entry.TargetKind { case "resource": // A settings row's id is the control-plane kind the catalog names. view.Label = labels.titles[entry.TargetID] case "task": if entry.TargetID != "" { view.Label = "#" + entry.TargetID view.Href = "/tasks/" + url.PathEscape(entry.TargetID) } case "identity": view.Label = labels.actorName(entry.TargetID) view.Href = "/org/agents" case "workflow": view.Label = labels.workflow(entry.TargetID) view.Href = "/workflows" } if view.Label == "" { view.Label = auditTargetLabel(entry.TargetKind, entry.TargetID) } return view } // auditTargetLabel is the fallback for a row the dashboard has no route or // title for: the kind and id it names. func auditTargetLabel(kind, id string) string { switch { case kind == "" && id == "": return "" case kind == "": return id case id == "": return kind default: return kind + "/" + id } } // auditEntryTable is the audited table a row came from, for the detail view. // The read model does not carry it, so it is derived from the branch that // produced the row; coverage rows already carry their table name as the // target kind. func auditEntryTable(entry audit.Entry) string { switch { case entry.Category == audit.CategoryIdentity: return "identity_events" case entry.Category == audit.CategoryRuntime, entry.Category == audit.CategoryAutomation: return "events" case entry.Kind == "access_denial": return "access_denials" case entry.TargetKind == "policy": return "access_policies" case entry.TargetKind == "" || entry.TargetKind == "resource": return "resources" default: return entry.TargetKind } } // writeAuditError maps the feed's transport errors to the dashboard's status // vocabulary. An unreadable feed is unavailable, never an empty page. func writeAuditError(w http.ResponseWriter, err error) { code := http.StatusInternalServerError switch status.Code(err) { case codes.InvalidArgument: code = http.StatusBadRequest case codes.PermissionDenied: code = http.StatusForbidden case codes.Unavailable, codes.DeadlineExceeded: code = http.StatusServiceUnavailable } message := firstLine(status.Convert(err).Message()) if message == "" { message = http.StatusText(code) } http.Error(w, message, code) } func firstLine(message string) string { line, _, _ := strings.Cut(message, "\n") return strings.TrimSpace(line) } // auditExportIdentity is the rate-limit key: the signed-in person. A service // call acting for no person falls back to its org so it still has a budget. func auditExportIdentity(ctx context.Context) string { principal, ok := access.PrincipalFromContext(ctx) if !ok { return "unknown" } if principal.IdentityID != "" { return string(principal.IdentityID) } if principal.Org != "" { return "org:" + string(principal.Org) } return "unknown" } func (s *Server) auditExportLimiter() *ratelimit.Limiter { s.auditExportOnce.Do(func() { s.auditExportRate = ratelimit.New(auditExportWindow, auditExportPerHour) }) return s.auditExportRate } // beginAuditExport admits one export per identity. The guard is per identity, // not process-wide: one person's long export must not stop another person in // another org from taking their own. func (s *Server) beginAuditExport(identity string) bool { s.auditExportMu.Lock() defer s.auditExportMu.Unlock() if s.auditExporting == nil { s.auditExporting = make(map[string]bool) } if s.auditExporting[identity] { return false } s.auditExporting[identity] = true return true } func (s *Server) endAuditExport(identity string) { s.auditExportMu.Lock() delete(s.auditExporting, identity) s.auditExportMu.Unlock() } var auditCSVHeader = []string{ "id", "at", "category", "action", "kind", "severity", "outcome", "actor_id", "actor_name", "actor_kind", "principal_id", "target_kind", "target_id", "target_label", "summary", "fields", "data", "version", "request_id", "source", "table", } func auditCSVRow(view auditRecordView) []string { fields, _ := json.Marshal(view.Detail.Fields) return []string{ csvCell(view.ID), csvCell(view.At.UTC().Format(time.RFC3339Nano)), csvCell(view.Category), csvCell(view.Action), csvCell(view.Kind), csvCell(view.Severity), csvCell(view.Outcome), csvCell(view.Actor.ID), csvCell(view.Actor.Name), csvCell(view.Actor.Kind), csvCell(view.Actor.PrincipalID), csvCell(view.Target.Kind), csvCell(view.Target.ID), csvCell(view.Target.Label), csvCell(view.Summary), csvCell(string(fields)), csvCell(string(view.Detail.Data)), csvCell(strconv.FormatInt(view.Detail.Version, 10)), csvCell(view.Detail.RequestID), csvCell(view.Detail.Source), csvCell(view.Detail.Table), } } // csvCell neutralises a spreadsheet formula. A cell a spreadsheet would // evaluate is prefixed with an apostrophe, which every common spreadsheet // reads as text. Quoting and newlines are encoding/csv's job. func csvCell(value string) string { if value == "" { return value } switch value[0] { case '=', '+', '-', '@', '\t', '\r': return "'" + value } return value } func jsonOrNull(value []byte) json.RawMessage { if len(value) == 0 { return json.RawMessage("null") } return value }