feat(operator): make any Paper image joinable behind the forwarding proxy

Velocity modern forwarding is proxy-WIDE. A backend that cannot verify the signed
handshake does not degrade -- it rejects every login the proxy forwards. Until now the
only backends that could verify it were the two images Felis builds itself
(deploy/limbo, deploy/lobby), which read FELIS_FORWARDING_SECRET in their own
entrypoints. An arbitrary Paper image a user brings does not, so it passed admission,
started, reported Ready, and was UNJOINABLE. The platform's answer was to recommend the
lobby image as a base for a user's own world (0018_recommended_images.sql), which was
never a good base -- it carries the /menu plugin whose job is to TRANSFER a joining
player away, the exact opposite of a server you mean to stay on.

The fix configures forwarding from OUTSIDE the image instead of requiring it inside.
The operator now injects a root `felis init-forwarding` initContainer into every user
server; it writes the proxies.velocity block into config/paper-global.yml and forces
online-mode=false in server.properties on the /data PVC before the main container
starts. The image needs no forwarding logic of its own, so the joinable set stops being
"images that self-configure forwarding" and becomes every Paper-family image the
platform runs.

buildStatefulSet gates the injection on the ABSENCE of the system-role label: the
Felis-built system servers already consume the secret in their entrypoints and the
login gate is a limbo, not Paper. It is also gated on a non-empty felis image name --
the operator Deployment passes its own image as FELIS_IMAGE, and an operator without it
skips the injection rather than failing, because a cluster whose proxy is not in modern
mode has nothing to configure.

The init runs as root deliberately. The world volume's ownership comes from the storage
provisioner and the main container runs as whatever UID its image declares, so root is
the only UID that can reliably write these files; it then chmods them 0666/0777 so that
non-root main container can rewrite them on boot. The privilege is bounded -- the init
exits before the server container starts and the server container keeps its own UID.
The alternative, an fsGroup on the pod, is noted in the code as the upgrade path if the
init ever stops running as root.

The writer merges rather than overwrites, both because Paper expands paper-global.yml to
its full default tree on first boot and because the panel file editor may edit either
file between boots. It sets proxies.velocity.* and the single online-mode key and leaves
every other setting alone. It is a no-op on an empty secret, for the same reason the env
var is optional: a proxy that is not in modern mode provisions no Secret, and wedging
every server's init on a missing optional value would be worse than the status quo.

felis-paper (deploy/paper) is the platform's plain-Paper expression of that base and
0019 seeds it recommended: same PAPER_JAR_URL the lobby build already resolves, no /menu
plugin, no forwarding gate, and a correctly-escaped RCON channel so the console, the
online-player list and permission commands work out of the box. 0018's row is left in
place -- an admin who kept it can keep it; this only adds the better default beside it.

Three fixes ride along, each of which the 1.8 path hit in practice.

bootstrap pins ViaVersion's serverside-blockconnections off. ConnectionData.init() only
builds its block-connection provider when Via's lowest supported protocol is below 1.13;
under modern forwarding the Velocity injector reports 393, so init() returns early,
blockConnectionProvider stays null, and the first 1.12.2->1.13 chunk rewrite dereferences
it -- a 1.8 client takes an NPE on the first chunk it is sent and never finishes joining.
Every call site is behind isServersideBlockConnections(), so switching it off skips all
of them, at a cosmetic pre-1.13 cost: fences and glass panes stop drawing connected.
ViaVersion ships the option ON, so a fresh install shipped that NPE. Seeding a file with
this one key suffices -- Config#loadConfig parses the bundled default as the base map and
merges the on-disk file over it, so every other option stays current across version
bumps. The absence of "Loading block connection mappings" in the log is NOT evidence this
worked: init() gates on the protocol version too, and that half fails on its own, so the
line is missing either way. The config value is the only evidence, which is what the test
asserts.

The Velocity unit gains -Dfelis.legacy-forwarding.servers=legacy18. A protocol-47 backend
sits behind ViaVersion, which strips modern forwarding's login-plugin-message when it
down-translates the proxy->backend pipeline to 47 -- the packet is registered from 1.13
and has nowhere to go. Only the handshake address field survives Via, so the Felis fork
forwards the named servers BungeeCord-style while every other backend keeps modern+secret
untouched. v1 hardcodes the one legacy backend; rendering the list from the MinecraftServer
CRs is the upgrade path.

deploy/lobby's set_prop escapes the value before substituting it. The RCON password is
operator-provisioned arbitrary bytes, and a '|', '\' or '&' in one corrupts a bare
`sed s|...|...|` and silently kills the key -- taking the console, the online-player list
and permission commands with it. deploy/paper was written with the escaping, so the lobby
gets the same rather than leaving the sibling caller broken.

