command_tower 0.10.0 → 0.11.1

data/lib/command_tower/audit/emit.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "command_tower/audit/attribution"
+require "command_tower/audit/payload"
+
+module CommandTower
+  module Audit
+    module Emit
+      module_function
+
+      def call(name:, subject: nil, affected_user: nil, changes: {}, metadata: {}, attribution_mode: nil, subject_label: nil, scope_class: :global, host_context: nil)
+        registry_name = normalized_event_name(name)
+        definition = CommandTower.config.registry.audit.fetch(registry_name)
+        return nil unless definition.enabled?
+
+        assert_subject!(definition, subject)
+        affected_user_id = extract_user_id(affected_user, required: definition.affected_user_required)
+        validated_changes = Payload.validate_changes!(changes || {}, allowed_keys: definition.allowed_changes)
+        validated_metadata = Payload.validate_metadata!(metadata)
+        attribution = Attribution.resolve(affected_user_id:, attribution_mode:)
+        snapshot = subject_snapshot(subject, subject_label)
+        normalized_scope_class = normalize_scope_class!(scope_class)
+        host_context_fields = normalize_host_context!(host_context, scope_class: normalized_scope_class)
+
+        CommandTower::Events.publish_audit(
+          name: registry_name,
+          envelope: attribution.merge(snapshot).merge(host_context_fields).merge(
+            action: registry_name,
+            occurred_at: Time.now.utc.iso8601(6),
+            scope_class: normalized_scope_class,
+            changes: validated_changes,
+            metadata: validated_metadata
+          )
+        )
+      end
+
+      def normalized_event_name(name)
+        CommandTower.config.registry.audit.fetch(name)
+        name.to_s.split(".").map { |segment| CommandTower::Events.normalize_segment(segment, field: "name") }.join(".")
+      end
+
+      def assert_subject!(definition, subject)
+        return unless definition.subject_required
+        return unless subject.nil?
+
+        raise MissingSubjectError, "audit event requires a subject"
+      end
+
+      def extract_user_id(value, required:)
+        if value.nil?
+          raise MissingAffectedUserError, "audit event requires an affected user" if required
+
+          return nil
+        end
+
+        return value if value.is_a?(Integer)
+        return value.id if value.respond_to?(:id)
+
+        raise InvalidPayloadError, "affected_user must be a user or id"
+      end
+
+      def subject_snapshot(subject, subject_label)
+        label = subject_label.nil? ? nil : subject_label.to_s
+        if subject.nil?
+          return { subject_type: nil, subject_id: nil, subject_label: label }
+        end
+
+        unless subject.respond_to?(:id)
+          raise InvalidPayloadError, "subject must provide an id"
+        end
+
+        {
+          subject_type: subject.class.name,
+          subject_id: subject.id,
+          subject_label: label
+        }
+      end
+
+      def normalize_scope_class!(value)
+        token = value.to_sym
+        normalized = CommandTower::Audit::Event::SCOPE_CLASSES[token]
+        unless normalized
+          raise InvalidPayloadError,
+            "scope_class must be one of #{CommandTower::Audit::Event::SCOPE_CLASSES.keys.join(", ")}"
+        end
+
+        normalized
+      end
+
+      def normalize_host_context!(host_context, scope_class:)
+        host_scope = CommandTower::Audit::Event::SCOPE_CLASSES[:host]
+        if scope_class != host_scope
+          return { host_context_type: nil, host_context_identifier: nil }
+        end
+
+        unless host_context.is_a?(Hash)
+          raise InvalidPayloadError, "host_context is required when scope_class is host"
+        end
+
+        context_type = host_context[:type] || host_context["type"]
+        context_identifier = host_context[:identifier] || host_context["identifier"]
+        if context_type.to_s.strip.empty? || context_identifier.to_s.strip.empty?
+          raise InvalidPayloadError, "host_context requires type and identifier when scope_class is host"
+        end
+
+        {
+          host_context_type: context_type.to_s.strip,
+          host_context_identifier: context_identifier.to_s.strip
+        }
+      end
+    end
+  end
+end

