react_on_rails 17.0.1 → 17.1.0.rc.0

data/lib/react_on_rails/agent_guardrails/templates/rsc_app_safety_check.rb

@@ -0,0 +1,215 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Claude Code PostToolUse hook — installed by `rake react_on_rails:install_rsc_agent_guardrails`.
+# NON-BLOCKING advisory (always exits 0). Warns when React on Rails Pro RSC endpoints are wired
+# without visible authentication. The RSC payload route renders any registered server component
+# with caller-supplied props and has NO built-in auth — see the `rsc-app-safety` skill.
+# Callback detection is a conservative name/scope heuristic; silence does not prove authorization.
+
+require "json"
+require "ripper"
+
+# Recognizing a callback as authentication only silences the advisory, so this stays deliberately
+# conservative: an over-broad match turns a false positive into a false negative, which is the more
+# dangerous direction for a security guardrail.
+#
+# A trailing `!`/`?` is the discriminating signal for the open-ended forms. Devise and friends
+# generate bang callbacks per scope (`authenticate_admin_user!`, `authenticate_api_user!`,
+# `authenticate_customer!`), and app-defined auth callbacks follow the same convention, so any
+# `authenticate*`/`authorize*` name that ends in a bang counts. Without a bang the name must come
+# from the narrow allowlist, which keeps unrelated callbacks such as `authenticate_analytics_session`
+# and `authorize_for_metrics` from reading as authentication.
+AUTH_NAME = /
+  (?:
+    authenticate(?:_\w+)?[!?] |
+    authorize(?:_\w+)?[!?] |
+    authenticate(?:_(?:user|account|admin|member|session))? |
+    authorize(?:_(?:request|access|user))? |
+    require_(?:login|user|authentication|authorization) |
+    verify_authenticat(?:ed|ion)
+  )[!?]?
+/x
+AUTH_CALLBACK_NAME = "(?:prepend_|append_)?before_action"
+COMMENT_EVENTS = %i[on_comment on_embdoc_beg on_embdoc on_embdoc_end].freeze
+# String, heredoc, and regexp bodies are data, not executable code. Ripper reports all of them as
+# :on_tstring_content, so they must be neutralized alongside comments — otherwise a
+# `skip_before_action` written inside a heredoc reads as a real callback and produces a false warning.
+STRING_BODY_EVENTS = %i[on_tstring_content].freeze
+SCOPE_SYNTAX = /(?:%[iw](?:\[[^\]]*\]|\([^)]*\)|\{[^}]*\})|\[[^\]]*\]|:[A-Za-z_]\w*[!?]?|["'][^"']+["'])/
+ONLY_SCOPE = /\A,\s*only:\s*(#{SCOPE_SYNTAX})\z/o
+EXCEPT_SCOPE = /\A,\s*except:\s*(#{SCOPE_SYNTAX})\z/o
+
+def logical_statements(lines, callback_name)
+  lines.each_with_index.filter_map do |line, index|
+    next unless line.match?(/^\s*#{callback_name}\b/)
+
+    statement = line.dup
+    while index + 1 < lines.length &&
+          (statement.rstrip.end_with?(",", "\\") ||
+           statement.count("(") > statement.count(")") ||
+           statement.count("[") > statement.count("]"))
+      index += 1
+      statement << lines[index]
+    end
+    statement.gsub(/\s+/, " ").strip
+  end
+end
+
+def parse_callback(statement, callback_name)
+  callback = statement.match(
+    /\A#{callback_name}\s*(?<parenthesized>\()?\s*:?(?<auth>#{AUTH_NAME})(?=\s*(?:,|\)|\z))(?<rest>.*)\z/
+  )
+  return unless callback
+
+  rest = callback[:rest].strip
+  rest = rest.delete_suffix(")").strip if callback[:parenthesized]
+  [callback[:auth], rest]
+end
+
+def applies_to_payload?(rest, unknown:)
+  return true if rest.empty?
+
+  if (scope = rest.match(ONLY_SCOPE))
+    scope[1].match?(/\brsc_payload\b/)
+  elsif (scope = rest.match(EXCEPT_SCOPE))
+    !scope[1].match?(/\brsc_payload\b/)
+  else
+    unknown
+  end
+end
+
+def authenticated_callback_names(lines)
+  logical_statements(lines, AUTH_CALLBACK_NAME).filter_map do |statement|
+    parsed = parse_callback(statement, AUTH_CALLBACK_NAME)
+    parsed&.first if parsed && applies_to_payload?(parsed.last, unknown: false)
+  end
+end
+
+def remove_skipped_callbacks(lines, authenticated_callbacks)
+  logical_statements(lines, "skip_before_action").each do |statement|
+    parsed = parse_callback(statement, "skip_before_action")
+    next unless parsed && authenticated_callbacks.include?(parsed.first)
+
+    authenticated_callbacks.delete(parsed.first) if applies_to_payload?(parsed.last, unknown: true)
+  end
+end
+
+def ruby_tokens(content)
+  return [] unless content.valid_encoding?
+
+  Ripper.lex(content)
+rescue ArgumentError
+  []
+end
+
+def blank_text(text)
+  text.gsub(/[^\n]/, " ")
+end
+
+# Blanks only the parts of a string body that begin a source line, because those are the parts that
+# can masquerade as a statement to the line-oriented callback scanner. Content that starts mid-line
+# (`only: "rsc_payload"`) is preserved so callback scope parsing keeps working.
+def blank_line_starting_text(text, column)
+  text.split("\n", -1).each_with_index.map do |part, index|
+    index.zero? && column.positive? ? part : blank_text(part)
+  end.join("\n")
+end
+
+def scannable_ruby_lines(tokens)
+  heredoc_depth = 0
+  tokens.each_with_object(+"") do |(position, event, token, _state), scannable|
+    heredoc_depth += 1 if event == :on_heredoc_beg
+    heredoc_depth -= 1 if event == :on_heredoc_end
+    scannable << if COMMENT_EVENTS.include?(event)
+                   blank_text(token)
+                 elsif STRING_BODY_EVENTS.include?(event)
+                   # Every line of a heredoc body begins a source line; Ripper reports its indentation
+                   # as a separate token, so the body's column is not a reliable signal there.
+                   heredoc_depth.positive? ? blank_text(token) : blank_line_starting_text(token, position[1])
+                 else
+                   token
+                 end
+  end.lines
+end
+
+# Executable lines only. Falls back to a crude comment strip when the file does not lex (so an
+# unparseable routes file still gets its advisory rather than silently passing).
+def code_lines(content)
+  tokens = ruby_tokens(content)
+  return scannable_ruby_lines(tokens) if tokens.any?
+
+  content.lines.map { |line| line.sub(/#.*/, "") }
+end
+
+def renderer_evidence?(tokens)
+  tokens.any? do |_position, event, token, _state|
+    (event == :on_const && token == "RSCPayloadRenderer") || (event == :on_ident && token == "rsc_payload")
+  end
+end
+
+def authentication_evidence?(lines)
+  authenticated_callbacks = authenticated_callback_names(lines)
+  remove_skipped_callbacks(lines, authenticated_callbacks)
+  authenticated_callbacks.any?
+end
+
+def input_file
+  input = $stdin.tty? ? "" : $stdin.read
+  parsed_input = JSON.parse(input)
+  parsed_path = parsed_input.is_a?(Hash) ? parsed_input.dig("tool_input", "file_path").to_s : ""
+  parsed_path.empty? ? ARGV.first.to_s : parsed_path
+rescue JSON::ParserError
+  ARGV.first.to_s
+end
+
+def warning_context(relative_path, detail)
+  [
+    "⚠️  rsc-app-safety: #{relative_path}",
+    detail,
+    "The React on Rails Pro RSC payload route renders any registered server component with",
+    "caller-supplied props and has NO built-in authentication. Confirm this endpoint is behind your",
+    "app's auth via ReactOnRailsPro.configure { |config| config.rsc_payload_authorizer = ... } or",
+    "an authenticated, app-owned controller's before_action, and",
+    "that server components derive identity from the session, not props. Read the rsc-app-safety",
+    "skill before shipping."
+  ].join("\n")
+end
+
+def read_file(path)
+  File.read(path)
+rescue SystemCallError
+  nil
+end
+
+file = input_file.tr("\\", "/")
+exit 0 if file.empty? || !File.file?(file)
+
+root = ENV.fetch("CLAUDE_PROJECT_DIR", Dir.pwd).tr("\\", "/").delete_suffix("/")
+relative_path = file.delete_prefix("#{root}/")
+detail = case file
+         when %r{\A(?:.*/)?config/routes(?:/[^/]+)?\.rb\z}
+           content = read_file(file)
+           if content && code_lines(content).any? { |line| line.include?("rsc_payload_route") }
+             "This routes file mounts rsc_payload_route (a public RSC endpoint)."
+           end
+         when %r{\A(?:.*/)?app/controllers/.+\.rb\z}
+           content = read_file(file)
+           tokens = ruby_tokens(content) if content
+           lines = scannable_ruby_lines(tokens) if tokens&.any?
+           if lines && renderer_evidence?(tokens) && !authentication_evidence?(lines)
+             "This controller wires an RSC payload renderer, but the edited file shows no " \
+               "before_action/authentication locally. Inherited callbacks are not inspected."
+           end
+         end
+
+if detail
+  puts JSON.generate(
+    "hookSpecificOutput" => {
+      "hookEventName" => "PostToolUse",
+      "additionalContext" => warning_context(relative_path, detail)
+    }
+  )
+end
+
+exit 0

data/lib/react_on_rails/agent_guardrails/templates/rsc_app_safety_skill.md

@@ -0,0 +1,71 @@
+---
+name: rsc-app-safety
+description: >
+  Use when building or reviewing a Rails app that uses React on Rails Pro React
+  Server Components (RSC) — mounting the RSC payload route, writing server
+  components, configuring the Node renderer, or handling props, secrets, or error
+  reporting. Flags the RSC API footguns that expose an app to XSS, auth bypass, or
+  data leakage.
+---
+
+# RSC app safety (React on Rails Pro)
+
+React Server Components render on a trusted server and stream to an untrusted client. The React on
+Rails Pro RSC API is safe when used correctly, but a few usage patterns are footguns. Check these
+whenever you add or change RSC in this app.
+
+## Footguns to avoid
+
+1. **Authenticate the RSC payload route.** `rsc_payload_route` mounts a public endpoint that renders
+   **any registered server component** with **caller-supplied props**
+   (`GET <path>/<Component>?props=…`). It ships with no built-in authentication. The default
+   `ReactOnRailsPro::RscPayloadController` does not inherit from your app's `ApplicationController`,
+   so an application-wide `before_action` does not protect it. Configure its supported authorizer in
+   `config/initializers/react_on_rails_pro.rb` to check the Rails session and component name before
+   props are parsed or rendered:
+
+   ```ruby
+   allowed_rsc_components = %w[AccountPage DashboardPage].freeze
+
+   ReactOnRailsPro.configure do |config|
+     config.rsc_payload_authorizer = lambda do |controller, component_name|
+       controller.session[:user_id].present? && allowed_rsc_components.include?(component_name)
+     end
+   end
+   ```
+
+   Alternatively, explicitly route to an app-owned controller that applies the required
+   authentication and authorization callbacks. (Ref: `shakacode/react_on_rails#4595`.)
+
+2. **Treat server-component props as untrusted input.** A server component must derive the current
+   user and permissions from the Rails session / `railsContext`, never from its props — props on the
+   payload route are attacker-controlled. Don't key data access or authorization off props alone.
+
+3. **Keep the Node renderer private.** It executes server bundles and is not meant to be
+   internet-facing. Bind it to a private network, set `RENDERER_PASSWORD` (required in production —
+   the renderer refuses to boot without one), and never expose its port publicly.
+   (Ref: `shakacode/react_on_rails#4596`.)
+
+4. **Minimize secrets or PII.** Don't embed the renderer password in a `renderer_url` that also gets
+   logged. React on Rails redacts SSR props and generated JavaScript from `PrerenderError` messages
+   and error-tracker context, but still minimize sensitive props and avoid logging them in application
+   code. (Ref: `shakacode/react_on_rails#4597`.)
+
+5. **Don't hand-build inline scripts around RSC output.** Let React on Rails serialize props and RSC
+   payloads — it HTML-escapes them (`ERB::Util.json_escape`). Never wrap RSC data in your own
+   `<script>` / `raw` / `html_safe` string; that reintroduces the XSS the framework already prevents.
+
+## Quick checklist for an RSC change
+
+- [ ] Any `rsc_payload_route` is protected by `config.rsc_payload_authorizer` or explicitly targets
+      an authenticated, app-owned controller.
+- [ ] Server components read identity from session / `railsContext`, not from props.
+- [ ] Node renderer is private and `RENDERER_PASSWORD` is set; its port is not publicly exposed.
+- [ ] No secrets in logged URLs; sensitive props minimized and not logged by application code.
+- [ ] No custom `<script>` / `html_safe` / `raw` wrapping of props or RSC payloads.
+
+## More
+
+- React on Rails Pro RSC docs: https://www.shakacode.com/react-on-rails-pro
+- Update this skill anytime with `rake react_on_rails:install_rsc_agent_guardrails`.
+- This skill and its hook are managed copies; reinstalling replaces local edits to either file.

data/lib/react_on_rails/agent_guardrails.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "tempfile"
+
+module ReactOnRails
+  # Installs (and idempotently updates) the RSC "agent guardrail" assets into a host app:
+  # a Claude Code skill and an advisory PostToolUse hook that steer AI agents away from the
+  # React Server Components API footguns (unauthenticated payload route, trusting props, exposing
+  # the Node renderer, leaking secrets). Invoked by `rake react_on_rails:install_rsc_agent_guardrails`
+  # and by the RSC generator.
+  module AgentGuardrails
+    Error = Class.new(StandardError)
+
+    TEMPLATES_DIR = File.expand_path("agent_guardrails/templates", __dir__)
+
+    # source template (under TEMPLATES_DIR) => destination path relative to the app root
+    FILES = {
+      "rsc_app_safety_skill.md" => ".claude/skills/rsc-app-safety/SKILL.md",
+      "rsc_app_safety_check.rb" => ".claude/hooks/rsc-app-safety-check.rb"
+    }.freeze
+
+    HOOK_COMMAND = "ruby"
+    HOOK_ARGS = ["${CLAUDE_PROJECT_DIR}/.claude/hooks/rsc-app-safety-check.rb"].freeze
+    LEGACY_HOOK_COMMAND = "${CLAUDE_PROJECT_DIR}/.claude/hooks/rsc-app-safety-check.sh"
+    LEGACY_HOOK_REL = ".claude/hooks/rsc-app-safety-check.sh"
+    HOOK_REL = ".claude/hooks/rsc-app-safety-check.rb"
+    HOOK_MATCHER = "Edit|Write"
+    SETTINGS_REL = ".claude/settings.json"
+
+    # Copies the guardrail files and registers the advisory hook. Idempotent: re-running only
+    # writes what changed. Returns an array of human-readable action strings.
+    def self.install(destination_root, skip_existing: false)
+      new_installer(destination_root, skip_existing:).install
+    end
+
+    def self.new_installer(destination_root, skip_existing: false)
+      Installer.new(destination_root, skip_existing:)
+    end
+
+    # Where guardrails get installed when no explicit destination is given. Prefers the Rails
+    # application root so the task installs into the app's `.claude/` even when rake is invoked
+    # from a subdirectory; falls back to the working directory outside a Rails app.
+    def self.default_destination_root(explicit = nil)
+      explicit = explicit.to_s
+      return explicit unless explicit.empty?
+
+      rails_root = defined?(Rails) && Rails.respond_to?(:root) ? Rails.root : nil
+      rails_root ? rails_root.to_s : Dir.pwd
+    end
+
+    # Encapsulates a single install run against one app root.
+    class Installer
+      def initialize(destination_root, skip_existing: false)
+        @destination_root = File.expand_path(destination_root.to_s)
+        @skip_existing = skip_existing
+      end
+
+      def install
+        validate_settings_before_copy
+        actions = FILES.map { |source, dest_rel| copy_file(source, dest_rel) }
+        actions << register_hook
+        actions << remove_legacy_hook
+        actions.compact
+      end
+
+      private
+
+      attr_reader :destination_root, :skip_existing
+
+      def validate_settings_before_copy
+        settings_path = File.join(destination_root, SETTINGS_REL)
+        return if skip_existing && File.exist?(settings_path)
+
+        read_settings(settings_path)
+      end
+
+      def copy_file(source, dest_rel)
+        source_path = File.join(TEMPLATES_DIR, source)
+        dest_path = File.join(destination_root, dest_rel)
+        existed = File.exist?(dest_path)
+        return "skipped    #{dest_rel} (already exists)" if skip_existing && existed
+
+        new_content = File.read(source_path)
+        unchanged = existed && File.read(dest_path) == new_content
+
+        unless unchanged
+          FileUtils.mkdir_p(File.dirname(dest_path))
+          File.write(dest_path, new_content)
+        end
+        File.chmod(0o755, dest_path) if dest_rel == HOOK_REL
+
+        return "unchanged  #{dest_rel}" if unchanged
+
+        existed ? "updated    #{dest_rel}" : "created    #{dest_rel}"
+      end
+
+      def register_hook
+        settings_path = File.join(destination_root, SETTINGS_REL)
+        return "skipped    #{SETTINGS_REL} (already exists)" if skip_existing && File.exist?(settings_path)
+
+        settings = read_settings(settings_path)
+        return "unchanged  #{SETTINGS_REL} (hook already registered)" if hook_registered?(settings)
+
+        add_hook(settings)
+        FileUtils.mkdir_p(File.dirname(settings_path))
+        existed = File.exist?(settings_path)
+        atomic_write(settings_path, "#{JSON.pretty_generate(settings)}\n")
+        existed ? "updated    #{SETTINGS_REL} (registered hook)" : "created    #{SETTINGS_REL} (registered hook)"
+      end
+
+      # settings.json is the user's file and may hold unrelated configuration, so it is replaced by
+      # rename rather than truncate-and-write: an interrupted or failed write can never leave a
+      # half-written or empty settings file behind.
+      def atomic_write(path, content)
+        directory = File.dirname(path)
+        mode = File.exist?(path) ? File.stat(path).mode & 0o7777 : 0o644
+        temp = Tempfile.create([".#{File.basename(path)}", ".tmp"], directory)
+        begin
+          temp.write(content)
+          temp.flush
+          temp.fsync
+          temp.close
+          File.chmod(mode, temp.path)
+          File.rename(temp.path, path)
+        rescue StandardError
+          FileUtils.rm_f(temp.path)
+          raise
+        end
+      end
+
+      def remove_legacy_hook
+        legacy_path = File.join(destination_root, LEGACY_HOOK_REL)
+        return unless File.exist?(legacy_path)
+        return "skipped    #{LEGACY_HOOK_REL} (already exists)" if skip_existing
+
+        FileUtils.rm_f(legacy_path)
+        "removed    #{LEGACY_HOOK_REL} (replaced by #{HOOK_REL})"
+      end
+
+      def read_settings(path)
+        return {} unless File.exist?(path)
+
+        content = File.read(path).strip
+        return {} if content.empty?
+
+        settings = JSON.parse(content)
+        raise Error, invalid_settings_message unless valid_settings_shape?(settings)
+
+        settings
+      rescue JSON::ParserError
+        raise Error, invalid_settings_message
+      end
+
+      def valid_settings_shape?(settings)
+        return false unless settings.is_a?(Hash)
+
+        hooks = settings["hooks"]
+        return true if hooks.nil?
+        return false unless hooks.is_a?(Hash)
+
+        valid_post_tool_use?(hooks["PostToolUse"])
+      end
+
+      def valid_post_tool_use?(entries)
+        return true if entries.nil?
+
+        entries.is_a?(Array) && entries.all? { |entry| valid_hook_group?(entry) }
+      end
+
+      def valid_hook_group?(entry)
+        return false unless entry.is_a?(Hash)
+
+        hooks = entry["hooks"]
+        hooks.nil? || (hooks.is_a?(Array) && hooks.all?(Hash))
+      end
+
+      # Settings are validated before anything is copied, so reaching here means NOTHING was
+      # installed — including #{HOOK_REL}. The recovery therefore has to be "fix the settings and
+      # re-run", not "register the hook manually": the hook script does not exist yet, so pointing
+      # Claude at it would leave the advisory guardrail silently disabled.
+      def invalid_settings_message
+        "#{SETTINGS_REL} is not valid JSON for Claude settings, so it was left untouched and no " \
+          "guardrail files were installed (#{HOOK_REL} does not exist yet). Fix or remove " \
+          "#{SETTINGS_REL}, then re-run `rake react_on_rails:install_rsc_agent_guardrails` to " \
+          "install the hook and register it as a PostToolUse (#{HOOK_MATCHER}) command hook."
+      end
+
+      def hook_registered?(settings)
+        entries = Array(settings.dig("hooks", "PostToolUse"))
+        managed_hooks = entries.flat_map { |entry| Array(entry["hooks"]) }.select { |hook| managed_hook?(hook) }
+        return false unless managed_hooks.one? && registered_hook?(managed_hooks.first)
+
+        entries.any? do |entry|
+          entry["matcher"] == HOOK_MATCHER && Array(entry["hooks"]).include?(managed_hooks.first)
+        end
+      end
+
+      def add_hook(settings)
+        hooks = (settings["hooks"] ||= {})
+        post_tool_use = (hooks["PostToolUse"] ||= [])
+        post_tool_use.each do |candidate|
+          Array(candidate["hooks"]).reject! { |hook| managed_hook?(hook) }
+        end
+        entry = post_tool_use.find { |candidate| candidate["matcher"] == HOOK_MATCHER }
+        unless entry
+          entry = { "matcher" => HOOK_MATCHER, "hooks" => [] }
+          post_tool_use << entry
+        end
+        (entry["hooks"] ||= []) << { "type" => "command", "command" => HOOK_COMMAND, "args" => HOOK_ARGS }
+      end
+
+      def registered_hook?(hook)
+        hook["type"] == "command" && hook["command"] == HOOK_COMMAND && hook["args"] == HOOK_ARGS
+      end
+
+      def managed_hook?(hook)
+        registered_hook?(hook) || hook["command"] == LEGACY_HOOK_COMMAND
+      end
+    end
+  end
+end

data/lib/react_on_rails/dev/service_checker.rb

@@ -90,7 +90,7 @@ module ReactOnRails
         end
 
         def load_config(config_path)
-          YAML.load_file(config_path)
+          YAML.safe_load_file(config_path)
         rescue StandardError => e
           puts Rainbow("⚠️  Failed to load #{config_path}: #{e.message}").yellow
           puts Rainbow("   Continuing without service checks...").yellow