command_tower 0.4.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 634d9c131508812e791849829e9cfe172b41c2508d25d3eefbad69a61ecb4228
-  data.tar.gz: c2c38369dd2c60e1656e0f607bda06518d32590baba669c05c1072e6cf6ac97b
+  metadata.gz: 726d34845596392ec87fbeacf508323aa72fbfa73d87094e40f0747595450ae9
+  data.tar.gz: 7f1ff986df01e27008e33867e80039a406534e57801111334e3e3c3798705e13
 SHA512:
-  metadata.gz: 12c681eeaeefcb8ed919cbb2b0eaf77849c74eccec569d99ead80e1cafecd0b69c106ed12c8902b2e294f1886cd8b148a1ab798a46695e059bd6f92eaa9d2ff0
-  data.tar.gz: a28884515dc4d80c789e62a1b0971c8fadbb2dcdd3d5ad3c3df6d2b6740bbea5c2c378418b604b171eb42e2ba7c4adc8a89087e6ffc53981b8ee7771e7f8495a
+  metadata.gz: 065535eb260884b0982e56e94c071d2d0707133a62e033d74db8c0d3eaed6c5629b924c8a4a27c007cbb9636aee5198070ef7b3a395cde9a77b1c0bb9661a4e0
+  data.tar.gz: dfd1337b02b1a6350a8ab5ba16316b77b219a47a383f294f42404dbb78f522f13cc0996e045a2dc9e758f4db0fd05f67bc80cfa2ebd6d9fc970e7db48508a211

data/README.md

@@ -1,62 +1,135 @@
 # 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.10.0](docs/upgrades/0.10.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 |
+| [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), 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` 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!`.
+
+- 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,36 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    AuthContext = Data.define(
+      :user,
+      :token_expires_at,
+      :token_source,
+      :roles,
+      :principal_type,
+      :generated_token
+    ) do
+      def initialize(user:, token_expires_at:, token_source:, roles:, principal_type:, generated_token: nil)
+        super(
+          user:,
+          token_expires_at:,
+          token_source:,
+          roles:,
+          principal_type:,
+          generated_token:
+        )
+      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]
+        )
+      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/messaging/announcements_controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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!
+
+        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/application_controller.rb

@@ -2,9 +2,9 @@
 
 module CommandTower
   class ApplicationController < ActionController::API
-    AUTHENTICATION_HEADER = "Authentication"
-    AUTHENTICATION_EXPIRE_HEADER = "X-Authentication-Expire"
-    AUTHENTICATION_WITH_RESET = "X-Authentication-Reset"
+    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
 
     def safe_boolean(value:)
       return nil unless [true, false, "true", "false", "0", "1", 0, 1].include?(value)
@@ -13,30 +13,84 @@ module CommandTower
     end
 
     ###
-    # Authenticate user via the passed in header
-    # AUTHENTICATION_HEADER="Bearer: {token value}"
+    # Authenticate user via the passed in header or cookie
+    # AUTHENTICATION_HEADER="Bearer {token value}" or cookie (if enabled)
     def authenticate_user!(bypass_email_validation: false)
-      raw_token = request.headers[AUTHENTICATION_HEADER]
-      if raw_token.nil?
+      # Extract and validate token (from header or cookie fallback)
+      token_data = CommandTower::Jwt::AuthorizationHelper.extract_token(request)
+      if token_data[:error]
         status = 401
-        schema = CommandTower::Schema::Error::Base.new(status:, message: "Bearer token missing")
+        schema = CommandTower::Schema::Error::Base.new(status:, message: token_data[:message])
         render(json: schema.to_h, status:)
         return false
       end
 
-      token = raw_token.split("Bearer:")[1].strip
-      with_reset = safe_boolean(value: request.headers[AUTHENTICATION_WITH_RESET])
+      token = token_data[:token]
+      token_source = token_data[:source]
+
+      # CSRF validation for cookie-authenticated unsafe requests
+      # Enforcement is centralized here because token_source is only reliably known in this shared filter
+      if csrf_required?(request, token_source)
+        csrf_validation = CommandTower::Jwt::CsrfHelper.validate(request)
+        unless csrf_validation[:valid]
+          status = 403
+          schema = CommandTower::Schema::Error::Base.new(
+            status: status.to_s,
+            message: csrf_validation[:message]  # Stable error code: "csrf_missing" or "csrf_mismatch"
+          )
+          render(json: schema.to_h, status: status)
+          return false
+        end
+      end
+
+      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
-        response.set_header(AUTHENTICATION_EXPIRE_HEADER, result.expires_at)
         if with_reset