Verified: the full Go suite passes on Windows and on Fedora 44 (go1.26.4), where
TestWriteForwardingFileModes actually runs its POSIX mode assertions instead of skipping.
The new tests cover the initContainer's image, root UID, world mount and secret env; the
merge preserving unrelated config trees; the properties upsert including the commented-key
case; and the bootstrap script both writing the Via key and still calling the function
that writes it.

Not verified: the initContainer has never run in a real cluster, and the felis-paper
image is code-only here as the other game-stack images are -- no Go CI builds them.

The ViaVersion pin is the one piece with live evidence, and that evidence is what it was
written from. Before it, a client was cut within a second of "logged in with entity id"
on legacy18 while the proxy logged the NPE above -- REMAP OF LEVEL_CHUNK chained into
Protocol1_8To1_9's MAP_BULK_CHUNK. It was applied by hand to the running proxy on
2026-07-24 at 14:47 and only then written back into bootstrap. At 14:48:14 the same
player joined real Paper 1.8.8 through the fork, issued commands, approved an op-login
from in-game at 14:50:39, and held the connection until 15:30:09 -- 42 minutes.

Neither session says which client version it was. The proxy never logged a protocol
number. It bounds above at 1.16.4, from the viabackwards "(1.17->1.16.4) ... for 1.16
players and below" warning that fired for that player on the lobby leg, and no lower --
Via floors every handshake to the proxy's 393, so anything from 47 up is admissible.
Reading Protocol1_8To1_9 in the stack as a client-version tell is backwards: that chain
runs on the BACKEND leg, up-translating the 47 server's chunks to the floor. What the
NPE proves is that the pin was load-bearing, not who was holding the mouse.

That is one hand-run session on one host, and it is not a cell. The 393->47 leg has one
now, in Felis-Legacy -- FL-009 puts a genuine protocol-47 client on a stock Paper 1.8.8
behind this proxy and flips this same option: on it, cut 0.2s after JoinGame with the
fault above; off, holds. No automated test in THIS repository exercises the leg.

internal/operator/builders.go

