feat: dedicated least-privilege replication ACL user (#34)

Replicas authenticated to their primary as the full-access `default` user
(masterauth only). Seed a dedicated `replicator` ACL user instead — granting just
`+psync +replconf +ping` with no key access — and point replicas at it via
`masteruser`. A leaked replication credential can now do nothing but replicate,
not read or write your data. It mirrors the Sentinel user (S1) and the upstream
community operator's dedicated replication user.

Seeded in users.acl for every replicating topology (Replication, Cluster,
Sentinel); Standalone has no replica link and gets neither the user nor
masteruser. The operator's own control connections keep using the default user.

Two safety issues a cross-model (Grok) review surfaced are fixed here:

- Password rotation now re-keys the managed non-default users (replicator, and
  the Sentinel user) alongside default, additive-then-cutover. Without this,
  masteruser=replicator would WRONGPASS the moment a live rotation dropped the old
  password — a regression this change would otherwise introduce, and a pre-existing
  gap for the Sentinel user.
- `replicator` and `sentinel-user` are reserved: the ValkeyACL webhook rejects
  them and the reconciler never DELUSERs them, so a user-defined ACL can't wipe
  the credential the operator depends on.

Verified live on a dedicated k3d cluster (a Replication cluster's replicas link
as replicator, master_link_status:up, data replicates, no NOPERM) and with a
Docker harness for the rotation sequence (after a full add-new + cutover rotation,
a forced replica re-handshake re-authenticates as replicator under the new
password with no WRONGPASS). Unit tests cover the render/seed/masteruser scoping,
the reserved-name webhook rejections, and the managed-user set. Full envtest +
lint clean.

Author: melancholictheory

CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
 follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+- Replicas now authenticate to their primary as a dedicated, least-privilege ACL
+  user (`replicator`, granting only `+psync +replconf +ping` and no key access)
+  via `masteruser`, instead of the full-access default user, so a leaked
+  replication credential can neither read nor write data. It is seeded for every
+  replicating topology (all but Standalone). Password rotation re-keys it (and the
+  Sentinel user) in place, so an in-place rotation keeps the replica links alive.
+  The `replicator` and `sentinel-user` names are reserved and rejected by ValkeyACL.
+
 ## [0.6.0]
 
 ### Changed

internal/controller/failover.go

@@ -136,6 +136,23 @@ func (c *replClient) aclAddDefaultPassword(ctx context.Context, password string)
 	return c.rdb.Do(ctx, "ACL", "SETUSER", "default", ">"+password).Err()
 }
 
+// aclSetManagedUser re-keys an operator-managed non-default user (the replication
+// or Sentinel identity) during rotation, fully re-specifying its rules so the
+// call is correct even if the user was not yet present live (e.g. an upgrade that
+// added it). additive=true keeps the old password (ACL accepts old+new during the
+// transition); additive=false resets to only the new one at cutover.
+func (c *replClient) aclSetManagedUser(ctx context.Context, name, rules, password string, additive bool) error {
+	args := []any{"ACL", "SETUSER", name, "on"}
+	if !additive {
+		args = append(args, "resetpass")
+	}
+	args = append(args, ">"+password)
+	for tok := range strings.FieldsSeq(rules) {
+		args = append(args, tok)
+	}
+	return c.rdb.Do(ctx, args...).Err()
+}
+
 // aclSave persists the in-memory ACL to the configured aclfile (users.acl on
 // the data PVC). Without it the live `ACL SETUSER` is lost on the next pod
 // restart, which reloads the old password from the on-disk aclfile.

internal/controller/password_rotation.go

@@ -158,11 +158,21 @@ func (r *ValkeyClusterReconciler) applyPasswordToPods(ctx context.Context, vc *c
 		return nil
 	}
 
