# AroFlo Connector

Tenant-aware middleware between the Flask platform and AroFlo. The target
architecture is API-first, with controlled browser automation only for
operations that the official AroFlo API does not support.

## Current migration block

The Platform App Standard v1 surface currently exports:

- `health_v1` / `platform.health`: local runtime and credential configuration
  status without contacting AroFlo.
- `test_connection_v1` / `platform.credentials.test`: an explicit, minimal,
  read-only API request against the AroFlo `lastupdate` zone.
- `zones_v1` / `aroflo.catalog.read`: a local catalog of registered zones and
  operation metadata. Catalog entries are not executable capabilities.
- `bots_v1` and `configure_bot_v1`: safe BOT profile listing and tenant-scoped
  zone assignment with write-only credentials.
- `configure_api_v1`: write-only tenant API credential provisioning.

The existing CLI, Flask blueprint, zones, agent code, and UI automation remain
available as legacy interfaces. They are not exported as Standard v1
capabilities yet.

## WordPress

The optional `aroflo_connector_wp` App Pack provides the
`[ams_aroflo_connector_console]` shortcode. It manages write-only API and BOT
credentials, assigned zones, live BOT state, connection, MFA, and the optional
30-day trusted-device preference. Stored credentials are never returned.

Custom WordPress applications can call the public PHP functions
`ams_aroflo_connector_zones()`, `ams_aroflo_connector_bots()`,
`ams_aroflo_connector_bot_status()`, `ams_aroflo_connector_bot_connect()`,
`ams_aroflo_connector_bot_mfa()`, and
`ams_aroflo_connector_bot_disconnect()`. Authenticated REST equivalents are
available below `/wp-json/ams-aroflo/v1`. Access requires `manage_options` by
default and can be integrated with a custom authorization policy through the
`ams_aroflo_connector_rest_permission` filter.

## Local validation

From `/var/www/html/flask_server`:

```text
PYTHONDONTWRITEBYTECODE=1 venv/bin/python -m unittest \
  apps.aroflo_connector_app.tests.contract_checks
venv/bin/python scripts/validate_app_contract.py aroflo_connector_app
php -l apps/aroflo_connector_app/wordpress-pack/aroflo-connector-wp/aroflo-connector-wp.php
```

Automated tests mock AroFlo and never use real tenant credentials.

## UI worker security

The worker resolves `ui_worker_shared_secret` from the tenant vault and
requires a unique `AROFLO_UI_WORKER_ID` per worker node. Every
request is signed over method, path, timestamp, nonce, and body. Replay nonces,
BOT state, and operation leases are stored in the shared control plane.

Worker requests require both `tenant_id` and `bot_id`. Browser runtimes are
keyed by that pair and credentials are resolved from the tenant vault; global
`AROFLO_USERNAME` and `AROFLO_PASSWORD` are not used by the hardened path.
The public session lifecycle is `bot_status_v1`, `connect_bot_v1`,
`submit_bot_mfa_v1`, and `disconnect_bot_v1`.

## Normalized users pilot

The first domain contract publishes `aroflo.users.list`, `aroflo.users.get`,
and `aroflo.users.search`. WordPress can exercise the same contract with
`[ams_aroflo_connector_lab]`. Flask console example:

```text
venv/bin/python -m apps.aroflo_connector_app.cli contract-users \
  --tenant-id absolutems \
  --filter 'display_name:contains:Carolina Penuela'
```