command_tower 0.3.1 → 0.10.0

data/docs/change_password_workflow.md

@@ -0,0 +1,67 @@
+# Authenticated Password Change Workflow
+
+Authenticated password change lets a signed-in user replace their password by proving knowledge of the current password. On success, CommandTower rotates `verifier_token` in the same transaction as the password digest update, invalidating **all** existing JWT sessions (including the caller’s). The API does **not** re-issue a JWT; hosts must clear local auth and send the user through Sign In again.
+
+This is distinct from [password recovery](password_reset_workflow.md), which is public and recovery-session/token-based.
+
+## Purpose and orchestration
+
+| Item | Value |
+|------|--------|
+| Route | `PATCH /me/password` (engine-relative) |
+| Auth | Authentication + authorization boundaries |
+| Controller | `CommandTower::Me::PasswordController#update` |
+| Workflow | `CommandTower::Workflows::Me::ChangePasswordWorkflow` (`ApplicationWorkflow`, `retry_strategy :none`) |
+| Service | `CommandTower::Services::Me::ChangePassword` |
+| Deserializer | `CommandTower::Deserializers::Me::ChangePasswordDeserializer` |
+| Serializer | `CommandTower::Serializers::Me::ChangePasswordResponseSerializer` |
+| Feature gate | Route always drawn (not constrained in `routes.rb`) |
+
+**Boundary:** The controller deserializes input and runs **one** workflow. The workflow orchestrates the change-password service and maps failures to HTTP status. It does not implement password rules itself.
+
+## Request
+
+```json
+{
+  "current_password": "string",
+  "password": "string",
+  "password_confirmation": "string"
+}
+```
+
+## Success (200)
+
+Serialized success payload (message only). Response effects include `clear_token: true` so cookie/header sessions are cleared. No JWT, verifier, or password material is returned.
+
+## Service flow (under the workflow)
+
+1. Authenticate `current_password`
+2. Confirm `password` matches `password_confirmation`
+3. Enforce configured password length bounds
+4. In one DB transaction: persist new password digest → `reset_verifier_token!`
+5. On failure: typed application errors → workflow HTTP mapping
+
+## Failures
+
+| Condition | Typical status |
+|-----------|----------------|
+| Missing / invalid JWT | 401 |
+| Validation / bad current password / confirmation | 4xx via Me error mapping |
+| Unexpected infra failure | 5xx |
+
+## Contrast with recovery reset
+
+| | Authenticated change | Forgot / reset |
+|--|----------------------|----------------|
+| Proof | Current password | Recovery session + reset token |
+| Route | `PATCH /me/password` | `POST /auth/password-recovery-session` + `/auth/password-reset/*` |
+| Auth | JWT | Public (+ recovery session) |
+| Verifier | Rotated | See recovery guide |
+| Post-success | All JWTs invalid; host → Sign In | Host-defined |
+
+## Related
+
+- [Sensitive changes](sensitive_routes.md)
+- [API reference](api_reference.md)
+- [Password reset workflow](password_reset_workflow.md)
+- [Extending](extending.md)

data/docs/controllers.md

@@ -0,0 +1,35 @@
+# Controllers and routes
+
+CommandTower exposes platform HTTP through `CommandTower::Engine` routes. Hosts typically mount the engine (for example at `/api`) via the configure generator or a custom mount.
+
+This page is an **index** of route areas. Detailed request/response contracts live in the [API reference](api_reference.md).
+
+## Route areas
+
+| Area | Prefix (engine-relative) | Purpose |
+|------|--------------------------|---------|
+| Auth session | `/auth/*` | Login, logout, session, register, signup-session, identity policy, availability |
+| Email verification | `/auth/email-verification/*` | Send / verify email codes |
+| Password recovery | `/auth/password-recovery-session`, `/auth/password-reset/*` | Forgot / reset password |
+| Me / profile | `/me`, `/profile`, `/me/name`, `/me/password` | Account reads and updates |
+| Inbox | `/me/inbox*` | User inbox consume (list, open, archive, bulk ops) |
+| Preferences | `/me/preferences*` | Notification preferences |
+| Phone | `/me/phone*` | Phone endpoint + verification |
+| Pushover | `/me/pushover*` | Pushover endpoint lifecycle + verification |
+| Admin messaging | `/admin/messaging/announcements` | Cohort announcements |
+
+Exact paths depend on where the host mounts the engine.
+
+## Controllers
+
+Engine controllers are transport adapters: authenticate/authorize as required, deserialize, run **exactly one** workflow, render the application envelope. See [Architecture](architecture.md).
+
+## Related
+
+- [API reference](api_reference.md) — endpoint catalog
+- [Messaging](messaging_integration_guide.md) — messaging surfaces summary
+- [Extending](extending.md) — host extension boundaries
+- [Initializing](initializing.md) — mount and configure
+- [README](../README.md)
+
+HTTP request specs for the engine live under `spec/requests/`.

