command_tower 0.4.0 → 0.11.0

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

@@ -0,0 +1,179 @@
+# Eventing
+
+CommandTower publishes internal events on **one** Rails-native network: `ActiveSupport::Notifications`. Hosts and platform code do not invent a second bus.
+
+Logging is a **consumer** of that network. CommandTower supplies structured Hash fields to `Rails.logger`. The host Rails logger/formatter/tagged/broadcast configuration owns the final representation. CommandTower does not JSON-encode log lines.
+
+**Event emission is exhaustive; log materialization is selective.** Lifecycle started/completed pairs always publish. **Workflow** completed success/deferred logs to Rails `info` by default (`ApplicationWorkflow` declares `log_lifecycle!`). **Service** completed success stays quiet unless the service class opts in. `started` never materializes. Envelope `log_lifecycle` means “success may be materialized,” not “emit only when true.” Subscribers must not `const_get(subject)`.
+
+Audit persistence is a **raising** subscriber on `command_tower.audit.*` (not on lifecycle, and not the logging subscriber). **Audit authoring** (`audit(...)`, registered policy, structured emission) is documented in [Audit](audit.md).
+
+## Grammar
+
+Instrument names are the subscription keys:
+
+```text
+command_tower.<category>.<name...>
+```
+
+- `command_tower` is the platform prefix. Hosts do **not** prepend it themselves.
+- `category` is one token: `\A[a-z][a-z0-9_]*\z`. Categories are **extensible**, not a closed enum.
+- `name` is one or more tokens of the same shape, joined by `.`.
+
+Do **not** publish a generic `command_tower.event` name and dispatch on `payload[:type]`.
+
+Do **not** use `ActiveSupport::Subscriber#attach_to` as the taxonomy driver. That convention is reversed `event.namespace` (for example `sql.active_record`). CommandTower names are `command_tower.<category>.<name...>`. Subscribe with the full string or a prefix regexp.
+
+### Lifecycle (automatic)
+
+| Instrument name |
+|-----------------|
+| `command_tower.lifecycle.workflow.started` |
+| `command_tower.lifecycle.workflow.completed` |
+| `command_tower.lifecycle.service.started` |
+| `command_tower.lifecycle.service.completed` |
+
+Every `ApplicationWorkflow` `.call` / `call_from_job` invocation and every `ServiceBase` Interactor invocation emits one started/completed pair. Nested workflow→service shares `execution_uuid` and emits four events (two pairs).
+
+### Semantic (deliberate)
+
+```text
+command_tower.<category>.<name...>
+```
+
+Example: `command_tower.audit.wager_transition` via **registered** `audit(:wager_transition, ...)` — see [Audit](audit.md). Generic scalar `publish_event` remains available for non-audit categories; nested audit `changes` require `audit(...)` / `Events.publish_audit`.
+
+```ruby
+publish_event(category: :messaging, name: :welcome_produce_failed, payload: { code: "x" })
+```
+
+`publish_event` is on `CommandTower::Execution::ContextAccess` (workflows and services inherit it). It delegates to `CommandTower::Events.publish`. Do not include a separate Eventing module.
+
+## Subscribe
+
+Rails 8.1 Fanout matches the **full instrument string**.
+
+Exact:
+
+```ruby
+ActiveSupport::Notifications.subscribe("command_tower.lifecycle.workflow.completed") { |*args| }
+```
+
+Broad (lifecycle category):
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\Acommand_tower\.lifecycle(?:\.|\z)/) { |*args| }
+```
+
+## Envelope
+
+Payload is a frozen Hash of scalars (and frozen arrays of scalars). Never `CommandTower::Current`, User, request, AuthContext, JWT, cookies, or exception objects.
+
+| Field | When |
+|-------|------|
+| `event_uuid` | every event (new UUID at publish; **not** `execution_uuid`) |
+| `subject` | class name string |
+| `layer` | `:workflow` / `:service` (lifecycle only) |
+| `execution_uuid`, `correlation_id`, `request_id`, `causation_id`, `source` | Execution Context snapshot |
+| `user_id`, `effective_user_id`, `originating_administrator_id`, `impersonation_active` | snapshot |
+| `outcome` | completed only: `:success` / `:deferred` / `:failure` / `:error` |
+| `duration_ms` | completed only (monotonic clock from matching started) |
+| `error_class`, `error_codes` | completed failure/error; codes only, no messages/PII |
+| caller keys | semantic publish only; unsafe objects are dropped |
+
+`event_uuid` ≠ `execution_uuid`. There is no parent/child event graph. Nested work shares `execution_uuid` only.
+
+The snapshot is taken at publish time and is frozen against later `Current` mutation.
+
+## Publisher
+
+```ruby
+CommandTower::Events.publish(category:, name:, payload: {}, subject: nil, layer: nil)
+CommandTower::Events.snapshot
+```
+
+`publish` builds the instrument name, merges snapshot + `event_uuid` + sanitized caller payload, then calls `ActiveSupport::Notifications.instrument` **without a block**. Business work is **not** yielded to `instrument`.
+
+## Subscriber failure (Rails-native)
+
+CommandTower uses ASN as a **synchronous** event network. `Events.publish` does **not** wrap `instrument` in `rescue StandardError`.
+
+> CommandTower preserves Rails-native synchronous `ActiveSupport::Notifications` publication semantics. Subscriber failure policy belongs to the subscriber/capability consuming the event. Best-effort consumers must protect their own failure boundary. Correctness-sensitive subscriber semantics are defined by the owning capability.
+
+The generic publisher does **not** impose either policy.
+
+| Consumer | Policy owner |
+|----------|----------------|
+| Logging subscriber | **This slice** — best-effort; rescues materialization failures |
+| Metrics subscriber | future (likely self-protecting) |
+| Audit subscriber | later phase (may be correctness-sensitive) |
+| Other semantic subscribers | owning capability |
+
+The logging subscriber (`CommandTower::Logging::Subscriber` < `ActiveSupport::LogSubscriber`) subscribes with prefix regexes (not `attach_to`) to:
+
+- `command_tower.lifecycle.*`
+- `command_tower.log.*`
+- `command_tower.messaging.*`
+
+It does **not** subscribe to `audit` or `metric`. It calls `Rails.logger` with a Hash. Host formatters decide text vs JSON vs tagged output.
+
+### Lifecycle Rails logs
+
+`ApplicationWorkflow` declares `log_lifecycle!`, so workflow **completed** success/deferred materializes at `info` by default. Services stay quiet unless they opt in. Use `disable_lifecycle_logging!` on a workflow subclass to suppress its completed success line.
+
+```ruby
+class NoisyService < ApplicationService
+  log_lifecycle!
+end
+
+class QuietWorkflow < ApplicationWorkflow
+  disable_lifecycle_logging!
+end
+```
+
+`lifecycle_loggable?` walks superclasses when unset. `log_lifecycle:` is passed into `Events.around_execution` as a **boolean scalar**. `started` is never materialized.
+
+### Severity and materialization
+
+| Event | Materialize? | Level when materialized |
+|-------|----------------|-------------------------|
+| lifecycle started | **no** (even with opt-in — completed has outcome/duration) | — |
+| lifecycle completed success / deferred | only if `payload[:log_lifecycle]` | `info` |
+| lifecycle completed failure | **always** | payload `log_level` or `:info` |
+| lifecycle completed error | **always** | `error` |
+| `command_tower.log.<level>` | **always** | that level |
+| `command_tower.messaging.*` | unchanged (3.3) | payload `log_level` or `:info` |
+
+Authorization (`Authorize::Validate`) success diagnostics (“No Authorization required”, “User Roles”, per-role Authorized/Reason) publish `command_tower.log.debug`. Denial publishes `command_tower.log.warn`.
+
+### Events are comprehensive. Logs are projections.
+
+ASN payloads remain full Execution Context snapshots (`event_uuid`, nils, `layer`, `log_lifecycle`, duplicate identity fields). The logging subscriber **projects** a new Hash for `Rails.logger`. It does not mutate the canonical payload and does not define the event contract.
+
+**Core log fields** (when present): `event`, `subject`, `execution_uuid`, `correlation_id`, lifecycle `outcome`, `duration_ms`.
+
+**Conditional:** `user_id` when present; `request_id` when present and different from `correlation_id`; `source` when not `:http`; `causation_id` / `originating_administrator_id` when present; `effective_user_id` when different from `user_id`; `impersonation_active` only when `true`; `error_class` / `error_codes` when present.
+
+**Omitted from ordinary logs:** nils; `event_uuid`; `layer`; `log_lifecycle`; payload `log_level` (Rails severity already carries level); default `impersonation_active: false`; HTTP `source`.
+
+Semantic events (`command_tower.messaging.*`, `command_tower.log.*`) keep the same common context plus remaining safe scalar fields (`message`, `channel`, `provider`, `attempt`, …). Host formatters still own JSON / tags / LGTM representation; CommandTower does not promise a Rails JSON schema.
+
+`ApplicationError#log_level` is copied onto completed failure events as a scalar.
+
+`log_debug` / `log_info` / `log_warn` / `log_error` publish `command_tower.log.*`. Messaging OperationLoggers publish `command_tower.messaging.*`. Delivery LogAdapters remain a **transport** (`Rails.logger.info` of a send), not observation.
+
+Direct `Rails.logger` remains allowed for JWT decode/authenticate, boot/lib/controllers, and LogAdapters. Workflows/services must not write lifecycle observation directly.
+
+A raising **logging** subscriber does not fail the business action. A raising **non-logging** test/audit subscriber still surfaces through `Events.publish`.
+
+Emission and consumption remain separate: logger silence / level skips **materialization**, never ASN publication.
+
+Architecture specs guard these seams: one `CommandTower::Current`, kernel-owned lifecycle, `Events.publish` as the ASN publisher, curated log projection, and an explicit `Rails.logger` allowlist in JWT/LogAdapter infrastructure.
+
+## Kernel behavior (when subscribers do not raise)
+
+- `ApplicationWorkflow.call`: unexpected `StandardError` still becomes InternalError **after** completed `outcome: :error`. `validate_retry_strategy!` stays outside instrumentation.
+- `call_from_job` / `invoke_for_job`: still **re-raise** after completed `outcome: :error`.
+- Services: Interactor success → `:success`; `Interactor::Failure` → `:failure` then re-raise; unexpected exception → `:error` then re-raise. Services have no deferred outcome.
+
+Do not wrap instance `#call` in addition to class entry (duplicate pairs). Do not also wrap `ApplicationService.call` (the Interactor `around` is the service pair).

