command_tower 0.4.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 634d9c131508812e791849829e9cfe172b41c2508d25d3eefbad69a61ecb4228
-  data.tar.gz: c2c38369dd2c60e1656e0f607bda06518d32590baba669c05c1072e6cf6ac97b
+  metadata.gz: d2becbc85a78f04d571714ca6a99a1442cc0bc9c270a322fe25d8d3881af9252
+  data.tar.gz: ab5432203fd213f203bdd1e5fc2af0ea81a873c5b0ee9fdd25afa357aca50988
 SHA512:
-  metadata.gz: 12c681eeaeefcb8ed919cbb2b0eaf77849c74eccec569d99ead80e1cafecd0b69c106ed12c8902b2e294f1886cd8b148a1ab798a46695e059bd6f92eaa9d2ff0
-  data.tar.gz: a28884515dc4d80c789e62a1b0971c8fadbb2dcdd3d5ad3c3df6d2b6740bbea5c2c378418b604b171eb42e2ba7c4adc8a89087e6ffc53981b8ee7771e7f8495a
+  metadata.gz: 8622b2e00ceb1218df245a00aad41f17e8840779e2f4b91531cdeecc6316bfa18305ce06c569e5a92582819875c87a58acb8ef396cfdcecfcc69752715e99671
+  data.tar.gz: 391cca33f7e186d24fa8f904be8a4f3dad6f5cb12d9615c84e54da2b0e59dc2fb4f49c8bd4279ca41083e204e8735e5864a575fc9c09e5de6694ce2afc2ace94

data/README.md

@@ -1,62 +1,139 @@
 # CommandTower
-This is an API only base engine to build on top of. This Engine takes care of all Authentication, Token Refresh, and RBAC Roles so that you do not have to! For all applications, you can get right to work on implementing the code directly related to your project rather than dealing with the administrative overhead.
 
-While this gem is heavily opinionated, everything can be configured to your liking.
+CommandTower is a mountable **Rails engine** that provides shared platform capabilities for host applications: JWT authentication, RBAC authorization, account/Me surfaces, messaging HTTP (inbox, preferences, endpoints), admin announcements, and shared test factories.
 
-## Installation
-Add this line to your application's Gemfile:
+Hosts mount the engine, configure secrets and product policy, and build product features on top—without re-implementing platform foundations.
+
+The engine is opinionated and configurable. Architecture follows a stable layer map (workflows orchestrate; services implement capabilities). See [Architecture](docs/architecture.md).
+
+## Quick start
 
 ```ruby
+# Gemfile
 gem "command_tower"
 ```
 
-And then execute:
 ```bash
-$ bundle
+bundle install
+bin/rails command_tower:install
+bin/rails db:migrate
+bin/rails command_tower:doctor
 ```
 
