command_tower 0.10.0 → 0.11.1

data/docs/principal_capabilities.md

@@ -0,0 +1,89 @@
+# Principal capabilities
+
+Authenticated **frontend-projectable** capability ids for the current principal. Projection is `effective RBAC entity grants ∩ curated registry` — never role/group names, and never an auto-dump of `Entity.entities`.
+
+```text
+RBAC groups → entity grants → curated projectable registry
+  → possessed principalCapabilities → shared FE gating (4.6.2+)
+```
+
+CommandTower owns which CT entities are frontend-projectable. Hosts own who receives those entities through RBAC group composition. Hosts register **host-owned** projectables only; they do **not** re-register or redefine CT capability ids.
+
+## Register (configuration)
+
+```ruby
+CommandTower.configure do |config|
+  # Default 1:1 — id and required_entity share the same name
+  config.registry.principal_capabilities.capability :admin_workspace
+
+  # Host additive (example) — override required_entity when names differ
+  config.registry.principal_capabilities.capability :manage_wagers do |capability|
+    capability.required_entity = :pickem_admin_wagers
+  end
+end
+```
+
+| Field | Rules |
+|-------|--------|
+| id | DSL name; public contract |
+| required_entity | RBAC entity name; defaults to id when omitted; must exist after RBAC composition |
+| owner | `:command_tower` (seeded) or `:host` (host registration) |
+
+Lookup: `CommandTower.config.registry.principal_capabilities.fetch(:admin_workspace)`.
+
+## Seeded CommandTower catalog (4.6.1 + 4.7.1 + 6.3)
+
+| id / required_entity | Why projectable |
+|----------------------|-----------------|
+| `admin_workspace` | Gate Admin Workspace affordances without probing `/admin/workspace` |
+| `admin_users` | Gate Admin Users Collection/detail presentation |
+| `admin_users_update` | Gate Admin Users identity mutations (name, username, email, email validation) |
+| `admin_rbac_assignments` | Gate Admin Users role assignment (assignable catalog + PATCH roles) |
+| `admin_audit_events` | Gate Audit Admin affordances and deep links outside the workspace manifest |
+| `admin_messaging_announcements` | Gate Messaging Admin affordances outside the manifest |
+| `admin_impersonation` | Gate Impersonate affordances (5.6 composition). Possession does not start a session by itself. |
+| `me_audit_events` | Gate Account **Activity** / self-audit Explorer presentation (4.7.1). Hosts own who receives the entity. |
+
+Me/Auth route gates (`session`, `me`, …) and unimplemented Admin entities are **not** seeded. Adding a new CT RBAC entity later requires an explicit slice decision to also register a principal capability.
+
+## Boot validation
+
+1. Host `CommandTower.configure` may register additive capabilities (mutable).
+2. `after_initialize` — `principal_capabilities.finalize!` with audit / admin_workspace, then freeze (skipped in test).
+3. `to_prepare` — after RBAC, `validate_required_entities!(Entity.entities)`.
+
+## Runtime HTTP
+
+`GET /auth/principal-capabilities` (engine-relative; hosts mounting at `/api` use `GET /api/auth/principal-capabilities`).
+
+- Authn + authz: entity `principal_capabilities` (`PrincipalCapabilitiesController#show`). Grant to host `member` (and operators that need the call) like other Me/Auth surfaces.
+- Controller → `Workflows::Auth::PrincipalCapabilities::ShowWorkflow` (`retry_strategy :none`) → `Services::Auth::PrincipalCapabilities::Project` → `PrincipalCapabilitiesSerializer`.
+- Service: if any role has `allow_everything`, return **all** registered projectable ids; else include definitions whose `required_entity` is granted. Unique + sorted. No role-name checks.
+- Envelope `data`: `{ principalCapabilities: string[] }` — possessed ids only.
+
+| Persona (typical host composition) | Example `principalCapabilities` |
+|------------------------------------|---------------------------------|
+| guest | **401** |
+| email verification required | **412** |
+| `member` (host grants `me_audit_events`) | `me_audit_events` |
+| `member` (host withholds `me_audit_events`) | `[]` |
+| `audit_operator` | `admin_audit_events`, `admin_workspace` |
+| `messaging_operator` | `admin_messaging_announcements`, `admin_workspace` |
+| host `admin` / `operations_admin` | CT Admin seeds (not necessarily `me_audit_events`) |
+| `owner` | all **registered** ids (CT + host additive) |
+
+## Naming collisions (different concepts)
+
+| Name | Meaning |
+|------|---------|
+| `principalCapabilities` / this registry | Runtime possessed, frontend-projectable RBAC-backed facts |
+| `/me` `capabilities` | Account self-service flags — **not** this projection |
+| HostConfig / build-time `capabilities` | Compile-time product modules — **not** this projection |
+| RBAC group / role names | Host privilege composition — **never** the FE gating contract |
+
+## Related
+
+- [API reference](api_reference.md#get-authprincipal-capabilities)
+- [Authorization](authorization.md)
+- [Admin Workspace](admin_workspace.md) — tool manifest only; not a UI permission probe
+- [Host integration](host_integration_guide.md)

data/docs/upgrades/0.10.0.md

@@ -14,7 +14,7 @@ This document summarizes **all changes from `main` through the `0.10.0` release*
 | Current-user path | Use `GET /me` (and `GET /profile`); not `GET /user` |
 | Login path | `POST /auth/plain-text/login` when `login.plain_text.enable?` (route absent → **404** if gate off) |
 | Password change | `PATCH /me/password` (rotates verifier; does not re-issue JWT) |
-| Host RBAC required | Without host `rbac_groups.yml` entity mappings, Me/Auth calls **403** (fail-closed) |
+| Host RBAC required | Host `rbac_groups.yml` must grant CT-owned Me/Auth entity **names** to product roles; do not copy CT controller mappings. Conflicts fail at boot. |
 | Feature gates | Login, email verify, password reset, availability routes are config-gated |
 | Schema ownership (**AD-SCH-01**) | CT authors migrations; hosts install via `command_tower:install` / `install:migrations` then `db:migrate` |
 | Admin HTTP | Only `POST /admin/messaging/announcements` (no SchemaHelper user admin) |
@@ -40,7 +40,7 @@ This document summarizes **all changes from `main` through the `0.10.0` release*
 
 1. Bump gem to `0.10.0` and run `bin/rails command_tower:install:migrations` (or `SKIP_CONFIGURE=1 bin/rails command_tower:install`) then `bin/rails db:migrate`.
 2. Set JWT + signup/recovery session secrets; run `bin/rails command_tower:doctor`.
-3. Copy/adapt [`rails_app/config/rbac_groups.yml`](../../rails_app/config/rbac_groups.yml) into the host; do not redefine engine `owner` / `admin` groups.
+3. Add host `rbac_groups.yml` with a product role (typically `member`) that **grants** CT-owned entity names; do not redefine engine `owner` or copy CT controller mappings. Operational Admin roles are host-owned.
 4. Ensure users who need Me surfaces have the host `member` role (or equivalent).
 5. Enable feature gates you rely on (`login.plain_text.enable`, password reset, email verify, availability).
 6. Point clients at modern paths (`/me`, `/auth/plain-text/login`, envelope parsing).

data/docs/upgrades/0.11.0.md

@@ -0,0 +1,92 @@
+# Upgrade: CommandTower 0.11.0
+
+**From:** `0.10.0`  
+**To:** `0.11.0`
+
+This document summarizes **host-visible changes from `0.10.0` through the `0.11.0` release**. It is the durable upgrade / change SST for hosts already on the Auth/Me/Messaging platform. For a sequenced blank-host path, use [Host integration](../host_integration_guide.md).
+
+## Breaking / host-impact
+
+| Change | Host impact |
+|--------|-------------|
+| New migrations | Install and migrate audit events (+ scope columns) and impersonation sessions via `command_tower:install:migrations` then `db:migrate` |
+| New RBAC entities | Hosts must **explicitly grant** new CT-owned entity names; they are **not** auto-added to a generic CT admin role |
+| `GET /auth/principal-capabilities` | Frontend gating should use possessed projectable ids from this endpoint — **not** role names and **not** `GET /admin/workspace` as a permission probe |
+| Admin HTTP during impersonation | Admin routes return **418** while an impersonation session is active |
+| Admin least privilege | Operational Admin privilege is host-owned role composition; CT ships entities only |
+| Optional Admin resource scoping | Hosts that need scoped Users/Audit register `config.admin_scope` and may set `scope_required` on workspace tools |
+
+## Platform capabilities in 0.11.0
+
+(In addition to everything in [0.10.0](0.10.0.md).)
+
+- **Execution context + eventing:** workflow/service lifecycle on `ActiveSupport::Notifications`; structured logging is a subscriber (not a second bus)
+- **Audit ledger:** append-only `command_tower_audit_events`; registered `audit(...)` on workflows/services; Me + Admin query HTTP + filter-options
+- **Admin Workspace:** tool registry + RBAC-filtered `GET /admin/workspace` manifest; optional host `admin_scope`
+- **Principal capabilities:** curated FE-projectable ids via `GET /auth/principal-capabilities` (effective grants ∩ registry)
+- **Impersonation:** start via Admin Users, end via `DELETE /auth/impersonation-session`; overlay identity; idle/absolute timeouts
+- **Admin Users:** list/show, identity update, assignable roles, RBAC assignment — host-granted entities only
+
+### New engine HTTP (engine-relative)
+
+| Method | Path |
+|--------|------|
+| GET | `/auth/principal-capabilities` |
+| DELETE | `/auth/impersonation-session` |
+| GET | `/me/audit-events`, `/me/audit-events/:id`, `/me/audit-events/filter-options` |
+| GET | `/admin/workspace` |
+| GET | `/admin/audit-events`, `/admin/audit-events/:id`, `/admin/audit-events/filter-options` |
+| GET | `/admin/users`, `/admin/users/:id`, `/admin/users/assignable-roles` |
+| PATCH | `/admin/users/:id/name`, `/username`, `/email`, `/email-validation`, `/roles` |
+| POST | `/admin/users/:id/impersonation-sessions` |
+
+### New RBAC entities (host grants required)
+
+| Entity | Typical grant |
+|--------|----------------|
+| `principal_capabilities` | `member` (and operators that need the call) |
+| `me_audit_events` | `member` when Account Activity is in product |
+| `admin_workspace` | host operator roles |
+| `admin_audit_events` | audit operators |
+| `admin_users` | users operators |
+| `admin_users_update` | identity-update operators |
+| `admin_rbac_assignments` | RBAC assignment operators |
+| `admin_impersonation` | impersonation operators |
+
+See dummy composition in `rails_app/config/rbac_groups.yml`.
+
+### Migrations
+
+- `20260816000001_create_command_tower_audit_events.rb`
+- `20260817000001_add_scope_columns_to_command_tower_audit_events.rb`
+- `20260817000003_create_command_tower_impersonation_sessions.rb`
+
+## Documentation
+
+- [Eventing](../eventing.md)
+- [Audit](../audit.md)
+- [Admin Workspace](../admin_workspace.md)
+- [Principal capabilities](../principal_capabilities.md)
+- Host start-here: [Host integration](../host_integration_guide.md)
+- Canonical HTTP catalog: [API reference](../api_reference.md)
+
+## Upgrade checklist (existing 0.10.0 hosts)
+
+1. Bump gem to `0.11.0` and run `bin/rails command_tower:install:migrations` then `bin/rails db:migrate`.
+2. Run `bin/rails command_tower:doctor`.
+3. Grant `principal_capabilities` (and `me_audit_events` if Account Activity is in product) on host `member` / equivalent.
+4. Explicitly grant Admin entities to **host-owned** operator roles (`admin_workspace`, `admin_users`, `admin_users_update`, `admin_rbac_assignments`, `admin_audit_events`, `admin_impersonation`) — do not assume a platform `admin` role.
+5. Point Admin FE gating at `GET /auth/principal-capabilities`, not `GET /admin/workspace`.
+6. Optional: register host Admin Workspace tools, `admin_scope`, host audit events, and impersonation timeouts.
+7. Smoke: login → `GET /auth/principal-capabilities` **200**; operator with grants → `GET /admin/workspace` **200**; without grants → **403**.
+8. Smoke: start impersonation → Admin routes **418**; `DELETE /auth/impersonation-session` restores actor.
+
+New hosts: follow [Host integration](../host_integration_guide.md) end-to-end (includes 0.10.0 foundations plus this release).
+
+## Related
+
+- [Initializing](../initializing.md)
+- [Extending](../extending.md)
+- [Authentication & authorization guide](../authentication_authorization_guide.md)
+- [README](../../README.md)
+- Prior release: [0.10.0](0.10.0.md)

data/docs/upgrades/0.11.1.md

@@ -0,0 +1,25 @@
+# Upgrade: CommandTower 0.11.1
+
+**From:** `0.11.0`  
+**To:** `0.11.1`
+
+Patch release for MariaDB-safe audit persistence and install migrations.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| `CommandTower::Audit::Event` JSON coding | `metadata`, `change_set`, and `sensitive_fields` declare `attribute :…, :json`. Forces JSON encoding on MySQL 8 and MariaDB (where `t.json` is often LONGTEXT + `json_valid` CHECK). Fixes HTTP 500 `ActiveRecord::CheckViolation` on failed-login audit writes. |
+| Audit events migration collation | Engine migration no longer hardcodes MySQL 8–only `utf8mb4_0900_ai_ci`. Fresh installs / `command_tower:install:migrations` copies inherit the database default (e.g. `utf8mb4_unicode_ci` on MariaDB 10.11). |
+
+## Host actions
+
+1. Bump gem to `0.11.1` and deploy.
+2. **No new migration** is required if `command_tower_audit_events` already exists.
+3. Already-installed host copies of the audit migration that still contain `utf8mb4_0900_ai_ci` only matter for **new** databases; runtime login fix does not depend on re-running that migration.
+4. Smoke: unknown-user `POST /auth/plain-text/login` should return auth failure (e.g. `invalid_credentials`), **not** `internal_error` / 500.
+
+## Not in this release
+
+- Jumbotron / host `t.json` columns outside CommandTower
+- Altering charset/collation on already-created production audit tables

data/docs/upgrades/README.md

@@ -4,6 +4,8 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [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 |
 
 New hosts should start with [Host integration](../host_integration_guide.md).

data/lib/command_tower/admin_scope/apply_audit_scoping.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    module ApplyAuditScoping
+      module_function
+
+      def call(relation:, scope_context:, principal:)
+        return relation if scope_context.nil?
+
+        registration = CommandTower.config.admin_scope.fetch(scope_context.tool_id)
+        global_event_names = global_visible_event_names
+        affected_user_ids = registration.affected_users_in_scope.call(
+          scope_value: scope_context.scope_value,
+          principal:,
+          tool_id: scope_context.tool_id
+        )
+
+        host_relation = registration.narrow_audit.call(
+          relation: relation.where(scope_class: CommandTower::Audit::Event::SCOPE_CLASSES[:host]),
+          scope_value: scope_context.scope_value,
+          principal:,
+          tool_id: scope_context.tool_id
+        )
+
+        global_relation = relation.where(
+          scope_class: CommandTower::Audit::Event::SCOPE_CLASSES[:global],
+          action: global_event_names,
+          affected_user_id: affected_user_ids
+        )
+
+        relation.where(id: host_relation.select(:id))
+          .or(relation.where(id: global_relation.select(:id)))
+          .where.not(scope_class: CommandTower::Audit::Event::SCOPE_CLASSES[:legacy])
+      end
+
+      def global_visible_event_names
+        CommandTower.config.registry.audit.definitions.filter_map do |name, definition|
+          name if definition.global_visible_in_host_scope?
+        end
+      end
+      private_class_method :global_visible_event_names
+    end
+  end
+end

data/lib/command_tower/admin_scope/apply_users_narrowing.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    module ApplyUsersNarrowing
+      module_function
+
+      def call(relation:, scope_context:, principal:)
+        return relation if scope_context.nil?
+
+        registration = CommandTower.config.admin_scope.fetch(scope_context.tool_id)
+        registration.narrow_users.call(
+          relation:,
+          scope_value: scope_context.scope_value,
+          principal:,
+          tool_id: scope_context.tool_id
+        )
+      end
+    end
+  end
+end

data/lib/command_tower/admin_scope/manifest_projection.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    module ManifestProjection
+      IMPERSONATION_DISABLED_REASON = "Admin tools are unavailable while impersonating a user."
+
+      module_function
+
+      def call(definition:, principal:)
+        scope_payload = scope_payload_for(definition)
+        unscoped_unregistered = scope_payload.nil? && !admin_scope_registered?(definition.id)
+
+        availability = availability_for(definition, principal:)
+        scope_options = scope_options_for(definition, principal:)
+
+        payload = {
+          scope: scope_payload,
+          availability:,
+          scope_options:
+        }.compact
+
+        if CommandTower::Current.impersonation_active
+          payload[:availability] = {
+            enabled: false,
+            reason: IMPERSONATION_DISABLED_REASON
+          }
+          return payload
+        end
+
+        return {} if unscoped_unregistered
+
+        payload
+      end
+
+      def scope_payload_for(definition)
+        return unless definition.scope_required?
+
+        {
+          required: true,
+          parameter: camelize_parameter(definition.scope_parameter),
+          label: definition.scope_label
+        }
+      end
+      private_class_method :scope_payload_for
+
+      def availability_for(definition, principal:)
+        return { enabled: true, reason: nil } unless admin_scope_registered?(definition.id)
+
+        registration = CommandTower.config.admin_scope.fetch(definition.id)
+        normalize_availability(registration.availability.call(principal:))
+      end
+      private_class_method :availability_for
+
+      def scope_options_for(definition, principal:)
+        return unless definition.scope_required? && admin_scope_registered?(definition.id)
+
+        registration = CommandTower.config.admin_scope.fetch(definition.id)
+        Array(registration.options.call(principal:)).map do |option|
+          normalize_scope_option(option)
+        end
+      end
+      private_class_method :scope_options_for
+
+      def admin_scope_registered?(tool_id)
+        CommandTower.config.admin_scope.registered?(tool_id)
+      end
+      private_class_method :admin_scope_registered?
+
+      def normalize_availability(value)
+        hash = value.is_a?(Hash) ? value : {}
+        enabled = hash.fetch(:enabled, hash["enabled"])
+        reason = hash.fetch(:reason, hash["reason"])
+        {
+          enabled: enabled != false,
+          reason: reason.nil? ? nil : reason.to_s
+        }
+      end
+      private_class_method :normalize_availability
+
+      def normalize_scope_option(option)
+        case option
+        when AdminScope::ScopeOption
+          { value: option.value, label: option.label }
+        when Hash
+          {
+            value: option.fetch(:value, option["value"]).to_s,
+            label: option.fetch(:label, option["label"]).to_s
+          }
+        else
+          raise ArgumentError, "scope option must be ScopeOption or Hash, got #{option.class}"
+        end
+      end
+      private_class_method :normalize_scope_option
+
+      def camelize_parameter(parameter)
+        parameter.to_s.camelize(:lower)
+      end
+      private_class_method :camelize_parameter
+    end
+  end
+end

data/lib/command_tower/admin_scope/resolve.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    module Resolve
+      module_function
+
+      def call(tool_id:, principal:, scope_value:)
+        definition = CommandTower.config.registry.admin_workspace.fetch(tool_id)
+        return nil unless definition.scope_required?
+
+        token = scope_value.to_s.strip
+        if token.empty?
+          raise CommandTower::Errors::ForbiddenError
+        end
+
+        registration = CommandTower.config.admin_scope.fetch(tool_id)
+        valid = registration.validate.call(value: token, principal:)
+        unless valid
+          raise CommandTower::Errors::ForbiddenError
+        end
+
+        ScopeContext.new(
+          tool_id: definition.id,
+          scope_value: token,
+          scope_parameter: definition.scope_parameter
+        )
+      end
+    end
+  end
+end

data/lib/command_tower/admin_scope/scope_context.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    ScopeContext = Data.define(:tool_id, :scope_value, :scope_parameter)
+  end
+end

data/lib/command_tower/admin_scope/scope_option.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    ScopeOption = Data.define(:value, :label)
+  end
+end

data/lib/command_tower/admin_scope.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminScope
+    class Error < CommandTower::Error; end
+
+    class UnregisteredToolError < Error; end
+    class DuplicateRegistrationError < Error; end
+    class InvalidToolRegistrationError < Error; end
+    class MissingRegistrationError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end
+
+require "command_tower/admin_scope/scope_context"
+require "command_tower/admin_scope/scope_option"
+require "command_tower/admin_scope/resolve"
+require "command_tower/admin_scope/apply_users_narrowing"
+require "command_tower/admin_scope/apply_audit_scoping"
+require "command_tower/admin_scope/manifest_projection"

data/lib/command_tower/admin_workspace.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module AdminWorkspace
+    class Error < CommandTower::Error; end
+
+    class UnregisteredToolError < Error; end
+    class DuplicateToolError < Error; end
+    class HostOverrideError < Error; end
+    class InvalidToolNameError < Error; end
+    class InvalidToolDefinitionError < Error; end
+    class DuplicateRouteError < Error; end
+    class MissingRequiredEntityError < Error; end
+    class FrozenRegistryError < Error; end
+  end
+end

data/lib/command_tower/audit/attribution.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Audit
+    module Attribution
+      MODES = %i[self_service admin_direct impersonation system].freeze
+
+      module_function
+
+      def resolve(affected_user_id:, attribution_mode:)
+        requested = normalize_mode(attribution_mode)
+        impersonating = CommandTower::Current.impersonation_active == true
+
+        if impersonating
+          if requested && requested != :impersonation
+            raise InvalidAttributionError,
+              "attribution_mode #{requested} conflicts with active impersonation"
+          end
+
+          originating = CommandTower::Current.originating_administrator_id
+          if originating.nil?
+            raise InvalidAttributionError, "impersonation requires originating_administrator_id"
+          end
+
+          return envelope(
+            mode: :impersonation,
+            actor_user_id: originating,
+            affected_user_id:
+          )
+        end
+
+        if requested == :impersonation
+          raise InvalidAttributionError, "attribution_mode impersonation requires impersonation_active"
+        end
+
+        if requested == :system || (requested.nil? && CommandTower::Current.user_id.nil?)
+          return envelope(mode: :system, actor_user_id: nil, affected_user_id:)
+        end
+
+        if requested == :admin_direct
+          if CommandTower::Current.user_id.nil?
+            raise InvalidAttributionError, "admin_direct requires a Current.user_id actor"
+          end
+
+          return envelope(mode: :admin_direct, actor_user_id: CommandTower::Current.user_id, affected_user_id:)
+        end
+
+        actor_id = CommandTower::Current.user_id
+        if actor_id.nil?
+          raise InvalidAttributionError, "self_service requires a Current.user_id actor"
+        end
+
+        if requested.nil? && !affected_user_id.nil? && actor_id != affected_user_id
+          raise InvalidAttributionError,
+            "attribution_mode must be explicit when actor and affected user differ"
+        end
+
+        if requested == :self_service && !affected_user_id.nil? && actor_id != affected_user_id
+          raise InvalidAttributionError,
+            "self_service requires Current.user_id to match affected_user_id"
+        end
+
+        envelope(mode: :self_service, actor_user_id: actor_id, affected_user_id:)
+      end
+
+      def normalize_mode(value)
+        return nil if value.nil?
+
+        mode = value.to_sym
+        unless MODES.include?(mode)
+          raise InvalidAttributionError, "invalid attribution_mode #{value.inspect}"
+        end
+
+        mode
+      end
+
+      def envelope(mode:, actor_user_id:, affected_user_id:)
+        {
+          attribution_mode: mode,
+          actor_user_id:,
+          affected_user_id:,
+          effective_user_id: CommandTower::Current.effective_user_id || CommandTower::Current.user_id,
+          originating_administrator_id: CommandTower::Current.originating_administrator_id,
+          impersonation_active: CommandTower::Current.impersonation_active == true,
+          user_id: CommandTower::Current.user_id
+        }
+      end
+    end
+  end
+end