- Overview
- Architecture
- Features
- Components
- Installation
- Usage
- API Reference
- Authentication Flow
- Security Features
- Demo Credentials
- Technologies Used
This project is an innovative authentication platform built for the Nafath Hackathon that combines:
- Visual Authentication - A revolutionary approach using animated 3D particle nebulas with encoded color sequences
- QR Code Authentication - Traditional secure scanning method
- AI-Powered Risk Analysis - Real-time fraud detection using OpenAI's o3 model
- Mobile Approval Workflow - Flutter-based app mimicking the Nafath experience
The system provides a secure, multi-factor authentication solution for Saudi Arabian government and financial services, including banks, telecom providers, and government ministries.
┌─────────────────────────────────────────────────────────────────────────────┐
│ NAFATH AUTHENTICATION PLATFORM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────┐ WebSocket ┌────────────────────┐ │
│ │ Desktop Client │◄──────────────────►│ Express Server │ │
│ │ (React + Three) │ │ (Socket.io) │ │
│ │ │ │ Port: 3000 │ │
│ │ • 3D Nebula │ └────────────────────┘ │
│ │ • QR Generator │ │
│ │ • Session Manager │ │
│ └────────────────────┘ │
│ │ │
│ │ Visual/QR Scan │
│ ▼ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ Mobile Scanner │ │ Flask Backend │ │
│ │ (React) │ │ Port: 8002 │ │
│ │ │ │ │ │
│ │ • Camera Capture │ HTTP/REST │ • Request Store │ │
│ │ • Color Decoder │ │ • Approval Logic │ │
│ │ • QR Scanner │ │ • AI Risk Engine │ │
│ └────────────────────┘ └────────────────────┘ │
│ │ │
│ │ Polls │
│ ▼ │
│ ┌────────────────────┐ │
│ │ Flutter App │ │
│ │ (Nafath Replica) │ │
│ │ │ │
│ │ • Request Display │ │
│ │ • Approval Timer │ │
│ │ • Accept/Reject │ │
│ └────────────────────┘ │
│ │ │
│ │ On Approve │
│ ▼ │
│ ┌────────────────────┐ │
│ │ OpenAI o3 │ │
│ │ Risk Analysis │ │
│ │ │ │
│ │ • Fraud Detection │ │
│ │ • Pattern Analysis│ │
│ │ • Risk Scoring │ │
│ └────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
- 3D Animated Nebula - Particle-based sphere with 4000+ particles using Three.js shaders
- Dual-Layer Color Encoding - Core and Aura colors create a 4-step visual sequence
- Camera-Based Decoding - Mobile camera reads RGB color patterns in real-time
- Rotation-Invariant Matching - Sequences can be read starting from any point
- Fuzzy Matching - 50%+ similarity threshold for reliable detection
- Dynamic QR Generation - Session-specific codes with challenge tokens
- 30-Second Challenge Windows - Time-based security tokens
- Instant Verification - Fallback for environments where visual scanning isn't optimal
- OpenAI o3 Integration - Advanced reasoning model for fraud detection
- Multi-Signal Analysis - Evaluates device, location, behavior patterns
- Contextual Scoring - 0-100 risk score with LOW/MEDIUM/HIGH/CRITICAL levels
- Detailed Reporting - Comprehensive risk reasons and assessments
- Real-Time Notifications - Polling-based request detection
- Visual Timer - 60-second countdown with animated progress
- One-Tap Actions - Accept or reject with immediate feedback
- Device Fingerprinting - Browser/device identification via WebGL, Canvas, Audio
- IP Intelligence - City, country, VPN detection
- Historical Pattern Analysis - Behavioral anomaly detection
- Challenge-Response Protocol - Cryptographic handshake verification
A React + Vite application featuring:
| Feature | Description |
|---|---|
| Desktop View | 3D particle nebula with color-encoded authentication |
| Scanner View | Camera-based visual pattern decoder |
| Login System | User authentication before scanning |
| Real-time Sync | Socket.io WebSocket communication |
Key Technologies:
- React 19.2 with React Router
- Three.js via React Three Fiber & Drei
- Framer Motion animations
- Tailwind CSS styling
- Socket.io client
A Flutter cross-platform application:
| Feature | Description |
|---|---|
| Request Polling | Fetches pending auth requests every 5 seconds |
| Circular Timer | Custom-painted 60-dash countdown display |
| Approval Actions | Accept/Reject buttons with API integration |
| Auto-Timeout | Automatic rejection when timer expires |
Supported Platforms:
- iOS
- Android
- Web
- macOS
- Windows
- Linux
Python Flask API with AI integration:
| Endpoint | Method | Description |
|---|---|---|
/api/request |
POST | Store authentication request |
/api/request |
GET | Retrieve pending request |
/api/approval |
POST | Submit approval decision |
/api/approval |
GET | Fetch approval result with risk analysis |
Additional Tools:
fingerprinter.html- Browser fingerprint generatorrequest_builder_2.html- Interactive request builder UIrequest_properties.json- Request schema definition
- Node.js 18+ (for web frontend)
- Flutter 3.8+ (for mobile app)
- Python 3.9+ (for backend)
- OpenAI API Key (for AI risk analysis)
git clone https://github.com/your-repo/NafathHackathonAll.git
cd NafathHackathonAllcd absher-hakathon
# Install dependencies
npm install
# Start development server (includes Express backend)
npm run devThe server runs on http://localhost:5173 (Vite) with WebSocket on port 3000.
cd NafathBackend/backend
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Add your OpenAI API key
# Edit agent.py and replace "OPENAI_KEY" with your actual key
# Start the server
python app.pyThe API runs on http://localhost:8002.
cd nafath_replica
# Get dependencies
flutter pub get
# Run on your preferred platform
flutter run # Auto-detect device
flutter run -d chrome # Web browser
flutter run -d macos # macOS
flutter run -d ios # iOS simulator
flutter run -d android # Android emulator- Open Desktop App - Navigate to
http://localhost:5173 - View Nebula - A 3D particle sphere with encoded colors appears
- Toggle QR Mode - Click "Show QR Code" for easier scanning
- Login - Go to
http://localhost:5173/login- Username:
user1oruser2 - Password:
password
- Username:
- Scan - Point camera at desktop nebula or QR code
- Authenticate - Session pairs automatically on match
- Open Builder - Open
NafathBackend/request_builder_2.htmlin browser - Configure Request - Fill in operation details, requester context
- Submit - Send to backend
- Approve in App - Open Flutter app and accept/reject
- View Risk - Risk analysis appears after approval
- Launch App - The app shows "Waiting for requests"
- Receive Request - When a request is sent, it displays with a timer
- Approve/Reject - Tap the appropriate button
- AI Analysis - On approval, risk assessment is generated
POST /api/request
Content-Type: application/json
{
"request_metadata": {
"target_national_id": "1234567890"
},
"operation_details": {
"client_name": "STC_BANK",
"operation_type": "OPEN_BANK_ACCOUNT",
"operation_sensitivity": "HIGH"
},
"requester_context": {
"device": { ... },
"ip_information": { ... }
}
}GET /api/requestPOST /api/approval
Content-Type: application/json
{
"status": "approved"
}GET /api/approvalResponse includes AI risk analysis:
{
"status": "success",
"approval_risk": {
"risk_score": 35,
"risk_level": "MEDIUM",
"risk_reasons": ["First-time device usage", "IP city mismatch"],
"overall_assessment": "Some anomalies detected but within acceptable parameters.",
"analysis_confidence": 75
}
}[Service Provider] [Backend] [Mobile App] [AI Engine]
│ │ │ │
│ 1. POST /api/request │ │ │
│────────────────────────────►│ │ │
│ │ │ │
│ │ 2. GET /api/request │ │
│ │◄─────────────────────────│ (polling every 5s) │
│ │ │ │
│ │ 3. Request Data │ │
│ │─────────────────────────►│ │
│ │ │ │
│ │ │ 4. User Decision │
│ │ │ (60s timer) │
│ │ │ │
│ │ 5. POST /api/approval │ │
│ │◄─────────────────────────│ │
│ │ │ │
│ │ 6. Analyze Risk │ │
│ │─────────────────────────────────────────────────►│
│ │ │ │
│ │ 7. Risk Assessment │ │
│ │◄─────────────────────────────────────────────────│
│ │ │ │
│ 8. GET /api/approval │ │ │
│◄────────────────────────────│ │ │
│ (includes risk analysis) │ │ │
| Layer | Protection |
|---|---|
| Color Encoding | 4-step RGB sequence with core/aura dual-layer |
| Rotation Tolerance | All 4 rotations mapped for flexible reading |
| Fuzzy Matching | 50% similarity threshold prevents false negatives |
| Session Isolation | Each session has unique sequence |
| Feature | Implementation |
|---|---|
| Time-Based Tokens | 30-second challenge windows |
| SHA-256 Hashing | Cryptographic challenge generation |
| Window Tolerance | Current + previous window accepted |
| Secret Key | Server-side secret for token generation |
| Signal Group | Factors Analyzed |
|---|---|
| Device Context | Device hash, user agent, browser, OS |
| IP Intelligence | City, country, VPN status, ISP |
| Behavioral Patterns | Request frequency, historical cities, device usage |
| Temporal Analysis | 24-hour activity, session duration, timeouts |
| Data Consistency | Name, phone, address verification |
| Username | Password | Role |
|---|---|---|
user1 |
password |
Admin |
user2 |
password |
Visitor |
- Ministry of Justice
- Real Estate Registrars
- STC Bank / STC
- SAB Bank / Al Rajhi Bank / Alinma Bank
- Monshaat
- Ejar
- Mobily
- Platform Login
- Register Account
- Issue Power of Attorney
- Open Bank Account
- Issue New SIM
- Verify Trusted Device
- Verify Loan Request
| Technology | Version | Purpose |
|---|---|---|
| React | 19.2.0 | UI Framework |
| Vite | 7.2.4 | Build Tool |
| Three.js | 0.181.2 | 3D Graphics |
| React Three Fiber | 9.4.0 | React + Three.js Bridge |
| Socket.io Client | 4.8.1 | WebSocket Communication |
| Framer Motion | 12.23.24 | Animations |
| Tailwind CSS | 3.4.17 | Styling |
| Lucide React | 0.554.0 | Icons |
| Technology | Version | Purpose |
|---|---|---|
| Flask | 3.0.0 | API Framework |
| Flask-CORS | 4.0.0 | Cross-Origin Requests |
| OpenAI | Latest | AI Risk Analysis (o3 model) |
| Express | 5.1.0 | WebSocket Server |
| Socket.io | 4.8.1 | Real-time Communication |
| Technology | Version | Purpose |
|---|---|---|
| Flutter | 3.8.1 | Cross-Platform Framework |
| http | 1.5.0 | HTTP Client |
| cupertino_icons | 1.0.8 | iOS Icons |
NafathHackathonAll/
├── absher-hakathon/ # Web Frontend (React + Vite)
│ ├── src/
│ │ ├── components/
│ │ │ ├── Login.jsx # User authentication
│ │ │ ├── Scanner.jsx # Visual/QR scanner
│ │ │ ├── ParticleField.jsx # 3D nebula shader
│ │ │ └── OverlayUI.jsx # UI overlays
│ │ ├── App.jsx # Main app with routing
│ │ └── main.jsx # Entry point
│ ├── server.js # Express + Socket.io server
│ └── package.json
│
├── nafath_replica/ # Flutter Mobile App
│ ├── lib/
│ │ ├── main.dart # App entry point
│ │ └── process_screen.dart # Request approval screen
│ └── pubspec.yaml
│
├── NafathBackend/ # Python Backend
│ ├── backend/
│ │ ├── app.py # Flask API
│ │ ├── agent.py # OpenAI risk analysis
│ │ ├── prompt.txt # AI system prompt
│ │ └── requirements.txt # Python dependencies
│ ├── fingerprinter.html # Device fingerprinting tool
│ ├── request_builder_2.html # Request builder UI
│ └── request_properties.json # Request schema
│
└── README.md # This file
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project was created for the Nafath Hackathon.
- Nafath - For the hackathon opportunity
- OpenAI - For the o3 reasoning model
- Three.js Community - For shader examples and guidance
Built with ❤️ for the Nafath Hackathon