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.

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 lineIds.
• 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.