Merge remote-tracking branch 'origin/main' into refactor/permissions-manager

2026-10-27 14:59:09 +01:00 · 2026-09-11 13:55:02 +02:00
parent 9b10d74ab8 0fac1ee638
commit 18c7917c6d
2126 changed files with 284567 additions and 42026 deletions
@@ -0,0 +1,134 @@
+package handlers
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+// addAccessLogEndpoints registers the read-only, server-side-filtered
+// agent-network access-log listing and the aggregated usage overview.
+func (h *handler) addAccessLogEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/access-logs", h.listAccessLogs).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/access-log-sessions", h.listAccessLogSessions).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/usage/overview", h.getUsageOverview).Methods("GET", "OPTIONS")
+}
+
+func (h *handler) getUsageOverview(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	// Reuse the access-log filter for the shared date/user/group/provider/model
+	// params; pagination/sort/search are irrelevant for an aggregate.
+	var filter types.AgentNetworkAccessLogFilter
+	if err := filter.ParseFromRequest(r); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	// Bound the aggregation window so an unbounded or over-wide query can't load
+	// an account's entire usage history into memory.
+	filter.ApplyUsageOverviewBounds(time.Now())
+	granularity := types.ParseUsageGranularity(r.URL.Query().Get("granularity"))
+
+	buckets, err := h.manager.GetUsageOverview(r.Context(), userAuth.AccountId, userAuth.UserId, filter, granularity)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := make([]api.AgentNetworkUsageBucket, 0, len(buckets))
+	for _, b := range buckets {
+		out = append(out, b.ToAPIResponse())
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+func (h *handler) listAccessLogs(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var filter types.AgentNetworkAccessLogFilter
+	if err := filter.ParseFromRequest(r); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	rows, total, err := h.manager.ListAccessLogs(r.Context(), userAuth.AccountId, userAuth.UserId, filter)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	data := make([]api.AgentNetworkAccessLog, 0, len(rows))
+	for _, row := range rows {
+		data = append(data, row.ToAPIResponse())
+	}
+
+	pageSize := filter.GetLimit()
+	totalPages := 0
+	if pageSize > 0 {
+		totalPages = int((total + int64(pageSize) - 1) / int64(pageSize))
+	}
+
+	util.WriteJSONObject(r.Context(), w, api.AgentNetworkAccessLogsResponse{
+		Data:         data,
+		Page:         filter.Page,
+		PageSize:     pageSize,
+		TotalRecords: int(total),
+		TotalPages:   totalPages,
+	})
+}
+
+// listAccessLogSessions returns the access logs grouped by session: the page
+// unit is a session (total counts sessions), each carrying an aggregate summary
+// and its ordered entries. Accepts the same filters as listAccessLogs.
+func (h *handler) listAccessLogSessions(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var filter types.AgentNetworkAccessLogFilter
+	if err := filter.ParseFromRequest(r); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	sessions, total, err := h.manager.ListAccessLogSessions(r.Context(), userAuth.AccountId, userAuth.UserId, filter)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	data := make([]api.AgentNetworkAccessLogSession, 0, len(sessions))
+	for _, sess := range sessions {
+		data = append(data, sess.ToAPIResponse())
+	}
+
+	pageSize := filter.GetLimit()
+	totalPages := 0
+	if pageSize > 0 {
+		totalPages = int((total + int64(pageSize) - 1) / int64(pageSize))
+	}
+
+	util.WriteJSONObject(r.Context(), w, api.AgentNetworkAccessLogSessionsResponse{
+		Data:         data,
+		Page:         filter.Page,
+		PageSize:     pageSize,
+		TotalRecords: int(total),
+		TotalPages:   totalPages,
+	})
+}
@@ -0,0 +1,56 @@
+package handlers
+
+import (
+	"net/http"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+// addAgentConfigEndpoints registers the self-service agent-config route.
+// It is available to every authenticated user regardless of role: the
+// providers in the response are scoped strictly to the caller, which is
+// tighter than any role gate could be. The caller's own usage and requests are served by
+// the regular usage/logs endpoints, which self-scope for callers without
+// the account-wide grants.
+func (h *handler) addAgentConfigEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/agent-config", h.getAgentConfig).Methods("GET", "OPTIONS")
+}
+
+func (h *handler) getAgentConfig(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	setup, err := h.manager.GetAgentConfigForUser(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, agentConfigToAPI(setup))
+}
+
+func agentConfigToAPI(setup *types.AgentConfig) api.AgentNetworkAgentConfig {
+	providers := make([]api.AgentNetworkAgentConfigProvider, 0, len(setup.Providers))
+	for _, p := range setup.Providers {
+		providers = append(providers, api.AgentNetworkAgentConfigProvider{
+			Name:             p.Name,
+			CatalogId:        p.CatalogID,
+			ApiFlavor:        p.APIFlavor,
+			AllModelsAllowed: p.AllModelsAllowed,
+			Models:           p.Models,
+		})
+	}
+	return api.AgentNetworkAgentConfig{
+		Configured: setup.Configured,
+		Endpoint:   setup.Endpoint,
+		Providers:  providers,
+	}
+}
@@ -0,0 +1,172 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+// addBudgetRuleEndpoints registers the account-level budget rule routes.
+func (h *handler) addBudgetRuleEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/budget-rules", h.getAllBudgetRules).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/budget-rules", h.createBudgetRule).Methods("POST", "OPTIONS")
+	router.HandleFunc("/agent-network/budget-rules/{ruleId}", h.getBudgetRule).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/budget-rules/{ruleId}", h.updateBudgetRule).Methods("PUT", "OPTIONS")
+	router.HandleFunc("/agent-network/budget-rules/{ruleId}", h.deleteBudgetRule).Methods("DELETE", "OPTIONS")
+}
+
+func (h *handler) getAllBudgetRules(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	rules, err := h.manager.GetAllBudgetRules(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := make([]*api.AgentNetworkBudgetRule, 0, len(rules))
+	for _, rule := range rules {
+		out = append(out, rule.ToAPIResponse())
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+func (h *handler) getBudgetRule(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	ruleID := mux.Vars(r)["ruleId"]
+	if ruleID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "budget rule ID is required"), w)
+		return
+	}
+
+	rule, err := h.manager.GetBudgetRule(r.Context(), userAuth.AccountId, userAuth.UserId, ruleID)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, rule.ToAPIResponse())
+}
+
+func (h *handler) createBudgetRule(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkBudgetRuleRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validateBudgetRule(&req); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	rule := types.NewAccountBudgetRule(userAuth.AccountId)
+	rule.FromAPIRequest(&req)
+
+	created, err := h.manager.CreateBudgetRule(r.Context(), userAuth.UserId, rule)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, created.ToAPIResponse())
+}
+
+func (h *handler) updateBudgetRule(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	ruleID := mux.Vars(r)["ruleId"]
+	if ruleID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "budget rule ID is required"), w)
+		return
+	}
+
+	var req api.AgentNetworkBudgetRuleRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validateBudgetRule(&req); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	rule := &types.AccountBudgetRule{ID: ruleID, AccountID: userAuth.AccountId}
+	rule.FromAPIRequest(&req)
+
+	updated, err := h.manager.UpdateBudgetRule(r.Context(), userAuth.UserId, rule)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
+}
+
+func (h *handler) deleteBudgetRule(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	ruleID := mux.Vars(r)["ruleId"]
+	if ruleID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "budget rule ID is required"), w)
+		return
+	}
+
+	if err := h.manager.DeleteBudgetRule(r.Context(), userAuth.AccountId, userAuth.UserId, ruleID); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, util.EmptyObject{})
+}
+
+// validateBudgetRule rejects malformed budget rules. It reuses the policy limit
+// validation since the cap shape is identical, and rejects empty target entries.
+func validateBudgetRule(req *api.AgentNetworkBudgetRuleRequest) error {
+	if strings.TrimSpace(req.Name) == "" {
+		return status.Errorf(status.InvalidArgument, "name is required")
+	}
+	if req.TargetGroups != nil {
+		for _, id := range *req.TargetGroups {
+			if strings.TrimSpace(id) == "" {
+				return status.Errorf(status.InvalidArgument, "target_groups must not contain empty entries")
+			}
+		}
+	}
+	if req.TargetUsers != nil {
+		for _, id := range *req.TargetUsers {
+			if strings.TrimSpace(id) == "" {
+				return status.Errorf(status.InvalidArgument, "target_users must not contain empty entries")
+			}
+		}
+	}
+	return validatePolicyLimits(req.Limits)
+}
@@ -0,0 +1,131 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	agentNetworkTypes "github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+// TestBudgetRuleHandler_RoundTrip seeds a budget rule via the store and asserts
+// the GET wire shape carries targets and the reused PolicyLimits cap shape. The
+// create/update/delete success paths go through accountManager.StoreEvent which
+// this fixture doesn't wire — they are covered by the manager-level no-mock
+// test (TestAgentNetwork_BudgetRuleCRUD_RealManager).
+func TestBudgetRuleHandler_RoundTrip(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rule := &agentNetworkTypes.AccountBudgetRule{
+		ID:           "ainbud_test",
+		AccountID:    testAccountID,
+		Name:         "org-monthly",
+		Enabled:      true,
+		TargetGroups: []string{"grp-eng"},
+		TargetUsers:  []string{"user-alice"},
+		Limits: agentNetworkTypes.PolicyLimits{
+			TokenLimit:  agentNetworkTypes.PolicyTokenLimit{Enabled: true, GroupCap: 100000, UserCap: 10000, WindowSeconds: 2_592_000},
+			BudgetLimit: agentNetworkTypes.PolicyBudgetLimit{Enabled: true, GroupCapUsd: 500, WindowSeconds: 2_592_000},
+		},
+	}
+	require.NoError(t, f.store.SaveAgentNetworkBudgetRule(context.Background(), rule))
+
+	rec := f.do(t, http.MethodGet, "/agent-network/budget-rules/"+rule.ID, "")
+	require.Equal(t, http.StatusOK, rec.Code, "GET must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkBudgetRule
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, "org-monthly", got.Name, "name must round-trip")
+	assert.Equal(t, []string{"grp-eng"}, got.TargetGroups, "target groups must round-trip")
+	assert.Equal(t, []string{"user-alice"}, got.TargetUsers, "target users must round-trip")
+	assert.Equal(t, int64(100000), got.Limits.TokenLimit.GroupCap, "token group cap must round-trip")
+	assert.Equal(t, int64(2_592_000), got.Limits.BudgetLimit.WindowSeconds, "budget window must round-trip")
+}
+
+// TestBudgetRuleHandler_ListReturnsArray asserts the list endpoint returns a
+// JSON array (never null) for an account with no rules.
+func TestBudgetRuleHandler_ListReturnsArray(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodGet, "/agent-network/budget-rules", "")
+	require.Equal(t, http.StatusOK, rec.Code, "GET must succeed: %s", rec.Body.String())
+	assert.Equal(t, "[]", trimSpace(rec.Body.String()), "empty account must return an empty array, not null")
+}
+
+// TestBudgetRuleHandler_RejectsMissingName covers the validation path (which
+// runs before the manager call, so it works without a wired accountManager).
+func TestBudgetRuleHandler_RejectsMissingName(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	body := `{
+        "name": "",
+        "limits": {
+            "token_limit": {"enabled": false, "group_cap": 0, "user_cap": 0, "window_seconds": 0},
+            "budget_limit": {"enabled": false, "group_cap_usd": 0, "user_cap_usd": 0, "window_seconds": 0}
+        }
+    }`
+	rec := f.do(t, http.MethodPost, "/agent-network/budget-rules", body)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"missing name must be rejected as a validation error (not a route/auth 4xx): got %d body=%s", rec.Code, rec.Body.String())
+	assert.Contains(t, rec.Body.String(), "name",
+		"rejection body must name the offending field, proving the validation path: %s", rec.Body.String())
+}
+
+// TestBudgetRuleHandler_RejectsSubMinuteWindow proves budget rules reuse the
+// policy-limit validation (enabled limit needs window >= 60s).
+func TestBudgetRuleHandler_RejectsSubMinuteWindow(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	body := `{
+        "name": "bad-window",
+        "limits": {
+            "token_limit": {"enabled": true, "group_cap": 1000, "user_cap": 0, "window_seconds": 30},
+            "budget_limit": {"enabled": false, "group_cap_usd": 0, "user_cap_usd": 0, "window_seconds": 0}
+        }
+    }`
+	rec := f.do(t, http.MethodPost, "/agent-network/budget-rules", body)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"sub-minute window must be rejected as a validation error (not a route/auth 4xx): got %d body=%s", rec.Code, rec.Body.String())
+	assert.Contains(t, rec.Body.String(), "window_seconds",
+		"rejection body must name the offending window_seconds field, proving the validation path: %s", rec.Body.String())
+}
+
+// TestSettingsHandler_GetExposesCollectionToggles asserts the GET settings wire
+// shape carries the account-level collection toggles after a store seed.
+func TestSettingsHandler_GetExposesCollectionToggles(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	require.NoError(t, f.store.SaveAgentNetworkSettings(context.Background(), &agentNetworkTypes.Settings{
+		AccountID:              testAccountID,
+		Domain:                 "violet.eu.proxy.netbird.io",
+		ProxyAddress:           "eu.proxy.netbird.io",
+		EnableLogCollection:    true,
+		EnablePromptCollection: true,
+		RedactPii:              false,
+	}))
+
+	rec := f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code, "GET must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.True(t, got.EnableLogCollection, "log collection toggle must surface on the wire")
+	assert.True(t, got.EnablePromptCollection, "prompt collection toggle must surface on the wire")
+	assert.False(t, got.RedactPii, "redact toggle must surface its false value")
+	assert.Equal(t, "violet.eu.proxy.netbird.io", got.Endpoint, "endpoint stays computed from immutable cluster+subdomain")
+}
+
+func trimSpace(s string) string {
+	for len(s) > 0 && (s[len(s)-1] == '\n' || s[len(s)-1] == ' ' || s[len(s)-1] == '\t' || s[len(s)-1] == '\r') {
+		s = s[:len(s)-1]
+	}
+	for len(s) > 0 && (s[0] == '\n' || s[0] == ' ' || s[0] == '\t' || s[0] == '\r') {
+		s = s[1:]
+	}
+	return s
+}
@@ -0,0 +1,53 @@
+package handlers
+
+import (
+	"net/http"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+// addConsumptionEndpoints registers the read-only Agent Network
+// consumption listing — backs the dashboard's basic counter view.
+func (h *handler) addConsumptionEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/consumption", h.listConsumption).Methods("GET", "OPTIONS")
+}
+
+func (h *handler) listConsumption(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	rows, err := h.manager.ListConsumption(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := make([]api.AgentNetworkConsumption, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, consumptionToAPI(row))
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+func consumptionToAPI(c *types.Consumption) api.AgentNetworkConsumption {
+	windowStart := c.WindowStartUTC
+	updatedAt := c.UpdatedAt
+	return api.AgentNetworkConsumption{
+		DimensionKind:  api.AgentNetworkConsumptionDimensionKind(c.DimensionKind),
+		DimensionId:    c.DimensionID,
+		WindowSeconds:  c.WindowSeconds,
+		WindowStartUtc: windowStart,
+		TokensInput:    c.TokensInput,
+		TokensOutput:   c.TokensOutput,
+		CostUsd:        c.CostUSD,
+		UpdatedAt:      &updatedAt,
+	}
+}
@@ -0,0 +1,171 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+// addGuardrailEndpoints registers all Agent Network guardrail routes.
+func (h *handler) addGuardrailEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/guardrails", h.getAllGuardrails).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/guardrails", h.createGuardrail).Methods("POST", "OPTIONS")
+	router.HandleFunc("/agent-network/guardrails/{guardrailId}", h.getGuardrail).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/guardrails/{guardrailId}", h.updateGuardrail).Methods("PUT", "OPTIONS")
+	router.HandleFunc("/agent-network/guardrails/{guardrailId}", h.deleteGuardrail).Methods("DELETE", "OPTIONS")
+}
+
+func (h *handler) getAllGuardrails(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	guardrails, err := h.manager.GetAllGuardrails(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := make([]*api.AgentNetworkGuardrail, 0, len(guardrails))
+	for _, g := range guardrails {
+		out = append(out, g.ToAPIResponse())
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+func (h *handler) getGuardrail(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	guardrailID := mux.Vars(r)["guardrailId"]
+	if guardrailID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "guardrail ID is required"), w)
+		return
+	}
+
+	guardrail, err := h.manager.GetGuardrail(r.Context(), userAuth.AccountId, userAuth.UserId, guardrailID)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, guardrail.ToAPIResponse())
+}
+
+func (h *handler) createGuardrail(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkGuardrailRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validateGuardrail(&req); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	guardrail := types.NewGuardrail(userAuth.AccountId)
+	guardrail.FromAPIRequest(&req)
+
+	created, err := h.manager.CreateGuardrail(r.Context(), userAuth.UserId, guardrail)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, created.ToAPIResponse())
+}
+
+func (h *handler) updateGuardrail(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	guardrailID := mux.Vars(r)["guardrailId"]
+	if guardrailID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "guardrail ID is required"), w)
+		return
+	}
+
+	var req api.AgentNetworkGuardrailRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validateGuardrail(&req); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	guardrail := &types.Guardrail{
+		ID:        guardrailID,
+		AccountID: userAuth.AccountId,
+	}
+	guardrail.FromAPIRequest(&req)
+
+	updated, err := h.manager.UpdateGuardrail(r.Context(), userAuth.UserId, guardrail)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
+}
+
+func (h *handler) deleteGuardrail(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	guardrailID := mux.Vars(r)["guardrailId"]
+	if guardrailID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "guardrail ID is required"), w)
+		return
+	}
+
+	if err := h.manager.DeleteGuardrail(r.Context(), userAuth.AccountId, userAuth.UserId, guardrailID); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, util.EmptyObject{})
+}
+
+func validateGuardrail(req *api.AgentNetworkGuardrailRequest) error {
+	if strings.TrimSpace(req.Name) == "" {
+		return status.Errorf(status.InvalidArgument, "name is required")
+	}
+
+	c := req.Checks
+	if c.ModelAllowlist.Enabled {
+		for _, id := range c.ModelAllowlist.Models {
+			if strings.TrimSpace(id) == "" {
+				return status.Errorf(status.InvalidArgument, "model_allowlist.models must not contain empty entries")
+			}
+		}
+	}
+	return nil
+}
@@ -0,0 +1,270 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"runtime"
+	"strings"
+	"testing"
+
+	"go.uber.org/mock/gomock"
+	"github.com/gorilla/mux"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
+	agentNetworkTypes "github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	"github.com/netbirdio/netbird/management/server/account"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/management/internals/modules/permissions"
+	"github.com/netbirdio/netbird/management/server/store"
+	nbtypes "github.com/netbirdio/netbird/management/server/types"
+	"github.com/netbirdio/netbird/shared/auth"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+const (
+	testAccountID = "acc-1"
+	testUserID    = "user-bob"
+)
+
+// agentNetworkHandlerFixture builds a real agentnetwork.Manager with
+// a sqlite store and an always-allow permissions mock, then exposes
+// the HTTP handlers via a gorilla router. Tests issue requests
+// through httptest and assert on the wire shape — the same path the
+// dashboard exercises.
+type agentNetworkHandlerFixture struct {
+	store   store.Store
+	manager agentnetwork.Manager
+	router  *mux.Router
+}
+
+func newAgentNetworkHandlerFixture(t *testing.T) *agentNetworkHandlerFixture {
+	t.Helper()
+	if runtime.GOOS == "windows" {
+		t.Skip("sqlite store not properly supported on Windows yet")
+	}
+	t.Setenv("NETBIRD_STORE_ENGINE", string(nbtypes.SqliteStoreEngine))
+
+	st, cleanUp, err := store.NewTestStoreFromSQL(context.Background(), "", t.TempDir())
+	require.NoError(t, err)
+	t.Cleanup(cleanUp)
+
+	ctrl := gomock.NewController(t)
+	perms := permissions.NewMockManager(ctrl)
+	// Always-allow: the handler tests are about wire shape, not
+	// authz. Authz is covered by the manager's own tests.
+	perms.EXPECT().
+		ValidateUserPermissions(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).
+		Return(true, context.Background(), nil).
+		AnyTimes()
+
+	// Swallow activity events so the mutation paths (create/update/delete)
+	// are exercisable through the HTTP layer.
+	accounts := account.NewMockManager(ctrl)
+	accounts.EXPECT().
+		StoreEvent(gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any(), gomock.Any()).
+		AnyTimes()
+	accounts.EXPECT().
+		UpdateAccountPeers(gomock.Any(), gomock.Any(), gomock.Any()).
+		AnyTimes()
+
+	manager := agentnetwork.NewManager(st, perms, accounts, nil)
+	h := &handler{manager: manager}
+
+	router := mux.NewRouter()
+	router.HandleFunc("/agent-network/providers", h.createProvider).Methods("POST")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.getProvider).Methods("GET")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.updateProvider).Methods("PUT")
+	h.addPolicyEndpoints(router)
+	h.addConsumptionEndpoints(router)
+	h.addBudgetRuleEndpoints(router)
+	h.addSettingsEndpoints(router)
+
+	return &agentNetworkHandlerFixture{
+		store:   st,
+		manager: manager,
+		router:  router,
+	}
+}
+
+func (f *agentNetworkHandlerFixture) do(t *testing.T, method, path, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	var reader io.Reader
+	if body != "" {
+		reader = strings.NewReader(body)
+	}
+	req := httptest.NewRequest(method, path, reader)
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	req = nbcontext.SetUserAuthInRequest(req, auth.UserAuth{
+		UserId:    testUserID,
+		AccountId: testAccountID,
+	})
+	rec := httptest.NewRecorder()
+	f.router.ServeHTTP(rec, req)
+	return rec
+}
+
+// seedProvider persists a minimal provider record so policy create
+// passes the manager's destination_provider_ids existence check.
+func (f *agentNetworkHandlerFixture) seedProvider(t *testing.T, id string) {
+	t.Helper()
+	require.NoError(t, f.store.SaveAgentNetworkProvider(context.Background(), &agentNetworkTypes.Provider{
+		ID:                id,
+		AccountID:         testAccountID,
+		ProviderID:        "openai_api",
+		Name:              "test-" + id,
+		UpstreamURL:       "https://api.openai.com",
+		APIKey:            "sk-test",
+		Enabled:           true,
+		SessionPrivateKey: "test-priv-key",
+		SessionPublicKey:  "test-pub-key",
+	}))
+}
+
+// TestPolicyHandler_WindowSecondsRoundTrip ports bash 10 to Go:
+// assert that a policy with window_seconds on both Token + Budget
+// halves round-trips through GET unchanged AND that legacy
+// window_hours / window_days are absent from the JSON response. We
+// seed the policy directly via the store rather than POST-ing
+// because the create path goes through the manager's
+// accountManager.StoreEvent which we don't wire in this fixture; the
+// on-wire shape is what matters here, and the POST validation path
+// is covered separately by the RejectsSubMinuteWindow test.
+func TestPolicyHandler_WindowSecondsRoundTrip(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	policy := &agentNetworkTypes.Policy{
+		ID:                     "ainpol_test",
+		AccountID:              testAccountID,
+		Name:                   "round-trip",
+		Enabled:                true,
+		SourceGroups:           []string{"grp-engineers"},
+		DestinationProviderIDs: []string{"prov-1"},
+		Limits: agentNetworkTypes.PolicyLimits{
+			TokenLimit:  agentNetworkTypes.PolicyTokenLimit{Enabled: true, GroupCap: 10000, UserCap: 5000, WindowSeconds: 86_400},
+			BudgetLimit: agentNetworkTypes.PolicyBudgetLimit{Enabled: true, GroupCapUsd: 10.0, UserCapUsd: 2.5, WindowSeconds: 2_592_000},
+		},
+	}
+	require.NoError(t, f.store.SaveAgentNetworkPolicy(context.Background(), policy))
+
+	rec := f.do(t, http.MethodGet, "/agent-network/policies/"+policy.ID, "")
+	require.Equal(t, http.StatusOK, rec.Code, "GET must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkPolicy
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, int64(86_400), got.Limits.TokenLimit.WindowSeconds, "token_limit.window_seconds must round-trip")
+	assert.Equal(t, int64(2_592_000), got.Limits.BudgetLimit.WindowSeconds, "budget_limit.window_seconds must round-trip")
+
+	// Legacy field names must NOT appear in the response — would
+	// signal that the management server is still emitting the old
+	// shape and would fool a v1 dashboard into rendering days/hours.
+	assert.NotContains(t, rec.Body.String(), "window_hours",
+		"legacy window_hours field must be absent from the on-wire response")
+	assert.NotContains(t, rec.Body.String(), "window_days",
+		"legacy window_days field must be absent from the on-wire response")
+}
+
+// TestPolicyHandler_RejectsSubMinuteWindow ports bash 20 to Go: an
+// enabled limit with window_seconds < 60 must surface as a 4xx
+// because anything finer than per-minute produces an untenable
+// volume of consumption rows for a feature whose value comes from
+// per-window cap enforcement.
+func TestPolicyHandler_RejectsSubMinuteWindow(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+	f.seedProvider(t, "prov-1")
+
+	body := `{
+        "name": "sub-minute-window",
+        "enabled": true,
+        "source_groups": ["grp-engineers"],
+        "destination_provider_ids": ["prov-1"],
+        "guardrail_ids": [],
+        "limits": {
+            "token_limit": {"enabled": true, "group_cap": 10000, "user_cap": 5000, "window_seconds": 30},
+            "budget_limit": {"enabled": false, "group_cap_usd": 0, "user_cap_usd": 0, "window_seconds": 0}
+        }
+    }`
+	rec := f.do(t, http.MethodPost, "/agent-network/policies", body)
+	// 422 specifically (InvalidArgument) proves the window-validation path —
+	// a route miss would be 404 and an auth failure 403, so a generic 4xx
+	// would let those false-pass.
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"enabled token_limit with window_seconds<60 must be rejected as a validation error: got %d body=%s", rec.Code, rec.Body.String())
+	assert.Contains(t, rec.Body.String(), "window_seconds",
+		"rejection body must name the offending window_seconds field, proving it's the validation path: %s", rec.Body.String())
+}
+
+// TestConsumptionHandler_EmptyAccountReturnsArray ports bash 30 to
+// Go: GET /agent-network/consumption on a clean account always
+// returns a JSON array (possibly empty), never a 404 / 500. The
+// dashboard depends on this shape to render its empty state.
+func TestConsumptionHandler_EmptyAccountReturnsArray(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodGet, "/agent-network/consumption", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var rows []api.AgentNetworkConsumption
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &rows),
+		"response must always be a JSON array — even when empty: %s", rec.Body.String())
+	assert.Empty(t, rows)
+}
+
+// TestConsumptionHandler_PopulatedAccountListsRows mirrors the
+// /consumption read after a few RecordConsumption calls. Validates
+// the wire shape carries every field the dashboard reads (dim_kind,
+// dim_id, window_seconds, window_start_utc, tokens, cost_usd) and
+// rows are ordered window-newest-first.
+func TestConsumptionHandler_PopulatedAccountListsRows(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	require.NoError(t, f.manager.RecordConsumption(
+		context.Background(), testAccountID,
+		agentNetworkTypes.DimensionGroup, "grp-engineers",
+		86_400, 100, 50, 0.0125,
+	))
+	require.NoError(t, f.manager.RecordConsumption(
+		context.Background(), testAccountID,
+		agentNetworkTypes.DimensionUser, testUserID,
+		86_400, 100, 50, 0.0125,
+	))
+
+	rec := f.do(t, http.MethodGet, "/agent-network/consumption", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+
+	var rows []api.AgentNetworkConsumption
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &rows))
+	require.Len(t, rows, 2, "two RecordConsumption calls must yield two rows")
+
+	// Index by dim_kind so we can assert the full wire shape of each row,
+	// including the dimension id and the aligned window start the dashboard
+	// keys on. Both rows share totals and window.
+	byKind := make(map[string]api.AgentNetworkConsumption, len(rows))
+	for _, row := range rows {
+		assert.Equal(t, int64(100), row.TokensInput)
+		assert.Equal(t, int64(50), row.TokensOutput)
+		assert.InDelta(t, 0.0125, row.CostUsd, 1e-9)
+		assert.Equal(t, int64(86_400), row.WindowSeconds)
+		assert.False(t, row.WindowStartUtc.IsZero(), "window_start_utc must be set on every row")
+		byKind[string(row.DimensionKind)] = row
+	}
+
+	groupRow, ok := byKind["group"]
+	require.True(t, ok, "group dimension must surface")
+	assert.Equal(t, "grp-engineers", groupRow.DimensionId, "group row must carry the source group id as dimension_id")
+
+	userRow, ok := byKind["user"]
+	require.True(t, ok, "user dimension must surface")
+	assert.Equal(t, testUserID, userRow.DimensionId, "user row must carry the user id as dimension_id")
+
+	// Both rows fall in the same aligned window (same length, recorded
+	// together), so window_start_utc must match across them.
+	assert.Equal(t, groupRow.WindowStartUtc, userRow.WindowStartUtc,
+		"rows recorded in the same window must share the aligned window_start_utc")
+}
@@ -0,0 +1,178 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/modeldiscovery"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/auth"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+// discoveryManagerStub records what the handler asked for and returns a canned
+// answer. The Manager interface is embedded rather than implemented: only the
+// one method is reachable from this handler, and a call to any other should
+// fail loudly rather than silently return a zero value.
+type discoveryManagerStub struct {
+	agentnetwork.Manager
+
+	gotReq      modeldiscovery.Request
+	gotRecordID string
+	models      []modeldiscovery.Model
+	err         error
+}
+
+func (s *discoveryManagerStub) DiscoverProviderModels(
+	_ context.Context, _, _ string, req modeldiscovery.Request, recordID string,
+) ([]modeldiscovery.Model, error) {
+	s.gotReq = req
+	s.gotRecordID = recordID
+	return s.models, s.err
+}
+
+// postDiscovery drives the handler with an authenticated request.
+func postDiscovery(t *testing.T, stub *discoveryManagerStub, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	h := &handler{manager: stub}
+
+	req := httptest.NewRequest(http.MethodPost, "/agent-network/catalog/providers/models", strings.NewReader(body))
+	req = req.WithContext(nbcontext.SetUserAuthInContext(req.Context(), auth.UserAuth{
+		AccountId: "acc-1",
+		UserId:    "user-1",
+	}))
+
+	rec := httptest.NewRecorder()
+	h.discoverProviderModels(rec, req)
+	return rec
+}
+
+func TestDiscoverModelsReturnsTheVendorList(t *testing.T) {
+	stub := &discoveryManagerStub{models: []modeldiscovery.Model{
+		{ID: "eu.anthropic.claude-haiku-4-5-20251001-v1:0", Label: "EU Claude Haiku 4.5", PricingKnown: true},
+		{ID: "global.cohere.embed-v4:0", Label: "Global Cohere Embed v4"},
+		// A vendor that supplies no display name at all. Bedrock does for
+		// every profile, but the OpenAI listing carries none.
+		{ID: "gpt-4o-mini", PricingKnown: true},
+	}}
+
+	rec := postDiscovery(t, stub, `{
+		"catalog_provider_id":"bedrock_api",
+		"upstream_url":"https://bedrock-runtime.eu-central-1.amazonaws.com",
+		"api_key":"aws-bearer"
+	}`)
+	require.Equal(t, http.StatusOK, rec.Code, "body: %s", rec.Body.String())
+
+	var out api.AgentNetworkModelDiscoveryResponse
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &out))
+	require.Len(t, out.Models, 3)
+
+	assert.Equal(t, "eu.anthropic.claude-haiku-4-5-20251001-v1:0", out.Models[0].Id)
+	assert.True(t, out.Models[0].PricingKnown)
+	// An unpriced model must say so rather than arriving indistinguishable
+	// from a priced one: registering it silently would meter at zero.
+	assert.False(t, out.Models[1].PricingKnown)
+
+	require.NotNil(t, out.Models[0].Label, "the vendor supplied a display name")
+	assert.Equal(t, "EU Claude Haiku 4.5", *out.Models[0].Label)
+	// A vendor that supplies no name must omit the key rather than send an
+	// empty string: the dashboard falls back to the id on absence, and would
+	// render a blank row for "".
+	assert.Nil(t, out.Models[2].Label, "an absent label must not serialize")
+	assert.NotContains(t, rec.Body.String(), `"label":""`)
+
+	assert.Equal(t, "bedrock_api", stub.gotReq.CatalogID)
+	assert.Equal(t, "aws-bearer", stub.gotReq.APIKey)
+	// The upstream is what the region is read back out of for Bedrock, so
+	// losing it here would break discovery for every regional provider.
+	assert.Equal(t, "https://bedrock-runtime.eu-central-1.amazonaws.com", stub.gotReq.UpstreamURL)
+	assert.Empty(t, stub.gotRecordID)
+}
+
+func TestDiscoverModelsUsesAStoredRecordWithoutAKey(t *testing.T) {
+	stub := &discoveryManagerStub{}
+
+	rec := postDiscovery(t, stub, `{"catalog_provider_id":"openai_api","provider_id":"prov-42"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "body: %s", rec.Body.String())
+
+	// The dashboard refreshes a saved provider's list without ever holding
+	// the credential, so the record id has to reach the manager.
+	assert.Equal(t, "prov-42", stub.gotRecordID)
+	assert.Empty(t, stub.gotReq.APIKey)
+}
+
+// TestDiscoverModelsRefusesMixedCredentials covers the case where a caller
+// names a saved provider AND supplies a key. Accepting it would run an
+// arbitrary credential under the identity of a record the caller may only be
+// permitted to read.
+func TestDiscoverModelsRefusesMixedCredentials(t *testing.T) {
+	stub := &discoveryManagerStub{}
+
+	rec := postDiscovery(t, stub, `{
+		"catalog_provider_id":"openai_api",
+		"provider_id":"prov-42",
+		"api_key":"sk-attacker"
+	}`)
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+	assert.Empty(t, stub.gotRecordID, "the request must be refused before it reaches the manager")
+}
+
+// TestDiscoverModelsReportsNoDiscoveryDistinctly matters because the caller
+// falls back to the catalog's own model list on this outcome. Collapsing it
+// into a generic 500 would turn "this provider has no listing endpoint" into
+// "something went wrong", and the form would show an error instead of a list.
+func TestDiscoverModelsReportsNoDiscoveryDistinctly(t *testing.T) {
+	stub := &discoveryManagerStub{err: modeldiscovery.ErrNoDiscovery}
+
+	rec := postDiscovery(t, stub, `{"catalog_provider_id":"litellm_proxy","upstream_url":"https://gw.example.com","api_key":"sk"}`)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code)
+}
+
+// TestDiscoverModelsTrimsTheCatalogID pins that the id the emptiness check
+// accepts is the id the manager receives. A padded value that clears the check
+// but reaches the catalog untrimmed misses the lookup, and the operator is told
+// their provider does not exist.
+func TestDiscoverModelsTrimsTheCatalogID(t *testing.T) {
+	stub := &discoveryManagerStub{}
+
+	rec := postDiscovery(t, stub, `{"catalog_provider_id":"  openai_api  ","api_key":"sk"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "body: %s", rec.Body.String())
+	assert.Equal(t, "openai_api", stub.gotReq.CatalogID)
+}
+
+// TestDiscoverModelsReportsCallerInputAsBadRequest covers the other half of the
+// error mapping. These failures are all reachable from a well-formed request
+// with a bad field value, so answering 500 both misinforms the operator and
+// puts their typo into the server's error rate.
+func TestDiscoverModelsReportsCallerInputAsBadRequest(t *testing.T) {
+	stub := &discoveryManagerStub{
+		err: fmt.Errorf("%w: unknown catalog provider %q", modeldiscovery.ErrInvalidRequest, "nope"),
+	}
+
+	rec := postDiscovery(t, stub, `{"catalog_provider_id":"nope","api_key":"sk"}`)
+	assert.Equal(t, http.StatusBadRequest, rec.Code)
+	assert.Contains(t, rec.Body.String(), "unknown catalog provider")
+}
+
+func TestDiscoverModelsRejectsMalformedRequests(t *testing.T) {
+	for name, body := range map[string]string{
+		"not json":               `{`,
+		"no catalog provider":    `{"api_key":"sk"}`,
+		"blank catalog provider": `{"catalog_provider_id":"   ","api_key":"sk"}`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			stub := &discoveryManagerStub{}
+			rec := postDiscovery(t, stub, body)
+			assert.Equal(t, http.StatusBadRequest, rec.Code)
+		})
+	}
+}
@@ -0,0 +1,228 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+// minWindowSeconds is the floor enforced on enabled token / budget
+// limit windows. One minute is short enough for fine-grained burst
+// control without producing untenable consumption-row volume at scale.
+const minWindowSeconds int64 = 60
+
+// addPolicyEndpoints registers all Agent Network policy routes on the
+// shared handler.
+func (h *handler) addPolicyEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/policies", h.getAllPolicies).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/policies", h.createPolicy).Methods("POST", "OPTIONS")
+	router.HandleFunc("/agent-network/policies/{policyId}", h.getPolicy).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/policies/{policyId}", h.updatePolicy).Methods("PUT", "OPTIONS")
+	router.HandleFunc("/agent-network/policies/{policyId}", h.deletePolicy).Methods("DELETE", "OPTIONS")
+}
+
+func (h *handler) getAllPolicies(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	policies, err := h.manager.GetAllPolicies(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := make([]*api.AgentNetworkPolicy, 0, len(policies))
+	for _, p := range policies {
+		out = append(out, p.ToAPIResponse())
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+func (h *handler) getPolicy(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	policyID := mux.Vars(r)["policyId"]
+	if policyID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "policy ID is required"), w)
+		return
+	}
+
+	policy, err := h.manager.GetPolicy(r.Context(), userAuth.AccountId, userAuth.UserId, policyID)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, policy.ToAPIResponse())
+}
+
+func (h *handler) createPolicy(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkPolicyRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validatePolicy(&req); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	policy := types.NewPolicy(userAuth.AccountId)
+	policy.FromAPIRequest(&req)
+
+	created, err := h.manager.CreatePolicy(r.Context(), userAuth.UserId, policy)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, created.ToAPIResponse())
+}
+
+func (h *handler) updatePolicy(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	policyID := mux.Vars(r)["policyId"]
+	if policyID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "policy ID is required"), w)
+		return
+	}
+
+	var req api.AgentNetworkPolicyRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validatePolicy(&req); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	policy := &types.Policy{
+		ID:        policyID,
+		AccountID: userAuth.AccountId,
+	}
+	policy.FromAPIRequest(&req)
+
+	updated, err := h.manager.UpdatePolicy(r.Context(), userAuth.UserId, policy)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
+}
+
+func (h *handler) deletePolicy(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	policyID := mux.Vars(r)["policyId"]
+	if policyID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "policy ID is required"), w)
+		return
+	}
+
+	if err := h.manager.DeletePolicy(r.Context(), userAuth.AccountId, userAuth.UserId, policyID); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, util.EmptyObject{})
+}
+
+func validatePolicy(req *api.AgentNetworkPolicyRequest) error {
+	if strings.TrimSpace(req.Name) == "" {
+		return status.Errorf(status.InvalidArgument, "name is required")
+	}
+	if len(req.SourceGroups) == 0 {
+		return status.Errorf(status.InvalidArgument, "source_groups must contain at least one group id")
+	}
+	for _, id := range req.SourceGroups {
+		if strings.TrimSpace(id) == "" {
+			return status.Errorf(status.InvalidArgument, "source_groups must not contain empty entries")
+		}
+	}
+	if len(req.DestinationProviderIds) == 0 {
+		return status.Errorf(status.InvalidArgument, "destination_provider_ids must contain at least one provider id")
+	}
+	for _, id := range req.DestinationProviderIds {
+		if strings.TrimSpace(id) == "" {
+			return status.Errorf(status.InvalidArgument, "destination_provider_ids must not contain empty entries")
+		}
+	}
+	if req.GuardrailIds != nil {
+		for _, id := range *req.GuardrailIds {
+			if strings.TrimSpace(id) == "" {
+				return status.Errorf(status.InvalidArgument, "guardrail_ids must not contain empty entries")
+			}
+		}
+	}
+	if req.Limits != nil {
+		if err := validatePolicyLimits(*req.Limits); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func validatePolicyLimits(l api.AgentNetworkPolicyLimits) error {
+	if l.TokenLimit.Enabled {
+		if l.TokenLimit.WindowSeconds < minWindowSeconds {
+			return status.Errorf(status.InvalidArgument, "limits.token_limit.window_seconds must be at least %d (one minute) when enabled", minWindowSeconds)
+		}
+		if l.TokenLimit.GroupCap < 0 {
+			return status.Errorf(status.InvalidArgument, "limits.token_limit.group_cap must not be negative")
+		}
+		if l.TokenLimit.UserCap < 0 {
+			return status.Errorf(status.InvalidArgument, "limits.token_limit.user_cap must not be negative")
+		}
+		if l.TokenLimit.GroupCap == 0 && l.TokenLimit.UserCap == 0 {
+			return status.Errorf(status.InvalidArgument, "limits.token_limit requires group_cap or user_cap to be greater than zero when enabled")
+		}
+	}
+	if l.BudgetLimit.Enabled {
+		if l.BudgetLimit.WindowSeconds < minWindowSeconds {
+			return status.Errorf(status.InvalidArgument, "limits.budget_limit.window_seconds must be at least %d (one minute) when enabled", minWindowSeconds)
+		}
+		if l.BudgetLimit.GroupCapUsd < 0 {
+			return status.Errorf(status.InvalidArgument, "limits.budget_limit.group_cap_usd must not be negative")
+		}
+		if l.BudgetLimit.UserCapUsd < 0 {
+			return status.Errorf(status.InvalidArgument, "limits.budget_limit.user_cap_usd must not be negative")
+		}
+		if l.BudgetLimit.GroupCapUsd == 0 && l.BudgetLimit.UserCapUsd == 0 {
+			return status.Errorf(status.InvalidArgument, "limits.budget_limit requires group_cap_usd or user_cap_usd to be greater than zero when enabled")
+		}
+	}
+	return nil
+}
@@ -0,0 +1,385 @@
+// Package handlers serves the Agent Network HTTP API.
+//
+// All persistence is delegated to agentnetwork.Manager so this layer only
+// translates between the wire format (api.AgentNetworkProvider*) and the
+// domain types.
+package handlers
+
+import (
+	"encoding/json"
+	"errors"
+	"math"
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork"
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/catalog"
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/modeldiscovery"
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/pricing"
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+	"github.com/netbirdio/netbird/shared/management/status"
+)
+
+type handler struct {
+	manager agentnetwork.Manager
+}
+
+// RegisterEndpoints registers all Agent Network routes.
+func RegisterEndpoints(manager agentnetwork.Manager, router *mux.Router) {
+	h := &handler{manager: manager}
+	router.HandleFunc("/agent-network/catalog/providers", h.getCatalogProviders).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/catalog/providers/models", h.discoverProviderModels).Methods("POST", "OPTIONS")
+	router.HandleFunc("/agent-network/providers", h.getAllProviders).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/providers", h.createProvider).Methods("POST", "OPTIONS")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.getProvider).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.updateProvider).Methods("PUT", "OPTIONS")
+	router.HandleFunc("/agent-network/providers/{providerId}", h.deleteProvider).Methods("DELETE", "OPTIONS")
+	h.addPolicyEndpoints(router)
+	h.addGuardrailEndpoints(router)
+	h.addSettingsEndpoints(router)
+	h.addConsumptionEndpoints(router)
+	h.addAccessLogEndpoints(router)
+	h.addBudgetRuleEndpoints(router)
+	h.addAgentConfigEndpoints(router)
+}
+
+func (h *handler) getCatalogProviders(w http.ResponseWriter, r *http.Request) {
+	if _, err := nbcontext.GetUserAuthFromContext(r.Context()); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	entries := catalog.All()
+	out := make([]api.AgentNetworkCatalogProvider, 0, len(entries))
+	for _, e := range entries {
+		resp := e.ToAPIResponse()
+		applyDefaultPricing(e, &resp)
+		out = append(out, resp)
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+// discoverProviderModels asks the vendor which models the operator's own
+// credential can reach, so the provider form can offer a live list rather than
+// only the static catalog.
+func (h *handler) discoverProviderModels(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var body api.AgentNetworkModelDiscoveryRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		util.WriteErrorResponse("invalid json", http.StatusBadRequest, w)
+		return
+	}
+	// Trimmed once and carried, not trimmed for the emptiness test and then
+	// discarded: a padded " openai_api " would clear the check here and miss
+	// the catalog lookup, reporting the provider as unknown.
+	catalogID := strings.TrimSpace(body.CatalogProviderId)
+	if catalogID == "" {
+		util.WriteErrorResponse("catalog_provider_id is required", http.StatusBadRequest, w)
+		return
+	}
+
+	recordID := strValue(body.ProviderId)
+	req := modeldiscovery.Request{
+		CatalogID:   catalogID,
+		UpstreamURL: strValue(body.UpstreamUrl),
+		APIKey:      strValue(body.ApiKey),
+	}
+	// One source of credential or the other, never a mix: taking a key from
+	// the request while addressing a saved record would let a caller run an
+	// arbitrary credential against a provider they can only read.
+	if recordID != "" && req.APIKey != "" {
+		util.WriteErrorResponse("provide either provider_id or api_key, not both", http.StatusBadRequest, w)
+		return
+	}
+
+	models, err := h.manager.DiscoverProviderModels(r.Context(), userAuth.AccountId, userAuth.UserId, req, recordID)
+	if err != nil {
+		// A provider with no listing endpoint is a fact about the catalog
+		// entry, not a failure: the caller falls back to the catalog's own
+		// models, so it must be able to tell the two apart.
+		if errors.Is(err, modeldiscovery.ErrNoDiscovery) {
+			util.WriteErrorResponse(err.Error(), http.StatusUnprocessableEntity, w)
+			return
+		}
+		// An unknown provider, an unusable upstream, a missing region or a
+		// missing key are all things the caller sent, reachable from a
+		// well-formed request. Reporting them as 500 tells the operator the
+		// server broke and buries genuine faults in the error rate.
+		if errors.Is(err, modeldiscovery.ErrInvalidRequest) {
+			util.WriteErrorResponse(err.Error(), http.StatusBadRequest, w)
+			return
+		}
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := api.AgentNetworkModelDiscoveryResponse{Models: make([]api.AgentNetworkDiscoveredModel, 0, len(models))}
+	for _, m := range models {
+		entry := api.AgentNetworkDiscoveredModel{
+			Id:           m.ID,
+			PricingKnown: m.PricingKnown,
+			// Sent even when zero: the form prefills every discovered model as
+			// an editable row, and an unpriced one is shown at zero and flagged
+			// rather than left out.
+			InputPer1k:  m.InputPer1k,
+			OutputPer1k: m.OutputPer1k,
+			// Cache rates stay absent when unset, matching the catalog
+			// response — a zero would read as "free", not "not applicable".
+			CachedInputPer1k:   positiveRatePtr(m.CachedInputPer1k),
+			CacheReadPer1k:     positiveRatePtr(m.CacheReadPer1k),
+			CacheCreationPer1k: positiveRatePtr(m.CacheCreationPer1k),
+		}
+		if m.Label != "" {
+			label := m.Label
+			entry.Label = &label
+		}
+		out.Models = append(out.Models, entry)
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+// strValue reads an optional string field, treating absent as empty.
+func strValue(v *string) string {
+	if v == nil {
+		return ""
+	}
+	return strings.TrimSpace(*v)
+}
+
+// applyDefaultPricing overwrites the catalog response's model rates with
+// the LIVE default pricing table, which may differ from the compiled-in
+// catalog rates when the operator provides a defaults_llm_pricing.yaml.
+// This keeps the dashboard's model-row prefill identical to what the
+// proxy will actually bill — the same table the synthesizer ships.
+func applyDefaultPricing(cp catalog.Provider, resp *api.AgentNetworkCatalogProvider) {
+	if len(cp.PricingSurfaces) == 0 {
+		return
+	}
+	for i := range resp.Models {
+		m := &resp.Models[i]
+		e, ok := pricing.LookupDefault(cp.PricingSurfaces, m.Id)
+		if !ok {
+			continue
+		}
+		m.InputPer1k = e.InputPer1k
+		m.OutputPer1k = e.OutputPer1k
+		m.CachedInputPer1k = positiveRatePtr(e.CachedInputPer1k)
+		m.CacheReadPer1k = positiveRatePtr(e.CacheReadPer1k)
+		m.CacheCreationPer1k = positiveRatePtr(e.CacheCreationPer1k)
+	}
+}
+
+// positiveRatePtr renders a cache rate for the API: absent (nil) when
+// unset, matching the catalog response convention.
+func positiveRatePtr(v float64) *float64 {
+	if v <= 0 {
+		return nil
+	}
+	return &v
+}
+
+func (h *handler) getAllProviders(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	providers, err := h.manager.GetAllProviders(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	out := make([]*api.AgentNetworkProvider, 0, len(providers))
+	for _, p := range providers {
+		out = append(out, p.ToAPIResponse())
+	}
+	util.WriteJSONObject(r.Context(), w, out)
+}
+
+func (h *handler) getProvider(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	providerID := mux.Vars(r)["providerId"]
+	if providerID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "provider ID is required"), w)
+		return
+	}
+
+	provider, err := h.manager.GetProvider(r.Context(), userAuth.AccountId, userAuth.UserId, providerID)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, provider.ToAPIResponse())
+}
+
+func (h *handler) createProvider(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkProviderRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validate(&req, true); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	provider := types.NewProvider(userAuth.AccountId)
+	provider.FromAPIRequest(&req)
+
+	created, err := h.manager.CreateProvider(r.Context(), userAuth.UserId, provider)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, created.ToAPIResponse())
+}
+
+func (h *handler) updateProvider(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	providerID := mux.Vars(r)["providerId"]
+	if providerID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "provider ID is required"), w)
+		return
+	}
+
+	var req api.AgentNetworkProviderRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	if err := validate(&req, false); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	provider := &types.Provider{
+		ID:        providerID,
+		AccountID: userAuth.AccountId,
+	}
+	provider.FromAPIRequest(&req)
+
+	updated, err := h.manager.UpdateProvider(r.Context(), userAuth.UserId, provider)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
+}
+
+func (h *handler) deleteProvider(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	providerID := mux.Vars(r)["providerId"]
+	if providerID == "" {
+		util.WriteError(r.Context(), status.Errorf(status.InvalidArgument, "provider ID is required"), w)
+		return
+	}
+
+	if err := h.manager.DeleteProvider(r.Context(), userAuth.AccountId, userAuth.UserId, providerID); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	util.WriteJSONObject(r.Context(), w, util.EmptyObject{})
+}
+
+func validate(req *api.AgentNetworkProviderRequest, requireAPIKey bool) error {
+	if strings.TrimSpace(req.ProviderId) == "" {
+		return status.Errorf(status.InvalidArgument, "provider_id is required")
+	}
+	if !catalog.IsKnown(req.ProviderId) {
+		return status.Errorf(status.InvalidArgument, "provider_id %q is not a known catalog provider", req.ProviderId)
+	}
+	if strings.TrimSpace(req.Name) == "" {
+		return status.Errorf(status.InvalidArgument, "name is required")
+	}
+	if strings.TrimSpace(req.UpstreamUrl) == "" {
+		return status.Errorf(status.InvalidArgument, "upstream_url is required")
+	}
+	u, err := url.Parse(strings.TrimSpace(req.UpstreamUrl))
+	if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") {
+		return status.Errorf(status.InvalidArgument, "upstream_url must be a full http(s) URL")
+	}
+	if requireAPIKey && (req.ApiKey == nil || strings.TrimSpace(*req.ApiKey) == "") {
+		return status.Errorf(status.InvalidArgument, "api_key is required")
+	}
+	// An update omits api_key to keep the stored credential. A key that is
+	// present but blank is not that: Provider.FromAPIRequest drops it exactly
+	// as if it were absent, so a rotation the operator believes they performed
+	// would answer 200 having changed nothing. Refuse it here, where the
+	// request still carries the difference between absent and blank.
+	if req.ApiKey != nil && strings.TrimSpace(*req.ApiKey) == "" {
+		return status.Errorf(status.InvalidArgument, "api_key must be omitted to keep the stored credential rather than sent blank")
+	}
+	if req.Models != nil {
+		for i, m := range *req.Models {
+			if err := validateModel(i, m); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// validateModel is the single ingress guard for operator-entered pricing:
+// these rates are synthesized into the proxy's cost_meter config verbatim,
+// and a negative or non-finite rate there would poison every cost the
+// proxy records, so reject at the API boundary.
+func validateModel(i int, m api.AgentNetworkProviderModel) error {
+	if strings.TrimSpace(m.Id) == "" {
+		return status.Errorf(status.InvalidArgument, "models[%d]: id is required", i)
+	}
+	rates := map[string]*float64{
+		"input_per_1k":          &m.InputPer1k,
+		"output_per_1k":         &m.OutputPer1k,
+		"cached_input_per_1k":   m.CachedInputPer1k,
+		"cache_read_per_1k":     m.CacheReadPer1k,
+		"cache_creation_per_1k": m.CacheCreationPer1k,
+	}
+	for field, v := range rates {
+		if v == nil {
+			continue
+		}
+		if *v < 0 || math.IsNaN(*v) || math.IsInf(*v, 0) {
+			return status.Errorf(status.InvalidArgument, "models[%d] (%s): %s must be a finite, non-negative USD rate", i, m.Id, field)
+		}
+	}
+	return nil
+}
@@ -0,0 +1,138 @@
+package handlers
+
+import (
+	"encoding/json"
+	"math"
+	nethttp "net/http"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+func f(v float64) *float64 { return &v }
+
+// TestValidate_ModelRates guards the single ingress point for operator-entered
+// pricing. These rates flow verbatim into the proxy's cost_meter config at
+// synthesis time; the proxy treats a bad rate as a chain-build failure, so
+// rejecting here is what keeps an account's gateway from going down.
+func TestValidate_ModelRates(t *testing.T) {
+	base := func(models ...api.AgentNetworkProviderModel) *api.AgentNetworkProviderRequest {
+		key := "sk-test"
+		return &api.AgentNetworkProviderRequest{
+			ProviderId:  "openai_api",
+			Name:        "OpenAI",
+			UpstreamUrl: "https://api.openai.com",
+			ApiKey:      &key,
+			Models:      &models,
+		}
+	}
+
+	valid := api.AgentNetworkProviderModel{
+		Id: "gpt-4o", InputPer1k: 0.0025, OutputPer1k: 0.01,
+		CachedInputPer1k: f(0.00125),
+	}
+	require.NoError(t, validate(base(valid), true), "finite non-negative rates must pass")
+
+	zeroRates := api.AgentNetworkProviderModel{Id: "self-hosted-llama", InputPer1k: 0, OutputPer1k: 0}
+	require.NoError(t, validate(base(zeroRates), true), "explicit zero prices are allowed (free / self-hosted models)")
+
+	cases := map[string]api.AgentNetworkProviderModel{
+		"empty id":           {Id: "  ", InputPer1k: 0.001, OutputPer1k: 0.002},
+		"negative input":     {Id: "m", InputPer1k: -0.001, OutputPer1k: 0.002},
+		"negative output":    {Id: "m", InputPer1k: 0.001, OutputPer1k: -0.002},
+		"NaN input":          {Id: "m", InputPer1k: math.NaN(), OutputPer1k: 0.002},
+		"Inf output":         {Id: "m", InputPer1k: 0.001, OutputPer1k: math.Inf(1)},
+		"negative cached":    {Id: "m", InputPer1k: 0.001, OutputPer1k: 0.002, CachedInputPer1k: f(-1)},
+		"NaN cache read":     {Id: "m", InputPer1k: 0.001, OutputPer1k: 0.002, CacheReadPer1k: f(math.NaN())},
+		"Inf cache creation": {Id: "m", InputPer1k: 0.001, OutputPer1k: 0.002, CacheCreationPer1k: f(math.Inf(-1))},
+	}
+	for name, m := range cases {
+		assert.Error(t, validate(base(m), true), "case %q must be rejected", name)
+	}
+}
+
+// TestValidate_ABlankApiKeyIsNotTheSameAsAnOmittedOne covers the one shape the
+// manager's own guard cannot see. Provider.FromAPIRequest assigns the key only
+// when it trims to something, so a request carrying "   " arrives at
+// UpdateProvider indistinguishable from one that omitted it — the stored
+// credential is kept and the write answers 200, telling an operator who thinks
+// they just rotated a key that it worked.
+//
+// The request still knows the difference, so the refusal belongs here.
+func TestValidate_ABlankApiKeyIsNotTheSameAsAnOmittedOne(t *testing.T) {
+	req := func(key *string) *api.AgentNetworkProviderRequest {
+		return &api.AgentNetworkProviderRequest{
+			ProviderId:  "openai_api",
+			Name:        "OpenAI",
+			UpstreamUrl: "https://api.openai.com",
+			ApiKey:      key,
+		}
+	}
+
+	blank := "   "
+	err := validate(req(&blank), false)
+	require.Error(t, err, "a blank api_key on update must not be read as 'keep what is stored'")
+	assert.Contains(t, err.Error(), "api_key")
+
+	require.NoError(t, validate(req(nil), false), "an omitted api_key is how an update keeps the stored credential")
+
+	// Create already refuses this, and keeps its own message: a caller who sent
+	// no usable key is told the field is required rather than being told how to
+	// preserve a credential that does not exist yet.
+	err = validate(req(&blank), true)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "api_key is required")
+}
+
+// TestProviderHandler_UpdateReplacesFullState pins the update contract shared
+// with the other PUT endpoints: the request replaces the provider's mutable
+// state, so optional fields absent from the JSON land as their zero values.
+// The two exceptions are server-side: the api_key (a secret — omitted means
+// "not rotated") and the session keypair, both preserved by the manager. The
+// identity headers stay on the wire as explicit empty strings so a cleared
+// value round-trips.
+func TestProviderHandler_UpdateReplacesFullState(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	// A private upstream: the save-time credential check leaves it unchecked
+	// rather than spending "sk-test" against the real api.openai.com, which
+	// the vendor refuses.
+	create := `{
+        "provider_id": "openai_api",
+        "name": "openai",
+        "upstream_url": "https://10.255.255.1",
+        "api_key": "sk-test",
+        "enabled": true,
+        "metadata_disabled": true,
+        "skip_tls_verification": true,
+        "extra_values": {"x-portkey-config": "pc-prod-3f2a"},
+        "identity_header_user_id": "x-bf-dim-netbird_user_id",
+        "models": [{"id": "gpt-4o", "input_per_1k": 0.0025, "output_per_1k": 0.01}]
+    }`
+	rec := f.do(t, nethttp.MethodPost, "/agent-network/providers", create)
+	require.Equal(t, nethttp.StatusOK, rec.Code, "create must succeed: %s", rec.Body.String())
+
+	var created api.AgentNetworkProvider
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &created))
+
+	// Minimal update: only the required fields, no api_key. Everything
+	// optional must land as its zero value.
+	update := `{"provider_id": "openai_api", "name": "openai-renamed", "upstream_url": "https://10.255.255.1", "enabled": true}`
+	rec = f.do(t, nethttp.MethodPut, "/agent-network/providers/"+created.Id, update)
+	require.Equal(t, nethttp.StatusOK, rec.Code, "update without api_key must succeed (key is preserved): %s", rec.Body.String())
+
+	var updated api.AgentNetworkProvider
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &updated))
+	assert.Equal(t, "openai-renamed", updated.Name, "sent field must apply")
+	assert.True(t, updated.Enabled, "sent field must apply")
+	assert.False(t, updated.MetadataDisabled, "omitted metadata_disabled must land as false — PUT replaces the full state")
+	assert.False(t, updated.SkipTlsVerification, "omitted skip_tls_verification must land as false")
+	assert.Nil(t, updated.ExtraValues, "omitted extra_values must be cleared")
+	assert.Equal(t, "", updated.IdentityHeaderUserId, "omitted identity header must be cleared yet stay on the wire")
+	assert.Empty(t, updated.Models, "omitted models must be cleared")
+	assert.Contains(t, rec.Body.String(), `"identity_header_user_id":""`,
+		"cleared identity header must round-trip as an explicit empty string")
+}
@@ -0,0 +1,127 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/gorilla/mux"
+
+	"github.com/netbirdio/netbird/management/internals/modules/agentnetwork/types"
+	nbcontext "github.com/netbirdio/netbird/management/server/context"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+	"github.com/netbirdio/netbird/shared/management/http/util"
+)
+
+// addSettingsEndpoints registers the Agent Network settings routes. POST
+// bootstraps the settings row, assigning the account's immutable endpoint;
+// GET reads it (defaults with an empty endpoint before bootstrap); PUT
+// carries every field, replacing the mutable collection toggles and rejecting
+// any change to the identity fields; DELETE removes the row — guarded so it
+// stays a bootstrap-repair operation — releasing the endpoint for a fresh
+// bootstrap.
+func (h *handler) addSettingsEndpoints(router *mux.Router) {
+	router.HandleFunc("/agent-network/settings", h.getSettings).Methods("GET", "OPTIONS")
+	router.HandleFunc("/agent-network/settings", h.createSettings).Methods("POST", "OPTIONS")
+	router.HandleFunc("/agent-network/settings", h.updateSettings).Methods("PUT", "OPTIONS")
+	router.HandleFunc("/agent-network/settings", h.deleteSettings).Methods("DELETE", "OPTIONS")
+}
+
+// createSettings bootstraps the account's settings row. Exactly one of
+// proxy_address (labeled endpoint; the server allocates the label) and
+// endpoint (self-addressed, claimed verbatim) must be provided; optional
+// collection toggles ride along with defaults for omitted fields.
+func (h *handler) createSettings(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkSettingsCreateRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	settings := types.DefaultSettings(userAuth.AccountId)
+	settings.FromAPICreateRequest(&req)
+
+	proxyAddress := ""
+	if req.ProxyAddress != nil {
+		proxyAddress = *req.ProxyAddress
+	}
+	endpoint := ""
+	if req.Endpoint != nil {
+		endpoint = *req.Endpoint
+	}
+
+	created, err := h.manager.CreateSettings(r.Context(), userAuth.UserId, settings, proxyAddress, endpoint)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, created.ToAPIResponse())
+}
+
+// updateSettings replaces the mutable settings fields on the account's row.
+// A request carrying a cluster bootstraps the row when the account doesn't
+// have one yet.
+func (h *handler) updateSettings(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	var req api.AgentNetworkSettingsRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		util.WriteErrorResponse("couldn't parse JSON request", http.StatusBadRequest, w)
+		return
+	}
+
+	settings := &types.Settings{AccountID: userAuth.AccountId}
+	settings.FromAPIRequest(&req)
+
+	updated, err := h.manager.UpdateSettings(r.Context(), userAuth.UserId, settings)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, updated.ToAPIResponse())
+}
+
+// deleteSettings removes the account's settings row, releasing the endpoint.
+// The manager refuses (412) while providers exist or a proxy is actively
+// serving the endpoint; a later POST bootstraps fresh, allocating a new
+// endpoint.
+func (h *handler) deleteSettings(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	if err := h.manager.DeleteSettings(r.Context(), userAuth.AccountId, userAuth.UserId); err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, util.EmptyObject{})
+}
+
+// getSettings returns the account's agent-network settings. Accounts that
+// haven't been bootstrapped yet read as the defaults with an empty cluster,
+// subdomain and endpoint; the manager synthesises that view.
+func (h *handler) getSettings(w http.ResponseWriter, r *http.Request) {
+	userAuth, err := nbcontext.GetUserAuthFromContext(r.Context())
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+
+	settings, err := h.manager.GetSettings(r.Context(), userAuth.AccountId, userAuth.UserId)
+	if err != nil {
+		util.WriteError(r.Context(), err, w)
+		return
+	}
+	util.WriteJSONObject(r.Context(), w, settings.ToAPIResponse())
+}
@@ -0,0 +1,395 @@
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	rpproxy "github.com/netbirdio/netbird/management/internals/modules/reverseproxy/proxy"
+	"github.com/netbirdio/netbird/shared/management/http/api"
+)
+
+// TestSettingsHandler_GetUnbootstrappedReturnsDefaults pins the settings-read
+// convention shared with the account and DNS settings endpoints: settings
+// always read as a JSON object. Before bootstrap that object carries the
+// defaults with an empty endpoint/proxy_address (the "not bootstrapped"
+// signal) and no timestamps — never a 404 and never the legacy null body.
+func TestSettingsHandler_GetUnbootstrappedReturnsDefaults(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code,
+		"unbootstrapped account must read as 200 with defaults: got %d body=%s", rec.Code, rec.Body.String())
+	require.NotEqual(t, "null", trimSpace(rec.Body.String()),
+		"the legacy 200+null shape must not come back")
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Empty(t, got.Endpoint, "endpoint must be empty until bootstrapped")
+	assert.Empty(t, got.ProxyAddress, "proxy address must be empty until bootstrapped")
+	assert.False(t, got.Dedicated, "an unbootstrapped account has no serving shape")
+	assert.True(t, got.EnableLogCollection, "defaults must show log collection on, matching bootstrap")
+	assert.False(t, got.EnablePromptCollection, "defaults must show prompt collection off")
+	assert.False(t, got.RedactPii, "defaults must show redaction off")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 30, *got.AccessLogRetentionDays, "defaults must show the bootstrap retention")
+	assert.Nil(t, got.CreatedAt, "no timestamps before a row exists")
+	assert.Nil(t, got.UpdatedAt, "no timestamps before a row exists")
+}
+
+// TestSettingsHandler_PostBootstrapsLabeled covers the labeled bootstrap
+// shape: a POST carrying a proxy_address allocates a label beneath it, so the
+// endpoint hangs one label under the shared cluster's address and the pin is
+// not dedicated. Toggles riding along apply; omitted ones keep defaults.
+func TestSettingsHandler_PostBootstrapsLabeled(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true, "access_log_retention_days": 14}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, "eu.proxy.netbird.io", got.ProxyAddress, "proxy address must be pinned from the request")
+	require.NotEmpty(t, got.Endpoint, "endpoint must be allocated at bootstrap")
+	assert.True(t, strings.HasSuffix(got.Endpoint, ".eu.proxy.netbird.io"),
+		"labeled endpoint must hang off the proxy address: %s", got.Endpoint)
+	label := strings.TrimSuffix(got.Endpoint, ".eu.proxy.netbird.io")
+	assert.NotContains(t, label, ".", "the allocated label must be a single DNS label: %s", label)
+	assert.False(t, got.Dedicated, "a labeled pin is not dedicated")
+	assert.True(t, got.EnableLogCollection, "omitted toggle must keep its default")
+	assert.True(t, got.EnablePromptCollection, "toggle from the bootstrap request must apply")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 14, *got.AccessLogRetentionDays, "retention from the bootstrap request must apply")
+	assert.NotNil(t, got.CreatedAt, "a persisted row carries timestamps")
+
+	// The row is now readable via GET.
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code, "GET after bootstrap must succeed")
+	var read api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &read))
+	assert.Equal(t, got.Endpoint, read.Endpoint, "GET must return the bootstrapped endpoint")
+}
+
+// TestSettingsHandler_PostBootstrapsSelfAddressed covers the dedicated shape:
+// a POST carrying an endpoint claims the hostname verbatim, the proxy address
+// equals it, and the pin reads as dedicated. The claim is legitimate before
+// any proxy declares the address (address-first).
+func TestSettingsHandler_PostBootstrapsSelfAddressed(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"endpoint": "Brave-Otter.Gateway.Example.com"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, "brave-otter.gateway.example.com", got.Endpoint,
+		"endpoint must be claimed verbatim, lowercased")
+	assert.Equal(t, got.Endpoint, got.ProxyAddress, "self-addressed: the proxy address is the endpoint")
+	assert.True(t, got.Dedicated, "a self-addressed pin is dedicated")
+	assert.True(t, got.EnableLogCollection, "omitted toggles must keep their defaults")
+}
+
+// TestSettingsHandler_PostRequiresExactlyOneIdentityField pins the request
+// contract: proxy_address and endpoint are mutually exclusive and one is
+// required — both or neither is a validation error, not a guess.
+func TestSettingsHandler_PostRequiresExactlyOneIdentityField(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", `{}`)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"empty POST must be rejected: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "endpoint": "brave-otter.gateway.example.com"}`)
+	assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+		"POST with both identity fields must be rejected: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_PostRejectsMalformedHostnames pins per-write input
+// validation: shapes canonicalization cannot repair — trailing dots, embedded
+// whitespace, empty labels — are rejected with a validation error instead of
+// landing in an immutable column.
+func TestSettingsHandler_PostRejectsMalformedHostnames(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	for name, body := range map[string]string{
+		"trailing dot":     `{"endpoint": "gateway.example.com."}`,
+		"leading dot":      `{"endpoint": ".gateway.example.com"}`,
+		"inner whitespace": `{"endpoint": "gate way.example.com"}`,
+		"empty label":      `{"proxy_address": "eu..proxy.netbird.io"}`,
+	} {
+		rec := f.do(t, http.MethodPost, "/agent-network/settings", body)
+		assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+			"%s must be rejected: got %d body=%s", name, rec.Code, rec.Body.String())
+	}
+}
+
+// TestSettingsHandler_PostConflictsOnSecondBootstrap pins that bootstrap is a
+// one-time create: a second POST returns 409 and leaves the row untouched.
+func TestSettingsHandler_PostConflictsOnSecondBootstrap(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "eu.proxy.netbird.io"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "first bootstrap must succeed: %s", rec.Body.String())
+	var first api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &first))
+
+	rec = f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "us.proxy.netbird.io"}`)
+	assert.Equal(t, http.StatusConflict, rec.Code,
+		"second bootstrap must 409: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, first.Endpoint, got.Endpoint, "the original endpoint must survive the rejected bootstrap")
+	assert.Equal(t, first.ProxyAddress, got.ProxyAddress, "the original proxy address must survive")
+}
+
+// TestSettingsHandler_PutBeforeBootstrapIs404 pins that a PUT cannot conjure a
+// settings row out of nothing — bootstrap is the explicit POST — and the
+// error points the caller there.
+func TestSettingsHandler_PutBeforeBootstrapIs404(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPut, "/agent-network/settings",
+		`{"enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false}`)
+	assert.Equal(t, http.StatusNotFound, rec.Code,
+		"PUT on an unbootstrapped account must 404: got %d body=%s", rec.Code, rec.Body.String())
+	assert.Contains(t, rec.Body.String(), "/api/agent-network/settings",
+		"the error must point the caller at the bootstrap POST: %s", rec.Body.String())
+}
+
+// TestSettingsHandler_PutReplacesMutableFields pins the update contract shared
+// with the other PUT endpoints: the request carries every field, replacing the
+// mutable ones. The identity fields ride along as a required echo of the
+// assigned values — compared, never written — so the endpoint and proxy
+// address survive every accepted update.
+func TestSettingsHandler_PutReplacesMutableFields(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true, "redact_pii": true, "access_log_retention_days": 14}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	var before api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
+
+	rec = f.do(t, http.MethodPut, "/agent-network/settings", fmt.Sprintf(
+		`{"endpoint": %q, "proxy_address": %q, "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 7}`,
+		before.Endpoint, before.ProxyAddress))
+	require.Equal(t, http.StatusOK, rec.Code, "update PUT must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.True(t, got.EnableLogCollection, "sent toggle must apply")
+	assert.False(t, got.EnablePromptCollection, "sent toggle must apply")
+	assert.False(t, got.RedactPii, "sent toggle must apply")
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 7, *got.AccessLogRetentionDays, "sent retention must apply")
+	assert.Equal(t, before.Endpoint, got.Endpoint, "endpoint must survive updates untouched")
+	assert.Equal(t, before.ProxyAddress, got.ProxyAddress, "proxy address must survive updates untouched")
+}
+
+// TestSettingsHandler_PutRejectsChangedIdentity pins the immutability contract:
+// the PUT carries the identity fields like every other field, but they are an
+// echo — a request carrying a different endpoint or proxy address is rejected
+// as a validation error and the row is left untouched. The comparison is
+// lenient about casing (the stored values are normalized lowercase), so a
+// client replaying a GET response with different casing is not rejected.
+func TestSettingsHandler_PutRejectsChangedIdentity(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+	var before api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
+
+	for name, body := range map[string]string{
+		"changed endpoint": fmt.Sprintf(
+			`{"endpoint": "other.gateway.example.com", "proxy_address": %q, "enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 30}`,
+			before.ProxyAddress),
+		"changed proxy_address": fmt.Sprintf(
+			`{"endpoint": %q, "proxy_address": "us.proxy.netbird.io", "enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 30}`,
+			before.Endpoint),
+		"omitted identity": `{"enable_log_collection": false, "enable_prompt_collection": false, "redact_pii": false, "access_log_retention_days": 30}`,
+	} {
+		rec = f.do(t, http.MethodPut, "/agent-network/settings", body)
+		assert.Equal(t, http.StatusUnprocessableEntity, rec.Code,
+			"%s must be rejected: got %d body=%s", name, rec.Code, rec.Body.String())
+	}
+
+	// The rejected updates must not have applied anything — toggles included.
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, before.Endpoint, got.Endpoint, "rejected PUT must not change the endpoint")
+	assert.Equal(t, before.ProxyAddress, got.ProxyAddress, "rejected PUT must not change the proxy address")
+	assert.True(t, got.EnablePromptCollection, "rejected PUT must not apply its toggles")
+
+	// An uppercased echo of the assigned values still names the same host and
+	// must be accepted.
+	rec = f.do(t, http.MethodPut, "/agent-network/settings", fmt.Sprintf(
+		`{"endpoint": %q, "proxy_address": %q, "enable_log_collection": true, "enable_prompt_collection": true, "redact_pii": false, "access_log_retention_days": 30}`,
+		strings.ToUpper(before.Endpoint), strings.ToUpper(before.ProxyAddress)))
+	assert.Equal(t, http.StatusOK, rec.Code,
+		"an uppercased identity echo must be accepted: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_PutOmittedRetentionLandsAsZero documents a residual the
+// required-ness of access_log_retention_days does not remove. Marking the field
+// required changes the generated client type from *int to int, so a generated
+// client cannot omit it — but nothing validates OpenAPI required-ness at
+// runtime, so a hand-rolled body without the field still decodes as 0, which
+// the API documents as "keep indefinitely".
+//
+// That is the same latitude the three booleans already have, so it is left
+// consistent rather than special-cased. This test exists to make the gap
+// explicit: if request validation is ever added, this expectation is what
+// changes.
+func TestSettingsHandler_PutOmittedRetentionLandsAsZero(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "access_log_retention_days": 14}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+	var before api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
+
+	rec = f.do(t, http.MethodPut, "/agent-network/settings", fmt.Sprintf(
+		`{"endpoint": %q, "proxy_address": %q, "enable_log_collection": true, "enable_prompt_collection": false, "redact_pii": false}`,
+		before.Endpoint, before.ProxyAddress))
+	require.Equal(t, http.StatusOK, rec.Code, "update PUT must succeed: %s", rec.Body.String())
+
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	require.NotNil(t, got.AccessLogRetentionDays)
+	assert.Equal(t, 0, *got.AccessLogRetentionDays,
+		"a non-conforming body that omits retention still replaces it with the zero value")
+}
+
+// TestSettingsHandler_DeleteBeforeBootstrapIs404 pins that DELETE on an
+// account with no settings row is a 404, mirroring the PUT.
+func TestSettingsHandler_DeleteBeforeBootstrapIs404(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusNotFound, rec.Code,
+		"DELETE on an unbootstrapped account must 404: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_DeleteBlockedByProviders pins the first delete guard:
+// while any provider exists for the account, the delete is refused with 412
+// and the row survives. Providers route through the endpoint — the guard
+// keeps DELETE a bootstrap-repair operation rather than a way to abandon a
+// configured gateway.
+func TestSettingsHandler_DeleteBlockedByProviders(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "eu.proxy.netbird.io"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+	var before api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &before))
+
+	f.seedProvider(t, "prov-guard")
+
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusPreconditionFailed, rec.Code,
+		"delete with a provider present must be refused: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+	var got api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &got))
+	assert.Equal(t, before.Endpoint, got.Endpoint, "the refused delete must leave the row intact")
+}
+
+// TestSettingsHandler_DeleteBlockedByActiveProxy pins the second delete
+// guard: while a proxy is actively serving the endpoint — an active proxy
+// row declaring the endpoint hostname as its cluster address, the dedicated
+// shape — the delete is refused with 412. A proxy that has disconnected no
+// longer blocks: the guard is about a live serving path, not history.
+//
+// The proxy declares its address with mixed casing on purpose: Connect
+// stores the declared address verbatim while the settings row is normalized
+// lowercase, and hostnames are case-insensitive, so the guard must match
+// across the casing difference rather than be sidestepped by it.
+func TestSettingsHandler_DeleteBlockedByActiveProxy(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	const endpoint = "gw.dedicated.example.com"
+	rec := f.do(t, http.MethodPost, "/agent-network/settings", fmt.Sprintf(`{"endpoint": %q}`, endpoint))
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	now := time.Now()
+	accountID := testAccountID
+	proxyRow := &rpproxy.Proxy{
+		ID:             "proxy-guard",
+		SessionID:      "sess-1",
+		ClusterAddress: "GW.Dedicated.Example.Com",
+		AccountID:      &accountID,
+		LastSeen:       now,
+		ConnectedAt:    &now,
+		Status:         rpproxy.StatusConnected,
+	}
+	require.NoError(t, f.store.SaveProxy(context.Background(), proxyRow))
+
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusPreconditionFailed, rec.Code,
+		"delete with an active proxy at the endpoint must be refused: got %d body=%s", rec.Code, rec.Body.String())
+
+	// Once the proxy disconnects it no longer serves the endpoint, so the
+	// delete goes through.
+	require.NoError(t, f.store.DisconnectProxy(context.Background(), proxyRow.ID, proxyRow.SessionID))
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	assert.Equal(t, http.StatusOK, rec.Code,
+		"delete after the proxy disconnected must succeed: got %d body=%s", rec.Code, rec.Body.String())
+}
+
+// TestSettingsHandler_DeleteReleasesEndpointForFreshBootstrap pins the
+// full-reset semantic that gives replace-on-change clients (e.g. Terraform's
+// RequiresReplace) a real path: with both guards clear the delete succeeds,
+// the account reads as the defaults again, and a fresh bootstrap draws a
+// fresh label. The released hostname is not reserved — a fresh draw may even
+// legitimately re-pick it — so the assertions check the new row's shape, not
+// that the label differs.
+func TestSettingsHandler_DeleteReleasesEndpointForFreshBootstrap(t *testing.T) {
+	f := newAgentNetworkHandlerFixture(t)
+
+	rec := f.do(t, http.MethodPost, "/agent-network/settings",
+		`{"proxy_address": "eu.proxy.netbird.io", "enable_prompt_collection": true}`)
+	require.Equal(t, http.StatusOK, rec.Code, "bootstrap POST must succeed: %s", rec.Body.String())
+
+	rec = f.do(t, http.MethodDelete, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code,
+		"delete with both guards clear must succeed: got %d body=%s", rec.Code, rec.Body.String())
+
+	rec = f.do(t, http.MethodGet, "/agent-network/settings", "")
+	require.Equal(t, http.StatusOK, rec.Code)
+	var after api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &after))
+	assert.Empty(t, after.Endpoint, "a deleted account must read as unbootstrapped defaults")
+	assert.False(t, after.EnablePromptCollection, "the deleted row's toggles must not linger")
+
+	rec = f.do(t, http.MethodPost, "/agent-network/settings", `{"proxy_address": "eu.proxy.netbird.io"}`)
+	require.Equal(t, http.StatusOK, rec.Code, "re-bootstrap after delete must succeed: %s", rec.Body.String())
+	var second api.AgentNetworkSettings
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &second))
+	require.NotEmpty(t, second.Endpoint, "the fresh bootstrap must allocate an endpoint")
+	assert.True(t, strings.HasSuffix(second.Endpoint, ".eu.proxy.netbird.io"),
+		"the fresh endpoint must hang beneath the requested proxy address: %s", second.Endpoint)
+	assert.False(t, second.EnablePromptCollection,
+		"the fresh row must carry bootstrap defaults, not the deleted row's toggles")
+	assert.NotNil(t, second.CreatedAt, "the fresh row is persisted and carries timestamps")
+}