# Monetarie SPB — Deep System Audit: Master Gap Analysis

**Date**: 2026-02-08
**Auditor**: Claude Opus 4.6
**Objective**: Identify ALL gaps before BACEN homologation testing
**Areas Audited**: NATS, Database, Backend, IBM MQ, BACEN Protocol, Frontend, Security

---

## EXECUTIVE SUMMARY

| Area | Status | Risk | Gaps Found |
|------|--------|------|------------|
| **NATS JetStream** | NOT READY | CRITICAL | 14 gaps |
| **Database Integrity** | MODERATE RISK | HIGH | 15 gaps |
| **IBM MQ / BACEN Connection** | NOT READY | CRITICAL | 4 gaps |
| **BACEN Protocol Compliance** | INCOMPLETE | CRITICAL | 7 gaps |
| **Backend Resilience** | PARTIAL | HIGH | 8 gaps |
| **Authentication/Security** | PARTIAL | HIGH | 5 gaps |
| **Frontend-Backend Integrity** | MODERATE | MEDIUM | 8 gaps |
| **Monitoring/Observability** | MINIMAL | MEDIUM | 5 gaps |
| **TOTAL** | | | **66 gaps** |

**VERDICT**: System is **NOT READY for BACEN homologation**. Requires focused remediation.

---

## TIER 1: CRITICAL BLOCKERS (Must fix before any BACEN contact)

### CB-01: NATS Using Core Pub/Sub Instead of JetStream
- **Impact**: Zero message persistence. System restart = data loss
- **Files**: `nats/publisher.ex`, `consumers/message_consumer.ex`
- **Fix**: Add `jetstream` library, create streams, use durable consumers with ack/nak

### CB-02: No JetStream Durable Consumers
- **Impact**: Ephemeral subscriptions lost on pod restart
- **Files**: `consumers/message_consumer.ex`
- **Fix**: Configure durable consumers with explicit ack policy

### CB-03: No Message Acknowledgment in NATS
- **Impact**: Fire-and-forget processing. Failed messages never retried by NATS
- **Files**: `consumers/message_consumer.ex:56-64`
- **Fix**: Replace `Task.start` with ack/nak/term flow

### CB-04: XMLDSig Signature Verification Incomplete
- **Impact**: ALL inbound BACEN messages will be rejected
- **Files**: `crypto/xmldsig.ex`, `security/signature_manager.ex`
- **Fix**: Complete certificate chain validation, add CRL/OCSP

### CB-05: No ICP-Brasil CA Certificates
- **Impact**: Certificate chain validation fails on 100% of messages
- **Files**: `security/signature_manager.ex:181-193`
- **Fix**: Load ICP-Brasil root + intermediate CAs from K8s Secret

### CB-06: Security Header Encryption Not Implemented
- **Impact**: Messages lack required AES-256 encryption per BACEN spec
- **Files**: `security/security_header.ex:104-108`
- **Fix**: Implement AES-256 + RSA-2048 key encryption

### CB-07: No Active MQ Consumer (Cannot Receive BACEN Responses)
- **Impact**: Cannot receive R1/R2/R3/COA/COD from BACEN
- **Files**: `mq/mq_consumer.ex`, `mq/domain_manager.ex`
- **Fix**: Implement active MQ queue polling with MQGET + SYNCPOINT

### CB-08: No SSL/TLS on MQ Channels
- **Impact**: BACEN requires mTLS. Connections will be refused
- **Files**: `k8s/production/ibmmq-deployment.yaml`
- **Fix**: Configure SSL cipher suites, client certificates, CERTLABL

### CB-09: No BCMSG/SISMSG Message Envelope Structure
- **Impact**: Messages rejected by BACEN for malformed structure
- **Fix**: Build 3-layer envelope (BCMSG → SISMSG → USERMSG/ISO20022)

### CB-10: ZERO Foreign Key Constraints in Database
- **Impact**: Data orphaning, referential integrity violations
- **Files**: All 10 migration files
- **Fix**: Add FK constraints to bacen_messages, operation_events, message_tracking

---

## TIER 2: HIGH PRIORITY (Fix within 2 weeks)

