command_tower 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 726d34845596392ec87fbeacf508323aa72fbfa73d87094e40f0747595450ae9
-  data.tar.gz: 7f1ff986df01e27008e33867e80039a406534e57801111334e3e3c3798705e13
+  metadata.gz: d2becbc85a78f04d571714ca6a99a1442cc0bc9c270a322fe25d8d3881af9252
+  data.tar.gz: ab5432203fd213f203bdd1e5fc2af0ea81a873c5b0ee9fdd25afa357aca50988
 SHA512:
-  metadata.gz: 065535eb260884b0982e56e94c071d2d0707133a62e033d74db8c0d3eaed6c5629b924c8a4a27c007cbb9636aee5198070ef7b3a395cde9a77b1c0bb9661a4e0
-  data.tar.gz: dfd1337b02b1a6350a8ab5ba16316b77b219a47a383f294f42404dbb78f522f13cc0996e045a2dc9e758f4db0fd05f67bc80cfa2ebd6d9fc970e7db48508a211
+  metadata.gz: 8622b2e00ceb1218df245a00aad41f17e8840779e2f4b91531cdeecc6316bfa18305ce06c569e5a92582819875c87a58acb8ef396cfdcecfcc69752715e99671
+  data.tar.gz: 391cca33f7e186d24fa8f904be8a4f3dad6f5cb12d9615c84e54da2b0e59dc2fb4f49c8bd4279ca41083e204e8735e5864a575fc9c09e5de6694ce2afc2ace94

data/README.md

@@ -41,10 +41,14 @@ See [Architecture](docs/architecture.md) and [ServiceBase](app/services/command_
 | Guide | Purpose |
 |-------|---------|
 | [Host integration](docs/host_integration_guide.md) | **Start here** — step-by-step new Rails host path |
-| [Upgrades](docs/upgrades/README.md) | Release upgrade summaries (see [0.10.0](docs/upgrades/0.10.0.md)) |
+| [Upgrades](docs/upgrades/README.md) | Release upgrade summaries (see [0.11.0](docs/upgrades/0.11.0.md)) |
 | [Initializing](docs/initializing.md) | Install, configure, migrate, doctor, upgrades |
 | [Testing](docs/testing.md) | Shared FactoryBot / `CommandTower::Testing` |
 | [Architecture](docs/architecture.md) | Layer map for hosts and contributors |
+| [Eventing](docs/eventing.md) | ASN grammar, lifecycle vs semantic, envelope, subscriber failure |
+| [Audit](docs/audit.md) | Registered `audit(...)` + append-only `command_tower_audit_events` ledger |
+| [Admin Workspace](docs/admin_workspace.md) | Tool registry + RBAC-filtered `GET /admin/workspace` manifest |
+| [Principal capabilities](docs/principal_capabilities.md) | Curated FE-projectable ids via `GET /auth/principal-capabilities` |
 | [Controllers / routes](docs/controllers.md) | Engine route areas (index) |
 | [API reference](docs/api_reference.md) | Endpoint catalog (detailed contracts) |
 | [Extending](docs/extending.md) | Stable extension points / do-not-extend |
@@ -86,7 +90,7 @@ Engine HTTP coverage lives primarily under `spec/requests/`. Residual journey co
 
 ## Routes
 
-Engine routes cover Auth, Me (profile, inbox, preferences, phone, Pushover), and Admin messaging announcements. Index: [Controllers](docs/controllers.md). Contracts: [API reference](docs/api_reference.md).
+Engine routes cover Auth, Me (profile, inbox, preferences, phone, Pushover), Admin Workspace manifest, admin audit events, and Admin messaging announcements. Index: [Controllers](docs/controllers.md). Contracts: [API reference](docs/api_reference.md).
 
 ## Models
 
@@ -109,7 +113,7 @@ Cookie mode supports HttpOnly JWT cookies, SameSite, optional double-submit CSRF
 
 Authorization establishes permission after authentication (`403` when it fails).
 
-Engine defaults ship `owner` and `admin` (announcements). Hosts **must** supply `rbac_groups.yml` entities for Me/Auth surfaces (fail-closed). Host controllers may use provisional `authorize_user!` after `authenticate_user!`.
+Engine defaults ship `owner` (full access) plus CT-owned Me/Auth and Admin **entity** definitions. CommandTower does **not** ship an operational `admin` role. Hosts supply `rbac_groups.yml` **product roles** that grant those entity names (fail-closed), including any operational Admin bundles. Do not copy CT controller mappings. Host controllers may use provisional `authorize_user!` after `authenticate_user!`.
 
 - Quick start: [Authorization](docs/authorization.md)
 - Deep guide: [Authentication & authorization](docs/authentication_authorization_guide.md)

data/app/auth/command_tower/auth/auth_context.rb

@@ -8,16 +8,20 @@ module CommandTower
       :token_source,
       :roles,
       :principal_type,
-      :generated_token
+      :generated_token,
+      :actor_user,
+      :impersonation_session_id
     ) do
