command_tower 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e983f8f191ccb75948cdad73067d1cd43b7b1e5a8a3e0d34fc0130a76c313da
-  data.tar.gz: 5ef89ea100c06425afe3aee6f87b8b71503e4d28be6a4ff6e309af8a5b02c83f
+  metadata.gz: 465f6aea711f7cb8158e7b3eb9389663c2ac06d5104e89335da339d04cda81b6
+  data.tar.gz: 3e8c5a0b870ec8fd71f954ee3e04573cf87bf3eb3b8091e056dddb0db37176a6
 SHA512:
-  metadata.gz: 6555727a8b33efc95493ecdeec48067e39c8ee9eb4f1750c8fd183599a8d41bf1e763d538d379d0be7888697e6f09ca0795ebb643817d5aea2c548c61cd867f6
-  data.tar.gz: ca51dafb697b03848b2509f16660df1e9e349f325a01da7d589300ac7db0ee087df33c08d46194a97e60ae6cbc984de8bcbf1fbc65f41d7bd31f31013d64add4
+  metadata.gz: 38ac950878823bda838001b2948ef4c54fe6b07cd0520242681607415f0ffce8c3ac795280fda9248a8a7ba449ffeef1cd8403a89777940d1ee0e846ba683906
+  data.tar.gz: b42d36dc8afb1cc9d0df9f254622b01981984d50f7839eebe8040056714e91d04b1b30dd397828133f270056f7032a695b06071c7cb958d65f4f0885d95c415f

data/app/controllers/command_tower/application_controller.rb

@@ -3,6 +3,7 @@
 module CommandTower
   class ApplicationController < ActionController::API
     include CommandTower::Execution::HttpBoundary
+    include CommandTower::Execution::ClientCompatibilityBoundary
 
     AUTHENTICATION_HEADER = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_HEADER
     AUTHENTICATION_EXPIRE_HEADER = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_EXPIRE_HEADER

data/app/controllers/concerns/command_tower/execution/client_compatibility_boundary.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Execution
+    # Runs the client-version-compatibility check for every JSON request,
+    # before any authentication/authorization filter. Transport-only: it
+    # invokes exactly one workflow and renders its result — all decisioning
+    # lives in `Workflows::ClientCompatibility::EvaluateWorkflow` /
+    # `Services::ClientCompatibility::Evaluate` (authority §10).
+    #
+    # Hosts that need to exempt a controller (e.g. a healthz-style endpoint)
+    # do so with `skip_before_action :evaluate_client_compatibility!`.
+    module ClientCompatibilityBoundary
+      extend ActiveSupport::Concern
+
+      included do
+        include CommandTower::Api::ApplicationResponseRenderer
+        before_action :evaluate_client_compatibility!
+      end
+
+      private
+
+      def evaluate_client_compatibility!
+        result = CommandTower::Workflows::ClientCompatibility::EvaluateWorkflow.call(
+          request: request,
+          controller_class: self.class,
+          action_name: action_name
+        )
+
+        unless result.success?
+          render_application_result(result)
+          return false
+        end
+
+        true
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/client_update_required_error.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    # Hard client-version incompatibility (authority §14). Deliberately NOT
+    # registered in `SessionErrorStatus` — its HTTP status (426) is set
+    # directly by `Workflows::ClientCompatibility::EvaluateWorkflow`, not
+    # derived from that closed 401/403/412 mapping table.
+    class ClientUpdateRequiredError < ApplicationError
+      def initialize(details: {})
+        super(details:)
+      end
+
+      def code
+        "client_update_required"
+      end
+
+      def message
+        "Client update required"
+      end
+
+      def log_level
+        :warn
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/messaging/inbox.rb

@@ -16,7 +16,8 @@ module CommandTower
           def self.serialize(item)
             ItemSerializer.serialize(item).merge(
               body: item.fetch(:body), metadata: item[:metadata],
-              notificationTypeKey: item.fetch(:notification_type_key)
+              notificationTypeKey: item.fetch(:notification_type_key),
+              content: item.fetch(:content)
             )
           end
         end