data/docs/cookie_authentication_guide.md

@@ -0,0 +1,167 @@
+# Cookie Authentication Guide
+
+HttpOnly cookie authentication for browser / SPA hosts. Mobile and API clients typically use Bearer tokens only.
+
+Back to [README](../README.md). Endpoint contracts: [API reference](api_reference.md). Deep authn/RBAC: [authentication_authorization_guide.md](authentication_authorization_guide.md).
+
+Journey coverage: `spec/integration_test/auth/cookie_*.rb`.
+
+## Enable cookies
+
+```ruby
+CommandTower.configure do |config|
+  config.jwt.cookie.enabled = true
+  # Optional CSRF for cookie-authenticated unsafe methods:
+  # config.jwt.cookie.csrf.enabled = true
+end
+```
+
+### Defaults
+
+| Setting | Default |
+|---------|---------|
+| `jwt.ttl` | `7.days` |
+| `jwt.cookie.enabled` | `false` |
+| `jwt.cookie.name` | `"ct_jwt"` |
+| `jwt.cookie.same_site` | `:lax` |
+| `jwt.cookie.secure` | `false` (set `true` in production / HTTPS) |
+| `jwt.cookie.httponly` | `true` |
+| `jwt.cookie.path` | `"/"` |
+| `jwt.cookie.domain` | `nil` (host-only) |
+| `jwt.cookie.ttl` | `7.days` |
+| `jwt.cookie.csrf.enabled` | `false` |
+| `jwt.cookie.csrf.cookie_name` | `"ct_csrf"` |
+| `jwt.cookie.csrf.header_name` | `"X-CSRF-Token"` |
+| `jwt.cookie.csrf.rotate_on_login` | `true` |
+| `jwt.cookie.csrf.rotate_on_reset` | `true` |
+| CSRF `same_site` / `secure` / `path` / `domain` | `nil` (inherit JWT cookie) |
+| CSRF `ttl` | `7.days` |
+
+## Token extraction order
+
+1. `Authorization: Bearer <token>` header (wins when present)
+2. HttpOnly JWT cookie when cookie mode is enabled
+
+## Login / logout examples
+
+Paths are engine-relative. Prefix with your mount (generator often mounts at `/`; hosts may use `/api`).
+
+Plain-text login is gated by `config.login.plain_text.enable?`.
+
+### Login
+
+```http
+POST /auth/plain-text/login
+Content-Type: application/json
+
+{ "identifier": "user@example.com", "password": "secret" }
+```
+
+Success **201** envelope:
+
+```json
+{
+  "data": {
+    "user": {
+      "id": 1,
+      "email": "user@example.com",
+      "username": "user",
+      "firstName": "Ada",
+      "lastName": "Lovelace",
+      "emailValidated": true,
+      "roles": ["member"]
+    },
+    "token": "<jwt>",
+    "tokenExpiresAt": "<iso8601>"
+  },
+  "meta": {},
+  "errors": []
+}
+```
+
+When cookies are enabled, the response also sets the JWT cookie (and may set/rotate CSRF cookie). Clients that rely on cookies should use `credentials: "include"` (fetch) / `withCredentials: true` (axios).
+
+### Current user
+
+```http
+GET /me
+Authorization: Bearer <jwt>
+```
+
+Or rely on the JWT cookie when cookie mode is enabled and no Bearer header is sent.
+
+### Logout (this browser)
+
+```http
+POST /auth/logout
+```
+
+Success **200**:
+
+```json
+{
+  "data": { "message": "logged_out" },
+  "meta": {},
+  "errors": []
+}
+```
+
+Clears the auth cookie for this client. It does **not** rotate `verifier_token`, so other devices’ JWTs remain valid until expiry or verifier rotation.
+
+### Logout everywhere
+
+Rotate the verifier via authenticated password change:
+
+```http
+PATCH /me/password
+```
+
+Or call `user.reset_verifier_token!` from trusted host ops. There is no `POST /user/modify` engine route.
+
+See [sensitive_routes.md](sensitive_routes.md).
+
+## CSRF (optional)
+
+When `jwt.cookie.csrf.enabled` is true, cookie-authenticated **unsafe** methods (POST/PATCH/PUT/DELETE) require:
+
+1. Non-HttpOnly CSRF cookie (`ct_csrf` by default)
+2. Matching header (`X-CSRF-Token` by default)
+
+Mismatch / missing → auth failure with codes such as `csrf_missing` / `csrf_mismatch` (envelope via modern auth boundaries).
+
+Bearer-header requests do not require CSRF.
+
+## CORS
+
+Browser SPA on another origin needs host CORS that allows credentials and your frontend origin. Example sketch (host-owned):
+
+```ruby
+# Host rack-cors or equivalent — illustrative only
+allow do
+  origins "https://app.example.com"
+  resource "*",
+    headers: :any,
+    methods: [:get, :post, :put, :patch, :delete, :options],
+    credentials: true,
+    expose: ["X-Authorization-Expire", "X-Authorization-Reset"]
+end
+```
+
+`SameSite=None` cookies require `Secure=true` (HTTPS). Prefer same-site deployments with `SameSite=Lax` when possible.
+
+## Production checklist
+
+- [ ] `jwt.cookie.enabled = true` only when browsers need cookies
+- [ ] `jwt.cookie.secure = true` on HTTPS
+- [ ] Review `same_site` for cross-site SPAs
+- [ ] Enable CSRF if cookies authenticate mutating requests from browsers
+- [ ] CORS credentials + explicit origin (not `*`)
+- [ ] Do not log tokens or CSRF secrets
+
+## Related
+
+- [API reference](api_reference.md)
+- [Authentication](authentication.md)
+- [Authentication & authorization guide](authentication_authorization_guide.md)
+- [Sensitive changes](sensitive_routes.md)
+- [Initializing](initializing.md)