-      def initialize(user:, token_expires_at:, token_source:, roles:, principal_type:, generated_token: nil)
+      def initialize(user:, token_expires_at:, token_source:, roles:, principal_type:, generated_token: nil, actor_user: nil, impersonation_session_id: nil)
         super(
           user:,
           token_expires_at:,
           token_source:,
           roles:,
           principal_type:,
-          generated_token:
+          generated_token:,
+          actor_user: actor_user || user,
+          impersonation_session_id:
         )
       end
 
@@ -28,7 +32,9 @@ module CommandTower
           token_source: metadata[:token_source],
           roles: data[:user].roles,
           principal_type: :user,
-          generated_token: data[:generated_token]
+          generated_token: data[:generated_token],
+          actor_user: data[:actor_user] || data[:user],
+          impersonation_session_id: data[:impersonation_session_id]
         )
       end
     end

data/app/controllers/command_tower/admin/application_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    class ApplicationController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+      before_action :reject_admin_operations_during_impersonation!
+
+      private
+
+      def reject_admin_operations_during_impersonation!
+        return unless CommandTower::Current.impersonation_active
+
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [CommandTower::Errors::Auth::AdminUnavailableDuringImpersonationError.new],
+            http_status: 418
+          )
+        )
+      end
+    end
+  end
+end