-          response.set_header(AUTHENTICATION_WITH_RESET, result.generated_token)
+          # Use helper to set both headers and cookie (if enabled)
+          CommandTower::Jwt::AuthorizationHelper.set_token(
+            response,
+            result.generated_token,
+            expires_at: result.expires_at
+          )
+
+          # Handle CSRF cookie issuance/rotation for token reset path
+          # CSRF cookie issuance rules:
+          # - rotate_on_reset = true → force rotate (generate new token)
+          # - rotate_on_reset = false → ensure exists only (create if missing, keep if exists)
+          if CommandTower::Jwt::CsrfHelper.csrf_enabled?
+            if CommandTower.config.jwt.cookie.csrf.rotate_on_reset
+              CommandTower::Jwt::CsrfHelper.ensure_cookie(request, response, should_rotate: true)
+            else
+              # Ensure cookie exists (rotate-or-ensure model)
+              CommandTower::Jwt::CsrfHelper.ensure_cookie(request, response, should_rotate: false)
+            end
+          end
+        else
+          # Only set expire header when not resetting
+          response.set_header(AUTHENTICATION_EXPIRE_HEADER, result.expires_at)
         end
         true
       else
-        status = 401
-        schema = CommandTower::Schema::Error::Base.new(status:, message: result.msg)
+        # Check if this is an email validation failure (status 412)
+        if result.status == 412
+          status = 412
+          schema = CommandTower::Schema::Error::EmailValidationRequired.new(
+            status:,
+            message: result.msg,
+            meta: { email_validated: false }
+          )
+          # Do NOT clear cookie for 412 status - user needs to keep cookie to verify email
+        else
+          # If authentication failed and token came from cookie, clear the invalid cookie
+          # Exception: Do not clear cookie for 412 status (email validation required)
+          if token_source == :cookie
+            CommandTower::Jwt::AuthorizationHelper.clear_cookie(response)
+          end
+          status = result.status || 401
+          schema = CommandTower::Schema::Error::Base.new(status:, message: result.msg)
+        end
         render(json: schema.to_h, status:)
         # Must return false so callbacks know to halt propagation
         false
@@ -77,5 +131,17 @@ module CommandTower
     def current_user
       @current_user ||= nil
     end
+
+    private
+
+    def csrf_required?(request, token_source)
+      return false unless CommandTower::Jwt::CsrfHelper.csrf_enabled?
+      # CRITICAL: Check token_source, not cookie presence
+      return false unless token_source == :cookie
+      return false if request.get? || request.head? || request.options?
+
+      # Unsafe methods: POST, PUT, PATCH, DELETE
+      %w[POST PUT PATCH DELETE].include?(request.method)
+    end
   end
 end

