command_tower 0.13.1 → 0.14.0

data/docs/api_reference.md

@@ -426,6 +426,27 @@ Errors include `422` (`pushover_already_configured`, `pushover_not_configured`,
 
 ---
 
+## Push (Expo)
+
+Routes are **always drawn**. Product readiness is workflow-gated as **503** `push_capability_unavailable` (`config.messaging.expo.adapter` must be `fake`, `log`, or `http`).
+
+There is **no** `POST /me/push/verification`. Create and replace call `Endpoints.mark_verified` in-workflow after persist.
+
+| Method | Path | Body | Notes |
+|--------|------|------|--------|
+| `GET` | `/me/push` | — | `{ endpoints: [...] }` — **active only** (terminal rows omitted) |
+| `POST` | `/me/push` | `token`/`address` (snake or camelCase) | Create or idempotent same-fingerprint; returns verified endpoint |
+| `PATCH` / `PUT` | `/me/push/:id` | same | Replace by id; new row verified; other actives untouched |
+| `DELETE` | `/me/push/:id` | — | Revoke; returns revoked SafeView |
+
+**Token form:** `ExponentPushToken[...]` or `ExpoPushToken[...]` (422 otherwise).
+
+**Endpoint fields:** `id`, `channelKey`, `lifecycleState`, `verificationState`, `maskedDisplayValue`, `verifiedAt`, `createdAt`, `updatedAt`, `actions: { canReplace, canRemove }`. Never the raw token.
+
+**RBAC:** `me_push`. **Spec:** `spec/requests/command_tower/me/push_spec.rb`.
+
+---
+
 ## Admin Workspace
 
 ### `GET /admin/workspace`

data/docs/controllers.md

@@ -20,6 +20,7 @@ This page is an **index** of route areas. Detailed request/response contracts li
 | Preferences | `/me/preferences*` | Notification preferences |
 | Phone | `/me/phone*` | Phone endpoint + verification |
 | Pushover | `/me/pushover*` | Pushover endpoint lifecycle + verification |
+| Push | `/me/push*` | Expo push endpoint collection (register / replace / revoke) |
 | Admin messaging | `/admin/messaging/announcements` | Cohort announcements |
 
 Exact paths depend on where the host mounts the engine.

data/docs/messaging_integration_guide.md

@@ -10,7 +10,8 @@ Complete install and host RBAC first: [Host integration](host_integration_guide.
 |---------|----------------|
 | User inbox (consume) | Engine `/me/inbox*` — see [API reference](api_reference.md#me-inbox) |
 | Preferences | Engine `/me/preferences*` — see [API reference](api_reference.md#preferences) |
-| Phone / Pushover endpoints | Engine `/me/phone*`, `/me/pushover*` (503 when capability unavailable) |
+| Phone / Pushover / Push endpoints | Engine `/me/phone*`, `/me/pushover*`, `/me/push*` (503 when capability unavailable) |
+
 | Single-recipient emit | `CommandTower::Services::Messaging::Communications::Produce` |
 | Multi-recipient emit | `CommandTower::Services::Messaging::Communications::ProduceMany` |
 | Admin cohort announce | Engine `POST /admin/messaging/announcements` |
@@ -73,10 +74,14 @@ Pagination detail: [pagination.md](pagination.md). Full catalog: [api_reference.
 
 - Notification catalog content (registered into CommandTower notification types)
 - `platform_enabled_channels` / channel policy injection
-- Messaging adapter credentials (email / SMS / Pushover) via initializer or ENV
-- Host product roles that grant CT-owned Me inbox/preferences/phone/pushover entities (and `admin` if used)
+- Messaging adapter credentials (email / SMS / Pushover / Expo push) via initializer or ENV
+- Host product roles that grant CT-owned Me inbox/preferences/phone/pushover/`me_push` entities (and `admin` if used)
 - Product-specific operational tooling (announce rake tasks, welcome copy)
 
+Expo push (`config.messaging.expo`): set `adapter` to `fake`, `log`, or `http` to enable the Messaging `push` channel and Me `/me/push*` (default `disabled`). `access_token` is optional — send `Authorization: Bearer` only when non-blank (required only if the Expo project enables enhanced push security). Never log the token.
+
+Me push registration: engine `/me/push*` (collection of active endpoints). Create/replace persist via `Endpoints` and **mark_verified** in-workflow — there is no `POST /me/push/verification`. Tokens must be Expo form (`ExponentPushToken[...]` / `ExpoPushToken[...]`).
+
 ## Related
 
 - [Controllers / routes](controllers.md)

data/docs/upgrades/0.14.0.md

@@ -0,0 +1,31 @@
+# Upgrade: CommandTower 0.14.0
+
+**From:** `0.13.1`  
+**To:** `0.14.0`
+
+Minor release: Expo push as an executable Messaging channel, plus engine `/me/push*` registration HTTP. No schema migration.
+
+## Host-visible changes
+
+| Change | Host impact |
+|--------|-------------|
+| `config.messaging.expo` | New composer: `adapter` (`disabled` / `fake` / `log` / `http`) and optional `access_token` (Bearer sent only when non-blank). Required for `push` to be platform-configured. |
+| Channel `push` execution | Detector, renderer (`RenderedPushPayload`), Expo adapter (send + one getReceipts pass), multi-endpoint fan-out via `AdapterRequest.eligible_endpoint_ids`. `DeviceNotRegistered` → `Endpoints.mark_invalid`. |
+| `/api/me/push*` | Collection register / list (active) / replace / revoke. Create/replace call `mark_verified` in-workflow (no verification POST). 503 when Expo adapter is disabled. |
+| RBAC `me_push` | Show/create/update/destroy for Me push. Hosts must grant on roles that should register device tokens (e.g. `member`). |
+| `Validators::Push` | Requires Expo token form (`ExponentPushToken[…]` / `ExpoPushToken[…]`). |
+
+## Host actions
+
+1. Bump gem to `0.14.0` (or `>= 0.14.0`).
+2. **No new migration.**
+3. Set `config.messaging.expo.adapter` (use `http` on production TF API; `fake` is fine for development/test with `allow_fake_adapter`).
+4. Optionally set `config.messaging.expo.access_token` **only if** the Expo project has enhanced push security enabled.
+5. Enable `push` in `platform_enabled_channels` and grant `me_push` when the host product should register/send push.
+6. Add `push` to announcement (or other) message types’ allowed/default channels when Planner should select it.
+
+## Not in this release
+
+- Host channel policy / Pick’em enablement (host repo)
+- Native client token lifecycle / CT FE `beforeLogout`
+- EAS/APNs credentials or TestFlight proof

data/docs/upgrades/README.md

@@ -4,6 +4,7 @@ Host-facing upgrade / change summaries for CommandTower releases.
 
 | Version | Summary |
 |---------|---------|
+| [0.14.0](0.14.0.md) | Expo push Messaging channel (`config.messaging.expo`) + `/api/me/push*` registration HTTP; `me_push` RBAC |
 | [0.13.1](0.13.1.md) | Canonical `Intervention::Severity` constants (`blocking`, `warning`, `informational`) |
 | [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 |

data/lib/command_tower/authorization/default.yml

@@ -68,6 +68,13 @@ entities:
   - name: me_pushover_verification
     controller: CommandTower::Me::Pushover::VerificationsController
     only: create
+  - name: me_push
+    controller: CommandTower::Me::PushController
+    only:
+      - index
+      - create
+      - update
+      - destroy
   - name: me_audit_events
     controller: CommandTower::Me::AuditEventsController
     only:

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

@@ -3,6 +3,7 @@
 require "class_composer"
 require "command_tower/configuration/messaging/sms"
 require "command_tower/configuration/messaging/pushover"
+require "command_tower/configuration/messaging/expo"
 
 module CommandTower
   module Configuration
@@ -54,6 +55,11 @@ module CommandTower
           desc: "Pushover verification transport configuration (credential validate + test notification)",
           allowed: Pushover,
           default: Pushover.new
+
+        add_composer :expo,
+          desc: "Expo Push delivery configuration (Messaging push channel; optional access_token)",
+          allowed: Expo,
+          default: Expo.new
       end
     end
   end

data/lib/command_tower/configuration/messaging/expo.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "class_composer"
+
+module CommandTower
+  module Configuration
+    module Messaging
+      class Expo < ::CommandTower::Configuration::Base
+        include ClassComposer::Generator
+
+        ADAPTERS = %w[disabled fake log http].freeze
+
+        add_composer :adapter,
+          desc: "Expo Push delivery: disabled | fake | log | http. Default disabled (fail closed).",
+          allowed: String,
+          default: "disabled",
+          validator: ->(val) { ADAPTERS.include?(val.to_s) },
+          invalid_message: ->(val) { "Provided #{val.inspect}. Allowed: #{ADAPTERS.join(', ')}" }
+
+        add_composer :api_base_url,
+          desc: "Expo Push API origin (send = {base}/send, receipts = {base}/getReceipts).",
+          allowed: String,
+          default: "https://exp.host/--/api/v2/push"
+
+        add_composer :timeout_seconds,
+          desc: "HTTP open/read timeout seconds for Expo Push provider calls.",
+          allowed: Integer,
+          default: 5
+
+        add_composer :access_token,
+          desc: "Optional Expo Push access token. When non-blank, send Authorization: Bearer. " \
+                "Required only if the Expo project enables enhanced push security. Never log.",
+          allowed: String,
+          default: ""
+      end
+    end
+  end
+end

data/lib/command_tower/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_tower
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - matt-taylor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-30 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phonelib
@@ -218,6 +218,7 @@ files:
 - app/controllers/command_tower/me/phone_verification/verifications_controller.rb
 - app/controllers/command_tower/me/phone_verification/verify_controller.rb
 - app/controllers/command_tower/me/preferences_controller.rb
+- app/controllers/command_tower/me/push_controller.rb
 - app/controllers/command_tower/me/pushover/verifications_controller.rb
 - app/controllers/command_tower/me/pushover_controller.rb
 - app/controllers/command_tower/me_controller.rb
@@ -254,6 +255,7 @@ files:
 - 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/push/token_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/pushover/credentials_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/update_name_deserializer.rb
 - app/deserializers/command_tower/deserializers/me/update_phone_deserializer.rb
@@ -267,6 +269,8 @@ files:
 - app/errors/command_tower/errors/account/phone_verification_send_failed_error.rb
 - app/errors/command_tower/errors/account/phone_verification_stale_error.rb
 - app/errors/command_tower/errors/account/phone_verification_throttled_error.rb
+- app/errors/command_tower/errors/account/push_capability_unavailable_error.rb
+- app/errors/command_tower/errors/account/push_endpoint_not_found_error.rb
 - app/errors/command_tower/errors/account/pushover_already_configured_error.rb
 - app/errors/command_tower/errors/account/pushover_capability_unavailable_error.rb
 - app/errors/command_tower/errors/account/pushover_not_configured_error.rb
@@ -363,6 +367,7 @@ files:
 - 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/push_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
@@ -486,6 +491,9 @@ files:
 - app/services/command_tower/messaging/execution/adapter_result.rb
 - app/services/command_tower/messaging/execution/adapters/email/adapter.rb
 - app/services/command_tower/messaging/execution/adapters/email/configuration.rb
+- app/services/command_tower/messaging/execution/adapters/expo/adapter.rb
+- app/services/command_tower/messaging/execution/adapters/expo/configuration.rb
+- app/services/command_tower/messaging/execution/adapters/expo/http_client.rb
 - app/services/command_tower/messaging/execution/adapters/fake_adapter.rb
 - app/services/command_tower/messaging/execution/adapters/pushover/adapter.rb
 - app/services/command_tower/messaging/execution/adapters/pushover/configuration.rb
@@ -579,6 +587,7 @@ files:
 - app/services/command_tower/messaging/rendering/channel_renderer.rb
 - app/services/command_tower/messaging/rendering/render_error.rb
 - app/services/command_tower/messaging/rendering/rendered_payload.rb
+- app/services/command_tower/messaging/rendering/rendered_push_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_pushover_payload.rb
 - app/services/command_tower/messaging/rendering/rendered_sms_payload.rb
 - app/services/command_tower/secrets.rb
@@ -590,6 +599,11 @@ files:
 - app/services/command_tower/services/account/clear_phone.rb
 - app/services/command_tower/services/account/phone_verification/send.rb
 - app/services/command_tower/services/account/phone_verification/verify.rb
+- app/services/command_tower/services/account/push/create.rb
+- app/services/command_tower/services/account/push/ct_support.rb
+- app/services/command_tower/services/account/push/destroy.rb
+- app/services/command_tower/services/account/push/list.rb
+- app/services/command_tower/services/account/push/replace.rb
 - app/services/command_tower/services/account/pushover/create.rb
 - app/services/command_tower/services/account/pushover/ct_support.rb
 - app/services/command_tower/services/account/pushover/destroy.rb
@@ -642,6 +656,7 @@ files:
 - 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/push_product_gate.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
@@ -660,6 +675,7 @@ files:
 - app/views/command_tower/email_verification_mailer/verify_email.html.erb
 - app/views/command_tower/messaging/rendering/email.html.erb
 - app/views/command_tower/messaging/rendering/email.text.erb
+- app/views/command_tower/messaging/rendering/push.text.erb
 - app/views/command_tower/messaging/rendering/pushover.text.erb
 - app/views/command_tower/messaging/rendering/sms.text.erb
 - app/views/command_tower/password_reset_mailer/reset_password.html.erb
@@ -720,6 +736,11 @@ files:
 - app/workflows/command_tower/workflows/me/error_status.rb
 - app/workflows/command_tower/workflows/me/phone_verification/send_workflow.rb
 - app/workflows/command_tower/workflows/me/phone_verification/verify_workflow.rb
+- app/workflows/command_tower/workflows/me/push/create_workflow.rb
+- app/workflows/command_tower/workflows/me/push/destroy_workflow.rb
+- app/workflows/command_tower/workflows/me/push/index_workflow.rb
+- app/workflows/command_tower/workflows/me/push/replace_workflow.rb
+- app/workflows/command_tower/workflows/me/push/workflow_support.rb
 - app/workflows/command_tower/workflows/me/pushover/create_workflow.rb
 - app/workflows/command_tower/workflows/me/pushover/destroy_workflow.rb
 - app/workflows/command_tower/workflows/me/pushover/replace_workflow.rb
@@ -776,6 +797,7 @@ files:
 - docs/upgrades/0.12.0.md
 - docs/upgrades/0.13.0.md
 - docs/upgrades/0.13.1.md
+- docs/upgrades/0.14.0.md
 - docs/upgrades/README.md
 - lib/command_tower.rb
 - lib/command_tower/admin_scope.rb
@@ -822,6 +844,7 @@ files:
 - lib/command_tower/configuration/login/strategy/plain_text/lockable.rb
 - lib/command_tower/configuration/login/strategy/plain_text/password_reset.rb
 - lib/command_tower/configuration/messaging/config.rb
+- lib/command_tower/configuration/messaging/expo.rb
 - lib/command_tower/configuration/messaging/pushover.rb
 - lib/command_tower/configuration/messaging/sms.rb
 - lib/command_tower/configuration/otp/config.rb