command_tower 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d495e295241fa7ac4f9179acc5fd2d4c47fcb8a0603dccdf5353ac08e7c98b28
-  data.tar.gz: 9d56364ffd4a79ad9bcabe07e2713a2613b2d43112039bc5f31db855f3baad2d
+  metadata.gz: a7116094a133d9fc9edaf8cc0851bde09a3c2bebacded3ea64b1f4a7b4f445db
+  data.tar.gz: e4880f05a6c601fb07349d44d27d3a746e10051e8b4ef2b701dc961998862fc4
 SHA512:
-  metadata.gz: f605fe2a8117b8e5b6af32dc7c65df55c9400a33a5d50220f5a0c992efd74f28545a8fbfe8c293982f062f398dcc3b86aa552de12d1ec87f733e5a2d6435169e
-  data.tar.gz: 85072dd065a8589a239166286a2261a331a7cd9c59e0b0c7eb870e5bc60dcfdeb4d32df84671015a93d2edcd3a93592e7647210cf5f553c4a47a346abb214bdb
+  metadata.gz: 3633188b6f62b92945cf142ea65fff20a596420b9c0cc4f907d4688732b4d03f283843277e36ea662091b097f71d39d348f4bd06822604f2dace486b3484df38
+  data.tar.gz: 749c9b86dd4919c072e1a29af779a84bcd65892f1c95b80f06ded36b4e30844c9598eabf050902d13679cfe911c6b6214898236afd6472ef61fb17370a8b7757

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Me
+    class AccountController < CommandTower::ApplicationController
+      include CommandTower::Auth::AuthenticationBoundary
+      include CommandTower::Auth::AuthorizationBoundary
+
+      before_action :authenticate_request!
+      before_action :authorize_request!
+
+      def destroy
+        deserialized = CommandTower::Deserializers::Me::DeleteAccountDeserializer.call(params)
+        return render_deserializer_errors unless deserialized.success?
+
+        result = CommandTower::Workflows::Me::DeleteAccountWorkflow.call(
+          current_user: current_user,
+          password: deserialized.input.password
+        )
+        render_application_result(result)
+      end
+
+      private
+
+      def render_deserializer_errors
+        render_application_result(
+          CommandTower::Workflows::WorkflowResult.failure(
+            errors: [CommandTower::Errors::ValidationError.new(details: { base: "Missing required fields" })],
+            http_status: :unprocessable_entity
+          )
+        )
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/intervention/envelope_deserializer.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Intervention
+      # Parses a canonical intervention envelope from untrusted params/JSON.
+      class EnvelopeDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:action, :allowed, :blockers)
+
+        def call(params)
+          source = normalize_source(params)
+          action = required_text(source[:action] || source["action"], field: "action")
+          return action if deserializer_result?(action)
+
+          allowed_raw = source[:allowed].nil? ? source["allowed"] : source[:allowed]
+          allowed = allowed_raw == true || allowed_raw.to_s == "true"
+
+          blockers_raw = source[:blockers] || source["blockers"] || []
+          unless blockers_raw.is_a?(Array)
+            return failure(errors: [{ field: "blockers", code: "invalid_type", message: "must be an array" }])
+          end
+
+          blockers = []
+          blockers_raw.each_with_index do |row, index|
+            parsed = parse_blocker(row, index)
+            return parsed if deserializer_result?(parsed)
+
+            blockers << parsed
+          end
+
+          success(Input.new(action: action, allowed: allowed, blockers: blockers))
+        end
+
+        private
+
+        def normalize_source(params)
+          return params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
+          return params.to_h if params.respond_to?(:to_h)
+
+          params.is_a?(Hash) ? params : {}
+        end
+
+        def required_text(raw, field:)
+          value = raw.is_a?(String) ? raw.strip : raw.to_s.strip
+          if value.empty?
+            return failure(errors: [{ field: field, code: "missing_required_fields", message: "is required" }])
+          end
+
+          value
+        end
+
+        def parse_blocker(row, index)
+          unless row.is_a?(Hash)
+            return failure(
+              errors: [{ field: "blockers[#{index}]", code: "invalid_type", message: "must be an object" }]
+            )
+          end
+
+          code = required_text(row[:code] || row["code"], field: "blockers[#{index}].code")
+          return code if deserializer_result?(code)
+
+          action = required_text(row[:action] || row["action"], field: "blockers[#{index}].action")
+          return action if deserializer_result?(action)
+
+          title = required_text(row[:title] || row["title"], field: "blockers[#{index}].title")
+          return title if deserializer_result?(title)
+
+          message = required_text(row[:message] || row["message"], field: "blockers[#{index}].message")
+          return message if deserializer_result?(message)
+
+          blocker = {
+            code: code,
+            action: action,
+            title: title,
+            message: message
+          }
+
+          severity = row[:severity] || row["severity"]
+          blocker[:severity] = severity.to_s if severity.present?
+
+          remediation_raw = row[:remediation] || row["remediation"]
+          if remediation_raw.present?
+            remediation = parse_remediation(remediation_raw, index)
+            return remediation if deserializer_result?(remediation)
+
+            blocker[:remediation] = remediation
+          end
+
+          blocker
+        end
+
+        def parse_remediation(row, index)
+          unless row.is_a?(Hash)
+            return failure(
+              errors: [
+                { field: "blockers[#{index}].remediation", code: "invalid_type", message: "must be an object" }
+              ]
+            )
+          end
+
+          kind = required_text(row[:kind] || row["kind"], field: "blockers[#{index}].remediation.kind")
+          return kind if deserializer_result?(kind)
+
+          action = required_text(row[:action] || row["action"], field: "blockers[#{index}].remediation.action")
+          return action if deserializer_result?(action)
+
+          remediation = { kind: kind, action: action }
+          label = row[:label] || row["label"]
+          remediation[:label] = label.to_s if label.present?
+          remediation
+        end
+      end
+    end
+  end
+end