data/app/services/command_tower/email_theme/resolver.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module EmailTheme
+    # Internal rendering-time collaborator (not a Service/Workflow/Controller).
+    #
+    # Assembles the full semantic token set an email template needs: the
+    # visual tokens from CommandTower.config.email_theme plus the identity
+    # tokens CommandTower already exposes (config.application). Shared by
+    # Messaging email templates and, later, CT's own auth mail templates —
+    # hence its own top-level namespace rather than living under
+    # Messaging::Rendering.
+    #
+    # No template calls this yet (Rich Messaging Strategy §12 steps C/D are
+    # separate, later slices). This is deliberately not a
+    # CommandTower::Services::ApplicationService: it takes no arguments,
+    # performs no I/O, and cannot fail under normal config state — there is
+    # nothing to validate and nothing to fail. Mirrors
+    # Messaging::Rendering::TemplateResolver's own documented exemption.
+    class Resolver
+      class << self
+        def resolve
+          new.resolve
+        end
+      end
+
+      def resolve
+        theme = CommandTower.config.email_theme
+        {
+          canvas_background: theme.canvas_background,
+          surface_background: theme.surface_background,
+          surface_border: theme.surface_border,
+          primary_text: theme.primary_text,
+          body_text: theme.body_text,
+          muted_text: theme.muted_text,
+          accent: theme.accent,
+          text_on_accent: theme.text_on_accent,
+          primary_action: theme.primary_action,
+          product_name: CommandTower.app_name_for_comms,
+          product_url: CommandTower.config.application.composed_url
+        }.freeze
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/notification_types/declaration.rb

@@ -22,6 +22,7 @@ module CommandTower
         :retention,
         :delivery_status_visible,
         :host_ownership,
+        :inbox_document_composer,
       ) do
         def self.build(
           key:,
@@ -41,7 +42,8 @@ module CommandTower
           priority: nil,
           retention: nil,
           delivery_status_visible: nil,
-          host_ownership: nil
+          host_ownership: nil,
+          inbox_document_composer: nil
         )
           new(
             key: key.nil? ? nil : key.to_s,
@@ -62,6 +64,17 @@ module CommandTower
             retention:,
             delivery_status_visible:,
             host_ownership:,
+            # Rich Messaging Slice 2.5 revision — String class name of a
+            # pure-Ruby Inbox document composer (`.call(communication:) ->
+            # InboxDocument`), lazily `.constantize`d by
+            # `InboxDocumentRenderer` at render time, never at registration
+            # time (mirrors the existing RBAC `Entity#controller` deferred
+            # class-string convention — decouples host `to_prepare`
+            # registration order from composer class-load order). `nil`
+            # means this type intentionally has no custom Inbox document and
+            # renders via `InboxDocumentRenderer#build_generic`. See
+            # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md.
+            inbox_document_composer: inbox_document_composer.nil? ? nil : inbox_document_composer.to_s,
           ).freeze
         end
 

data/app/services/command_tower/messaging/rendering/channel_renderer.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "erb"
 require "cgi"
 
 module CommandTower
@@ -12,7 +11,7 @@ module CommandTower
         PUSHOVER_CHANNEL = "pushover"
         PUSH_CHANNEL = "push"
         SUPPORTED_CHANNELS = [EMAIL_CHANNEL, SMS_CHANNEL, PUSHOVER_CHANNEL, PUSH_CHANNEL].freeze
-        TEMPLATE_DIR = CommandTower::Engine.root.join("app/views/command_tower/messaging/rendering")
+        TEMPLATE_FILENAME_PATTERN = /\A(?<basename>[a-z]+)\.(?<format>html|text)\.erb\z/
         DEFAULT_TITLE = "Notification"
 
         def self.render(communication:, channel_key:, recipient_address:)
