core: implement real-time events via Supabase Realtime

[Godfrey-Delight]

🔗 Related Issue

Closes #30

---

🔖 Title

Implementation of real-time events via Supabase Realtime

---

📝 Description

Adds real-time notifications via Supabase Realtime (replication on loan_index/payment_index) and a standalone WebSocket gateway (port 3005), so loan status changes and payment confirmations broadcast immediately instead of requiring polling. Includes indexer event handlers wiring LOAN_CREATED/LOAN_REPAID/LOAN_DEFAULTED to broadcasts, and an integration guide for clients. Closes #30

---

🔄 Changes Made

• Migration to enable Supabase Realtime on loan_index and payment_index
• Standalone WebSocket gateway (port 3005) + realtime.service.ts broadcast helpers
• Indexer event handlers wired to broadcast on LOAN_CREATED/LOAN_REPAID/LOAN_DEFAULTED, plus integration guide

---

📸 Screenshots (if applicable)

---

🗒️ Additional Notes

[EmeditWeb]

Review verdict: ❌ Request changes (security — data leak)

The implementation is clean and well-tested (11 tests pass, no any), but the design leaks sensitive financial data.

The gateway is unauthenticated and unscoped. src/realtime/realtime.gateway.ts:

• wss.on('connection', ...) accepts any client that reaches WEBSOCKET_PORT — no JWT/token verification on the handshake.
• broadcast() sends every message to every connected client (this.wss.clients.forEach(... client.send(message))) — no per-user rooms/scoping.

And the payloads are per-user financial data. From realtime.handler.ts → realtime.service.ts:

• loan.status_changed → { loanId, userWallet, principalAmount, interestAmount, dueDate }
• payment.confirmed → { loanId, txHash, amount, paidAt }

So any anonymous client connecting to the WebSocket port receives every user's loan creations (wallet + amounts + due date), repayments, and defaults. That's a privacy/data-exposure vulnerability for a lending app.

Required before merge:

1. Authenticate the WS handshake (verify the same JWT used for HTTP; reject unauthenticated upgrades).
2. Scope delivery per user — only send a user events for their own wallet (rooms/subscriptions keyed to the authenticated wallet), or restrict broadcasts to genuinely public aggregate data.
3. Prefer the NestJS WebSocket adapter over a raw ws server on a separate port, so guards/CORS/origin checks apply consistently.