data/app/controllers/command_tower/admin/audit/events_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    module Audit
+      class EventsController < CommandTower::Admin::ApplicationController
+        def index
+          deserialized = CommandTower::Deserializers::Audit::Events::AdminListDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Audit::Events::ListForAdminWorkflow.call(
+              limit: deserialized.input.limit,
+              offset: deserialized.input.offset,
+              actions: deserialized.input.actions,
+              occurred_after: deserialized.input.occurred_after,
+              occurred_before: deserialized.input.occurred_before,
+              subject_types: deserialized.input.subject_types,
+              affected_user_id: deserialized.input.affected_user_id,
+              actor_user_id: deserialized.input.actor_user_id,
+              originating_administrator_id: deserialized.input.originating_administrator_id,
+              attribution_mode: deserialized.input.attribution_mode,
+              user: current_user,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        def show
+          deserialized = CommandTower::Deserializers::Audit::Events::ShowDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Audit::Events::ShowForAdminWorkflow.call(
+              id: deserialized.input.id,
+              user: current_user,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        def filter_options
+          render_application_result(
+            CommandTower::Workflows::Audit::Events::FilterOptionsForAdminWorkflow.call
+          )
+        end
+
+        private
+
+        def render_deserializer_errors
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/admin/messaging/announcements_controller.rb

@@ -3,14 +3,7 @@
 module CommandTower
   module Admin
     module Messaging
-      class AnnouncementsController < CommandTower::ApplicationController
-        include CommandTower::Auth::AuthenticationBoundary
-        include CommandTower::Auth::AuthorizationBoundary
-        include CommandTower::Api::ApplicationResponseRenderer
-
-        before_action :authenticate_request!
-        before_action :authorize_request!
-
+      class AnnouncementsController < CommandTower::Admin::ApplicationController
         def create
           deserialized = CommandTower::Deserializers::Admin::Messaging::CreateAnnouncementDeserializer.call(params)
           unless deserialized.success?

data/app/controllers/command_tower/admin/users/identities_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    module Users
+      class IdentitiesController < CommandTower::Admin::ApplicationController
+        def update_name
+          deserialized = CommandTower::Deserializers::Admin::Users::UpdateNameDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Admin::Users::UpdateNameWorkflow.call(
+              id: deserialized.input.id,
+              user: current_user,
+              first_name: deserialized.input.first_name,
+              last_name: deserialized.input.last_name,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        def update_username
+          deserialized = CommandTower::Deserializers::Admin::Users::UpdateUsernameDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Admin::Users::UpdateUsernameWorkflow.call(
+              id: deserialized.input.id,
+              user: current_user,
+              username: deserialized.input.username,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        def update_email
+          deserialized = CommandTower::Deserializers::Admin::Users::UpdateEmailDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Admin::Users::UpdateEmailWorkflow.call(
+              id: deserialized.input.id,
+              user: current_user,
+              email: deserialized.input.email,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        def update_email_validation
+          deserialized = CommandTower::Deserializers::Admin::Users::UpdateEmailValidationDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Admin::Users::SetEmailValidatedWorkflow.call(
+              id: deserialized.input.id,
+              user: current_user,
+              email_validated: deserialized.input.email_validated,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        private
+
+        def render_deserializer_errors
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/admin/users/impersonation_sessions_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    module Users
+      class ImpersonationSessionsController < CommandTower::Admin::ApplicationController
+        def create
+          deserialized = CommandTower::Deserializers::Admin::Users::ShowDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Impersonation::StartWorkflow.call(
+              id: deserialized.input.id,
+              actor: current_user,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        private
+
+        def render_deserializer_errors
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/admin/users/roles_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    module Users
+      class RolesController < CommandTower::Admin::ApplicationController
+        def index
+          render_application_result(
+            CommandTower::Workflows::Admin::Users::ListAssignableRolesWorkflow.call
+          )
+        end
+
+        def update
+          deserialized = CommandTower::Deserializers::Admin::Users::UpdateRolesDeserializer.call(params)
+          return render_deserializer_errors unless deserialized.success?
+
+          render_application_result(
+            CommandTower::Workflows::Admin::Users::UpdateRolesWorkflow.call(
+              id: deserialized.input.id,
+              user: current_user,
+              roles: deserialized.input.roles,
+              scope_value: deserialized.input.scope_value
+            )
+          )
+        end
+
+        private
+
+        def render_deserializer_errors
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/admin/users_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    class UsersController < CommandTower::Admin::ApplicationController
+      def index
+        deserialized = CommandTower::Deserializers::Admin::Users::ListDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        render_application_result(
+          CommandTower::Workflows::Admin::Users::ListWorkflow.call(
+            limit: deserialized.input.limit,
+            offset: deserialized.input.offset,
+            search: deserialized.input.search,
+            user: current_user,
+            scope_value: deserialized.input.scope_value
+          )
+        )
+      end
+
+      def show
+        deserialized = CommandTower::Deserializers::Admin::Users::ShowDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        render_application_result(
+          CommandTower::Workflows::Admin::Users::ShowWorkflow.call(
+            id: deserialized.input.id,
+            user: current_user,
+            scope_value: deserialized.input.scope_value
+          )
+        )
+      end
+
+      private
+
+      def render_deserializer_errors
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+            http_status: :unprocessable_entity
+          )
+        )
+      end
+    end
+  end
+end

data/app/controllers/command_tower/admin/workspace_controller.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    class WorkspaceController < CommandTower::Admin::ApplicationController
+      skip_before_action :reject_admin_operations_during_impersonation!, only: :show
+
+      def show
+        render_application_result(
+          CommandTower::Workflows::Admin::Workspace::ManifestWorkflow.call(user: current_user)
+        )
+      end
+    end
+  end
+end

data/app/controllers/command_tower/application_controller.rb

@@ -2,6 +2,8 @@
 
 module CommandTower
   class ApplicationController < ActionController::API
+    include CommandTower::Execution::HttpBoundary
+
     AUTHENTICATION_HEADER = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_HEADER
     AUTHENTICATION_EXPIRE_HEADER = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_EXPIRE_HEADER
     AUTHENTICATION_WITH_RESET = CommandTower::Jwt::AuthorizationHelper::AUTHENTICATION_WITH_RESET
@@ -46,7 +48,21 @@ module CommandTower
       with_reset = CommandTower::Jwt::AuthorizationHelper.get_with_reset_flag(request)
       result = CommandTower::Jwt::AuthenticateUser.(token:, bypass_email_validation:, with_reset:)
       if result.success?
-        @current_user = result.user
+        established = CommandTower::Impersonation::EstablishIdentity.call(
+          actor: result.user,
+          impersonation_session_id: result.impersonation_session_id
+        )
+        if established.expired?
+          status = 401
+          schema = CommandTower::Schema::Error::Base.new(
+            status:,
+            message: CommandTower::Errors::Auth::ImpersonationSessionExpiredError.new.message
+          )
+          render(json: schema.to_h, status:)
+          return false
+        end
+
+        @current_user = established.user
         if with_reset
           # Use helper to set both headers and cookie (if enabled)
           CommandTower::Jwt::AuthorizationHelper.set_token(

data/app/controllers/command_tower/auth/impersonation_session_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    class ImpersonationSessionController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Api::ApplicationResponseRenderer
+
+      before_action :authenticate_stop_request!
+
+      def destroy
+        result = CommandTower::Workflows::Impersonation::StopWorkflow.call(
+          actor: current_auth_context.actor_user,
+          impersonation_session_id: current_auth_context.impersonation_session_id,
+          token_expires_at: current_auth_context.token_expires_at
+        )
+        render_application_result(result)
+      end
+
+      private
+
+      def authenticate_stop_request!
+        authenticate_request!(overlay_mode: :capture)
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/logout_controller.rb

@@ -6,7 +6,9 @@ module CommandTower
       include CommandTower::Api::ApplicationResponseRenderer
 
       def create
-        result = CommandTower::Workflows::Auth::LogoutWorkflow.call
+        token_data = CommandTower::Jwt::AuthorizationHelper.extract_token(request)
+        token = token_data[:error] ? nil : token_data[:token]
+        result = CommandTower::Workflows::Auth::LogoutWorkflow.call(token:)
         render_application_result(result)
       end
     end

data/app/controllers/command_tower/auth/principal_capabilities_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    class PrincipalCapabilitiesController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+
+      def show
+        render_application_result(
+          CommandTower::Workflows::Auth::PrincipalCapabilities::ShowWorkflow.call(user: current_user)
+        )
+      end
+    end
+  end
+end

data/app/controllers/command_tower/me/audit_events_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Me
+    class AuditEventsController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+
+      def index
+        deserialized = CommandTower::Deserializers::Audit::Events::UserListDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        render_application_result(
+          CommandTower::Workflows::Audit::Events::ListForUserWorkflow.call(
+            user: current_user,
+            limit: deserialized.input.limit,
+            offset: deserialized.input.offset,
+            actions: deserialized.input.actions,
+            occurred_after: deserialized.input.occurred_after,
+            occurred_before: deserialized.input.occurred_before,
+            subject_types: deserialized.input.subject_types
+          )
+        )
+      end
+
+      def show
+        deserialized = CommandTower::Deserializers::Audit::Events::ShowDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        render_application_result(
+          CommandTower::Workflows::Audit::Events::ShowForUserWorkflow.call(
+            user: current_user,
+            id: deserialized.input.id
+          )
+        )
+      end
+
+      def filter_options
+        render_application_result(
+          CommandTower::Workflows::Audit::Events::FilterOptionsForUserWorkflow.call
+        )
+      end
+
+      private
+
+      def render_deserializer_errors
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+            http_status: :unprocessable_entity
+          )
+        )
+      end
+    end
+  end
+end

data/app/controllers/concerns/command_tower/api/application_response_renderer.rb

@@ -14,6 +14,11 @@ module CommandTower
                    data: result.payload,
                    meta: result.meta
                  )
+               elsif result.deferred?
+                 CommandTower::Serializers::Application::EnvelopeSerializer.success(
+                   data: result.payload,
+                   meta: result.meta.merge(reason: result.reason, retry_after: result.retry_after)
+                 )
                else
                  serialized_errors = result.errors.map do |error|
                    CommandTower::Serializers::Application::ErrorEntrySerializer.serialize(error)

data/app/controllers/concerns/command_tower/auth/authentication_boundary.rb

@@ -13,11 +13,12 @@ module CommandTower
 
       private
 
-      def authenticate_request!(bypass_email_validation: false)
+      def authenticate_request!(bypass_email_validation: false, overlay_mode: :enforce)
         result = CommandTower::Workflows::Auth::AuthenticateRequestWorkflow.call(
           request: request,
           response: response,
-          bypass_email_validation: bypass_email_validation
+          bypass_email_validation: bypass_email_validation,
+          overlay_mode: overlay_mode
         )
 
         unless result.success?

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Execution
+    module HttpBoundary
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :command_tower_http_execution
+      end
+
+      private
+
+      def command_tower_http_execution
+        request_id = request.request_id.presence || request.uuid
+        CommandTower.with_execution(
+          source: :http,
+          request_id:,
+          correlation_id: request_id,
+          remote_ip: request.remote_ip,
+          user_agent: request.user_agent
+        ) do
+          yield
+          record_impersonation_activity_if_needed
+        end
+      end
+
+      def record_impersonation_activity_if_needed
+        return unless CommandTower::Current.impersonation_active
+        return unless CommandTower::Current.impersonation_activity_recorded
+        return unless response.status.to_i.between?(200, 299)
+
+        session_id = CommandTower::Current.impersonation_session_id
+        return if session_id.blank?
+
+        result = CommandTower::Services::Impersonation::RecordActivity.call(session_id:)
+        return unless result.success?
+        return unless result.data[:refreshed]
+
+        merge_impersonation_clock_meta!(result.data[:session])
+      end
+
+      def merge_impersonation_clock_meta!(session)
+        return if session.nil?
+
+        raw = response.body
+        return if raw.blank?
+
+        parsed = JSON.parse(raw)
+        return unless parsed.is_a?(Hash)
+
+        parsed["meta"] ||= {}
+        parsed["meta"]["impersonation"] = {
+          "idleExpiresAt" => CommandTower::Serializers::ApplicationSerializer.iso8601(session.idle_expires_at),
+          "absoluteExpiresAt" => CommandTower::Serializers::ApplicationSerializer.iso8601(session.absolute_expires_at)
+        }
+        json = parsed.to_json
+        response.body = json
+        response.headers["Content-Length"] = json.bytesize.to_s
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end