phlex-reactive 0.9.0 → 0.9.2

data/lib/phlex/reactive/component/dsl.rb

@@ -20,6 +20,14 @@ module Phlex
       module DSL
         extend ActiveSupport::Concern
 
+        # A cross-root mirror target must be a single ID selector (issue #159)
+        # — "#" + a CSS identifier, nothing else. Not a class, not an attribute
+        # selector, not `*`, not a compound/descendant/list selector: a
+        # compromised reducer must not be able to scribble text across the
+        # page. The client interpreter enforces the SAME shape (two-sided
+        # default-deny, mirroring the attr allowlist posture).
+        MIRROR_ID_SELECTOR = /\A#[A-Za-z_][\w-]*\z/
+
         class_methods do
           # Declare the ActiveRecord (GlobalID-able) record this component is
           # rebuilt from. The signed token carries its GlobalID; the server
@@ -165,15 +173,45 @@ module Phlex
           #
           #   import { setComputeReducer } from "phlex/reactive/compute"
           #   setComputeReducer("payment_split", ({ allowance, cash, leasing, total }, { changed }) => ({ … }))
-          def reactive_compute(name, inputs: nil, outputs: nil, reducer: nil)
-            return reactive_compute_def(name) if inputs.nil? && outputs.nil?
+          #
+          # `mirror:` (issue #159) declares CROSS-ROOT text mirrors — the opt-in
+          # escape from root isolation (issue #15) for a derived value shown in a
+          # recap OUTSIDE the computing root (another tab pane, a sticky footer):
+          #
+          #   reactive_compute :split,
+          #     inputs:  %i[a b total],
+          #     outputs: %i[a b],
+          #     mirror:  { sum_a: "#sum_a", sum_total: ["#sum_total", "#footer-total"] }
+          #
+          # Each key is a compute name — a declared input (its identity mirror
+          # also paints cross-root) or a reducer-result key (an extra text-only
+          # output). Each value is one or more DOCUMENT-WIDE id selectors the
+          # value is painted into via textContent (XSS-safe, change-guarded,
+          # never innerHTML, never a field write). Id selectors ONLY — a class/
+          # attribute/compound selector raises here (declared, not arbitrary;
+          # the client interpreter re-checks the same shape).
+          def reactive_compute(name, inputs: nil, outputs: nil, reducer: nil, mirror: nil)
+            if inputs.nil? && outputs.nil?
+              # The bare form is the GETTER — a mirror: passed here would be
+              # silently dropped, so refuse it LOUDLY (declare-time validation,
+              # same posture as normalize_compute_mirror's selector check).
+              unless mirror.nil?
+                raise ArgumentError,
+                  "#{self}: reactive_compute(#{name.inspect}, mirror: ...) without inputs:/outputs: " \
+                  "is the getter form — the mirror would be silently dropped. Declare the mirror " \
+                  "alongside inputs:/outputs:."
+              end
+
+              return reactive_compute_def(name)
+            end
 
             input_names, input_types = normalize_compute_inputs(inputs)
             Registry.write_entry(
               self, :computes, name.to_sym,
               ComputeDefinition.new(
                 name: name.to_sym, inputs: input_names, input_types:,
-                outputs: Array(outputs).map(&:to_sym), reducer: (reducer || name).to_s
+                outputs: Array(outputs).map(&:to_sym), reducer: (reducer || name).to_s,
+                mirror: normalize_compute_mirror(mirror)
               )
             )
           end
@@ -210,6 +248,27 @@ module Phlex
             end
           end
 
+          # Normalize `mirror:` to { name => [id selectors] } (nil passes
+          # through — no mirror declared). Each value may be one selector or a
+          # list; every selector is validated LOUDLY at declare time against
+          # MIRROR_ID_SELECTOR (id selectors only).
+          def normalize_compute_mirror(mirror)
+            return nil if mirror.nil?
+
+            mirror.to_h do |name, selectors|
+              list = Array(selectors).map(&:to_s)
+              list.each do
+                next if it.match?(MIRROR_ID_SELECTOR)
+
+                raise ArgumentError,
+                  "#{self}: mirror target #{it.inspect} for #{name.inspect} must be a single " \
+                  "id selector (\"#some-id\") — cross-root text mirrors are declared, allowlisted " \
+                  "targets, never arbitrary selectors"
+              end
+              [name.to_sym, list.freeze]
+            end.freeze
+          end
+
           # Rebuild a component instance from a verified identity payload. Called
           # by the action endpoint after the token signature is verified.
           #