@@ -40,6 +40,11 @@ const (
 	dataVolumeName = "world"
 	dataMountPath  = "/data"
 
+	// felisBinaryPath is where the felis image installs its binary; the
+	// forwarding-config initContainer invokes it by absolute path (matches
+	// platform.felisBinaryPath — the same image, the same install location).
+	felisBinaryPath = "/usr/local/bin/felis"
+
 	// ManagedByValue / ComponentValue are the values of the LabelManagedBy /
 	// LabelComponent labels stamped on every per-server pod (see labelsFor). They
 	// are exported because the platform package's minecraft-namespace
@@ -184,7 +189,7 @@ func readinessProbe(server *v1alpha1.MinecraftServer) *corev1.Probe {
 // buildStatefulSet renders the workload for replicas in {0,1}. It is where
 // graceful shutdown is injected: the pod gets terminationGracePeriodSeconds and
 // (when enabled) a preStop RCON save+stop hook.
-func buildStatefulSet(server *v1alpha1.MinecraftServer, replicas int32) (*appsv1.StatefulSet, error) {
+func buildStatefulSet(server *v1alpha1.MinecraftServer, replicas int32, felisImage string) (*appsv1.StatefulSet, error) {
 	storageSize := server.Spec.Storage.Size
 	if storageSize == "" {
 		storageSize = defaultStorageSize
@@ -235,6 +240,15 @@ func buildStatefulSet(server *v1alpha1.MinecraftServer, replicas int32) (*appsv1
 		}
 	}
 
+	// An arbitrary user Paper image does not consume FELIS_FORWARDING_SECRET, so the
+	// operator writes the forwarding config into the world volume for it via an
+	// initContainer. System servers (login/lobby) are Felis-built and handle it in
+	// their own entrypoints, and without a felis image name there is nothing to run.
+	var initContainers []corev1.Container
+	if felisImage != "" && server.Labels[v1alpha1.LabelSystemRole] == "" {
+		initContainers = append(initContainers, forwardingInitContainer(felisImage))
+	}
+
 	grace := graceSeconds(server)
 	pvc := corev1.PersistentVolumeClaim{
 		ObjectMeta: metav1.ObjectMeta{Name: dataVolumeName},
@@ -263,6 +277,7 @@ func buildStatefulSet(server *v1alpha1.MinecraftServer, replicas int32) (*appsv1
 				ObjectMeta: metav1.ObjectMeta{Labels: labelsFor(server)},
 				Spec: corev1.PodSpec{
 					TerminationGracePeriodSeconds: &grace,
+					InitContainers:                initContainers,
 					Containers:                    []corev1.Container{container},
 					// A Minecraft server runs untrusted user worlds and plugins and
 					// has no business calling the K8s API, so its pod must NOT carry the
@@ -335,12 +350,22 @@ func buildEnv(server *v1alpha1.MinecraftServer) []corev1.EnvVar {
 	// the player's UUID is Mojang-verified, not offline-derived) — the pod-level fence
 	// against bypassing the proxy is the NetworkPolicy, not this value's secrecy.
 	//
-	// A user server is built from an operator-typed Dockerfile, so Felis cannot make it
-	// consume this; the two images Felis does build (deploy/limbo, deploy/lobby) read it
-	// in their entrypoints and refuse to start without it. Optional so a cluster whose
-	// proxy is not in modern mode — no Secret provisioned — still schedules its pods
-	// instead of wedging them all in CreateContainerConfigError.
-	env = append(env, corev1.EnvVar{
+	// The Felis-built images (deploy/limbo, deploy/lobby) read this in their
+	// entrypoints. An arbitrary user Paper image does NOT — so the operator also runs
+	// a forwarding-config initContainer (see forwardingInitContainer) that writes the
+	// Velocity block into the shared world volume before the server starts, making a
+	// stock Paper image joinable without modifying it.
+	env = append(env, forwardingSecretEnvVar())
+	return env
+}
+
+// forwardingSecretEnvVar sources FELIS_FORWARDING_SECRET from the Secret the setup
+// provisioner replicas into this namespace. Optional so a cluster whose proxy is
+// not in modern mode — no Secret provisioned — still schedules its pods instead of
+// wedging them all in CreateContainerConfigError; the init and lobby/limbo
+// entrypoints treat an empty value as "not in modern mode" and leave config alone.
+func forwardingSecretEnvVar() corev1.EnvVar {
+	return corev1.EnvVar{
 		Name: envForwardingSecret,
 		ValueFrom: &corev1.EnvVarSource{
 			SecretKeyRef: &corev1.SecretKeySelector{
@@ -349,12 +374,43 @@ func buildEnv(server *v1alpha1.MinecraftServer) []corev1.EnvVar {
 				Optional:             boolPtr(true),
 			},
 		},
-	})
-	return env
+	}
+}
+
+// forwardingInitContainer writes Velocity modern-forwarding config into the shared
+// world volume before the server container starts, so an arbitrary Paper image Felis
+// did NOT build becomes joinable behind the proxy without being modified. It runs the
+// felis image's `init-forwarding` subcommand, which merges the proxies.velocity block
+// into config/paper-global.yml and forces online-mode=false in server.properties.
+//
+// It runs as root: the world volume's ownership is set by the storage provisioner and
+// the main container runs as the user image's own UID, so root is the only UID that
+// can reliably write these files and leave them rewritable by that main container.
+// This is a bounded privilege — the init exits before the server container starts, and
+// the server container keeps whatever (non-root) UID its image declares.
+//
+// Only user servers get it: the Felis-built system images (login limbo, lobby) already
+// consume the secret in their own entrypoints, and the login limbo is not Paper at all.
+func forwardingInitContainer(felisImage string) corev1.Container {
+	return corev1.Container{
+		Name:    "init-forwarding",
+		Image:   felisImage,
+		Command: []string{felisBinaryPath, "init-forwarding"},
+		Env:     []corev1.EnvVar{forwardingSecretEnvVar()},
+		VolumeMounts: []corev1.VolumeMount{
+			{Name: dataVolumeName, MountPath: dataMountPath},
+		},
+		SecurityContext: &corev1.SecurityContext{
+			RunAsUser:    int64Ptr(0),
+			RunAsNonRoot: boolPtr(false),
+		},
+	}
 }
 
 func boolPtr(b bool) *bool { return &b }
 
+func int64Ptr(i int64) *int64 { return &i }
+
 func joinFlags(flags []string) string {
 	out := ""
 	for i, f := range flags {

internal/operator/builders_internal_test.go

@@ -56,13 +56,76 @@ func TestReadinessProbeHTTPCustomPath(t *testing.T) {
 	}
 }
 
+// A user server (no system-role label) gets the forwarding-config initContainer,
+// running the felis image as root and mounting the world volume. A system server
+// and a build with no felis image name get none.
+func TestBuildStatefulSetForwardingInitContainer(t *testing.T) {
+	user := &v1alpha1.MinecraftServer{}
+	user.Spec.Storage.Size = "1Gi"
+
+	sts, err := buildStatefulSet(user, 1, "felis:demo")
+	if err != nil {
+		t.Fatalf("buildStatefulSet: %v", err)
+	}
+	inits := sts.Spec.Template.Spec.InitContainers
+	if len(inits) != 1 {
+		t.Fatalf("want 1 initContainer, got %d", len(inits))
+	}
+	ic := inits[0]
+	if ic.Image != "felis:demo" {
+		t.Errorf("init image = %q, want felis:demo", ic.Image)
+	}
+	if ic.SecurityContext == nil || ic.SecurityContext.RunAsUser == nil || *ic.SecurityContext.RunAsUser != 0 {
+		t.Errorf("init must run as root, got %+v", ic.SecurityContext)
+	}
+	mounted := false
+	for _, vm := range ic.VolumeMounts {
+		if vm.Name == dataVolumeName && vm.MountPath == dataMountPath {
+			mounted = true
+		}
+	}
+	if !mounted {
+		t.Errorf("init must mount the world volume at %s, got %+v", dataMountPath, ic.VolumeMounts)
+	}
+	// The whole point of the initContainer is to write the forwarding config, which it
+	// cannot do without the secret: a missing Env here makes `init-forwarding` no-op and
+	// the server Ready-but-unjoinable — the exact silent failure the feature removes.
+	// Same secretKeyRef rule as the main container (optional so a non-modern proxy still
+	// schedules), so assert it, not just the image/root/mount above.
+	fwd := findEnv(ic.Env, envForwardingSecret)
+	if fwd == nil {
+		t.Fatalf("init must carry %s or it writes no forwarding config", envForwardingSecret)
+	}
+	if fwd.ValueFrom == nil || fwd.ValueFrom.SecretKeyRef == nil {
+		t.Fatalf("%s on init must be a secretKeyRef, got %+v", envForwardingSecret, fwd)
+	}
+	if ref := fwd.ValueFrom.SecretKeyRef; ref.Name != naming.ForwardingSecretName || ref.Key != naming.ForwardingSecretKey {
+		t.Errorf("init %s secretKeyRef = %s/%s, want %s/%s", envForwardingSecret, ref.Name, ref.Key, naming.ForwardingSecretName, naming.ForwardingSecretKey)
+	}
+
+	// No felis image name → nothing to run.
+	noImg, _ := buildStatefulSet(user, 1, "")
+	if len(noImg.Spec.Template.Spec.InitContainers) != 0 {
+		t.Error("no felis image must yield no initContainer")
+	}
+
+	// System server handles forwarding in its own entrypoint.
+	sys := &v1alpha1.MinecraftServer{}
+	sys.Spec.Storage.Size = "1Gi"
+	sys.Labels = map[string]string{v1alpha1.LabelSystemRole: "lobby"}
+	sysSts, _ := buildStatefulSet(sys, 1, "felis:demo")
+	if len(sysSts.Spec.Template.Spec.InitContainers) != 0 {
+		t.Error("system server must get no forwarding initContainer")
+	}
+}
+
 // A server with a health port also exposes it as a named container port so the
 // kubelet can reach it.
 func TestBuildStatefulSetAddsHealthPort(t *testing.T) {
 	s := &v1alpha1.MinecraftServer{}
 	s.Spec.Storage.Size = "1Gi"
 	s.Spec.Startup.HealthHTTPPort = 8080
-	sts, err := buildStatefulSet(s, 1)
+	sts, err := buildStatefulSet(s, 1, "")
 	if err != nil {
 		t.Fatalf("buildStatefulSet: %v", err)
 	}

internal/operator/reconciler.go

@@ -40,6 +40,10 @@ type Reconciler struct {
 	Scheme *runtime.Scheme
 	// Prober gates readiness on RCON reachability.
 	Prober Prober
+	// FelisImage is this operator's own image, used for the forwarding-config
+	// initContainer injected into user servers. Empty (an operator Deployment
+	// without FELIS_IMAGE) disables that injection rather than failing.
+	FelisImage string
 	// Now is injectable for deterministic timestamps in tests; defaults to
 	// metav1.Now.
 	Now func() metav1.Time
@@ -98,7 +102,7 @@ func (r *Reconciler) reconcileRunning(ctx context.Context, server *v1alpha1.Mine
 		return ctrl.Result{RequeueAfter: requeueSecret}, nil
 	}
 
-	desired, err := buildStatefulSet(server, 1)
+	desired, err := buildStatefulSet(server, 1, r.FelisImage)
 	if err != nil {
 		// A malformed spec (e.g. bad storage quantity) is terminal until edited.
 		r.markFailed(server, "InvalidSpec", err.Error())