data/docs/email_verification_workflow.md

@@ -0,0 +1,58 @@
+# Email Verification Workflow
+
+Code-based email verification ensures the user can receive mail at their registered address. Users authenticate with JWT; a configurable grace period may allow API access before verification is mandatory.
+
+## Purpose and orchestration
+
+| Step | Route | Workflow |
+|------|-------|----------|
+| Send code | `POST /auth/email-verification/send` | `Workflows::Auth::EmailVerification::SendWorkflow` |
+| Verify code | `POST /auth/email-verification/verify` | `Workflows::Auth::EmailVerification::VerifyWorkflow` |
+
+Both workflows inherit `ApplicationWorkflow` with `retry_strategy :none`.
+
+| Item | Value |
+|------|--------|
+| Controllers | `CommandTower::Auth::EmailVerification::SendController` / `VerifyController` |
+| Auth | Authentication + authorization boundaries; send bypasses email-validation precondition so unverified users can request codes |
+| Feature gate | `CommandTower.config.login.plain_text.email_verify?` |
+
+**Boundary:** Controllers authenticate/authorize, run **one** workflow, render results. Workflows orchestrate verification services. Hosts do not reopen JWT or email-verification framework internals — see [extending.md](extending.md).
+
+## Key characteristics
+
+- **Method:** Numeric code (length configurable; commonly 6 digits)
+- **Delivery:** Email to the registered address
+- **Expiration:** Configurable (commonly ~10 minutes)
+- **Authentication required:** Valid JWT
+- **Grace period:** Configurable window before verification is enforced on other routes
+
+## Endpoints (engine-relative)
+
+### Send
+
+`POST /auth/email-verification/send`
+
+No body typically required (uses `current_user`). Returns a message payload on success.
+
+### Verify
+
+`POST /auth/email-verification/verify`
+
+**Body (typical):** `{ "code": "string" }`  
+
+On success, marks the user’s email validated.
+
+## Errors
+
+Standard application envelope. Invalid codes and validation failures map through Auth identity error status helpers. See [API reference](api_reference.md) for envelope shape.
+
+## Configuration
+
+Email verification options live on CommandTower config (enablement, code length, TTL, grace period). Hosts set secrets and product mail delivery via initializer — [initializing.md](initializing.md).
+
+## Related
+
+- [API reference](api_reference.md)
+- [Authentication](authentication.md)
+- [Extending](extending.md)