### HP-01: No Circuit Breaker Pattern
- **Impact**: Cascading failures when BACEN/MQ is down
- **Fix**: Implement circuit breaker with states (closed/open/half_open)

### HP-02: No Transaction Wrapping for Multi-Table Operations
- **Impact**: Partial writes, data inconsistency
- **Files**: `operations_controller.ex` (update_state, send_bulk, create)
- **Fix**: Wrap in `Repo.transaction/1`

### HP-03: No Rate Limiting on API
- **Impact**: DoS vulnerability, brute-force attacks
- **Fix**: Add RateLimitPlug (100 req/min general, 5 req/min auth)

### HP-04: NATS Single-Node Connection (No Cluster Failover)
- **Impact**: Single point of failure
- **Files**: `application.ex:21-27`
- **Fix**: Configure all 3 NATS cluster nodes

### HP-05: Missing Composite Database Indexes
- **Impact**: Slow queries on 40K+ messages during peak BACEN windows
- **Fix**: Add ~20 composite indexes on bacen_messages, operation_events, etc.

### HP-06: No Optimistic Locking (Race Conditions)
- **Impact**: Lost updates in concurrent operations
- **Files**: `operations_controller.ex`
- **Fix**: Add `lock_version` column + WHERE clause

### HP-07: Schema-Database Field Mismatch (BacenMessage)
- **Impact**: Runtime errors accessing non-existent columns
- **Files**: `bacen_message.ex` — 15+ fields misaligned with DB
- **Fix**: Create migration to align DB with schema

### HP-08: 27+ Tables Missing Migration Files
- **Impact**: Schema drift, no version control for 73% of tables
- **Fix**: Create migration files for all tables created in seeds

### HP-09: JWT Secret Fallback to Hardcoded Dev Secret
- **Impact**: Production security bypass if env var missing
- **Files**: `auth/jwt.ex:10-14`
- **Fix**: Crash on startup if secret not configured

### HP-10: No Token Refresh Mechanism
- **Impact**: Users logged out unnecessarily, lost work
- **Files**: Frontend `api.ts`, Backend `auth_controller.ex`
- **Fix**: Add refresh token endpoint + interceptor logic

### HP-11: Blocking Process.sleep in Error Handler
- **Impact**: Blocks GenServer, prevents message processing
- **Files**: `error_handler.ex:106`, `legacy_parity.ex:272`
- **Fix**: Use `Process.send_after/3` for async retry

### HP-12: No Message Ordering Guarantees
- **Impact**: Financial messages processed out-of-order
- **Files**: `message_consumer.ex:59-61`
- **Fix**: Use JetStream ordered consumers or single-threaded processing per operation_id

### HP-13: No DLQ Max Size / Purge Policy
- **Impact**: Unbounded table growth
- **Fix**: Add auto-archive, size limits, alerts

### HP-14: Frontend Transaction Field Mapping Broken
- **Impact**: Transaction table shows "undefined" values
- **Files**: `TransactionsView.vue`
- **Fix**: Map sender_ispb→from_account, receiver_ispb→to_account, inserted_at→created_at

---

## TIER 3: MEDIUM PRIORITY (Fix within 1 month)

### MP-01: No Health Checks for NATS/MQ in Readiness Probe
### MP-02: No Prometheus Metrics Endpoint
### MP-03: No Session Revocation (tokens valid 24h after logout)
### MP-04: No API Key Rotation Policy
### MP-05: No Structured JSON Logging with Correlation IDs
### MP-06: No Request ID Tracing (Plug.RequestId)
### MP-07: No Graceful Shutdown for NATS Subscriptions
### MP-08: No Load Balancing Across NATS Consumers (Queue Groups)
### MP-09: No Backpressure Mechanism (Unlimited Async Tasks)
### MP-10: No Message Deduplication in Consumer
### MP-11: No Sequence Number Management (BACEN requires monotonic)
### MP-12: No Operating Schedule Validation (accepts messages 24/7)
### MP-13: Incomplete Message Handlers (30+ empty stubs)
### MP-14: No Config Validation at Startup
### MP-15: No Runtime Type Validation in Frontend (Zod)
### MP-16: No Error Boundary Components in Frontend
### MP-17: WebSocket Message Queuing During Reconnection
### MP-18: Inconsistent Error Response Format (success/error vs success/errors)

