// Package webui implements the dashboard's HTTP API and serves the embedded SPA. package webui import ( "context" "encoding/json" "io/fs" "log/slog" "net/http" "strconv" "strings" "sync" "time" "github.com/klauspost/compress/gzhttp" 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/domain/health" "github.com/samcharles93/archie-core/internal/domain/identity" "github.com/samcharles93/archie-core/internal/domain/org" "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/storepkg" "github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/infrastructure/captureintake" "github.com/samcharles93/archie-core/internal/infrastructure/telemetry" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/ratelimit" "github.com/samcharles93/archie-core/internal/secret" "github.com/samcharles93/archie-core/ui" ) type Server struct { RepositoryChecks RepositoryChecker Accounts identity.Accounts accountRateLimit *ratelimit.Limiter Store storecontract.TaskStore // Usage reads the caller org's model-usage report. Nil answers // GET /api/usage with 503. Usage storecontract.UsageStore Log *slog.Logger // Steps lists an execution's recorded steps. Nil reports none. Steps storecontract.StepReader // ConfigSource supplies the configuration projection GET /api/config // renders. Composition sets it to RemoteConfigView in a process that // only displays configuration; unset means this process builds the view // from the configuration it holds (LocalConfigView). ConfigSource ConfigViewSource CheckSecret func(context.Context, secret.SecretRef) (bool, error) // LogFeed is the daemon diagnostic stream. It is separate from Events, // which contains persisted task lifecycle activity only. LogFeed *logging.Feed LogSources map[string]LogSource // TaskLogs reads task logs. Nil means this process cannot read them. TaskLogs TaskLogSource // Channels reports actual adapter lifecycle, independently of configuration. // A process that hosts channels satisfies it from its own manager; the // dashboard process satisfies it by reading the State Store, where the // hosting process publishes (webui.RemoteChannelStatus). Channels ChannelStatusSource // ReloadChannel invokes a channel-specific reload seam. Only adapters that // explicitly support reload are wired here; nil means reload is unavailable. ReloadChannel func(context.Context, string) error // Skills is the webui-owned skill catalogue view; nil degrades // /api/skills to an empty page. Skills SkillCatalog // Curators is the daemon's live curator registry. // Backs GET /api/curators: registered names, per-curator health, and // recent activity. Optional: nil reports // an empty curator list rather than failing the dashboard. Curators CuratorStatus // Chat exposes the Gateway's wire-safe conversational contract. Optional: // the dashboard simply omits chat when it is nil. Chat *ChatService // Health runs the operator readiness probes served by /health/detailed. // Optional: nil answers 503 rather than fabricating a report, so a // deployment that has not wired probes never looks healthy by accident. Health *health.Registry // ControlPlane is the State Store's versioned runtime administration // contract. The HTTP adapter supplies operator attribution; browser JSON // never carries actor, source, or request IDs. ControlPlane controlpb.ControlPlaneServiceClient Identities identity.Repository // Packages is the State Store's installed-package surface, behind the // extensions page. Nil answers 503. Packages storepkg.Installations // ApplyStatus reports which control-plane resource version each process // is running. Optional: nil renders an empty page rather than failing the // dashboard. ApplyStatus storecontract.ApplyStatusStore // Alerts lists and dismisses the caller's org's operator alerts. Nil // answers 503. Alerts AlertSource // Presence lists every service instance's record, behind the services // card. Nil answers 503. Presence storecontract.PresenceStore // Refusals counts the events the network rules refused, per source. Refusals storecontract.CaptureRefusalStore // Policies is the stored access policy chain, behind the policies page. // Nil answers 503. Policies access.PolicyStore // DenialLister lists the caller's org's recorded denials, behind the // denials page. Nil answers 503. DenialLister access.DenialStore // Audit is the org-scoped audit feed, behind the audit page and the live // tail. Nil answers 503 on every audit route. Audit audit.Store // now is the clock applyState reads staleness against. Nil means // time.Now; tests set it to pin a record's age. now func() time.Time // Token gates access. Empty means no check, which is how loopback binds // stay frictionless -- see IsLoopback. Token string // Authenticate resolves a presented credential to an identity. Non-nil // replaces the shared token. Authenticate func(context.Context, string) (identity.Identity, error) AuthenticateBrowser func(context.Context, string) (identity.Identity, error) // PersonalTokens manages the signed-in person's API tokens. Nil answers // Unavailable. PersonalTokens identity.PersonalTokens // Login drives the provider's browser sign-in. Nil removes the sign-in // routes. Login identity.LoginFlow // Access evaluates the policy chain, Principals builds the request principal // and Denials records refusals. All three or none; a nil or unready chain // refuses every gated request. Access Chain Principals access.PrincipalSource Denials access.DenialRecorder // Subjects binds a provider subject to an identity, and Issuer is the // provider those subjects are asserted under. Nil or empty answers the // add-member route Unavailable. Subjects identity.SubjectBinding Issuer string // Instance names this deployment among others on the same host. It // prefixes the cookie names and is shown in the dashboard when it is not // the default. Instance string // Models answers which model aliases the caller's org may use. Optional: // nil leaves model readiness out of the setup checklist. Models ModelReader // Orgs serves the org pages: the caller's org, its workspaces, members and // agent assignments. Nil answers the org routes Unavailable. Orgs org.API // Events publishes operator actions so they reach the task timeline and // the live activity stream. Optional: nil means the action is recorded // in the store but invisible to anyone watching. Events EventPublisher // Captures backs the dashboard's read of captured events: the // GET /api/captures list and the mapping preview's by-ID scan. // Optional: nil makes the list // answer {"enabled": false} rather than the dashboard failing to start. Captures storecontract.CaptureStore // CaptureMaxEvents is the operator's configured [capture] max_events, // used to bound captureByID's scan window (api_mapping.go). // CaptureIntake is the write half's mount. CaptureMaxEvents int // CaptureIntake serves unauthenticated POST /webhooks/capture/{source}. Nil // removes the route. CaptureIntake http.Handler // Mappings persists payload field mappings. // Optional: nil makes every /api/mappings route answer 503 rather than // the dashboard failing to start. Mappings storecontract.MappingStore // EventTypes persists event types. Optional: // nil reports the inspector's event types as disabled. EventTypes storecontract.EventTypeStore // Bindings persists playbook bindings: matcher + mapping + workflow // triples that turn a captured webhook into an archie task. // Optional: nil makes every // /api/bindings route answer 503 rather than the dashboard failing to start. Bindings storecontract.BindingStore // Dispatches reads the binding dispatch ledger. Nil answers the dispatch // routes 503 and lists bindings without their last outcome. Dispatches storecontract.DispatchLedger // Schedules reads and edits schedules and their runs: every schedule to // the system org, only the acting org's own to any other. Nil answers the // /api/schedules routes 503. Schedules ScheduleStore // Sources persists capture sources and their signing setting. // Optional: nil makes every // /api/sources route answer 503 and marks no binding unsigned. Sources storecontract.SourceStore // TelegramUpdateReportPath and TelegramUpdateChatID route a dashboard // update's post-restart report to Telegram. Either empty uses // UpdateReportPath. TelegramUpdateReportPath string TelegramUpdateChatID int64 // UpdateReportPath is where the update watchdog leaves a dashboard-initiated // update's outcome for relay on next boot. Empty disables it. UpdateReportPath string // RunningVersions reports, per component ID (see releaseupdate.Report.Verify), // the version that component reports for itself right now. Optional: // nil leaves every claim in a relayed update report Unverified rather // than Confirmed. RunningVersions func() map[string]string // TrustForwardedHeaders controls whether X-Forwarded-Proto and // X-Forwarded-Host are trusted when validating Origin on mutating // requests. When false, Origin scheme must match the direct connection (r.TLS). // When Cfg is present, Cfg.Get().Web.TrustForwardedHeaders is also checked. TrustForwardedHeaders bool mu sync.Mutex conns map[*liveSubscriber]struct{} latest map[string]liveUpdate } // secureRequest reports whether the browser reached the dashboard over HTTPS, // directly or through a trusted proxy that terminates TLS. func (s *Server) secureRequest(r *http.Request) bool { scheme, _ := s.expectedOrigin(r) return scheme == "https" } func (s *Server) trustForwardedHeaders() bool { if s == nil { return false } return s.TrustForwardedHeaders } // EventPublisher accepts events for the store and the live stream. The bus // in cmd/archied satisfies it. type EventPublisher interface { Publish(events.Event) } // Broadcast delivers a persisted task event through the shared stream hub. func (s *Server) Broadcast(e events.Event) { s.publish(liveUpdate{topic: "tasks", data: e}, "") } func (s *Server) registerCoreRoutes(mux *http.ServeMux) { mux.HandleFunc("GET /api/summary", s.handleSummary) mux.HandleFunc("GET /api/usage", s.handleUsage) mux.HandleFunc("GET /api/setup", s.handleSetup) newWorkflowsAPI(s).register(mux) mux.HandleFunc("POST /api/control-plane/resources/repository-policies/check", s.handleRepositoryCheck) mux.HandleFunc("GET /api/skills", instanceOnly(s.handleSkills)) mux.HandleFunc("GET /api/curators", instanceOnly(s.handleCurators)) mux.HandleFunc("GET /api/captures", s.handleCaptures) newSchedulesAPI(s).register(mux) newAuditAPI(s).register(mux) newAlertsAPI(s).register(mux) mux.HandleFunc("GET /api/channels", instanceOnly(s.handleChannels)) mux.HandleFunc("POST /api/channels/{id}/reload", instanceOnly(s.handleChannelReload)) mux.HandleFunc("GET /api/version", s.handleVersion) mux.HandleFunc("GET /api/capabilities", s.handleCapabilities) } func (s *Server) registerTaskRoutes(mux *http.ServeMux) { newTasksAPI(s).register(mux) } func (s *Server) registerMappingAndBindingRoutes(mux *http.ServeMux) { // Event types register unconditionally: the list answers {"enabled": false} // when the store is nil. Mappings and sources mount a 503 stub otherwise. newEventTypesAPI(s).register(mux) if s.Mappings == nil { for _, p := range mappingsRoutes { mux.HandleFunc(p, notConfigured("mappings not configured")) } } else { newMappingsAPI(s).register(mux) } // The bindings module owns its routes and registers itself when the store // is configured; the stub keeps the 503 "not configured" answers otherwise. if s.Bindings == nil { for _, p := range bindingsRoutes { mux.HandleFunc(p, notConfigured("bindings not configured")) } } else { newBindingsAPI(s).register(mux) } mux.HandleFunc("GET /api/captures/{id}/dispatches", s.handleDispatches(func(id string) (storecontract.DispatchFilter, bool) { return storecontract.DispatchFilter{CaptureID: id}, id != "" })) mux.HandleFunc("GET /api/tasks/{id}/dispatches", s.handleDispatches(func(id string) (storecontract.DispatchFilter, bool) { taskID, err := strconv.ParseInt(id, 10, 64) return storecontract.DispatchFilter{TaskID: taskID}, err == nil && taskID > 0 })) if s.Sources == nil { for _, p := range sourcesRoutes { mux.HandleFunc(p, notConfigured("sources not configured")) } } else { newSourcesAPI(s).register(mux) } } func (s *Server) registerConfigAndLogRoutes(mux *http.ServeMux) { newExtensionsAPI(s).register(mux) mux.HandleFunc("GET /api/control-plane/apply-status", instanceOnly(s.handleApplyStatus)) mux.HandleFunc("GET /api/services", instanceOnly(s.handleServices)) newAccessAPI(s).register(mux) newControlPlaneAPI(s).register(mux) newLogsAPI(s).register(mux) newOrgsAPI(s).register(mux) newIdentitiesAPI(s).register(mux) mux.HandleFunc("PUT /api/orgs/current", s.handleOrgSelect) mux.HandleFunc("GET /api/config", instanceOnly(s.handleConfig)) mux.HandleFunc("GET /api/secret-engines", instanceOnly(s.handleSecretEngines)) mux.HandleFunc("POST /api/secret-references/check", instanceOnly(s.handleSecretCheck)) } func (s *Server) registerChatRoutes(mux *http.ServeMux) { newChatAPI(s).register(mux) } func (s *Server) Handler() http.Handler { mux := http.NewServeMux() s.registerCoreRoutes(mux) s.registerTaskRoutes(mux) s.registerMappingAndBindingRoutes(mux) s.registerConfigAndLogRoutes(mux) s.registerChatRoutes(mux) mux.HandleFunc("GET "+healthDetailedRoute, instanceOnly(s.handleHealthDetailed)) mux.HandleFunc("GET /api/stream", s.handleSSE) mux.Handle("GET /", s.assets()) top := http.NewServeMux() s.registerAccountRoutes(top, mux) top.HandleFunc("GET /healthz", s.handleHealthz) top.HandleFunc("GET /health", s.handleHealth) // The sign-in routes sit on the bypass mux because they are how a caller // becomes authenticated: gating them behind the credential they obtain would // make signing in impossible. if s.Login != nil { top.HandleFunc(loginRoute, s.handleLogin) top.HandleFunc(loginCallbackRoute, s.handleCallback) } if s.CaptureIntake != nil { // captureintake.Path is the single spelling of this route: the receiver // owns the route's semantics, so mounting re-spells nothing and a rename // there cannot silently unmount here. top.Handle(captureintake.Path, s.CaptureIntake) } // The chain runs after the credential check and before any handler: the // principal exists only once the credential resolved authenticated := s.requireToken(s.authorize(telemetry.Routed(mux))) top.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if s.Accounts != nil && r.Method == http.MethodGet && !strings.HasPrefix(r.URL.Path, "/api/") && r.URL.Path != healthDetailedRoute { s.assets().ServeHTTP(w, r) return } authenticated.ServeHTTP(w, r) })) return top } // handleHealthz is the unauthenticated liveness probe the update watchdog // polls. func (s *Server) handleHealthz(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusOK) _, _ = w.Write([]byte("ok")) } // assets serves the embedded dashboard, falling back to index.html so client // routes deep-link correctly. An unserved /api path is a 404, never the page. // Under the no_ui build tag the assets are absent and a plain explanation is // served instead of a confusing 404. func (s *Server) assets() http.Handler { if ui.DistDirFS == nil { return http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { http.Error(w, "dashboard not built into this binary (no_ui)", http.StatusNotFound) }) } files := http.FileServerFS(ui.DistDirFS) return gzhttp.GzipHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if strings.HasPrefix(r.URL.Path, "/api/") { http.Error(w, "this archied does not serve "+r.URL.Path, http.StatusNotFound) return } if _, err := fs.Stat(ui.DistDirFS, trimLeadingSlash(r.URL.Path)); err != nil { r = r.Clone(r.Context()) r.URL.Path = "/" } // Asset names carry a content hash, so a cached copy never goes stale; // index.html names the current hashes and must always be revalidated. if strings.HasPrefix(r.URL.Path, "/assets/") { w.Header().Set("Cache-Control", "public, max-age=31536000, immutable") } else { w.Header().Set("Cache-Control", "no-cache") } files.ServeHTTP(w, r) })) } func trimLeadingSlash(p string) string { if len(p) > 0 && p[0] == '/' { return p[1:] } if p == "" { return "." } return p } // healthDetailedRoute is the instance health report. const healthDetailedRoute = "/health/detailed" // Chain is the policy chain the dashboard gates on. Ready is false until the // stored policies have loaded. type Chain interface { access.Authorizer Ready() bool } func writeJSON(w http.ResponseWriter, v any) { w.Header().Set("Content-Type", "application/json") _ = json.NewEncoder(w).Encode(v) } // decodeBody decodes the JSON request body into a T, answering 400 itself // when the body is invalid. func decodeBody[T any](w http.ResponseWriter, r *http.Request) (T, bool) { var v T if err := json.NewDecoder(r.Body).Decode(&v); err != nil { http.Error(w, "invalid request body: "+err.Error(), http.StatusBadRequest) return v, false } return v, true }