@@ -120,24 +119,56 @@ module CommandTower
         alias pushover_title notification_title
 
         def render_template(filename)
-          path = TEMPLATE_DIR.join(filename)
-          raise Errno::ENOENT, "missing template #{filename}" unless path.file?
-
-          template = ERB.new(path.read, trim_mode: "-")
-          template.result_with_hash(template_locals)
+          match = TEMPLATE_FILENAME_PATTERN.match(filename.to_s)
+          raise Errno::ENOENT, "missing template #{filename}" unless match
+
+          TemplateResolver.render(
+            basename: match[:basename],
+            format: match[:format].to_sym,
+            notification_type_key: @communication.notification_type_key,
+            generic_locals: template_locals,
+            type_locals: type_template_locals,
+          )
         end
 
+        # ActionView's OutputBuffer auto-escapes any interpolated value that is
+        # not marked `html_safe?`, for every format (html and text alike) —
+        # see `ActionView::OutputBuffer#<<`. Generic templates historically
+        # relied on plain ERB, which never auto-escaped anything; callers
+        # (namely `email.html.erb`) explicitly call `h.call(...)` when they
+        # want escaping. To preserve that exact contract under ActionView
+        # rendering, `title`/`body`/`deep_link` are pre-marked `html_safe` (so
+        # raw interpolation stays unescaped, matching legacy behavior) and
+        # `h.call` marks its own already-escaped output `html_safe` too, so it
+        # is not escaped a second time by the output buffer.
         def template_locals
+          {
+            title: @communication.title.to_s.html_safe,
+            body: @communication.body.to_s.html_safe,
+            deep_link: deep_link_from_metadata&.html_safe,
+            h: ->(value) { CGI.escapeHTML(value.to_s).html_safe },
+          }
+        end
+
+        def type_template_locals
+          template_locals.merge(
+            metadata: frozen_metadata,
+            notification_type_key: @communication.notification_type_key.to_s,
+          )
+        end
+
+        def deep_link_from_metadata
           metadata = @communication.metadata
           deep_link = metadata.is_a?(Hash) ? metadata["deep_link"] || metadata[:deep_link] : nil
           deep_link = deep_link.to_s if deep_link
+          deep_link.presence
+        end
 
-          {
-            title: @communication.title.to_s,
-            body: @communication.body.to_s,
-            deep_link: deep_link.presence,
-            h: ->(value) { CGI.escapeHTML(value.to_s) },
-          }
+        def frozen_metadata
+          metadata = @communication.metadata
+          return {}.freeze unless metadata.is_a?(Hash)
+
+          metadata.to_h.transform_keys(&:to_s).freeze
         end
       end
     end