data/docs/extending.md

@@ -0,0 +1,105 @@
+# Extending CommandTower
+
+How hosts customize and integrate with CommandTower **without forking platform internals**.
+
+**New host?** Start with [Host integration](host_integration_guide.md).
+
+Layer map: [architecture.md](architecture.md). Install/configure/migrate/doctor: [initializing.md](initializing.md). Testing API: [testing.md](testing.md). HTTP catalog: [api_reference.md](api_reference.md).
+
+## What hosts should extend
+
+| Stable Extension Point | Purpose |
+|------------------------|---------|
+| Routes | Additional host endpoints |
+| Controllers | Product-specific HTTP |
+| Workflows | Product orchestration |
+| Services | Product business logic |
+| `Communications::Produce` / `ProduceMany` | Sending messaging |
+| `FactoryBot.modify` | Extend shared factories |
+| Model reopen | Product associations / behavior |
+| Initializers | Configuration |
+| Notification catalogs / channel policy | Host-owned messaging customization |
+
+## Internal platform — do not extend
+
+| Internal Platform | Do Not Extend |
+|-------------------|---------------|
+| ApplicationWorkflow | Framework / shared orchestration base |
+| ServiceBase | Shared service framework |
+| Serializers | Platform response shaping |
+| Deserializers | Platform request trust boundary |
+| Messaging execution pipeline | Handoff / execution / accept internals |
+| RequestContext | Framework request context |
+| JWT primitives | Token issue / validate plumbing |
+| Internal framework plumbing | Envelope renderer, workflow base mechanics, etc. |
+
+Hosts **use** these via documented public APIs and configuration. Do not subclass, reopen, or fork them as product customization.
+
+## Generators and install flags
+
+Full install narrative: [initializing.md](initializing.md).
+
+| Surface | Notes |
+|---------|--------|
+| `bin/rails command_tower:install` | Migrations + optional configure |
+| `SKIP_CONFIGURE=1` | Migrations only |
+| `SKIP_MOUNT=1` | Initializer without mount |
+| `FORCE=1` | Overwrite initializer |
+| `rails g command_tower:configure` | `--skip-routes`, `--force` |
+
+## Mounting and configuration
+
+Mount `CommandTower::Engine` at the path your product needs. Configuration and secrets belong in the host initializer. Details: [initializing.md](initializing.md).
+
+## Migrations
+
+CommandTower authors CT-owned schema; hosts install via engine tasks (`command_tower:install:migrations` / `command_tower:install`) and run `db:migrate`. Do not dual-author CT schema in the host (**AD-SCH-01**). Details: [initializing.md](initializing.md).
+
+## Testing API and factories
+
+Primary SST: [testing.md](testing.md).
+
+| API | Role |
+|-----|------|
+| `CommandTower::Testing.install!` | Preferred host entry (loads factories) |
+| `CommandTower::Testing.load_factories!` | Factories only / advanced |
+| `CommandTower::Testing.ensure_endpoint_secret!` | Test helper for endpoint ciphertext when env unset |
+| `FactoryBot.modify` | Host extension of shared factories |
+
+Shipped factory files (under the gem `spec/factories/`): `user`, `user_secret`, messaging factories, `entity`, `role`.
+
+## RBAC on host controllers
+
+Protect host controllers with `authenticate_user!` / `authorize_user!` (or modern Auth boundaries) and RBAC entities. See [authentication_authorization_guide.md](authentication_authorization_guide.md) and [api_reference.md](api_reference.md).
+
+## Model reopen
+
+Prefer services/workflows for new behavior. Reopen patterns: [models.md](models.md).
+
+## Produce from product workflows
+
+Product business events own **host** workflows that call:
+
+- `CommandTower::Services::Messaging::Communications::Produce`
+- `CommandTower::Services::Messaging::Communications::ProduceMany`
+
+Do not create one Messaging workflow per message type. Do not call the messaging handoff/execution pipeline directly. Summary: [messaging_integration_guide.md](messaging_integration_guide.md).
+
+## Blank-host checklist
+
+1. Add gem → [initializing.md](initializing.md) quick start (`install`, `db:migrate`, `doctor`)
+2. Configure secrets and feature flags in the host initializer
+3. Mount the engine
+4. Load factories in the host test boot path → [testing.md](testing.md)
+5. Exercise shared surfaces via engine routes → [controllers.md](controllers.md) / [api_reference.md](api_reference.md)
+6. Add product routes/controllers/workflows/services only in the **stable extension** columns above
+7. Keep catalogs, channel policy, and adapter credentials host-owned
+
+No DoubleFloor Me (or other product) source is required to use the platform.
+
+## Related
+
+- [Architecture](architecture.md)
+- [Controllers](controllers.md)
+- [Sensitive changes](sensitive_routes.md)
+- Workflow guides: [password reset](password_reset_workflow.md), [change password](change_password_workflow.md), [email verification](email_verification_workflow.md)