data/docs/extending.md

@@ -0,0 +1,136 @@
+# 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, including `config.registry.audit.event`, `config.registry.admin_workspace.tool`, and `config.registry.principal_capabilities.capability` |
+| 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.
+
+## Execution Context
+
+Greenfield hosts inherit CommandTower-owned execution-boundary bases so HTTP and jobs establish ambient context automatically:
+
+```ruby
+class ApplicationController < CommandTower::ApplicationController
+end
+
+class ApplicationJob < CommandTower::ApplicationJob
+end
+```
+
+`CommandTower::Current` is the single `CurrentAttributes` bag (`execution_uuid`, `correlation_id`, `request_id`, `source`, identity scalars). Workflows and services **read** it (`execution_context`); they do not mint a new execution per call.
+
+`CommandTower::Auth::RequestContext` remains the HTTP request/response JWT transport handle. It is not Execution Context.
+
+Rake/console (and other non-HTTP/job entry points) wrap work with:
+
+```ruby
+CommandTower.with_execution(source: :rake) do
+  # ...
+end
+```
+
+Nested `with_execution` shares the outer context. Do not wrap `db:migrate` or doctor.
+
+If a host **cannot** change `ApplicationController` / `ApplicationJob` superclasses, include `CommandTower::Execution::HttpBoundary` / `CommandTower::Execution::JobBoundary` as a compatibility escape hatch. Do not include those modules into every `ActionController` or `ActiveJob::Base`.
+
+Automatic workflow/service lifecycle notifications are emitted by CommandTower kernels. Logging is a subscriber: emission is exhaustive; materialization is selective; log records are curated projections. The host owns format. See [Eventing](eventing.md).
+
+## Related
+
+- [Eventing](eventing.md)
+- [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)