data/lib/command_tower/audit/masking.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    module Masking
+      REDACTED = "********"
+
+      module_function
+
+      def value(field:, raw:)
+        return if raw.nil?
+        return REDACTED unless scalar?(raw)
+
+        string = raw.to_s
+        case field.to_s
+        when "phone" then phone(string)
+        when "email" then email(string)
+        else REDACTED
+        end
+      end
+
+      def phone(string)
+        digits = string.gsub(/\D/, "")
+        return REDACTED if digits.length < 4
+
+        "#{'*' * 7}#{digits[-4, 4]}"
+      end
+
+      def email(string)
+        local, domain = string.split("@", 2)
+        return REDACTED if local.blank? || domain.blank?
+
+        "#{local[0]}***@#{domain}"
+      end
+
+      def scalar?(raw)
+        raw.is_a?(String) || raw.is_a?(Numeric)
+      end
+    end
+  end
+end

data/lib/command_tower/audit/payload.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CommandTower
+  module Audit
+    module Payload
+      SCALAR_TYPES = [NilClass, TrueClass, FalseClass, Integer, Float, String, Symbol].freeze
+      MAX_DEPTH = 4
+      MAX_BYTES = 16_384
+      CHANGE_KEYS = %w[from to].freeze
+
+      module_function
+
+      def validate!(value, depth: 0, path: "payload")
+        if depth > MAX_DEPTH
+          raise InvalidPayloadError, "#{path} exceeds max nesting depth #{MAX_DEPTH}"
+        end
+
+        case value
+        when Hash
+          value.each do |key, nested|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise InvalidPayloadError, "#{path} has a non-string key #{key.inspect}"
+            end
+
+            validate!(nested, depth: depth + 1, path: "#{path}.#{key}")
+          end
+        when Array
+          value.each_with_index do |item, index|
+            validate!(item, depth: depth + 1, path: "#{path}[#{index}]")
+          end
+        else
+          unless SCALAR_TYPES.any? { |type| value.is_a?(type) }
+            raise InvalidPayloadError, "#{path} contains unsafe type #{value.class}"
+          end
+        end
+
+        value
+      end
+
+      def validate_changes!(changes, allowed_keys:)
+        unless changes.nil? || changes.is_a?(Hash)
+          raise InvalidPayloadError, "changes must be a Hash"
+        end
+
+        normalized = {}
+        (changes || {}).each do |key, value|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise InvalidPayloadError, "changes has a non-string key #{key.inspect}"
+          end
+
+          token = key.to_s
+          unless token.match?(CommandTower::Events::SEGMENT)
+            raise InvalidPayloadError, "changes key #{key.inspect} is invalid"
+          end
+
+          unless allowed_keys.map(&:to_s).include?(token)
+            raise ForbiddenChangeKeyError,
+              "changes key #{token} is not allowed (allowed: #{allowed_keys.join(", ").presence || "none"})"
+          end
+
+          unless value.is_a?(Hash)
+            raise InvalidPayloadError, "changes.#{token} must be a Hash with from/to"
+          end
+
+          extra = value.keys.map(&:to_s) - CHANGE_KEYS
+          if extra.any? || (value.keys.map(&:to_s) & CHANGE_KEYS).empty?
+            raise InvalidPayloadError, "changes.#{token} must use from/to keys only"
+          end
+
+          from_value = value.key?(:from) ? value[:from] : value["from"]
+          to_value = value.key?(:to) ? value[:to] : value["to"]
+          validate!(from_value, depth: 2, path: "changes.#{token}.from")
+          validate!(to_value, depth: 2, path: "changes.#{token}.to")
+          normalized[token] = { "from" => from_value, "to" => to_value }
+        end
+
+        enforce_size!(normalized)
+        normalized
+      end
+
+      def validate_metadata!(metadata)
+        unless metadata.nil? || metadata.is_a?(Hash)
+          raise InvalidPayloadError, "metadata must be a Hash"
+        end
+
+        validated = metadata || {}
+        validate!(validated, path: "metadata")
+        enforce_size!(validated)
+        stringify_keys(validated)
+      end
+
+      def enforce_size!(value)
+        encoded = JSON.generate(jsonify(value))
+        return if encoded.bytesize <= MAX_BYTES
+
+        raise InvalidPayloadError, "audit payload exceeds #{MAX_BYTES} bytes"
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested), memo|
+            memo[key.to_s] = stringify_keys(nested)
+          end
+        when Array
+          value.map { |item| stringify_keys(item) }
+        else
+          value
+        end
+      end
+
+      def jsonify(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(key, nested), memo| memo[key.to_s] = jsonify(nested) }
+        when Array
+          value.map { |item| jsonify(item) }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/audit/persistence/subscriber.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    module Persistence
+      class Subscriber
+        PATTERN = /\Acommand_tower\.audit(?:\.|\z)/
+
+        class << self
+          def attach!
+            detach!
+            subscriber = new
+            @subscriptions = [
+              ActiveSupport::Notifications.subscribe(PATTERN) do |name, started, finished, id, payload|
+                event = ActiveSupport::Notifications::Event.new(name, started, finished, id, payload)
+                subscriber.call(event)
+              end
+            ]
+          end
+
+          def detach!
+            Array(@subscriptions).each { |subscription| ActiveSupport::Notifications.unsubscribe(subscription) }
+            @subscriptions = []
+          end
+
+          def subscriptions
+            Array(@subscriptions)
+          end
+        end
+
+        def call(event)
+          payload = event.payload.to_h.with_indifferent_access
+          return unless persistable?(payload)
+
+          persist!(payload)
+        end
+
+        private
+
+        def persistable?(payload)
+          payload[:action].present? && payload[:event_uuid].present?
+        end
+
+        def persist!(payload)
+          action = payload.fetch(:action).to_s
+          definition = CommandTower.config.registry.audit.fetch(action)
+
+          CommandTower::Audit::Event.create!(
+            event_uuid: payload.fetch(:event_uuid),
+            action: action,
+            occurred_at: parse_occurred_at(payload.fetch(:occurred_at)),
+            scope_class: payload.fetch(:scope_class).to_s,
+            host_context_type: payload[:host_context_type],
+            host_context_identifier: payload[:host_context_identifier],
+            execution_uuid: payload[:execution_uuid],
+            correlation_id: payload[:correlation_id],
+            request_id: payload[:request_id],
+            causation_id: payload[:causation_id],
+            source: payload[:source]&.to_s,
+            actor_user_id: payload[:actor_user_id],
+            affected_user_id: payload[:affected_user_id],
+            effective_user_id: payload[:effective_user_id],
+            originating_administrator_id: payload[:originating_administrator_id],
+            impersonation_active: payload[:impersonation_active] == true,
+            attribution_mode: payload.fetch(:attribution_mode).to_s,
+            subject_type: payload[:subject_type],
+            subject_id: payload[:subject_id],
+            subject_label: payload[:subject_label],
+            change_set: payload[:changes] || {},
+            metadata: payload[:metadata] || {},
+            user_history: definition.user_history,
+            sensitive_fields: Array(definition.sensitive_fields).map(&:to_s),
+            retention: definition.retention.to_s
+          )
+        end
+
+        def parse_occurred_at(value)
+          return value if value.is_a?(Time) || value.is_a?(ActiveSupport::TimeWithZone)
+
+          Time.iso8601(value.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/command_tower/audit.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    class Error < CommandTower::Error; end
+
+    class UnregisteredEventError < Error; end
+    class DuplicateEventError < Error; end
+    class HostOverrideError < Error; end
+    class InvalidEventNameError < Error; end
+    class ForbiddenChangeKeyError < Error; end
+    class InvalidPayloadError < Error; end
+    class InvalidAttributionError < Error; end
+    class MissingSubjectError < Error; end
+    class MissingAffectedUserError < Error; end
+    class FrozenRegistryError < Error; end
+    class InvalidEventDefinitionError < Error; end
+    class EnablementNotConfigurableError < Error; end
+    class ImmutableError < Error; end
+  end
+end
+
+require "command_tower/audit/payload"
+require "command_tower/audit/attribution"
+require "command_tower/audit/emit"
+require "command_tower/audit/masking"
+require "command_tower/audit/persistence/subscriber"

data/lib/command_tower/authorization/assignable_roles.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Authorization
+    module AssignableRoles
+      OWNER_NAME = "owner"
+
+      module_function
+
+      def catalog
+        CommandTower::Authorization::Role.roles.values
+          .select { |role| assignable?(role) }
+          .sort_by { |role| role.name.to_s }
+          .map do |role|
+            { name: role.name.to_s, description: role.description.to_s }
+          end
+      end
+
+      def names
+        catalog.map { |entry| entry[:name] }.to_set
+      end
+
+      def assignable?(role)
+        return false if role.nil?
+        return false if role.allow_everything
+        return false if role.name.to_s == OWNER_NAME
+
+        role.source == :host
+      end
+
+      def assignable_name?(name)
+        names.include?(name.to_s)
+      end
+    end
+  end
+end

data/lib/command_tower/authorization/default.yml

@@ -3,12 +3,106 @@ groups:
   owner:
     description: The owner of the application will have full access to all components
     entities: true
-  admin:
-    description: |
-      Platform admin role for modern Engine admin surfaces (e.g. messaging announcements).
-    entities:
-      - admin_messaging_announcements
 entities:
+  - name: email_verification_send
+    controller: CommandTower::Auth::EmailVerification::SendController
+    only: create
+  - name: email_verification_verify
+    controller: CommandTower::Auth::EmailVerification::VerifyController
+    only: create
+  - name: session
+    controller: CommandTower::Auth::SessionController
+    only: show
+  - name: me
+    controller: CommandTower::MeController
+    only: show
+  - name: profile
+    controller: CommandTower::ProfileController
+    only: show
+  - name: me_name
+    controller: CommandTower::Me::NameController
+    only: update
+  - name: me_password
+    controller: CommandTower::Me::PasswordController
+    only: update
+  - name: me_inbox
+    controller: CommandTower::Me::InboxController
+    only:
+      - index
+      - show
+      - open
+      - archive
+      - destroy
+      - unread_count
+      - bulk_read
+      - bulk_unread
+      - bulk_archive
+      - bulk_restore
+      - bulk_delete
+  - name: me_preferences
+    controller: CommandTower::Me::PreferencesController
+    only:
+      - show
+      - update
+  - name: me_phone
+    controller: CommandTower::Me::PhoneController
+    only:
+      - update
+      - destroy
+  - name: me_phone_verification_send
+    controller: CommandTower::Me::PhoneVerification::VerificationsController
+    only: create
+  - name: me_phone_verification_verify
+    controller: CommandTower::Me::PhoneVerification::VerifyController
+    only: create
+  - name: me_pushover
+    controller: CommandTower::Me::PushoverController
+    only:
+      - show
+      - create
+      - update
+      - destroy
+  - name: me_pushover_verification
+    controller: CommandTower::Me::Pushover::VerificationsController
+    only: create
+  - name: me_audit_events
+    controller: CommandTower::Me::AuditEventsController
+    only:
+      - index
+      - show
+      - filter_options
   - name: admin_messaging_announcements
     controller: CommandTower::Admin::Messaging::AnnouncementsController
     only: create
+  - name: admin_audit_events
+    controller: CommandTower::Admin::Audit::EventsController
+    only:
+      - index
+      - show
+      - filter_options
+  - name: admin_workspace
+    controller: CommandTower::Admin::WorkspaceController
+    only: show
+  - name: admin_users
+    controller: CommandTower::Admin::UsersController
+    only:
+      - index
+      - show
+  - name: admin_users_update
+    controller: CommandTower::Admin::Users::IdentitiesController
+    only:
+      - update_name
+      - update_username
+      - update_email
+      - update_email_validation
+  - name: admin_rbac_assignments
+    controller: CommandTower::Admin::Users::RolesController
+    only:
+      - index
+      - update
+  - name: admin_impersonation
+    controller: CommandTower::Admin::Users::ImpersonationSessionsController
+    only: create
+  - name: principal_capabilities
+    controller: CommandTower::Auth::PrincipalCapabilitiesController
+    only: show

data/lib/command_tower/authorization/effective_entity_grants.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Authorization
+    # Composed RBAC graph → effective entity name sets.
+    # Backend policy only. Not a frontend authorization shortcut.
+    module EffectiveEntityGrants
+      ALL = :all
+
+      module_function
+
+      def allow_everything?(user)
+        Array(user.roles).any? do |role_name|
+          role = CommandTower::Authorization::Role.roles[role_name]
+          role&.allow_everything
+        end
+      end
+
+      def for_user(user)
+        return ALL if allow_everything?(user)
+
+        for_role_names(Array(user.roles))
+      end
+
+      def for_role_names(role_names)
+        names = Array(role_names).map(&:to_s)
+        if names.any? { |name| CommandTower::Authorization::Role.roles[name]&.allow_everything }
+          return ALL
+        end
+
+        names.each_with_object(Set.new) do |name, grants|
+          role = CommandTower::Authorization::Role.roles[name]
+          next unless role
+
+          role.entities.each { |entity| grants << entity.name.to_s }
+        end
+      end
+
+      def for_role(role_name)
+        for_role_names([role_name])
+      end
+
+      def includes?(grants, entity_name)
+        grants == ALL || grants.include?(entity_name.to_s)
+      end
+
+      def subset?(candidate_grants, actor_grants)
+        return true if actor_grants == ALL
+        return false if candidate_grants == ALL
+
+        candidate_grants.subset?(actor_grants)
+      end
+    end
+  end
+end

data/lib/command_tower/authorization/entity.rb

@@ -4,13 +4,21 @@ module CommandTower
   module Authorization
     class Entity
       class << self
-        def create_entity(name:, controller:, only: nil, except: nil)
+        def create_entity(name:, controller:, only: nil, except: nil, source: :host)
           if entities[name]
-            Rails.logger.warn("Warning: Authorization entity #{name} duplicated. Only the most recent one will persist")
+            raise Error, "Authorization entity [#{name}] already exists. Hosts must not redefine CommandTower-owned entities."
           end
 
-          entities[name] = new(name:, controller:, only:, except:)
+          entity = new(name:, controller:, only:, except:, source:)
 
+          if source.to_sym == :host
+            ct_controllers = entities.values.select { |existing| existing.source == :command_tower }.map(&:controller)
+            if ct_controllers.include?(entity.controller)
+              raise Error, "Host entity [#{name}] redefines CommandTower-owned controller [#{entity.controller}]"
+            end
+          end
+
+          entities[name] = entity
           entities[name]
         end
 
@@ -23,11 +31,13 @@ module CommandTower
         end
       end
 
-      attr_reader :name, :controller, :only, :except
-      def initialize(name:, controller:, only: nil, except: nil)
+      attr_reader :name, :controller, :only, :except, :source
+      def initialize(name:, controller:, only: nil, except: nil, source: :host)
         @controller = controller
         @except = except.nil? ? nil : Array(except).map(&:to_sym)
         @only = only.nil? ? nil : Array(only).map(&:to_sym)
+        @source = source.to_sym
+        @name = name
 
         validate!
       end

data/lib/command_tower/authorization/role.rb

@@ -4,7 +4,7 @@ module CommandTower
   module Authorization
     class Role
       class << self
-        def create_role(name:, description:, entities: nil, allow_everything: false)
+        def create_role(name:, description:, entities: nil, allow_everything: false, source: :host)
           if roles[name]
             raise Error, "Role [#{name}] already exists. Must use different name"
           end
@@ -17,7 +17,7 @@ module CommandTower
             end
           end
 
-          roles[name] = new(name:, description:, entities:, allow_everything:)
+          roles[name] = new(name:, description:, entities:, allow_everything:, source:)
           # A role is `intended` to be immutable (attr_reader)
           # Once the role is defined it will not get changed
           # After it is created, add the mapping to the source of truth list of mapped method names to their controllers
@@ -35,12 +35,13 @@ module CommandTower
         end
       end
 
-      attr_reader :entities, :name, :description, :allow_everything
-      def initialize(name:, description:, entities:, allow_everything: false)
+      attr_reader :entities, :name, :description, :allow_everything, :source
+      def initialize(name:, description:, entities:, allow_everything: false, source: :host)
         @name = name
         @entities = Array(entities)
         @description = description
         @allow_everything = allow_everything
+        @source = source.to_sym
       end
 
       def authorized?(controller:, method:, user:)