data/app/services/command_tower/messaging/rendering/inbox_document.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Frozen v1 Inbox content document. Rendered at read (never persisted) by
+      # `InboxDocumentRenderer`. Blocks are plain frozen Hashes, not nested
+      # `Data` objects, so `#to_h` is already the exact JSON-serializable shape
+      # the `content` response key needs — no extra conversion at the
+      # serializer boundary.
+      #
+      # This value object only guarantees the envelope (`schema` tag, `blocks`
+      # is an Array); block-level construction and validation is
+      # `InboxDocumentRenderer`'s responsibility.
+      InboxDocument = Data.define(:schema, :blocks)
+
+      # Reopened (rather than defined inside the `Data.define` block) so that
+      # `SCHEMA_V1` and `.build` attach to `InboxDocument` under normal
+      # lexical constant scoping — a block passed to `Data.define` does not
+      # change the lexical scope for constant assignment the way `class ...
+      # end` does.
+      class InboxDocument
+        SCHEMA_V1 = "inbox_document_v1"
+
+        def self.build(blocks:)
+          raise ArgumentError, "blocks must be an Array" unless blocks.is_a?(Array)
+          raise ArgumentError, "arbitrary hashes are not accepted as blocks entries" if blocks.any? { |b| !b.is_a?(Hash) }
+
+          new(schema: SCHEMA_V1, blocks: blocks.freeze).freeze
+        end
+
+        # Small pure-Ruby authoring DSL (Rich Messaging Slice 2.5 revision —
+        # replaces `inbox_document.json.erb` entirely; see
+        # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md).
+        # A notification-type Inbox document composer calls `.compose` and
+        # authors an ordered document via exactly three methods:
+        #
+        #   doc.paragraph "..."
+        #   doc.cta "label", path: "/internal/route"
+        #   doc.cta "label", href: "https://external.example/..."
+        #   doc.presentation "pickem.make_picks", variant: :compact
+        #
+        # `cta` takes exactly one of `path:` (an internal, origin-free
+        # destination the host's own navigation owns) or `href:` (an
+        # absolute external URL opened via the platform's normal external-
+        # link handling). The composer — which already knows whether a
+        # destination is its own app's route or a third-party URL — states
+        # that intent explicitly via a typed `destination`, rather than
+        # having the frontend infer it from an absolute URL (Slice 2.6.4;
+        # see artifacts/visual-improvements/rich-messaging/plans/
+        # 2.6.4-ct-fe-inbox-navigation-capability.md).
+        # `presentation` intentionally has no `data:`/`props:` argument at
+        # all — the message type may only *name* a registered presentation
+        # capability. Its data is composed separately, post-authoring, by
+        # `InboxDocumentRenderer` and the registered presentation composer
+        # (Rich Messaging Presentation Authority §8). There is no argument
+        # slot to violate that boundary with.
+        def self.compose
+          builder = Builder.new
+          yield builder
+          build(blocks: builder.blocks)
+        end
+
+        class Builder
+          UNSAFE_SCHEMES = %w[javascript data vbscript].freeze
+          DEFAULT_CTA_LABEL = "Open"
+
+          def initialize
+            @blocks = []
+          end
+
+          def paragraph(text)
+            return self unless text.is_a?(String) && !text.empty?
+
+            @blocks << { type: "paragraph", text: }.freeze
+            self
+          end
+
+          def cta(label, path: nil, href: nil)
+            destination = cta_destination(path:, href:)
+            return self unless destination
+
+            resolved_label = label.is_a?(String) && !label.strip.empty? ? label : DEFAULT_CTA_LABEL
+            @blocks << { type: "cta", label: resolved_label, destination: }.freeze
+            self
+          end
+
+          def presentation(key, variant: nil)
+            @blocks << { type: "presentation", key: key.to_s, variant: variant&.to_s }.freeze
+            self
+          end
+
+          def blocks
+            @blocks
+          end
+
+          private
+
+          # Internal takes precedence when both are supplied — a `cta` only
+          # ever means one navigation intent, and a composer that mistakenly
+          # supplies both almost certainly means the internal one.
+          def cta_destination(path:, href:)
+            if safe_internal_path?(path)
+              { kind: "internal", path: }
+            elsif safe_href?(href)
+              { kind: "external", href: }
+            end
+          end
+
+          # A leading `//` is rejected even though it "starts with a slash" —
+          # it is a protocol-relative URL (browsers/RN resolve it against
+          # whatever scheme is active), not a safe same-app-only destination.
+          def safe_internal_path?(path)
+            path.is_a?(String) && path.start_with?("/") && !path.start_with?("//")
+          end
+
+          def safe_href?(href)
+            return false unless href.is_a?(String) && !href.strip.empty?
+
+            scheme = URI.parse(href).scheme&.downcase
+            scheme.present? && UNSAFE_SCHEMES.exclude?(scheme)
+          rescue URI::InvalidURIError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/rendering/inbox_document_renderer.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Internal Messaging::Rendering collaborator (peer of `ChannelRenderer`,
+      # not a host-facing service). Builds the `InboxDocument` shown at Inbox
+      # detail read time.
+      #
+      # Generic path: one `paragraph` block from `communication.body`, plus an
+      # optional `cta` block with a typed `destination` — internal
+      # (`metadata["deep_link_path"]`, origin-free, host-navigation-owned) if
+      # present and safe, else external (`metadata["deep_link"]`) if that is
+      # a safe href (D-INBOX-GENERIC; typed destination added Slice 2.6.4).
+      #
+      # Optional per-`notification_type_key` override: a pure-Ruby composer
+      # class (`declaration.inbox_document_composer`, resolved via
+      # `NotificationTypes.lookup` + `.constantize`), `.call(communication:) ->
+      # InboxDocument`. Any failure (unregistered type, absent composer,
+      # unresolvable class name, a raising composer, or a composer returning
+      # something other than an `InboxDocument`) fails open to the generic
+      # document — the Inbox read path must never 500 on a bad type composer
+      # (D-INBOX-TYPE). This replaces the Rich Messaging Campaign 2 ERB/JSON
+      # authoring path entirely — see
+      # artifacts/visual-improvements/rich-messaging/authority/RICH_MESSAGING_RUBY_INBOX_DEFINITION_DISCOVERY.md.
+      #
+      # After the document (type-specific or generic) is built, any
+      # `"presentation"` block is resolved against
+      # `CommandTower.config.registry.inbox_presentations` — at most one
+      # attempted/resolved presentation capability per document (Rich
+      # Messaging Slice 2.5). The budget is consumed the instant a
+      # `"presentation"`-typed block is seen, before lookup or composition,
+      # regardless of outcome, so a malformed/unregistered first node cannot
+      # fail open and then let a second node still execute composer domain
+      # I/O.
+      #
+      # The composer's raw result is always projected down to the
+      # registration's declared `output_keys` before it reaches
+      # `content.blocks[].data` (corrective slice — presentation
+      # ServiceResult/context leak fix). Composer inputs and any other
+      # incidental context/result keys never reach the wire, regardless of
+      # whether the composer is `ApplicationService`-shaped or a plain Hash.
+      class InboxDocumentRenderer
+        UNSAFE_SCHEMES = %w[javascript data vbscript].freeze
+        DEFAULT_CTA_LABEL = "Open"
+
+        def self.render(communication:, recipient_id:)
+          new(communication:, recipient_id:).render
+        end
+
+        def initialize(communication:, recipient_id:)
+          @communication = communication
+          @recipient_id = recipient_id
+          @presentation_attempted = false
+        end
+
+        def render
+          document = build_from_type_composer || build_generic
+
+          resolve_presentation_blocks(document)
+        end
+
+        private
+
+        attr_reader :communication, :recipient_id
+
+        def build_from_type_composer
+          declaration = CommandTower::Messaging::NotificationTypes.lookup(communication.notification_type_key)
+          composer_name = declaration.inbox_document_composer
+          return nil if composer_name.nil?
+
+          document = composer_name.constantize.call(communication:)
+          document.is_a?(InboxDocument) ? document : nil
+        rescue StandardError
+          # Fail-open: unregistered type, unresolvable class name, a raising
+          # composer, or a composer returning invalid data must never surface
+          # as a 500 on the Inbox read path (D-INBOX-TYPE).
+          nil
+        end
+
+        def build_generic
+          blocks = []
+          blocks << paragraph_block(communication.body) if communication.body.present?
+          cta = generic_cta_block
+          blocks << cta if cta
+
+          InboxDocument.build(blocks:)
+        end
+
+        # Re-walks the already-validated blocks array (produced either by a
+        # trusted Ruby composer via `InboxDocument::Builder` or by
+        # `build_generic`), resolving any `"presentation"` node in place.
+        # There is no untrusted JSON to parse/whitelist here — every block was
+        # already constructed via a whitelisted `Builder` method or this
+        # class's own `paragraph_block`/`cta_block` helpers.
+        def resolve_presentation_blocks(document)
+          resolved = document.blocks.map do |block|
+            block[:type] == "presentation" ? presentation_block(block) : block
+          end.compact
+
+          InboxDocument.build(blocks: resolved)
+        end
+
+        def presentation_block(block)
+          return nil if @presentation_attempted
+
+          @presentation_attempted = true
+          key = block[:key]
+          variant = block[:variant]
+
+          definition = CommandTower.config.registry.inbox_presentations.fetch(key)
+          composer_result = definition.composer_class.constantize.call(communication:, recipient_id:)
+
+          # Duck-typed: a registered composer may be a plain class returning a
+          # Hash directly, or a `CommandTower::Services::ApplicationService`
+          # (whose `.call` always returns a `ServiceResult`) — either way the
+          # unwrapped result below is a plain Hash (Rich Messaging Presentation
+          # Authority's composer contract).
+          if composer_result.respond_to?(:success?)
+            return nil unless composer_result.success?
+
+            raw_data = composer_result.data
+          else
+            raw_data = composer_result
+          end
+
+          # Explicit output projection (corrective slice — presentation
+          # ServiceResult/context leak fix): only the keys the presentation's
+          # own registration declares in `output_keys` ever reach
+          # `content.blocks[].data`. This is a declared allow-list owned by
+          # the registration, not an inference from `ApplicationService`
+          # argument metadata — composer inputs (e.g. `communication`,
+          # `recipient_id` on an `ApplicationService`-shaped composer),
+          # incidental intermediate context/result keys, and anything else
+          # are dropped unconditionally here, independent of composer shape.
+          { type: "presentation", key:, variant:, data: raw_data.to_h.slice(*definition.output_keys) }.freeze
+        rescue StandardError
+          # Fail-open: unregistered capability, unresolvable composer class,
+          # or a raising/failing composer must never surface as a 500 on the
+          # Inbox read path, and must never allow a subsequent presentation
+          # block in the same document to still attempt composition (the
+          # budget above is consumed regardless of this outcome).
+          nil
+        end
+
+        def paragraph_block(text)
+          return nil unless text.is_a?(String)
+          return nil if text.empty?
+
+          { type: "paragraph", text: }.freeze
+        end
+
+        def generic_cta_block
+          cta_block(
+            label: metadata_value("cta_label"),
+            path: metadata_value("deep_link_path"),
+            href: metadata_value("deep_link")
+          )
+        end
+
+        # Internal (`path`) takes precedence over external (`href`) when
+        # both are present — a `cta` only ever means one navigation intent
+        # (Slice 2.6.4 typed destination; see artifacts/visual-improvements/
+        # rich-messaging/plans/2.6.4-ct-fe-inbox-navigation-capability.md).
+        def cta_block(label:, path: nil, href: nil)
+          destination = cta_destination(path:, href:)
+          return nil unless destination
+
+          resolved_label = label.is_a?(String) && !label.strip.empty? ? label : DEFAULT_CTA_LABEL
+          { type: "cta", label: resolved_label, destination: }.freeze
+        end
+
+        def cta_destination(path:, href:)
+          if safe_internal_path?(path)
+            { kind: "internal", path: }
+          elsif safe_href?(href)
+            { kind: "external", href: }
+          end
+        end
+
+        # A leading `//` is rejected even though it "starts with a slash" —
+        # it is a protocol-relative URL, not a safe same-app-only destination.
+        def safe_internal_path?(path)
+          path.is_a?(String) && path.start_with?("/") && !path.start_with?("//")
+        end
+
+        def safe_href?(href)
+          return false unless href.is_a?(String) && !href.strip.empty?
+
+          scheme = URI.parse(href).scheme&.downcase
+          scheme.present? && UNSAFE_SCHEMES.exclude?(scheme)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def metadata_value(key)
+          metadata = communication.metadata
+          return nil unless metadata.is_a?(Hash)
+
+          metadata[key] || metadata[key.to_sym]
+        end
+      end
+    end
+  end
+end