data/app/controllers/command_tower/auth/email/availability_controller.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module Email
+      class AvailabilityController < CommandTower::ApplicationController
+        include CommandTower::Auth::SignupSessionBoundary
+
+        before_action :authenticate_signup_session!
+
+        def show
+          deserialized = CommandTower::Deserializers::Auth::EmailAvailabilityDeserializer.call(params)
+          return render_email_deserializer_errors unless deserialized.success?
+
+          result = CommandTower::Workflows::Auth::EmailAvailabilityWorkflow.call(
+            input: deserialized.input,
+            signup_session: current_signup_session
+          )
+          render_application_result(result)
+        end
+
+        private
+
+        def render_email_deserializer_errors
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [CommandTower::Errors::ValidationError.new(details: { email: "Email is required" })],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/email_verification/send_controller.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module EmailVerification
+      class SendController < CommandTower::ApplicationController
+        include CommandTower::Auth::AuthenticationBoundary
+        include CommandTower::Auth::AuthorizationBoundary
+
+        # Requesting a verification code is exactly the action an unverified user
+        # needs, so the email verification precondition is bypassed here.
+        before_action -> { authenticate_request!(bypass_email_validation: true) }
+        before_action :authorize_request!
+
+        def create
+          result = CommandTower::Workflows::Auth::EmailVerification::SendWorkflow.call(
+            current_user: current_user
+          )
+          render_application_result(result)
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/email_verification/verify_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module EmailVerification
+      class VerifyController < CommandTower::ApplicationController
+        include CommandTower::Auth::AuthenticationBoundary
+        include CommandTower::Auth::AuthorizationBoundary
+
+        before_action -> { authenticate_request!(bypass_email_validation: true) }
+        before_action :authorize_request!
+
+        def create
+          deserialized = CommandTower::Deserializers::Auth::EmailVerification::VerifyDeserializer.call(params)
+          return render_verify_deserializer_errors unless deserialized.success?
+
+          result = CommandTower::Workflows::Auth::EmailVerification::VerifyWorkflow.call(
+            current_user: current_user,
+            input: deserialized.input
+          )
+          render_application_result(result)
+        end
+
+        private
+
+        def render_verify_deserializer_errors
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [
+                CommandTower::Errors::Auth::VerificationCodeInvalidError.new(
+                  details: { code: "Verification code is required" }
+                )
+              ],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    class IdentityPolicyController < CommandTower::ApplicationController
+      include CommandTower::Api::ApplicationResponseRenderer
+
+      def show
+        result = CommandTower::Workflows::Auth::IdentityPolicyWorkflow.call
+        render_application_result(result)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    class LogoutController < CommandTower::ApplicationController
+      include CommandTower::Api::ApplicationResponseRenderer
+
+      def create
+        result = CommandTower::Workflows::Auth::LogoutWorkflow.call
+        render_application_result(result)
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/password_recovery_session/create_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module PasswordRecoverySession
+      class CreateController < CommandTower::ApplicationController
+        include CommandTower::Api::ApplicationResponseRenderer
+
+        def create
+          client_ip = CommandTower::Services::Auth::ClientIpResolver.call(request: request)
+          result = CommandTower::Workflows::Auth::PasswordRecoverySession::CreateWorkflow.call(client_ip: client_ip)
+          render_application_result(result)
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/password_reset/reset_controller.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module PasswordReset
+      class ResetController < CommandTower::ApplicationController
+        include CommandTower::Api::ApplicationResponseRenderer
+        include CommandTower::Api::DeserializerFailureDetails
+
+        def create
+          deserialized = CommandTower::Deserializers::Auth::PasswordReset::ResetDeserializer.call(params)
+          return render_reset_deserializer_errors(deserialized) unless deserialized.success?
+
+          result = CommandTower::Workflows::Auth::PasswordReset::ResetWorkflow.call(input: deserialized.input)
+          render_application_result(result)
+        end
+
+        private
+
+        def render_reset_deserializer_errors(deserialized)
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [
+                CommandTower::Errors::ValidationError.new(
+                  details: deserializer_failure_details(deserialized)
+                )
+              ],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/password_reset/send_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module PasswordReset
+      class SendController < CommandTower::ApplicationController
+        include CommandTower::Auth::PasswordRecoverySessionBoundary
+        include CommandTower::Api::DeserializerFailureDetails
+
+        before_action :authenticate_password_recovery_session!
+
+        def create
+          deserialized = CommandTower::Deserializers::Auth::PasswordReset::SendDeserializer.call(params)
+          return render_send_deserializer_errors(deserialized) unless deserialized.success?
+
+          result = CommandTower::Workflows::Auth::PasswordReset::SendWorkflow.call(
+            input: deserialized.input,
+            password_recovery_session: current_password_recovery_session
+          )
+          render_application_result(result)
+        end
+
+        private
+
+        def render_send_deserializer_errors(deserialized)
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [
+                CommandTower::Errors::ValidationError.new(
+                  details: deserializer_failure_details(deserialized)
+                )
+              ],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/command_tower/auth/password_reset/validate_controller.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Auth
+    module PasswordReset
+      class ValidateController < CommandTower::ApplicationController
+        include CommandTower::Api::ApplicationResponseRenderer
+        include CommandTower::Api::DeserializerFailureDetails
+
+        def create
+          deserialized = CommandTower::Deserializers::Auth::PasswordReset::ValidateDeserializer.call(params)
+          return render_validate_deserializer_errors(deserialized) unless deserialized.success?
+
+          result = CommandTower::Workflows::Auth::PasswordReset::ValidateWorkflow.call(input: deserialized.input)
+          render_application_result(result)
+        end
+
+        private
+
+        def render_validate_deserializer_errors(deserialized)
+          render_application_result(
+            CommandTower::Workflows::WorkflowResult.failure(
+              errors: [
+                CommandTower::Errors::ValidationError.new(
+                  details: deserializer_failure_details(deserialized)
+                )
+              ],
+              http_status: :unprocessable_entity
+            )
+          )
+        end
+      end
+    end
+  end
+end