command_tower 0.4.0 → 0.11.0

data/docs/password_reset_workflow.md

@@ -0,0 +1,82 @@
+# Password Reset (Forgot Password) Workflow
+
+Public password recovery for users who cannot authenticate. Flow uses a **password-recovery session** plus gated **password-reset** endpoints. Detailed schemas live here and are summarized in the [API reference](api_reference.md).
+
+## Purpose and orchestration
+
+| Step | Route | Workflow |
+|------|-------|----------|
+| Create recovery session | `POST /auth/password-recovery-session` | `Workflows::Auth::PasswordRecoverySession::CreateWorkflow` |
+| Send reset email | `POST /auth/password-reset/send` | `Workflows::Auth::PasswordReset::SendWorkflow` |
+| Validate token | `POST /auth/password-reset/validate` | `Workflows::Auth::PasswordReset::ValidateWorkflow` |
+| Reset password | `POST /auth/password-reset/reset` | `Workflows::Auth::PasswordReset::ResetWorkflow` |
+
+All listed workflows inherit `ApplicationWorkflow` with `retry_strategy :none`. Controllers under `CommandTower::Auth::PasswordReset::*` and password-recovery-session authenticate the recovery session where required, deserialize, run **one** workflow, and render `WorkflowResult`.
+
+**Feature gate:** `CommandTower.config.login.plain_text.password_reset?` (reset endpoints). Recovery session creation is part of the public recovery path.
+
+**Boundary:** Controllers own transport + recovery-session auth. Workflows orchestrate rate limits and password-reset services. Services own email/token capability details. Do not call messaging execution internals from hosts — see [extending.md](extending.md).
+
+## High-level characteristics
+
+- **No user JWT**; `password-reset/send` requires a valid **password-recovery session**; `validate` / `reset` are public and use the emailed reset `token` in the body
+- Email-based identification; responses avoid user enumeration where designed to
+- Secure, time-limited reset tokens
+- Rate limiting via password-recovery rate-limit services
+
+## Endpoints (engine-relative)
+
+### 1. Create password-recovery session
+
+`POST /auth/password-recovery-session`
+
+Establishes the recovery session used by subsequent reset calls. See request specs under `spec/requests/` for exact payload/envelope.
+
+### 2. Send reset email
+
+`POST /auth/password-reset/send`
+
+**Auth:** Password-recovery session  
+
+**Body (typical):** `{ "email": "string" }`  
+
+**Workflow:** `SendWorkflow` → rate-limit check → `Services::Auth::PasswordReset::Send`
+
+### 3. Validate token
+
+`POST /auth/password-reset/validate`
+
+**Auth:** Public (reset token in body)
+
+**Body (typical):** `{ "token": "string" }` (optional `email` when config requires it)
+
+**Workflow:** `ValidateWorkflow`
+
+### 4. Reset password
+
+`POST /auth/password-reset/reset`
+
+**Auth:** Public (reset token in body)
+
+**Body (typical):** token + new password fields (`passwordConfirmation` / `password_confirmation`)
+
+**Workflow:** `ResetWorkflow`
+
+Success behavior and verifier rotation differ from authenticated [change password](change_password_workflow.md) — treat recovery success per product policy (often force Sign In).
+
+## Errors
+
+Failures return the standard application envelope via `render_application_result`. Status mapping uses Auth identity/password-reset error helpers. Validation failures from deserializers typically surface as `422 Unprocessable Entity`.
+
+## Security notes
+
+- Never log passwords, raw tokens, or recovery-session secrets
+- Prefer HTTPS in production
+- Respect rate limits; do not probe for account existence in client UX
+
+## Related
+
+- [Change password workflow](change_password_workflow.md)
+- [API reference](api_reference.md)
+- [Initializing](initializing.md) — secrets / feature config
+- [Extending](extending.md)

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/sensitive_routes.md

@@ -0,0 +1,47 @@
+# Sensitive changes and session invalidation
+
+CommandTower JWTs are bound to the authenticated user’s **verifier token**. When the verifier rotates, previously issued access tokens that carried the old verifier no longer authenticate (`401`).
+
+This is the platform mechanism behind “logout everywhere” and post-password-change session invalidation.
+
+## Verifier token on `User`
+
+Each `User` may store:
+
+- `verifier_token` — opaque string embedded in JWTs at issue time
+- `verifier_token_last_reset` — timestamp of the last rotation
+
+API:
+
+```ruby
+user.reset_verifier_token!    # generates a new token, updates timestamp, returns the value
+user.retreive_verifier_token! # returns existing token or creates one (historical spelling)
+```
+
+Authentication compares the verifier claim in the JWT to the user’s current `verifier_token`. A mismatch fails authentication.
+
+## When the platform rotates the verifier
+
+| Event | Behavior |
+|-------|----------|
+| Authenticated password change (`PATCH /me/password`) | Rotates verifier so prior tokens fail |
+| Host / ops call `user.reset_verifier_token!` | Explicit revoke-all-sessions |
+
+There is no engine HTTP admin “mutate user with `verifier_token: true`” route. `UserAttributes::Mutate` may still exist for internal/host use; do not assume a public SchemaHelper admin path.
+
+Browser `POST /auth/logout` clears cookie/session transport for that client; it does **not** by itself rotate `verifier_token` for all devices. Use verifier rotation when all outstanding JWTs must die.
+
+## Host guidance
+
+- Treat password changes and explicit “revoke all sessions” as **sensitive** operations that should rotate the verifier.
+- Do not expose `verifier_token` in API payloads (platform serializers omit it).
+- Prefer platform workflows/services for password change rather than hand-editing password digests without rotation.
+- `UserSecret` backs related validation/recovery secrets; see [Models](models.md).
+
+## Related
+
+- [Change password workflow](change_password_workflow.md)
+- [Authentication](authentication.md) / [Authentication & authorization guide](authentication_authorization_guide.md)
+- [Cookie authentication](cookie_authentication_guide.md)
+- [Models](models.md)
+- [README](../README.md)