data/docs/host_integration_guide.md

@@ -0,0 +1,158 @@
+# Host Integration Guide
+
+**Start here** for integrating CommandTower into a new Rails host.
+
+This page owns the **order of operations**. It does not replace specialty docs: install details stay in [Initializing](initializing.md), HTTP contracts in [API reference](api_reference.md), boundaries in [Extending](extending.md).
+
+`command_tower:doctor` green means secrets/migrations look sane. It does **not** prove Me/Auth authorization works.
+
+## Prerequisites
+
+- A Rails host application (engine is mounted into the host)
+- `gem "command_tower"` in the host Gemfile (path, git, or released gem)
+- Host-owned database (and any host Redis/job stack your app already uses)
+
+## Step 1 — Install
+
+Follow [Initializing](initializing.md):
+
+```bash
+bundle install
+bin/rails command_tower:install
+bin/rails db:migrate
+bin/rails command_tower:doctor
+```
+
+That copies CT migrations, generates `config/initializers/command_tower.rb` (unless skipped), and mounts `CommandTower::Engine` (unless skipped).
+
+## Step 2 — Secrets and initializer
+
+In the host initializer, set at least:
+
+- `config.jwt.hmac_secret`
+- `config.signup_session.jwt_secret` (or `SIGNUP_SESSION_JWT_SECRET`)
+- `config.password_recovery_session.jwt_secret` (or `PASSWORD_RECOVERY_SESSION_JWT_SECRET`)
+
+Re-run `bin/rails command_tower:doctor`. Details: [Initializing — Configuration](initializing.md#configuration).
+
+Dummy-host reference: [`rails_app/config/initializers/command_tower.rb`](../rails_app/config/initializers/command_tower.rb).
+
+## Step 3 — Confirm mount path
+
+Ensure routes include something like:
+
+```ruby
+mount CommandTower::Engine => "/"   # or "/api"
+```
+
+Engine paths below are **relative to that mount**. Route area index: [Controllers](controllers.md).
+
+## Step 4 — Host RBAC (required)
+
+AuthorizeRequest **fails closed**. Without host entity mappings, authenticated calls to `/me`, `/auth/session`, inbox, etc. return **403**.
+
+The configure generator does **not** create this file.
+
+1. Copy and adapt the dummy host file: [`rails_app/config/rbac_groups.yml`](../rails_app/config/rbac_groups.yml) → host `config/rbac_groups.yml`.
+2. Keep a host group such as `member` with entities for session, me, profile, inbox, preferences, phone, pushover, email verification.
+3. Do **not** redefine engine groups that already exist in `default.yml` (`owner`, `admin`).
+4. Point config at the file if needed:
+
+```ruby
+CommandTower.configure do |c|
+  c.authorization.rbac_group_path = Rails.root.join("config/rbac_groups.yml")
+end
+```
+
+(Default path is already `config/rbac_groups.yml`.)
+
+More: [Authorization](authorization.md), [Authentication & authorization guide](authentication_authorization_guide.md).
+
+## Step 5 — Roles on users
+
+RBAC YAML defines what a role **may** do. Users still need that role assigned.
+
+- Specs and the dummy pattern use role name **`member`** for Me/Auth surfaces.
+- Engine register does **not** automatically attach `member`. Hosts must assign roles via product logic, ops (`command_tower:users:create`), or host hooks after account creation.
+- Admin announcements need a role that includes `admin_messaging_announcements` (engine `admin` group, or an equivalent host mapping).
+
+## Step 6 — Enable feature gates you need
+
+When a gate is off, the route is **not drawn** → **404**.
+
+| Capability | Config |
+|------------|--------|
+| Plain-text login | `config.login.plain_text.enable = true` |
+| Email verification routes | `config.login.plain_text.email_verify = true` |
+| Password reset routes | `config.login.plain_text.password_reset = true` |
+| Email availability | `config.signup_session.email_availability = true` |
+| Username availability | `config.username.realtime_username_check = true` |
+
+Full gate list: [API reference — Feature gates](api_reference.md#feature-gates).
+
+## Step 7 — Choose auth client path
+
+- **API / mobile:** `Authorization: Bearer <jwt>` (default)
+- **Browser / SPA cookies:** enable `config.jwt.cookie` (+ CSRF as needed) — [Cookie authentication](cookie_authentication_guide.md)
+
+Engine HTTP success/error bodies use the application envelope `{ data, meta, errors }`. Host provisional helpers (`authenticate_user!`) can differ — [Authentication](authentication.md).
+
+## Step 8 — Smoke check
+
+With gates and RBAC in place (paths relative to your mount):
+
+1. `POST /auth/register` (always drawn) — create a user, then **assign `member`** (Step 5) if not done by host logic.
+2. `POST /auth/plain-text/login` (if enabled) — receive `data.token`.
+3. `GET /me` with Bearer token — expect **200** and envelope `data` (account payload).
+
+If you get **401**, authn failed. If you get **403**, fix Steps 4–5 before debugging clients.
+
+Contracts: [API reference](api_reference.md).
+
+## Step 9 — Messaging (when needed)
+
+Host owns:
+
+- Notification catalog / types
+- `platform_enabled_channels` / channel policy
+- Adapter credentials (email / SMS / Pushover)
+
+Emit from a **host product workflow** via `Communications::Produce` / `ProduceMany` — not by bypassing workflows. See [Messaging](messaging_integration_guide.md) and [Extending](extending.md).
+
+Phone/Pushover routes are always drawn; missing product readiness returns **503** capability errors.
+
+## Step 10 — Host tests
+
+```ruby
+require "command_tower/testing"
+CommandTower::Testing.install!
+```
+
+Details: [Testing](testing.md). Prefer `spec/requests/` patterns in the gem as HTTP contract proof.
+
+## Done when
+
+- Doctor passes for secrets/migrations
+- Host `rbac_groups.yml` maps Me/Auth entities
+- Users who should use Me surfaces have the host `member` (or equivalent) role
+- Needed feature gates are enabled
+- `GET /me` returns **200** with a Bearer token for a member user
+
+## Common failures
+
+| Symptom | Likely cause |
+|---------|----------------|
+| Doctor green, `GET /me` is **403** | Missing host RBAC YAML or user lacks `member` (Steps 4–5) |
+| `POST /auth/plain-text/login` is **404** | `login.plain_text.enable?` off (Step 6) |
+| Password-reset / availability **404** | Matching feature gate off |
+| Phone / Pushover **503** | Capability / adapters not ready (Step 9) |
+| Confused error JSON on host controllers | Provisional `authenticate_user!` vs engine envelope (Step 7) |
+
+## Related
+
+- [Initializing](initializing.md)
+- [Extending](extending.md)
+- [API reference](api_reference.md)
+- [Authentication & authorization guide](authentication_authorization_guide.md)
+- [Messaging](messaging_integration_guide.md)
+- [README](../README.md)