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_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.

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.