Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(cyclops-cs): add feature flag administration (#6821)

r33drichards3cf6f259da2a
diff --git a/libs/fleet/backend/auth/authz_feature_flags.rego b/libs/fleet/backend/auth/authz_feature_flags.rego
new file mode 100644
index 0000000000..2e4a29e0b7
--- /dev/null
+++ b/libs/fleet/backend/auth/authz_feature_flags.rego
@@ -0,0 +1,17 @@
+package authz_feature_flags
+
+import data.authz
+
+allow {
+ input.route == "/api/admin/feature-flags"
+ authz.is_interactive_client
+ input.user.azp == "cyclops-cs-spa"
+ authz.is_admin
+}
+
+allow {
+ input.route == "/api/admin/feature-flags/{key}"
+ authz.is_interactive_client
+ input.user.azp == "cyclops-cs-spa"
+ authz.is_admin
+}
diff --git a/libs/fleet/backend/auth/authz_feature_flags_test.rego b/libs/fleet/backend/auth/authz_feature_flags_test.rego
new file mode 100644
index 0000000000..de90fad4fe
--- /dev/null
+++ b/libs/fleet/backend/auth/authz_feature_flags_test.rego
@@ -0,0 +1,48 @@
+package authz_feature_flags_test
+
+import rego.v1
+
+import data.authz_base
+import data.authz_feature_flags
+
+route_allow if {
+ authz_base.allow
+ authz_feature_flags.allow
+}
+
+test_admin_spa_allowed if {
+ route_allow with input as input_for({"sub": "admin-1", "azp": "cyclops-cs-spa"})
+}
+
+test_cli_denied if {
+ not route_allow with input as input_for({"sub": "admin-1", "azp": "cua-cli"})
+}
+
+test_user_key_denied if {
+ not route_allow with input as input_for({"sub": "admin-1", "azp": "ukey-abc", "principal_type": "user_key"})
+}
+
+test_github_oidc_denied if {
+ not route_allow with input as input_for({"sub": "admin-1", "azp": "github-actions"})
+}
+
+test_oauth2_proxy_denied if {
+ not route_allow with input as input_for({"sub": "admin-1", "azp": "oauth2-proxy"})
+}
+
+test_empty_subject_denied if {
+ not route_allow with input as input_for({"sub": "", "azp": "cyclops-cs-spa"})
+}
+
+test_ordinary_spa_denied if {
+ not route_allow with input as input_for({"sub": "ordinary-user", "azp": "cyclops-cs-spa"})
+}
+
+input_for(user) := {
+ "route": "/api/admin/feature-flags/{key}",
+ "method": "PUT",
+ "path": "/api/admin/feature-flags/example",
+ "params": {"key": "example"},
+ "user": object.union({"namespace": "", "email": "", "principal_type": ""}, user),
+ "flags": {"admin_subs": ["admin-1"]},
+}
diff --git a/libs/fleet/backend/auth/flags_test.go b/libs/fleet/backend/auth/flags_test.go
index 55b961878d..f4a399d5fd 100644
--- a/libs/fleet/backend/auth/flags_test.go
+++ b/libs/fleet/backend/auth/flags_test.go
@@ -2,6 +2,9 @@ package auth
import (
"context"
+ "net/http"
+ "net/http/httptest"
+ "reflect"
"testing"
"time"
@@ -14,13 +17,129 @@ func resetFlagsCache() {
flagsMu.Lock()
flagsValue = nil
flagsExp = time.Time{}
+ flagsGeneration = 0
flagsMu.Unlock()
+ flagsSF.Forget("flags")
+}
+
+func TestInvalidateFeatureFlagsPreventsInFlightRefreshFromPublishingStaleData(t *testing.T) {
+ resetFlagsCache()
+ originalCompute := computeFlagsDataFn
+ t.Cleanup(func() { computeFlagsDataFn = originalCompute })
+
+ started := make(chan struct{})
+ release := make(chan struct{})
+ var calls int
+ computeFlagsDataFn = func(context.Context) map[string]interface{} {
+ calls++
+ if calls == 1 {
+ close(started)
+ <-release
+ return map[string]interface{}{"admin_subs": []interface{}{"stale-admin"}}
+ }
+ return map[string]interface{}{"admin_subs": []interface{}{"fresh-admin"}}
+ }
+
+ done := make(chan map[string]interface{}, 1)
+ go func() { done <- flagsData() }()
+ <-started
+ InvalidateFeatureFlags()
+ close(release)
+ if got := <-done; !reflect.DeepEqual(got, map[string]interface{}{"admin_subs": []interface{}{"stale-admin"}}) {
+ t.Fatalf("in-flight caller result = %#v", got)
+ }
+
+ flagsMu.Lock()
+ cached := flagsValue
+ flagsMu.Unlock()
+ if cached != nil {
+ t.Fatalf("stale refresh republished cache = %#v", cached)
+ }
+
+ fresh := flagsData()
+ if !reflect.DeepEqual(fresh, map[string]interface{}{"admin_subs": []interface{}{"fresh-admin"}}) {
+ t.Fatalf("next caller result = %#v, want fresh generation", fresh)
+ }
+ if calls != 2 {
+ t.Fatalf("compute calls = %d, want 2", calls)
+ }
+ if cachedAgain := flagsData(); !reflect.DeepEqual(cachedAgain, fresh) || calls != 2 {
+ t.Fatalf("cached fresh result = %#v calls=%d", cachedAgain, calls)
+ }
}
// TestExportedEvalsEndToEnd wires the real path: SimpleEnvProvider →
// flagsData() → input.flags → the prepared OPA query. It guards the
// glue (flag discovery, env→key mapping, result decoding) that the
// pure-policy tests in policy_test.go don't touch.
+func TestFeatureFlagAdminMiddlewareBypassesAnotherReplicasStaleAdminCache(t *testing.T) {
+ LoadOpa()
+ resetFlagsCache()
+ originalCompute := computeFlagsDataFn
+ originalFresh := computeFreshAdminFlagsFn
+ t.Cleanup(func() {
+ computeFlagsDataFn = originalCompute
+ computeFreshAdminFlagsFn = originalFresh
+ })
+
+ // Replica B cached membership before replica A removed the administrator.
+ computeFlagsDataFn = func(context.Context) map[string]interface{} {
+ return map[string]interface{}{"admin_subs": []interface{}{"removed-admin"}}
+ }
+ if got := flagsData(); !reflect.DeepEqual(got["admin_subs"], []interface{}{"removed-admin"}) {
+ t.Fatalf("stale replica cache = %#v", got)
+ }
+
+ // The shared provider now reflects replica A's committed mutation. Replica
+ // B's process-local invalidator was never called.
+ var freshCalls int
+ computeFreshAdminFlagsFn = func(context.Context) map[string]interface{} {
+ freshCalls++
+ return map[string]interface{}{"admin_subs": []interface{}{}}
+ }
+
+ policy := surfacePolicies["feature-flags"]
+ handler := PolicyMiddleware(policy.tree(), policy.options...)(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+ t.Fatal("removed administrator reached feature flag handler")
+ }))
+ request := routeRequest(http.MethodGet, "/api/admin/feature-flags", "/api/admin/feature-flags", nil, "")
+ request = request.WithContext(context.WithValue(request.Context(), UserKey, &User{ID: "removed-admin", AZP: "cyclops-cs-spa"}))
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+
+ if response.Code != http.StatusForbidden {
+ t.Fatalf("status = %d, want 403; body = %s", response.Code, response.Body.String())
+ }
+ if freshCalls != 1 {
+ t.Fatalf("fresh admin provider calls = %d, want 1", freshCalls)
+ }
+ if got := flagsData(); !reflect.DeepEqual(got["admin_subs"], []interface{}{"removed-admin"}) {
+ t.Fatalf("unrelated TTL cache changed = %#v", got)
+ }
+
+ computeFreshAdminFlagsFn = func(context.Context) map[string]interface{} {
+ freshCalls++
+ return map[string]interface{}{"admin_subs": []interface{}{"current-admin"}}
+ }
+ allowed := PolicyMiddleware(policy.tree(), policy.options...)(http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+ isAdmin, err := EvalIsAdminFresh(request.Context(), &User{ID: "current-admin", AZP: "cyclops-cs-spa"})
+ if err != nil || !isAdmin {
+ t.Fatalf("handler defense check = %v, %v", isAdmin, err)
+ }
+ w.WriteHeader(http.StatusNoContent)
+ }))
+ request = routeRequest(http.MethodGet, "/api/admin/feature-flags", "/api/admin/feature-flags", nil, "")
+ request = request.WithContext(context.WithValue(request.Context(), UserKey, &User{ID: "current-admin", AZP: "cyclops-cs-spa"}))
+ response = httptest.NewRecorder()
+ allowed.ServeHTTP(response, request)
+ if response.Code != http.StatusNoContent {
+ t.Fatalf("allowed status = %d; body = %s", response.Code, response.Body.String())
+ }
+ if freshCalls != 2 {
+ t.Fatalf("fresh provider calls after middleware and handler = %d, want 2 total", freshCalls)
+ }
+}
+
func TestExportedEvalsEndToEnd(t *testing.T) {
t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-sub"]`)
t.Setenv("CYCLOPS_CS_CHAT_SUBS", `["chat-sub"]`)
@@ -131,6 +250,31 @@ func TestComputeFlagsDataLoadsOnlyOPAStringListFlags(t *testing.T) {
}
}
+func TestComputeFlagsDataFailsClosedOnAuthorizationListTypeMismatch(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-sub"]`)
+ t.Setenv("CYCLOPS_CS_CHAT_SUBS", "true")
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup dev provider: %v", err)
+ }
+
+ got := computeFlagsData(context.Background())
+ if len(got) != 0 {
+ t.Fatalf("computeFlagsData() = %v, want empty flags after authorization list type mismatch", got)
+ }
+}
+
+func TestComputeFreshAdminFlagsFailsClosedOnTypeMismatch(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", "true")
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup dev provider: %v", err)
+ }
+
+ got := computeFreshAdminFlags(context.Background())
+ if admins := asStrings(got["admin_subs"]); len(admins) != 0 {
+ t.Fatalf("admin_subs = %v, want empty allowlist after type mismatch", admins)
+ }
+}
+
func asStrings(v any) []string {
items, ok := v.([]interface{})
if !ok {
diff --git a/libs/fleet/backend/auth/middlewares.go b/libs/fleet/backend/auth/middlewares.go
index 99f8d99a0a..874f89b7a4 100644
--- a/libs/fleet/backend/auth/middlewares.go
+++ b/libs/fleet/backend/auth/middlewares.go
@@ -23,7 +23,10 @@ import (
type ctxKey int
-const UserKey ctxKey = 1
+const (
+ UserKey ctxKey = iota + 1
+ freshAdminFlagsKey
+)
var (
opaAdminQuery *rego.PreparedEvalQuery
@@ -61,18 +64,19 @@ var surfacePolicySources = map[string]struct {
filename string
source string
}{
- "authz-base": {"authz_base.rego", authzBasePolicy},
- "authz-keys": {"authz_keys.rego", authzKeysPolicy},
- "authz-config": {"authz_config.rego", authzConfigPolicy},
- "authz-chat": {"authz_chat.rego", authzChatPolicy},
- "authz-billing": {"authz_billing.rego", authzBillingPolicy},
- "authz-usage": {"authz_usage.rego", authzUsagePolicy},
- "authz-namespaces": {"authz_namespaces.rego", authzNamespacesPolicy},
- "authz-github-trust": {"authz_github_trust.rego", authzGitHubTrustPolicy},
- "authz-user-keys": {"authz_user_keys.rego", authzUserKeysPolicy},
- "authz-k8s": {"authz_k8s.rego", authzK8sPolicy},
- "authz-svc": {"authz_svc.rego", authzSvcPolicy},
- "authz-state-query": {"authz_state_query.rego", authzStateQueryPolicy},
+ "authz-base": {"authz_base.rego", authzBasePolicy},
+ "authz-keys": {"authz_keys.rego", authzKeysPolicy},
+ "authz-config": {"authz_config.rego", authzConfigPolicy},
+ "authz-chat": {"authz_chat.rego", authzChatPolicy},
+ "authz-billing": {"authz_billing.rego", authzBillingPolicy},
+ "authz-usage": {"authz_usage.rego", authzUsagePolicy},
+ "authz-namespaces": {"authz_namespaces.rego", authzNamespacesPolicy},
+ "authz-github-trust": {"authz_github_trust.rego", authzGitHubTrustPolicy},
+ "authz-user-keys": {"authz_user_keys.rego", authzUserKeysPolicy},
+ "authz-k8s": {"authz_k8s.rego", authzK8sPolicy},
+ "authz-svc": {"authz_svc.rego", authzSvcPolicy},
+ "authz-state-query": {"authz_state_query.rego", authzStateQueryPolicy},
+ "authz-feature-flags": {"authz_feature_flags.rego", authzFeatureFlagsPolicy},
}
//go:embed authz_base.rego
@@ -140,9 +144,10 @@ const (
const flagsTTL = 1 * time.Minute
var (
- flagsMu sync.Mutex
- flagsValue map[string]interface{}
- flagsExp time.Time
+ flagsMu sync.Mutex
+ flagsValue map[string]interface{}
+ flagsExp time.Time
+ flagsGeneration uint64
// flagsSF collapses concurrent refreshes (e.g. a burst of requests
// arriving right after expiry, or at cold start) into a single
@@ -155,8 +160,22 @@ var (
// client name to one place.
ffClientOnce sync.Once
ffClient *openfeature.Client
+
+ computeFlagsDataFn = computeFlagsData
+ computeFreshAdminFlagsFn = computeFreshAdminFlags
)
+// InvalidateFeatureFlags clears the resolved auth flag cache so the next
+// authorization request observes a successful feature-flag mutation.
+func InvalidateFeatureFlags() {
+ flagsMu.Lock()
+ flagsValue = nil
+ flagsExp = time.Time{}
+ flagsGeneration++
+ flagsMu.Unlock()
+ flagsSF.Forget("flags")
+}
+
// flagsData returns the resolved feature-flag map (admin_subs, …), TTL-cached
// at flagsTTL. On a hit it returns the cached map under the lock; on a miss it
// resolves via OpenFeature behind a singleflight so only one goroutine fans out
@@ -186,21 +205,67 @@ func flagsData() map[string]interface{} {
flagsMu.Unlock()
return cached, nil
}
+ generation := flagsGeneration
flagsMu.Unlock()
// Resolve with a detached context so a single caller's cancelled
// request can't abort the refresh shared by everyone else.
- result := computeFlagsData(context.Background())
+ result := computeFlagsDataFn(context.Background())
flagsMu.Lock()
- flagsValue = result
- flagsExp = time.Now().Add(flagsTTL)
+ if flagsGeneration == generation {
+ flagsValue = result
+ flagsExp = time.Now().Add(flagsTTL)
+ }
flagsMu.Unlock()
return result, nil
})
return v.(map[string]interface{})
}
+func computeFreshAdminFlags(ctx context.Context) map[string]interface{} {
+ ffClientOnce.Do(func() {
+ ffClient = openfeature.NewClient("cyclops-cs-auth")
+ })
+ key := flagPrefix + "admin-subs"
+ admins, err := loadStringList(ctx, ffClient, key)
+ if err != nil {
+ slog.Warn("auth: fresh admin flag load failed; denying admin access", "flag", key, "err", err)
+ admins = []interface{}{}
+ }
+ return map[string]interface{}{
+ "admin_subs": admins,
+ }
+}
+
+func freshAdminFlags(ctx context.Context) map[string]interface{} {
+ if flags, ok := ctx.Value(freshAdminFlagsKey).(map[string]interface{}); ok {
+ return flags
+ }
+ return computeFreshAdminFlagsFn(ctx)
+}
+
+func withFreshAdminFlags(request *http.Request) *http.Request {
+ if _, ok := request.Context().Value(freshAdminFlagsKey).(map[string]interface{}); ok {
+ return request
+ }
+ flags := computeFreshAdminFlagsFn(request.Context())
+ return request.WithContext(context.WithValue(request.Context(), freshAdminFlagsKey, flags))
+}
+
+func authorizationFlags(ctx context.Context) map[string]interface{} {
+ if fresh, ok := ctx.Value(freshAdminFlagsKey).(map[string]interface{}); ok {
+ cached := flagsData()
+ flags := make(map[string]interface{}, len(cached)+1)
+ for key, value := range cached {
+ flags[key] = value
+ }
+ flags["admin_subs"] = fresh["admin_subs"]
+ return flags
+ }
+ return flagsData()
+}
+
func computeFlagsData(ctx context.Context) map[string]interface{} {
ffClientOnce.Do(func() {
ffClient = openfeature.NewClient("cyclops-cs-auth")
@@ -327,26 +392,33 @@ func LoadOpa() {
// (data.authz.is_admin). is_admin only reads input.user and input.flags, so
// no route/method/path is needed.
func EvalIsAdmin(ctx context.Context, user *User) (bool, error) {
- return evalUserDecision(ctx, user, opaAdminQuery)
+ return evalUserDecision(ctx, user, opaAdminQuery, flagsData())
+}
+
+// EvalIsAdminFresh bypasses the process-local admin membership cache. If the
+// feature-admin middleware already resolved membership for this request, the
+// handler reuses that result instead of issuing a duplicate provider call.
+func EvalIsAdminFresh(ctx context.Context, user *User) (bool, error) {
+ return evalUserDecision(ctx, user, opaAdminQuery, freshAdminFlags(ctx))
}
// EvalChatEnabled returns the restricted-mode chat decision: administrators
// and users listed in input.flags.chat_subs are enabled.
func EvalChatEnabled(ctx context.Context, user *User) (bool, error) {
- return evalUserDecision(ctx, user, opaChatQuery)
+ return evalUserDecision(ctx, user, opaChatQuery, flagsData())
}
func EvalUsageEnabled(ctx context.Context, user *User) (bool, error) {
- return evalUserDecision(ctx, user, opaUsageQuery)
+ return evalUserDecision(ctx, user, opaUsageQuery, flagsData())
}
-func evalUserDecision(ctx context.Context, user *User, query *rego.PreparedEvalQuery) (bool, error) {
+func evalUserDecision(ctx context.Context, user *User, query *rego.PreparedEvalQuery, flags map[string]interface{}) (bool, error) {
if user == nil {
return false, nil
}
input := map[string]interface{}{
"user": buildUserInput(user),
- "flags": flagsData(),
+ "flags": flags,
}
res, err := query.Eval(ctx, rego.EvalInput(input))
if err != nil {
@@ -547,3 +619,6 @@ func GetUser(ctx context.Context) *User {
}
return nil
}
+
+//go:embed authz_feature_flags.rego
+var authzFeatureFlagsPolicy string
diff --git a/libs/fleet/backend/auth/policy_characterization_test.go b/libs/fleet/backend/auth/policy_characterization_test.go
index 2c318ed00e..4f583dee89 100644
--- a/libs/fleet/backend/auth/policy_characterization_test.go
+++ b/libs/fleet/backend/auth/policy_characterization_test.go
@@ -169,6 +169,8 @@ func characterizationCases() map[string][]routeCase {
simple("/api/namespaces", "/api/namespaces")
simple("/api/user-keys", "/api/user-keys")
simple("/api/github-trust-policies", "/api/github-trust-policies")
+ simple("/api/admin/feature-flags", "/api/admin/feature-flags")
+ cases["/api/admin/feature-flags/{key}"] = []routeCase{{name: "key", params: map[string]string{"key": "example"}, path: "/api/admin/feature-flags/example"}}
withID := func(route, prefix string) {
cases[route] = []routeCase{{
diff --git a/libs/fleet/backend/auth/policy_middleware.go b/libs/fleet/backend/auth/policy_middleware.go
index 83a948ce21..50d68f8ed8 100644
--- a/libs/fleet/backend/auth/policy_middleware.go
+++ b/libs/fleet/backend/auth/policy_middleware.go
@@ -4,6 +4,7 @@ import (
"bytes"
"context"
"crypto/sha256"
+ "encoding/json"
"errors"
"fmt"
"io"
@@ -14,6 +15,7 @@ import (
"strings"
"sync"
+ "cyclops-cs-backend/featureflagadmin"
"cyclops-cs-backend/middlewares"
)
@@ -245,7 +247,7 @@ func newRequestPolicyInput(request *http.Request, bodyBudget int64) *requestPoli
"route": route,
"params": params,
"user": buildUserInput(user),
- "flags": flagsData(),
+ "flags": authorizationFlags(request.Context()),
},
}
}
@@ -387,7 +389,10 @@ func (input *requestPolicyInput) loadBody(maxBytes int64) ([]byte, error) {
type MiddlewareOption func(*middlewareConfig)
type middlewareConfig struct {
- deniedMessage string
+ deniedMessage string
+ deniedAudit *deniedAuditConfig
+ adminAPIErrors bool
+ freshAdminAuth bool
// pipeline names the optimizer passes to run before compiling. pipelineSet
// distinguishes "run the default pipeline" from "run nothing": the two are
// both an empty slice, and only the flag tells them apart.
@@ -395,12 +400,38 @@ type middlewareConfig struct {
pipelineSet bool
}
+func WithFreshAdminAuthorization() MiddlewareOption {
+ return func(config *middlewareConfig) {
+ config.freshAdminAuth = true
+ }
+}
+
+func WithAdminAPIErrorResponses() MiddlewareOption {
+ return func(config *middlewareConfig) {
+ config.adminAPIErrors = true
+ }
+}
+
func WithDeniedMessage(message string) MiddlewareOption {
return func(config *middlewareConfig) {
config.deniedMessage = message
}
}
+type deniedAuditConfig struct {
+ event string
+ maxBytes int64
+}
+
+// WithDeniedAudit records a bounded, typed summary of rejected mutation
+// attempts. It is intentionally generic so every privileged surface can use
+// the same safe behavior without retaining raw request bodies.
+func WithDeniedAudit(event string, maxBytes int64) MiddlewareOption {
+ return func(config *middlewareConfig) {
+ config.deniedAudit = &deniedAuditConfig{event: event, maxBytes: maxBytes}
+ }
+}
+
// WithPipeline overrides the optimizer passes for this middleware.
// WithPipeline() with no arguments disables optimization entirely.
//
@@ -435,16 +466,22 @@ func PolicyMiddleware(expression Node, options ...MiddlewareOption) Middleware {
}
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, request *http.Request) {
+ if config.freshAdminAuth {
+ request = withFreshAdminFlags(request)
+ }
verdict := compiled.eval(request.Context(), newRequestPolicyInput(request, compiled.bodyBudget))
switch verdict.truth {
case truthTrue:
next.ServeHTTP(w, request)
case truthFalse:
+ if config.deniedAudit != nil && request.Method != http.MethodGet {
+ logRejectedMutation(request, *config.deniedAudit, "not_admin")
+ }
message := verdict.reason
if message == "" {
message = config.deniedMessage
}
- writeJSONErr(w, http.StatusForbidden, message)
+ writePolicyError(w, config, http.StatusForbidden, "not_admin", message)
default:
// truthError, and deliberately also any truth value a future
// change adds: an undecidable policy must fail closed rather
@@ -458,8 +495,14 @@ func PolicyMiddleware(expression Node, options ...MiddlewareOption) Middleware {
var factErr *FactUnavailableError
switch {
case errors.As(verdict.err, &bodyErr):
- writeJSONErr(w, http.StatusBadRequest, "could not inspect request")
+ if config.deniedAudit != nil && request.Method != http.MethodGet {
+ logRejectedMutation(request, *config.deniedAudit, "invalid_request")
+ }
+ writePolicyError(w, config, http.StatusBadRequest, "invalid_request", "could not inspect request")
case errors.As(verdict.err, &factErr):
+ if config.deniedAudit != nil && request.Method != http.MethodGet {
+ logRejectedMutation(request, *config.deniedAudit, "authorization_unavailable")
+ }
// A dependency the policy consults is down. Warn rather than
// Error: nothing here is broken, and the alert this should
// raise is the dependency's, not ours.
@@ -469,16 +512,94 @@ func PolicyMiddleware(expression Node, options ...MiddlewareOption) Middleware {
"facts", factErr.Namespace,
"route", request.Context().Value(routeKey),
"traceId", request.Context().Value(middlewares.ContextKey("traceId")))
- writeJSONErr(w, http.StatusBadGateway, "authorization check unavailable")
+ writePolicyError(w, config, http.StatusBadGateway, "authorization_unavailable", "authorization check unavailable")
default:
+ if config.deniedAudit != nil && request.Method != http.MethodGet {
+ logRejectedMutation(request, *config.deniedAudit, "policy_error")
+ }
slog.Error("opa: policy evaluation failed",
"class", "policy_evaluation_failed",
"retryable", false,
"route", request.Context().Value(routeKey),
"traceId", request.Context().Value(middlewares.ContextKey("traceId")))
- writeJSONErr(w, http.StatusInternalServerError, "policy evaluation failed")
+ writePolicyError(w, config, http.StatusInternalServerError, "policy_error", "policy evaluation failed")
}
}
})
}
}
+
+func writePolicyError(w http.ResponseWriter, config middlewareConfig, status int, code, message string) {
+ if !config.adminAPIErrors {
+ writeJSONErr(w, status, message)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(status)
+ _ = json.NewEncoder(w).Encode(map[string]any{"code": code, "message": message})
+}
+
+func logDeniedMutation(request *http.Request, config deniedAuditConfig) {
+ logRejectedMutation(request, config, "not_admin")
+}
+
+func logRejectedMutation(request *http.Request, config deniedAuditConfig, reason string) {
+ details := map[string]any{}
+ parseFailure := ""
+ if request.Body != nil && config.maxBytes > 0 {
+ body, err := io.ReadAll(io.LimitReader(request.Body, config.maxBytes))
+ var extra [1]byte
+ extraCount, extraErr := request.Body.Read(extra[:])
+ request.Body = splicedBody{Reader: io.MultiReader(bytes.NewReader(body), bytes.NewReader(extra[:extraCount]), request.Body), Closer: request.Body}
+ switch {
+ case err != nil:
+ parseFailure = "read_failed"
+ case extraErr != io.EOF || extraCount != 0:
+ parseFailure = "body_too_large"
+ case len(body) > 0:
+ if err := json.Unmarshal(body, &details); err != nil {
+ parseFailure = "invalid_json"
+ }
+ }
+ }
+ user, _ := request.Context().Value(UserKey).(*User)
+ key := request.PathValue("key")
+ if key == "" && request.Method == http.MethodPost && parseFailure == "" {
+ if bodyKey, ok := details["key"].(string); ok && bodyKey != "" && featureflagadmin.BoundedAuditKey(bodyKey) == bodyKey {
+ key = bodyKey
+ }
+ }
+ attrs := []any{
+ "event", config.event,
+ "actor", "",
+ "actor_email", "",
+ "principal_type", "",
+ "operation", strings.ToLower(request.Method),
+ "path", featureflagadmin.BoundedAuditPath(request.URL.Path, request.PathValue("key")),
+ "traceId", request.Context().Value(middlewares.ContextKey("traceId")),
+ "result", "rejected",
+ "reason", reason,
+ }
+ if key != "" {
+ attrs = append(attrs, "key", featureflagadmin.BoundedAuditKey(key))
+ }
+ if user != nil {
+ attrs[3] = user.ID
+ attrs[5] = user.Email
+ attrs[7] = user.PrincipalType
+ }
+ if parseFailure != "" {
+ attrs = append(attrs, "parse_failure", parseFailure)
+ } else {
+ if value, ok := details["value"]; ok {
+ attrs = append(attrs, "attempted_value", value)
+ }
+ if valueType, ok := details["value_type"]; ok {
+ attrs = append(attrs, "value_type", valueType)
+ }
+ if expectedVersion, ok := details["expected_version"]; ok {
+ attrs = append(attrs, "expected_version", expectedVersion)
+ }
+ }
+ slog.Warn("authorization mutation rejected", attrs...)
+}
diff --git a/libs/fleet/backend/auth/policy_middleware_test.go b/libs/fleet/backend/auth/policy_middleware_test.go
index c51febaac1..17b923783f 100644
--- a/libs/fleet/backend/auth/policy_middleware_test.go
+++ b/libs/fleet/backend/auth/policy_middleware_test.go
@@ -813,6 +813,255 @@ allow { input.body == "12345" }
}
}
+func TestPolicyMiddlewareFeatureFlagErrorsUseAdminAPIEnvelope(t *testing.T) {
+ cases := []struct {
+ name string
+ expression Node
+ body string
+ wantStatus int
+ wantCode string
+ }{
+ {name: "denied", expression: Policy(Inline("admin-envelope-deny.rego", "package admin_envelope_deny\ndefault allow = false\n"), Query("data.admin_envelope_deny.allow")), wantStatus: http.StatusForbidden, wantCode: "not_admin"},
+ {name: "invalid request", expression: Policy(Inline("admin-envelope-body.rego", `package admin_envelope_body
+allow { input.body == "ok" }
+`), Query("data.admin_envelope_body.allow"), WithRawBody(2)), body: "oversized", wantStatus: http.StatusBadRequest, wantCode: "invalid_request"},
+ {name: "authorization unavailable", expression: Policy(Inline("admin-envelope-facts.rego", `package admin_envelope_facts
+allow { input.facts.user.allowed }
+`), Query("data.admin_envelope_facts.allow"), WithFacts("user", &testFactProvider{cacheKey: "admin-envelope-unavailable", err: &FactUnavailableError{Namespace: "user", Err: errors.New("database unavailable")}})), wantStatus: http.StatusBadGateway, wantCode: "authorization_unavailable"},
+ {name: "policy error", expression: Policy(Inline("admin-envelope-error.rego", undecidablePolicy), Query("data.undecidable.allow")), wantStatus: http.StatusInternalServerError, wantCode: "policy_error"},
+ }
+ for _, testCase := range cases {
+ t.Run(testCase.name, func(t *testing.T) {
+ handler := PolicyMiddleware(testCase.expression, WithDeniedAudit("feature_flag_admin", 64<<10), WithAdminAPIErrorResponses())(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+ t.Fatal("failed policy request reached handler")
+ }))
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, httptest.NewRequest(http.MethodPost, "/api/admin/feature-flags", strings.NewReader(testCase.body)))
+ if response.Code != testCase.wantStatus {
+ t.Fatalf("status = %d, want %d; body = %s", response.Code, testCase.wantStatus, response.Body.String())
+ }
+ var body map[string]any
+ if err := json.Unmarshal(response.Body.Bytes(), &body); err != nil {
+ t.Fatal(err)
+ }
+ if body["code"] != testCase.wantCode || body["message"] == "" || body["error"] != nil {
+ t.Fatalf("body = %#v", body)
+ }
+ })
+ }
+}
+
+func TestPolicyMiddlewareUnrelatedRouteKeepsLegacyErrorEnvelope(t *testing.T) {
+ denied := Policy(Inline("legacy-envelope.rego", "package legacy_envelope\ndefault allow = false\n"), Query("data.legacy_envelope.allow"))
+ handler := PolicyMiddleware(denied)(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, httptest.NewRequest(http.MethodPost, "/api/keys", nil))
+ if got, want := response.Body.String(), `{"error":"forbidden"}`+"\n"; got != want {
+ t.Fatalf("body = %q, want %q", got, want)
+ }
+}
+
+func TestPolicyMiddlewareDeniedAuditCapturesBoundedMutationSummary(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ denied := Policy(Inline("deny.rego", "package denied\ndefault allow = false\n"), Query("data.denied.allow"))
+ handler := PolicyMiddleware(denied, WithDeniedAudit("feature_flag_admin", 64<<10))(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+ t.Fatal("denied request reached handler")
+ }))
+ request := httptest.NewRequest(http.MethodPut, "/api/admin/feature-flags/enabled", strings.NewReader(`{"value_type":"boolean","value":true,"expected_version":7}`))
+ request.SetPathValue("key", "enabled")
+ request = request.WithContext(context.WithValue(request.Context(), UserKey, &User{ID: "admin-1", Email: "[email protected]", PrincipalType: PrincipalTypeUser}))
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+
+ if response.Code != http.StatusForbidden {
+ t.Fatalf("status = %d, want 403", response.Code)
+ }
+ line := logs.String()
+ for _, want := range []string{`"event":"feature_flag_admin"`, `"actor":"admin-1"`, `"operation":"put"`, `"key":"enabled"`, `"attempted_value":true`, `"expected_version":7`, `"result":"rejected"`, `"reason":"not_admin"`} {
+ if !strings.Contains(line, want) {
+ t.Fatalf("audit log missing %s: %s", want, line)
+ }
+ }
+}
+
+func TestPolicyMiddlewareDeniedAuditBoundsInvalidURLIdentifiers(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ denied := Policy(Inline("deny-invalid-key.rego", "package deny_invalid_key\ndefault allow = false\n"), Query("data.deny_invalid_key.allow"))
+ handler := PolicyMiddleware(denied, WithDeniedAudit("feature_flag_admin", 64<<10))(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+ t.Fatal("denied request reached handler")
+ }))
+ invalidKey := strings.Repeat("Sensitive/", 40)
+ request := httptest.NewRequest(http.MethodPut, "/api/admin/feature-flags/"+invalidKey, strings.NewReader(`{"value_type":"boolean","value":true,"expected_version":7}`))
+ request.SetPathValue("key", invalidKey)
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+
+ if response.Code != http.StatusForbidden {
+ t.Fatalf("status = %d, want 403", response.Code)
+ }
+ var event map[string]any
+ decoder := json.NewDecoder(bytes.NewReader(logs.Bytes()))
+ for decoder.More() {
+ var record map[string]any
+ if err := decoder.Decode(&record); err != nil {
+ t.Fatalf("decode audit: %v; logs=%s", err, logs.String())
+ }
+ if record["event"] == "feature_flag_admin" {
+ event = record
+ break
+ }
+ }
+ if event == nil {
+ t.Fatalf("feature flag audit missing: %s", logs.String())
+ }
+ for _, field := range []string{"key", "path"} {
+ value, _ := event[field].(string)
+ if !strings.HasPrefix(value, "sha256:") || len(value) > 80 {
+ t.Errorf("%s = %q, want bounded SHA-256 identifier", field, value)
+ }
+ }
+ if strings.Contains(logs.String(), invalidKey) || strings.Contains(logs.String(), request.URL.Path) {
+ t.Fatalf("audit leaked invalid URL identifier: %s", logs.String())
+ }
+}
+
+func TestPolicyMiddlewareDeniedCreateAuditUsesOnlySafeBodyKey(t *testing.T) {
+ denied := Policy(Inline("deny-create-key.rego", "package deny_create_key\ndefault allow = false\n"), Query("data.deny_create_key.allow"))
+ for _, testCase := range []struct {
+ name string
+ body string
+ wantKey string
+ }{
+ {name: "safe decoded key", body: `{"key":"enabled","value_type":"boolean","value":true}`, wantKey: "enabled"},
+ {name: "invalid decoded key", body: `{"key":"Sensitive/key","value_type":"boolean","value":true}`},
+ {name: "non-string decoded key", body: `{"key":7,"value_type":"boolean","value":true}`},
+ } {
+ t.Run(testCase.name, func(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+ handler := PolicyMiddleware(denied, WithDeniedAudit("feature_flag_admin", 64<<10))(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+ t.Fatal("denied request reached handler")
+ }))
+ handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/api/admin/feature-flags", strings.NewReader(testCase.body)))
+ var event map[string]any
+ if err := json.Unmarshal(logs.Bytes(), &event); err != nil {
+ t.Fatalf("decode audit: %v; logs=%s", err, logs.String())
+ }
+ if got, present := event["key"]; testCase.wantKey == "" {
+ if present {
+ t.Fatalf("key = %#v, want omitted; logs=%s", got, logs.String())
+ }
+ } else if got != testCase.wantKey {
+ t.Fatalf("key = %#v, want %q; logs=%s", got, testCase.wantKey, logs.String())
+ }
+ if got, _ := event["key"].(string); got == "/api/admin/feature-flags" {
+ t.Fatalf("collection URL used as key: %s", logs.String())
+ }
+ })
+ }
+}
+
+func TestPolicyMiddlewareDeniedAuditBoundsOversizedBodyAndSkipsGET(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+ denied := Policy(Inline("deny-large.rego", "package denied_large\ndefault allow = false\n"), Query("data.denied_large.allow"))
+ handler := PolicyMiddleware(denied, WithDeniedAudit("feature_flag_admin", 8))(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+ handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/api/admin/feature-flags", strings.NewReader(`{"value":"this is deliberately too large"}`)))
+ if !strings.Contains(logs.String(), `"parse_failure":"body_too_large"`) || strings.Contains(logs.String(), "deliberately too large") {
+ t.Fatalf("oversized audit = %s", logs.String())
+ }
+ logs.Reset()
+ handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/api/admin/feature-flags", nil))
+ if logs.Len() != 0 {
+ t.Fatalf("GET denial unexpectedly audited: %s", logs.String())
+ }
+}
+
+func TestDeniedAuditRestoresEntireOversizedBody(t *testing.T) {
+ original := []byte("0123456789abcdefghijklmnopqrstuvwxyz")
+ request := httptest.NewRequest(http.MethodPost, "/api/admin/feature-flags", bytes.NewReader(original))
+ logDeniedMutation(request, deniedAuditConfig{event: "feature_flag_admin", maxBytes: 8})
+ restored, err := io.ReadAll(request.Body)
+ if err != nil {
+ t.Fatalf("read restored body: %v", err)
+ }
+ if !bytes.Equal(restored, original) {
+ t.Fatalf("restored body = %q, want %q", restored, original)
+ }
+}
+
+func TestPolicyMiddlewareAuditsEveryMutationEvaluationErrorExactlyOnce(t *testing.T) {
+ cases := []struct {
+ name string
+ expression Node
+ body string
+ wantStatus int
+ wantReason string
+ }{
+ {
+ name: "invalid request body",
+ expression: Policy(Inline("audit-body.rego", `package audit_body
+allow { input.body == "ok" }
+`), Query("data.audit_body.allow"), WithRawBody(2)),
+ body: "oversized",
+ wantStatus: http.StatusBadRequest,
+ wantReason: "invalid_request",
+ },
+ {
+ name: "authorization dependency unavailable",
+ expression: Policy(Inline("audit-facts.rego", `package audit_facts
+allow { input.facts.user.allowed }
+`), Query("data.audit_facts.allow"), WithFacts("user", &testFactProvider{cacheKey: "audit-unavailable", err: &FactUnavailableError{Namespace: "user", Err: errors.New("database unavailable")}})),
+ wantStatus: http.StatusBadGateway,
+ wantReason: "authorization_unavailable",
+ },
+ {
+ name: "policy evaluation error",
+ expression: Policy(Inline("audit-undecidable.rego", undecidablePolicy), Query("data.undecidable.allow")),
+ wantStatus: http.StatusInternalServerError,
+ wantReason: "policy_error",
+ },
+ }
+
+ for _, testCase := range cases {
+ t.Run(testCase.name, func(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ handler := PolicyMiddleware(testCase.expression, WithDeniedAudit("feature_flag_admin", 64<<10))(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {
+ t.Fatal("failed policy request reached handler")
+ }))
+ request := httptest.NewRequest(http.MethodPut, "/api/admin/feature-flags/enabled", strings.NewReader(testCase.body))
+ request.SetPathValue("key", "enabled")
+ response := httptest.NewRecorder()
+ handler.ServeHTTP(response, request)
+ if response.Code != testCase.wantStatus {
+ t.Fatalf("status = %d, want %d; body = %s", response.Code, testCase.wantStatus, response.Body.String())
+ }
+ if count := strings.Count(logs.String(), `"event":"feature_flag_admin"`); count != 1 {
+ t.Fatalf("audit count = %d, want 1; logs=%s", count, logs.String())
+ }
+ if !strings.Contains(logs.String(), `"reason":"`+testCase.wantReason+`"`) {
+ t.Fatalf("audit reason missing %q: %s", testCase.wantReason, logs.String())
+ }
+ })
+ }
+}
+
func TestPolicyMiddlewareMergesFactsFromSeparateProvidersInOneNamespace(t *testing.T) {
year := &testFactProvider{cacheKey: "current-year", facts: FactSet{"current_year": 2026}}
month := &testFactProvider{cacheKey: "current-month", facts: FactSet{"current_month": 8}}
diff --git a/libs/fleet/backend/auth/policy_routes.go b/libs/fleet/backend/auth/policy_routes.go
index 8d7871a777..433b13a246 100644
--- a/libs/fleet/backend/auth/policy_routes.go
+++ b/libs/fleet/backend/auth/policy_routes.go
@@ -168,6 +168,11 @@ func StateQueryRoutePolicy() Node {
const billingSetupRequiredMessage = "A payment method is required to create this resource. Add one in Billing and try again."
+// FeatureFlagsRoutePolicy guards the admin-only feature-flag management API.
+func FeatureFlagsRoutePolicy() Node {
+ return All(BasePolicy(), surfaceLeaf("authz-feature-flags", "data.authz_feature_flags.allow"))
+}
+
// K8sRoutePolicy guards /api/k8s/{path...}. It is the same base + surface shape
// as every other route, with two admission conjuncts: card-or-admin admission
// for custom-resource creation, and pool admission over the request body.
@@ -241,19 +246,22 @@ type surfacePolicy struct {
options []MiddlewareOption
}
+const featureFlagAuditBodyLimit = 64 << 10
+
// surfacePolicies is every surface, by name. A surface owning no route fails
// TestEveryPolicySurfaceOwnsARoute; a route naming no surface cannot start.
var surfacePolicies = map[string]surfacePolicy{
- "keys": {tree: KeysRoutePolicy},
- "config": {tree: ConfigRoutePolicy},
- "chat": {tree: ChatRoutePolicy},
- "billing": {tree: BillingRoutePolicy},
- "usage": {tree: UsageRoutePolicy},
- "namespaces": {tree: NamespacesRoutePolicy},
- "github-trust": {tree: GitHubTrustRoutePolicy},
- "user-keys": {tree: UserKeysRoutePolicy},
- "svc": {tree: SvcRoutePolicy},
- "state-query": {tree: StateQueryRoutePolicy},
+ "keys": {tree: KeysRoutePolicy},
+ "config": {tree: ConfigRoutePolicy},
+ "chat": {tree: ChatRoutePolicy},
+ "billing": {tree: BillingRoutePolicy},
+ "usage": {tree: UsageRoutePolicy},
+ "namespaces": {tree: NamespacesRoutePolicy},
+ "github-trust": {tree: GitHubTrustRoutePolicy},
+ "user-keys": {tree: UserKeysRoutePolicy},
+ "svc": {tree: SvcRoutePolicy},
+ "state-query": {tree: StateQueryRoutePolicy},
+ "feature-flags": {tree: FeatureFlagsRoutePolicy, options: []MiddlewareOption{WithDeniedAudit("feature_flag_admin", featureFlagAuditBodyLimit), WithAdminAPIErrorResponses(), WithFreshAdminAuthorization()}},
"k8s": {
tree: K8sRoutePolicy,
options: []MiddlewareOption{WithDeniedMessage("k8s request is not allowed")},
@@ -296,7 +304,9 @@ var routeSurfaces = map[string]string{
"/api/svc/{namespace}/{service}": "svc",
"/api/svc/{namespace}/{service}/{path...}": "svc",
- "/api/k8s/{path...}": "k8s",
+ "/api/k8s/{path...}": "k8s",
+ "/api/admin/feature-flags": "feature-flags",
+ "/api/admin/feature-flags/{key}": "feature-flags",
}
// AuthenticatedRoutes returns every route the policy layer covers, sorted.
diff --git a/libs/fleet/backend/auth/testdata/feature-flags-route-plan.txt b/libs/fleet/backend/auth/testdata/feature-flags-route-plan.txt
new file mode 100644
index 0000000000..7da06dbcbb
--- /dev/null
+++ b/libs/fleet/backend/auth/testdata/feature-flags-route-plan.txt
@@ -0,0 +1,3 @@
+All
+ Leaf query=data.authz_base.allow source=registered:authz-base
+ Leaf query=data.authz_feature_flags.allow source=multi["registered:authz","registered:authz-feature-flags"]
diff --git a/libs/fleet/backend/auth/testdata/route-authorization-table.txt b/libs/fleet/backend/auth/testdata/route-authorization-table.txt
index abca683948..189ba24bdf 100644
--- a/libs/fleet/backend/auth/testdata/route-authorization-table.txt
+++ b/libs/fleet/backend/auth/testdata/route-authorization-table.txt
@@ -1,3 +1,113 @@
+/api/admin/feature-flags | plain | DELETE | admin-spa = allow
+/api/admin/feature-flags | plain | DELETE | cua-cli = deny
+/api/admin/feature-flags | plain | DELETE | dcr-client = deny
+/api/admin/feature-flags | plain | DELETE | empty-sub = deny
+/api/admin/feature-flags | plain | DELETE | github-oidc = deny
+/api/admin/feature-flags | plain | DELETE | oauth2-proxy = deny
+/api/admin/feature-flags | plain | DELETE | per-key-other-ns = deny
+/api/admin/feature-flags | plain | DELETE | per-key-owned-ns = deny
+/api/admin/feature-flags | plain | DELETE | spa = deny
+/api/admin/feature-flags | plain | DELETE | user-key = deny
+/api/admin/feature-flags | plain | DELETE | user-key-verified = deny
+/api/admin/feature-flags | plain | GET | admin-spa = allow
+/api/admin/feature-flags | plain | GET | cua-cli = deny
+/api/admin/feature-flags | plain | GET | dcr-client = deny
+/api/admin/feature-flags | plain | GET | empty-sub = deny
+/api/admin/feature-flags | plain | GET | github-oidc = deny
+/api/admin/feature-flags | plain | GET | oauth2-proxy = deny
+/api/admin/feature-flags | plain | GET | per-key-other-ns = deny
+/api/admin/feature-flags | plain | GET | per-key-owned-ns = deny
+/api/admin/feature-flags | plain | GET | spa = deny
+/api/admin/feature-flags | plain | GET | user-key = deny
+/api/admin/feature-flags | plain | GET | user-key-verified = deny
+/api/admin/feature-flags | plain | PATCH | admin-spa = allow
+/api/admin/feature-flags | plain | PATCH | cua-cli = deny
+/api/admin/feature-flags | plain | PATCH | dcr-client = deny
+/api/admin/feature-flags | plain | PATCH | empty-sub = deny
+/api/admin/feature-flags | plain | PATCH | github-oidc = deny
+/api/admin/feature-flags | plain | PATCH | oauth2-proxy = deny
+/api/admin/feature-flags | plain | PATCH | per-key-other-ns = deny
+/api/admin/feature-flags | plain | PATCH | per-key-owned-ns = deny
+/api/admin/feature-flags | plain | PATCH | spa = deny
+/api/admin/feature-flags | plain | PATCH | user-key = deny
+/api/admin/feature-flags | plain | PATCH | user-key-verified = deny
+/api/admin/feature-flags | plain | POST | admin-spa = allow
+/api/admin/feature-flags | plain | POST | cua-cli = deny
+/api/admin/feature-flags | plain | POST | dcr-client = deny
+/api/admin/feature-flags | plain | POST | empty-sub = deny
+/api/admin/feature-flags | plain | POST | github-oidc = deny
+/api/admin/feature-flags | plain | POST | oauth2-proxy = deny
+/api/admin/feature-flags | plain | POST | per-key-other-ns = deny
+/api/admin/feature-flags | plain | POST | per-key-owned-ns = deny
+/api/admin/feature-flags | plain | POST | spa = deny
+/api/admin/feature-flags | plain | POST | user-key = deny
+/api/admin/feature-flags | plain | POST | user-key-verified = deny
+/api/admin/feature-flags | plain | QUERY | admin-spa = allow
+/api/admin/feature-flags | plain | QUERY | cua-cli = deny
+/api/admin/feature-flags | plain | QUERY | dcr-client = deny
+/api/admin/feature-flags | plain | QUERY | empty-sub = deny
+/api/admin/feature-flags | plain | QUERY | github-oidc = deny
+/api/admin/feature-flags | plain | QUERY | oauth2-proxy = deny
+/api/admin/feature-flags | plain | QUERY | per-key-other-ns = deny
+/api/admin/feature-flags | plain | QUERY | per-key-owned-ns = deny
+/api/admin/feature-flags | plain | QUERY | spa = deny
+/api/admin/feature-flags | plain | QUERY | user-key = deny
+/api/admin/feature-flags | plain | QUERY | user-key-verified = deny
+/api/admin/feature-flags/{key} | key | DELETE | admin-spa = allow
+/api/admin/feature-flags/{key} | key | DELETE | cua-cli = deny
+/api/admin/feature-flags/{key} | key | DELETE | dcr-client = deny
+/api/admin/feature-flags/{key} | key | DELETE | empty-sub = deny
+/api/admin/feature-flags/{key} | key | DELETE | github-oidc = deny
+/api/admin/feature-flags/{key} | key | DELETE | oauth2-proxy = deny
+/api/admin/feature-flags/{key} | key | DELETE | per-key-other-ns = deny
+/api/admin/feature-flags/{key} | key | DELETE | per-key-owned-ns = deny
+/api/admin/feature-flags/{key} | key | DELETE | spa = deny
+/api/admin/feature-flags/{key} | key | DELETE | user-key = deny
+/api/admin/feature-flags/{key} | key | DELETE | user-key-verified = deny
+/api/admin/feature-flags/{key} | key | GET | admin-spa = allow
+/api/admin/feature-flags/{key} | key | GET | cua-cli = deny
+/api/admin/feature-flags/{key} | key | GET | dcr-client = deny
+/api/admin/feature-flags/{key} | key | GET | empty-sub = deny
+/api/admin/feature-flags/{key} | key | GET | github-oidc = deny
+/api/admin/feature-flags/{key} | key | GET | oauth2-proxy = deny
+/api/admin/feature-flags/{key} | key | GET | per-key-other-ns = deny
+/api/admin/feature-flags/{key} | key | GET | per-key-owned-ns = deny
+/api/admin/feature-flags/{key} | key | GET | spa = deny
+/api/admin/feature-flags/{key} | key | GET | user-key = deny
+/api/admin/feature-flags/{key} | key | GET | user-key-verified = deny
+/api/admin/feature-flags/{key} | key | PATCH | admin-spa = allow
+/api/admin/feature-flags/{key} | key | PATCH | cua-cli = deny
+/api/admin/feature-flags/{key} | key | PATCH | dcr-client = deny
+/api/admin/feature-flags/{key} | key | PATCH | empty-sub = deny
+/api/admin/feature-flags/{key} | key | PATCH | github-oidc = deny
+/api/admin/feature-flags/{key} | key | PATCH | oauth2-proxy = deny
+/api/admin/feature-flags/{key} | key | PATCH | per-key-other-ns = deny
+/api/admin/feature-flags/{key} | key | PATCH | per-key-owned-ns = deny
+/api/admin/feature-flags/{key} | key | PATCH | spa = deny
+/api/admin/feature-flags/{key} | key | PATCH | user-key = deny
+/api/admin/feature-flags/{key} | key | PATCH | user-key-verified = deny
+/api/admin/feature-flags/{key} | key | POST | admin-spa = allow
+/api/admin/feature-flags/{key} | key | POST | cua-cli = deny
+/api/admin/feature-flags/{key} | key | POST | dcr-client = deny
+/api/admin/feature-flags/{key} | key | POST | empty-sub = deny
+/api/admin/feature-flags/{key} | key | POST | github-oidc = deny
+/api/admin/feature-flags/{key} | key | POST | oauth2-proxy = deny
+/api/admin/feature-flags/{key} | key | POST | per-key-other-ns = deny
+/api/admin/feature-flags/{key} | key | POST | per-key-owned-ns = deny
+/api/admin/feature-flags/{key} | key | POST | spa = deny
+/api/admin/feature-flags/{key} | key | POST | user-key = deny
+/api/admin/feature-flags/{key} | key | POST | user-key-verified = deny
+/api/admin/feature-flags/{key} | key | QUERY | admin-spa = allow
+/api/admin/feature-flags/{key} | key | QUERY | cua-cli = deny
+/api/admin/feature-flags/{key} | key | QUERY | dcr-client = deny
+/api/admin/feature-flags/{key} | key | QUERY | empty-sub = deny
+/api/admin/feature-flags/{key} | key | QUERY | github-oidc = deny
+/api/admin/feature-flags/{key} | key | QUERY | oauth2-proxy = deny
+/api/admin/feature-flags/{key} | key | QUERY | per-key-other-ns = deny
+/api/admin/feature-flags/{key} | key | QUERY | per-key-owned-ns = deny
+/api/admin/feature-flags/{key} | key | QUERY | spa = deny
+/api/admin/feature-flags/{key} | key | QUERY | user-key = deny
+/api/admin/feature-flags/{key} | key | QUERY | user-key-verified = deny
/api/billing/portal-session | plain | DELETE | admin-spa = allow
/api/billing/portal-session | plain | DELETE | cua-cli = deny
/api/billing/portal-session | plain | DELETE | dcr-client = deny
diff --git a/libs/fleet/backend/docs/docs.go b/libs/fleet/backend/docs/docs.go
index f7f7f6c431..228c169480 100644
--- a/libs/fleet/backend/docs/docs.go
+++ b/libs/fleet/backend/docs/docs.go
@@ -15,6 +15,356 @@ const docTemplate = `{
"host": "{{.Host}}",
"basePath": "{{.BasePath}}",
"paths": {
+ "/api/admin/feature-flags": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Lists direct non-SecureString parameters under /feature-flags/cyclops-cs/ with typed values, ownership, and SSM versions.",
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "List Cyclops feature flags",
+ "responses": {
+ "200": {
+ "description": "OK",
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ },
+ "post": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Creates a String parameter under /feature-flags/cyclops-cs/ with cyclops-cs-admin ownership and a typed logical value.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "Create an ad hoc Cyclops feature flag",
+ "parameters": [
+ {
+ "description": "Feature flag to create",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/handlers.CreateFeatureFlagRequest"
+ }
+ }
+ ],
+ "responses": {
+ "201": {
+ "description": "Created",
+ "schema": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "422": {
+ "description": "Unprocessable Entity",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/feature-flags/{key}": {
+ "put": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Updates the typed value when expected_version matches. Terraform and external ownership protect the key from deletion, not value edits.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "Update a Cyclops feature flag value",
+ "parameters": [
+ {
+ "type": "string",
+ "description": "Flat feature flag key",
+ "name": "key",
+ "in": "path",
+ "required": true
+ },
+ {
+ "description": "Typed value and expected SSM version",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/handlers.UpdateFeatureFlagRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "schema": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "422": {
+ "description": "Unprocessable Entity",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ },
+ "delete": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Deletes only cyclops-cs-admin-owned flags when expected_version matches. Terraform and external keys are protected.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "Delete an ad hoc Cyclops feature flag",
+ "parameters": [
+ {
+ "type": "string",
+ "description": "Flat feature flag key",
+ "name": "key",
+ "in": "path",
+ "required": true
+ },
+ {
+ "description": "Expected SSM version",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/handlers.DeleteFeatureFlagRequest"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "422": {
+ "description": "Unprocessable Entity",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ }
+ },
"/api/billing/portal-session": {
"post": {
"security": [
@@ -1241,6 +1591,90 @@ const docTemplate = `{
}
}
},
+ "featureflagadmin.Flag": {
+ "type": "object",
+ "properties": {
+ "deletable": {
+ "type": "boolean"
+ },
+ "description": {
+ "type": "string"
+ },
+ "key": {
+ "type": "string"
+ },
+ "managed_by": {
+ "type": "string"
+ },
+ "modified_at": {
+ "type": "string"
+ },
+ "ownership": {
+ "$ref": "#/definitions/featureflagadmin.Ownership"
+ },
+ "path": {
+ "type": "string"
+ },
+ "raw_value": {
+ "type": "string"
+ },
+ "tags": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string"
+ }
+ },
+ "value": {},
+ "value_type": {
+ "$ref": "#/definitions/featureflags.ValueType"
+ },
+ "version": {
+ "type": "integer"
+ }
+ }
+ },
+ "featureflagadmin.Ownership": {
+ "type": "string",
+ "enum": [
+ "terraform",
+ "ad_hoc",
+ "external"
+ ],
+ "x-enum-varnames": [
+ "OwnershipTerraform",
+ "OwnershipAdHoc",
+ "OwnershipExternal"
+ ]
+ },
+ "featureflags.ValueType": {
+ "type": "string",
+ "enum": [
+ "boolean",
+ "number",
+ "string",
+ "json"
+ ],
+ "x-enum-varnames": [
+ "ValueBoolean",
+ "ValueNumber",
+ "ValueString",
+ "ValueJSON"
+ ]
+ },
+ "handlers.AdminAPIError": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string"
+ },
+ "current": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
"handlers.BillingSessionResponse": {
"type": "object",
"properties": {
@@ -1264,6 +1698,21 @@ const docTemplate = `{
}
}
},
+ "handlers.CreateFeatureFlagRequest": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "key": {
+ "type": "string"
+ },
+ "value": {},
+ "value_type": {
+ "$ref": "#/definitions/featureflags.ValueType"
+ }
+ }
+ },
"handlers.CreateKeyRequest": {
"type": "object",
"properties": {
@@ -1348,6 +1797,14 @@ const docTemplate = `{
}
}
},
+ "handlers.DeleteFeatureFlagRequest": {
+ "type": "object",
+ "properties": {
+ "expected_version": {
+ "type": "integer"
+ }
+ }
+ },
"handlers.ErrorResponse": {
"type": "object",
"properties": {
@@ -1417,6 +1874,18 @@ const docTemplate = `{
}
}
},
+ "handlers.UpdateFeatureFlagRequest": {
+ "type": "object",
+ "properties": {
+ "expected_version": {
+ "type": "integer"
+ },
+ "value": {},
+ "value_type": {
+ "$ref": "#/definitions/featureflags.ValueType"
+ }
+ }
+ },
"handlers.UserKeyResponse": {
"type": "object",
"properties": {
diff --git a/libs/fleet/backend/docs/swagger.json b/libs/fleet/backend/docs/swagger.json
index 897286cfd5..a5f9fa0484 100644
--- a/libs/fleet/backend/docs/swagger.json
+++ b/libs/fleet/backend/docs/swagger.json
@@ -8,6 +8,356 @@
},
"basePath": "/",
"paths": {
+ "/api/admin/feature-flags": {
+ "get": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Lists direct non-SecureString parameters under /feature-flags/cyclops-cs/ with typed values, ownership, and SSM versions.",
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "List Cyclops feature flags",
+ "responses": {
+ "200": {
+ "description": "OK",
+ "schema": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ }
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ },
+ "post": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Creates a String parameter under /feature-flags/cyclops-cs/ with cyclops-cs-admin ownership and a typed logical value.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "Create an ad hoc Cyclops feature flag",
+ "parameters": [
+ {
+ "description": "Feature flag to create",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/handlers.CreateFeatureFlagRequest"
+ }
+ }
+ ],
+ "responses": {
+ "201": {
+ "description": "Created",
+ "schema": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "422": {
+ "description": "Unprocessable Entity",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/feature-flags/{key}": {
+ "put": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Updates the typed value when expected_version matches. Terraform and external ownership protect the key from deletion, not value edits.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "Update a Cyclops feature flag value",
+ "parameters": [
+ {
+ "type": "string",
+ "description": "Flat feature flag key",
+ "name": "key",
+ "in": "path",
+ "required": true
+ },
+ {
+ "description": "Typed value and expected SSM version",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/handlers.UpdateFeatureFlagRequest"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "schema": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ }
+ },
+ "400": {
+ "description": "Bad Request",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "422": {
+ "description": "Unprocessable Entity",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ },
+ "delete": {
+ "security": [
+ {
+ "BearerAuth": []
+ }
+ ],
+ "description": "Deletes only cyclops-cs-admin-owned flags when expected_version matches. Terraform and external keys are protected.",
+ "consumes": [
+ "application/json"
+ ],
+ "produces": [
+ "application/json"
+ ],
+ "tags": [
+ "admin feature flags"
+ ],
+ "summary": "Delete an ad hoc Cyclops feature flag",
+ "parameters": [
+ {
+ "type": "string",
+ "description": "Flat feature flag key",
+ "name": "key",
+ "in": "path",
+ "required": true
+ },
+ {
+ "description": "Expected SSM version",
+ "name": "request",
+ "in": "body",
+ "required": true,
+ "schema": {
+ "$ref": "#/definitions/handlers.DeleteFeatureFlagRequest"
+ }
+ }
+ ],
+ "responses": {
+ "204": {
+ "description": "No Content"
+ },
+ "400": {
+ "description": "Bad Request",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "401": {
+ "description": "Unauthorized",
+ "schema": {
+ "$ref": "#/definitions/handlers.ErrorResponse"
+ }
+ },
+ "403": {
+ "description": "Forbidden",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "404": {
+ "description": "Not Found",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "409": {
+ "description": "Conflict",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "422": {
+ "description": "Unprocessable Entity",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "500": {
+ "description": "Internal Server Error",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "501": {
+ "description": "Not Implemented",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "502": {
+ "description": "Bad Gateway",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "schema": {
+ "$ref": "#/definitions/handlers.AdminAPIError"
+ }
+ }
+ }
+ }
+ },
"/api/billing/portal-session": {
"post": {
"security": [
@@ -1234,6 +1584,90 @@
}
}
},
+ "featureflagadmin.Flag": {
+ "type": "object",
+ "properties": {
+ "deletable": {
+ "type": "boolean"
+ },
+ "description": {
+ "type": "string"
+ },
+ "key": {
+ "type": "string"
+ },
+ "managed_by": {
+ "type": "string"
+ },
+ "modified_at": {
+ "type": "string"
+ },
+ "ownership": {
+ "$ref": "#/definitions/featureflagadmin.Ownership"
+ },
+ "path": {
+ "type": "string"
+ },
+ "raw_value": {
+ "type": "string"
+ },
+ "tags": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string"
+ }
+ },
+ "value": {},
+ "value_type": {
+ "$ref": "#/definitions/featureflags.ValueType"
+ },
+ "version": {
+ "type": "integer"
+ }
+ }
+ },
+ "featureflagadmin.Ownership": {
+ "type": "string",
+ "enum": [
+ "terraform",
+ "ad_hoc",
+ "external"
+ ],
+ "x-enum-varnames": [
+ "OwnershipTerraform",
+ "OwnershipAdHoc",
+ "OwnershipExternal"
+ ]
+ },
+ "featureflags.ValueType": {
+ "type": "string",
+ "enum": [
+ "boolean",
+ "number",
+ "string",
+ "json"
+ ],
+ "x-enum-varnames": [
+ "ValueBoolean",
+ "ValueNumber",
+ "ValueString",
+ "ValueJSON"
+ ]
+ },
+ "handlers.AdminAPIError": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "string"
+ },
+ "current": {
+ "$ref": "#/definitions/featureflagadmin.Flag"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
"handlers.BillingSessionResponse": {
"type": "object",
"properties": {
@@ -1257,6 +1691,21 @@
}
}
},
+ "handlers.CreateFeatureFlagRequest": {
+ "type": "object",
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "key": {
+ "type": "string"
+ },
+ "value": {},
+ "value_type": {
+ "$ref": "#/definitions/featureflags.ValueType"
+ }
+ }
+ },
"handlers.CreateKeyRequest": {
"type": "object",
"properties": {
@@ -1341,6 +1790,14 @@
}
}
},
+ "handlers.DeleteFeatureFlagRequest": {
+ "type": "object",
+ "properties": {
+ "expected_version": {
+ "type": "integer"
+ }
+ }
+ },
"handlers.ErrorResponse": {
"type": "object",
"properties": {
@@ -1410,6 +1867,18 @@
}
}
},
+ "handlers.UpdateFeatureFlagRequest": {
+ "type": "object",
+ "properties": {
+ "expected_version": {
+ "type": "integer"
+ },
+ "value": {},
+ "value_type": {
+ "$ref": "#/definitions/featureflags.ValueType"
+ }
+ }
+ },
"handlers.UserKeyResponse": {
"type": "object",
"properties": {
diff --git a/libs/fleet/backend/docs/swagger.yaml b/libs/fleet/backend/docs/swagger.yaml
index eb9176a538..e5833152c7 100644
--- a/libs/fleet/backend/docs/swagger.yaml
+++ b/libs/fleet/backend/docs/swagger.yaml
@@ -92,6 +92,65 @@ definitions:
name:
type: string
type: object
+ featureflagadmin.Flag:
+ properties:
+ deletable:
+ type: boolean
+ description:
+ type: string
+ key:
+ type: string
+ managed_by:
+ type: string
+ modified_at:
+ type: string
+ ownership:
+ $ref: '#/definitions/featureflagadmin.Ownership'
+ path:
+ type: string
+ raw_value:
+ type: string
+ tags:
+ additionalProperties:
+ type: string
+ type: object
+ value: {}
+ value_type:
+ $ref: '#/definitions/featureflags.ValueType'
+ version:
+ type: integer
+ type: object
+ featureflagadmin.Ownership:
+ enum:
+ - terraform
+ - ad_hoc
+ - external
+ type: string
+ x-enum-varnames:
+ - OwnershipTerraform
+ - OwnershipAdHoc
+ - OwnershipExternal
+ featureflags.ValueType:
+ enum:
+ - boolean
+ - number
+ - string
+ - json
+ type: string
+ x-enum-varnames:
+ - ValueBoolean
+ - ValueNumber
+ - ValueString
+ - ValueJSON
+ handlers.AdminAPIError:
+ properties:
+ code:
+ type: string
+ current:
+ $ref: '#/definitions/featureflagadmin.Flag'
+ message:
+ type: string
+ type: object
handlers.BillingSessionResponse:
properties:
url:
@@ -111,6 +170,16 @@ definitions:
chat:
type: boolean
type: object
+ handlers.CreateFeatureFlagRequest:
+ properties:
+ description:
+ type: string
+ key:
+ type: string
+ value: {}
+ value_type:
+ $ref: '#/definitions/featureflags.ValueType'
+ type: object
handlers.CreateKeyRequest:
properties:
name:
@@ -167,6 +236,11 @@ definitions:
token_url:
type: string
type: object
+ handlers.DeleteFeatureFlagRequest:
+ properties:
+ expected_version:
+ type: integer
+ type: object
handlers.ErrorResponse:
properties:
error:
@@ -211,6 +285,14 @@ definitions:
$ref: '#/definitions/chat.Message'
type: array
type: object
+ handlers.UpdateFeatureFlagRequest:
+ properties:
+ expected_version:
+ type: integer
+ value: {}
+ value_type:
+ $ref: '#/definitions/featureflags.ValueType'
+ type: object
handlers.UserKeyResponse:
properties:
client_id:
@@ -254,6 +336,237 @@ info:
title: Cyclops CS Backend API
version: "0.1"
paths:
+ /api/admin/feature-flags:
+ get:
+ description: Lists direct non-SecureString parameters under /feature-flags/cyclops-cs/
+ with typed values, ownership, and SSM versions.
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: OK
+ schema:
+ items:
+ $ref: '#/definitions/featureflagadmin.Flag'
+ type: array
+ "401":
+ description: Unauthorized
+ schema:
+ $ref: '#/definitions/handlers.ErrorResponse'
+ "403":
+ description: Forbidden
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "501":
+ description: Not Implemented
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "502":
+ description: Bad Gateway
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ security:
+ - BearerAuth: []
+ summary: List Cyclops feature flags
+ tags:
+ - admin feature flags
+ post:
+ consumes:
+ - application/json
+ description: Creates a String parameter under /feature-flags/cyclops-cs/ with
+ cyclops-cs-admin ownership and a typed logical value.
+ parameters:
+ - description: Feature flag to create
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/handlers.CreateFeatureFlagRequest'
+ produces:
+ - application/json
+ responses:
+ "201":
+ description: Created
+ schema:
+ $ref: '#/definitions/featureflagadmin.Flag'
+ "400":
+ description: Bad Request
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "401":
+ description: Unauthorized
+ schema:
+ $ref: '#/definitions/handlers.ErrorResponse'
+ "403":
+ description: Forbidden
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "409":
+ description: Conflict
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "422":
+ description: Unprocessable Entity
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "500":
+ description: Internal Server Error
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "501":
+ description: Not Implemented
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "502":
+ description: Bad Gateway
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "503":
+ description: Service Unavailable
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ security:
+ - BearerAuth: []
+ summary: Create an ad hoc Cyclops feature flag
+ tags:
+ - admin feature flags
+ /api/admin/feature-flags/{key}:
+ delete:
+ consumes:
+ - application/json
+ description: Deletes only cyclops-cs-admin-owned flags when expected_version
+ matches. Terraform and external keys are protected.
+ parameters:
+ - description: Flat feature flag key
+ in: path
+ name: key
+ required: true
+ type: string
+ - description: Expected SSM version
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/handlers.DeleteFeatureFlagRequest'
+ produces:
+ - application/json
+ responses:
+ "204":
+ description: No Content
+ "400":
+ description: Bad Request
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "401":
+ description: Unauthorized
+ schema:
+ $ref: '#/definitions/handlers.ErrorResponse'
+ "403":
+ description: Forbidden
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "404":
+ description: Not Found
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "409":
+ description: Conflict
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "422":
+ description: Unprocessable Entity
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "500":
+ description: Internal Server Error
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "501":
+ description: Not Implemented
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "502":
+ description: Bad Gateway
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "503":
+ description: Service Unavailable
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ security:
+ - BearerAuth: []
+ summary: Delete an ad hoc Cyclops feature flag
+ tags:
+ - admin feature flags
+ put:
+ consumes:
+ - application/json
+ description: Updates the typed value when expected_version matches. Terraform
+ and external ownership protect the key from deletion, not value edits.
+ parameters:
+ - description: Flat feature flag key
+ in: path
+ name: key
+ required: true
+ type: string
+ - description: Typed value and expected SSM version
+ in: body
+ name: request
+ required: true
+ schema:
+ $ref: '#/definitions/handlers.UpdateFeatureFlagRequest'
+ produces:
+ - application/json
+ responses:
+ "200":
+ description: OK
+ schema:
+ $ref: '#/definitions/featureflagadmin.Flag'
+ "400":
+ description: Bad Request
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "401":
+ description: Unauthorized
+ schema:
+ $ref: '#/definitions/handlers.ErrorResponse'
+ "403":
+ description: Forbidden
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "404":
+ description: Not Found
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "409":
+ description: Conflict
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "422":
+ description: Unprocessable Entity
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "500":
+ description: Internal Server Error
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "501":
+ description: Not Implemented
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "502":
+ description: Bad Gateway
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ "503":
+ description: Service Unavailable
+ schema:
+ $ref: '#/definitions/handlers.AdminAPIError'
+ security:
+ - BearerAuth: []
+ summary: Update a Cyclops feature flag value
+ tags:
+ - admin feature flags
/api/billing/portal-session:
post:
description: Creates a Stripe-hosted Billing Portal Session for the customer
diff --git a/libs/fleet/backend/feature_flag_management.go b/libs/fleet/backend/feature_flag_management.go
new file mode 100644
index 0000000000..c7568f304f
--- /dev/null
+++ b/libs/fleet/backend/feature_flag_management.go
@@ -0,0 +1,50 @@
+package main
+
+import (
+ "context"
+ "fmt"
+ "sync"
+
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+const featureFlagManagementModeEphemeral = "ephemeral"
+
+func featureFlagManagementStoreFromEnv(getenv func(string) string) (featureflags.ManagementStore, bool, error) {
+ mode := getenv("FEATURE_FLAG_MANAGEMENT_MODE")
+ switch mode {
+ case "":
+ store, err := featureflags.NewManagementStore()
+ return store, false, err
+ case featureFlagManagementModeEphemeral:
+ store, err := featureflags.NewEphemeralManagementStore(getenv("FEATURE_FLAG_MANAGEMENT_SEED"))
+ return store, true, err
+ default:
+ return nil, false, fmt.Errorf("unsupported feature flag management mode %q", mode)
+ }
+}
+
+type processLocalMutationLock struct {
+ once sync.Once
+ token chan struct{}
+}
+
+func (l *processLocalMutationLock) WithLock(ctx context.Context, callback func(context.Context) error) error {
+ if err := ctx.Err(); err != nil {
+ return err
+ }
+ l.once.Do(func() {
+ l.token = make(chan struct{}, 1)
+ l.token <- struct{}{}
+ })
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ case <-l.token:
+ }
+ defer func() { l.token <- struct{}{} }()
+ if err := ctx.Err(); err != nil {
+ return err
+ }
+ return callback(ctx)
+}
diff --git a/libs/fleet/backend/featureflagadmin/audit.go b/libs/fleet/backend/featureflagadmin/audit.go
new file mode 100644
index 0000000000..0b7ebbd6f9
--- /dev/null
+++ b/libs/fleet/backend/featureflagadmin/audit.go
@@ -0,0 +1,95 @@
+package featureflagadmin
+
+import (
+ "context"
+ "crypto/sha256"
+ "encoding/hex"
+ "fmt"
+ "log/slog"
+
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+type slogAuditLogger struct {
+ logger *slog.Logger
+}
+
+type auditTypedValue struct {
+ ValueType featureflags.ValueType `json:"value_type"`
+ Value any `json:"value"`
+ RawValue string `json:"raw_value"`
+}
+
+func NewSlogAuditLogger(logger *slog.Logger) AuditLogger {
+ if logger == nil {
+ logger = slog.Default()
+ }
+ return &slogAuditLogger{logger: logger}
+}
+
+func (logger *slogAuditLogger) Log(ctx context.Context, event AuditEvent) {
+ logger.logger.WarnContext(ctx, "feature flag mutation audited",
+ "event", event.Event,
+ "timestamp", event.Timestamp,
+ "actor", event.Actor.Subject,
+ "actor_email", event.Actor.Email,
+ "principal_type", event.Actor.PrincipalType,
+ "operation", event.Operation,
+ "key", auditKey(event.Key),
+ "path", auditPath(event.Path, event.Key),
+ "traceId", event.Actor.TraceID,
+ "ownership", event.Ownership,
+ "old_value", auditValue(event.OldValue),
+ "new_value", auditValue(event.NewValue),
+ "expected_version", event.ExpectedVersion,
+ "previous_version", event.PreviousVersion,
+ "result_version", event.ResultVersion,
+ "result", event.Result,
+ "reason", event.Reason,
+ )
+}
+
+func auditValue(value *featureflags.TypedValue) any {
+ if value == nil {
+ return nil
+ }
+ return auditTypedValue{ValueType: value.Type, Value: value.Value, RawValue: value.Raw}
+}
+
+const maxAuditIdentifierBytes = 128
+
+func BoundedAuditKey(value string) string {
+ return auditKey(value)
+}
+
+func BoundedAuditPath(path, key string) string {
+ return auditPath(path, key)
+}
+
+func boundedAuditIdentifier(value string) string {
+ if len(value) <= maxAuditIdentifierBytes {
+ return value
+ }
+ sum := sha256.Sum256([]byte(value))
+ prefix := value[:96]
+ return fmt.Sprintf("%s... sha256:%s", prefix, hex.EncodeToString(sum[:8]))
+}
+
+func auditKey(value string) string {
+ if value == "" || validateKey(value) == nil {
+ return boundedAuditIdentifier(value)
+ }
+ return hashedAuditIdentifier(value)
+}
+
+func auditPath(path, key string) string {
+ if key != "" && validateKey(key) != nil {
+ return hashedAuditIdentifier(path)
+ }
+ return boundedAuditIdentifier(path)
+}
+
+func hashedAuditIdentifier(value string) string {
+ sum := sha256.Sum256([]byte(value))
+ return fmt.Sprintf("sha256:%s", hex.EncodeToString(sum[:16]))
+}
diff --git a/libs/fleet/backend/featureflagadmin/audit_test.go b/libs/fleet/backend/featureflagadmin/audit_test.go
new file mode 100644
index 0000000000..b16960ff0d
--- /dev/null
+++ b/libs/fleet/backend/featureflagadmin/audit_test.go
@@ -0,0 +1,100 @@
+package featureflagadmin
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "log/slog"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+func TestSlogAuditLoggerEmitsStableJSONSchema(t *testing.T) {
+ var output bytes.Buffer
+ logger := slog.New(slog.NewJSONHandler(&output, nil))
+ timestamp := time.Date(2026, 8, 13, 14, 15, 16, 0, time.UTC)
+ oldValue := featureflags.TypedValue{Type: featureflags.ValueBoolean, Value: false, Raw: "false"}
+ newValue := featureflags.TypedValue{Type: featureflags.ValueJSON, Value: map[string]any{"enabled": true}, Raw: `{"enabled":true}`}
+
+ NewSlogAuditLogger(logger).Log(context.Background(), AuditEvent{
+ Event: "feature_flag_admin",
+ Timestamp: timestamp,
+ Actor: Actor{
+ Subject: "admin-1",
+ Email: "[email protected]",
+ PrincipalType: "user",
+ TraceID: "trace-123",
+ },
+ Operation: "update",
+ Key: "example-flag",
+ Path: Prefix + "example-flag",
+ Ownership: OwnershipTerraform,
+ OldValue: &oldValue,
+ NewValue: &newValue,
+ ExpectedVersion: 4,
+ PreviousVersion: 4,
+ ResultVersion: 5,
+ Result: "success",
+ Reason: "",
+ })
+
+ var record map[string]any
+ if err := json.Unmarshal(output.Bytes(), &record); err != nil {
+ t.Fatalf("unmarshal audit log: %v; output=%s", err, output.String())
+ }
+ wants := map[string]any{
+ "event": "feature_flag_admin", "actor": "admin-1", "actor_email": "[email protected]",
+ "principal_type": "user", "operation": "update", "key": "example-flag",
+ "path": Prefix + "example-flag", "traceId": "trace-123", "ownership": "terraform",
+ "expected_version": float64(4), "previous_version": float64(4), "result_version": float64(5),
+ "result": "success", "reason": "", "timestamp": timestamp.Format(time.RFC3339),
+ }
+ for key, want := range wants {
+ if got := record[key]; got != want {
+ t.Errorf("%s = %#v, want %#v", key, got, want)
+ }
+ }
+ assertTypedAuditValue(t, record["old_value"], "boolean", false, "false")
+ assertTypedAuditValue(t, record["new_value"], "json", map[string]any{"enabled": true}, `{"enabled":true}`)
+}
+
+func TestSlogAuditLoggerBoundsUnvalidatedIdentifiers(t *testing.T) {
+ var output bytes.Buffer
+ logger := slog.New(slog.NewJSONHandler(&output, nil))
+ invalidKey := "Sensitive/Secret" + strings.Repeat("-value", 100)
+ NewSlogAuditLogger(logger).Log(context.Background(), AuditEvent{
+ Event: "feature_flag_admin", Key: invalidKey, Path: Prefix + invalidKey, Result: "rejected", Reason: "invalid_key",
+ })
+ if strings.Contains(output.String(), invalidKey) || strings.Contains(output.String(), "Sensitive/Secret") {
+ t.Fatalf("audit contains unvalidated invalid key: %s", output.String())
+ }
+ var record map[string]any
+ if err := json.Unmarshal(output.Bytes(), &record); err != nil {
+ t.Fatal(err)
+ }
+ for _, field := range []string{"key", "path"} {
+ value, _ := record[field].(string)
+ if len(value) > 160 || !strings.Contains(value, "sha256:") {
+ t.Errorf("%s = %q, want bounded hash marker", field, value)
+ }
+ }
+}
+
+func assertTypedAuditValue(t *testing.T, raw any, wantType string, wantValue any, wantRaw string) {
+ t.Helper()
+ value, ok := raw.(map[string]any)
+ if !ok {
+ t.Fatalf("typed value = %#v, want object", raw)
+ }
+ if value["value_type"] != wantType || value["raw_value"] != wantRaw {
+ t.Fatalf("typed value metadata = %#v", value)
+ }
+ wantJSON, _ := json.Marshal(wantValue)
+ gotJSON, _ := json.Marshal(value["value"])
+ if !bytes.Equal(gotJSON, wantJSON) {
+ t.Fatalf("typed value = %s, want %s", gotJSON, wantJSON)
+ }
+}
diff --git a/libs/fleet/backend/featureflagadmin/lease.go b/libs/fleet/backend/featureflagadmin/lease.go
new file mode 100644
index 0000000000..921bd1f9ff
--- /dev/null
+++ b/libs/fleet/backend/featureflagadmin/lease.go
@@ -0,0 +1,385 @@
+package featureflagadmin
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "net/http"
+ "os"
+ "strings"
+ "sync"
+ "time"
+)
+
+var (
+ ErrLeaseUnavailable = errors.New("featureflagadmin: lease unavailable")
+ ErrLeaseNotFound = errors.New("featureflagadmin: pre-created lease not found")
+
+ leaseLifecycleGuardsMu sync.Mutex
+ leaseLifecycleGuards = map[string]*lifecycleGuard{}
+)
+
+type lifecycleGuard struct {
+ token chan struct{}
+ refs int
+}
+
+func acquireLifecycleGuard(key string) *lifecycleGuard {
+ leaseLifecycleGuardsMu.Lock()
+ defer leaseLifecycleGuardsMu.Unlock()
+ guard := leaseLifecycleGuards[key]
+ if guard == nil {
+ guard = &lifecycleGuard{token: make(chan struct{}, 1)}
+ guard.token <- struct{}{}
+ leaseLifecycleGuards[key] = guard
+ }
+ guard.refs++
+ return guard
+}
+
+func releaseLifecycleGuard(key string, guard *lifecycleGuard) {
+ leaseLifecycleGuardsMu.Lock()
+ defer leaseLifecycleGuardsMu.Unlock()
+ guard.refs--
+ if guard.refs == 0 && leaseLifecycleGuards[key] == guard {
+ delete(leaseLifecycleGuards, key)
+ }
+}
+
+type KubernetesLeaseLock struct {
+ apiBaseURL string
+ namespace string
+ name string
+ holderIdentity string
+ leaseDuration time.Duration
+ retryInterval time.Duration
+ now func() time.Time
+ client *http.Client
+ lifecycleKey string
+ waitForRetry func(context.Context, time.Duration) error
+ renewalTicks func(time.Duration) (<-chan time.Time, func())
+ renewed func()
+}
+
+type leaseLockHooks struct {
+ waitForRetry func(context.Context, time.Duration) error
+ renewalTicks func(time.Duration) (<-chan time.Time, func())
+ renewed func()
+}
+
+func NewKubernetesLeaseLock(apiBaseURL, namespace, name, holderIdentity string, leaseDuration, retryInterval time.Duration, now func() time.Time) *KubernetesLeaseLock {
+ return newKubernetesLeaseLock(apiBaseURL, namespace, name, holderIdentity, leaseDuration, retryInterval, now, leaseLockHooks{})
+}
+
+func newKubernetesLeaseLock(apiBaseURL, namespace, name, holderIdentity string, leaseDuration, retryInterval time.Duration, now func() time.Time, hooks leaseLockHooks) *KubernetesLeaseLock {
+ if holderIdentity == "" {
+ holderIdentity, _ = os.Hostname()
+ }
+ if leaseDuration <= 0 {
+ leaseDuration = 30 * time.Second
+ }
+ if retryInterval <= 0 {
+ retryInterval = 100 * time.Millisecond
+ }
+ if now == nil {
+ now = time.Now
+ }
+ lifecycleKey := strings.TrimRight(apiBaseURL, "/") + "\x00" + namespace + "\x00" + name
+ lock := &KubernetesLeaseLock{
+ apiBaseURL: strings.TrimRight(apiBaseURL, "/"), namespace: namespace, name: name, holderIdentity: holderIdentity,
+ leaseDuration: leaseDuration, retryInterval: retryInterval, now: now, client: &http.Client{}, lifecycleKey: lifecycleKey,
+ }
+ lock.waitForRetry = hooks.waitForRetry
+ if lock.waitForRetry == nil {
+ lock.waitForRetry = waitForLeaseRetry
+ }
+ lock.renewalTicks = hooks.renewalTicks
+ if lock.renewalTicks == nil {
+ lock.renewalTicks = renewalTicker
+ }
+ lock.renewed = hooks.renewed
+ return lock
+}
+
+func (l *KubernetesLeaseLock) WithLock(ctx context.Context, callback func(context.Context) error) error {
+ // The Kubernetes holder identity is shared by every goroutine in this pod,
+ // so serialize the full lifecycle locally as well as across replicas.
+ guard := acquireLifecycleGuard(l.lifecycleKey)
+ defer releaseLifecycleGuard(l.lifecycleKey, guard)
+ select {
+ case <-ctx.Done():
+ return errors.Join(ErrLeaseUnavailable, ctx.Err())
+ case <-guard.token:
+ defer func() { guard.token <- struct{}{} }()
+ }
+
+ for {
+ lease, err := l.get(ctx)
+ if err != nil {
+ if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, context.Canceled) {
+ return errors.Join(ErrLeaseUnavailable, err)
+ }
+ return err
+ }
+ if !l.available(lease) {
+ if err := l.waitForRetry(ctx, l.retryInterval); err != nil {
+ return errors.Join(ErrLeaseUnavailable, err)
+ }
+ continue
+ }
+
+ updated, conflict, err := l.put(ctx, l.claim(lease))
+ if err != nil {
+ return err
+ }
+ if conflict {
+ continue
+ }
+
+ callbackCtx, cancelCallback := context.WithCancel(ctx)
+ renewalCtx, cancelRenewal := context.WithCancel(context.Background())
+ renewalDone := make(chan renewalResult, 1)
+ go func() {
+ lease, err := l.renew(renewalCtx, updated)
+ renewalDone <- renewalResult{lease: lease, err: err}
+ }()
+ callbackDone := make(chan error, 1)
+ go func() { callbackDone <- callback(callbackCtx) }()
+
+ var callbackErr error
+ var renewal renewalResult
+ var renewalErr error
+ select {
+ case callbackErr = <-callbackDone:
+ cancelRenewal()
+ renewal = <-renewalDone
+ renewalErr = renewal.err
+ case renewal = <-renewalDone:
+ renewalErr = renewal.err
+ if renewalErr != nil {
+ cancelCallback()
+ }
+ callbackErr = <-callbackDone
+ }
+ cancelCallback()
+ cancelRenewal()
+
+ releaseCtx, releaseCancel := context.WithTimeout(context.Background(), l.releaseTimeout())
+ l.release(releaseCtx, renewal.lease)
+ releaseCancel()
+ if renewalErr != nil {
+ return errors.Join(ErrLeaseUnavailable, renewalErr, callbackErr)
+ }
+ return errors.Join(callbackErr, renewalErr)
+ }
+}
+
+func (l *KubernetesLeaseLock) renewalRequestTimeout() time.Duration {
+ timeout := l.leaseDuration / 4
+ if timeout > time.Second {
+ timeout = time.Second
+ }
+ if timeout < 100*time.Millisecond {
+ timeout = 100 * time.Millisecond
+ }
+ return timeout
+}
+
+func (l *KubernetesLeaseLock) releaseTimeout() time.Duration {
+ timeout := l.renewalRequestTimeout()
+ if timeout < l.retryInterval {
+ timeout = l.retryInterval
+ }
+ return timeout
+}
+
+func (l *KubernetesLeaseLock) claim(lease leaseObject) leaseObject {
+ lease.APIVersion = "coordination.k8s.io/v1"
+ lease.Kind = "Lease"
+ lease.Spec.HolderIdentity = l.holderIdentity
+ lease.Spec.LeaseDurationSeconds = int32(l.leaseDuration / time.Second)
+ if lease.Spec.LeaseDurationSeconds < 1 {
+ lease.Spec.LeaseDurationSeconds = 1
+ }
+ now := l.now().UTC().Format(time.RFC3339Nano)
+ lease.Spec.AcquireTime = &now
+ lease.Spec.RenewTime = &now
+ return lease
+}
+
+func (l *KubernetesLeaseLock) renew(ctx context.Context, lease leaseObject) (leaseObject, error) {
+ interval := l.leaseDuration / 2
+ if interval <= 0 {
+ interval = time.Millisecond
+ }
+ ticks, stop := l.renewalTicks(interval)
+ defer stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return lease, nil
+ case <-ticks:
+ renewCtx, cancel := context.WithTimeout(ctx, l.renewalRequestTimeout())
+ lease.Spec.RenewTime = stringPtr(l.now().UTC().Format(time.RFC3339Nano))
+ updated, conflict, err := l.put(renewCtx, lease)
+ cancel()
+ if err != nil {
+ if ctx.Err() != nil {
+ return lease, nil
+ }
+ return lease, err
+ }
+ if conflict {
+ readCtx, readCancel := context.WithTimeout(ctx, l.renewalRequestTimeout())
+ current, err := l.get(readCtx)
+ readCancel()
+ if err != nil {
+ if ctx.Err() != nil {
+ return lease, nil
+ }
+ return lease, err
+ }
+ if current.Spec.HolderIdentity != l.holderIdentity {
+ return lease, ErrLeaseUnavailable
+ }
+ lease = current
+ continue
+ }
+ lease = updated
+ if l.renewed != nil {
+ l.renewed()
+ }
+ }
+ }
+}
+
+type renewalResult struct {
+ lease leaseObject
+ err error
+}
+
+func stringPtr(value string) *string { return &value }
+
+func (l *KubernetesLeaseLock) available(lease leaseObject) bool {
+ if lease.Spec.HolderIdentity == "" {
+ return true
+ }
+ if lease.Spec.HolderIdentity == l.holderIdentity {
+ return true
+ }
+ if lease.Spec.RenewTime == nil {
+ return true
+ }
+ renewedAt, err := time.Parse(time.RFC3339Nano, *lease.Spec.RenewTime)
+ if err != nil {
+ return false
+ }
+ duration := time.Duration(lease.Spec.LeaseDurationSeconds) * time.Second
+ if duration <= 0 {
+ duration = l.leaseDuration
+ }
+ return !l.now().Before(renewedAt.Add(duration))
+}
+
+func (l *KubernetesLeaseLock) release(ctx context.Context, lease leaseObject) {
+ lease.Spec.HolderIdentity = ""
+ lease.Spec.AcquireTime = nil
+ lease.Spec.RenewTime = nil
+ _, _, _ = l.put(ctx, lease)
+}
+
+func (l *KubernetesLeaseLock) get(ctx context.Context) (leaseObject, error) {
+ request, err := http.NewRequestWithContext(ctx, http.MethodGet, l.leaseURL(), nil)
+ if err != nil {
+ return leaseObject{}, fmt.Errorf("build lease GET: %w", err)
+ }
+ response, err := l.client.Do(request)
+ if err != nil {
+ return leaseObject{}, err
+ }
+ defer response.Body.Close()
+ if response.StatusCode == http.StatusNotFound {
+ return leaseObject{}, ErrLeaseNotFound
+ }
+ if response.StatusCode != http.StatusOK {
+ return leaseObject{}, fmt.Errorf("lease GET: unexpected HTTP status %d", response.StatusCode)
+ }
+ var lease leaseObject
+ if err := json.NewDecoder(response.Body).Decode(&lease); err != nil {
+ return leaseObject{}, fmt.Errorf("decode lease GET: %w", err)
+ }
+ return lease, nil
+}
+
+func (l *KubernetesLeaseLock) put(ctx context.Context, lease leaseObject) (leaseObject, bool, error) {
+ body, err := json.Marshal(lease)
+ if err != nil {
+ return leaseObject{}, false, fmt.Errorf("marshal lease PUT: %w", err)
+ }
+ request, err := http.NewRequestWithContext(ctx, http.MethodPut, l.leaseURL(), bytes.NewReader(body))
+ if err != nil {
+ return leaseObject{}, false, fmt.Errorf("build lease PUT: %w", err)
+ }
+ request.Header.Set("Content-Type", "application/json")
+ response, err := l.client.Do(request)
+ if err != nil {
+ return leaseObject{}, false, err
+ }
+ defer response.Body.Close()
+ if response.StatusCode == http.StatusConflict {
+ return leaseObject{}, true, nil
+ }
+ if response.StatusCode == http.StatusNotFound {
+ return leaseObject{}, false, ErrLeaseNotFound
+ }
+ if response.StatusCode < http.StatusOK || response.StatusCode >= http.StatusMultipleChoices {
+ return leaseObject{}, false, fmt.Errorf("lease PUT: unexpected HTTP status %d", response.StatusCode)
+ }
+ var updated leaseObject
+ if err := json.NewDecoder(response.Body).Decode(&updated); err != nil {
+ return leaseObject{}, false, fmt.Errorf("decode lease PUT: %w", err)
+ }
+ return updated, false, nil
+}
+
+func waitForLeaseRetry(ctx context.Context, interval time.Duration) error {
+ timer := time.NewTimer(interval)
+ defer timer.Stop()
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ case <-timer.C:
+ return nil
+ }
+}
+
+func (l *KubernetesLeaseLock) leaseURL() string {
+ return l.apiBaseURL + "/apis/coordination.k8s.io/v1/namespaces/" + l.namespace + "/leases/" + l.name
+}
+
+type leaseObject struct {
+ APIVersion string `json:"apiVersion,omitempty"`
+ Kind string `json:"kind,omitempty"`
+ Metadata leaseMetadata `json:"metadata"`
+ Spec leaseSpec `json:"spec"`
+}
+
+type leaseMetadata struct {
+ Name string `json:"name,omitempty"`
+ Namespace string `json:"namespace,omitempty"`
+ ResourceVersion string `json:"resourceVersion,omitempty"`
+}
+
+type leaseSpec struct {
+ HolderIdentity string `json:"holderIdentity,omitempty"`
+ LeaseDurationSeconds int32 `json:"leaseDurationSeconds,omitempty"`
+ AcquireTime *string `json:"acquireTime,omitempty"`
+ RenewTime *string `json:"renewTime,omitempty"`
+}
+
+func renewalTicker(interval time.Duration) (<-chan time.Time, func()) {
+ ticker := time.NewTicker(interval)
+ return ticker.C, ticker.Stop
+}
diff --git a/libs/fleet/backend/featureflagadmin/lease_test.go b/libs/fleet/backend/featureflagadmin/lease_test.go
new file mode 100644
index 0000000000..249d02a460
--- /dev/null
+++ b/libs/fleet/backend/featureflagadmin/lease_test.go
@@ -0,0 +1,470 @@
+package featureflagadmin
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "sync"
+ "testing"
+ "time"
+)
+
+func TestKubernetesLeaseLockAcquiresFreeLeaseWithResourceVersion(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "7"}})
+ defer server.Close()
+ clock := fixedClock(time.Date(2026, 8, 13, 12, 0, 0, 0, time.UTC))
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", 30*time.Second, time.Millisecond, clock)
+
+ calls := 0
+ if err := lock.WithLock(context.Background(), func(context.Context) error { calls++; return nil }); err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ if calls != 1 {
+ t.Fatalf("callback calls = %d, want 1", calls)
+ }
+ requests := server.Requests()
+ if len(requests) != 3 || requests[0].Method != http.MethodGet || requests[1].Method != http.MethodPut || requests[2].Method != http.MethodPut {
+ t.Fatalf("requests = %#v", requests)
+ }
+ if requests[1].Lease.Metadata.ResourceVersion != "7" || requests[1].Lease.Spec.HolderIdentity != "pod-a" {
+ t.Fatalf("acquire request = %#v", requests[1].Lease)
+ }
+ if requests[2].Lease.Spec.HolderIdentity != "" {
+ t.Fatalf("release request = %#v", requests[2].Lease)
+ }
+}
+
+func TestKubernetesLeaseLockTakesOverExpiredLease(t *testing.T) {
+ now := time.Date(2026, 8, 13, 12, 0, 0, 0, time.UTC)
+ expired := now.Add(-31 * time.Second).Format(time.RFC3339Nano)
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "3"}, Spec: leaseSpec{HolderIdentity: "old-pod", RenewTime: &expired, LeaseDurationSeconds: 30}})
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", 30*time.Second, time.Millisecond, fixedClock(now))
+
+ if err := lock.WithLock(context.Background(), func(context.Context) error { return nil }); err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ requests := server.Requests()
+ if requests[1].Lease.Spec.HolderIdentity != "pod-a" || requests[1].Lease.Metadata.ResourceVersion != "3" {
+ t.Fatalf("takeover request = %#v", requests[1].Lease)
+ }
+}
+
+func TestKubernetesLeaseLockWaitsForHeldLeaseUntilContextCanceled(t *testing.T) {
+ now := time.Date(2026, 8, 13, 12, 0, 0, 0, time.UTC)
+ renewed := now.Format(time.RFC3339Nano)
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "2"}, Spec: leaseSpec{HolderIdentity: "other-pod", RenewTime: &renewed, LeaseDurationSeconds: 60}})
+ defer server.Close()
+ waiting := make(chan struct{}, 1)
+ lock := newKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", 30*time.Second, time.Hour, fixedClock(now), leaseLockHooks{
+ waitForRetry: func(ctx context.Context, _ time.Duration) error {
+ waiting <- struct{}{}
+ <-ctx.Done()
+ return ctx.Err()
+ },
+ })
+ ctx, cancel := context.WithCancel(context.Background())
+ errDone := make(chan error, 1)
+ calls := 0
+ go func() {
+ errDone <- lock.WithLock(ctx, func(context.Context) error { calls++; return nil })
+ }()
+
+ <-waiting
+ cancel()
+ err := <-errDone
+ if !errors.Is(err, ErrLeaseUnavailable) {
+ t.Fatalf("WithLock() error = %v, want ErrLeaseUnavailable", err)
+ }
+ if calls != 0 || server.Count(http.MethodGet) != 1 {
+ t.Fatalf("callback calls=%d GETs=%d", calls, server.Count(http.MethodGet))
+ }
+}
+
+func TestKubernetesLeaseLockRejectsMissingPrecreatedLease(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{})
+ server.missing = true
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", 30*time.Second, time.Millisecond, time.Now)
+
+ err := lock.WithLock(context.Background(), func(context.Context) error { return nil })
+ if !errors.Is(err, ErrLeaseNotFound) {
+ t.Fatalf("WithLock() error = %v, want ErrLeaseNotFound", err)
+ }
+ if server.Count(http.MethodPost) != 0 {
+ t.Fatalf("POST count = %d, want 0", server.Count(http.MethodPost))
+ }
+}
+
+func TestKubernetesLeaseLockReleasesAfterCallbackContextIsCanceled(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", 30*time.Second, time.Millisecond, time.Now)
+ ctx, cancel := context.WithCancel(context.Background())
+
+ if err := lock.WithLock(ctx, func(context.Context) error { cancel(); return context.Canceled }); !errors.Is(err, context.Canceled) {
+ t.Fatalf("WithLock() error = %v, want context.Canceled", err)
+ }
+ requests := server.Requests()
+ if len(requests) != 3 || requests[2].Lease.Spec.HolderIdentity != "" {
+ t.Fatalf("requests = %#v", requests)
+ }
+}
+
+func TestKubernetesLeaseLockRetriesConflictAndBestEffortReleases(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ server.conflicts = 1
+ server.releaseStatus = http.StatusInternalServerError
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", 30*time.Second, time.Millisecond, time.Now)
+
+ if err := lock.WithLock(context.Background(), func(context.Context) error { return nil }); err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ if server.Count(http.MethodGet) != 2 || server.Count(http.MethodPut) != 3 {
+ t.Fatalf("GETs=%d PUTs=%d", server.Count(http.MethodGet), server.Count(http.MethodPut))
+ }
+}
+
+type recordedLeaseRequest struct {
+ Method string
+ Lease leaseObject
+}
+
+type leaseServer struct {
+ *httptest.Server
+ mu sync.Mutex
+ lease leaseObject
+ missing bool
+ conflicts int
+ releaseStatus int
+ requireCurrentResourceVersion bool
+ renewalLosesOwnership bool
+ acquireCompleted bool
+ requests []recordedLeaseRequest
+}
+
+func newLeaseServer(t *testing.T, initial leaseObject) *leaseServer {
+ t.Helper()
+ server := &leaseServer{lease: initial}
+ server.Server = httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+ server.mu.Lock()
+ defer server.mu.Unlock()
+ if request.URL.Path != "/apis/coordination.k8s.io/v1/namespaces/cyclops-cs/leases/cyclops-feature-flags-writer" {
+ http.NotFound(writer, request)
+ return
+ }
+ if server.missing {
+ http.NotFound(writer, request)
+ return
+ }
+ switch request.Method {
+ case http.MethodGet:
+ server.requests = append(server.requests, recordedLeaseRequest{Method: request.Method})
+ writeLeaseJSON(t, writer, server.lease)
+ case http.MethodPut:
+ var lease leaseObject
+ if err := json.NewDecoder(request.Body).Decode(&lease); err != nil {
+ t.Errorf("decode lease request: %v", err)
+ http.Error(writer, "invalid lease request", http.StatusBadRequest)
+ return
+ }
+ server.requests = append(server.requests, recordedLeaseRequest{Method: request.Method, Lease: lease})
+ if lease.Spec.HolderIdentity != "" && server.renewalLosesOwnership && server.acquireCompleted {
+ server.lease.Spec.HolderIdentity = "other-pod"
+ server.lease.Metadata.ResourceVersion = incrementResourceVersion(server.lease.Metadata.ResourceVersion)
+ writer.WriteHeader(http.StatusConflict)
+ return
+ }
+ if lease.Spec.HolderIdentity != "" && server.conflicts > 0 {
+ server.conflicts--
+ writer.WriteHeader(http.StatusConflict)
+ return
+ }
+ if lease.Spec.HolderIdentity == "" && server.releaseStatus != 0 {
+ writer.WriteHeader(server.releaseStatus)
+ return
+ }
+ resourceVersion := server.lease.Metadata.ResourceVersion
+ if resourceVersion == "" {
+ resourceVersion = "1"
+ }
+ if server.requireCurrentResourceVersion && lease.Metadata.ResourceVersion != resourceVersion {
+ writer.WriteHeader(http.StatusConflict)
+ return
+ }
+ lease.Metadata.ResourceVersion = incrementResourceVersion(resourceVersion)
+ server.lease = lease
+ if lease.Spec.HolderIdentity != "" {
+ server.acquireCompleted = true
+ }
+ writeLeaseJSON(t, writer, lease)
+ default:
+ writer.WriteHeader(http.StatusMethodNotAllowed)
+ }
+ }))
+ return server
+}
+
+func (s *leaseServer) Requests() []recordedLeaseRequest {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ requests := make([]recordedLeaseRequest, len(s.requests))
+ copy(requests, s.requests)
+ return requests
+}
+
+func (s *leaseServer) Count(method string) int {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ count := 0
+ for _, request := range s.requests {
+ if request.Method == method {
+ count++
+ }
+ }
+ return count
+}
+
+func writeLeaseJSON(t *testing.T, writer http.ResponseWriter, lease leaseObject) {
+ t.Helper()
+ writer.Header().Set("Content-Type", "application/json")
+ if err := json.NewEncoder(writer).Encode(lease); err != nil {
+ t.Errorf("encode lease response: %v", err)
+ }
+}
+
+func fixedClock(now time.Time) func() time.Time { return func() time.Time { return now } }
+
+func TestKubernetesLeaseLockSerializesSamePodCallbacks(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, time.Millisecond, time.Now)
+
+ firstStarted := make(chan struct{})
+ allowFirstExit := make(chan struct{})
+ secondStarted := make(chan struct{})
+ errors := make(chan error, 2)
+ go func() {
+ errors <- lock.WithLock(context.Background(), func(context.Context) error {
+ close(firstStarted)
+ <-allowFirstExit
+ return nil
+ })
+ }()
+ <-firstStarted
+ go func() {
+ errors <- lock.WithLock(context.Background(), func(context.Context) error {
+ close(secondStarted)
+ return nil
+ })
+ }()
+
+ select {
+ case <-secondStarted:
+ t.Fatal("second callback entered while the first callback still held the same-pod lock")
+ case <-time.After(25 * time.Millisecond):
+ }
+ close(allowFirstExit)
+ if err := <-errors; err != nil {
+ t.Fatalf("first WithLock() error = %v", err)
+ }
+ select {
+ case <-secondStarted:
+ case <-time.After(time.Second):
+ t.Fatal("second callback did not enter after first callback exited")
+ }
+ if err := <-errors; err != nil {
+ t.Fatalf("second WithLock() error = %v", err)
+ }
+}
+
+func TestKubernetesLeaseLockRenewsLongCallbackBeforeTakeover(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ defer server.Close()
+ owner := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, 10*time.Millisecond, time.Now)
+ contender := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-b", time.Second, 10*time.Millisecond, time.Now)
+
+ ownerStarted := make(chan struct{})
+ allowOwnerExit := make(chan struct{})
+ ownerDone := make(chan error, 1)
+ go func() {
+ ownerDone <- owner.WithLock(context.Background(), func(context.Context) error {
+ close(ownerStarted)
+ <-allowOwnerExit
+ return nil
+ })
+ }()
+ <-ownerStarted
+ time.Sleep(1200 * time.Millisecond)
+
+ ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+ defer cancel()
+ contenderCalls := 0
+ err := contender.WithLock(ctx, func(context.Context) error { contenderCalls++; return nil })
+ if !errors.Is(err, ErrLeaseUnavailable) || contenderCalls != 0 {
+ t.Fatalf("contender error=%v calls=%d, want unavailable and 0 calls", err, contenderCalls)
+ }
+ close(allowOwnerExit)
+ if err := <-ownerDone; err != nil {
+ t.Fatalf("owner WithLock() error = %v", err)
+ }
+}
+
+func TestKubernetesLeaseLockSerializesSeparateInstancesWithSameHolder(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ defer server.Close()
+ first := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, time.Millisecond, time.Now)
+ second := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, time.Millisecond, time.Now)
+
+ firstStarted := make(chan struct{})
+ allowFirstExit := make(chan struct{})
+ secondStarted := make(chan struct{})
+ errors := make(chan error, 2)
+ go func() {
+ errors <- first.WithLock(context.Background(), func(context.Context) error {
+ close(firstStarted)
+ <-allowFirstExit
+ return nil
+ })
+ }()
+ <-firstStarted
+ go func() {
+ errors <- second.WithLock(context.Background(), func(context.Context) error {
+ close(secondStarted)
+ return nil
+ })
+ }()
+
+ select {
+ case <-secondStarted:
+ t.Fatal("separate same-holder lock instance entered while the first callback was active")
+ case <-time.After(25 * time.Millisecond):
+ }
+ close(allowFirstExit)
+ if err := <-errors; err != nil {
+ t.Fatalf("first WithLock() error = %v", err)
+ }
+ select {
+ case <-secondStarted:
+ case <-time.After(time.Second):
+ t.Fatal("second callback did not enter after first callback exited")
+ }
+ if err := <-errors; err != nil {
+ t.Fatalf("second WithLock() error = %v", err)
+ }
+}
+
+func TestKubernetesLeaseLockReleasesRenewedLeaseVersion(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ server.requireCurrentResourceVersion = true
+ defer server.Close()
+ renewalTicks := make(chan time.Time)
+ renewalCompleted := make(chan struct{})
+ lock := newKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, 10*time.Millisecond, time.Now, leaseLockHooks{
+ renewalTicks: func(time.Duration) (<-chan time.Time, func()) { return renewalTicks, func() {} },
+ renewed: func() { close(renewalCompleted) },
+ })
+
+ if err := lock.WithLock(context.Background(), func(context.Context) error {
+ renewalTicks <- time.Now()
+ <-renewalCompleted
+ return nil
+ }); err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ requests := server.Requests()
+ if len(requests) < 4 || requests[len(requests)-1].Lease.Spec.HolderIdentity != "" {
+ t.Fatalf("requests = %#v", requests)
+ }
+ server.mu.Lock()
+ defer server.mu.Unlock()
+ if server.lease.Spec.HolderIdentity != "" {
+ t.Fatalf("lease holder = %q, want released", server.lease.Spec.HolderIdentity)
+ }
+}
+
+func incrementResourceVersion(value string) string {
+ if value == "1" {
+ return "2"
+ }
+ return value + "-next"
+}
+
+func TestKubernetesLeaseLockCancelsInFlightRenewalWhenCallbackCompletes(t *testing.T) {
+ var mu sync.Mutex
+ lease := leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}}
+ renewalStarted := make(chan struct{})
+ renewalCanceled := make(chan struct{})
+ server := httptest.NewServer(http.HandlerFunc(func(writer http.ResponseWriter, request *http.Request) {
+ mu.Lock()
+ defer mu.Unlock()
+ switch request.Method {
+ case http.MethodGet:
+ writeLeaseJSON(t, writer, lease)
+ case http.MethodPut:
+ var updated leaseObject
+ if err := json.NewDecoder(request.Body).Decode(&updated); err != nil {
+ t.Errorf("decode lease: %v", err)
+ http.Error(writer, "invalid lease request", http.StatusBadRequest)
+ return
+ }
+ if updated.Spec.HolderIdentity != "" && lease.Spec.HolderIdentity != "" {
+ close(renewalStarted)
+ mu.Unlock()
+ <-request.Context().Done()
+ close(renewalCanceled)
+ mu.Lock()
+ return
+ }
+ updated.Metadata.ResourceVersion = incrementResourceVersion(lease.Metadata.ResourceVersion)
+ lease = updated
+ writeLeaseJSON(t, writer, updated)
+ default:
+ writer.WriteHeader(http.StatusMethodNotAllowed)
+ }
+ }))
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, 10*time.Millisecond, time.Now)
+
+ started := time.Now()
+ err := lock.WithLock(context.Background(), func(context.Context) error {
+ select {
+ case <-renewalStarted:
+ return nil
+ case <-time.After(2 * time.Second):
+ return errors.New("renewal did not start")
+ }
+ })
+ if err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ if elapsed := time.Since(started); elapsed > 1500*time.Millisecond {
+ t.Fatalf("WithLock() returned after %v, want prompt shutdown", elapsed)
+ }
+ select {
+ case <-renewalCanceled:
+ case <-time.After(time.Second):
+ t.Fatal("in-flight renewal request was not canceled")
+ }
+}
+
+func TestKubernetesLeaseLockReleasesUnusedLifecycleGuard(t *testing.T) {
+ leaseLifecycleGuardsMu.Lock()
+ leaseLifecycleGuards = map[string]*lifecycleGuard{}
+ leaseLifecycleGuardsMu.Unlock()
+
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, time.Millisecond, time.Now)
+ if err := lock.WithLock(context.Background(), func(context.Context) error { return nil }); err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ leaseLifecycleGuardsMu.Lock()
+ defer leaseLifecycleGuardsMu.Unlock()
+ if len(leaseLifecycleGuards) != 0 {
+ t.Fatalf("lifecycle guards = %#v, want empty after lock lifecycle", leaseLifecycleGuards)
+ }
+}
diff --git a/libs/fleet/backend/featureflagadmin/service.go b/libs/fleet/backend/featureflagadmin/service.go
new file mode 100644
index 0000000000..23294a313e
--- /dev/null
+++ b/libs/fleet/backend/featureflagadmin/service.go
@@ -0,0 +1,450 @@
+package featureflagadmin
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "regexp"
+ "sort"
+ "strings"
+ "time"
+
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+const Prefix = "/feature-flags/cyclops-cs/"
+
+var keyPattern = regexp.MustCompile(`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`)
+
+type Ownership string
+
+const (
+ OwnershipTerraform Ownership = "terraform"
+ OwnershipAdHoc Ownership = "ad_hoc"
+ OwnershipExternal Ownership = "external"
+)
+
+type Flag struct {
+ Key string `json:"key"`
+ Path string `json:"path"`
+ ValueType featureflags.ValueType `json:"value_type"`
+ Value any `json:"value"`
+ RawValue string `json:"raw_value"`
+ Ownership Ownership `json:"ownership"`
+ ManagedBy string `json:"managed_by,omitempty"`
+ Deletable bool `json:"deletable"`
+ Version int64 `json:"version"`
+ ModifiedAt time.Time `json:"modified_at"`
+ Description string `json:"description,omitempty"`
+ Tags map[string]string `json:"tags"`
+}
+
+type Actor struct {
+ Subject string
+ Email string
+ PrincipalType string
+ TraceID string
+}
+
+type CreateInput struct {
+ Key string
+ ValueType featureflags.ValueType
+ Value any
+ Description string
+}
+
+type UpdateInput struct {
+ ValueType featureflags.ValueType
+ Value any
+ ExpectedVersion int64
+}
+
+type AuditEvent struct {
+ Event string
+ Timestamp time.Time
+ Actor Actor
+ Operation string
+ Key string
+ Path string
+ Ownership Ownership
+ OldValue *featureflags.TypedValue
+ NewValue *featureflags.TypedValue
+ ExpectedVersion int64
+ PreviousVersion int64
+ ResultVersion int64
+ Result string
+ Reason string
+}
+
+type MutationLock interface {
+ WithLock(context.Context, func(context.Context) error) error
+}
+
+type CacheInvalidator interface {
+ InvalidateFeatureFlags()
+}
+
+type AuditLogger interface {
+ Log(context.Context, AuditEvent)
+}
+
+type ServiceError struct {
+ Code string
+ HTTPStatus int
+ Message string
+ Current *Flag
+ Cause error
+}
+
+func (e *ServiceError) Error() string { return e.Message }
+
+func (e *ServiceError) Unwrap() error { return e.Cause }
+
+type Service struct {
+ store featureflags.ManagementStore
+ lock MutationLock
+ invalidator CacheInvalidator
+ audit AuditLogger
+}
+
+func NewService(store featureflags.ManagementStore, lock MutationLock, invalidator CacheInvalidator, audit AuditLogger) *Service {
+ if store == nil {
+ store = unsupportedStore{}
+ }
+ return &Service{store: store, lock: lock, invalidator: invalidator, audit: audit}
+}
+
+func (s *Service) List(ctx context.Context) ([]Flag, error) {
+ parameters, err := s.store.List(ctx, Prefix)
+ if err != nil {
+ return nil, errors.Join(serviceStoreError(err), err)
+ }
+ flags := make([]Flag, 0, len(parameters))
+ for _, parameter := range parameters {
+ if parameter.Type == "SecureString" {
+ continue
+ }
+ key, ok := keyFromPath(parameter.Name)
+ if !ok {
+ continue
+ }
+ flag, err := flagFromParameter(key, parameter)
+ if err != nil {
+ return nil, err
+ }
+ flags = append(flags, flag)
+ }
+ sort.Slice(flags, func(i, j int) bool { return flags[i].Key < flags[j].Key })
+ return flags, nil
+}
+
+func (s *Service) Create(ctx context.Context, actor Actor, input CreateInput) (flag Flag, err error) {
+ path := Prefix + input.Key
+ event := AuditEvent{Event: "feature_flag_admin", Timestamp: time.Now().UTC(), Actor: actor, Operation: "create", Key: input.Key, Path: path, Ownership: OwnershipAdHoc, Result: "rejected"}
+ defer func() { s.logAudit(ctx, event, err) }()
+
+ err = s.withLock(ctx, func(lockCtx context.Context) error {
+ if err := validateKey(input.Key); err != nil {
+ return err
+ }
+ typed, err := featureflags.SerializeTypedValue(input.ValueType, input.Value)
+ if err != nil {
+ return errors.Join(invalidValueError(err), err)
+ }
+ event.NewValue = &typed
+ if input.Key == "admin-subs" {
+ if err := validateAdminSubs(typed); err != nil {
+ return err
+ }
+ }
+ parameter, err := s.store.Create(lockCtx, featureflags.Parameter{
+ Name: path, Value: typed.Raw, Type: "String", Description: input.Description,
+ Tags: map[string]string{"ManagedBy": "cyclops-cs-admin", "Feature": "cyclops-cs", "Environment": "production"},
+ })
+ if err != nil {
+ return errors.Join(serviceStoreError(err), err)
+ }
+ flag, err = flagFromParameter(input.Key, parameter)
+ if err != nil {
+ return err
+ }
+ event.ResultVersion = flag.Version
+ event.Result = "success"
+ if s.invalidator != nil {
+ s.invalidator.InvalidateFeatureFlags()
+ }
+ return nil
+ })
+ return flag, err
+}
+
+func (s *Service) Update(ctx context.Context, actor Actor, key string, input UpdateInput) (flag Flag, err error) {
+ path := Prefix + key
+ event := AuditEvent{Event: "feature_flag_admin", Timestamp: time.Now().UTC(), Actor: actor, Operation: "update", Key: key, Path: path, ExpectedVersion: input.ExpectedVersion, Result: "rejected"}
+ defer func() { s.logAudit(ctx, event, err) }()
+
+ err = s.withLock(ctx, func(lockCtx context.Context) error {
+ if err := validateKey(key); err != nil {
+ return err
+ }
+ parameter, err := s.store.Get(lockCtx, path)
+ if err != nil {
+ return errors.Join(serviceStoreError(err), err)
+ }
+ current, err := flagFromParameter(key, parameter)
+ if err != nil {
+ return err
+ }
+ event.Ownership = current.Ownership
+ event.PreviousVersion = current.Version
+ old := featureflags.TypedValue{Type: current.ValueType, Value: current.Value, Raw: current.RawValue}
+ event.OldValue = &old
+ if current.Version != input.ExpectedVersion {
+ typed, serializeErr := featureflags.SerializeTypedValue(input.ValueType, input.Value)
+ if serializeErr != nil {
+ return errors.Join(&ServiceError{Code: "version_conflict", HTTPStatus: 409, Message: "feature flag version is stale", Current: &current, Cause: serializeErr}, serializeErr)
+ }
+ event.NewValue = &typed
+ return &ServiceError{Code: "version_conflict", HTTPStatus: 409, Message: "feature flag version is stale", Current: &current}
+ }
+ typed, err := featureflags.SerializeTypedValue(input.ValueType, input.Value)
+ if err != nil {
+ return errors.Join(invalidValueError(err), err)
+ }
+ event.NewValue = &typed
+ if key == "admin-subs" {
+ if err := validateAdminSubs(typed); err != nil {
+ return err
+ }
+ }
+ parameter, err = s.store.Update(lockCtx, path, typed.Raw)
+ if err != nil {
+ return errors.Join(serviceStoreError(err), err)
+ }
+ flag, err = flagFromParameter(key, parameter)
+ if err != nil {
+ return err
+ }
+ event.ResultVersion = flag.Version
+ event.Result = "success"
+ if s.invalidator != nil {
+ s.invalidator.InvalidateFeatureFlags()
+ }
+ return nil
+ })
+ return flag, err
+}
+
+func (s *Service) Delete(ctx context.Context, actor Actor, key string, expectedVersion int64) (err error) {
+ path := Prefix + key
+ event := AuditEvent{Event: "feature_flag_admin", Timestamp: time.Now().UTC(), Actor: actor, Operation: "delete", Key: key, Path: path, ExpectedVersion: expectedVersion, Result: "rejected"}
+ defer func() { s.logAudit(ctx, event, err) }()
+
+ err = s.withLock(ctx, func(lockCtx context.Context) error {
+ if err := validateKey(key); err != nil {
+ return err
+ }
+ if key == "admin-subs" {
+ return &ServiceError{Code: "last_admin", HTTPStatus: 422, Message: "admin-subs cannot be deleted"}
+ }
+ parameter, err := s.store.Get(lockCtx, path)
+ if err != nil {
+ return errors.Join(serviceStoreError(err), err)
+ }
+ current, err := flagFromParameter(key, parameter)
+ if err != nil {
+ return err
+ }
+ event.Ownership = current.Ownership
+ event.PreviousVersion = current.Version
+ old := featureflags.TypedValue{Type: current.ValueType, Value: current.Value, Raw: current.RawValue}
+ event.OldValue = &old
+ if current.Version != expectedVersion {
+ return &ServiceError{Code: "version_conflict", HTTPStatus: 409, Message: "feature flag version is stale", Current: &current}
+ }
+ if !current.Deletable {
+ code := "unknown_ownership"
+ message := "feature flag ownership is unknown and does not permit deletion"
+ if current.Ownership == OwnershipTerraform {
+ code = "managed_flag"
+ message = "Terraform-managed feature flags cannot be deleted"
+ }
+ return &ServiceError{Code: code, HTTPStatus: 422, Message: message, Current: &current}
+ }
+ if err := s.store.Delete(lockCtx, path); err != nil {
+ return errors.Join(serviceStoreError(err), err)
+ }
+ event.Result = "success"
+ if s.invalidator != nil {
+ s.invalidator.InvalidateFeatureFlags()
+ }
+ return nil
+ })
+ return err
+}
+
+func (s *Service) withLock(ctx context.Context, callback func(context.Context) error) error {
+ if s.lock == nil {
+ return &ServiceError{Code: "mutation_lock_unconfigured", HTTPStatus: 500, Message: "feature flag mutation lock is not configured"}
+ }
+ if err := s.lock.WithLock(ctx, callback); err != nil {
+ if errors.Is(err, ErrLeaseNotFound) {
+ return errors.Join(&ServiceError{Code: "lease_not_found", HTTPStatus: 503, Message: "feature flag mutation lease was not found", Cause: err}, err)
+ }
+ if errors.Is(err, ErrLeaseUnavailable) {
+ return errors.Join(&ServiceError{Code: "lease_unavailable", HTTPStatus: 503, Message: "feature flag mutation lock is unavailable", Cause: err}, err)
+ }
+ return err
+ }
+ return nil
+}
+
+func (s *Service) logAudit(_ context.Context, event AuditEvent, err error) {
+ if s.audit == nil {
+ return
+ }
+ if err != nil {
+ event.Result = "rejected"
+ var serviceError *ServiceError
+ if errors.As(err, &serviceError) {
+ event.Reason = serviceError.Code
+ } else {
+ event.Reason = "internal_error"
+ }
+ }
+ auditCtx, cancel := context.WithTimeout(context.Background(), time.Second)
+ defer cancel()
+ s.audit.Log(auditCtx, event)
+}
+
+func flagFromParameter(key string, parameter featureflags.Parameter) (Flag, error) {
+ if parameter.Type == "SecureString" {
+ return Flag{}, &ServiceError{Code: "unsupported_parameter", HTTPStatus: 422, Message: "SecureString feature flags are unsupported"}
+ }
+ typed, err := featureflags.InferTypedValue(parameter.Value)
+ if err != nil {
+ return Flag{}, fmt.Errorf("infer feature flag value: %w", err)
+ }
+ managedBy := parameter.Tags["ManagedBy"]
+ ownership := ownershipFromManagedBy(managedBy)
+ return Flag{
+ Key: key, Path: parameter.Name, ValueType: typed.Type, Value: typed.Value, RawValue: typed.Raw,
+ Ownership: ownership, ManagedBy: managedBy, Deletable: ownership == OwnershipAdHoc,
+ Version: parameter.Version, ModifiedAt: parameter.LastModified, Description: parameter.Description, Tags: cloneTags(parameter.Tags),
+ }, nil
+}
+
+func ownershipFromManagedBy(managedBy string) Ownership {
+ switch managedBy {
+ case "terraform":
+ return OwnershipTerraform
+ case "cyclops-cs-admin":
+ return OwnershipAdHoc
+ default:
+ return OwnershipExternal
+ }
+}
+
+func keyFromPath(path string) (string, bool) {
+ if !strings.HasPrefix(path, Prefix) {
+ return "", false
+ }
+ key := strings.TrimPrefix(path, Prefix)
+ if validateKey(key) != nil {
+ return "", false
+ }
+ return key, true
+}
+
+func validateKey(key string) error {
+ if len(key) == 0 || len(key) > 63 || !keyPattern.MatchString(key) {
+ return &ServiceError{Code: "invalid_key", HTTPStatus: 400, Message: "feature flag key must be a lowercase DNS label"}
+ }
+ return nil
+}
+
+func validateAdminSubs(typed featureflags.TypedValue) error {
+ if typed.Type != featureflags.ValueJSON {
+ return &ServiceError{Code: "invalid_value", HTTPStatus: 422, Message: "admin-subs must be a JSON string array"}
+ }
+ var values []any
+ if err := json.Unmarshal([]byte(typed.Raw), &values); err != nil {
+ return errors.Join(&ServiceError{Code: "invalid_value", HTTPStatus: 422, Message: "admin-subs must be a JSON string array", Cause: err}, err)
+ }
+ if len(values) == 0 {
+ return &ServiceError{Code: "last_admin", HTTPStatus: 422, Message: "admin-subs must contain at least one administrator"}
+ }
+ seen := make(map[string]struct{}, len(values))
+ for _, value := range values {
+ subject, ok := value.(string)
+ if !ok || subject == "" {
+ return &ServiceError{Code: "invalid_value", HTTPStatus: 422, Message: "admin-subs must contain non-empty strings"}
+ }
+ if _, duplicate := seen[subject]; duplicate {
+ return &ServiceError{Code: "invalid_value", HTTPStatus: 422, Message: "admin-subs must not contain duplicate subjects"}
+ }
+ seen[subject] = struct{}{}
+ }
+ return nil
+}
+
+func invalidValueError(err error) error {
+ return &ServiceError{Code: "invalid_value", HTTPStatus: 400, Message: fmt.Sprintf("invalid feature flag value: %v", err), Cause: err}
+}
+
+func serviceStoreError(err error) error {
+ if errors.Is(err, featureflags.ErrSecureString) {
+ return &ServiceError{Code: "unsupported_parameter", HTTPStatus: 422, Message: "SecureString feature flags are unsupported", Cause: err}
+ }
+ switch {
+ case errors.Is(err, featureflags.ErrUnsupportedProvider):
+ return &ServiceError{Code: "unsupported_provider", HTTPStatus: 501, Message: "feature flag management provider is unsupported", Cause: err}
+ case errors.Is(err, featureflags.ErrParameterExists):
+ return &ServiceError{Code: "flag_exists", HTTPStatus: 409, Message: "feature flag already exists", Cause: err}
+ case errors.Is(err, featureflags.ErrParameterNotFound):
+ return &ServiceError{Code: "flag_not_found", HTTPStatus: 404, Message: "feature flag not found", Cause: err}
+ case errors.Is(err, featureflags.ErrAccessDenied):
+ return &ServiceError{Code: "access_denied", HTTPStatus: 403, Message: "feature flag store access denied", Cause: err}
+ default:
+ return &ServiceError{Code: "store_error", HTTPStatus: 502, Message: "feature flag store operation failed", Cause: err}
+ }
+}
+
+func cloneTags(tags map[string]string) map[string]string {
+ if tags == nil {
+ return map[string]string{}
+ }
+ cloned := make(map[string]string, len(tags))
+ for key, value := range tags {
+ cloned[key] = value
+ }
+ return cloned
+}
+
+type unsupportedStore struct{}
+
+func (unsupportedStore) List(context.Context, string) ([]featureflags.Parameter, error) {
+ return nil, featureflags.ErrUnsupportedProvider
+}
+func (unsupportedStore) Get(context.Context, string) (featureflags.Parameter, error) {
+ return featureflags.Parameter{}, featureflags.ErrUnsupportedProvider
+}
+func (unsupportedStore) Create(context.Context, featureflags.Parameter) (featureflags.Parameter, error) {
+ return featureflags.Parameter{}, featureflags.ErrUnsupportedProvider
+}
+func (unsupportedStore) Update(context.Context, string, string) (featureflags.Parameter, error) {
+ return featureflags.Parameter{}, featureflags.ErrUnsupportedProvider
+}
+func (unsupportedStore) Delete(context.Context, string) error {
+ return featureflags.ErrUnsupportedProvider
+}
+
+type noOpMutationLock struct{}
+
+func (noOpMutationLock) WithLock(ctx context.Context, callback func(context.Context) error) error {
+ return callback(ctx)
+}
+func NewUnsupportedService(audit AuditLogger) *Service {
+ return NewService(unsupportedStore{}, noOpMutationLock{}, nil, audit)
+}
diff --git a/libs/fleet/backend/featureflagadmin/service_test.go b/libs/fleet/backend/featureflagadmin/service_test.go
new file mode 100644
index 0000000000..3e1d4e70b5
--- /dev/null
+++ b/libs/fleet/backend/featureflagadmin/service_test.go
@@ -0,0 +1,667 @@
+package featureflagadmin
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "sort"
+ "testing"
+ "time"
+
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+func TestServiceListClassifiesOwnershipAndFiltersNestedKeys(t *testing.T) {
+ modifiedAt := time.Date(2026, 8, 13, 12, 0, 0, 0, time.UTC)
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "terraform-flag": {
+ Name: Prefix + "terraform-flag", Value: "true", Type: "String", Version: 3, LastModified: modifiedAt,
+ Tags: map[string]string{"ManagedBy": "terraform"},
+ },
+ Prefix + "ad-hoc-flag": {
+ Name: Prefix + "ad-hoc-flag", Value: "value", Type: "String", Version: 4, LastModified: modifiedAt,
+ Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"},
+ },
+ Prefix + "external-flag": {
+ Name: Prefix + "external-flag", Value: "false", Type: "String", Version: 5, LastModified: modifiedAt,
+ Tags: map[string]string{"ManagedBy": "another-system"},
+ },
+ Prefix + "nested/flag": {
+ Name: Prefix + "nested/flag", Value: "ignored", Type: "String", Version: 6, LastModified: modifiedAt,
+ },
+ Prefix + "secret": {
+ Name: Prefix + "secret", Value: "ignored", Type: "SecureString", Version: 7, LastModified: modifiedAt,
+ },
+ }}
+
+ flags, err := NewService(store, nil, nil, nil).List(context.Background())
+ if err != nil {
+ t.Fatalf("List() error = %v", err)
+ }
+ if len(flags) != 3 {
+ t.Fatalf("List() returned %d flags, want 3: %#v", len(flags), flags)
+ }
+
+ if flags[0].Key != "ad-hoc-flag" || flags[0].Ownership != OwnershipAdHoc || !flags[0].Deletable {
+ t.Fatalf("ad hoc flag = %#v", flags[0])
+ }
+ if flags[1].Key != "external-flag" || flags[1].Ownership != OwnershipExternal || flags[1].Deletable {
+ t.Fatalf("external flag = %#v", flags[1])
+ }
+ if flags[2].Key != "terraform-flag" || flags[2].Ownership != OwnershipTerraform || flags[2].Deletable {
+ t.Fatalf("terraform flag = %#v", flags[2])
+ }
+}
+
+func TestServiceListReturnsTypedValuesAndVersions(t *testing.T) {
+ modifiedAt := time.Date(2026, 8, 13, 12, 0, 0, 0, time.UTC)
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "boolean": {Name: Prefix + "boolean", Value: "true", Type: "String", Version: 1, LastModified: modifiedAt},
+ Prefix + "json": {Name: Prefix + "json", Value: `{"items":[1,"two"]}`, Type: "String", Version: 2, LastModified: modifiedAt},
+ Prefix + "number": {Name: Prefix + "number", Value: "42.5", Type: "String", Version: 3, LastModified: modifiedAt},
+ Prefix + "string": {Name: Prefix + "string", Value: "hello", Type: "String", Version: 4, LastModified: modifiedAt},
+ }}
+
+ flags, err := NewService(store, nil, nil, nil).List(context.Background())
+ if err != nil {
+ t.Fatalf("List() error = %v", err)
+ }
+ byKey := map[string]Flag{}
+ for _, flag := range flags {
+ byKey[flag.Key] = flag
+ }
+
+ if got := byKey["boolean"]; got.ValueType != featureflags.ValueBoolean || got.Value != true || got.RawValue != "true" || got.Version != 1 || !got.ModifiedAt.Equal(modifiedAt) {
+ t.Fatalf("boolean flag = %#v", got)
+ }
+ if got := byKey["number"]; got.ValueType != featureflags.ValueNumber || got.RawValue != "42.5" || got.Version != 3 {
+ t.Fatalf("number flag = %#v", got)
+ }
+ if got := byKey["string"]; got.ValueType != featureflags.ValueString || got.Value != "hello" || got.RawValue != "hello" || got.Version != 4 {
+ t.Fatalf("string flag = %#v", got)
+ }
+ jsonFlag := byKey["json"]
+ if jsonFlag.ValueType != featureflags.ValueJSON || jsonFlag.RawValue != `{"items":[1,"two"]}` || jsonFlag.Version != 2 {
+ t.Fatalf("json flag = %#v", jsonFlag)
+ }
+ encoded, err := json.Marshal(jsonFlag.Value)
+ if err != nil || string(encoded) != `{"items":[1,"two"]}` {
+ t.Fatalf("json flag value = %s, %v", encoded, err)
+ }
+}
+
+type fakeStore struct {
+ parameters map[string]featureflags.Parameter
+ updateErr error
+ deleteErr error
+}
+
+func (s *fakeStore) List(_ context.Context, prefix string) ([]featureflags.Parameter, error) {
+ parameters := make([]featureflags.Parameter, 0, len(s.parameters))
+ for path, parameter := range s.parameters {
+ if len(path) >= len(prefix) && path[:len(prefix)] == prefix {
+ parameters = append(parameters, cloneParameter(parameter))
+ }
+ }
+ sort.Slice(parameters, func(i, j int) bool { return parameters[i].Name < parameters[j].Name })
+ return parameters, nil
+}
+
+func (s *fakeStore) Get(_ context.Context, path string) (featureflags.Parameter, error) {
+ parameter, ok := s.parameters[path]
+ if !ok {
+ return featureflags.Parameter{}, featureflags.ErrParameterNotFound
+ }
+ return cloneParameter(parameter), nil
+}
+
+func (s *fakeStore) Create(_ context.Context, parameter featureflags.Parameter) (featureflags.Parameter, error) {
+ if _, exists := s.parameters[parameter.Name]; exists {
+ return featureflags.Parameter{}, featureflags.ErrParameterExists
+ }
+ parameter.Version = 1
+ s.parameters[parameter.Name] = cloneParameter(parameter)
+ return cloneParameter(parameter), nil
+}
+
+func (s *fakeStore) Update(_ context.Context, path, value string) (featureflags.Parameter, error) {
+ updateErr := s.updateErr
+ if updateErr != nil {
+ return featureflags.Parameter{}, errors.Join(updateErr)
+ }
+ parameter, ok := s.parameters[path]
+ if !ok {
+ return featureflags.Parameter{}, featureflags.ErrParameterNotFound
+ }
+ parameter.Value = value
+ parameter.Version++
+ s.parameters[path] = cloneParameter(parameter)
+ return cloneParameter(parameter), nil
+}
+
+func (s *fakeStore) Delete(_ context.Context, path string) error {
+ deleteErr := s.deleteErr
+ if deleteErr != nil {
+ return errors.Join(deleteErr)
+ }
+ if _, ok := s.parameters[path]; !ok {
+ return featureflags.ErrParameterNotFound
+ }
+ delete(s.parameters, path)
+ return nil
+}
+
+func TestServiceMapsSecureStringMutationErrors(t *testing.T) {
+ parameter := featureflags.Parameter{Name: Prefix + "secret", Value: "opaque", Type: "String", Version: 4, Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}}
+ for _, testCase := range []struct {
+ name string
+ run func(*Service) error
+ store *fakeStore
+ }{
+ {name: "update", store: &fakeStore{parameters: map[string]featureflags.Parameter{parameter.Name: parameter}, updateErr: featureflags.ErrSecureString}, run: func(service *Service) error {
+ _, err := service.Update(context.Background(), Actor{}, "secret", UpdateInput{ValueType: featureflags.ValueString, Value: "replacement", ExpectedVersion: 4})
+ return err
+ }},
+ {name: "delete", store: &fakeStore{parameters: map[string]featureflags.Parameter{parameter.Name: parameter}, deleteErr: featureflags.ErrSecureString}, run: func(service *Service) error {
+ return service.Delete(context.Background(), Actor{}, "secret", 4)
+ }},
+ } {
+ t.Run(testCase.name, func(t *testing.T) {
+ err := testCase.run(NewService(testCase.store, &fakeLock{}, nil, nil))
+ var serviceError *ServiceError
+ if !errors.As(err, &serviceError) {
+ t.Fatalf("error = %v, want ServiceError", err)
+ }
+ if serviceError.Code != "unsupported_parameter" || serviceError.HTTPStatus != 422 {
+ t.Fatalf("error = %#v", serviceError)
+ }
+ })
+ }
+}
+
+func cloneParameter(parameter featureflags.Parameter) featureflags.Parameter {
+ cloned := parameter
+ if parameter.Tags != nil {
+ cloned.Tags = make(map[string]string, len(parameter.Tags))
+ for key, value := range parameter.Tags {
+ cloned.Tags[key] = value
+ }
+ }
+ return cloned
+}
+
+type fakeLock struct {
+ calls int
+ err error
+}
+
+func (l *fakeLock) WithLock(ctx context.Context, callback func(context.Context) error) error {
+ l.calls++
+ lockErr := l.err
+ if lockErr != nil {
+ return errors.Join(lockErr)
+ }
+ return callback(ctx)
+}
+
+type fakeInvalidator struct{ calls int }
+
+func (i *fakeInvalidator) InvalidateFeatureFlags() { i.calls++ }
+
+type fakeAuditLogger struct{ events []AuditEvent }
+
+func (l *fakeAuditLogger) Log(_ context.Context, event AuditEvent) {
+ l.events = append(l.events, event)
+}
+
+func TestServiceCreateTagsAndInvalidatesAfterSuccess(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{}}
+ lock := &fakeLock{}
+ invalidator := &fakeInvalidator{}
+ audit := &fakeAuditLogger{}
+ actor := Actor{Subject: "admin", Email: "[email protected]", PrincipalType: "spa", TraceID: "trace-1"}
+
+ flag, err := NewService(store, lock, invalidator, audit).Create(context.Background(), actor, CreateInput{
+ Key: "new-flag", ValueType: featureflags.ValueJSON, Value: map[string]any{"enabled": true}, Description: "new flag",
+ })
+ if err != nil {
+ t.Fatalf("Create() error = %v", err)
+ }
+ parameter := store.parameters[Prefix+"new-flag"]
+ if parameter.Value != `{"enabled":true}` || parameter.Description != "new flag" {
+ t.Fatalf("created parameter = %#v", parameter)
+ }
+ wantTags := map[string]string{"ManagedBy": "cyclops-cs-admin", "Feature": "cyclops-cs", "Environment": "production"}
+ if !equalTags(parameter.Tags, wantTags) {
+ t.Fatalf("created tags = %#v, want %#v", parameter.Tags, wantTags)
+ }
+ if flag.Ownership != OwnershipAdHoc || !flag.Deletable || invalidator.calls != 1 || lock.calls != 1 {
+ t.Fatalf("Create() flag=%#v invalidations=%d locks=%d", flag, invalidator.calls, lock.calls)
+ }
+ if len(audit.events) != 1 || audit.events[0].Result != "success" || audit.events[0].ResultVersion != 1 {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+}
+
+func TestServiceCreateRejectsDuplicateWithoutInvalidation(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "existing": {Name: Prefix + "existing", Value: "true", Type: "String", Version: 1},
+ }}
+ invalidator := &fakeInvalidator{}
+ audit := &fakeAuditLogger{}
+
+ _, err := NewService(store, &fakeLock{}, invalidator, audit).Create(context.Background(), Actor{}, CreateInput{
+ Key: "existing", ValueType: featureflags.ValueBoolean, Value: true,
+ })
+ assertServiceError(t, err, "flag_exists", 409)
+ if invalidator.calls != 0 {
+ t.Fatalf("invalidations = %d, want 0", invalidator.calls)
+ }
+ if len(audit.events) != 1 || audit.events[0].Result != "rejected" || audit.events[0].Reason != "flag_exists" {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+}
+
+func TestServiceMapsMissingFlagToStableError(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{}}
+ _, err := NewService(store, &fakeLock{}, nil, nil).Update(context.Background(), Actor{}, "missing", UpdateInput{
+ ValueType: featureflags.ValueBoolean, Value: true, ExpectedVersion: 1,
+ })
+ assertServiceError(t, err, "flag_not_found", 404)
+}
+
+func TestServiceRejectsInvalidKeysBeforeStoreCalls(t *testing.T) {
+ for _, key := range []string{"", "UPPER", "nested/key", Prefix + "escape", string(make([]byte, 64))} {
+ t.Run(key, func(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{}}
+ _, err := NewService(store, &fakeLock{}, nil, nil).Create(context.Background(), Actor{}, CreateInput{
+ Key: key, ValueType: featureflags.ValueString, Value: "value",
+ })
+ assertServiceError(t, err, "invalid_key", 400)
+ if len(store.parameters) != 0 {
+ t.Fatalf("store was changed for invalid key %q", key)
+ }
+ })
+ }
+}
+
+func TestServiceUpdateAllowsTerraformAndExternalOwnership(t *testing.T) {
+ for _, managedBy := range []string{"terraform", "another-system"} {
+ t.Run(managedBy, func(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "old", Type: "String", Version: 4, Tags: map[string]string{"ManagedBy": managedBy}},
+ }}
+ invalidator := &fakeInvalidator{}
+ flag, err := NewService(store, &fakeLock{}, invalidator, nil).Update(context.Background(), Actor{}, "flag", UpdateInput{
+ ValueType: featureflags.ValueString, Value: "new", ExpectedVersion: 4,
+ })
+ if err != nil {
+ t.Fatalf("Update() error = %v", err)
+ }
+ if flag.Version != 5 || store.parameters[Prefix+"flag"].Value != "new" || invalidator.calls != 1 {
+ t.Fatalf("updated flag=%#v parameter=%#v invalidations=%d", flag, store.parameters[Prefix+"flag"], invalidator.calls)
+ }
+ })
+ }
+}
+
+func TestServiceUpdateRejectsStaleVersionWithoutInvalidation(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "old", Type: "String", Version: 4},
+ }}
+ invalidator := &fakeInvalidator{}
+ audit := &fakeAuditLogger{}
+
+ _, err := NewService(store, &fakeLock{}, invalidator, audit).Update(context.Background(), Actor{}, "flag", UpdateInput{
+ ValueType: featureflags.ValueString, Value: "new", ExpectedVersion: 3,
+ })
+ serviceError := assertServiceError(t, err, "version_conflict", 409)
+ if serviceError.Current == nil || serviceError.Current.Version != 4 || store.parameters[Prefix+"flag"].Value != "old" || invalidator.calls != 0 {
+ t.Fatalf("conflict=%#v parameter=%#v invalidations=%d", serviceError, store.parameters[Prefix+"flag"], invalidator.calls)
+ }
+ if len(audit.events) != 1 || audit.events[0].PreviousVersion != 4 || audit.events[0].Reason != "version_conflict" {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+}
+
+func TestServiceDeleteAllowsAdHocAndProtectsOtherOwnership(t *testing.T) {
+ for _, testCase := range []struct {
+ name string
+ managedBy string
+ wantError string
+ }{
+ {name: "ad hoc", managedBy: "cyclops-cs-admin"},
+ {name: "terraform", managedBy: "terraform", wantError: "managed_flag"},
+ {name: "external", managedBy: "other", wantError: "unknown_ownership"},
+ } {
+ t.Run(testCase.name, func(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "old", Type: "String", Version: 2, Tags: map[string]string{"ManagedBy": testCase.managedBy}},
+ }}
+ invalidator := &fakeInvalidator{}
+ err := NewService(store, &fakeLock{}, invalidator, nil).Delete(context.Background(), Actor{}, "flag", 2)
+ if testCase.wantError != "" {
+ assertServiceError(t, err, testCase.wantError, 422)
+ if invalidator.calls != 0 {
+ t.Fatalf("invalidations = %d, want 0", invalidator.calls)
+ }
+ return
+ }
+ if err != nil || invalidator.calls != 1 {
+ t.Fatalf("Delete() error=%v invalidations=%d", err, invalidator.calls)
+ }
+ if _, exists := store.parameters[Prefix+"flag"]; exists {
+ t.Fatal("ad hoc flag still exists after delete")
+ }
+ })
+ }
+}
+
+func TestServiceNeverDeletesAdminSubs(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "admin-subs": {Name: Prefix + "admin-subs", Value: `["actor"]`, Type: "String", Version: 2, Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}},
+ }}
+ audit := &fakeAuditLogger{}
+ err := NewService(store, &fakeLock{}, nil, audit).Delete(context.Background(), Actor{Subject: "actor"}, "admin-subs", 2)
+ assertServiceError(t, err, "last_admin", 422)
+ if _, exists := store.parameters[Prefix+"admin-subs"]; !exists {
+ t.Fatal("admin-subs was deleted")
+ }
+ if len(audit.events) != 1 || audit.events[0].Reason != "last_admin" {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+}
+
+func TestServiceDeleteSuccessAuditsNoResultVersion(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "true", Type: "String", Version: 7, Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}},
+ }}
+ audit := &fakeAuditLogger{}
+ if err := NewService(store, &fakeLock{}, nil, audit).Delete(context.Background(), Actor{}, "flag", 7); err != nil {
+ t.Fatal(err)
+ }
+ if len(audit.events) != 1 || audit.events[0].ResultVersion != 0 || audit.events[0].PreviousVersion != 7 {
+ t.Fatalf("delete audit = %#v", audit.events)
+ }
+}
+
+func TestUpdateAdminSubsAllowsSelfRemovalWhenAnotherAdminRemains(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "admin-subs": {Name: Prefix + "admin-subs", Value: `["actor","other"]`, Type: "String", Version: 1},
+ }}
+ _, err := NewService(store, &fakeLock{}, nil, nil).Update(context.Background(), Actor{Subject: "actor"}, "admin-subs", UpdateInput{
+ ValueType: featureflags.ValueJSON, Value: []any{"other"}, ExpectedVersion: 1,
+ })
+ if err != nil || store.parameters[Prefix+"admin-subs"].Value != `["other"]` {
+ t.Fatalf("Update(admin-subs) error=%v value=%q", err, store.parameters[Prefix+"admin-subs"].Value)
+ }
+}
+
+func TestUpdateAdminSubsRejectsEmptyArray(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "admin-subs": {Name: Prefix + "admin-subs", Value: `["actor"]`, Type: "String", Version: 1},
+ }}
+ _, err := NewService(store, &fakeLock{}, nil, nil).Update(context.Background(), Actor{}, "admin-subs", UpdateInput{
+ ValueType: featureflags.ValueJSON, Value: []any{}, ExpectedVersion: 1,
+ })
+ assertServiceError(t, err, "last_admin", 422)
+}
+
+func TestUpdateAdminSubsRejectsDuplicatesAndNonStrings(t *testing.T) {
+ for _, value := range []any{[]any{"one", "one"}, []any{"one", 2}} {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "admin-subs": {Name: Prefix + "admin-subs", Value: `["actor"]`, Type: "String", Version: 1},
+ }}
+ _, err := NewService(store, &fakeLock{}, nil, nil).Update(context.Background(), Actor{}, "admin-subs", UpdateInput{
+ ValueType: featureflags.ValueJSON, Value: value, ExpectedVersion: 1,
+ })
+ assertServiceError(t, err, "invalid_value", 422)
+ }
+}
+
+func TestServiceAuditsStructuredSuccessAndRejection(t *testing.T) {
+ actor := Actor{Subject: "subject", Email: "[email protected]", PrincipalType: "spa", TraceID: "trace-123"}
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "false", Type: "String", Version: 7, Tags: map[string]string{"ManagedBy": "terraform"}},
+ }}
+ audit := &fakeAuditLogger{}
+ service := NewService(store, &fakeLock{}, nil, audit)
+
+ if _, err := service.Update(context.Background(), actor, "flag", UpdateInput{ValueType: featureflags.ValueBoolean, Value: true, ExpectedVersion: 7}); err != nil {
+ t.Fatalf("Update() error = %v", err)
+ }
+ if _, err := service.Update(context.Background(), actor, "flag", UpdateInput{ValueType: featureflags.ValueBoolean, Value: false, ExpectedVersion: 7}); err == nil {
+ t.Fatal("stale Update() unexpectedly succeeded")
+ }
+ if len(audit.events) != 2 {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+ success := audit.events[0]
+ if success.Actor != actor || success.Operation != "update" || success.Path != Prefix+"flag" || success.Ownership != OwnershipTerraform || success.OldValue == nil || success.NewValue == nil || success.OldValue.Value != false || success.NewValue.Value != true || success.ExpectedVersion != 7 || success.PreviousVersion != 7 || success.ResultVersion != 8 || success.Result != "success" || success.Reason != "" {
+ t.Fatalf("success audit event = %#v", success)
+ }
+ rejected := audit.events[1]
+ if rejected.Actor != actor || rejected.OldValue == nil || rejected.NewValue == nil || rejected.NewValue.Value != false || rejected.ExpectedVersion != 7 || rejected.PreviousVersion != 8 || rejected.Result != "rejected" || rejected.Reason != "version_conflict" {
+ t.Fatalf("rejected audit event = %#v", rejected)
+ }
+}
+
+func assertServiceError(t *testing.T, err error, code string, status int) *ServiceError {
+ t.Helper()
+ var serviceError *ServiceError
+ if !errors.As(err, &serviceError) {
+ t.Fatalf("error = %v, want ServiceError code %q", err, code)
+ }
+ if serviceError.Code != code || serviceError.HTTPStatus != status || serviceError.Message == "" {
+ t.Fatalf("service error = %#v, want code=%q status=%d", serviceError, code, status)
+ }
+ return serviceError
+}
+
+func equalTags(got, want map[string]string) bool {
+ if len(got) != len(want) {
+ return false
+ }
+ for key, value := range want {
+ if got[key] != value {
+ return false
+ }
+ }
+ return true
+}
+
+func TestServiceReturnsStableLeaseUnavailableError(t *testing.T) {
+ lock := &fakeLock{err: ErrLeaseUnavailable}
+ invalidator := &fakeInvalidator{}
+ audit := &fakeAuditLogger{}
+ service := NewService(&fakeStore{parameters: map[string]featureflags.Parameter{}}, lock, invalidator, audit)
+
+ _, err := service.Create(context.Background(), Actor{}, CreateInput{Key: "flag", ValueType: featureflags.ValueBoolean, Value: true})
+ assertServiceError(t, err, "lease_unavailable", 503)
+ if invalidator.calls != 0 || len(audit.events) != 1 || audit.events[0].Reason != "lease_unavailable" {
+ t.Fatalf("invalidations=%d audit=%#v", invalidator.calls, audit.events)
+ }
+}
+
+func TestServiceCreateAdminSubsRejectsInvalidArrays(t *testing.T) {
+ for _, testCase := range []struct {
+ name string
+ valueType featureflags.ValueType
+ value any
+ code string
+ }{
+ {name: "non JSON type", valueType: featureflags.ValueString, value: `["admin"]`, code: "invalid_value"},
+ {name: "empty", valueType: featureflags.ValueJSON, value: []any{}, code: "last_admin"},
+ {name: "duplicate", valueType: featureflags.ValueJSON, value: []any{"admin", "admin"}, code: "invalid_value"},
+ {name: "empty member", valueType: featureflags.ValueJSON, value: []any{""}, code: "invalid_value"},
+ {name: "non string member", valueType: featureflags.ValueJSON, value: []any{"admin", 1}, code: "invalid_value"},
+ } {
+ t.Run(testCase.name, func(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{}}
+ invalidator := &fakeInvalidator{}
+ _, err := NewService(store, &fakeLock{}, invalidator, nil).Create(context.Background(), Actor{}, CreateInput{
+ Key: "admin-subs", ValueType: testCase.valueType, Value: testCase.value,
+ })
+ assertServiceError(t, err, testCase.code, 422)
+ if len(store.parameters) != 0 || invalidator.calls != 0 {
+ t.Fatalf("parameters=%#v invalidations=%d", store.parameters, invalidator.calls)
+ }
+ })
+ }
+}
+
+func TestServiceUpdateReturnsVersionConflictBeforeInvalidValueValidation(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "true", Type: "String", Version: 4},
+ }}
+
+ _, err := NewService(store, &fakeLock{}, nil, nil).Update(context.Background(), Actor{}, "flag", UpdateInput{
+ ValueType: featureflags.ValueBoolean, Value: "not-a-bool", ExpectedVersion: 3,
+ })
+ serviceError := assertServiceError(t, err, "version_conflict", 409)
+ if serviceError.Current == nil || serviceError.Current.Version != 4 {
+ t.Fatalf("current = %#v", serviceError.Current)
+ }
+}
+
+func TestServiceRejectsNilMutationLockWithoutStoreMutation(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{}}
+ audit := &fakeAuditLogger{}
+ _, err := NewService(store, nil, nil, audit).Create(context.Background(), Actor{}, CreateInput{
+ Key: "flag", ValueType: featureflags.ValueBoolean, Value: true,
+ })
+ assertServiceError(t, err, "mutation_lock_unconfigured", 500)
+ if len(store.parameters) != 0 || len(audit.events) != 1 || audit.events[0].Reason != "mutation_lock_unconfigured" {
+ t.Fatalf("parameters=%#v audit=%#v", store.parameters, audit.events)
+ }
+}
+
+type contextAuditLogger struct {
+ calls int
+ event AuditEvent
+ err error
+}
+
+type contextFailingLock struct{}
+
+func (contextFailingLock) WithLock(ctx context.Context, _ func(context.Context) error) error {
+ return ctx.Err()
+}
+
+func (l *contextAuditLogger) Log(ctx context.Context, event AuditEvent) {
+ l.calls++
+ l.event = event
+ l.err = ctx.Err()
+}
+
+func TestServiceAuditsExactlyOnceWithDetachedContextAfterCancellation(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{}}
+ audit := &contextAuditLogger{}
+ ctx, cancel := context.WithCancel(context.Background())
+ cancel()
+
+ _, err := NewService(store, contextFailingLock{}, nil, audit).Create(ctx, Actor{TraceID: "trace"}, CreateInput{
+ Key: "flag", ValueType: featureflags.ValueBoolean, Value: true,
+ })
+ if err == nil {
+ t.Fatal("Create() unexpectedly succeeded")
+ }
+ if audit.calls != 1 || audit.err != nil || audit.event.Actor.TraceID != "trace" || audit.event.Result != "rejected" {
+ t.Fatalf("audit calls=%d err=%v event=%#v", audit.calls, audit.err, audit.event)
+ }
+}
+
+func TestServiceUpdateAuditsValidSubmittedValueOnStaleConflict(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "true", Type: "String", Version: 4},
+ }}
+ audit := &fakeAuditLogger{}
+
+ _, err := NewService(store, &fakeLock{}, nil, audit).Update(context.Background(), Actor{}, "flag", UpdateInput{
+ ValueType: featureflags.ValueBoolean, Value: false, ExpectedVersion: 3,
+ })
+ assertServiceError(t, err, "version_conflict", 409)
+ if len(audit.events) != 1 || audit.events[0].NewValue == nil || audit.events[0].NewValue.Value != false {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+}
+
+func TestServiceUpdateAuditsInvalidSubmittedValueAsVersionConflict(t *testing.T) {
+ store := &fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "true", Type: "String", Version: 4},
+ }}
+ audit := &fakeAuditLogger{}
+
+ _, err := NewService(store, &fakeLock{}, nil, audit).Update(context.Background(), Actor{}, "flag", UpdateInput{
+ ValueType: featureflags.ValueBoolean, Value: "not-a-bool", ExpectedVersion: 3,
+ })
+ assertServiceError(t, err, "version_conflict", 409)
+ if len(audit.events) != 1 || audit.events[0].Reason != "version_conflict" || audit.events[0].NewValue != nil {
+ t.Fatalf("audit events = %#v", audit.events)
+ }
+}
+
+type contextBlockingStore struct {
+ fakeStore
+ updateStarted chan struct{}
+ updateErr error
+}
+
+func (s *contextBlockingStore) Update(ctx context.Context, path, value string) (featureflags.Parameter, error) {
+ close(s.updateStarted)
+ <-ctx.Done()
+ s.updateErr = ctx.Err()
+ return featureflags.Parameter{}, ctx.Err()
+}
+
+func TestServiceStopsStoreWorkWhenLeaseRenewalLosesOwnership(t *testing.T) {
+ server := newLeaseServer(t, leaseObject{Metadata: leaseMetadata{ResourceVersion: "1"}})
+ server.renewalLosesOwnership = true
+ defer server.Close()
+ lock := NewKubernetesLeaseLock(server.URL, "cyclops-cs", "cyclops-feature-flags-writer", "pod-a", time.Second, 10*time.Millisecond, time.Now)
+ store := &contextBlockingStore{fakeStore: fakeStore{parameters: map[string]featureflags.Parameter{
+ Prefix + "flag": {Name: Prefix + "flag", Value: "true", Type: "String", Version: 1},
+ }}, updateStarted: make(chan struct{})}
+
+ result := make(chan error, 1)
+ go func() {
+ _, err := NewService(store, lock, nil, nil).Update(context.Background(), Actor{}, "flag", UpdateInput{
+ ValueType: featureflags.ValueBoolean, Value: false, ExpectedVersion: 1,
+ })
+ result <- err
+ }()
+ select {
+ case <-store.updateStarted:
+ case <-time.After(time.Second):
+ t.Fatal("store update did not start")
+ }
+ select {
+ case err := <-result:
+ assertServiceError(t, err, "lease_unavailable", 503)
+ case <-time.After(2 * time.Second):
+ t.Fatal("service did not stop the store update after lease loss")
+ }
+ if !errors.Is(store.updateErr, context.Canceled) {
+ t.Fatalf("store update error = %v, want context cancellation", store.updateErr)
+ }
+}
+
+func TestServiceMapsMissingLeaseToStableError(t *testing.T) {
+ service := NewService(&fakeStore{parameters: map[string]featureflags.Parameter{}}, &fakeLock{err: ErrLeaseNotFound}, nil, nil)
+ _, err := service.Create(context.Background(), Actor{}, CreateInput{Key: "flag", ValueType: featureflags.ValueBoolean, Value: true})
+ assertServiceError(t, err, "lease_not_found", 503)
+}
+
+func TestServiceNilStoreFailsClosed(t *testing.T) {
+ service := NewService(nil, &fakeLock{}, nil, nil)
+ if _, err := service.List(context.Background()); err == nil {
+ t.Fatal("List() error = nil")
+ } else {
+ assertServiceError(t, err, "unsupported_provider", 501)
+ }
+ if _, err := service.Create(context.Background(), Actor{}, CreateInput{Key: "flag", ValueType: featureflags.ValueBoolean, Value: true}); err == nil {
+ t.Fatal("Create() error = nil")
+ } else {
+ assertServiceError(t, err, "unsupported_provider", 501)
+ }
+}
diff --git a/libs/fleet/backend/handlers/config_test.go b/libs/fleet/backend/handlers/config_test.go
index 2813b29d3d..c3d6dd94b9 100644
--- a/libs/fleet/backend/handlers/config_test.go
+++ b/libs/fleet/backend/handlers/config_test.go
@@ -9,6 +9,7 @@ import (
"cyclops-cs-backend/auth"
"cyclops-cs-backend/config"
+ "github.com/trycua/cloud/pkg/featureflags"
)
func TestGetConfigReturnsEffectiveChatAccess(t *testing.T) {
@@ -55,11 +56,40 @@ func TestGetConfigReturnsEffectiveUsageAccess(t *testing.T) {
h := Handlers{usageAccessEvaluator: func(context.Context, *auth.User) (bool, error) { return true, nil }, adminAccessEvaluator: func(context.Context, *auth.User) (bool, error) { return false, nil }}
w := httptest.NewRecorder()
h.GetConfig(w, withUser(httptest.NewRequest(http.MethodGet, "/api/config", nil), &auth.User{ID: "user", AZP: "cyclops-cs-spa"}))
- var r ConfigResponse
- if err := json.Unmarshal(w.Body.Bytes(), &r); err != nil {
+ var response ConfigResponse
+ if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
t.Fatal(err)
}
- if !r.Usage {
+ if !response.Usage {
t.Fatal("usage false")
}
}
+
+func TestGetConfigBypassesAnotherReplicasStaleAdminCache(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["removed-admin"]`)
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup provider: %v", err)
+ }
+ auth.InvalidateFeatureFlags()
+ auth.LoadOpa()
+ user := &auth.User{ID: "removed-admin", AZP: "cyclops-cs-spa"}
+ if admin, err := auth.EvalIsAdmin(context.Background(), user); err != nil || !admin {
+ t.Fatalf("prime stale replica cache: admin=%v err=%v", admin, err)
+ }
+
+ // Replica A committed removal; this process never received invalidation.
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `[]`)
+ request := withUser(httptest.NewRequest(http.MethodGet, "/api/config", nil), user)
+ response := httptest.NewRecorder()
+ Handlers{}.GetConfig(response, request)
+ if response.Code != http.StatusOK {
+ t.Fatalf("status = %d; body = %s", response.Code, response.Body.String())
+ }
+ var config ConfigResponse
+ if err := json.NewDecoder(response.Body).Decode(&config); err != nil {
+ t.Fatal(err)
+ }
+ if config.Admin {
+ t.Fatal("removed administrator remained admin through stale replica cache")
+ }
+}
diff --git a/libs/fleet/backend/handlers/feature_flags.go b/libs/fleet/backend/handlers/feature_flags.go
new file mode 100644
index 0000000000..1ab9b4cfe7
--- /dev/null
+++ b/libs/fleet/backend/handlers/feature_flags.go
@@ -0,0 +1,293 @@
+package handlers
+
+import (
+ "bytes"
+ "encoding/json"
+ "errors"
+ "io"
+ "log/slog"
+ "net/http"
+ "strings"
+
+ "cyclops-cs-backend/auth"
+ "cyclops-cs-backend/featureflagadmin"
+ "cyclops-cs-backend/middlewares"
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+type CreateFeatureFlagRequest struct {
+ Key string `json:"key"`
+ ValueType featureflags.ValueType `json:"value_type"`
+ Value any `json:"value"`
+ Description string `json:"description,omitempty"`
+}
+
+type UpdateFeatureFlagRequest struct {
+ ValueType featureflags.ValueType `json:"value_type"`
+ Value any `json:"value"`
+ ExpectedVersion int64 `json:"expected_version"`
+}
+
+type DeleteFeatureFlagRequest struct {
+ ExpectedVersion int64 `json:"expected_version"`
+}
+
+type AdminAPIError struct {
+ Code string `json:"code"`
+ Message string `json:"message"`
+ Current *featureflagadmin.Flag `json:"current,omitempty"`
+}
+
+const maxFeatureFlagRequestBytes = 64 << 10
+
+// ListFeatureFlags godoc
+// @Summary List Cyclops feature flags
+// @Description Lists direct non-SecureString parameters under /feature-flags/cyclops-cs/ with typed values, ownership, and SSM versions.
+// @Tags admin feature flags
+// @Produce json
+// @Success 200 {array} featureflagadmin.Flag
+// @Failure 401 {object} ErrorResponse
+// @Failure 403 {object} AdminAPIError
+// @Failure 501 {object} AdminAPIError
+// @Failure 502 {object} AdminAPIError
+// @Security BearerAuth
+// @Router /api/admin/feature-flags [get]
+func (h Handlers) ListFeatureFlags(w http.ResponseWriter, r *http.Request) {
+ if !h.requireFeatureFlagAdmin(w, r) {
+ return
+ }
+ if h.FeatureFlags == nil {
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "unsupported_provider", HTTPStatus: http.StatusNotImplemented, Message: "feature flag management is unavailable"})
+ return
+ }
+ flags, err := h.FeatureFlags.List(r.Context())
+ if err != nil {
+ writeAdminAPIError(w, err)
+ return
+ }
+ writeJSON(w, http.StatusOK, flags)
+}
+
+// CreateFeatureFlag godoc
+// @Summary Create an ad hoc Cyclops feature flag
+// @Description Creates a String parameter under /feature-flags/cyclops-cs/ with cyclops-cs-admin ownership and a typed logical value.
+// @Tags admin feature flags
+// @Accept json
+// @Produce json
+// @Param request body CreateFeatureFlagRequest true "Feature flag to create"
+// @Success 201 {object} featureflagadmin.Flag
+// @Failure 400 {object} AdminAPIError
+// @Failure 401 {object} ErrorResponse
+// @Failure 403 {object} AdminAPIError
+// @Failure 409 {object} AdminAPIError
+// @Failure 422 {object} AdminAPIError
+// @Failure 500 {object} AdminAPIError
+// @Failure 501 {object} AdminAPIError
+// @Failure 502 {object} AdminAPIError
+// @Failure 503 {object} AdminAPIError
+// @Security BearerAuth
+// @Router /api/admin/feature-flags [post]
+func (h Handlers) CreateFeatureFlag(w http.ResponseWriter, r *http.Request) {
+ if !h.requireFeatureFlagAdmin(w, r) {
+ return
+ }
+ var request CreateFeatureFlagRequest
+ if !decodeFeatureFlagJSON(w, r, &request) {
+ return
+ }
+ if h.FeatureFlags == nil {
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "unsupported_provider", HTTPStatus: http.StatusNotImplemented, Message: "feature flag management is unavailable"})
+ return
+ }
+ flag, err := h.FeatureFlags.Create(r.Context(), featureFlagActor(r), featureflagadmin.CreateInput{Key: request.Key, ValueType: request.ValueType, Value: request.Value, Description: request.Description})
+ if err != nil {
+ writeAdminAPIError(w, err)
+ return
+ }
+ writeJSON(w, http.StatusCreated, flag)
+}
+
+// UpdateFeatureFlag godoc
+// @Summary Update a Cyclops feature flag value
+// @Description Updates the typed value when expected_version matches. Terraform and external ownership protect the key from deletion, not value edits.
+// @Tags admin feature flags
+// @Accept json
+// @Produce json
+// @Param key path string true "Flat feature flag key"
+// @Param request body UpdateFeatureFlagRequest true "Typed value and expected SSM version"
+// @Success 200 {object} featureflagadmin.Flag
+// @Failure 400 {object} AdminAPIError
+// @Failure 401 {object} ErrorResponse
+// @Failure 403 {object} AdminAPIError
+// @Failure 404 {object} AdminAPIError
+// @Failure 409 {object} AdminAPIError
+// @Failure 422 {object} AdminAPIError
+// @Failure 500 {object} AdminAPIError
+// @Failure 501 {object} AdminAPIError
+// @Failure 502 {object} AdminAPIError
+// @Failure 503 {object} AdminAPIError
+// @Security BearerAuth
+// @Router /api/admin/feature-flags/{key} [put]
+func (h Handlers) UpdateFeatureFlag(w http.ResponseWriter, r *http.Request) {
+ if !h.requireFeatureFlagAdmin(w, r) {
+ return
+ }
+ var request UpdateFeatureFlagRequest
+ if !decodeFeatureFlagJSON(w, r, &request) {
+ return
+ }
+ if h.FeatureFlags == nil {
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "unsupported_provider", HTTPStatus: http.StatusNotImplemented, Message: "feature flag management is unavailable"})
+ return
+ }
+ flag, err := h.FeatureFlags.Update(r.Context(), featureFlagActor(r), r.PathValue("key"), featureflagadmin.UpdateInput{ValueType: request.ValueType, Value: request.Value, ExpectedVersion: request.ExpectedVersion})
+ if err != nil {
+ writeAdminAPIError(w, err)
+ return
+ }
+ writeJSON(w, http.StatusOK, flag)
+}
+
+// DeleteFeatureFlag godoc
+// @Summary Delete an ad hoc Cyclops feature flag
+// @Description Deletes only cyclops-cs-admin-owned flags when expected_version matches. Terraform and external keys are protected.
+// @Tags admin feature flags
+// @Accept json
+// @Produce json
+// @Param key path string true "Flat feature flag key"
+// @Param request body DeleteFeatureFlagRequest true "Expected SSM version"
+// @Success 204
+// @Failure 400 {object} AdminAPIError
+// @Failure 401 {object} ErrorResponse
+// @Failure 403 {object} AdminAPIError
+// @Failure 404 {object} AdminAPIError
+// @Failure 409 {object} AdminAPIError
+// @Failure 422 {object} AdminAPIError
+// @Failure 500 {object} AdminAPIError
+// @Failure 501 {object} AdminAPIError
+// @Failure 502 {object} AdminAPIError
+// @Failure 503 {object} AdminAPIError
+// @Security BearerAuth
+// @Router /api/admin/feature-flags/{key} [delete]
+func (h Handlers) DeleteFeatureFlag(w http.ResponseWriter, r *http.Request) {
+ if !h.requireFeatureFlagAdmin(w, r) {
+ return
+ }
+ var request DeleteFeatureFlagRequest
+ if !decodeFeatureFlagJSON(w, r, &request) {
+ return
+ }
+ if h.FeatureFlags == nil {
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "unsupported_provider", HTTPStatus: http.StatusNotImplemented, Message: "feature flag management is unavailable"})
+ return
+ }
+ if err := h.FeatureFlags.Delete(r.Context(), featureFlagActor(r), r.PathValue("key"), request.ExpectedVersion); err != nil {
+ writeAdminAPIError(w, err)
+ return
+ }
+ w.WriteHeader(http.StatusNoContent)
+}
+
+var evalFeatureFlagAdmin = auth.EvalIsAdminFresh
+
+func (h Handlers) requireFeatureFlagAdmin(w http.ResponseWriter, r *http.Request) bool {
+ allowed, err := evalFeatureFlagAdmin(r.Context(), currentUser(r))
+ if err != nil {
+ slog.WarnContext(r.Context(), "opa: feature flag admin eval failed", "err", err)
+ if r.Method != http.MethodGet {
+ logFeatureFlagAdminRejection(r, "policy_error")
+ }
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "policy_error", HTTPStatus: http.StatusInternalServerError, Message: "feature flag authorization evaluation failed"})
+ return false
+ }
+ if allowed {
+ return true
+ }
+ if r.Method != http.MethodGet {
+ logFeatureFlagAdminRejection(r, "not_admin")
+ }
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "not_admin", HTTPStatus: http.StatusForbidden, Message: "feature flag administration requires an admin user"})
+ return false
+}
+
+func featureFlagActor(r *http.Request) featureflagadmin.Actor {
+ user := currentUser(r)
+ if user == nil {
+ return featureflagadmin.Actor{}
+ }
+ traceID, _ := r.Context().Value(middlewares.ContextKey("traceId")).(string)
+ return featureflagadmin.Actor{Subject: user.ID, Email: user.Email, PrincipalType: user.PrincipalType, TraceID: traceID}
+}
+
+func decodeFeatureFlagJSON(w http.ResponseWriter, r *http.Request, destination any) bool {
+ defer r.Body.Close()
+ body, err := io.ReadAll(io.LimitReader(r.Body, maxFeatureFlagRequestBytes+1))
+ if err != nil || len(body) > maxFeatureFlagRequestBytes {
+ logInvalidFeatureFlagRequest(r, "body_too_large")
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "invalid_request", HTTPStatus: http.StatusBadRequest, Message: "request body exceeds 64 KiB"})
+ return false
+ }
+ decoder := json.NewDecoder(bytes.NewReader(body))
+ decoder.DisallowUnknownFields()
+ decoder.UseNumber()
+ if err := decoder.Decode(destination); err != nil {
+ parseFailure := "malformed_json"
+ if strings.HasPrefix(err.Error(), "json: unknown field ") {
+ parseFailure = "unknown_field"
+ }
+ logInvalidFeatureFlagRequest(r, parseFailure)
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "invalid_request", HTTPStatus: http.StatusBadRequest, Message: "request body must be valid JSON"})
+ return false
+ }
+ var extra any
+ if err := decoder.Decode(&extra); err != io.EOF {
+ logInvalidFeatureFlagRequest(r, "trailing_data")
+ writeAdminAPIError(w, &featureflagadmin.ServiceError{Code: "invalid_request", HTTPStatus: http.StatusBadRequest, Message: "request body must contain one JSON value"})
+ return false
+ }
+ return true
+}
+
+func logFeatureFlagAdminRejection(r *http.Request, reason string) {
+ actor := featureFlagActor(r)
+ key := r.PathValue("key")
+ slog.WarnContext(r.Context(), "feature flag mutation rejected by handler authorization",
+ "event", "feature_flag_admin",
+ "actor", actor.Subject,
+ "actor_email", actor.Email,
+ "principal_type", actor.PrincipalType,
+ "operation", strings.ToLower(r.Method),
+ "key", featureflagadmin.BoundedAuditKey(key),
+ "path", featureflagadmin.BoundedAuditPath(r.URL.Path, key),
+ "traceId", actor.TraceID,
+ "result", "rejected",
+ "reason", reason,
+ )
+}
+
+func logInvalidFeatureFlagRequest(r *http.Request, parseFailure string) {
+ actor := featureFlagActor(r)
+ key := r.PathValue("key")
+ slog.WarnContext(r.Context(), "feature flag mutation request rejected",
+ "event", "feature_flag_admin",
+ "actor", actor.Subject,
+ "actor_email", actor.Email,
+ "principal_type", actor.PrincipalType,
+ "operation", strings.ToLower(r.Method),
+ "key", featureflagadmin.BoundedAuditKey(key),
+ "path", featureflagadmin.BoundedAuditPath(r.URL.Path, key),
+ "traceId", actor.TraceID,
+ "result", "rejected",
+ "reason", "invalid_request",
+ "parse_failure", parseFailure,
+ )
+}
+
+func writeAdminAPIError(w http.ResponseWriter, err error) {
+ var serviceError *featureflagadmin.ServiceError
+ if errors.As(err, &serviceError) {
+ writeJSON(w, serviceError.HTTPStatus, AdminAPIError{Code: serviceError.Code, Message: serviceError.Message, Current: serviceError.Current})
+ return
+ }
+ writeJSON(w, http.StatusInternalServerError, AdminAPIError{Code: "internal_error", Message: "feature flag operation failed"})
+}
diff --git a/libs/fleet/backend/handlers/feature_flags_test.go b/libs/fleet/backend/handlers/feature_flags_test.go
new file mode 100644
index 0000000000..e7fe9a8cbf
--- /dev/null
+++ b/libs/fleet/backend/handlers/feature_flags_test.go
@@ -0,0 +1,467 @@
+package handlers
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "errors"
+ "io"
+ "log/slog"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "cyclops-cs-backend/auth"
+ "cyclops-cs-backend/featureflagadmin"
+ "cyclops-cs-backend/middlewares"
+ "github.com/trycua/cloud/pkg/featureflags"
+)
+
+type featureFlagStore struct {
+ parameters map[string]featureflags.Parameter
+ updatePath string
+ deletePath string
+ updateErr error
+ deleteErr error
+}
+
+func newFeatureFlagStore(parameters ...featureflags.Parameter) *featureFlagStore {
+ store := &featureFlagStore{parameters: map[string]featureflags.Parameter{}}
+ for _, parameter := range parameters {
+ store.parameters[parameter.Name] = parameter
+ }
+ return store
+}
+func (s *featureFlagStore) List(_ context.Context, prefix string) ([]featureflags.Parameter, error) {
+ var result []featureflags.Parameter
+ for name, parameter := range s.parameters {
+ if len(name) >= len(prefix) && name[:len(prefix)] == prefix {
+ result = append(result, parameter)
+ }
+ }
+ return result, nil
+}
+func (s *featureFlagStore) Get(_ context.Context, path string) (featureflags.Parameter, error) {
+ parameter, ok := s.parameters[path]
+ if !ok {
+ return featureflags.Parameter{}, featureflags.ErrParameterNotFound
+ }
+ return parameter, nil
+}
+func (s *featureFlagStore) Create(_ context.Context, parameter featureflags.Parameter) (featureflags.Parameter, error) {
+ if _, ok := s.parameters[parameter.Name]; ok {
+ return featureflags.Parameter{}, featureflags.ErrParameterExists
+ }
+ parameter.Version = 1
+ parameter.LastModified = time.Now().UTC()
+ s.parameters[parameter.Name] = parameter
+ return parameter, nil
+}
+func (s *featureFlagStore) Update(_ context.Context, path, value string) (featureflags.Parameter, error) {
+ updateErr := s.updateErr
+ if updateErr != nil {
+ return featureflags.Parameter{}, errors.Join(updateErr)
+ }
+ parameter, ok := s.parameters[path]
+ if !ok {
+ return featureflags.Parameter{}, featureflags.ErrParameterNotFound
+ }
+ s.updatePath = path
+ parameter.Value = value
+ parameter.Version++
+ s.parameters[path] = parameter
+ return parameter, nil
+}
+func (s *featureFlagStore) Delete(_ context.Context, path string) error {
+ deleteErr := s.deleteErr
+ if deleteErr != nil {
+ return errors.Join(deleteErr)
+ }
+ if _, ok := s.parameters[path]; !ok {
+ return featureflags.ErrParameterNotFound
+ }
+ s.deletePath = path
+ delete(s.parameters, path)
+ return nil
+}
+
+func TestFeatureFlagHandlersMapSecureStringMutationErrors(t *testing.T) {
+ parameter := featureflags.Parameter{Name: featureflagadmin.Prefix + "enabled", Value: "true", Type: "String", Version: 1, Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}}
+ for _, testCase := range []struct {
+ name string
+ method string
+ body string
+ invoke func(Handlers, http.ResponseWriter, *http.Request)
+ store *featureFlagStore
+ }{
+ {name: "update", method: http.MethodPut, body: `{"value_type":"string","value":"replacement","expected_version":1}`, store: &featureFlagStore{parameters: map[string]featureflags.Parameter{parameter.Name: parameter}, updateErr: featureflags.ErrSecureString}, invoke: func(h Handlers, w http.ResponseWriter, r *http.Request) { h.UpdateFeatureFlag(w, r) }},
+ {name: "delete", method: http.MethodDelete, body: `{"expected_version":1}`, store: &featureFlagStore{parameters: map[string]featureflags.Parameter{parameter.Name: parameter}, deleteErr: featureflags.ErrSecureString}, invoke: func(h Handlers, w http.ResponseWriter, r *http.Request) { h.DeleteFeatureFlag(w, r) }},
+ } {
+ t.Run(testCase.name, func(t *testing.T) {
+ h := featureFlagHandlers(t, testCase.store)
+ request := featureFlagRequest(testCase.method, "/api/admin/feature-flags/enabled", testCase.body, adminUser())
+ request.SetPathValue("key", "enabled")
+ response := httptest.NewRecorder()
+ testCase.invoke(h, response, request)
+ if response.Code != http.StatusUnprocessableEntity {
+ t.Fatalf("status = %d, want 422; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "unsupported_parameter" {
+ t.Fatalf("code = %q, want unsupported_parameter", apiError.Code)
+ }
+ })
+ }
+}
+
+type featureFlagLock struct{}
+
+func (featureFlagLock) WithLock(ctx context.Context, callback func(context.Context) error) error {
+ return callback(ctx)
+}
+
+func featureFlagHandlers(t *testing.T, store *featureFlagStore) Handlers {
+ t.Helper()
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-1"]`)
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup provider: %v", err)
+ }
+ auth.LoadOpa()
+ return Handlers{FeatureFlags: featureflagadmin.NewService(store, featureFlagLock{}, nil, nil)}
+}
+func featureFlagRequest(method, path, body string, user *auth.User) *http.Request {
+ request := httptest.NewRequest(method, path, bytes.NewBufferString(body))
+ return withUser(request, user)
+}
+func adminUser() *auth.User {
+ return &auth.User{ID: "admin-1", Email: "[email protected]", AZP: "cyclops-cs-spa", PrincipalType: auth.PrincipalTypeUser}
+}
+
+func TestListFeatureFlagsRejectsNonAdmin(t *testing.T) {
+ h := featureFlagHandlers(t, newFeatureFlagStore())
+ response := httptest.NewRecorder()
+ h.ListFeatureFlags(response, featureFlagRequest(http.MethodGet, "/api/admin/feature-flags", "", &auth.User{ID: "user-1", AZP: "cyclops-cs-spa"}))
+ if response.Code != http.StatusForbidden {
+ t.Fatalf("status = %d, want 403; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.Unmarshal(response.Body.Bytes(), &apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "not_admin" || apiError.Message != "feature flag administration requires an admin user" {
+ t.Fatalf("error = %#v", apiError)
+ }
+}
+
+func TestFeatureFlagHandlerAdminEvaluationFailureIsStableAndAudited(t *testing.T) {
+ var logs bytes.Buffer
+ previousLogger := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previousLogger) })
+ previousEval := evalFeatureFlagAdmin
+ evalFeatureFlagAdmin = func(context.Context, *auth.User) (bool, error) { return false, errors.New("opa unavailable") }
+ t.Cleanup(func() { evalFeatureFlagAdmin = previousEval })
+
+ h := featureFlagHandlers(t, newFeatureFlagStore())
+ response := httptest.NewRecorder()
+ request := featureFlagRequest(http.MethodPost, "/api/admin/feature-flags", `{"key":"enabled","value_type":"boolean","value":true}`, adminUser())
+ h.CreateFeatureFlag(response, request)
+ if response.Code != http.StatusInternalServerError {
+ t.Fatalf("status = %d, want 500; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.Unmarshal(response.Body.Bytes(), &apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "policy_error" || apiError.Message == "" {
+ t.Fatalf("error = %#v", apiError)
+ }
+ if count := strings.Count(logs.String(), `"event":"feature_flag_admin"`); count != 1 || !strings.Contains(logs.String(), `"reason":"policy_error"`) {
+ t.Fatalf("audit logs = %s", logs.String())
+ }
+}
+
+func TestUpdateFeatureFlagDefenseInDepthDenialAuditsExactlyOnce(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ h := featureFlagHandlers(t, newFeatureFlagStore())
+ response := httptest.NewRecorder()
+ invalidKey := strings.Repeat("Sensitive/", 40)
+ requestPath := "/api/admin/feature-flags/" + invalidKey
+ request := featureFlagRequest(http.MethodPut, requestPath, `{"value_type":"boolean","value":true,"expected_version":1}`, &auth.User{
+ ID: "user-1", Email: "[email protected]", AZP: "cyclops-cs-spa", PrincipalType: auth.PrincipalTypeUser,
+ })
+ request.SetPathValue("key", invalidKey)
+ request = request.WithContext(context.WithValue(request.Context(), middlewares.ContextKey("traceId"), "trace-123"))
+ h.UpdateFeatureFlag(response, request)
+
+ if response.Code != http.StatusForbidden {
+ t.Fatalf("status = %d, want 403; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.Unmarshal(response.Body.Bytes(), &apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "not_admin" {
+ t.Fatalf("error = %#v", apiError)
+ }
+
+ events := make([]map[string]any, 0, 1)
+ decoder := json.NewDecoder(bytes.NewReader(logs.Bytes()))
+ for {
+ var record map[string]any
+ if err := decoder.Decode(&record); err == io.EOF {
+ break
+ } else if err != nil {
+ t.Fatalf("decode logs: %v; logs=%s", err, logs.String())
+ }
+ if record["event"] == "feature_flag_admin" {
+ events = append(events, record)
+ }
+ }
+ if len(events) != 1 {
+ t.Fatalf("feature flag audit events = %d, want 1; logs=%s", len(events), logs.String())
+ }
+ for key, want := range map[string]any{
+ "actor": "user-1", "actor_email": "[email protected]", "principal_type": "user",
+ "operation": "put", "traceId": "trace-123", "result": "rejected", "reason": "not_admin",
+ } {
+ if got := events[0][key]; got != want {
+ t.Errorf("%s = %#v, want %#v", key, got, want)
+ }
+ }
+ for _, field := range []string{"key", "path"} {
+ value, _ := events[0][field].(string)
+ if !strings.HasPrefix(value, "sha256:") || len(value) > 80 {
+ t.Errorf("%s = %q, want bounded SHA-256 identifier", field, value)
+ }
+ }
+ if strings.Contains(logs.String(), invalidKey) {
+ t.Fatalf("audit leaked unvalidated key/path: %s", logs.String())
+ }
+}
+
+func TestCreateFeatureFlagReturns201(t *testing.T) {
+ store := newFeatureFlagStore()
+ h := featureFlagHandlers(t, store)
+ response := httptest.NewRecorder()
+ h.CreateFeatureFlag(response, featureFlagRequest(http.MethodPost, "/api/admin/feature-flags", `{"key":"enabled","value_type":"boolean","value":true}`, adminUser()))
+ if response.Code != http.StatusCreated {
+ t.Fatalf("status = %d, want 201; body = %s", response.Code, response.Body.String())
+ }
+ if _, ok := store.parameters[featureflagadmin.Prefix+"enabled"]; !ok {
+ t.Fatal("flag was not created")
+ }
+}
+
+func TestUpdateFeatureFlagReturnsCurrentOnVersionConflict(t *testing.T) {
+ current := featureflags.Parameter{Name: featureflagadmin.Prefix + "enabled", Value: "true", Type: "String", Version: 3, LastModified: time.Now().UTC(), Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}}
+ h := featureFlagHandlers(t, newFeatureFlagStore(current))
+ response := httptest.NewRecorder()
+ request := featureFlagRequest(http.MethodPut, "/api/admin/feature-flags/enabled", `{"value_type":"boolean","value":false,"expected_version":2}`, adminUser())
+ request.SetPathValue("key", "enabled")
+ h.UpdateFeatureFlag(response, request)
+ if response.Code != http.StatusConflict {
+ t.Fatalf("status = %d, want 409; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "version_conflict" || apiError.Current == nil || apiError.Current.Version != 3 {
+ t.Fatalf("error = %#v", apiError)
+ }
+}
+
+func TestDeleteFeatureFlagAcceptsExpectedVersionBody(t *testing.T) {
+ parameter := featureflags.Parameter{Name: featureflagadmin.Prefix + "enabled", Value: "true", Type: "String", Version: 3, LastModified: time.Now().UTC(), Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}}
+ store := newFeatureFlagStore(parameter)
+ h := featureFlagHandlers(t, store)
+ response := httptest.NewRecorder()
+ request := featureFlagRequest(http.MethodDelete, "/api/admin/feature-flags/enabled", `{"expected_version":3}`, adminUser())
+ request.SetPathValue("key", "enabled")
+ h.DeleteFeatureFlag(response, request)
+ if response.Code != http.StatusNoContent {
+ t.Fatalf("status = %d, want 204; body = %s", response.Code, response.Body.String())
+ }
+ if store.deletePath != featureflagadmin.Prefix+"enabled" {
+ t.Fatalf("delete path = %q", store.deletePath)
+ }
+}
+
+func TestDeleteFeatureFlagRejectsAdminSubsWithLastAdmin(t *testing.T) {
+ parameter := featureflags.Parameter{Name: featureflagadmin.Prefix + "admin-subs", Value: `["admin-1"]`, Type: "String", Version: 3, LastModified: time.Now().UTC(), Tags: map[string]string{"ManagedBy": "cyclops-cs-admin"}}
+ store := newFeatureFlagStore(parameter)
+ h := featureFlagHandlers(t, store)
+ response := httptest.NewRecorder()
+ request := featureFlagRequest(http.MethodDelete, "/api/admin/feature-flags/admin-subs", `{"expected_version":3}`, adminUser())
+ request.SetPathValue("key", "admin-subs")
+ h.DeleteFeatureFlag(response, request)
+ if response.Code != http.StatusUnprocessableEntity {
+ t.Fatalf("status = %d, want 422; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "last_admin" {
+ t.Fatalf("code = %q, want last_admin", apiError.Code)
+ }
+ if store.deletePath != "" {
+ t.Fatalf("delete path = %q, want no deletion", store.deletePath)
+ }
+}
+
+func TestFeatureFlagHandlersReturnStableErrors(t *testing.T) {
+ h := featureFlagHandlers(t, newFeatureFlagStore())
+ response := httptest.NewRecorder()
+ h.CreateFeatureFlag(response, featureFlagRequest(http.MethodPost, "/api/admin/feature-flags", `{"key":"Bad_Key","value_type":"boolean","value":true}`, adminUser()))
+ if response.Code != http.StatusBadRequest {
+ t.Fatalf("status = %d, want 400", response.Code)
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "invalid_key" || apiError.Message == "" {
+ t.Fatalf("error = %#v", apiError)
+ }
+}
+
+func TestFeatureFlagHandlersReturnUnsupportedProvider(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-1"]`)
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup provider: %v", err)
+ }
+ auth.LoadOpa()
+ response := httptest.NewRecorder()
+ Handlers{FeatureFlags: featureflagadmin.NewUnsupportedService(nil)}.ListFeatureFlags(response, featureFlagRequest(http.MethodGet, "/api/admin/feature-flags", "", adminUser()))
+ if response.Code != http.StatusNotImplemented {
+ t.Fatalf("status = %d, want 501; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "unsupported_provider" {
+ t.Fatalf("code = %q", apiError.Code)
+ }
+}
+
+func TestFeatureFlagHandlersAuditStrictJSONRejectionsWithoutRawBodies(t *testing.T) {
+ validCreate := `{"key":"enabled","value_type":"boolean","value":true}`
+ cases := []struct {
+ name string
+ method string
+ path string
+ key string
+ body string
+ parseFailure string
+ invoke func(Handlers, http.ResponseWriter, *http.Request)
+ }{
+ {name: "malformed create", method: http.MethodPost, path: "/api/admin/feature-flags", body: `{"key":"secret-body-value"`, parseFailure: "malformed_json", invoke: func(h Handlers, w http.ResponseWriter, r *http.Request) { h.CreateFeatureFlag(w, r) }},
+ {name: "oversized create", method: http.MethodPost, path: "/api/admin/feature-flags", body: validCreate + strings.Repeat("X", maxFeatureFlagRequestBytes-len(validCreate)+1), parseFailure: "body_too_large", invoke: func(h Handlers, w http.ResponseWriter, r *http.Request) { h.CreateFeatureFlag(w, r) }},
+ {name: "unknown update field", method: http.MethodPut, path: "/api/admin/feature-flags/enabled", key: "enabled", body: `{"value_type":"boolean","value":true,"expected_version":1,"unexpected":"secret-body-value"}`, parseFailure: "unknown_field", invoke: func(h Handlers, w http.ResponseWriter, r *http.Request) { h.UpdateFeatureFlag(w, r) }},
+ {name: "trailing delete data", method: http.MethodDelete, path: "/api/admin/feature-flags/enabled", key: "enabled", body: `{"expected_version":1} {"secret":"secret-body-value"}`, parseFailure: "trailing_data", invoke: func(h Handlers, w http.ResponseWriter, r *http.Request) { h.DeleteFeatureFlag(w, r) }},
+ }
+ for _, testCase := range cases {
+ t.Run(testCase.name, func(t *testing.T) {
+ var logs bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ h := featureFlagHandlers(t, newFeatureFlagStore())
+ response := httptest.NewRecorder()
+ request := featureFlagRequest(testCase.method, testCase.path, testCase.body, adminUser())
+ request.SetPathValue("key", testCase.key)
+ request = request.WithContext(context.WithValue(request.Context(), middlewares.ContextKey("traceId"), "trace-123"))
+ testCase.invoke(h, response, request)
+ if response.Code != http.StatusBadRequest {
+ t.Fatalf("status = %d, want 400; body = %s", response.Code, response.Body.String())
+ }
+ var record map[string]any
+ decoder := json.NewDecoder(bytes.NewReader(logs.Bytes()))
+ for {
+ var candidate map[string]any
+ if err := decoder.Decode(&candidate); err == io.EOF {
+ break
+ } else if err != nil {
+ t.Fatalf("unmarshal audit log: %v; logs=%s", err, logs.String())
+ }
+ if candidate["event"] == "feature_flag_admin" {
+ record = candidate
+ }
+ }
+ if record == nil {
+ t.Fatalf("feature flag audit missing: %s", logs.String())
+ }
+ for key, want := range map[string]any{
+ "event": "feature_flag_admin", "actor": "admin-1", "actor_email": "[email protected]",
+ "principal_type": "user", "operation": strings.ToLower(testCase.method), "key": testCase.key,
+ "path": testCase.path, "traceId": "trace-123", "result": "rejected", "reason": "invalid_request",
+ "parse_failure": testCase.parseFailure,
+ } {
+ if got := record[key]; got != want {
+ t.Errorf("%s = %#v, want %#v; logs=%s", key, got, want, logs.String())
+ }
+ }
+ if strings.Contains(logs.String(), "secret-body-value") || strings.Contains(logs.String(), strings.Repeat("X", 128)) {
+ t.Fatalf("audit leaked raw request body: %s", logs.String())
+ }
+ })
+ }
+}
+
+func TestFeatureFlagHandlerReturnsLeaseNotFound(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-1"]`)
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup provider: %v", err)
+ }
+ auth.LoadOpa()
+ service := featureflagadmin.NewService(newFeatureFlagStore(), errorLock{err: featureflagadmin.ErrLeaseNotFound}, nil, nil)
+ response := httptest.NewRecorder()
+ Handlers{FeatureFlags: service}.CreateFeatureFlag(response, featureFlagRequest(http.MethodPost, "/api/admin/feature-flags", `{"key":"enabled","value_type":"boolean","value":true}`, adminUser()))
+ if response.Code != http.StatusServiceUnavailable {
+ t.Fatalf("status = %d, want 503; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "lease_not_found" {
+ t.Fatalf("code = %q", apiError.Code)
+ }
+}
+
+type errorLock struct{ err error }
+
+func (l errorLock) WithLock(context.Context, func(context.Context) error) error { return l.err }
+
+func TestFeatureFlagHandlerNilStoreReturnsUnsupportedProvider(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", `["admin-1"]`)
+ if err := featureflags.SetupProvider(context.Background(), "development", featureflags.AWSCredentials{}); err != nil {
+ t.Fatalf("setup provider: %v", err)
+ }
+ auth.LoadOpa()
+ response := httptest.NewRecorder()
+ Handlers{FeatureFlags: featureflagadmin.NewService(nil, featureFlagLock{}, nil, nil)}.ListFeatureFlags(response, featureFlagRequest(http.MethodGet, "/api/admin/feature-flags", "", adminUser()))
+ if response.Code != http.StatusNotImplemented {
+ t.Fatalf("status = %d, want 501; body = %s", response.Code, response.Body.String())
+ }
+ var apiError AdminAPIError
+ if err := json.NewDecoder(response.Body).Decode(&apiError); err != nil {
+ t.Fatal(err)
+ }
+ if apiError.Code != "unsupported_provider" {
+ t.Fatalf("code = %q", apiError.Code)
+ }
+}
diff --git a/libs/fleet/backend/handlers/handlers.go b/libs/fleet/backend/handlers/handlers.go
index 2d7ddfe5aa..febff76b5a 100644
--- a/libs/fleet/backend/handlers/handlers.go
+++ b/libs/fleet/backend/handlers/handlers.go
@@ -15,6 +15,7 @@ import (
"cyclops-cs-backend/auth"
"cyclops-cs-backend/chat"
"cyclops-cs-backend/config"
+ "cyclops-cs-backend/featureflagadmin"
"cyclops-cs-backend/keycloak"
"cyclops-cs-backend/usage"
"go.opentelemetry.io/otel"
@@ -44,6 +45,8 @@ type Handlers struct {
usageAccessEvaluator func(context.Context, *auth.User) (bool, error)
adminAccessEvaluator func(context.Context, *auth.User) (bool, error)
+ FeatureFlags *featureflagadmin.Service
+
ChatAccess config.ChatAccessMode
Conversations chat.ConversationStore
Model chat.ModelClient
@@ -85,7 +88,7 @@ func (h Handlers) usageEnabled(ctx context.Context, user *auth.User) (bool, erro
func (h Handlers) isAdmin(ctx context.Context, user *auth.User) (bool, error) {
evaluator := h.adminAccessEvaluator
if evaluator == nil {
- evaluator = auth.EvalIsAdmin
+ evaluator = auth.EvalIsAdminFresh
}
return evaluator(ctx, user)
}
diff --git a/libs/fleet/backend/main.go b/libs/fleet/backend/main.go
index 32c7bd81f5..b6cb16624d 100644
--- a/libs/fleet/backend/main.go
+++ b/libs/fleet/backend/main.go
@@ -36,6 +36,7 @@ import (
"cyclops-cs-backend/config"
"cyclops-cs-backend/database"
_ "cyclops-cs-backend/docs" // generated by `swag init`
+ "cyclops-cs-backend/featureflagadmin"
"cyclops-cs-backend/githubtrust"
"cyclops-cs-backend/handlers"
"cyclops-cs-backend/keycloak"
@@ -151,6 +152,10 @@ func setupRouter(c handlers.Handlers) http.Handler {
withAuthenticatedMiddlewares("/api/state/query", c.QueryState))
r.Handle("GET /api/usage/overview", withAuthenticatedMiddlewares("/api/usage/overview", c.GetUsageOverview))
r.Handle("GET /api/usage/pool", withAuthenticatedMiddlewares("/api/usage/pool", c.GetUsagePoolDetail))
+ r.Handle("GET /api/admin/feature-flags", withAuthenticatedMiddlewares("/api/admin/feature-flags", c.ListFeatureFlags))
+ r.Handle("POST /api/admin/feature-flags", withAuthenticatedMiddlewares("/api/admin/feature-flags", c.CreateFeatureFlag))
+ r.Handle("PUT /api/admin/feature-flags/{key}", withAuthenticatedMiddlewares("/api/admin/feature-flags/{key}", c.UpdateFeatureFlag))
+ r.Handle("DELETE /api/admin/feature-flags/{key}", withAuthenticatedMiddlewares("/api/admin/feature-flags/{key}", c.DeleteFeatureFlag))
// Stripe-hosted billing. Browser routes require the normal SPA JWT; the
// webhook uses Stripe signature verification as its authentication boundary.
@@ -348,6 +353,19 @@ func run() error {
} else {
slog.Info("usage: enabled")
}
+ managementStore, processLocalManagement, managementStoreErr := featureFlagManagementStoreFromEnv(os.Getenv)
+ if managementStoreErr != nil {
+ startupErrors = errors.Join(startupErrors, managementStoreErr)
+ slog.Warn("feature flag management: unavailable", "err", managementStoreErr)
+ h.FeatureFlags = newUnsupportedFeatureFlagAdminService()
+ } else if processLocalManagement {
+ slog.Warn("feature flag management: ephemeral process-local store enabled")
+ h.FeatureFlags = newFeatureFlagAdminService(managementStore, &processLocalMutationLock{})
+ } else {
+ leaseConfig := featureFlagLeaseConfigFromEnv(os.Getenv)
+ lease := featureflagadmin.NewKubernetesLeaseLock(leaseConfig.apiBaseURL, leaseConfig.namespace, leaseConfig.name, leaseConfig.holderIdentity, 30*time.Second, 5*time.Second, time.Now)
+ h.FeatureFlags = newFeatureFlagAdminService(managementStore, lease)
+ }
if cfg.Stripe.SecretKey != "" {
h.Billing = billing.NewService(billing.NewStripeGateway(cfg.Stripe.SecretKey))
slog.Info("stripe billing: hosted flows enabled")
@@ -382,6 +400,40 @@ func run() error {
return errors.Join(startupErrors, telemetryErr)
}
+func newFeatureFlagAdminService(store featureflags.ManagementStore, lock featureflagadmin.MutationLock) *featureflagadmin.Service {
+ return featureflagadmin.NewService(store, lock, cacheInvalidator{}, featureflagadmin.NewSlogAuditLogger(nil))
+}
+
+func newUnsupportedFeatureFlagAdminService() *featureflagadmin.Service {
+ return featureflagadmin.NewUnsupportedService(featureflagadmin.NewSlogAuditLogger(nil))
+}
+
+type cacheInvalidator struct{}
+
+func (cacheInvalidator) InvalidateFeatureFlags() { auth.InvalidateFeatureFlags() }
+
+type featureFlagLeaseConfig struct {
+ apiBaseURL string
+ namespace string
+ name string
+ holderIdentity string
+}
+
+func featureFlagLeaseConfigFromEnv(getenv func(string) string) featureFlagLeaseConfig {
+ valueOrDefault := func(key, fallback string) string {
+ if value := getenv(key); value != "" {
+ return value
+ }
+ return fallback
+ }
+ return featureFlagLeaseConfig{
+ apiBaseURL: valueOrDefault("KUBERNETES_PROXY_URL", "http://127.0.0.1:8001"),
+ namespace: valueOrDefault("FEATURE_FLAG_LEASE_NAMESPACE", "cyclops-cs"),
+ name: valueOrDefault("FEATURE_FLAG_LEASE_NAME", "cyclops-feature-flags-writer"),
+ holderIdentity: getenv("HOSTNAME"),
+ }
+}
+
const (
databaseStartupTimeout = 5 * time.Second
// How often a degraded pod re-attempts its database dependencies.
diff --git a/libs/fleet/backend/main_feature_flag_management_test.go b/libs/fleet/backend/main_feature_flag_management_test.go
new file mode 100644
index 0000000000..93e348a25f
--- /dev/null
+++ b/libs/fleet/backend/main_feature_flag_management_test.go
@@ -0,0 +1,132 @@
+package main
+
+import (
+ "context"
+ "errors"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "testing"
+ "time"
+)
+
+func TestFeatureFlagManagementStoreFromEnvUsesExplicitEphemeralMode(t *testing.T) {
+ t.Setenv("CYCLOPS_CS_ADMIN_SUBS", "original")
+ values := map[string]string{
+ "FEATURE_FLAG_MANAGEMENT_MODE": "ephemeral",
+ "FEATURE_FLAG_MANAGEMENT_SEED": `[{"name":"/feature-flags/cyclops-cs/admin-subs","value":"[\"preview-admin\"]","tags":{"ManagedBy":"terraform"}}]`,
+ }
+
+ store, processLocal, err := featureFlagManagementStoreFromEnv(func(key string) string { return values[key] })
+ if err != nil {
+ t.Fatalf("featureFlagManagementStoreFromEnv() error = %v", err)
+ }
+ if !processLocal {
+ t.Fatal("featureFlagManagementStoreFromEnv() processLocal = false, want true")
+ }
+ parameter, err := store.Get(context.Background(), "/feature-flags/cyclops-cs/admin-subs")
+ if err != nil {
+ t.Fatalf("Get() error = %v", err)
+ }
+ if parameter.Value != `["preview-admin"]` || parameter.Tags["ManagedBy"] != "terraform" {
+ t.Fatalf("Get() = %#v", parameter)
+ }
+}
+
+func TestFeatureFlagManagementStoreFromEnvRejectsUnknownMode(t *testing.T) {
+ _, _, err := featureFlagManagementStoreFromEnv(func(key string) string {
+ if key == "FEATURE_FLAG_MANAGEMENT_MODE" {
+ return "production-ish"
+ }
+ return ""
+ })
+ if err == nil || !strings.Contains(err.Error(), "production-ish") {
+ t.Fatalf("featureFlagManagementStoreFromEnv() error = %v", err)
+ }
+}
+
+func TestProcessLocalMutationLockRunsCallback(t *testing.T) {
+ called := false
+ if err := (&processLocalMutationLock{}).WithLock(context.Background(), func(context.Context) error {
+ called = true
+ return nil
+ }); err != nil {
+ t.Fatalf("WithLock() error = %v", err)
+ }
+ if !called {
+ t.Fatal("WithLock() did not run callback")
+ }
+}
+
+func TestProcessLocalMutationLockSerializesCallbacks(t *testing.T) {
+ lock := &processLocalMutationLock{}
+ var active atomic.Int32
+ var maximum atomic.Int32
+ var wait sync.WaitGroup
+
+ for range 8 {
+ wait.Add(1)
+ go func() {
+ defer wait.Done()
+ if err := lock.WithLock(context.Background(), func(context.Context) error {
+ current := active.Add(1)
+ if current > maximum.Load() {
+ maximum.Store(current)
+ }
+ time.Sleep(time.Millisecond)
+ active.Add(-1)
+ return nil
+ }); err != nil {
+ t.Errorf("WithLock() error = %v", err)
+ }
+ }()
+ }
+ wait.Wait()
+ if maximum.Load() != 1 {
+ t.Fatalf("maximum concurrent callbacks = %d, want 1", maximum.Load())
+ }
+}
+
+func TestProcessLocalMutationLockHonorsCancellationWhileQueued(t *testing.T) {
+ lock := &processLocalMutationLock{}
+ entered := make(chan struct{})
+ release := make(chan struct{})
+ firstDone := make(chan error, 1)
+ go func() {
+ firstDone <- lock.WithLock(context.Background(), func(context.Context) error {
+ close(entered)
+ <-release
+ return nil
+ })
+ }()
+ <-entered
+
+ ctx, cancel := context.WithCancel(context.Background())
+ called := false
+ secondDone := make(chan error, 1)
+ go func() {
+ secondDone <- lock.WithLock(ctx, func(context.Context) error {
+ called = true
+ return nil
+ })
+ }()
+ time.Sleep(10 * time.Millisecond)
+ cancel()
+
+ select {
+ case err := <-secondDone:
+ if !errors.Is(err, context.Canceled) {
+ t.Fatalf("WithLock() error = %v, want context.Canceled", err)
+ }
+ case <-time.After(100 * time.Millisecond):
+ close(release)
+ t.Fatal("WithLock() did not return after context cancellation")
+ }
+ if called {
+ t.Fatal("WithLock() ran callback after context cancellation")
+ }
+ close(release)
+ if err := <-firstDone; err != nil {
+ t.Fatalf("first WithLock() error = %v", err)
+ }
+}
diff --git a/libs/fleet/backend/main_lease_config_test.go b/libs/fleet/backend/main_lease_config_test.go
new file mode 100644
index 0000000000..0e498f0a65
--- /dev/null
+++ b/libs/fleet/backend/main_lease_config_test.go
@@ -0,0 +1,17 @@
+package main
+
+import "testing"
+
+func TestFeatureFlagLeaseConfigDefaults(t *testing.T) {
+ config := featureFlagLeaseConfigFromEnv(func(string) string { return "" })
+ if config.apiBaseURL != "http://127.0.0.1:8001" || config.namespace != "cyclops-cs" || config.name != "cyclops-feature-flags-writer" {
+ t.Fatalf("defaults = %#v", config)
+ }
+}
+func TestFeatureFlagLeaseConfigUsesEnvironment(t *testing.T) {
+ values := map[string]string{"KUBERNETES_PROXY_URL": "http://proxy:9000", "FEATURE_FLAG_LEASE_NAMESPACE": "flags", "FEATURE_FLAG_LEASE_NAME": "writer", "HOSTNAME": "pod-1"}
+ config := featureFlagLeaseConfigFromEnv(func(key string) string { return values[key] })
+ if config.apiBaseURL != "http://proxy:9000" || config.namespace != "flags" || config.name != "writer" || config.holderIdentity != "pod-1" {
+ t.Fatalf("config = %#v", config)
+ }
+}
diff --git a/libs/fleet/backend/main_test.go b/libs/fleet/backend/main_test.go
index 9052ce2b35..a12a4a2e5a 100644
--- a/libs/fleet/backend/main_test.go
+++ b/libs/fleet/backend/main_test.go
@@ -26,6 +26,7 @@ import (
"cyclops-cs-backend/auth"
"cyclops-cs-backend/billing"
"cyclops-cs-backend/config"
+ "cyclops-cs-backend/featureflagadmin"
"cyclops-cs-backend/githubtrust"
"cyclops-cs-backend/handlers"
"cyclops-cs-backend/metrics"
@@ -39,6 +40,90 @@ import (
"github.com/trycua/cloud/pkg/featureflags"
)
+type auditWiringLock struct{}
+
+func (auditWiringLock) WithLock(ctx context.Context, callback func(context.Context) error) error {
+ return callback(ctx)
+}
+
+func TestFeatureFlagAdminServiceWiresMutationAuditLogger(t *testing.T) {
+ var output bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&output, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ service := newFeatureFlagAdminService(nil, auditWiringLock{})
+ _, err := service.Create(context.Background(), featureflagadmin.Actor{Subject: "admin-1"}, featureflagadmin.CreateInput{Key: "INVALID"})
+ if err == nil {
+ t.Fatal("Create() error = nil, want invalid key rejection")
+ }
+ if !strings.Contains(output.String(), `"event":"feature_flag_admin"`) || !strings.Contains(output.String(), `"reason":"invalid_key"`) {
+ t.Fatalf("production mutation audit missing: %s", output.String())
+ }
+}
+
+func TestUnsupportedFeatureFlagAdminServiceWiresMutationAuditLogger(t *testing.T) {
+ var output bytes.Buffer
+ previous := slog.Default()
+ slog.SetDefault(slog.New(slog.NewJSONHandler(&output, nil)))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ service := newUnsupportedFeatureFlagAdminService()
+ _, err := service.Create(context.Background(), featureflagadmin.Actor{Subject: "admin-1"}, featureflagadmin.CreateInput{
+ Key: "enabled", ValueType: featureflags.ValueBoolean, Value: true,
+ })
+ var serviceError *featureflagadmin.ServiceError
+ if !errors.As(err, &serviceError) || serviceError.HTTPStatus != http.StatusNotImplemented {
+ t.Fatalf("Create() error = %#v, want 501", err)
+ }
+ if !strings.Contains(output.String(), `"event":"feature_flag_admin"`) || !strings.Contains(output.String(), `"reason":"unsupported_provider"`) {
+ t.Fatalf("fallback mutation audit missing: %s", output.String())
+ }
+}
+
+func TestFeatureFlagAdminSwaggerDocumentsReachableResponses(t *testing.T) {
+ data, err := os.ReadFile("docs/swagger.json")
+ if err != nil {
+ t.Fatal(err)
+ }
+ type swaggerResponse struct {
+ Schema struct {
+ Ref string `json:"$ref"`
+ } `json:"schema"`
+ }
+ var document struct {
+ Paths map[string]map[string]struct {
+ Responses map[string]swaggerResponse `json:"responses"`
+ } `json:"paths"`
+ }
+ if err := json.Unmarshal(data, &document); err != nil {
+ t.Fatal(err)
+ }
+ wants := map[string]map[string][]string{
+ "/api/admin/feature-flags": {"get": {"200", "401", "403", "501", "502"}, "post": {"201", "400", "401", "403", "409", "422", "500", "501", "502", "503"}},
+ "/api/admin/feature-flags/{key}": {"put": {"200", "400", "401", "403", "404", "409", "422", "500", "501", "502", "503"}, "delete": {"204", "400", "401", "403", "404", "409", "422", "500", "501", "502", "503"}},
+ }
+ for path, methods := range wants {
+ for method, statuses := range methods {
+ operation := document.Paths[path][method]
+ for _, status := range statuses {
+ response, ok := operation.Responses[status]
+ if !ok {
+ t.Errorf("%s %s missing Swagger response %s", method, path, status)
+ continue
+ }
+ wantRef := "#/definitions/handlers.AdminAPIError"
+ if status == "401" {
+ wantRef = "#/definitions/handlers.ErrorResponse"
+ }
+ if status != "200" && status != "201" && status != "204" && response.Schema.Ref != wantRef {
+ t.Errorf("%s %s response %s schema = %q, want %q", method, path, status, response.Schema.Ref, wantRef)
+ }
+ }
+ }
+ }
+}
+
func TestGatewayRoutesAreRemoved(t *testing.T) {
router := setupRouter(handlers.Handlers{})
diff --git a/libs/fleet/e2e/feature-flags.spec.ts b/libs/fleet/e2e/feature-flags.spec.ts
new file mode 100644
index 0000000000..2ab18c0832
--- /dev/null
+++ b/libs/fleet/e2e/feature-flags.spec.ts
@@ -0,0 +1,742 @@
+import { expect, test } from "@playwright/test"
+import {
+ DEFAULT_ADMIN_FEATURE_FLAGS,
+ mockAdminFeatureFlagsApi,
+ mockAuth,
+ mockConfigApi,
+ mockNamespacesApi,
+ mockPoolsApi,
+ type MockAdminFeatureFlag,
+} from "./fixtures/mock-api"
+
+test.describe("feature flag admin route", () => {
+ test("redirects malformed deep links instead of rendering an empty shell", async ({ page }) => {
+ await mockAuth(page, { admin: true })
+ await mockNamespacesApi(page)
+ await mockPoolsApi(page)
+
+ await page.goto("/admin/feature-flags.")
+
+ await expect(page).toHaveURL(/\/pools$/)
+ await expect(page.getByRole("heading", { name: "Pools", level: 1 })).toBeVisible()
+ })
+
+ test("shows the admin navigation and page after admin config resolves", async ({
+ page,
+ }) => {
+ await mockAuth(page)
+ await mockNamespacesApi(page)
+ await mockPoolsApi(page)
+
+ let resolveConfig: ((value: void) => void) | undefined
+ const configReady = new Promise<void>(resolve => {
+ resolveConfig = resolve
+ })
+ await page.route("**/api/config", async route => {
+ await configReady
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: true, billing: false }),
+ })
+ })
+
+ await page.goto("/pools")
+ await expect(page.getByRole("link", { name: "Feature flags" })).toHaveCount(0)
+
+ resolveConfig?.()
+ await expect(page.getByRole("link", { name: "Feature flags" })).toBeVisible()
+ await expect(page.getByText("Admin", { exact: true })).toBeVisible()
+ await page.getByRole("link", { name: "Feature flags" }).click()
+ await expect(page).toHaveURL(/\/admin\/feature-flags$/)
+ await expect(page.getByRole("heading", { name: "Feature flags" })).toBeVisible()
+ await expect(page.getByText("Admin only · Feature flagged", { exact: true })).toBeVisible()
+ })
+
+ test("redirects non-admin direct navigation without requesting admin flags", async ({
+ page,
+ }) => {
+ await mockAuth(page)
+ await mockNamespacesApi(page)
+ await mockPoolsApi(page)
+
+ let resolveConfig: (() => void) | undefined
+ const configReady = new Promise<void>(resolve => {
+ resolveConfig = resolve
+ })
+ await page.route("**/api/config", async route => {
+ await configReady
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: false, billing: false }),
+ })
+ })
+
+ const adminRequests: string[] = []
+ await page.route("**/api/admin/feature-flags**", async route => {
+ adminRequests.push(route.request().url())
+ await route.abort("failed")
+ })
+
+ await page.goto("/admin/feature-flags")
+ await expect(page.getByRole("heading", { name: "Feature flags" })).toHaveCount(0)
+
+ resolveConfig?.()
+ await expect(page).toHaveURL(/\/pools$/)
+ await page.waitForTimeout(250)
+ await expect(page.getByRole("heading", { name: "Feature flags" })).toHaveCount(0)
+ expect(adminRequests).toEqual([])
+ })
+})
+
+async function openAdminFeatureFlags(page: import("@playwright/test").Page): Promise<void> {
+ await mockAuth(page)
+ await mockConfigApi(page, { admin: true })
+ await page.goto("/admin/feature-flags")
+ await expect(page.getByRole("heading", { name: "Feature flags" })).toBeVisible()
+}
+
+function featureFlagRow(page: import("@playwright/test").Page, key: string) {
+ return page.getByRole("row").filter({ has: page.getByText(key, { exact: true }) })
+}
+
+test.describe("feature flags CRUD", () => {
+ test("lists, filters, refreshes, and protects managed flags", async ({ page }) => {
+ const api = await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+
+ const terraformRow = featureFlagRow(page, "admin-subs")
+ await expect(terraformRow).toContainText('["test-user-id","other-admin"]')
+ await expect(terraformRow).toContainText("JSON")
+ await expect(terraformRow).toContainText("Terraform")
+ await expect(terraformRow).toContainText("7")
+ await expect(terraformRow).toContainText("Aug 12, 2026")
+ await expect(terraformRow.getByRole("link", { name: "Terraform" })).toHaveAttribute(
+ "href",
+ /github\.com\/trycua\/cloud\/tree\/main\/terraform\/aws\/feature-flags/,
+ )
+
+ const adHocRow = featureFlagRow(page, "new-checkout")
+ await expect(adHocRow).toContainText("true")
+ await expect(adHocRow).toContainText("Boolean")
+ await expect(adHocRow).toContainText("Ad hoc")
+ await expect(featureFlagRow(page, "legacy-threshold")).toContainText("External")
+
+ await page.getByPlaceholder("Find feature flags").fill("checkout")
+ await expect(adHocRow).toBeVisible()
+ await expect(featureFlagRow(page, "admin-subs")).toHaveCount(0)
+ await page.getByRole("button", { name: "Clear filter" }).click()
+
+ api.flags.push({
+ key: "refreshed-flag",
+ path: "/feature-flags/cyclops-cs/refreshed-flag",
+ value_type: "string",
+ value: "ready",
+ raw_value: "ready",
+ ownership: "ad_hoc",
+ managed_by: "cyclops-cs",
+ deletable: true,
+ version: 1,
+ modified_at: "2026-08-13T12:10:00Z",
+ tags: {},
+ })
+ await page.getByRole("button", { name: "Refresh feature flags" }).click()
+ await expect(featureFlagRow(page, "refreshed-flag")).toBeVisible()
+
+ await terraformRow.getByRole("button", { name: "Actions for admin-subs" }).click()
+ await expect(page.getByRole("menuitem", { name: "Delete" })).toHaveCount(0)
+ await page.keyboard.press("Escape")
+ await featureFlagRow(page, "legacy-threshold").getByRole("button", { name: "Actions for legacy-threshold" }).click()
+ await expect(page.getByRole("menuitem", { name: "Delete" })).toHaveCount(0)
+ })
+
+ test("never offers deletion for admin-subs even when ownership metadata is wrong", async ({ page }) => {
+ const unsafeAdminSubs: MockAdminFeatureFlag = {
+ ...DEFAULT_ADMIN_FEATURE_FLAGS[0],
+ ownership: "ad_hoc",
+ managed_by: "cyclops-cs-admin",
+ deletable: true,
+ }
+ await mockAdminFeatureFlagsApi(page, [unsafeAdminSubs])
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "admin-subs").getByRole("button", { name: "Actions for admin-subs" }).click()
+ await expect(page.getByRole("menuitem", { name: "Delete" })).toHaveCount(0)
+ })
+
+ test("renders row actions above the table overflow boundary", async ({ page }) => {
+ await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "new-checkout").getByRole("button", { name: "Actions for new-checkout" }).click()
+ const deleteAction = page.getByRole("menuitem", { name: "Delete" })
+ const deleteActionBox = await deleteAction.boundingBox()
+
+ expect(deleteActionBox).not.toBeNull()
+ const centerIsInteractive = await page.evaluate(({ x, y }) => {
+ return document.elementFromPoint(x, y)?.closest('[role="menuitem"]') !== null
+ }, {
+ x: deleteActionBox!.x + deleteActionBox!.width / 2,
+ y: deleteActionBox!.y + deleteActionBox!.height / 2,
+ })
+ expect(centerIsInteractive).toBe(true)
+ })
+
+ test("creates every typed value and validates malformed JSON", async ({ page }) => {
+ const api = await mockAdminFeatureFlagsApi(page, [])
+ await openAdminFeatureFlags(page)
+
+ const cases = [
+ { key: "bool-flag", type: "Boolean", apiType: "boolean", value: "true", expected: true },
+ { key: "number-flag", type: "Number", apiType: "number", value: "42.5", expected: 42.5 },
+ { key: "string-flag", type: "String", apiType: "string", value: "hello", expected: "hello" },
+ { key: "json-flag", type: "JSON", apiType: "json", value: '{"rollout":[1,2]}', expected: { rollout: [1, 2] } },
+ ] as const
+
+ for (const [index, testCase] of cases.entries()) {
+ await page.getByRole("button", { name: "Create feature flag" }).click()
+ const editor = page.getByRole("dialog", { name: "Create feature flag" })
+ await editor.getByRole("textbox", { name: "Key" }).fill(testCase.key)
+ if (index === 0) {
+ await editor.getByRole("textbox", { name: "Description (optional)" }).fill("Boolean rollout")
+ }
+ await editor.getByLabel("Value type").click()
+ await page.getByRole("option", { name: testCase.type, exact: true }).click()
+ if (testCase.type === "Boolean") {
+ await editor.getByRole("button", { name: /^Value Value / }).click()
+ await page.getByRole("option", { name: "True", exact: true }).click()
+ } else if (testCase.type === "JSON") {
+ await editor.getByRole("textbox", { name: "Value" }).fill("{")
+ await page.getByRole("button", { name: "Create", exact: true }).click()
+ await expect(editor.locator("span").filter({ hasText: /^Enter valid JSON$/ })).toBeVisible()
+ expect(api.requests.filter(request => request.method === "POST")).toHaveLength(index)
+ await editor.getByRole("textbox", { name: "Value" }).fill(testCase.value)
+ } else {
+ await editor.getByRole(testCase.type === "Number" ? "spinbutton" : "textbox", { name: "Value" }).fill(testCase.value)
+ }
+ await page.getByRole("button", { name: "Create", exact: true }).click()
+ await expect(page.getByText(`Created ${testCase.key}`)).toBeVisible()
+ await expect(featureFlagRow(page, testCase.key)).toBeVisible()
+ }
+
+ expect(api.requests.filter(request => request.method === "POST").map(request => request.body)).toEqual(
+ cases.map((testCase, index) => ({
+ key: testCase.key,
+ value_type: testCase.apiType,
+ value: testCase.expected,
+ ...(index === 0 ? { description: "Boolean rollout" } : {}),
+ })),
+ )
+ })
+
+ test("shows stored descriptions and keeps them create-only", async ({ page }) => {
+ await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "new-checkout").getByRole("button", { name: "Actions for new-checkout" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ const editor = page.getByRole("dialog", { name: "Edit new-checkout" })
+ await expect(editor.getByText("Enable the checkout experiment")).toBeVisible()
+ await expect(editor.getByRole("textbox", { name: "Description (optional)" })).toHaveCount(0)
+ })
+
+ test("refreshes access and redirects on middleware not_admin", async ({ page }) => {
+ let configRequests = 0
+ await mockAuth(page)
+ await page.route("**/api/config", route => {
+ configRequests += 1
+ return route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: configRequests === 1, billing: false }),
+ })
+ })
+ await mockNamespacesApi(page)
+ await mockPoolsApi(page)
+ await page.route("**/api/admin/feature-flags", route => route.fulfill({
+ status: 403,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "not_admin", message: "feature flag administration requires an admin user" }),
+ }))
+
+ await page.goto("/admin/feature-flags")
+ await expect(page).toHaveURL(/\/pools$/)
+ await expect(page.getByRole("link", { name: "Feature flags" })).toHaveCount(0)
+ expect(configRequests).toBeGreaterThanOrEqual(2)
+ })
+
+ test("handles stable middleware authorization errors", async ({ page }) => {
+ await mockAuth(page)
+ await mockConfigApi(page, { admin: true })
+ await page.route("**/api/admin/feature-flags", route => route.fulfill({
+ status: 502,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "authorization_unavailable", message: "authorization check unavailable" }),
+ }))
+ await page.goto("/admin/feature-flags")
+ await expect(page.getByText("authorization check unavailable")).toBeVisible()
+ })
+
+ test("edits type with an expected version and reloads after a conflict", async ({ page }) => {
+ const stale = { ...DEFAULT_ADMIN_FEATURE_FLAGS[1], version: 3 }
+ const current: MockAdminFeatureFlag = {
+ ...stale,
+ value: false,
+ raw_value: "false",
+ version: 4,
+ modified_at: "2026-08-13T11:00:00Z",
+ }
+ const putBodies: Record<string, unknown>[] = []
+ await mockAdminFeatureFlagsApi(page, [stale])
+ await page.route("**/api/admin/feature-flags/new-checkout", async route => {
+ if (route.request().method() !== "PUT") {
+ await route.fallback()
+ return
+ }
+ const body = route.request().postDataJSON() as Record<string, unknown>
+ putBodies.push(body)
+ if (putBodies.length === 1) {
+ await route.fulfill({
+ status: 409,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "version_conflict", message: "feature flag version is stale", current }),
+ })
+ return
+ }
+ await route.fallback()
+ })
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "new-checkout").getByRole("button", { name: "Actions for new-checkout" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ const editor = page.getByRole("dialog", { name: "Edit new-checkout" })
+ await editor.getByLabel("Value type").click()
+ await page.getByRole("option", { name: "Number", exact: true }).click()
+ await editor.getByRole("spinbutton", { name: "Value" }).fill("9")
+ await page.getByRole("button", { name: "Save changes" }).click()
+
+ await expect(page.getByText("This flag changed after you loaded it.")).toBeVisible()
+ await page.getByRole("button", { name: "Reload current value" }).click()
+ await expect(editor.getByLabel("Value type")).toContainText("Boolean")
+ await expect(editor.getByRole("button", { name: /^Value Value / })).toContainText("False")
+ await editor.getByRole("button", { name: /^Value Value / }).click()
+ await page.getByRole("option", { name: "True", exact: true }).click()
+ await page.getByRole("button", { name: "Save changes" }).click()
+ await expect(page.getByText("Updated new-checkout")).toBeVisible()
+
+ expect(putBodies).toEqual([
+ { value_type: "number", value: 9, expected_version: 3 },
+ { value_type: "boolean", value: true, expected_version: 4 },
+ ])
+ })
+
+ test("requires an exact key before deleting an ad hoc flag", async ({ page }) => {
+ const api = await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "new-checkout").getByRole("button", { name: "Actions for new-checkout" }).click()
+ await page.getByRole("menuitem", { name: "Delete" }).click()
+ const deleteDialog = page.getByRole("dialog", { name: "Delete new-checkout?" })
+ await expect(deleteDialog).toBeVisible()
+ await expect(
+ deleteDialog.getByText("Deleting this flag causes consumers to receive defaults after the feature flag cache refreshes."),
+ ).toBeVisible()
+ const confirm = page.getByLabel("Type new-checkout to confirm")
+ await confirm.fill("new-checkou")
+ await expect(page.getByRole("button", { name: "Delete feature flag" })).toBeDisabled()
+ await confirm.fill("new-checkout")
+ await page.getByRole("button", { name: "Delete feature flag" }).click()
+ await expect(featureFlagRow(page, "new-checkout")).toHaveCount(0)
+ expect(api.requests.find(request => request.method === "DELETE")?.body).toEqual({ expected_version: 3 })
+ })
+
+ test("confirms self-removal then refreshes access and redirects", async ({ page }) => {
+ let configRequests = 0
+ await mockAuth(page)
+ await page.route("**/api/config", route => {
+ configRequests += 1
+ return route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: configRequests === 1, billing: false }),
+ })
+ })
+ const api = await mockAdminFeatureFlagsApi(page, [DEFAULT_ADMIN_FEATURE_FLAGS[0]])
+ await mockNamespacesApi(page)
+ await mockPoolsApi(page)
+ await page.goto("/admin/feature-flags")
+
+ await featureFlagRow(page, "admin-subs").getByRole("button", { name: "Actions for admin-subs" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ await page.getByRole("dialog", { name: "Edit admin-subs" }).getByRole("textbox", { name: "Value" }).fill('["other-admin"]')
+ await page.getByRole("button", { name: "Save changes" }).click()
+ await expect(page.getByText("You are removing your own administrator access.")).toBeVisible()
+ await expect(page.getByRole("button", { name: "Confirm and save" })).toBeDisabled()
+ await page.getByLabel("I understand I will lose access").check()
+ await page.getByRole("button", { name: "Confirm and save" }).click()
+
+ await expect(page).toHaveURL(/\/pools$/)
+ await expect(page.getByRole("link", { name: "Feature flags" })).toHaveCount(0)
+ expect(api.requests.find(request => request.method === "PUT")?.body).toEqual({
+ value_type: "json",
+ value: ["other-admin"],
+ expected_version: 7,
+ })
+ expect(configRequests).toBe(2)
+ const updateIndex = api.requests.findIndex(request => request.method === "PUT")
+ expect(updateIndex).toBeGreaterThanOrEqual(0)
+ expect(api.requests.slice(updateIndex + 1).filter(request => request.method === "GET")).toHaveLength(0)
+ })
+ test("shows an initial list failure", async ({ page }) => {
+ await mockAuth(page)
+ await mockConfigApi(page, { admin: true })
+ await page.route("**/api/admin/feature-flags", route =>
+ route.fulfill({
+ status: 503,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "unavailable", message: "feature flags are unavailable" }),
+ }),
+ )
+
+ await page.goto("/admin/feature-flags")
+
+ await expect(page.getByText("feature flags are unavailable")).toBeVisible()
+ })
+
+ test("preserves existing rows when manual refresh fails", async ({ page }) => {
+ await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+ let listRequests = 0
+ await page.route("**/api/admin/feature-flags", async route => {
+ if (route.request().method() !== "GET") {
+ await route.fallback()
+ return
+ }
+ listRequests += 1
+ await route.fulfill({
+ status: 503,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "refresh_failed", message: "refresh failed" }),
+ })
+ })
+
+ await page.getByRole("button", { name: "Refresh feature flags" }).click()
+
+ await expect(page.getByText("refresh failed")).toBeVisible()
+ await expect(featureFlagRow(page, "new-checkout")).toBeVisible()
+ expect(listRequests).toBe(1)
+ })
+
+ test("rejects oversized keys and scalar JSON before calling the API", async ({ page }) => {
+ const api = await mockAdminFeatureFlagsApi(page, [])
+ await openAdminFeatureFlags(page)
+
+ await page.getByRole("button", { name: "Create feature flag" }).click()
+ let editor = page.getByRole("dialog", { name: "Create feature flag" })
+ await editor.getByRole("textbox", { name: "Key" }).fill("a".repeat(64))
+ await page.getByRole("button", { name: "Create", exact: true }).click()
+ await expect(editor.getByText("Feature flag keys can be at most 63 characters")).toBeVisible()
+ expect(api.requests.filter(request => request.method === "POST")).toHaveLength(0)
+
+ await editor.getByRole("button", { name: "Cancel" }).click()
+ await expect(editor).toBeHidden()
+ await page.getByLabel("Feature flags", { exact: true }).getByRole("button", { name: "Create feature flag" }).click()
+ editor = page.getByRole("dialog", { name: "Create feature flag" })
+ await editor.getByRole("textbox", { name: "Key" }).fill("json-scalar")
+ await editor.getByLabel("Value type").click()
+ await page.getByRole("option", { name: "JSON", exact: true }).click()
+ for (const scalar of ["null", "true", "42", '"text"']) {
+ await editor.getByRole("textbox", { name: "Value" }).fill(scalar)
+ await page.getByRole("button", { name: "Create", exact: true }).click()
+ await expect(editor.getByText("JSON values must be an object or array")).toBeVisible()
+ }
+ expect(api.requests.filter(request => request.method === "POST")).toHaveLength(0)
+ })
+
+ test("edits a Terraform-managed flag without exposing deletion", async ({ page }) => {
+ const api = await mockAdminFeatureFlagsApi(page, [DEFAULT_ADMIN_FEATURE_FLAGS[0]])
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "admin-subs").getByRole("button", { name: "Actions for admin-subs" }).click()
+ await expect(page.getByRole("menuitem", { name: "Delete" })).toHaveCount(0)
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ const editor = page.getByRole("dialog", { name: "Edit admin-subs" })
+ await expect(editor.getByText("The key is protected; only its typed value can be changed.")).toBeVisible()
+ await editor.getByRole("textbox", { name: "Value" }).fill('["test-user-id","other-admin","third-admin"]')
+ await page.getByRole("button", { name: "Save changes" }).click()
+
+ await expect(page.getByText("Updated admin-subs")).toBeVisible()
+ expect(api.requests.find(request => request.method === "PUT")?.body).toEqual({
+ value_type: "json",
+ value: ["test-user-id", "other-admin", "third-admin"],
+ expected_version: 7,
+ })
+ })
+
+ test("provides an accessible full-value view", async ({ page }) => {
+ await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "admin-subs").getByRole("button", { name: "View full value for admin-subs" }).click()
+
+ const details = page.getByRole("dialog", { name: "Value for admin-subs" })
+ await expect(details).toContainText('"test-user-id"')
+ await expect(details.getByRole("button", { name: "Copy full value" })).toBeVisible()
+ })
+
+ test("keeps delete failures local and recovers from stale versions", async ({ page }) => {
+ const current = { ...DEFAULT_ADMIN_FEATURE_FLAGS[1], version: 4, value: false, raw_value: "false" }
+ await mockAdminFeatureFlagsApi(page, [DEFAULT_ADMIN_FEATURE_FLAGS[1]])
+ let deleteRequests = 0
+ await page.route("**/api/admin/feature-flags/new-checkout", async route => {
+ if (route.request().method() !== "DELETE") {
+ await route.fallback()
+ return
+ }
+ deleteRequests += 1
+ if (deleteRequests === 1) {
+ await route.fulfill({
+ status: 409,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "version_conflict", message: "feature flag version is stale", current }),
+ })
+ return
+ }
+ if (deleteRequests === 2) {
+ await route.fulfill({
+ status: 503,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "delete_failed", message: "delete failed" }),
+ })
+ return
+ }
+ await route.fallback()
+ })
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "new-checkout").getByRole("button", { name: "Actions for new-checkout" }).click()
+ await page.getByRole("menuitem", { name: "Delete" }).click()
+ let dialog = page.getByRole("dialog", { name: "Delete new-checkout?" })
+ await dialog.getByLabel("Type new-checkout to confirm").fill("new-checkout")
+ await dialog.getByRole("button", { name: "Delete feature flag" }).click()
+ await expect(dialog.getByText("This flag changed after you loaded it.")).toBeVisible()
+ await dialog.getByRole("button", { name: "Reload current version" }).click()
+ await expect(dialog.getByText("Current version: 4")).toBeVisible()
+ await dialog.getByLabel("Type new-checkout to confirm").fill("new-checkout")
+ await dialog.getByRole("button", { name: "Delete feature flag" }).click()
+ await expect(dialog.getByText("delete failed")).toBeVisible()
+ await expect(featureFlagRow(page, "new-checkout")).toBeVisible()
+ })
+
+ test("keeps self-removal failures inside the confirmation modal", async ({ page }) => {
+ await mockAdminFeatureFlagsApi(page, [DEFAULT_ADMIN_FEATURE_FLAGS[0]])
+ await page.route("**/api/admin/feature-flags/admin-subs", async route => {
+ if (route.request().method() === "PUT") {
+ await route.fulfill({
+ status: 503,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "update_failed", message: "self-removal update failed" }),
+ })
+ return
+ }
+ await route.fallback()
+ })
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "admin-subs").getByRole("button", { name: "Actions for admin-subs" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ await page.getByRole("dialog", { name: "Edit admin-subs" }).getByRole("textbox", { name: "Value" }).fill('["other-admin"]')
+ await page.getByRole("button", { name: "Save changes" }).click()
+ const confirmation = page.getByRole("dialog", { name: "Confirm loss of administrator access" })
+ await confirmation.getByLabel("I understand I will lose access").check()
+ await confirmation.getByRole("button", { name: "Confirm and save" }).click()
+
+ await expect(confirmation.getByText("self-removal update failed")).toBeVisible()
+ await expect(confirmation).toBeVisible()
+ })
+
+ test("returns self-removal version conflicts to the editor", async ({ page }) => {
+ const current = {
+ ...DEFAULT_ADMIN_FEATURE_FLAGS[0],
+ value: ["test-user-id", "other-admin", "new-admin"],
+ raw_value: '["test-user-id","other-admin","new-admin"]',
+ version: 8,
+ }
+ await mockAdminFeatureFlagsApi(page, [DEFAULT_ADMIN_FEATURE_FLAGS[0]])
+ await page.route("**/api/admin/feature-flags/admin-subs", async route => {
+ if (route.request().method() === "PUT") {
+ await route.fulfill({
+ status: 409,
+ contentType: "application/json",
+ body: JSON.stringify({ code: "version_conflict", message: "feature flag version is stale", current }),
+ })
+ return
+ }
+ await route.fallback()
+ })
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "admin-subs").getByRole("button", { name: "Actions for admin-subs" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ await page.getByRole("dialog", { name: "Edit admin-subs" }).getByRole("textbox", { name: "Value" }).fill('["other-admin"]')
+ await page.getByRole("button", { name: "Save changes" }).click()
+ const confirmation = page.getByRole("dialog", { name: "Confirm loss of administrator access" })
+ await confirmation.getByLabel("I understand I will lose access").check()
+ await confirmation.getByRole("button", { name: "Confirm and save" }).click()
+
+ await expect(confirmation).toBeHidden()
+ const editor = page.getByRole("dialog", { name: "Edit admin-subs" })
+ await expect(editor.getByText("This flag changed after you loaded it.")).toBeVisible()
+ await editor.getByRole("button", { name: "Reload current value" }).click()
+ await expect(editor.getByText("Current version: 8")).toBeVisible()
+ await expect(editor.getByRole("textbox", { name: "Value" })).toHaveValue(
+ '[\n "test-user-id",\n "other-admin",\n "new-admin"\n]',
+ )
+ })
+
+ test("sorts feature flags by key", async ({ page }) => {
+ await mockAdminFeatureFlagsApi(page)
+ await openAdminFeatureFlags(page)
+
+ const keyHeader = page.getByRole("columnheader", { name: /Key/ })
+ await keyHeader.getByRole("button").click()
+ let keys = await page.getByRole("row").locator("th code").allTextContents()
+ expect(keys).toEqual(["admin-subs", "legacy-threshold", "new-checkout"])
+
+ await keyHeader.getByRole("button").click()
+ keys = await page.getByRole("row").locator("th code").allTextContents()
+ expect(keys).toEqual(["new-checkout", "legacy-threshold", "admin-subs"])
+ })
+
+ test("uses multiline string editing and explains versions and managed behavior", async ({ page }) => {
+ const stringFlag: MockAdminFeatureFlag = {
+ key: "welcome-message",
+ path: "/feature-flags/cyclops-cs/welcome-message",
+ value_type: "string",
+ value: "hello\nworld",
+ raw_value: "hello\nworld",
+ ownership: "ad_hoc",
+ managed_by: "cyclops-cs",
+ deletable: true,
+ version: 5,
+ modified_at: "2026-08-13T12:00:00Z",
+ tags: {},
+ }
+ await mockAdminFeatureFlagsApi(page, [stringFlag, DEFAULT_ADMIN_FEATURE_FLAGS[2]])
+ await openAdminFeatureFlags(page)
+
+ await featureFlagRow(page, "welcome-message").getByRole("button", { name: "Actions for welcome-message" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ let editor = page.getByRole("dialog", { name: "Edit welcome-message" })
+ await expect(editor.getByRole("textbox", { name: "Value" })).toHaveJSProperty("tagName", "TEXTAREA")
+ await expect(editor.getByText("Current version: 5")).toBeVisible()
+ await editor.getByRole("button", { name: "Cancel" }).click()
+
+ await featureFlagRow(page, "legacy-threshold").getByRole("button", { name: "Actions for legacy-threshold" }).click()
+ await page.getByRole("menuitem", { name: "Edit" }).click()
+ editor = page.getByRole("dialog", { name: "Edit legacy-threshold" })
+ await expect(editor.getByText("External flags cannot be deleted here.")).toBeVisible()
+ await expect(editor.getByText(/Consumers receive defaults/)).toHaveCount(0)
+ })
+
+})
+
+async function mountFeatureFlagsHarness(page: import("@playwright/test").Page): Promise<void> {
+ await page.goto("/e2e/fixtures/feature-flags-harness.html")
+}
+
+test.describe("feature flag refresh", () => {
+ test("keeps the forced config result when an older request resolves later", async ({ page }) => {
+ await mockAuth(page)
+
+ let resolveInitial: (() => void) | undefined
+ const initialReady = new Promise<void>(resolve => {
+ resolveInitial = resolve
+ })
+ let configRequests = 0
+ await page.route("**/api/config", async route => {
+ configRequests += 1
+ if (configRequests === 1) {
+ await initialReady
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: true, billing: false }),
+ })
+ return
+ }
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: false, billing: false }),
+ })
+ })
+
+ await mountFeatureFlagsHarness(page)
+ await expect(page.getByTestId("flags-state")).toHaveText("false:false")
+ await page.getByRole("button", { name: "Refresh config" }).click()
+ await expect.poll(() => configRequests).toBe(2)
+ await expect(page.getByTestId("flags-state")).toHaveText("false:true")
+
+ resolveInitial?.()
+ await expect(page.getByTestId("flags-state")).toHaveText("false:true")
+ await page.getByRole("button", { name: "Read cached config" }).click()
+ await expect(page.getByTestId("cached-state")).toHaveText("false:false")
+ })
+
+ test("rejects failed refreshes while failing closed in context", async ({ page }) => {
+ await mockAuth(page)
+
+ let configRequests = 0
+ await page.route("**/api/config", async route => {
+ configRequests += 1
+ if (configRequests === 1) {
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: true, billing: false }),
+ })
+ return
+ }
+ await route.abort("failed")
+ })
+
+ await mountFeatureFlagsHarness(page)
+ await expect(page.getByTestId("flags-state")).toHaveText("true:true")
+ await page.getByRole("button", { name: "Refresh config" }).click()
+ await expect(page.getByTestId("refresh-outcome")).toHaveText("rejected")
+ await expect(page.getByTestId("flags-state")).toHaveText("false:true")
+ })
+
+ test("hides stale admin navigation and route content while refresh resolves", async ({ page }) => {
+ await mockAuth(page)
+
+ let resolveRefresh: (() => void) | undefined
+ const refreshReady = new Promise<void>(resolve => {
+ resolveRefresh = resolve
+ })
+ let configRequests = 0
+ await page.route("**/api/config", async route => {
+ configRequests += 1
+ if (configRequests === 1) {
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: true, billing: false }),
+ })
+ return
+ }
+ await refreshReady
+ await route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ admin: false, billing: false }),
+ })
+ })
+
+ await mountFeatureFlagsHarness(page)
+ await expect(page.getByRole("link", { name: "Feature flags" })).toBeVisible()
+ await expect(page.getByRole("heading", { name: "Feature flags" })).toBeVisible()
+
+ await page.getByRole("button", { name: "Refresh config" }).click()
+ await expect.poll(() => configRequests).toBe(2)
+ await expect(page.getByTestId("flags-state")).toHaveText("false:false")
+ await expect(page.getByRole("link", { name: "Feature flags" })).toHaveCount(0)
+ await expect(page.getByRole("heading", { name: "Feature flags" })).toHaveCount(0)
+
+ resolveRefresh?.()
+ await expect(page.getByTestId("flags-state")).toHaveText("false:true")
+ })
+})
diff --git a/libs/fleet/e2e/fixtures/feature-flags-harness.html b/libs/fleet/e2e/fixtures/feature-flags-harness.html
new file mode 100644
index 0000000000..a673caf5d0
--- /dev/null
+++ b/libs/fleet/e2e/fixtures/feature-flags-harness.html
@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <title>Feature flags test harness</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module">
+ import RefreshRuntime from "/@react-refresh"
+ RefreshRuntime.injectIntoGlobalHook(window)
+ window.$RefreshReg$ = () => {}
+ window.$RefreshSig$ = () => type => type
+ window.__vite_plugin_react_preamble_installed__ = true
+ </script>
+ <script type="module" src="/e2e/fixtures/feature-flags-harness.tsx"></script>
+ </body>
+</html>
diff --git a/libs/fleet/e2e/fixtures/feature-flags-harness.tsx b/libs/fleet/e2e/fixtures/feature-flags-harness.tsx
new file mode 100644
index 0000000000..3ee5891c50
--- /dev/null
+++ b/libs/fleet/e2e/fixtures/feature-flags-harness.tsx
@@ -0,0 +1,55 @@
+import { createRoot } from "react-dom/client"
+import { BrowserRouter, Route, Routes } from "react-router-dom"
+import { useState } from "react"
+import { AdminRoute } from "../../src/components/AdminRoute"
+import { fetchFeatureFlags } from "../../src/sdk/featureFlags"
+import {
+ FeatureFlagProvider,
+ useFeatureFlags,
+} from "../../src/components/FeatureFlagContext"
+
+function Controls() {
+ const { admin, refresh, resolved } = useFeatureFlags()
+ const [outcome, setOutcome] = useState("idle")
+ const [cached, setCached] = useState("idle")
+ const refreshFlags = async () => {
+ try {
+ await refresh()
+ setOutcome("fulfilled")
+ } catch {
+ setOutcome("rejected")
+ }
+ }
+
+ return (
+ <>
+ {admin && resolved ? <a href="#admin">Feature flags</a> : null}
+ <button onClick={() => void refreshFlags()}>Refresh config</button>
+ <output data-testid="flags-state">{`${admin}:${resolved}`}</output>
+ <button onClick={() => void fetchFeatureFlags().then(flags => setCached(`${flags.admin}:${flags.billing}`))}>
+ Read cached config
+ </button>
+ <output data-testid="refresh-outcome">{outcome}</output>
+ <output data-testid="cached-state">{cached}</output>
+ </>
+ )
+}
+
+function Harness() {
+ return (
+ <FeatureFlagProvider>
+ <BrowserRouter>
+ <Controls />
+ <Routes>
+ <Route element={<AdminRoute />}>
+ <Route path="*" element={<h1>Feature flags</h1>} />
+ </Route>
+ </Routes>
+ </BrowserRouter>
+ </FeatureFlagProvider>
+ )
+}
+
+const root = document.getElementById("root")
+if (!root) throw new Error("missing root")
+createRoot(root).render(<Harness />)
diff --git a/libs/fleet/e2e/fixtures/mock-api.ts b/libs/fleet/e2e/fixtures/mock-api.ts
index 1429e922c2..5540342637 100644
--- a/libs/fleet/e2e/fixtures/mock-api.ts
+++ b/libs/fleet/e2e/fixtures/mock-api.ts
@@ -189,6 +189,173 @@ export async function mockAuth(
}
}
+// ---------------------------------------------------------------------------
+// Feature flags / per-user config mocking
+// ---------------------------------------------------------------------------
+
+export async function mockConfigApi(
+ page: Page,
+ config: { admin: boolean; billing?: boolean },
+): Promise<void> {
+ await page.route("**/api/config", route =>
+ route.fulfill({
+ contentType: "application/json",
+ body: JSON.stringify({ billing: false, ...config }),
+ }),
+ )
+}
+
+// ---------------------------------------------------------------------------
+// Admin feature flags API mocking
+// ---------------------------------------------------------------------------
+
+export type MockFeatureFlagValueType = "boolean" | "number" | "string" | "json"
+export type MockFeatureFlagOwnership = "terraform" | "ad_hoc" | "external"
+
+export interface MockAdminFeatureFlag {
+ key: string
+ path: string
+ value_type: MockFeatureFlagValueType
+ value: unknown
+ raw_value: string
+ ownership: MockFeatureFlagOwnership
+ managed_by?: string
+ deletable: boolean
+ version: number
+ modified_at: string
+ description?: string
+ tags: Record<string, string>
+}
+
+export interface MockFeatureFlagRequest {
+ method: string
+ key?: string
+ body?: Record<string, unknown>
+}
+
+export const DEFAULT_ADMIN_FEATURE_FLAGS: MockAdminFeatureFlag[] = [
+ {
+ key: "admin-subs",
+ path: "/feature-flags/cyclops-cs/admin-subs",
+ value_type: "json",
+ value: ["test-user-id", "other-admin"],
+ raw_value: '["test-user-id","other-admin"]',
+ ownership: "terraform",
+ managed_by: "terraform",
+ deletable: false,
+ version: 7,
+ modified_at: "2026-08-12T10:15:00Z",
+ description: "Cyclops administrators",
+ tags: { ManagedBy: "Terraform" },
+ },
+ {
+ key: "new-checkout",
+ path: "/feature-flags/cyclops-cs/new-checkout",
+ value_type: "boolean",
+ value: true,
+ raw_value: "true",
+ ownership: "ad_hoc",
+ managed_by: "cyclops-cs",
+ deletable: true,
+ version: 3,
+ modified_at: "2026-08-13T08:30:00Z",
+ description: "Enable the checkout experiment",
+ tags: { ManagedBy: "cyclops-cs" },
+ },
+ {
+ key: "legacy-threshold",
+ path: "/feature-flags/cyclops-cs/legacy-threshold",
+ value_type: "number",
+ value: 12.5,
+ raw_value: "12.5",
+ ownership: "external",
+ managed_by: "migration-tool",
+ deletable: false,
+ version: 11,
+ modified_at: "2026-08-11T17:45:00Z",
+ tags: {},
+ },
+]
+
+function rawFeatureFlagValue(value: unknown, valueType: MockFeatureFlagValueType): string {
+ if (valueType === "string") return String(value)
+ return JSON.stringify(value)
+}
+
+export async function mockAdminFeatureFlagsApi(
+ page: Page,
+ initialFlags: MockAdminFeatureFlag[] = DEFAULT_ADMIN_FEATURE_FLAGS,
+): Promise<{ flags: MockAdminFeatureFlag[]; requests: MockFeatureFlagRequest[] }> {
+ const flags = initialFlags.map(flag => ({ ...flag, tags: { ...flag.tags } }))
+ const requests: MockFeatureFlagRequest[] = []
+
+ await page.route(/\/api\/admin\/feature-flags(?:\/[^/?]+)?(?:\?.*)?$/, async route => {
+ const request = route.request()
+ const url = new URL(request.url())
+ const pathParts = url.pathname.split("/").filter(Boolean)
+ const encodedKey = pathParts.length > 3 ? pathParts.at(-1) : undefined
+ const key = encodedKey ? decodeURIComponent(encodedKey) : undefined
+ const body = request.postData() ? request.postDataJSON() as Record<string, unknown> : undefined
+ requests.push({ method: request.method(), key, body })
+
+ if (request.method() === "GET" && !key) {
+ await route.fulfill({ contentType: "application/json", body: JSON.stringify(flags) })
+ return
+ }
+
+ if (request.method() === "POST" && !key && body) {
+ const valueType = body.value_type as MockFeatureFlagValueType
+ const created: MockAdminFeatureFlag = {
+ key: String(body.key),
+ path: `/feature-flags/cyclops-cs/${String(body.key)}`,
+ value_type: valueType,
+ value: body.value,
+ raw_value: rawFeatureFlagValue(body.value, valueType),
+ ownership: "ad_hoc",
+ managed_by: "cyclops-cs",
+ deletable: true,
+ version: 1,
+ modified_at: "2026-08-13T12:00:00Z",
+ description: body.description ? String(body.description) : undefined,
+ tags: { ManagedBy: "cyclops-cs" },
+ }
+ flags.push(created)
+ await route.fulfill({ status: 201, contentType: "application/json", body: JSON.stringify(created) })
+ return
+ }
+
+ const index = flags.findIndex(flag => flag.key === key)
+ if (index < 0) {
+ await route.fulfill({ status: 404, contentType: "application/json", body: JSON.stringify({ code: "flag_not_found", message: "feature flag not found" }) })
+ return
+ }
+
+ if (request.method() === "PUT" && body) {
+ const valueType = body.value_type as MockFeatureFlagValueType
+ flags[index] = {
+ ...flags[index],
+ value_type: valueType,
+ value: body.value,
+ raw_value: rawFeatureFlagValue(body.value, valueType),
+ version: flags[index].version + 1,
+ modified_at: "2026-08-13T12:05:00Z",
+ }
+ await route.fulfill({ contentType: "application/json", body: JSON.stringify(flags[index]) })
+ return
+ }
+
+ if (request.method() === "DELETE") {
+ flags.splice(index, 1)
+ await route.fulfill({ status: 204, body: "" })
+ return
+ }
+
+ await route.continue()
+ })
+
+ return { flags, requests }
+}
+
// ---------------------------------------------------------------------------
// Namespaces API mocking
// ---------------------------------------------------------------------------
diff --git a/libs/fleet/nginx.conf b/libs/fleet/nginx.conf
index a2aa347e65..e792b178ef 100644
--- a/libs/fleet/nginx.conf
+++ b/libs/fleet/nginx.conf
@@ -150,7 +150,7 @@ server {
proxy_set_header X-Forwarded-Proto $scheme;
}
- location ~ ^/api/(keys|user-keys|github-trust-policies|gateway|k8s|swagger|batch|label|namespaces|config|chat|billing|state|usage)(/|$) {
+ location ~ ^/api/(keys|user-keys|github-trust-policies|gateway|k8s|swagger|batch|label|namespaces|config|chat|billing|state|usage|admin)(/|$) {
proxy_pass ${CYCLOPS_CS_BACKEND};
proxy_http_version 1.1;
proxy_set_header Host $host;
diff --git a/libs/fleet/src/App.tsx b/libs/fleet/src/App.tsx
index 02e5a02f6a..aba92a7868 100644
--- a/libs/fleet/src/App.tsx
+++ b/libs/fleet/src/App.tsx
@@ -8,6 +8,7 @@ import {
useNavigate,
} from "react-router-dom"
import AppLayout from "@cloudscape-design/components/app-layout"
+import Badge from "@cloudscape-design/components/badge"
import Button from "@cloudscape-design/components/button"
import SideNavigation from "@cloudscape-design/components/side-navigation"
import TopNavigation from "@cloudscape-design/components/top-navigation"
@@ -24,7 +25,9 @@ import { Settings } from "./pages/Settings"
import { AgentChat } from "./pages/AgentChat"
import { Usage } from "./pages/Usage"
import { PageShell } from "./components/PageShell"
+import { FeatureFlags } from "./pages/FeatureFlags"
import { FeatureFlagProvider, useFeatureFlags } from "./components/FeatureFlagContext"
+import { AdminRoute } from "./components/AdminRoute"
import { FlashContext, type FlashMsg } from "./components/FlashContext"
import { logout, userInfo } from "./auth/keycloak"
import cuaLockup from "@cua/design/assets/brand/cua-lockup-white.svg"
@@ -109,7 +112,7 @@ function Shell() {
setNavigationOpen(tabletOrWider)
}, [tabletOrWider])
const user = userInfo()
- const { chat, usage } = useFeatureFlags()
+ const { admin, chat, usage } = useFeatureFlags()
useEffect(() => {
const path = location.pathname
const pageTitle = path === "/usage"
@@ -205,6 +208,16 @@ function Shell() {
: []),
{ type: "link", text: "User API keys", href: "#/user-keys" },
{ type: "link", text: "Settings", href: "#/settings" },
+ ...(admin
+ ? [
+ {
+ type: "link" as const,
+ text: "Feature flags",
+ href: "#/admin/feature-flags",
+ info: <Badge color="blue">Admin</Badge>,
+ },
+ ]
+ : []),
]}
/>
</div>
@@ -261,6 +274,9 @@ export function App() {
<Route path="/usage" element={<UsageRoute />} />
<Route path="/agent" element={<ChatRoute />} />
<Route path="/billing" element={<Navigate to="/settings" replace />} />
+ <Route element={<AdminRoute />}>
+ <Route path="/admin/feature-flags" element={<FeatureFlags />} />
+ </Route>
<Route
path="/pools/:namespace/:poolName/claims/:claimName"
element={<ClaimDetail />}
@@ -271,6 +287,7 @@ export function App() {
element={<Navigate to="/pools/new" replace />}
/>
<Route path="/modules/:name" element={<RedirectModule />} />
+ <Route path="*" element={<Navigate to="/pools" replace />} />
<Route path="/pools/:name" element={<Navigate to="/pools" replace />} />
</Route>
</Routes>
diff --git a/libs/fleet/src/components/AdminRoute.tsx b/libs/fleet/src/components/AdminRoute.tsx
new file mode 100644
index 0000000000..0ae0a4e681
--- /dev/null
+++ b/libs/fleet/src/components/AdminRoute.tsx
@@ -0,0 +1,11 @@
+import Spinner from "@cloudscape-design/components/spinner"
+import { Navigate, Outlet } from "react-router-dom"
+import { useFeatureFlags } from "./FeatureFlagContext"
+
+export function AdminRoute() {
+ const { admin, resolved } = useFeatureFlags()
+
+ if (!resolved) return <Spinner nativeAttributes={{ "aria-label": "Loading admin access" }} />
+ if (!admin) return <Navigate to="/pools" replace />
+ return <Outlet />
+}
diff --git a/libs/fleet/src/components/FeatureFlagContext.tsx b/libs/fleet/src/components/FeatureFlagContext.tsx
index 874f8e96a9..4e5040aa2d 100644
--- a/libs/fleet/src/components/FeatureFlagContext.tsx
+++ b/libs/fleet/src/components/FeatureFlagContext.tsx
@@ -1,4 +1,12 @@
-import { createContext, useContext, useEffect, useState, type ReactNode } from "react"
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useRef,
+ useState,
+ type ReactNode,
+} from "react"
import { fetchFeatureFlags, type FeatureFlags } from "../sdk/featureFlags"
import { isLocalVisualPreview } from "../local-visual-preview"
@@ -6,11 +14,15 @@ const DEFAULT_FLAGS: FeatureFlags = { admin: false, billing: false, chat: false,
interface FeatureFlagContextValue extends FeatureFlags {
resolved: boolean
+ refresh: () => Promise<FeatureFlags>
}
+const unavailableRefresh = async (): Promise<FeatureFlags> => DEFAULT_FLAGS
+
const FeatureFlagContext = createContext<FeatureFlagContextValue>({
...DEFAULT_FLAGS,
resolved: false,
+ refresh: unavailableRefresh,
})
/**
@@ -19,22 +31,49 @@ const FeatureFlagContext = createContext<FeatureFlagContextValue>({
*/
export function FeatureFlagProvider({ children }: { children: ReactNode }) {
const visualPreview = isLocalVisualPreview()
- const [value, setValue] = useState<FeatureFlagContextValue>({
+ const [value, setValue] = useState<Omit<FeatureFlagContextValue, "refresh">>({
...(visualPreview
? { ...DEFAULT_FLAGS, billing: true, chat: true }
: DEFAULT_FLAGS),
resolved: visualPreview,
})
+ const requestGeneration = useRef(0)
+
+ const refresh = useCallback(async (): Promise<FeatureFlags> => {
+ const currentGeneration = ++requestGeneration.current
+ setValue({ ...DEFAULT_FLAGS, resolved: false })
+ try {
+ const flags = await fetchFeatureFlags({ force: true })
+ if (requestGeneration.current === currentGeneration) {
+ setValue({ ...flags, resolved: true })
+ }
+ return flags
+ } catch (error) {
+ if (requestGeneration.current === currentGeneration) {
+ setValue({ ...DEFAULT_FLAGS, resolved: true })
+ }
+ throw error
+ }
+ }, [])
useEffect(() => {
if (visualPreview) return
+ const currentGeneration = ++requestGeneration.current
fetchFeatureFlags()
- .then(flags => setValue({ ...flags, resolved: true }))
- .catch(() => setValue({ ...DEFAULT_FLAGS, resolved: true }))
+ .then(flags => {
+ if (requestGeneration.current === currentGeneration) {
+ setValue({ ...flags, resolved: true })
+ }
+ })
+ .catch(() => {
+ if (requestGeneration.current === currentGeneration) {
+ setValue({ ...DEFAULT_FLAGS, resolved: true })
+ }
+ })
}, [visualPreview])
return (
- <FeatureFlagContext.Provider value={value}>
+ <FeatureFlagContext.Provider value={{ ...value, refresh }}>
{children}
</FeatureFlagContext.Provider>
)
diff --git a/libs/fleet/src/pages/FeatureFlags.tsx b/libs/fleet/src/pages/FeatureFlags.tsx
new file mode 100644
index 0000000000..3bf7be08f4
--- /dev/null
+++ b/libs/fleet/src/pages/FeatureFlags.tsx
@@ -0,0 +1,670 @@
+import { useCallback, useEffect, useMemo, useState } from "react"
+import { useCollection } from "@cloudscape-design/collection-hooks"
+import Alert from "@cloudscape-design/components/alert"
+import Badge from "@cloudscape-design/components/badge"
+import Box from "@cloudscape-design/components/box"
+import Button from "@cloudscape-design/components/button"
+import ButtonDropdown from "@cloudscape-design/components/button-dropdown"
+import Checkbox from "@cloudscape-design/components/checkbox"
+import CopyToClipboard from "@cloudscape-design/components/copy-to-clipboard"
+import Form from "@cloudscape-design/components/form"
+import FormField from "@cloudscape-design/components/form-field"
+import Header from "@cloudscape-design/components/header"
+import Input from "@cloudscape-design/components/input"
+import Link from "@cloudscape-design/components/link"
+import Modal from "@cloudscape-design/components/modal"
+import Select, { type SelectProps } from "@cloudscape-design/components/select"
+import SpaceBetween from "@cloudscape-design/components/space-between"
+import StatusIndicator from "@cloudscape-design/components/status-indicator"
+import Table from "@cloudscape-design/components/table"
+import Textarea from "@cloudscape-design/components/textarea"
+import TextFilter from "@cloudscape-design/components/text-filter"
+import { useNavigate } from "react-router-dom"
+import { userInfo } from "../auth/keycloak"
+import { useFeatureFlags } from "../components/FeatureFlagContext"
+import { useFlash } from "../components/FlashContext"
+import {
+ AdminFeatureFlagError,
+ adminFeatureFlagsApi,
+ type AdminFeatureFlag,
+ type FeatureFlagOwnership,
+ type FeatureFlagValueType,
+ type JSONValue,
+} from "../sdk/adminFeatureFlags"
+
+const TERRAFORM_FEATURE_FLAGS_URL =
+ "https://github.com/trycua/cloud/tree/main/terraform/aws/feature-flags"
+
+const VALUE_TYPE_OPTIONS: SelectProps.Option[] = [
+ { label: "Boolean", value: "boolean" },
+ { label: "Number", value: "number" },
+ { label: "String", value: "string" },
+ { label: "JSON", value: "json" },
+]
+
+const BOOLEAN_OPTIONS: SelectProps.Option[] = [
+ { label: "True", value: "true" },
+ { label: "False", value: "false" },
+]
+
+interface EditorState {
+ mode: "create" | "edit"
+ original?: AdminFeatureFlag
+ key: string
+ valueType: FeatureFlagValueType
+ valueText: string
+ description: string
+ error?: string
+ errorField?: "key" | "value"
+ conflict?: AdminFeatureFlag
+}
+
+function typeLabel(valueType: FeatureFlagValueType): string {
+ return valueType === "json" ? "JSON" : valueType[0].toUpperCase() + valueType.slice(1)
+}
+
+function ownershipLabel(ownership: FeatureFlagOwnership): string {
+ if (ownership === "ad_hoc") return "Ad hoc"
+ return ownership[0].toUpperCase() + ownership.slice(1)
+}
+
+function formatValue(value: JSONValue, valueType: FeatureFlagValueType): string {
+ if (valueType === "string") return String(value)
+ if (valueType === "json") return JSON.stringify(value, null, 2)
+ return JSON.stringify(value)
+}
+
+function compactValue(value: JSONValue, valueType: FeatureFlagValueType): string {
+ const formatted = valueType === "json" ? JSON.stringify(value) : formatValue(value, valueType)
+ return formatted.length > 72 ? `${formatted.slice(0, 69)}...` : formatted
+}
+
+function parseValue(valueType: FeatureFlagValueType, valueText: string): JSONValue {
+ if (valueType === "boolean") return valueText === "true"
+ if (valueType === "number") {
+ const parsed = Number(valueText)
+ if (!Number.isFinite(parsed) || valueText.trim() === "") throw new Error("Enter a valid number")
+ return parsed
+ }
+ if (valueType === "string") return valueText
+ try {
+ const parsed = JSON.parse(valueText) as JSONValue
+ if (parsed === null || typeof parsed !== "object") {
+ throw new Error("JSON values must be an object or array")
+ }
+ return parsed
+ } catch (error) {
+ if (error instanceof Error && error.message === "JSON values must be an object or array") throw error
+ throw new Error("Enter valid JSON")
+ }
+}
+
+function errorMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error)
+}
+
+export function FeatureFlags() {
+ const navigate = useNavigate()
+ const flash = useFlash()
+ const { refresh: refreshAccess } = useFeatureFlags()
+ const currentUser = userInfo()
+ const [flags, setFlags] = useState<AdminFeatureFlag[]>([])
+ const [loading, setLoading] = useState(true)
+ const [error, setError] = useState<string | null>(null)
+ const [filteringText, setFilteringText] = useState("")
+ const [editor, setEditor] = useState<EditorState | null>(null)
+ const [submitting, setSubmitting] = useState(false)
+ const [deleteFlag, setDeleteFlag] = useState<AdminFeatureFlag | null>(null)
+ const [deleteConfirmation, setDeleteConfirmation] = useState("")
+ const [deleteError, setDeleteError] = useState<string | null>(null)
+ const [deleteConflict, setDeleteConflict] = useState<AdminFeatureFlag | null>(null)
+ const [selfRemovalPending, setSelfRemovalPending] = useState<JSONValue | null>(null)
+ const [selfRemovalConfirmed, setSelfRemovalConfirmed] = useState(false)
+ const [selfRemovalError, setSelfRemovalError] = useState<string | null>(null)
+ const [valueDetails, setValueDetails] = useState<AdminFeatureFlag | null>(null)
+
+ const clearAdminState = useCallback(() => {
+ setFlags([])
+ setError(null)
+ setFilteringText("")
+ setEditor(null)
+ setDeleteFlag(null)
+ setDeleteConfirmation("")
+ setDeleteError(null)
+ setDeleteConflict(null)
+ setSelfRemovalPending(null)
+ setSelfRemovalConfirmed(false)
+ setSelfRemovalError(null)
+ setValueDetails(null)
+ }, [])
+
+ const handleAuthorizationError = useCallback(async (requestError: unknown): Promise<boolean> => {
+ if (!(requestError instanceof AdminFeatureFlagError) || requestError.code !== "not_admin") return false
+ clearAdminState()
+ try {
+ await refreshAccess()
+ } finally {
+ navigate("/pools", { replace: true })
+ }
+ return true
+ }, [clearAdminState, navigate, refreshAccess])
+
+ const load = useCallback(async () => {
+ setLoading(true)
+ try {
+ setFlags(await adminFeatureFlagsApi.list())
+ setError(null)
+ } catch (loadError) {
+ if (!await handleAuthorizationError(loadError)) setError(errorMessage(loadError))
+ } finally {
+ setLoading(false)
+ }
+ }, [handleAuthorizationError])
+
+ useEffect(() => {
+ void load()
+ }, [load])
+
+ const filteredFlags = useMemo(() => {
+ const filter = filteringText.trim().toLowerCase()
+ if (!filter) return flags
+ return flags.filter(flag =>
+ [flag.key, compactValue(flag.value, flag.value_type), flag.value_type, flag.ownership, flag.managed_by]
+ .filter(Boolean)
+ .some(value => String(value).toLowerCase().includes(filter)),
+ )
+ }, [filteringText, flags])
+
+ const { items: sortedFlags, collectionProps } = useCollection(filteredFlags, {
+ sorting: {},
+ })
+
+ const openCreate = () => {
+ setEditor({ mode: "create", key: "", valueType: "boolean", valueText: "false", description: "" })
+ }
+
+ const openEdit = (flag: AdminFeatureFlag) => {
+ setEditor({
+ mode: "edit",
+ original: flag,
+ key: flag.key,
+ valueType: flag.value_type,
+ valueText: formatValue(flag.value, flag.value_type),
+ description: flag.description ?? "",
+ })
+ }
+
+ const changeValueType = (valueType: FeatureFlagValueType) => {
+ setEditor(current => {
+ if (!current) return current
+ const valueText = valueType === "boolean" ? "false" : valueType === "json" ? "{}" : ""
+ return { ...current, valueType, valueText, error: undefined, errorField: undefined, conflict: undefined }
+ })
+ }
+
+ const saveValue = async (value: JSONValue) => {
+ if (!editor) return
+ setSubmitting(true)
+ try {
+ if (editor.mode === "create") {
+ await adminFeatureFlagsApi.create({
+ key: editor.key.trim(),
+ value_type: editor.valueType,
+ value,
+ ...(editor.description.trim() ? { description: editor.description.trim() } : {}),
+ })
+ flash.push({ type: "success", content: `Created ${editor.key.trim()}` })
+ } else if (editor.original) {
+ await adminFeatureFlagsApi.update(editor.original.key, {
+ value_type: editor.valueType,
+ value,
+ expected_version: editor.original.version,
+ })
+ flash.push({ type: "success", content: `Updated ${editor.original.key}` })
+ }
+ const updatedAdminSubs = editor.mode === "edit" && editor.original?.key === "admin-subs"
+ if (updatedAdminSubs) {
+ const access = await refreshAccess()
+ if (!access.admin) {
+ clearAdminState()
+ navigate("/pools", { replace: true })
+ return
+ }
+ }
+ setEditor(null)
+ setSelfRemovalPending(null)
+ setSelfRemovalConfirmed(false)
+ setSelfRemovalError(null)
+ await load()
+ } catch (saveError) {
+ if (await handleAuthorizationError(saveError)) return
+ if (saveError instanceof AdminFeatureFlagError && saveError.code === "version_conflict") {
+ if (selfRemovalPending !== null) {
+ setSelfRemovalPending(null)
+ setSelfRemovalConfirmed(false)
+ setSelfRemovalError(null)
+ }
+ setEditor(current => current ? { ...current, conflict: saveError.current, error: undefined, errorField: undefined } : current)
+ } else if (selfRemovalPending !== null) {
+ setSelfRemovalError(errorMessage(saveError))
+ } else {
+ setEditor(current => current ? { ...current, error: errorMessage(saveError), errorField: undefined } : current)
+ }
+ } finally {
+ setSubmitting(false)
+ }
+ }
+
+ const submitEditor = async () => {
+ if (!editor) return
+ if (editor.mode === "create" && editor.key.trim().length > 63) {
+ setEditor({
+ ...editor,
+ error: "Feature flag keys can be at most 63 characters",
+ errorField: "key",
+ })
+ return
+ }
+ if (editor.mode === "create" && !/^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$/.test(editor.key.trim())) {
+ setEditor({
+ ...editor,
+ error: "Use a lowercase DNS label with letters, numbers, or hyphens",
+ errorField: "key",
+ })
+ return
+ }
+ let value: JSONValue
+ try {
+ value = parseValue(editor.valueType, editor.valueText)
+ } catch (parseError) {
+ setEditor({ ...editor, error: errorMessage(parseError), errorField: "value" })
+ return
+ }
+ const removesCurrentUser =
+ editor.mode === "edit" &&
+ editor.original?.key === "admin-subs" &&
+ editor.valueType === "json" &&
+ Array.isArray(value) &&
+ Boolean(currentUser.sub) &&
+ !value.includes(currentUser.sub as JSONValue)
+ if (removesCurrentUser && selfRemovalPending === null) {
+ setSelfRemovalPending(value)
+ setSelfRemovalConfirmed(false)
+ setSelfRemovalError(null)
+ return
+ }
+ await saveValue(value)
+ }
+
+ const reloadConflict = () => {
+ if (!editor?.conflict) return
+ const current = editor.conflict
+ setEditor({
+ mode: "edit",
+ original: current,
+ key: current.key,
+ valueType: current.value_type,
+ valueText: formatValue(current.value, current.value_type),
+ description: current.description ?? "",
+ })
+ }
+
+ const remove = async () => {
+ if (!deleteFlag) return
+ setSubmitting(true)
+ setDeleteError(null)
+ try {
+ await adminFeatureFlagsApi.remove(deleteFlag.key, deleteFlag.version)
+ flash.push({ type: "success", content: `Deleted ${deleteFlag.key}` })
+ setDeleteFlag(null)
+ setDeleteConfirmation("")
+ setDeleteConflict(null)
+ await load()
+ } catch (removeError) {
+ if (removeError instanceof AdminFeatureFlagError && removeError.code === "version_conflict" && removeError.current) {
+ setDeleteConflict(removeError.current)
+ } else {
+ setDeleteError(errorMessage(removeError))
+ }
+ } finally {
+ setSubmitting(false)
+ }
+ }
+
+ const reloadDeleteConflict = () => {
+ if (!deleteConflict) return
+ setDeleteFlag(deleteConflict)
+ setDeleteConflict(null)
+ setDeleteError(null)
+ setDeleteConfirmation("")
+ }
+
+ const editorValueControl = editor?.valueType === "boolean" ? (
+ <Select
+ ariaLabel="Value"
+ selectedOption={BOOLEAN_OPTIONS.find(option => option.value === editor.valueText) ?? BOOLEAN_OPTIONS[1]}
+ options={BOOLEAN_OPTIONS}
+ onChange={({ detail }) => setEditor(current => current ? { ...current, valueText: detail.selectedOption.value ?? "false", error: undefined, errorField: undefined } : current)}
+ />
+ ) : editor?.valueType === "json" || editor?.valueType === "string" ? (
+ <Textarea
+ ariaLabel="Value"
+ rows={10}
+ value={editor.valueText}
+ onChange={({ detail }) => setEditor(current => current ? { ...current, valueText: detail.value, error: undefined, errorField: undefined } : current)}
+ />
+ ) : (
+ <Input
+ ariaLabel="Value"
+ type={editor?.valueType === "number" ? "number" : "text"}
+ value={editor?.valueText ?? ""}
+ onChange={({ detail }) => setEditor(current => current ? { ...current, valueText: detail.value, error: undefined, errorField: undefined } : current)}
+ />
+ )
+
+ return (
+ <>
+ <Table
+ {...collectionProps}
+ trackBy="key"
+ loading={loading}
+ loadingText="Loading feature flags"
+ items={sortedFlags}
+ empty={
+ <Box textAlign="center" padding="l">
+ <SpaceBetween size="xs">
+ <b>{filteringText ? "No matching feature flags" : "No feature flags"}</b>
+ {filteringText ? (
+ <Button onClick={() => setFilteringText("")}>Clear filter</Button>
+ ) : (
+ <Button onClick={openCreate}>Create feature flag</Button>
+ )}
+ </SpaceBetween>
+ </Box>
+ }
+ header={
+ <Header
+ variant="h1"
+ counter={loading ? undefined : `(${flags.length})`}
+ info={<Badge color="blue">Admin only · Feature flagged</Badge>}
+ description="Manage typed values under /feature-flags/cyclops-cs/. Terraform and external keys remain protected."
+ actions={
+ <SpaceBetween direction="horizontal" size="xs">
+ <Button
+ iconName="refresh"
+ ariaLabel="Refresh feature flags"
+ disabled={loading}
+ onClick={() => void load()}
+ />
+ <Button variant="primary" onClick={openCreate}>Create feature flag</Button>
+ </SpaceBetween>
+ }
+ >
+ Feature flags
+ </Header>
+ }
+ filter={
+ <TextFilter
+ filteringText={filteringText}
+ filteringPlaceholder="Find feature flags"
+ filteringClearAriaLabel="Clear filter"
+ countText={`${filteredFlags.length} matches`}
+ onChange={({ detail }) => setFilteringText(detail.filteringText)}
+ />
+ }
+ columnDefinitions={[
+ {
+ id: "key",
+ header: "Key",
+ cell: flag => <code>{flag.key}</code>,
+ isRowHeader: true,
+ sortingField: "key",
+ },
+ {
+ id: "value",
+ header: "Value",
+ cell: flag => (
+ <SpaceBetween direction="horizontal" size="xs">
+ <code>{compactValue(flag.value, flag.value_type)}</code>
+ <Button
+ variant="inline-icon"
+ iconName="view-full"
+ ariaLabel={`View full value for ${flag.key}`}
+ onClick={() => setValueDetails(flag)}
+ />
+ </SpaceBetween>
+ ),
+ },
+ { id: "type", header: "Type", cell: flag => typeLabel(flag.value_type), sortingField: "value_type" },
+ {
+ id: "ownership",
+ header: "Ownership",
+ sortingField: "ownership",
+ cell: flag => flag.ownership === "terraform" ? (
+ <Link external externalIconAriaLabel="Opens in a new tab" href={TERRAFORM_FEATURE_FLAGS_URL}>
+ <Badge color="blue">Terraform</Badge>
+ </Link>
+ ) : <Badge color={flag.ownership === "ad_hoc" ? "green" : "grey"}>{ownershipLabel(flag.ownership)}</Badge>,
+ },
+ { id: "version", header: "Version", cell: flag => flag.version, sortingField: "version" },
+ {
+ id: "modified",
+ header: "Modified",
+ cell: flag => new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeStyle: "short" }).format(new Date(flag.modified_at)),
+ sortingField: "modified_at",
+ },
+ {
+ id: "actions",
+ header: "Actions",
+ cell: flag => (
+ <ButtonDropdown
+ ariaLabel={`Actions for ${flag.key}`}
+ variant="icon"
+ expandToViewport
+ items={[
+ { id: "edit", text: "Edit" },
+ ...(flag.key !== "admin-subs" && flag.ownership === "ad_hoc" && flag.deletable
+ ? [{ id: "delete", text: "Delete" }]
+ : []),
+ ]}
+ onItemClick={({ detail }) => {
+ if (detail.id === "edit") openEdit(flag)
+ if (detail.id === "delete") {
+ setDeleteFlag(flag)
+ setDeleteConfirmation("")
+ setDeleteError(null)
+ setDeleteConflict(null)
+ }
+ }}
+ />
+ ),
+ },
+ ]}
+ />
+
+ {error && (
+ <Box margin={{ top: "m" }}>
+ <Alert type="error" dismissible onDismiss={() => setError(null)}>{error}</Alert>
+ </Box>
+ )}
+
+ <Modal
+ visible={editor !== null}
+ header={editor?.mode === "create" ? "Create feature flag" : `Edit ${editor?.key ?? "feature flag"}`}
+ onDismiss={() => !submitting && setEditor(null)}
+ footer={
+ <Box float="right">
+ <SpaceBetween direction="horizontal" size="xs">
+ <Button disabled={submitting} onClick={() => setEditor(null)}>Cancel</Button>
+ <Button variant="primary" loading={submitting} onClick={() => void submitEditor()}>
+ {editor?.mode === "create" ? "Create" : "Save changes"}
+ </Button>
+ </SpaceBetween>
+ </Box>
+ }
+ >
+ {editor && (
+ <Form errorText={editor.errorField ? undefined : editor.error}>
+ <SpaceBetween size="m">
+ {editor.conflict && (
+ <Alert
+ type="warning"
+ action={<Button onClick={reloadConflict}>Reload current value</Button>}
+ >
+ This flag changed after you loaded it.
+ </Alert>
+ )}
+ <FormField label="Key" errorText={editor.errorField === "key" ? editor.error : undefined}>
+ <Input
+ value={editor.key}
+ disabled={editor.mode === "edit"}
+ onChange={({ detail }) => setEditor(current => current ? { ...current, key: detail.value, error: undefined, errorField: undefined } : current)}
+ />
+ </FormField>
+ <FormField label="Value type">
+ <Select
+ selectedOption={VALUE_TYPE_OPTIONS.find(option => option.value === editor.valueType) ?? null}
+ options={VALUE_TYPE_OPTIONS}
+ onChange={({ detail }) => changeValueType(detail.selectedOption.value as FeatureFlagValueType)}
+ />
+ </FormField>
+ <FormField label="Value" errorText={editor.errorField === "value" ? editor.error : undefined}>{editorValueControl}</FormField>
+ {editor.mode === "create" && (
+ <FormField label="Description (optional)">
+ <Textarea
+ value={editor.description}
+ onChange={({ detail }) => setEditor(current => current ? { ...current, description: detail.value } : current)}
+ />
+ </FormField>
+ )}
+ {editor.mode === "edit" && editor.original?.description && (
+ <FormField label="Description">
+ <Box>{editor.original.description}</Box>
+ </FormField>
+ )}
+ {editor.mode === "edit" && editor.original && (
+ <Box color="text-body-secondary">Current version: {editor.original.version}</Box>
+ )}
+ {editor.mode === "edit" && editor.original?.ownership !== "ad_hoc" && (
+ <StatusIndicator type="info">The key is protected; only its typed value can be changed.</StatusIndicator>
+ )}
+ {editor.mode === "edit" && editor.original?.ownership === "external" && (
+ <StatusIndicator type="info">External flags cannot be deleted here.</StatusIndicator>
+ )}
+ </SpaceBetween>
+ </Form>
+ )}
+ </Modal>
+
+ <Modal
+ visible={deleteFlag !== null}
+ header={`Delete ${deleteFlag?.key ?? "feature flag"}?`}
+ onDismiss={() => {
+ if (!submitting) {
+ setDeleteFlag(null)
+ setDeleteError(null)
+ setDeleteConflict(null)
+ }
+ }}
+ footer={
+ <Box float="right">
+ <SpaceBetween direction="horizontal" size="xs">
+ <Button disabled={submitting} onClick={() => setDeleteFlag(null)}>Cancel</Button>
+ <Button
+ variant="primary"
+ loading={submitting}
+ disabled={deleteConfirmation !== deleteFlag?.key}
+ onClick={() => void remove()}
+ >
+ Delete feature flag
+ </Button>
+ </SpaceBetween>
+ </Box>
+ }
+ >
+ <SpaceBetween size="m">
+ <Alert type="warning">This action cannot be undone.</Alert>
+ <StatusIndicator type="info">
+ Deleting this flag causes consumers to receive defaults after the feature flag cache refreshes.
+ </StatusIndicator>
+ {deleteConflict && (
+ <Alert
+ type="warning"
+ action={<Button onClick={reloadDeleteConflict}>Reload current version</Button>}
+ >
+ This flag changed after you loaded it.
+ </Alert>
+ )}
+ {deleteError && <Alert type="error">{deleteError}</Alert>}
+ {deleteFlag && <Box color="text-body-secondary">Current version: {deleteFlag.version}</Box>}
+ <FormField label={`Type ${deleteFlag?.key ?? "the key"} to confirm`}>
+ <Input value={deleteConfirmation} onChange={({ detail }) => setDeleteConfirmation(detail.value)} />
+ </FormField>
+ </SpaceBetween>
+ </Modal>
+
+ <Modal
+ visible={selfRemovalPending !== null}
+ header="Confirm loss of administrator access"
+ onDismiss={() => {
+ if (!submitting) {
+ setSelfRemovalPending(null)
+ setSelfRemovalError(null)
+ }
+ }}
+ footer={
+ <Box float="right">
+ <SpaceBetween direction="horizontal" size="xs">
+ <Button disabled={submitting} onClick={() => setSelfRemovalPending(null)}>Cancel</Button>
+ <Button
+ variant="primary"
+ loading={submitting}
+ disabled={!selfRemovalConfirmed}
+ onClick={() => selfRemovalPending !== null && void saveValue(selfRemovalPending)}
+ >
+ Confirm and save
+ </Button>
+ </SpaceBetween>
+ </Box>
+ }
+ >
+ <SpaceBetween size="m">
+ <Alert type="warning">You are removing your own administrator access.</Alert>
+ {selfRemovalError && <Alert type="error">{selfRemovalError}</Alert>}
+ <Checkbox checked={selfRemovalConfirmed} onChange={({ detail }) => setSelfRemovalConfirmed(detail.checked)}>
+ I understand I will lose access
+ </Checkbox>
+ </SpaceBetween>
+ </Modal>
+
+ <Modal
+ visible={valueDetails !== null}
+ header={`Value for ${valueDetails?.key ?? "feature flag"}`}
+ onDismiss={() => setValueDetails(null)}
+ footer={
+ <Box float="right">
+ <Button onClick={() => setValueDetails(null)}>Close</Button>
+ </Box>
+ }
+ >
+ {valueDetails && (
+ <SpaceBetween size="m">
+ <Box variant="code" padding="m">
+ <pre style={{ margin: 0, whiteSpace: "pre-wrap", overflowWrap: "anywhere" }}>
+ {formatValue(valueDetails.value, valueDetails.value_type)}
+ </pre>
+ </Box>
+ <CopyToClipboard
+ variant="button"
+ copyButtonText="Copy full value"
+ copyButtonAriaLabel="Copy full value"
+ textToCopy={formatValue(valueDetails.value, valueDetails.value_type)}
+ copySuccessText="Feature flag value copied"
+ copyErrorText="Failed to copy feature flag value"
+ />
+ </SpaceBetween>
+ )}
+ </Modal>
+ </>
+ )
+}
diff --git a/libs/fleet/src/sdk/adminFeatureFlags.ts b/libs/fleet/src/sdk/adminFeatureFlags.ts
new file mode 100644
index 0000000000..890da59b11
--- /dev/null
+++ b/libs/fleet/src/sdk/adminFeatureFlags.ts
@@ -0,0 +1,106 @@
+import { getToken } from "../auth/keycloak"
+
+export type FeatureFlagValueType = "boolean" | "number" | "string" | "json"
+export type FeatureFlagOwnership = "terraform" | "ad_hoc" | "external"
+export type JSONValue =
+ | null
+ | boolean
+ | number
+ | string
+ | JSONValue[]
+ | { [key: string]: JSONValue }
+
+export interface AdminFeatureFlag {
+ key: string
+ path: string
+ value_type: FeatureFlagValueType
+ value: JSONValue
+ raw_value: string
+ ownership: FeatureFlagOwnership
+ managed_by?: string
+ deletable: boolean
+ version: number
+ modified_at: string
+ description?: string
+ tags: Record<string, string>
+}
+
+export interface CreateAdminFeatureFlag {
+ key: string
+ value_type: FeatureFlagValueType
+ value: JSONValue
+ description?: string
+}
+
+export interface UpdateAdminFeatureFlag {
+ value_type: FeatureFlagValueType
+ value: JSONValue
+ expected_version: number
+}
+
+export class AdminFeatureFlagError extends Error {
+ status: number
+ code: string
+ current?: AdminFeatureFlag
+
+ constructor(
+ status: number,
+ code: string,
+ message: string,
+ current?: AdminFeatureFlag,
+ ) {
+ super(message)
+ this.name = "AdminFeatureFlagError"
+ this.status = status
+ this.code = code
+ this.current = current
+ }
+}
+
+interface AdminFeatureFlagErrorResponse {
+ code?: string
+ message?: string
+ current?: AdminFeatureFlag
+}
+
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+ const token = await getToken()
+ const response = await fetch(path, {
+ ...init,
+ headers: {
+ Authorization: token ? `Bearer ${token}` : "",
+ "Content-Type": "application/json",
+ ...init?.headers,
+ },
+ })
+ if (!response.ok) {
+ const body = (await response.json().catch(() => ({}))) as AdminFeatureFlagErrorResponse
+ throw new AdminFeatureFlagError(
+ response.status,
+ body.code ?? "request_failed",
+ body.message ?? `feature flag request failed: ${response.status}`,
+ body.current,
+ )
+ }
+ if (response.status === 204) return undefined as T
+ return response.json() as Promise<T>
+}
+
+export const adminFeatureFlagsApi = {
+ list: () => request<AdminFeatureFlag[]>("/api/admin/feature-flags"),
+ create: (input: CreateAdminFeatureFlag) =>
+ request<AdminFeatureFlag>("/api/admin/feature-flags", {
+ method: "POST",
+ body: JSON.stringify(input),
+ }),
+ update: (key: string, input: UpdateAdminFeatureFlag) =>
+ request<AdminFeatureFlag>(`/api/admin/feature-flags/${encodeURIComponent(key)}`, {
+ method: "PUT",
+ body: JSON.stringify(input),
+ }),
+ remove: (key: string, expectedVersion: number) =>
+ request<void>(`/api/admin/feature-flags/${encodeURIComponent(key)}`, {
+ method: "DELETE",
+ body: JSON.stringify({ expected_version: expectedVersion }),
+ }),
+}
diff --git a/libs/fleet/src/sdk/featureFlags.ts b/libs/fleet/src/sdk/featureFlags.ts
index 697d21479c..a4f714b5e0 100644
--- a/libs/fleet/src/sdk/featureFlags.ts
+++ b/libs/fleet/src/sdk/featureFlags.ts
@@ -18,49 +18,69 @@ export interface FeatureFlags {
usage: boolean
}
-const DEFAULT_FLAGS: FeatureFlags = {
- admin: false,
- billing: false,
- chat: false,
- usage: false,
-}
+let cache: FeatureFlags | null = null
+let generation = 0
+let fetchPromise: { generation: number; promise: Promise<FeatureFlags> } | null = null
-let _cache: FeatureFlags | null = null
-let _fetchPromise: Promise<FeatureFlags> | null = null
+export async function fetchFeatureFlags(
+ options: { force?: boolean } = {},
+): Promise<FeatureFlags> {
+ if (options.force) {
+ cache = null
+ generation += 1
+ }
+ if (cache) return cache
+ if (fetchPromise?.generation === generation) return fetchPromise.promise
-export async function fetchFeatureFlags(): Promise<FeatureFlags> {
- if (_cache) return _cache
- if (_fetchPromise) return _fetchPromise
+ const requestGeneration = generation
+ const promise = (async () => {
+ const token = await getToken()
+ const response = await fetch("/api/config", {
+ headers: {
+ Authorization: token ? `Bearer ${token}` : "",
+ "Content-Type": "application/json",
+ },
+ })
+ if (!response.ok) {
+ throw new Error(`feature flag config request failed: ${response.status}`)
+ }
- _fetchPromise = (async () => {
- try {
- const token = await getToken()
- const res = await fetch("/api/config", {
- headers: {
- Authorization: token ? `Bearer ${token}` : "",
- "Content-Type": "application/json",
- },
- })
- if (!res.ok) return DEFAULT_FLAGS
- const data = (await res.json()) as FeatureFlags
- _cache = {
- admin: data.admin ?? false,
- billing: data.billing ?? false,
- chat: data.chat ?? false,
- usage: data.usage ?? false,
- }
- return _cache
- } catch {
- return DEFAULT_FLAGS
- } finally {
- _fetchPromise = null
+ const data = (await response.json()) as Partial<FeatureFlags>
+ if (!data || typeof data !== "object") {
+ throw new Error("feature flag config response must be an object")
+ }
+ const flags = {
+ admin: data.admin ?? false,
+ billing: data.billing ?? false,
+ chat: data.chat ?? false,
+ usage: data.usage ?? false,
}
+ if (
+ typeof flags.admin !== "boolean" ||
+ typeof flags.billing !== "boolean" ||
+ typeof flags.chat !== "boolean" ||
+ typeof flags.usage !== "boolean"
+ ) {
+ throw new Error("feature flag config response contains invalid values")
+ }
+ if (requestGeneration === generation) {
+ cache = flags
+ }
+ return flags
})()
- return _fetchPromise
+ fetchPromise = { generation: requestGeneration, promise }
+ try {
+ return await promise
+ } finally {
+ if (fetchPromise?.generation === requestGeneration) {
+ fetchPromise = null
+ }
+ }
}
/** Invalidate the cache (e.g., after login). */
export function invalidateFeatureFlags(): void {
- _cache = null
+ cache = null
+ generation += 1
}
diff --git a/libs/fleet/tests/nginx-config.test.mjs b/libs/fleet/tests/nginx-config.test.mjs
index 0ba691aa2e..0223aaeb9d 100644
--- a/libs/fleet/tests/nginx-config.test.mjs
+++ b/libs/fleet/tests/nginx-config.test.mjs
@@ -34,6 +34,11 @@ test("backend API nginx route includes GitHub trust policy endpoints", async ()
/\busage\b/,
"expected /api/usage to proxy to cyclops-cs-backend",
)
+ assert.match(
+ backendRoute[1],
+ /\badmin\b/,
+ "expected /api/admin/feature-flags to proxy to cyclops-cs-backend",
+ )
})
test("oauth2-proxy accepts Fleets GitHub WIF bearer tokens", async () => {