fix: cross-env validation and docs for renderer password (#3090)

## Summary

Addresses all three follow-up items from PR #2829:

- **Ruby-side NODE_ENV checking**:
`validate_renderer_password_for_production` now checks both `RAILS_ENV`
and `NODE_ENV`, mirroring the Node-side
`runtimeEnvsAllowDevelopmentDefaults()`. Surfaces misconfigurations
(e.g. `NODE_ENV=production` + `RAILS_ENV=development`) at Rails boot
time instead of at Node request time.
- **Clarifying comment**: Added comment to
`defaultReplayServerAsyncOperationLogs()` explaining the intentional
asymmetry — it only checks `NODE_ENV` because async log replay is a JS
debugging concern, not a security boundary.
- **Unconditional validator call**: Moved
`validate_renderer_password_for_production` from inside
`setup_renderer_password` to `setup_config_values`, making enforcement
unconditional and resilient to future refactors of the password
resolution logic.

Closes #2887

## Test plan

- [x] All 51 Ruby configuration specs pass (including 4 new cross-env
tests)
- [x] All 31 Node renderer configBuilder tests pass
- [x] RuboCop clean
- [x] ESLint + Prettier clean
- [ ] CI passes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Tightens production-like startup validation for the Node renderer
password, which can cause previously misconfigured deployments to fail
fast at Rails boot. Changes are localized to configuration/validation
paths with expanded spec coverage.
> 
> **Overview**
> Ensures `RENDERER_PASSWORD` enforcement is **fail-closed and
consistent across Ruby and Node** by validating against both `RAILS_ENV`
and `NODE_ENV`, including rejecting mixed-env setups (e.g.
`NODE_ENV=production` + `RAILS_ENV=development`).
> 
> Moves `validate_renderer_password_for_production` to run
unconditionally during Rails `setup_config_values`, updates the error
message docs/matrix accordingly, and expands Ruby specs to cover the new
cross-env scenarios.
> 
> Adds a clarifying comment in the Node `configBuilder` that
`defaultReplayServerAsyncOperationLogs()` intentionally keys only off
`NODE_ENV` (debugging behavior, not a security boundary).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
5a01f45. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Strengthened production validation for the Node renderer to prevent
misconfiguration in mixed or production envs.

* **Documentation**
* Clarified default server operation logging behavior and updated
environment-related messaging.

* **Tests**
* Expanded test coverage for environment-variable combinations to ensure
consistent behavior across deployment and development scenarios.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justin808

packages/react-on-rails-pro-node-renderer/src/shared/configBuilder.ts

@@ -163,6 +163,10 @@ function runtimeEnvsAllowDevelopmentDefaults() {
   return runtimeEnvs.length > 0 && runtimeEnvs.every((value) => value === 'development' || value === 'test');
 }
 
+// Intentionally checks only NODE_ENV, not both NODE_ENV and RAILS_ENV like
+// runtimeEnvsAllowDevelopmentDefaults(). Async operation log replay is a JS
+// debugging concern, not a security boundary — it should key off the JS
+// runtime environment alone.
 function defaultReplayServerAsyncOperationLogs() {
   if (env.REPLAY_SERVER_ASYNC_OPERATION_LOGS != null) {
     return truthy(env.REPLAY_SERVER_ASYNC_OPERATION_LOGS);

react_on_rails_pro/lib/react_on_rails_pro/configuration.rb

@@ -157,6 +157,7 @@ def setup_config_values
       validate_url
       validate_remote_bundle_cache_adapter
       setup_renderer_password
+      validate_renderer_password_for_production
       setup_assets_to_copy
       setup_execjs_profiler_if_needed
       check_react_on_rails_support_for_rsc
@@ -260,8 +261,6 @@ def setup_renderer_password
       # Mirror Node-side defaults: if Rails config and URL are both missing a password,
       # use RENDERER_PASSWORD from env.
       self.renderer_password = ENV.fetch("RENDERER_PASSWORD", nil) if renderer_password.blank?
-
-      validate_renderer_password_for_production
     end
 
     def validate_renderer_password_for_production
@@ -270,12 +269,14 @@ def validate_renderer_password_for_production
       return if renderer_password.present?
       return unless node_renderer?
 
-      # Fail closed: only skip validation when RAILS_ENV is explicitly set to development or test.
-      # Rails.env defaults to "development" when RAILS_ENV is unset, which would silently skip
-      # validation in misconfigured environments. Checking ENV["RAILS_ENV"] directly matches the
-      # Node-side behavior where an unset environment is treated as production-like.
-      rails_env = ENV["RAILS_ENV"]&.downcase
-      return if rails_env.present? && %w[development test].include?(rails_env)
+      # Fail closed: only skip validation when every present runtime env is explicitly
+      # development or test. This mirrors the Node-side runtimeEnvsAllowDevelopmentDefaults()
+      # which checks both NODE_ENV and RAILS_ENV. Checking NODE_ENV here surfaces
+      # misconfigurations (e.g. NODE_ENV=production + RAILS_ENV=development) at Rails boot
+      # time rather than waiting for the Node renderer to reject the request.
+      runtime_envs = [ENV.fetch("RAILS_ENV", nil), ENV.fetch("NODE_ENV", nil)].compact_blank.map(&:downcase)
+      allowed_envs = %w[development test].freeze
+      return if runtime_envs.any? && runtime_envs.all? { |e| allowed_envs.include?(e) }
 
       raise ReactOnRailsPro::Error, <<~MSG
         RENDERER_PASSWORD must be set in production-like environments (staging, production, etc.)
@@ -304,13 +305,12 @@ def validate_renderer_password_for_production
 
         If Rails and the Node Renderer disagree about startup behavior, verify both RAILS_ENV and NODE_ENV.
 
-        Environment matrix:
-          development    — password optional (no authentication)
-          test           — password optional (no authentication)
-          (RAILS_ENV unset) — treated as production-like; RENDERER_PASSWORD required
-          staging        — RENDERER_PASSWORD required
-          production     — RENDERER_PASSWORD required
-          (any other)    — RENDERER_PASSWORD required
+        Environment matrix (both RAILS_ENV and NODE_ENV are checked):
+          development/test — password optional when every set env is development or test
+          (both unset)     — treated as production-like; RENDERER_PASSWORD required
+          staging          — RENDERER_PASSWORD required
+          production       — RENDERER_PASSWORD required
+          (mixed envs)     — RENDERER_PASSWORD required (e.g. NODE_ENV=production + RAILS_ENV=development)
       MSG
     end
   end

react_on_rails_pro/sig/react_on_rails_pro/configuration.rbs

@@ -96,5 +96,7 @@ module ReactOnRailsPro
     def validate_remote_bundle_cache_adapter: () -> void
 
     def setup_renderer_password: () -> void
+
+    def validate_renderer_password_for_production: () -> void
   end
 end

react_on_rails_pro/spec/react_on_rails_pro/configuration_spec.rb

@@ -163,8 +163,9 @@ def self.fetch(*)
 
       it "is blank if not provided in the URL in development" do
         allow(ENV).to receive(:[]).and_call_original
-        allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("development")
         allow(ENV).to receive(:fetch).and_call_original
+        allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("development")
+        allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return(nil)
         allow(ENV).to receive(:fetch).with("RENDERER_PASSWORD", nil).and_return(nil)
 
         ReactOnRailsPro.configure do |config|
@@ -179,10 +180,11 @@ def self.fetch(*)
           allow(ENV).to receive(:[]).and_call_original
           allow(ENV).to receive(:fetch).and_call_original
           allow(ENV).to receive(:fetch).with("RENDERER_PASSWORD", nil).and_return(nil)
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return(nil)
         end
 
         it "raises an error if no password is set in production" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -193,7 +195,7 @@ def self.fetch(*)
         end
 
         it "raises an error if no password is set in staging" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("staging")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("staging")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -204,7 +206,31 @@ def self.fetch(*)
         end
 
         it "raises when RAILS_ENV is unset (fail-closed, matching Node-side behavior)" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return(nil)
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return(nil)
+
+          expect do
+            ReactOnRailsPro.configure do |config|
+              config.server_renderer = "NodeRenderer"
+              config.renderer_url = "https://localhost:3800"
+            end
+          end.to raise_error(ReactOnRailsPro::Error, /RENDERER_PASSWORD must be set/)
+        end
+
+        it "raises when NODE_ENV is production even if RAILS_ENV is development" do
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("development")
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return("production")
+
+          expect do
+            ReactOnRailsPro.configure do |config|
+              config.server_renderer = "NodeRenderer"
+              config.renderer_url = "https://localhost:3800"
+            end
+          end.to raise_error(ReactOnRailsPro::Error, /RENDERER_PASSWORD must be set/)
+        end
+
+        it "raises when NODE_ENV is production and RAILS_ENV is unset" do
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return(nil)
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return("production")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -215,7 +241,7 @@ def self.fetch(*)
         end
 
         it "does not raise when password comes from RENDERER_PASSWORD env var in production" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
           allow(ENV).to receive(:fetch).with("RENDERER_PASSWORD", nil).and_return("secure-password")
 
           expect do
@@ -229,7 +255,7 @@ def self.fetch(*)
         end
 
         it "does not raise when password is explicitly set in production" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -240,7 +266,7 @@ def self.fetch(*)
         end
 
         it "does not raise when password is embedded in the renderer URL in production" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -251,7 +277,7 @@ def self.fetch(*)
         end
 
         it "resolves from ENV when renderer_password is blank in production" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
           allow(ENV).to receive(:fetch).with("RENDERER_PASSWORD", nil).and_return("secure-password")
 
           expect do
@@ -266,7 +292,7 @@ def self.fetch(*)
         end
 
         it "resolves from URL when renderer_password is blank and URL has embedded password" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -283,10 +309,13 @@ def self.fetch(*)
       context "when using NodeRenderer in development/test environments" do
         before do
           allow(ENV).to receive(:[]).and_call_original
+          allow(ENV).to receive(:fetch).and_call_original
+          allow(ENV).to receive(:fetch).with("RENDERER_PASSWORD", nil).and_return(nil)
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return(nil)
         end
 
         it "does not raise in development even without a password" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("development")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("development")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -297,7 +326,43 @@ def self.fetch(*)
         end
 
         it "does not raise in test even without a password" do
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("test")
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("test")
+
+          expect do
+            ReactOnRailsPro.configure do |config|
+              config.server_renderer = "NodeRenderer"
+              config.renderer_url = "https://localhost:3800"
+            end
+          end.not_to raise_error
+        end
+
+        it "does not raise when RAILS_ENV is unset and NODE_ENV is development" do
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return(nil)
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return("development")
+
+          expect do
+            ReactOnRailsPro.configure do |config|
+              config.server_renderer = "NodeRenderer"
+              config.renderer_url = "https://localhost:3800"
+            end
+          end.not_to raise_error
+        end
+
+        it "does not raise when both RAILS_ENV and NODE_ENV are development" do
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("development")
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return("development")
+
+          expect do
+            ReactOnRailsPro.configure do |config|
+              config.server_renderer = "NodeRenderer"
+              config.renderer_url = "https://localhost:3800"
+            end
+          end.not_to raise_error
+        end
+
+        it "does not raise when RAILS_ENV is test and NODE_ENV is development" do
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("test")
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return("development")
 
           expect do
             ReactOnRailsPro.configure do |config|
@@ -311,7 +376,9 @@ def self.fetch(*)
       context "when using ExecJS renderer" do
         it "does not raise in production without a password" do
           allow(ENV).to receive(:[]).and_call_original
-          allow(ENV).to receive(:[]).with("RAILS_ENV").and_return("production")
+          allow(ENV).to receive(:fetch).and_call_original
+          allow(ENV).to receive(:fetch).with("RAILS_ENV", nil).and_return("production")
+          allow(ENV).to receive(:fetch).with("NODE_ENV", nil).and_return(nil)
 
           expect do
             ReactOnRailsPro.configure do |config|