# Operational compliance (OMNL)

## Webhooks

- Configure `OMNL_WEBHOOK_URLS` (comma-separated HTTPS endpoints).
- Set `OMNL_WEBHOOK_SECRET`. Each POST body is **UTF-8 JSON**; **`X-OMNL-Signature`** = `sha256=` + **hex(HMAC-SHA256(secret, rawBody))** (same bytes as the request body). Use `verifyOmnlWebhookSignature()` from `omnl-webhooks.ts` or reimplement with the same algorithm. **Timing-safe** compare the full header value.
- Payloads include **`deliveryId`** (e.g. `138-12345-2`) for idempotent processing at the receiver.
- Prefer allowlists and TLS 1.2+ only; rotate secrets on break-glass.

## API hardening

- **`OMNL_API_KEY`**: when set, `GET /api/v1/omnl/ipsas/fineract-compare` and `.../compliance-context/:lineId` require `Authorization: Bearer <key>` or `?access_token=<key>`.
- **`OMNL_DASHBOARD_TOKEN`**: when set, `GET /omnl/dashboard` requires the same token via `?access_token=` or header `X-OMNL-Dashboard-Token`. For Fineract compare in the embedded page, open **`/omnl/dashboard?access_token=<OMNL_API_KEY>`** so the script can call protected routes.
- **OMNL rate limit**: `OMNL_RATE_LIMIT_MAX` / `OMNL_RATE_LIMIT_WINDOW_MS` (default 30/min per IP on `/api/v1/omnl/*`, in addition to the global API limiter).

## Logs and retention

- Reserve commit and compliance events are emitted to application logs; align retention with your policy (often 90 days minimum for financial audit support).
- **Config anchor (IPSAS / journal matrix):** after registry/matrix JSON changes, run `bash scripts/hybx-omnl/omnl-reconcile-artifact.sh` — this hashes **off-chain config files only**, not custodian bank balances vs on-chain `R`. Use a separate control for **bank ↔ on-chain** reconciliation if required for your auditor.
- Automate anchors via cron or GitHub Actions — [OMNL_RECONCILE_CRON_AND_CI.md](OMNL_RECONCILE_CRON_AND_CI.md).

## Poller state

- **`OMNL_POLLER_STATE_PATH`**: optional path for JSON storing last processed block per chain (default: `.omnl-poller-state.json` in `cwd`). Survives restarts to avoid re-querying large ranges; webhook consumers should still treat **`deliveryId`** as idempotent.

## Recommended alerts (operational)

Wire your log/metrics stack to alert on:

- Webhook POST failures (warn logs from `omnl-webhooks.ts`).
- `reportingCompliant === false` or `attestationStale` from compliance APIs for critical `lineId`s.
- `mirror-status` / `inSync === false` when both reserve stores are configured.
- Repeated `401` on OMNL routes (possible credential scanning).

## Break-glass

- Document who can pause `OMNLCircuitBreaker` and rotate coordinator keys; store procedures outside this repo per org policy.

## Data minimization

- Webhook payloads avoid full PII; line IDs and hashes only unless contractually required.

## External audit

- See [EXTERNAL_AUDIT_CHECKLIST.md](EXTERNAL_AUDIT_CHECKLIST.md).