data/app/deserializers/command_tower/deserializers/me/delete_account_deserializer.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Deserializers
+    module Me
+      class DeleteAccountDeserializer < CommandTower::Deserializers::ApplicationDeserializer
+        Input = Data.define(:password)
+
+        def call(params)
+          password = params[:password]
+
+          if blank?(password)
+            return failure(errors: { message: "missing_required_fields" })
+          end
+
+          unless password.is_a?(String)
+            return failure(errors: { message: "invalid_field_types" })
+          end
+
+          success(Input.new(password:))
+        end
+
+        private
+
+        def blank?(value)
+          value.nil? || (value.is_a?(String) && value.strip.empty?)
+        end
+      end
+    end
+  end
+end

data/app/errors/command_tower/errors/auth/account_deleted_error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Errors
+    module Auth
+      class AccountDeletedError < CommandTower::Errors::UnauthorizedError
+        def code
+          "account_deleted"
+        end
+
+        def message
+          "Account has been deleted"
+        end
+
+        def log_level
+          :info
+        end
+      end
+    end
+  end
+end

data/app/models/user.rb

@@ -33,8 +33,14 @@ require "securerandom"
 class User < CommandTower::ApplicationRecord
   has_secure_password
 
-  validates :username, uniqueness: true
-  validates :email, uniqueness: true
+  TOMBSTONE_EMAIL_DOMAIN = "@invalid.local"
+  TOMBSTONE_EMAIL_PREFIX = "deleted+"
+  TOMBSTONE_USERNAME_PREFIX = "deleted_"
+
+  scope :not_deleted, -> { where(deleted_at: nil) }
+
+  validates :username, uniqueness: { conditions: -> { not_deleted } }
+  validates :email, uniqueness: { conditions: -> { not_deleted } }
 
   ###
   # Serialize the roles column to check for inclusion easily
@@ -49,6 +55,18 @@ class User < CommandTower::ApplicationRecord
     "#{first_name} #{last_name}"
   end
 
+  def deleted?
+    deleted_at.present?
+  end
+
+  def self.tombstone_email_for(id)
+    "#{TOMBSTONE_EMAIL_PREFIX}#{id}#{TOMBSTONE_EMAIL_DOMAIN}"
+  end
+
+  def self.tombstone_username_for(id)
+    "#{TOMBSTONE_USERNAME_PREFIX}#{id}"
+  end
+
   def reset_verifier_token!
     value = SecureRandom.alphanumeric(32)
     update!(verifier_token: value, verifier_token_last_reset: Time.now)

data/app/serializers/command_tower/serializers/intervention/blocker_serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Intervention
+      # One presentation-independent blocker fact. No presentation mode / routes / host policy.
+      class BlockerSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(code:, action:, title:, message:, remediation: nil, severity: nil)
+          payload = {
+            code: code.to_s,
+            action: action.to_s,
+            title: title.to_s,
+            message: message.to_s
+          }
+          payload[:severity] = severity.to_s if severity.present?
+          if remediation
+            payload[:remediation] = RemediationSerializer.serialize(**remediation)
+          end
+          payload
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/intervention/envelope_serializer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Intervention
+      # Action-scoped intervention envelope for GET projections and mutation errors.
+      # `blockers` ordered; primary is first. No presentation-mode fields.
+      # Host/CT FE owns presentation modes (callout, intercept, sheet, blocking_region).
+      class EnvelopeSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(action:, allowed:, blockers: [])
+          {
+            action: action.to_s,
+            allowed: allowed == true,
+            blockers: map_serialize(blockers) { |blocker| BlockerSerializer.serialize(**blocker) }
+          }
+        end
+
+        def self.serialize_many(envelopes)
+          map_serialize(envelopes) { |envelope| serialize(**envelope) }
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/intervention/remediation_serializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Intervention
+      # Canonical remediation facts (presentation-independent). Host maps `action` to routes.
+      class RemediationSerializer < CommandTower::Serializers::ApplicationSerializer
+        def self.serialize(kind:, action:, label: nil)
+          payload = {
+            kind: kind.to_s,
+            action: action.to_s
+          }
+          payload[:label] = label.to_s if label.present?
+          payload
+        end
+      end
+    end
+  end
+end

