# WebForm-mw — CiviCRM extension

Adds an **Engagement Report** tab to Organization contact-view pages that
embeds the FCI Co-op Survey staff report
(`https://survey.fci.coop/staff/report`) in an iframe. The tab shows the
report for the current organization, scoped by the contact id in the URL.

The embedded app handles its own auth via a shared staff secret. The
extension is otherwise read-only and adds no Civi tables, custom fields,
or scheduled jobs.

## Install

1. Copy the entire `webform-mw/` directory to your CiviCRM extensions
   directory (typically `<civi-root>/sites/default/ext/` or wherever
   `[civicrm.extensionsDir]` points in your `civicrm.settings.php`).
   - The directory name on disk must be `webform-mw` (matching `<key>` in
     `info.xml`).
2. In CiviCRM:
   `Administer → System Settings → Extensions → Add new → Refresh`,
   then click **Install** next to "WebForm-mw".
3. Configure (see next section). The tab will be hidden until both
   settings are present.

## Configuration

The extension reads two values, in this order:

1. Constants in `civicrm.settings.php` (preferred):

   ```php
   define('WEBFORM_MW_APP_URL',   'https://survey.fci.coop');
   define('WEBFORM_MW_STAFF_KEY', '...the STAFF_REPORT_KEY shared with the app...');
   ```

2. Or environment variables (`WEBFORM_MW_APP_URL`, `WEBFORM_MW_STAFF_KEY`)
   set wherever PHP-FPM / the web server reads its environment from.

`WEBFORM_MW_STAFF_KEY` must match the `STAFF_REPORT_KEY` configured on the
Next.js app (Amplify environment / SSM Parameter Store). The two are the
same shared secret; rotate them together.

`WEBFORM_MW_APP_URL` is the public base URL of the WebForm-mw deployment
(no trailing slash). Production: `https://survey.fci.coop`.

When either value is missing, the tab body shows a help banner with the
exact configuration snippet to paste, so anyone installing the extension
without prior context can self-serve.

## Behaviour

- Tab title: **Engagement Report**.
- Visible only on **Organization** contacts (Individuals and Households
  see no tab). The check happens server-side in the tabset hook.
- Tab body is an iframe pointing at
  `${WEBFORM_MW_APP_URL}/staff/report?org=<cid>&exp=<unix>&sig=<hmac>&frame=1`.
- `frame=1` tells the embedded app to suppress its site header/footer
  and emit a `postMessage({type:"webform-mw-height", height})` payload
  on render and on resize. The tab's small inline script listens for
  this message and auto-sizes the iframe so there's no nested scrollbar.
- The script validates the postMessage `event.origin` against the
  configured `WEBFORM_MW_APP_URL` origin before resizing.

## Security notes

- The shared secret never leaves the server. Each tab render mints a
  signed token, `HMAC-SHA256(secret, "webform-mw.staff-report.v1:<org>:<exp>")`,
  valid for one org for 8 hours. The app rejects tokens for other orgs,
  expired tokens, and anything valid for longer than 12 hours.
- Tokens are only minted after `CRM_Contact_BAO_Contact_Permission::allow()`
  confirms the current user can view the org, so Civi contact ACLs carry
  through to the embedded report.
- Rotating the secret: change `WEBFORM_MW_STAFF_KEY` and the app's
  `STAFF_REPORT_KEY` together; outstanding tokens stop working at once.
- The extension uses `access CiviCRM` as its access argument — anyone
  with that permission sees the tab on Organization contacts. Tighten by
  changing the `<access_arguments>` value in `xml/Menu/webform_mw.xml`
  to a more specific permission (e.g., `view all contacts`) and
  reinstalling.
- The embedded app's CSP (`frame-ancestors`) must include the CiviCRM
  origin or the iframe will refuse to render. The Next app reads
  `CIVI_BASE_URL` at build time and adds its origin to the staff route's
  CSP automatically. Confirm with `curl -I <app>/staff/report` after
  deploy — you should see `Content-Security-Policy: ... frame-ancestors
  'self' https://<your-civi-host> ...`.

## Files

- `info.xml` — extension manifest. Key `webform-mw`, type `module`.
- `webform_mw.php` — `hook_civicrm_tabset` + config readers.
- `CRM/WebformMw/Page/Tab.php` — page controller for the tab snippet.
- `templates/CRM/WebformMw/Page/Tab.tpl` — iframe + height-listener.
- `xml/Menu/webform_mw.xml` — registers the
  `civicrm/contact/view/engagement-report` URL.

## Versions tested

- CiviCRM 5.50+
- PHP 7.4+ / 8.x
- Tested against Backdrop-as-host and Drupal-as-host CiviCRM deployments.

## Uninstalling

`Administer → Extensions → Disable`, then `Uninstall`. Removes nothing
from the database; the extension stores no Civi data of its own.