Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Retain current reader authority for requested history
pulse-triage[bot]e30c14bffdf9
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.mdindex dbde340455..e854c36eb5 100644--- a/docs/release-control/v6/internal/subsystems/api-contracts.md+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md@@ -5658,6 +5658,35 @@ auto-register mutation boundary.## Current State+### Requested change history retains its disclosure authority++`GET /api/agent/changes` retains the admitted token identity, principal,+selected organisation and `monitoring:read` scope until each response write.+A projection admitted with command-reading authority must also retain+`ai:execute`; these are cumulative requirements, not scope alternatives.+Before any result is committed, withdrawal produces generic `401`, not history,+handler-specific headers or successful empty JSON. After an admitted prefix,+withdrawal only stops later bytes. An already-admitted write may be in flight.++The existing synchronous response guards retain session-instance withdrawal+checks and non-executable JSON/plain-text transport without buffering payloads,+replacing the request context, cancelling independent work or retrying reads.+A fresh monitoring-only read remains valid and command-redacted; adding command+scope during an old read does not unredact that read. Unrelated scope changes,+explicit required scopes replacing wildcard, and unchanged session/proxy reads+remain valid. Stored history, retention, event kinds, collection, the capability+manifest and all other routes are unchanged. The history-success activity+observer remains outside the disclosure guard so a refused response is not+counted as a successful history read.++Registered `agent_recent_changes_authority_test.go` suspends the normal inventory+lookup on the full authenticated HTTP route, with real history store reads,+independent controls, both token headers, token/scope/organisation/principal+withdrawal, actual persisted logout, session replacement/expiry and intact+canonical evidence. This external-agent endpoint has no frontend API consumer;+no rendered fields or first-party journeys change.++### Tenant agent install tokens authenticate header-less agents`POST /api/agent-install-command` in a tenant organization (every providerdiff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.mdindex 3550ffcbbe..22d1f6bb23 100644--- a/docs/release-control/v6/internal/subsystems/security-privacy.md+++ b/docs/release-control/v6/internal/subsystems/security-privacy.md@@ -1723,6 +1723,35 @@ database grew past it. `TestSQLiteLoggerUsesSharedPageCacheBound` and## Current State+### Requested change history retains its disclosure authority++`GET /api/agent/changes` retains the admitted token identity, principal,+selected organisation and `monitoring:read` scope until each response write.+A projection admitted with command-reading authority must also retain+`ai:execute`; these are cumulative requirements, not scope alternatives.+Before any result is committed, withdrawal produces generic `401`, not history,+handler-specific headers or successful empty JSON. After an admitted prefix,+withdrawal only stops later bytes. An already-admitted write may be in flight.++The existing synchronous response guards retain session-instance withdrawal+checks and non-executable JSON/plain-text transport without buffering payloads,+replacing the request context, cancelling independent work or retrying reads.+A fresh monitoring-only read remains valid and command-redacted; adding command+scope during an old read does not unredact that read. Unrelated scope changes,+explicit required scopes replacing wildcard, and unchanged session/proxy reads+remain valid. Stored history, retention, event kinds, collection, the capability+manifest and all other routes are unchanged. The history-success activity+observer remains outside the disclosure guard so a refused response is not+counted as a successful history read.++Registered `agent_recent_changes_authority_test.go` suspends the normal inventory+lookup on the full authenticated HTTP route, with real history store reads,+independent controls, both token headers, token/scope/organisation/principal+withdrawal, actual persisted logout, session replacement/expiry and intact+canonical evidence. This external-agent endpoint has no frontend API consumer;+no rendered fields or first-party journeys change.++### Synchronous audit recovery reads have an actual row ceilingThe canonical audit exporter and summary reader request at most 10,001 matchingdiff --git a/internal/api/agent_recent_changes.go b/internal/api/agent_recent_changes.goindex ea929dabea..e732f996b2 100644--- a/internal/api/agent_recent_changes.go+++ b/internal/api/agent_recent_changes.go@@ -8,9 +8,28 @@ import ("time""github.com/rcourtman/pulse-go-rewrite/internal/agentcapabilities"+ "github.com/rcourtman/pulse-go-rewrite/internal/config"unified "github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources")+// History can wait for its store and current inventory after authentication.+// Keep both the read authority and any command-disclosure authority used by+// that projection until the response is written. Do not refresh an old request+// into a different reader or retry its lookup with wider/different authority.+func retainAgentHistoryResponseAuthority(cfg *config.Config, next http.HandlerFunc) http.HandlerFunc {+ read := retainTokenResponseAuthority(cfg, config.ScopeMonitoringRead, false, next)+ // Compose the existing synchronous guards: these scopes are BOTH required+ // for a command-bearing projection, not interchangeable alternatives.+ commandRead := retainTokenResponseAuthority(cfg, config.ScopeAIExecute, false, read)+ return func(w http.ResponseWriter, r *http.Request) {+ if token := getAPITokenRecordFromRequest(r); token != nil && token.HasScope(config.ScopeAIExecute) {+ commandRead(w, r)+ return+ }+ read(w, r)+ }+}+// AgentRecentChange is one observed resource change as an agent reads it:// the canonical change record plus the resource's current name and type,// which the store does not keep. ResourceName and ResourceType are empty whendiff --git a/internal/api/agent_recent_changes_authority_test.go b/internal/api/agent_recent_changes_authority_test.gonew file mode 100644index 0000000000..d2e2b32379--- /dev/null+++ b/internal/api/agent_recent_changes_authority_test.go@@ -0,0 +1,209 @@+package api++import (+ "encoding/json"+ "io"+ "net/http"+ "net/http/httptest"+ "strings"+ "sync"+ "sync/atomic"+ "testing"+ "time"++ "github.com/rcourtman/pulse-go-rewrite/internal/agentcapabilities"+ "github.com/rcourtman/pulse-go-rewrite/internal/config"+ "github.com/rcourtman/pulse-go-rewrite/internal/models"+ unified "github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources"+)++const historyAuthorityToken = "history-authority-primary.12345678"+const historyAuthorityControl = "history-authority-control.12345678"++// Hold the normal inventory/name lookup, after the actual history store read.+// No database locks, clock sleeps, auth stubs or production hooks are needed.+type historyAuthorityProvider struct {+ entered chan struct{}+ release chan struct{}+ once sync.Once+ calls atomic.Int32+}++func (p *historyAuthorityProvider) ReadSnapshot() models.StateSnapshot {+ if p.calls.Add(1) <= 2 {+ p.entered <- struct{}{}+ <-p.release+ }+ return models.StateSnapshot{}+}++func (p *historyAuthorityProvider) unblock() { p.once.Do(func() { close(p.release) }) }++type historyAuthorityFixture struct {+ router *Router+ server *httptest.Server+ provider *historyAuthorityProvider+ store unified.ResourceStore+ original string+}++func newHistoryAuthorityFixture(t *testing.T, scopes []string) *historyAuthorityFixture {+ t.Helper()+ t.Setenv("PULSE_AUTH_BYPASS", "false")+ cfg := newTestConfigWithTokens(t,+ newTokenRecord(t, historyAuthorityToken, scopes, nil),+ newTokenRecord(t, historyAuthorityControl, []string{config.ScopeMonitoringRead, config.ScopeAIExecute}, nil),+ )+ cfg.AuthUser, cfg.AuthPass = "operator", "fixture-nonempty-hash"+ cfg.ProxyAuthSecret, cfg.ProxyAuthUserHeader = "history-authority-proxy-secret", "X-Remote-User"+ router := NewRouter(cfg, nil, nil, nil, nil, "test")+ t.Cleanup(router.ShutdownResourceStores)+ provider := &historyAuthorityProvider{entered: make(chan struct{}, 2), release: make(chan struct{})}+ router.resourceHandlers.SetStateProvider(provider)+ store, err := router.resourceHandlers.getStore("default")+ if err != nil {+ t.Fatal(err)+ }+ for _, change := range []*unified.ResourceChange{+ unified.BuildCommandExecutionChange("vm:101", "alert-1", "operator", recentChangePrivateText, true, recentChangePrivateText, nil),+ unified.BuildRunbookExecutionChange("vm:101", "alert-1", "operator", "rb-1", recentChangePrivateText, "partial", false, recentChangePrivateText, nil),+ } {+ if err := store.RecordChange(*change); err != nil {+ t.Fatal(err)+ }+ }+ f := &historyAuthorityFixture{router: router, provider: provider, store: store}+ f.original = f.stored(t)+ f.server = httptest.NewServer(router.Handler())+ t.Cleanup(f.server.Close)+ // Release before closing the HTTP server even when a test fails early.+ t.Cleanup(provider.unblock)+ return f+}++func (f *historyAuthorityFixture) stored(t *testing.T) string {+ t.Helper()+ changes, err := f.store.GetRecentChangesFiltered("", time.Time{}, 50, unified.ResourceChangeFilters{})+ if err != nil {+ t.Fatal(err)+ }+ body, err := json.Marshal(changes)+ if err != nil {+ t.Fatal(err)+ }+ return string(body)+}++func (f *historyAuthorityFixture) request(t *testing.T, raw, transport string) *http.Request {+ t.Helper()+ req, err := http.NewRequest(http.MethodGet, f.server.URL+agentcapabilities.RecentChangesCapabilityPath, nil)+ if err != nil {+ t.Fatal(err)+ }+ switch transport {+ case "header":+ req.Header.Set("X-API-Token", raw)+ case "bearer":+ req.Header.Set("Authorization", "Bearer "+raw)+ case "session":+ req.AddCookie(&http.Cookie{Name: cookieNameSession, Value: raw})+ case "proxy":+ req.Header.Set("X-Proxy-Secret", f.router.config.ProxyAuthSecret)+ req.Header.Set("X-Remote-User", "operator")+ default:+ t.Fatalf("unknown history fixture transport %q", transport)+ }+ return req+}++type historyAuthorityResult struct {+ response *http.Response+ err error+}++func (f *historyAuthorityFixture) begin(t *testing.T, raw, transport string) <-chan historyAuthorityResult {+ t.Helper()+ req := f.request(t, raw, transport)+ result := make(chan historyAuthorityResult, 1)+ go func() {+ response, err := f.server.Client().Do(req)+ result <- historyAuthorityResult{response, err}+ }()+ select {+ case <-f.provider.entered:+ case got := <-result:+ if got.response != nil {+ got.response.Body.Close()+ }+ t.Fatalf("history returned before its inventory gate: %v", got.err)+ case <-time.After(5 * time.Second):+ t.Fatal("history did not reach its inventory gate")+ }+ return result+}++func readHistoryAuthorityResult(t *testing.T, result <-chan historyAuthorityResult, status int, private bool) {+ t.Helper()+ var got historyAuthorityResult+ select {+ case got = <-result:+ case <-time.After(5 * time.Second):+ t.Fatal("history did not finish after inventory release")+ }+ if got.err != nil {+ t.Fatal(got.err)+ }+ defer got.response.Body.Close()+ body, err := io.ReadAll(got.response.Body)+ if err != nil {+ t.Fatal(err)+ }+ if got.response.StatusCode != status {+ t.Errorf("history status = %d, want %d (execution detail present: %t)", got.response.StatusCode, status, strings.Contains(string(body), recentChangePrivateText))+ }+ if status != http.StatusOK {+ if strings.Contains(string(body), recentChangePrivateText) || !strings.Contains(string(body), "Authentication required") || strings.Contains(got.response.Header.Get("Content-Type"), "application/json") {+ t.Error("withdrawn history disclosed data or implied successful empty JSON")+ }+ return+ }+ var history AgentRecentChanges+ if json.Unmarshal(body, &history) != nil || history.Count != 2 || len(history.Changes) != 2 || history.Truncated {+ t.Error("authorised history lost its existing JSON envelope")+ }+ if strings.Contains(string(body), recentChangePrivateText) != private {+ t.Error("history command visibility differs from admitted authority")+ }+ for _, change := range history.Changes {+ if change.CommandRedacted == private || change.Metadata[unified.MetadataAlertIdentifier] != "alert-1" {+ t.Error("history lost its redaction marker or safe attribution")+ }+ }+}++func TestAgentHistoryWithdrawnSessionCannotDisclose(t *testing.T) {+ for _, change := range []string{"logout", "expired", "replaced", "principal", "store"} {+ t.Run(change, func(t *testing.T) {+ f := newHistoryAuthorityFixture(t, []string{config.ScopeMonitoringRead})+ const raw = "history-authority-session"+ GetSessionStore().CreateSession(raw, time.Hour, "fixture", "127.0.0.1", f.router.config.AuthUser)+ t.Cleanup(func() { GetSessionStore().DeleteSession(raw) })+ control := f.begin(t, historyAuthorityControl, "header")+ primary := f.begin(t, raw, "session")+ switch change {+ case "logout":+ logoutReadSession(t, f.server.URL, raw)+ case "store":+ InitSessionStore(t.TempDir())+ default:+ mutateReadSession(raw, change)+ }+ f.provider.unblock()+ readHistoryAuthorityResult(t, primary, http.StatusUnauthorized, false)+ readHistoryAuthorityResult(t, control, http.StatusOK, true)+ if f.stored(t) != f.original {+ t.Error("session withdrawal rewrote canonical history")+ }+ })+ }+}diff --git a/internal/api/contract_test.go b/internal/api/contract_test.goindex 40d0eba274..6e1122df4b 100644--- a/internal/api/contract_test.go+++ b/internal/api/contract_test.go@@ -29193,3 +29193,51 @@ func TestContract_BackupJobsPayloadJSONSnapshot(t *testing.T) {assertJSONSnapshot(t, got, want)}++func TestAgentHistoryWithdrawnTokenCannotDisclose(t *testing.T) {+ for _, transport := range []string{"header", "bearer"} {+ for _, change := range []string{"revoked", "expired", "monitoring_removed", "execution_removed", "org_removed", "credential_replaced", "principal_replaced", "invalid_role"} {+ t.Run(transport+"/"+change, func(t *testing.T) {+ f := newHistoryAuthorityFixture(t, []string{config.ScopeMonitoringRead, config.ScopeAIExecute})+ control := f.begin(t, historyAuthorityControl, "header")+ primary := f.begin(t, historyAuthorityToken, transport)+ config.Mu.Lock()+ record := &f.router.config.APITokens[0]+ switch change {+ case "revoked":+ f.router.config.RemoveAPIToken(record.ID)+ case "expired":+ past := time.Now().Add(-time.Second)+ record.ExpiresAt = &past+ case "monitoring_removed":+ record.Scopes = []string{config.ScopeAIExecute}+ case "execution_removed":+ record.Scopes = []string{config.ScopeMonitoringRead}+ case "org_removed":+ record.OrgIDs = []string{"other-org"}+ case "credential_replaced":+ record.ID = "replacement-history-credential"+ case "principal_replaced":+ record.Metadata = map[string]string{apiTokenMetadataOwnerUserID: "replacement-history-principal"}+ case "invalid_role":+ record.Metadata = map[string]string{authpkg.RuntimeRoleMetadataKey: authpkg.RuntimeRoleActionRunner}+ }+ config.Mu.Unlock()+ f.provider.unblock()+ readHistoryAuthorityResult(t, primary, http.StatusUnauthorized, false)+ readHistoryAuthorityResult(t, control, http.StatusOK, true)+ if change == "execution_removed" {+ // No wider grant is needed to resume: a NEW monitoring read is+ // valid and redacted. The old full projection cannot be reused.+ response, err := f.server.Client().Do(f.request(t, historyAuthorityToken, transport))+ fresh := make(chan historyAuthorityResult, 1)+ fresh <- historyAuthorityResult{response, err}+ readHistoryAuthorityResult(t, fresh, http.StatusOK, false)+ }+ if f.stored(t) != f.original {+ t.Error("withdrawal or read rewrote canonical history")+ }+ })+ }+ }+}diff --git a/internal/api/route_inventory_test.go b/internal/api/route_inventory_test.goindex b57fb27b8c..01c8fbfdc6 100644--- a/internal/api/route_inventory_test.go+++ b/internal/api/route_inventory_test.go@@ -977,3 +977,44 @@ func TestAgentEventTokenLifecycleDeleteThroughHTTP(t *testing.T) {t.Fatalf("revoked reconnect = %d, want 401", resp.StatusCode)}}++func TestAgentHistoryPreservesAdmittedReaders(t *testing.T) {+ for _, kind := range []string{"monitoring", "executor", "wildcard", "scope_added", "session", "proxy"} {+ t.Run(kind, func(t *testing.T) {+ scopes := []string{config.ScopeMonitoringRead, config.ScopeSettingsRead}+ private := kind != "monitoring" && kind != "scope_added"+ if kind == "executor" {+ scopes = append(scopes, config.ScopeAIExecute)+ } else if kind == "wildcard" {+ scopes = []string{config.ScopeWildcard}+ }+ f := newHistoryAuthorityFixture(t, scopes)+ raw, transport := historyAuthorityToken, "bearer"+ if kind == "session" {+ raw, transport = "history-authority-unchanged-session", "session"+ GetSessionStore().CreateSession(raw, time.Hour, "fixture", "127.0.0.1", f.router.config.AuthUser)+ t.Cleanup(func() { GetSessionStore().DeleteSession(raw) })+ } else if kind == "proxy" {+ transport = "proxy"+ }+ control := f.begin(t, historyAuthorityControl, "header")+ primary := f.begin(t, raw, transport)+ config.Mu.Lock()+ if kind == "session" || kind == "proxy" {+ f.router.config.RemoveAPIToken(f.router.config.APITokens[0].ID)+ } else {+ f.router.config.APITokens[0].Scopes = []string{config.ScopeMonitoringRead}+ if private || kind == "scope_added" {+ f.router.config.APITokens[0].Scopes = append(f.router.config.APITokens[0].Scopes, config.ScopeAIExecute)+ }+ }+ config.Mu.Unlock()+ f.provider.unblock()+ readHistoryAuthorityResult(t, primary, http.StatusOK, private)+ readHistoryAuthorityResult(t, control, http.StatusOK, true)+ if f.stored(t) != f.original {+ t.Error("read rewrote canonical history")+ }+ })+ }+}diff --git a/internal/api/router_routes_monitoring.go b/internal/api/router_routes_monitoring.goindex 1b0fc91bb5..33ac19ef32 100644--- a/internal/api/router_routes_monitoring.go+++ b/internal/api/router_routes_monitoring.go@@ -126,7 +126,7 @@ func (r *Router) registerMonitoringResourceRoutes(// triage view above, which answers "where do I look now?".r.mux.HandleFunc(agentcapabilities.RecentChangesCapabilityPath, RequireAuth(r.config, RequireScope(config.ScopeMonitoringRead, r.withExternalAgentCapabilityActivity(agentcapabilities.ListRecentChangesCapabilityName,- r.agentContextHandler.HandleRecentChanges,+ retainAgentHistoryResponseAuthority(r.config, r.agentContextHandler.HandleRecentChanges),))))// Agent-consumable metric history — "how did it move?" for one resource,// served by the same history read the charts use.