data/lib/phlex/reactive/component/helpers.rb

@@ -422,13 +422,23 @@ module Phlex
           definition = self.class.reactive_compute_def(name)
           raise Error, "#{self.class} has no reactive_compute #{name.inspect}" unless definition
 
-          {
-            data: {
-              reactive_compute_reducer_param: definition.reducer,
-              reactive_compute_inputs_param: compute_inputs_param(definition),
-              reactive_compute_outputs_param: definition.outputs.map(&:to_s).to_json
-            }
+          data = {
+            reactive_compute_reducer_param: definition.reducer,
+            reactive_compute_inputs_param: compute_inputs_param(definition),
+            reactive_compute_outputs_param: definition.outputs.map(&:to_s).to_json
           }
+          # Declared cross-root text mirrors (issue #159) ride as a JSON object of
+          # name → [id selectors]; omitted entirely when undeclared so the shipped
+          # wire stays byte-identical.
+          data[:reactive_compute_mirror_param] = compute_mirror_param(definition) if definition.mirror
+
+          { data: }
+        end
+
+        # The mirror param wire (issue #159): { "sum_a" => ["#sum_a"], … } — the
+        # values are ALWAYS arrays so the client parses one uniform shape.
+        def compute_mirror_param(definition)
+          definition.mirror.transform_keys(&:to_s).to_json
         end
 
         # The inputs param wire (issue #104). Untyped (array form) → a JSON ARRAY of

data/lib/phlex/reactive/component.rb

@@ -86,7 +86,12 @@ module Phlex
       # { name => type } hash for the typed HASH form (:string reads the field
       # value raw, :number coerces). `inputs` stays the ordered name list either
       # way, so iteration order is preserved and the array-form wire is unchanged.
-      ComputeDefinition = Data.define(:name, :inputs, :outputs, :reducer, :input_types)
+      #
+      # `mirror` (issue #159) is nil when undeclared, else a { name => [id
+      # selectors] } map — DECLARED cross-root text mirrors, validated to id
+      # selectors only at declare time (the server half of the two-sided
+      # default-deny; the client interpreter re-checks the shape).
+      ComputeDefinition = Data.define(:name, :inputs, :outputs, :reducer, :input_types, :mirror)
 
       # A declared add/remove-row collection (issue #35): the list contract tied
       # into one unit — the per-row item component, the container DOM id rows

data/lib/phlex/reactive/js.rb

@@ -44,6 +44,44 @@ module Phlex
       URL_BEARING_ATTRS = %w[href src srcdoc action formaction xlink:href].freeze
       EVENT_HANDLER_ATTR = /\Aon/i
 
+      # The attr ops whose args carry a "name" the allowlist must gate. Used to
+      # re-validate a RAW [op, args] list (the js([...]) / broadcast_js_to([...])
+      # escape hatch) that skips the builder's build-time attr_args check.
+      ATTR_NAME_OPS = %w[set_attr remove_attr toggle_attr].freeze
+
+      # Validate a raw ops list ([[op, args], ...] as passed to js/broadcast_js_to
+      # without the builder) against the attribute allowlist, so the escape hatch
+      # gets the SAME server-side default-deny as the JS chain (defense in depth;
+      # the client also enforces it). Non-attr ops and malformed entries pass
+      # through untouched — the client interpreter default-denies unknown ops.
+      def self.assert_ops_allowed!(list)
+        Array(list).each do |op, args|
+          next unless ATTR_NAME_OPS.include?(op.to_s) && args.is_a?(::Hash)
+
+          name = args["name"] || args[:name]
+          assert_allowed_attr(name.to_s) if name
+        end
+      end
+
+      # The attribute-name allowlist (issue #96), case-insensitive. Refuses
+      # event-handler (on*), URL-bearing, and style attributes. Enforced at build
+      # time by the instance builder AND on the raw-list escape hatch — two-sided
+      # default-deny with the client interpreter.
+      def self.assert_allowed_attr(name)
+        lower = name.downcase
+        if name.match?(EVENT_HANDLER_ATTR)
+          raise ArgumentError,
+            "#{self}: attribute #{name.inspect} is an event handler (on*) — refused (XSS). " \
+            "Client attr ops target hidden/disabled/open/selected/aria-*/data-* and classes."
+        end
+        return unless URL_BEARING_ATTRS.include?(lower) || lower == "style"
+
+        raise ArgumentError,
+          "#{self}: attribute #{name.inspect} is refused — URL-bearing attributes " \
+          "(#{URL_BEARING_ATTRS.join(", ")}) and `style` can't be set from client ops " \
+          "(injection surface). Use classes for styling; target aria-*/data-*/boolean attrs."
+      end
+
       # The accumulated [name, args] op pairs, oldest first. Frozen.
       attr_reader :ops
 
@@ -119,6 +157,20 @@ module Phlex
         append("focus_first", target_args(to, global:))
       end
 
+      # --- Text content (issue #159) ---
+      #
+      # text(to, value) — set the target's textContent (stringified; nil clears).
+      # XSS-safe by construction: textContent only, NEVER innerHTML — strictly
+      # less powerful than set_attr. Pair with `global: true` to paint a value
+      # into a node OUTSIDE the component's root (the cross-root text escape,
+      # e.g. a read-only recap in another tab pane).
+
+      def text(to, value, global: false)
+        args = { "to" => normalize_target(to), "value" => value.to_s }
+        args["global"] = true if global
+        append("text", args.freeze)
+      end
+
       # --- Dispatch a bubbling CustomEvent (issue #96) ---
       #
       # dispatch(name, to: nil, detail: {}) — emit a bubbling CustomEvent so other
@@ -169,21 +221,10 @@ module Phlex
         args.freeze
       end
 
-      # The attribute-name allowlist (issue #96), case-insensitive. Enforced here
-      # AND in the client interpreter — two-sided default-deny.
+      # Build-time attr-name allowlist for the instance builder — delegates to the
+      # shared class-method check (also used by the raw-list escape hatch).
       def assert_allowed_attr(name)
-        lower = name.downcase
-        if name.match?(EVENT_HANDLER_ATTR)
-          raise ArgumentError,
-            "#{self.class}: attribute #{name.inspect} is an event handler (on*) — refused (XSS). " \
-            "Client attr ops target hidden/disabled/open/selected/aria-*/data-* and classes."
-        end
-        return unless URL_BEARING_ATTRS.include?(lower) || lower == "style"
-
-        raise ArgumentError,
-          "#{self.class}: attribute #{name.inspect} is refused — URL-bearing attributes " \
-          "(#{URL_BEARING_ATTRS.join(", ")}) and `style` can't be set from client ops " \
-          "(injection surface). Use classes for styling; target aria-*/data-*/boolean attrs."
+        self.class.assert_allowed_attr(name)
       end
 
       # A transition must be exactly [during, from, to] class lists (strings).

data/lib/phlex/reactive/response.rb

@@ -275,6 +275,10 @@ data-reactive-ops="#{ERB::Util.html_escape(json)}"></turbo-stream>).html_safe
             list = Array(ops)
             raise ArgumentError, "js(...) got no ops — a dead reactive:js stream" if list.empty?
 
+            # The builder validates attr names at build time; a raw [op, args]
+            # list skips that, so re-apply the allowlist here (defense in depth —
+            # the client interpreter also refuses on*/URL/style attrs).
+            Phlex::Reactive::JS.assert_ops_allowed!(list)
             list.to_json
           end
         end

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.9.0"
+    VERSION = "0.9.2"
   end
 end

data/lib/phlex/reactive.rb

@@ -446,6 +446,10 @@ module Phlex
       #     through the endpoint's existing `|| raise(InvalidToken)` → 400.
       def upgrade_token(payload)
         version = payload.fetch("v", 0)
+        # "v" is inside the signed blob, so only our own key could produce a
+        # malformed one — but fail closed rather than 500 on the comparison
+        # (String vs Integer) or silently treat a negative "v" as legacy.
+        return nil unless version.is_a?(::Integer) && version >= 0
         return payload if version == TOKEN_VERSION
         return nil if version > TOKEN_VERSION
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.2
 platform: ruby
 authors:
 - Mikael Henriksson