data/docs/testing.md

@@ -0,0 +1,74 @@
+# Testing with CommandTower
+
+CommandTower ships FactoryBot definitions for engine-owned models. Hosts load
+them explicitly in the test suite — there is no production Railtie and
+FactoryBot is not a runtime gem dependency.
+
+Back to [README](../README.md). See also [Initializing](initializing.md).
+
+## Setup
+
+```ruby
+# spec/rails_helper.rb (after Rails is loaded)
+require "command_tower/testing"
+
+CommandTower::Testing.install! # preferred
+# CommandTower::Testing.load_factories! # factories-only / advanced
+```
+
+Call `install!` **before** any host `FactoryBot.modify` blocks so shared
+factories exist when you extend them.
+
+## Extending factories
+
+Hosts must not redefine CommandTower base factories. Use `FactoryBot.modify`:
+
+```ruby
+FactoryBot.modify do
+  factory :user do
+    roles { ["member"] }
+
+    trait :operator do
+      roles { %w[member operator] }
+    end
+  end
+end
+```
+
+## Packaging and evolution
+
+Factory files live under `spec/factories/**` inside the gem and are included in
+the gemspec. Adding or changing a shared factory is a normal CommandTower gem
+bump — hosts pick it up on upgrade.
+
+`CommandTower::Testing.load_factories!` is idempotent (safe to call more than
+once). It loads each factory file under `CommandTower::Engine.root/spec/factories`
+explicitly; it does not append to global `FactoryBot.definition_file_paths`.
+
+## Responsibilities
+
+| Owner | Responsibility |
+|-------|----------------|
+| CommandTower | Base factories for CT-owned models; Testing API; packaging |
+| Host | `install!` in the test boot path; product traits via `FactoryBot.modify` |
+
+## Factory invariant
+
+Base factories construct **persistent model state only**. They must not invoke
+Services, Workflows, ApplicationWorkflows, or external adapters. Endpoint
+ciphertext uses `SecretBox` / `Fingerprinter` (crypto helpers).
+
+For endpoint factories in environments where
+`COMMAND_TOWER_MESSAGING_ENDPOINT_SECRET` is unset, you may call:
+
+```ruby
+CommandTower::Testing.ensure_endpoint_secret!
+```
+
+(SecretBox already falls back to a non-production test secret outside production.)
+
+## Contributors vs hosts
+
+This guide is the **host Testing API**. Contributors working inside the CommandTower
+repository also follow workspace test standards (`.cursor/rules/testing.mdc`) and
+architecture guards under `spec/architecture/`.

data/docs/upgrades/0.10.0.md

@@ -0,0 +1,58 @@
+# Upgrade: CommandTower 0.10.0
+
+**From:** `0.5.0` (and earlier SchemaHelper-era hosts on `main`)  
+**To:** `0.10.0`
+
+This document summarizes **all changes from `main` through the `0.10.0` release** (committed work on `schematizing` plus the modern platform working tree). It is the durable upgrade / change SST for hosts. For a sequenced blank-host path, use [Host integration](../host_integration_guide.md).
+
+## Breaking / host-impact
+
+| Change | Host impact |
+|--------|-------------|
+| SchemaHelper Admin / User / legacy Inbox HTTP removed | No `GET /user`, `/user/modify`, `/admin/modify*`, legacy blast/message SchemaHelper routes |
+| Modern response envelope | Engine HTTP returns `{ data, meta, errors }` via `render_application_result` |
+| 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 | 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) |
+
+## Platform capabilities in 0.10.0
+
+- **Auth:** register, plain-text login, logout, session, identity policy, signup session, email/username availability, email verification, password-recovery session + password reset
+- **Me:** account show, profile, name, password, inbox (list/detail/bulk), preferences, phone, Pushover
+- **Messaging emit:** `Communications::Produce` / `ProduceMany` from host workflows
+- **Install:** `command_tower:install`, configure generator, `command_tower:doctor`
+- **Testing:** `CommandTower::Testing.install!` shared factories
+- **Architecture:** Controller → Workflow → Service; Engine uses `authenticate_request!` / `authorize_request!`
+
+## Documentation
+
+- Canonical HTTP catalog: [API reference](../api_reference.md)
+- Host start-here: [Host integration](../host_integration_guide.md)
+- Install SST: [Initializing](../initializing.md)
+- Auth/cookie/RBAC guides refreshed to modern routes
+- Messaging and pagination aligned to Inbox + Produce contracts
+
+## Upgrade checklist (existing hosts)
+
+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. 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).
+7. Smoke: Bearer login → `GET /me` returns **200** (not **403**).
+8. If emitting messages: catalog, channels, adapters; call Produce from host workflows.
+
+New hosts: follow [Host integration](../host_integration_guide.md) end-to-end.
+
+## Related
+
+- [Initializing](../initializing.md)
+- [Extending](../extending.md)
+- [Messaging](../messaging_integration_guide.md)
+- [Authentication & authorization guide](../authentication_authorization_guide.md)
+- [README](../../README.md)

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/README.md

@@ -0,0 +1,10 @@
+# Upgrades
+
+Host-facing upgrade / change summaries for CommandTower releases.
+
+| Version | Summary |
+|---------|---------|
+| [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