---

## TIER 4: LOW PRIORITY (Ongoing improvement)

### LP-01: No Read Replica Support for Dashboard Queries
### LP-02: No Connection Pool Monitoring
### LP-03: Ecto Associations Missing (N+1 risk)
### LP-04: No Binary Protocol for WebSocket
### LP-05: skipLibCheck: true in TypeScript Config
### LP-06: Missing NOT NULL Constraints on Some Fields

---

## RECOMMENDED IMPLEMENTATION ORDER

### Sprint 1 (Week 1-2): Foundation & Data Integrity
1. Database migrations: FKs, indexes, schema alignment (CB-10, HP-05, HP-07, HP-08)
2. Transaction wrapping for multi-table ops (HP-02)
3. Optimistic locking (HP-06)
4. Circuit breaker implementation (HP-01)
5. Rate limiting (HP-03)
6. JWT secret validation (HP-09)

### Sprint 2 (Week 3-4): NATS JetStream
1. Add jetstream library (CB-01)
2. Create streams on startup (CB-01)
3. Durable consumers with ack/nak (CB-02, CB-03)
4. Cluster failover config (HP-04)
5. DLQ stream at NATS level
6. Message ordering guarantees (HP-12)

### Sprint 3 (Week 5-6): BACEN Protocol & Crypto
1. XMLDSig signature verification (CB-04)
2. ICP-Brasil CA certificates (CB-05)
3. Security header AES encryption (CB-06)
4. BCMSG/SISMSG envelope structure (CB-09)
5. Sequence number management (MP-11)

### Sprint 4 (Week 7-8): IBM MQ & Integration
1. Active MQ consumer implementation (CB-07)
2. SSL/TLS on MQ channels (CB-08)
3. Health checks for NATS/MQ (MP-01)
4. Prometheus metrics (MP-02)
5. Structured logging (MP-05)

### Sprint 5 (Week 9-10): Frontend & Testing
1. Token refresh mechanism (HP-10)
2. Transaction field mapping fix (HP-14)
3. Error handling improvements
4. End-to-end integration tests against simulator
5. Load testing (target: 1000 msg/sec)

---

## BACEN BOOK 5.11 UPDATE READINESS

The BACEN updates its Manual de Redes (Book 5.11) approximately 2x per year. To ensure smooth updates:

### Current Gaps for Update Readiness:
1. **No versioned message schema registry** — When BACEN adds/modifies message types, we need to update 979+ modules. Currently manual.
2. **No XSD validation pipeline** — Should auto-validate against BACEN-published XSDs
3. **No feature flag system** — Can't gradually roll out new message types
4. **No blue-green deployment** — Need zero-downtime updates during clearing hours
5. **No rollback strategy** — If new message types fail, need instant rollback

### Recommended Architecture for Update Readiness:
1. **XSD Registry Service**: Auto-download and cache BACEN XSDs
2. **Schema Version Manager**: Track which BACEN spec version each module implements
3. **Feature Flags**: Enable/disable message types per institution
4. **Canary Deployment**: Route 1% of traffic to new version before full rollout
5. **Automated Test Suite**: Run all 979 message types against new XSDs before deploy

---

## WHAT'S ALREADY EXCELLENT

Despite the gaps, the system has strong foundations:

- 979 message types registered and mapped
- 529 R1/R2/R3 response modules generated
- Full lifecycle state machine (LifecycleEngine + CoaCodHandler)
- 58 operation status codes (legacy parity)
- 40 database tables with seed data
- ~100+ API endpoints across 18 controllers
- Vue 3 + TypeScript strict mode frontend with zero mock data
- Phoenix Channels for real-time monitoring
- Proper OTP supervision tree with 13 children
- Dead Letter Queue with categorized error handling
- GKE deployment with Cloud SQL Proxy
- IBM MQ deployed with 21 BACEN queues defined

**The architecture is SOUND. The implementation needs completion in critical areas.**

---

*Generated by Claude Opus 4.6 — Deep System Audit*
*Total files analyzed: ~200+ across backend, frontend, database, and infrastructure*