smom-dbis-138/docs/hybx-omnl/OPERATIONAL_COMPLIANCE.md

# 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_REQUIRE_API_KEY=1`** (or `NODE_ENV=production`): all `/api/v1/omnl/*` routes require `OMNL_API_KEY` except `/omnl/openapi.json`, `/omnl/catalog`, `/omnl/integration-status`.
- **`OMNL_API_KEY`**: when set, sensitive routes require `Authorization: Bearer <key>` or `?access_token=<key>`.
- **Audit log**: `OMNL_AUDIT_LOG_PATH` (default `reports/audit/omnl-audit.jsonl`) — append-only JSONL for API, Fineract, webhooks, ISO 20022.
- **Triple reconcile**: `GET /api/v1/omnl/reconcile/triple-state?lineId=0x...` — Fineract GL + on-chain + `config/omnl-custodian-snapshot.json`.
- **IFRS disclosures**: `GET /api/v1/omnl/disclosures/full` (requires accountant review).
- **ISO 20022 store**: `POST /api/v1/omnl/iso20022/messages` — see `config/iso20022-omnl/README.md`.
- **`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).

## Operator compliance console

- **Public UI:** `https://explorer.d-bis.org/omnl/compliance` — posture, pending actions (Safe notary gate, DefiLlama PRs), on-chain evidence, triple reconcile snapshot.
- **JSON API:** `GET /api/v1/omnl/compliance/console` (requires `OMNL_API_KEY` unless `OMNL_COMPLIANCE_CONSOLE_PUBLIC=1` on token-aggregation).
- **Safe notary gate:** `GET /api/v1/omnl/compliance/safe-notary-gate-tx` or `pnpm omnl:safe-notary-gate-tx` → `reports/status/omnl-safe-notary-gate-tx.json`. Exec: `pnpm omnl:safe-notary-gate-exec` (needs **3-of-5** sigs from **current** Safe owners) or import into Safe UI.
- **Owner key alignment:** If automated exec reports `signers_available=1`, run owner swap per [OMNL_SAFE_OWNER_KEYS_RUNBOOK.md](../../../docs/03-deployment/OMNL_SAFE_OWNER_KEYS_RUNBOOK.md) (`pnpm compliance:omnl:safe:reconcile-keys`, `pnpm compliance:omnl:safe:owner-swap-tx`).
- **Deploy:** `bash scripts/deployment/sync-token-aggregation-vmid5000.sh` (full build + nginx `/omnl/` patch). Explorer Operator nav link: `bash explorer-monorepo/scripts/deploy-next-frontend-to-vmid5000.sh`.

## 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).