Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

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.md
index 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 provider
diff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.md
index 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 ceiling
The canonical audit exporter and summary reader request at most 10,001 matching
diff --git a/internal/api/agent_recent_changes.go b/internal/api/agent_recent_changes.go
index 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 when
diff --git a/internal/api/agent_recent_changes_authority_test.go b/internal/api/agent_recent_changes_authority_test.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index 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.