-Or install it yourself as:
-```bash
-$ gem install command_tower
+Full install, upgrade, configuration, and troubleshooting: [Initializing CommandTower](docs/initializing.md).
+
+After install, complete RBAC, feature gates, and a Me smoke check: [Host integration guide](docs/host_integration_guide.md) (**start here for a new Rails host**).
+
+## Architecture
+
+```text
+Controller / Job → Workflow → Shared Sequences / Services → Models & Clients
 ```
 
-## Initializing CommandTower
-Please follow all steps in [Initializing CommandTower](docs/initializing.md)
+- Controllers are transport adapters (one workflow per action).
+- Workflows orchestrate a business action.
+- Services (including `CommandTower::ServiceBase`) implement one capability.
+
+See [Architecture](docs/architecture.md) and [ServiceBase](app/services/command_tower/README.md).
+
+## Documentation
+
+| 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.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 |
+| [Models](docs/models.md) | `User`, `UserSecret`, reopening classes |
+| [Authentication](docs/authentication.md) | JWT auth quick start |
+| [Authorization](docs/authorization.md) | RBAC quick start |
+| [Authentication & authorization guide](docs/authentication_authorization_guide.md) | Deep authn + RBAC |
+| [Cookie authentication](docs/cookie_authentication_guide.md) | HttpOnly cookies, CORS, CSRF |
+| [Sensitive changes](docs/sensitive_routes.md) | Verifier token / session invalidation |
+| [Messaging](docs/messaging_integration_guide.md) | Current messaging surfaces |
+| [Pagination](docs/pagination.md) | Pagination helpers |
+| [ServiceBase](app/services/command_tower/README.md) | Service capability base |
+| [Password reset workflow](docs/password_reset_workflow.md) | Forgot-password flow |
+| [Change password workflow](docs/change_password_workflow.md) | Authenticated password change |
+| [Email verification workflow](docs/email_verification_workflow.md) | Email verification flow |
+
+## Installation and configuration
+
+See [Initializing CommandTower](docs/initializing.md) for:
+
+- `command_tower:install` / `install:migrations`
+- Configure generator flags (`SKIP_CONFIGURE`, `SKIP_MOUNT`, `FORCE`)
+- Schema ownership (**AD-SCH-01**)
+- Secrets and doctor checks
+- Existing customized hosts
+
+## Testing
+
+Shared factories for hosts:
+
+```ruby
+require "command_tower/testing"
+CommandTower::Testing.install!
+```
 
+Details: [Testing with CommandTower](docs/testing.md).
 
-## Available Routes
+Engine HTTP coverage lives primarily under `spec/requests/`. Residual journey coverage may remain under `spec/integration_test/`.
 
-For more info, check out [Controllers ReadMe](docs/controllers.md)
+## Routes
 
-Additionally, You can check out [RSpec Integration Testing](/spec/integration_test)
+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).
 
-## Available Models
+## Models
 
-CommandTower provides several Models at the in the root namespace. Core Models like `User` and `UserSecret` are readily available. Don't forget! You can add additional methods to these classes by opening them back up.
+Core models such as `User` and `UserSecret` are available for hosts to use and reopen carefully. See [Models](docs/models.md).
 
-For more info, check out [Models ReadMe](docs/models.md)
+## Authentication (JWT)
 
-## Authentication (JWT BearerToken)
-Authentication ensures that we know which user is requesting the action. When the Engine is unable to authenticate, a `401` status code is returned.
+Authentication establishes identity (`401` when it fails).
 
-For more info, check out [Authentication ReadMe](docs/authentication.md)
+- **Engine controllers** use `authenticate_request!` / `authorize_request!` (Authentication/Authorization boundaries) and return the application envelope.
+- **Host controllers** may use provisional `before_action :authenticate_user!` (failure shapes can differ — see the deep guide).
+
+- Quick start: [Authentication](docs/authentication.md)
+- Deep guide: [Authentication & authorization](docs/authentication_authorization_guide.md)
+- Web / SPA cookies: [Cookie authentication](docs/cookie_authentication_guide.md)
+
+Cookie mode supports HttpOnly JWT cookies, SameSite, optional double-submit CSRF, and secure cookies in production.
 
 ## Authorization (RBAC)
-Authorization is only done after authentication. This is the act of ensuring that the user can perform the action it is requesting. Put differently, I know who you are, but I need to validate you have permissions to complete the action. When the engine is unable to authorize the user, a `403` status code is returned.
 
-For more info, check out [Authentication ReadMe](docs/authorization.md)
+Authorization establishes permission after authentication (`403` when it fails).
+
+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)
 
-## Sensitive Changes
+## Sensitive changes
 
-For more info, check out [Sensitive Routes](docs/sensitive_routes.md)
+JWT tokens embed a `verifier_token` bound to the user. Rotating the verifier invalidates outstanding sessions. See [Sensitive changes](docs/sensitive_routes.md).
 
-## ServiceBase
-ServiceBase is built on top of Interactor. The ServiceBase is the heart of all logic for CommandTower. It includes Logging and enhanced ArgumentValidation that can directly return back to the API request.
+## Messaging
 
-For more info, check out [ServiceBase ReadMe](app/services/command_tower/README.md)
+Modern messaging surfaces: Me Inbox consume, Produce / ProduceMany emit, admin announcements. See [Messaging](docs/messaging_integration_guide.md).
 
 ## Pagination
-Pagination is available on routes when explicitly set. There are a subset of routes available as part of this engine. Pagination is available to be used in downstream services as well. For more info, check out [Pagination ReadMe](docs/pagination.md)
+
+Pagination helpers are available for controllers and services. See [Pagination](docs/pagination.md).
+
+## Services
+
+`CommandTower::ServiceBase` adds logging and argument validation for **service** classes under workflows. See [ServiceBase](app/services/command_tower/README.md).
 
 ## License
-The engine is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+MIT — see [MIT-LICENSE](MIT-LICENSE).

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    AuthContext = Data.define(
+      :user,
+      :token_expires_at,
+      :token_source,
+      :roles,
+      :principal_type,
+      :generated_token,
+      :actor_user,
+      :impersonation_session_id
+    ) do
+      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:,
+          actor_user: actor_user || user,
+          impersonation_session_id:
+        )
+      end
+
+      def self.from_authenticate_session_result(data:, metadata:)
+        new(
+          user: data[:user],
+          token_expires_at: data[:token_expires_at],
+          token_source: metadata[:token_source],
+          roles: data[:user].roles,
+          principal_type: :user,
+          generated_token: data[:generated_token],
+          actor_user: data[:actor_user] || data[:user],
+          impersonation_session_id: data[:impersonation_session_id]
+        )
+      end
+    end
+  end
+end

data/app/auth/command_tower/auth/password_recovery_session_context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    PasswordRecoverySessionContext = Data.define(:jti, :expires_at, :client_ip) do
+      def remaining_seconds
+        [expires_at.to_i - Time.now.to_i, 0].max
+      end
+    end
+  end
+end

data/app/auth/command_tower/auth/signup_session_context.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    SignupSessionContext = Data.define(:jti, :expires_at, :client_ip) do
+      def remaining_seconds
+        [expires_at.to_i - Time.now.to_i, 0].max
+      end
+    end
+  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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Admin
+    module Messaging
+      class AnnouncementsController < CommandTower::Admin::ApplicationController
+        def create
+          deserialized = CommandTower::Deserializers::Admin::Messaging::CreateAnnouncementDeserializer.call(params)
+          unless deserialized.success?
+            return render_application_result(
+              CommandTower::Workflows::WorkflowResult.failure(
+                errors: [CommandTower::Errors::ValidationError.new(details: { base: "Invalid request parameters" })],
+                http_status: :unprocessable_entity
+              )
+            )
+          end
+
+          render_application_result(
+            CommandTower::Workflows::Admin::Messaging::CreateAnnouncementWorkflow.call(
+              input: deserialized.input
+            )
+          )
+        end
+      end
+    end
+  end
+end

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