+	// Operator-managed non-default users (replication / Sentinel) carry the same
+	// password and must be re-keyed alongside default, or the replica links
+	// (masteruser=replicator) and Sentinel break the moment the old password drops.
+	managed := managedNonDefaultUsers(vc)
+
 	// Pass 1: every node accepts old AND new; replicas adopt the new masterauth.
 	if err := onEachPod("add-new", func(c *replClient) error {
 		if err := c.aclAddDefaultPassword(ctx, newPw); err != nil {
 			return err
 		}
+		for _, u := range managed {
+			if err := c.aclSetManagedUser(ctx, u.name, u.rules, newPw, true); err != nil {
+				return err
+			}
+		}
 		return c.configSet(ctx, "masterauth", newPw)
 	}); err != nil {
 		return err
@@ -173,6 +183,11 @@ func (r *ValkeyClusterReconciler) applyPasswordToPods(ctx context.Context, vc *c
 		if err := c.aclSetDefaultPassword(ctx, newPw); err != nil {
 			return err
 		}
+		for _, u := range managed {
+			if err := c.aclSetManagedUser(ctx, u.name, u.rules, newPw, false); err != nil {
+				return err
+			}
+		}
 		if err := c.configSet(ctx, "requirepass", newPw); err != nil {
 			return err
 		}

internal/controller/resources.go

@@ -405,11 +405,7 @@ func renderValkeyConf(vc *cachev1beta1.ValkeyCluster, password string) string {
 	fmt.Fprintf(&b, "bind 0.0.0.0\n")
 	fmt.Fprintf(&b, "protected-mode no\n")
 	fmt.Fprintf(&b, "dir %s\n", dataMountPath)
-	if password != "" {
-		quotedPassword := valkeyConfigArg(password)
-		fmt.Fprintf(&b, "requirepass %s\n", quotedPassword)
-		fmt.Fprintf(&b, "masterauth %s\n", quotedPassword)
-	}
+	renderAuthConfig(&b, vc, password)
 
 	// Persist ACL state on the data PVC so users survive pod restarts.
 	// `ACL SAVE` (called by ValkeyACLReconciler) writes here; Valkey loads
@@ -664,9 +660,25 @@ func renderInitScript(vc *cachev1beta1.ValkeyCluster) string {
 		sentinelReseed = fmt.Sprintf("    echo \"user %s on #$PW_HASH &* %s\" >> %s/users.acl.new\n",
 			sentinelACLUser, sentinelACLCommands, dataMountPath)
 	}
+	// Every replicating topology (all but Standalone) also seeds the dedicated
+	// replication user a replica authenticates as (masteruser) — minimal commands,
+	// no key glob, so it is far less exposed than the default user.
+	replSeed, replReseed := "", ""
+	if topologyReplicates(vc) {
+		replSeed = fmt.Sprintf("    echo \"user %s on #$PW_HASH %s\" >> %s/users.acl\n",
+			replicationACLUser, replicationACLCommands, dataMountPath)
+		replReseed = fmt.Sprintf("    echo \"user %s on #$PW_HASH %s\" >> %s/users.acl.new\n",
+			replicationACLUser, replicationACLCommands, dataMountPath)
+	}
+	managedSeed := sentinelSeed + replSeed
+	managedReseed := sentinelReseed + replReseed
+	// Extra operator-managed user names for the reseed grep (the template already
+	// lists `default`). Listing a user that isn't in the file is harmless.
+	managedUsersRe := fmt.Sprintf("%s|%s", sentinelACLUser, replicationACLUser)
 	// users.acl seeding. Valkey applies `requirepass` first, then loads the
 	// aclfile, and the aclfile is authoritative — so the operator-managed users
-	// (default, plus the Sentinel user) carry the password as a SHA-256 hash here.
+	// (default, plus the Sentinel and replication users) carry the password as a
+	// SHA-256 hash here.
 	// When the password changes (e.g. a rotated auth.existingSecret, which
 	// re-renders requirepass and rolls the pods) the seeded hash no longer matches,
 	// so we rewrite ONLY the operator-managed user lines and preserve any other
@@ -700,7 +712,7 @@ valkey_config_arg() {
     END { printf "\"\n" }
   '
 }
-	`, configMountPath, dataMountPath, sentinelSeed, sentinelReseed, sentinelACLUser)
+	`, configMountPath, dataMountPath, managedSeed, managedReseed, managedUsersRe)
 
 	// Multi-region: every pod (including pod-0) replicates from an external
 	// primary. Local primary/replica entrypoint logic is bypassed.
@@ -1406,6 +1418,59 @@ func tlsEnabled(vc *cachev1beta1.ValkeyCluster) bool {
 	return vc.Spec.TLS != nil && vc.Spec.TLS.Enabled
 }
 
+// topologyReplicates reports whether the topology has replicas that connect to a
+// primary (so a dedicated replication user is worth seeding). Standalone is the
+// only topology with no replication link.
+func topologyReplicates(vc *cachev1beta1.ValkeyCluster) bool {
+	return vc.Spec.Topology != cachev1beta1.TopologyStandalone
+}
+
+// isReservedACLUser reports whether an ACL user is operator-managed (the default
+// user plus the dedicated Sentinel and replication identities) and so must never
+// be dropped by the ValkeyACL reconciler. The webhook rejects the same names.
+func isReservedACLUser(name string) bool {
+	return name == "default" || name == sentinelACLUser || name == replicationACLUser
+}
+
+// managedACLUser is an operator-seeded non-default ACL user plus the ACL rules
+// (channels + commands) that define it.
+type managedACLUser struct {
+	name  string
+	rules string
+}
+
+// managedNonDefaultUsers returns the operator-managed ACL users (besides default)
+// this topology seeds, so password rotation can re-key them along with default.
+// Their password always matches the cluster auth password; leaving them stale
+// after a rotation would break the replica links (masteruser) and Sentinel.
+func managedNonDefaultUsers(vc *cachev1beta1.ValkeyCluster) []managedACLUser {
+	var users []managedACLUser
+	if topologyReplicates(vc) {
+		users = append(users, managedACLUser{replicationACLUser, replicationACLCommands})
+	}
+	if vc.Spec.Topology == cachev1beta1.TopologySentinel {
+		users = append(users, managedACLUser{sentinelACLUser, "&* " + sentinelACLCommands})
+	}
+	return users
+}
+
+// renderAuthConfig writes the auth directives into valkey.conf. Replicas
+// authenticate to their primary as the dedicated, least-privilege replication
+// user (seeded in users.acl by renderInitScript) rather than the full-access
+// default user; only replicating topologies need it, and the operator's own
+// control connections keep using the default user.
+func renderAuthConfig(b *strings.Builder, vc *cachev1beta1.ValkeyCluster, password string) {
+	if password == "" {
+		return
+	}
+	quotedPassword := valkeyConfigArg(password)
+	fmt.Fprintf(b, "requirepass %s\n", quotedPassword)
+	fmt.Fprintf(b, "masterauth %s\n", quotedPassword)
+	if topologyReplicates(vc) {
+		fmt.Fprintf(b, "masteruser %s\n", replicationACLUser)
+	}
+}
+
 // sourceCAMergeEnabled reports whether this cluster pulls from an external TLS
 // primary signed by a separate CA (S4). When true the operator merges that CA
 // with the local cluster CA into one trust bundle, because Valkey reads a single

internal/controller/resources_test.go

@@ -1572,21 +1572,109 @@ func TestRenderInitScriptReseedsDefaultUserOnPasswordChange(t *testing.T) {
 	std.Spec.Auth = &cachev1beta1.AuthSpec{Enabled: true}
 	s := renderInitScript(std)
 	for _, want := range []string{
-		`grep -q "^user default on #$PW_HASH "`,     // re-seed unless the line already carries the new hash
-		`grep -vE "^user (default|sentinel-user) "`, // preserve other ACL users while replacing operator-managed ones
-		dataMountPath + "/users.acl.new",            // rewrite via a temp file
+		`grep -q "^user default on #$PW_HASH "`,                // re-seed unless the line already carries the new hash
+		`grep -vE "^user (default|sentinel-user|replicator) "`, // preserve other ACL users while replacing operator-managed ones
+		dataMountPath + "/users.acl.new",                       // rewrite via a temp file
 	} {
 		if !strings.Contains(s, want) {
 			t.Errorf("init script missing re-seed-on-change logic %q\n%s", want, s)
 		}
 	}
+	// A replicating topology (minimalCR is Replication) re-seeds the replication
+	// user on a password change too.
+	if !strings.Contains(s, `echo "user replicator on #$PW_HASH `+replicationACLCommands+`" >> `+dataMountPath+"/users.acl.new") {
+		t.Errorf("init must re-seed the replication ACL user on a password change\n%s", s)
+	}
 	// Sentinel must re-seed its dedicated ACL user too; it also carries the password.
 	sen := renderInitScript(sentinelCR())
 	if !strings.Contains(sen, `echo "user sentinel-user on #$PW_HASH &* `+sentinelACLCommands+`" >> `+dataMountPath+"/users.acl.new") {
 		t.Errorf("sentinel init must re-seed the sentinel ACL user on a password change\n%s", sen)
 	}
 }
 
+// The dedicated replication user is seeded and wired as masteruser for every
+// replicating topology (not Standalone), least-privilege vs the default user.
+func TestRenderReplicationUser(t *testing.T) {
+	mk := func(topo cachev1beta1.Topology) *cachev1beta1.ValkeyCluster {
+		vc := minimalCR()
+		vc.Spec.Topology = topo
+		vc.Spec.Auth = &cachev1beta1.AuthSpec{Enabled: true}
+		if topo == cachev1beta1.TopologyCluster {
+			vc.Spec.Shards = ptr.To[int32](3)
+		}
+		if topo == cachev1beta1.TopologySentinel {
+			vc.Spec.Sentinel = &cachev1beta1.SentinelSpec{Replicas: 3}
+		}
+		return vc
+	}
+	seedLine := `echo "user replicator on #$PW_HASH ` + replicationACLCommands + `"`
+
+	for _, topo := range []cachev1beta1.Topology{
+		cachev1beta1.TopologyReplication, cachev1beta1.TopologyCluster, cachev1beta1.TopologySentinel,
+	} {
+		vc := mk(topo)
+		conf := renderValkeyConf(vc, "secret")
+		if !strings.Contains(conf, "masteruser replicator") {
+			t.Errorf("%s: valkey.conf must set masteruser replicator\n%s", topo, conf)
+		}
+		if s := renderInitScript(vc); !strings.Contains(s, seedLine) {
+			t.Errorf("%s: init must seed the replication user\n%s", topo, s)
+		}
+	}
+
+	// Standalone has no replicas: no replication user, no masteruser.
+	std := mk(cachev1beta1.TopologyStandalone)
+	conf := renderValkeyConf(std, "secret")
+	if strings.Contains(conf, "masteruser") {
+		t.Errorf("Standalone must not set masteruser\n%s", conf)
+	}
+	if s := renderInitScript(std); strings.Contains(s, "user replicator") {
+		t.Errorf("Standalone must not seed the replication user\n%s", s)
+	}
+	// The replication user carries NO key glob (no data access).
+	if strings.Contains(seedLine, "~*") {
+		t.Error("replication user must not be granted key access")
+	}
+}
+
+// managedNonDefaultUsers drives which users password rotation re-keys, and
+// isReservedACLUser protects them from the ValkeyACL reconciler.
+func TestManagedNonDefaultUsersAndReserved(t *testing.T) {
+	rep := minimalCR() // Replication
+	if got := managedNonDefaultUsers(rep); len(got) != 1 ||
+		got[0].name != replicationACLUser || got[0].rules != replicationACLCommands {
+		t.Fatalf("Replication managed users = %+v", got)
+	}
+
+	sen := minimalCR()
+	sen.Spec.Topology = cachev1beta1.TopologySentinel
+	rules := map[string]string{}
+	for _, u := range managedNonDefaultUsers(sen) {
+		rules[u.name] = u.rules
+	}
+	if _, ok := rules[replicationACLUser]; !ok {
+		t.Error("Sentinel must still re-key the replication user")
+	}
+	if r := rules[sentinelACLUser]; !strings.HasPrefix(r, "&* ") {
+		t.Errorf("sentinel-user rules must keep the channel glob: %q", r)
+	}
+
+	std := minimalCR()
+	std.Spec.Topology = cachev1beta1.TopologyStandalone
+	if got := managedNonDefaultUsers(std); len(got) != 0 {
+		t.Fatalf("Standalone must have no managed non-default users, got %+v", got)
+	}
+
+	for _, n := range []string{"default", replicationACLUser, sentinelACLUser} {
+		if !isReservedACLUser(n) {
+			t.Errorf("%q must be reserved", n)
+		}
+	}
+	if isReservedACLUser("alice") {
+		t.Error("a user-defined name must not be reserved")
+	}
+}
+
 func TestRenderInitScriptIsValidShell(t *testing.T) {
 	std := minimalCR()
 	std.Spec.Auth = &cachev1beta1.AuthSpec{Enabled: true}

internal/controller/sentinel.go

@@ -40,6 +40,16 @@ const (
 	// user can never read or write your data.
 	sentinelACLCommands = "+multi +slaveof +ping +exec +subscribe " +
 		"+config|rewrite +role +publish +info +client|setname +client|kill +script|kill"
+	// replicationACLUser is the dedicated ACL user a REPLICA authenticates as when
+	// it connects to its primary (masteruser/masterauth), instead of the
+	// full-access default user. If the replication credential ever leaks it can do
+	// nothing but replicate: no key access, no arbitrary commands.
+	replicationACLUser = "replicator"
+	// replicationACLCommands is the minimal set a replica needs on its primary:
+	// PSYNC to start/continue the replication stream, REPLCONF for the handshake
+	// and ACKs, and PING for keepalive. The stream itself is not ACL-checked per
+	// key, so no key glob is granted.
+	replicationACLCommands = "+psync +replconf +ping"
 )
 
 // reconcileSentinel brings up Replication primitives plus a separate

internal/controller/valkeyacl_controller.go

@@ -201,7 +201,7 @@ func (r *ValkeyACLReconciler) applyACLFanout(
 			}
 		}
 		for _, prev := range acl.Status.AppliedUsers {
-			if _, keep := desiredNames[prev]; keep || prev == "default" {
+			if _, keep := desiredNames[prev]; keep || isReservedACLUser(prev) {
 				continue
 			}
 			if err := c.rdb.Do(ctx, "ACL", "DELUSER", prev).Err(); err != nil {

internal/webhook/v1beta1/validators_test.go

@@ -330,6 +330,22 @@ func TestValkeyACLValidator(t *testing.T) {
 			objs:    []client.Object{cluster},
 			wantErr: true,
 		},
+		{
+			name: "reserved replication user -> error",
+			mutate: func(a *cachev1beta1.ValkeyACL) {
+				a.Spec.Users = []cachev1beta1.ValkeyACLUser{{Name: "replicator"}}
+			},
+			objs:    []client.Object{cluster},
+			wantErr: true,
+		},
+		{
+			name: "reserved sentinel user -> error",
+			mutate: func(a *cachev1beta1.ValkeyACL) {
+				a.Spec.Users = []cachev1beta1.ValkeyACLUser{{Name: "sentinel-user"}}
+			},
+			objs:    []client.Object{cluster},
+			wantErr: true,
+		},
 		{
 			name: "user passwordSecret missing -> error",
 			mutate: func(a *cachev1beta1.ValkeyACL) {

internal/webhook/v1beta1/valkeyacl_webhook.go

@@ -75,8 +75,12 @@ func (v *ValkeyACLCustomValidator) validate(ctx context.Context, acl *cachev1bet
 			return nil, fmt.Errorf("duplicate user %q in spec.users", u.Name)
 		}
 		seen[u.Name] = struct{}{}
-		if u.Name == "default" {
-			return nil, fmt.Errorf("user %q is reserved and cannot be managed via ValkeyACL", u.Name)
+		// Reserved by the operator: the default user plus the dedicated Sentinel
+		// (sentinel-user) and replication (replicator) identities it seeds itself.
+		// Managing these via ValkeyACL would let a reset/DELUSER wipe the credential
+		// the operator's own connections depend on.
+		if u.Name == "default" || u.Name == "sentinel-user" || u.Name == "replicator" {
+			return nil, fmt.Errorf("user %q is reserved by the operator and cannot be managed via ValkeyACL", u.Name)
 		}
 	}