data/app/serializers/command_tower/serializers/me/delete_account_response_serializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Serializers
+    module Me
+      class DeleteAccountResponseSerializer
+        def self.serialize(message:)
+          { message: message }
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/jwt/authenticate_user.rb

@@ -27,7 +27,7 @@ module CommandTower::Jwt
       return invalid_token if expires_at.nil?
 
       user = User.find_by(id: payload[:user_id])
-      if user.nil?
+      if user.nil? || user.deleted?
         log_warn("user_id [#{payload[:user_id]}] was not found. Cannot Continue")
         return invalid_token
       end

data/app/services/command_tower/services/admin/users.rb

@@ -12,7 +12,7 @@ module CommandTower
           validate :scope_context, is_a: [CommandTower::AdminScope::ScopeContext, NilClass], required: false
 
           def call
-            relation = ::User.order(id: :desc)
+            relation = ::User.not_deleted.order(id: :desc)
             relation = CommandTower::AdminScope::ApplyUsersNarrowing.call(
               relation:,
               scope_context:,
@@ -48,7 +48,7 @@ module CommandTower
           validate :scope_context, is_a: [CommandTower::AdminScope::ScopeContext, NilClass], required: false
 
           def call
-            relation = ::User.where(id:)
+            relation = ::User.not_deleted.where(id:)
             relation = CommandTower::AdminScope::ApplyUsersNarrowing.call(
               relation:,
               scope_context:,

data/app/services/command_tower/services/auth/email_availability.rb

@@ -16,7 +16,7 @@ module CommandTower
             return
           end
 
-          if ::User.exists?(email: normalized)
+          if ::User.not_deleted.exists?(email: normalized)
             context.valid = true
             context.available = false
             context.message = "Email is already registered"

data/app/services/command_tower/services/auth/plain_text/login.rb

@@ -9,7 +9,7 @@ module CommandTower
           validate :password, is_a: String, required: true, sensitive: true
 
           def call
-            user = User.where(username: identifier).or(User.where(email: identifier)).first
+            user = User.not_deleted.where(username: identifier).or(User.not_deleted.where(email: identifier)).first
             if user.nil?
               audit_login_failed(affected_user: nil, outcome: "unknown_identifier")
               invalid_credentials!

data/app/services/command_tower/services/auth/purge_user_associated_data.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Auth
+      class PurgeUserAssociatedData < CommandTower::Services::ApplicationService
+        validate :user, is_a: User, required: true
+
+        def call
+          purge_user_secrets!
+          purge_messaging_inbox!
+          purge_messaging_endpoints!
+          revoke_impersonation_sessions!
+        end
+
+        private
+
+        def purge_user_secrets!
+          UserSecret.where(user_id: user.id).delete_all
+        end
+
+        def purge_messaging_inbox!
+          item_ids = CommandTower::Messaging::Inbox::Scope.for_recipient(user.id).pluck(:id)
+          return if item_ids.empty?
+
+          CommandTower::Messaging::Inbox.bulk_delete(recipient_id: user.id, inbox_item_ids: item_ids)
+        end
+
+        def purge_messaging_endpoints!
+          return unless defined?(CommandTower::Messaging::Endpoint)
+
+          CommandTower::Messaging::Endpoint.where(user_id: user.id).find_each(&:destroy!)
+        end
+
+        def revoke_impersonation_sessions!
+          CommandTower::Services::Impersonation::TerminateOpenSessions.call(
+            actor_user_id: user.id,
+            reason: "revoked"
+          )
+
+          CommandTower::Impersonation::Session.open.where(target_user_id: user.id).find_each do |session|
+            CommandTower::Services::Impersonation::End.call(
+              session_id: session.id,
+              reason: "revoked"
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/auth/tombstone_user.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Auth
+      class TombstoneUser < CommandTower::Services::ApplicationService
+        validate :user, is_a: User, required: true
+
+        def call
+          if user.deleted?
+            context.user = user
+            context.changed = false
+            return
+          end
+
+          user_id = user.id
+          scrub_password = SecureRandom.hex(32)
+          user.assign_attributes(
+            deleted_at: Time.current,
+            first_name: "",
+            last_name: "",
+            email: User.tombstone_email_for(user_id),
+            username: User.tombstone_username_for(user_id),
+            phone_number: nil,
+            phone_number_validated: false,
+            email_validated: false,
+            roles: []
+          )
+          user.password = scrub_password
+          user.password_confirmation = scrub_password
+
+          unless user.save(validate: false)
+            context.fail!(
+              application_error: CommandTower::Errors::InternalError.new
+            )
+            return
+          end
+
+          user.reset_verifier_token!
+
+          context.user = user.reload
+          context.changed = true
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/services/me/capabilities.rb

@@ -15,14 +15,15 @@ module CommandTower
 
         def project
           {
-            editName: { enabled: true },
+            editName: { enabled: !user.deleted? },
             editUsername: { enabled: false },
             changeEmail: { enabled: false },
-            changePassword: { enabled: true },
-            editPhone: { enabled: sms_enabled? },
-            editPushover: { enabled: pushover_enabled? },
+            changePassword: { enabled: !user.deleted? },
+            editPhone: { enabled: sms_enabled? && !user.deleted? },
+            editPushover: { enabled: pushover_enabled? && !user.deleted? },
             logoutAllDevices: { enabled: false },
-            verifyEmail: { enabled: !user.email_validated }
+            verifyEmail: { enabled: !user.deleted? && !user.email_validated },
+            deleteAccount: { enabled: !user.deleted? }
           }
         end
 

data/app/services/command_tower/services/me/delete_account.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Services
+    module Me
+      class DeleteAccount < CommandTower::Services::ApplicationService
+        FIELD_KEYS = {
+          password: :password
+        }.freeze
+
+        validate :user, is_a: User, required: true
+        validate :password, is_a: String, required: true, sensitive: true
+
+        def call
+          if user.deleted?
+            context.fail!(
+              application_error: CommandTower::Errors::Auth::AccountDeletedError.new
+            )
+            return
+          end
+
+          reject!(password: "Incorrect password") unless user.authenticate(password)
+
+          infrastructure_failure = false
+
+          ActiveRecord::Base.transaction do
+            unless invoke_host_finalizer!
+              infrastructure_failure = true
+              raise ActiveRecord::Rollback
+            end
+
+            purge_result = CommandTower::Services::Auth::PurgeUserAssociatedData.call(user:)
+            unless purge_result.success?
+              infrastructure_failure = true
+              raise ActiveRecord::Rollback
+            end
+
+            tombstone_result = CommandTower::Services::Auth::TombstoneUser.call(user:)
+            unless tombstone_result.success?
+              infrastructure_failure = true
+              raise ActiveRecord::Rollback
+            end
+
+            user.reload
+            audit(
+              :account_deleted,
+              subject: user,
+              affected_user: user,
+              changes: {},
+              metadata: { mechanism: "self_service" }
+            )
+          end
+
+          if infrastructure_failure
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+            return
+          end
+
+          user.reload
+          unless user.deleted?
+            log_error("Account deletion transaction did not persist for user [#{user.id}]")
+            context.fail!(application_error: CommandTower::Errors::InternalError.new)
+          end
+
+          log_info("Account deleted for user [#{user.id}]")
+          context.message = "Your account has been deleted"
+        end
+
+        private
+
+        def invoke_host_finalizer!
+          finalizer = CommandTower.config.account_deletion.host_finalizer
+          return true if finalizer.nil?
+
+          outcome = finalizer.call(user:)
+          return true if outcome.nil?
+          return true if outcome.respond_to?(:success?) && outcome.success?
+
+          false
+        end
+
+        def reject!(errors)
+          details = errors.each_with_object({}) do |(key, message), mapped|
+            mapped[FIELD_KEYS.fetch(key.to_sym, key)] = message
+          end
+
+          context.fail!(application_error: CommandTower::Errors::ValidationError.new(details:))
+        end
+      end
+    end
+  end
+end

data/app/workflows/command_tower/workflows/me/delete_account_workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Workflows
+    module Me
+      class DeleteAccountWorkflow < CommandTower::Workflows::ApplicationWorkflow
+        retry_strategy :none
+
+        def call(current_user:, password:)
+          delete_result = CommandTower::Services::Me::DeleteAccount.call(
+            user: current_user,
+            password:
+          )
+
+          unless delete_result.success?
+            error = delete_result.errors.first
+            return failure(
+              errors: delete_result.errors,
+              http_status: CommandTower::Workflows::Me::ErrorStatus.http_status_for(error)
+            )
+          end
+
+          success(
+            payload: CommandTower::Serializers::Me::DeleteAccountResponseSerializer.serialize(
+              message: delete_result.data[:message]
+            ),
+            http_status: :ok,
+            response_effects: { clear_token: true }
+          )
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -60,6 +60,7 @@ CommandTower::Engine.routes.draw do
   namespace :me do
     patch "name", to: "name#update"
     patch "password", to: "password#update"
+    delete "account", to: "account#destroy"
 
     resources :inbox, only: [:index, :show, :destroy], controller: "inbox" do
       collection do

data/db/migrate/20260826140000_add_deleted_at_to_users.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddDeletedAtToUsers < ActiveRecord::Migration[7.2]
+  def change
+    add_column :users, :deleted_at, :datetime
+    add_index :users, :deleted_at
+  end
+end

data/docs/admin_workspace.md

@@ -46,7 +46,9 @@ Hosts configure scope behavior on `CommandTower.config.admin_scope` (see [Resour
 
 ## Resource scoping
 
-Optional **host-defined resource scoping** narrows Admin tool data (Users, Audit, …) after RBAC. CommandTower remains **domain-blind** — it does not know League, Season, or tenant semantics.
+Optional **host-defined resource scoping** selects a scope value before entering a tool and, for Users/Audit, narrows Admin tool data after RBAC. CommandTower remains **domain-blind** — it does not know League, Season, or tenant semantics.
+
+Every `admin_scope.register` requires **`options`**, **`validate`**, and **`availability`**. Resource-narrowing hooks (`narrow_users`, `narrow_audit`, `affected_users_in_scope`) are required for CT-owned **`users`** / **`audit`** (or whenever any narrowing hook is set). Product Admin host tools may register the three base hooks only — scope drives Workspace invocation (0/1/N), not CT SQL narrowing.
 
 ```ruby
 CommandTower.configure do |config|
@@ -64,23 +66,41 @@ CommandTower.configure do |config|
     registration.narrow_audit = ->(relation:, scope_value:, principal:, tool_id:) { relation }
     registration.affected_users_in_scope = ->(scope_value:, principal:, tool_id:) { [] }
   end
+
+  # Product Admin host tool — invocation scope only (no Users/Audit narrowing).
+  config.registry.admin_workspace.tool :example_product_admin do |tool|
+    tool.label = "Example Product Admin"
+    tool.route = "/admin/example-product"
+    tool.group = :product
+    tool.sort_order = 300
+    tool.required_entity = :host_example_entity
+    tool.scope_required = true
+    tool.scope_parameter = "resource_slug"
+    tool.scope_label = "Resource"
+  end
+
+  config.admin_scope.register(:example_product_admin) do |registration|
+    registration.options = ->(principal:) { [CommandTower::AdminScope::ScopeOption.new(value: "x", label: "X")] }
+    registration.validate = ->(value:, principal:) { value.to_s == "x" }
+    registration.availability = ->(principal:) { { enabled: true, reason: nil } }
+  end
 end
 ```
 
-| Hook | Purpose |
-|------|---------|
-| `options` | Eager scope choices for manifest (`scopeOptions`) |
-| `availability` | `{ enabled:, reason: }` — disabled tools render non-navigable in FE |
-| `validate` | Authorize requested scope value; fail closed → **403** |
-| `narrow_users` | SQL narrowing for Users list/show |
-| `narrow_audit` | SQL narrowing for host-scoped audit rows |
-| `affected_users_in_scope` | User ids for eligible **global** audit events in scoped admin views |
+| Hook | Purpose | Required |
+|------|---------|----------|
+| `options` | Eager scope choices for manifest (`scopeOptions`) | Always |
+| `availability` | `{ enabled:, reason: }` — disabled tools render non-navigable in FE | Always |
+| `validate` | Authorize requested scope value; fail closed → **403** | Always |
+| `narrow_users` | SQL narrowing for Users list/show | `users` / `audit` only |
+| `narrow_audit` | SQL narrowing for host-scoped audit rows | `users` / `audit` only |
+| `affected_users_in_scope` | User ids for eligible **global** audit events in scoped admin views | `users` / `audit` only |
 
-**HTTP disclosure policy:** missing/malformed/unauthorized scope → **403**; authorized scope + resource absent from narrowed relation (nonexistent **or** out of scope) → **404** (indistinguishable).
+**HTTP disclosure policy** (Users/Audit resource APIs): missing/malformed/unauthorized scope → **403**; authorized scope + resource absent from narrowed relation (nonexistent **or** out of scope) → **404** (indistinguishable).
 
 Unscoped tools (`scope_required: false`, default) behave exactly as before — no scope query param, no `admin_scope` registration required.
 
-Synthetic proof lives in `rails_app` (`FoundationProof::AdminScope`); Pick'em League adoption is Phase 7 only.
+Synthetic proof lives in `rails_app` (`FoundationProof::AdminScope`). Hosts own product-scoped destinations via FE `resolveScopedDestination` — CT does not interpret path params.
 
 ## Seeded CommandTower tools
 

data/docs/upgrades/0.12.0.md

@@ -0,0 +1,26 @@
+# Upgrade: CommandTower 0.12.0
+
+**From:** `0.11.1`  
+**To:** `0.12.0`
+
+Minor release: canonical action-intervention envelope ser/de, and Admin Scope registrations that do not require Users/Audit resource-narrowing for host product tools.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| Intervention envelope | `CommandTower::Serializers::Intervention::EnvelopeSerializer` / `EnvelopeDeserializer` (plus blocker/remediation serializers). Canonical `{ action, allowed, blockers[] }` with ordered blockers; **no** presentation-mode fields. Host/CT FE owns `callout` / `intercept` / `sheet` / `blocking_region`. |
+| Admin Scope hook requirements | Every `admin_scope.register` still requires `options`, `validate`, and `availability`. Resource-narrowing hooks (`narrow_users`, `narrow_audit`, `affected_users_in_scope`) are required for CT-owned **`users`** / **`audit`**, or whenever any narrowing hook is set. Host product tools may register the three base hooks only. |
+
+## Host actions
+
+1. Bump gem to `0.12.0`.
+2. **No new migration.**
+3. To emit interventions from host workflows, serialize with `EnvelopeSerializer` (and `serialize_many` for action maps). Do not invent a parallel envelope shape.
+4. Hosts with scoped product Admin tools can drop unused Users/Audit narrowing hooks from those registrations.
+
+## Not in this release
+
+- Frontend `ActionIntervention` presentation (ships in `@commandtower/frontend`)
+- Changing Users/Audit narrowing requirements
+- New HTTP routes

data/docs/upgrades/0.13.0.md

@@ -0,0 +1,18 @@
+# CommandTower 0.13.0
+
+Account self-service deletion (CANON-020 / M1).
+
+## Host actions
+
+1. `rails command_tower:install:migrations` (adds `users.deleted_at`)
+2. `rails db:migrate`
+3. Grant `me_account` to authenticated member role in `config/rbac_groups.yml`
+4. Optional: register `config.account_deletion.host_finalizer` for product cleanup
+
+## API
+
+- `DELETE /api/me/account` — body `{ "password": "..." }`; clears session on success
+
+## RBAC
+
+New entity: `me_account` → `CommandTower::Me::AccountController#destroy`

data/docs/upgrades/README.md

@@ -3,7 +3,9 @@
 Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
+| [0.13.0](0.13.0.md) | Account self-service deletion (`DELETE /api/me/account`); tombstone + PII scrub; `me_account` RBAC; `users.deleted_at` migration |
 |---------|---------|
+| [0.12.0](0.12.0.md) | Intervention envelope serializers/deserializers; product-tool admin_scope without Users/Audit narrowing |
 | [0.11.1](0.11.1.md) | Audit Event `attribute :json` (MariaDB); audit migration without `utf8mb4_0900_ai_ci` |
 | [0.11.0](0.11.0.md) | Execution context, audit ledger, Admin Workspace, principal capabilities, impersonation, Admin Users |
 | [0.10.0](0.10.0.md) | Modern Auth/Me/Messaging platform; SchemaHelper removal; host RBAC required |

data/lib/command_tower/authorization/default.yml

@@ -25,6 +25,9 @@ entities:
   - name: me_password
     controller: CommandTower::Me::PasswordController
     only: update
+  - name: me_account
+    controller: CommandTower::Me::AccountController
+    only: destroy
   - name: me_inbox
     controller: CommandTower::Me::InboxController
     only:

data/lib/command_tower/configuration/account_deletion/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "class_composer"
+require "command_tower/configuration/base"
+
+module CommandTower
+  module Configuration
+    module AccountDeletion
+      class Config < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        add_composer :host_finalizer,
+          desc: "Optional host-owned callable invoked synchronously during account deletion " \
+                "before the user row is tombstoned. Receives keyword `user:` (non-deleted User). " \
+                "Return value is ignored; raise to abort the deletion transaction.",
+          allowed: [Proc, NilClass],
+          default: nil,
+          default_shown: "nil"
+      end
+    end
+  end
+end

data/lib/command_tower/configuration/admin_scope/tool_registration.rb

@@ -4,13 +4,15 @@ module CommandTower
   module Configuration
     module AdminScope
       class ToolRegistration
-        REQUIRED_HOOKS = %i[options validate availability narrow_users narrow_audit affected_users_in_scope].freeze
+        BASE_HOOKS = %i[options validate availability].freeze
+        RESOURCE_NARROWING_HOOKS = %i[narrow_users narrow_audit affected_users_in_scope].freeze
+        RESOURCE_SCOPED_TOOL_IDS = %w[users audit].freeze
 
         attr_accessor :options, :validate, :availability, :narrow_users, :narrow_audit,
           :affected_users_in_scope, :host_context_type
 
         def validate!(tool_id:)
-          missing = REQUIRED_HOOKS.reject { |hook| callable?(public_send(hook)) }
+          missing = required_hooks_for(tool_id).reject { |hook| callable?(public_send(hook)) }
           return self if missing.empty?
 
           raise CommandTower::AdminScope::InvalidToolRegistrationError,
@@ -19,6 +21,19 @@ module CommandTower
 
         private
 
+        def required_hooks_for(tool_id)
+          hooks = BASE_HOOKS.dup
+          normalized = tool_id.to_s
+          if RESOURCE_SCOPED_TOOL_IDS.include?(normalized) || resource_narrowing_hooks_present?
+            hooks.concat(RESOURCE_NARROWING_HOOKS)
+          end
+          hooks
+        end
+
+        def resource_narrowing_hooks_present?
+          RESOURCE_NARROWING_HOOKS.any? { |hook| !public_send(hook).nil? }
+        end
+
         def callable?(value)
           value.respond_to?(:call)
         end

data/lib/command_tower/configuration/config.rb

@@ -2,6 +2,7 @@
 
 require "singleton"
 require "class_composer"
+require "command_tower/configuration/account_deletion/config"
 require "command_tower/configuration/admin/config"
 require "command_tower/configuration/admin_scope/config"
 require "command_tower/configuration/application/config"
@@ -91,6 +92,11 @@ module CommandTower
         allowed: Configuration::Messaging::Config,
         default: Configuration::Messaging::Config.new
 
+      add_composer :account_deletion,
+        desc: "Account self-service deletion host hooks",
+        allowed: Configuration::AccountDeletion::Config,
+        default: Configuration::AccountDeletion::Config.new
+
       add_composer :admin,
         desc: "Admin configuration for the app",
         allowed: Configuration::Admin::Config,

data/lib/command_tower/configuration/registry/audit/config.rb

@@ -64,6 +64,20 @@ module CommandTower
               affected_user_required: true,
               global_visible_in_host_scope: true
             },
+            account_deleted: {
+              label: "Account deleted",
+              tags: %w[identity account deletion security],
+              enabled: true,
+              enablement_configurable: false,
+              user_history: true,
+              sensitive_fields: [],
+              allowed_changes: [],
+              retention: :permanent,
+              subject_required: true,
+              subject_type: "User",
+              affected_user_required: true,
+              global_visible_in_host_scope: true
+            },
             email_verified: {
               label: "Email verified",
               tags: %w[identity verification email],

data/lib/command_tower/install/baseline.rb

@@ -14,6 +14,7 @@ module CommandTower
         20260816000001_create_command_tower_audit_events.rb
         20260817000001_add_scope_columns_to_command_tower_audit_events.rb
         20260817000003_create_command_tower_impersonation_sessions.rb
+        20260826140000_add_deleted_at_to_users.rb
       ].freeze
 
       module_function

data/lib/command_tower/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandTower
-  VERSION = "0.11.1"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.13.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -209,6 +209,7 @@ files:
 - app/controllers/command_tower/auth/session_controller.rb
 - app/controllers/command_tower/auth/signup_session/create_controller.rb
 - app/controllers/command_tower/auth/username/availability_controller.rb
+- app/controllers/command_tower/me/account_controller.rb
 - app/controllers/command_tower/me/audit_events_controller.rb
 - app/controllers/command_tower/me/inbox_controller.rb
 - app/controllers/command_tower/me/name_controller.rb
@@ -249,7 +250,9 @@ files:
 - app/deserializers/command_tower/deserializers/clients/types.rb
 - app/deserializers/command_tower/deserializers/coercion_result.rb
 - app/deserializers/command_tower/deserializers/failure.rb
+- app/deserializers/command_tower/deserializers/intervention/envelope_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/change_password_deserializer.rb
+- app/deserializers/command_tower/deserializers/me/delete_account_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/phone_verification/verify_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/pushover/credentials_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/update_name_deserializer.rb
@@ -271,6 +274,7 @@ files:
 - app/errors/command_tower/errors/account/pushover_verification_failed_error.rb
 - app/errors/command_tower/errors/account/sms_capability_unavailable_error.rb
 - app/errors/command_tower/errors/application_error.rb
+- app/errors/command_tower/errors/auth/account_deleted_error.rb
 - app/errors/command_tower/errors/auth/admin_unavailable_during_impersonation_error.rb
 - app/errors/command_tower/errors/auth/csrf_mismatch_error.rb
 - app/errors/command_tower/errors/auth/csrf_missing_error.rb
@@ -353,8 +357,12 @@ files:
 - app/serializers/command_tower/serializers/auth/user_serializer.rb
 - app/serializers/command_tower/serializers/auth/username_availability_serializer.rb
 - app/serializers/command_tower/serializers/impersonation/session_serializer.rb
+- app/serializers/command_tower/serializers/intervention/blocker_serializer.rb
+- app/serializers/command_tower/serializers/intervention/envelope_serializer.rb
+- app/serializers/command_tower/serializers/intervention/remediation_serializer.rb
 - app/serializers/command_tower/serializers/me/account_serializer.rb
 - app/serializers/command_tower/serializers/me/change_password_response_serializer.rb
+- app/serializers/command_tower/serializers/me/delete_account_response_serializer.rb
 - app/serializers/command_tower/serializers/me/pushover_serializer.rb
 - app/serializers/command_tower/serializers/messaging/inbox.rb
 - app/serializers/command_tower/serializers/messaging/preferences/catalog_serializer.rb
@@ -615,6 +623,7 @@ files:
 - app/services/command_tower/services/auth/password_reset/validate.rb
 - app/services/command_tower/services/auth/plain_text/login.rb
 - app/services/command_tower/services/auth/principal_capabilities/project.rb
+- app/services/command_tower/services/auth/purge_user_associated_data.rb
 - app/services/command_tower/services/auth/register.rb
 - app/services/command_tower/services/auth/signup_rate_limits/check_availability.rb
 - app/services/command_tower/services/auth/signup_rate_limits/check_register.rb
@@ -624,6 +633,7 @@ files:
 - app/services/command_tower/services/auth/signup_session/decode.rb
 - app/services/command_tower/services/auth/signup_session/encode.rb
 - app/services/command_tower/services/auth/signup_session/validate.rb
+- app/services/command_tower/services/auth/tombstone_user.rb
 - app/services/command_tower/services/auth/username_availability.rb
 - app/services/command_tower/services/impersonation/create.rb
 - app/services/command_tower/services/impersonation/end.rb
@@ -631,6 +641,7 @@ files:
 - app/services/command_tower/services/impersonation/terminate_open_sessions.rb
 - app/services/command_tower/services/me/capabilities.rb
 - app/services/command_tower/services/me/change_password.rb
+- app/services/command_tower/services/me/delete_account.rb
 - app/services/command_tower/services/me/pushover_product_gate.rb
 - app/services/command_tower/services/me/sms_product_gate.rb
 - app/services/command_tower/services/me/update_name.rb
@@ -704,6 +715,7 @@ files:
 - app/workflows/command_tower/workflows/impersonation/stop_workflow.rb
 - app/workflows/command_tower/workflows/me/change_password_workflow.rb
 - app/workflows/command_tower/workflows/me/clear_phone_workflow.rb
+- app/workflows/command_tower/workflows/me/delete_account_workflow.rb
 - app/workflows/command_tower/workflows/me/error_mapping.rb
 - app/workflows/command_tower/workflows/me/error_status.rb
 - app/workflows/command_tower/workflows/me/phone_verification/send_workflow.rb
@@ -735,6 +747,7 @@ files:
 - db/migrate/20260816000001_create_command_tower_audit_events.rb
 - db/migrate/20260817000001_add_scope_columns_to_command_tower_audit_events.rb
 - db/migrate/20260817000003_create_command_tower_impersonation_sessions.rb
+- db/migrate/20260826140000_add_deleted_at_to_users.rb
 - docs/admin_workspace.md
 - docs/api_reference.md
 - docs/architecture.md
@@ -760,6 +773,8 @@ files:
 - docs/upgrades/0.10.0.md
 - docs/upgrades/0.11.0.md
 - docs/upgrades/0.11.1.md
+- docs/upgrades/0.12.0.md
+- docs/upgrades/0.13.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb
@@ -782,6 +797,7 @@ files:
 - lib/command_tower/authorization/effective_entity_grants.rb
 - lib/command_tower/authorization/entity.rb
 - lib/command_tower/authorization/role.rb
+- lib/command_tower/configuration/account_deletion/config.rb
 - lib/command_tower/configuration/admin/config.rb
 - lib/command_tower/configuration/admin_scope/config.rb
 - lib/command_tower/configuration/admin_scope/tool_registration.rb