🔐 ZKAuth

Privacy-Preserving Identity Verification using Zero-Knowledge Proofs & ePassport Data

Verify your identity without revealing personal information. Powered by ZK-SNARKs and NFC passport reading.

Overview · How It Works · Architecture · Components · Quick Start · Use Cases

---

📖 Overview

ZKAuth is a decentralized identity verification system that enables users to prove attributes about themselves (like being over 18) without revealing their actual personal data. By combining:

• 📱 NFC-enabled passport reading on Android devices
• 🔐 Zero-Knowledge Proof generation using ZoKrates
• ⛓️ On-chain proof verification via Ethereum smart contracts
• 🌐 Web3-native DApp integration with modern frontend

Users can cryptographically prove claims about their identity while maintaining complete privacy over their sensitive passport data.

✨ Key Features

Feature	Description
🔏 Privacy-First	Your passport data never leaves your device. Only cryptographic proofs are shared.
✅ ICAO 9303 Compliant	Full support for international ePassport standards
🔗 On-Chain Verification	Proofs verified by Ethereum smart contracts for trustless verification
📱 Mobile-Native	Android app with OCR, NFC, and QR code support
🏛️ Decentralized	No central authority required for verification
🔄 Reusable Proofs	Generate proofs once, use across multiple DApps

---

🎯 How It Works

ZKAuth operates through a seamless flow between the mobile app, web DApps, and blockchain smart contracts.

System Architecture Overview

The complete verification flow involves 7 key steps:

1. MRZ Capture & NFC Scan - User reads their passport using the ZKAuth Android app
2. Secure Storage - Passport data is encrypted and stored locally on the device
3. QR Code Generation - DApp creates a verification challenge encoded as a QR code
4. QR Scanning - User scans the QR code with the ZKAuth app
5. ZK Proof Generation - App generates a zero-knowledge proof based on the challenge
6. Proof Submission - Proof is sent to the verification server
7. On-Chain Validation - Admin-side DApp fetches and validates the proof on-chain

Detailed Flow Diagrams

🔄 QR Code-Based Challenge Exchange

This diagram illustrates the interaction between the DApp and ZKAuth mobile app:

DApp Side:

1. User interacts with DApp and selects "Verify Age"
2. DApp creates a verification challenge with specific criteria
3. Challenge is encoded as JSON and converted to QR code
4. QR code is displayed on screen for the user

ZKAuth App Side:

1. User scans the QR code with the mobile app
2. App parses and validates the JSON challenge
3. Challenge data is stored and prepared for proof generation
4. App signals readiness for ZK proof generation

🛂 Passport Verification Flow

This comprehensive flow shows the complete passport onboarding process:

User Onboarding:

• User opens ZKAuth app and is prompted to add a passport
• Choice between OCR (camera) scanning or manual MRZ input

Key Generation & NFC:

• BAC key is derived from MRZ data
• Passport chip is read via NFC communication

Security Verification:

• ✅ BAC (Basic Access Control)
• ✅ PACE (Password Authenticated Connection Establishment)
• ✅ AA (Active Authentication)
• ✅ CA (Chip Authentication)
• ✅ CSCA (Certificate Authority Validation)

Data Handling:

• Data fields extracted from passport chip
• Encrypted and stored securely on device
• Identity data ready for ZK proof generation

---

🏗️ Architecture

ZKAuth/
├── 📱 PassportAndroidApp/          # Android mobile application
│   ├── app/src/main/
│   │   ├── java/example/jllarraz/  # Kotlin source code
│   │   │   ├── passport/           # Passport reading logic
│   │   │   ├── camera/             # OCR & QR scanning
│   │   │   ├── nfc/                # NFC communication
│   │   │   └── zk/                 # ZK proof generation
│   │   ├── assets/zokrates/        # ZoKrates proving keys
│   │   └── res/                    # Android resources
│   └── libs/                       # External libraries (JMRTD)
│
├── 🌐 ZK-Minimal-DApp/             # Web application & smart contracts
│   ├── Foundry-Backend/            # Solidity smart contracts
│   │   └── src/
│   │       ├── AuthBluePrint.sol   # Base authentication contract
│   │       └── RandomDApp.sol      # Example DApp implementation
│   ├── frontend/                   # Next.js React application
│   │   ├── app/                    # App router pages
│   │   ├── components/             # React UI components
│   │   └── contracts/              # Contract ABIs
│   └── zk-passport-auth/           # ZK verification system
│
└── 📊 media/                       # Documentation assets

---

🧩 Components

📱 Passport Android App

A comprehensive Android application for reading and verifying ePassport documents.

Features

Category	Capabilities
📖 Passport Reading	OCR-based MRZ scanning, NFC chip reading, Manual data entry
🔐 Security Protocols	BAC, PACE, EAC, Active Authentication, Chip Authentication
🔍 Verification	CSCA certificate chain validation, Cryptographic hash verification
📱 Mobile Features	QR code scanning, ZK proof generation, Encrypted local storage

Technical Stack

• Language: Kotlin
• NFC/Passport: JMRTD 0.7.35, Bouncy Castle
• OCR: Google ML Kit Text Recognition
• Camera: CameraX, ML Kit Barcode Scanning
• ZK Proofs: ZoKrates.js via WebView
• Security: Android Security Crypto, EncryptedSharedPreferences

Requirements

• Android 6.0+ (API Level 23)
• NFC-enabled device
• Camera for OCR/QR scanning

📚 Full Android App Documentation →

---

🌐 ZK Minimal DApp

A decentralized web application for requesting and verifying ZK proofs.

Features

Feature	Description
🔗 Wallet Integration	RainbowKit for seamless Web3 wallet connections
📱 QR Generation	Dynamic QR codes for verification requests
⛓️ Smart Contracts	Ethereum-based proof verification
🎨 Modern UI	Next.js 15 + React 19 + Tailwind CSS
👨‍💼 Admin Panel	Dashboard for managing verification requests

Smart Contracts

AuthBluePrint.sol - Base abstract contract providing:

// Core authentication states
enum AuthState { NONE, REQUESTED, PENDING, VERIFIED, FAILED }

// Key functions
function genQRCodeInfo() public;           // Generate verification challenge
function validateProof(...) public;        // Verify ZK proof on-chain

RandomDApp.sol - Example implementation showing custom verification logic.

Technical Stack

• Frontend: Next.js 15, React 19, TypeScript
• Styling: Tailwind CSS, shadcn/ui
• Web3: ethers.js, Wagmi, RainbowKit
• Contracts: Solidity, Foundry, OpenZeppelin

📚 Full DApp Documentation →

---

🚀 Quick Start

Prerequisites

# Required tools
- Node.js 18+ & pnpm
- Android Studio (for mobile app)
- Foundry (for smart contracts)
- Git

1. Clone the Repository

git clone --recurse-submodules https://github.com/roudra323/ZKAuth.git
cd ZKAuth

2. Setup Smart Contracts

cd ZK-Minimal-DApp/Foundry-Backend
forge install
forge build
forge test

3. Setup Frontend

cd ../frontend
pnpm install

# Create environment file
cat > .env.local << EOF
NEXT_PUBLIC_CONTRACT_ADDRESS=your_contract_address
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your_wallet_connect_id
EOF

pnpm dev

4. Setup Android App

1. Open PassportAndroidApp/ in Android Studio
2. Sync Gradle dependencies
3. Configure CSCA certificates (optional)
4. Build and run on NFC-enabled device

---

💡 Use Cases

🍺 Age Verification

Prove you're over 18/21 without revealing your birthdate to access age-restricted services.

🏛️ KYC/AML Compliance

Verify nationality or identity for financial services while preserving privacy.

🗳️ Anonymous Voting

Prove citizenship eligibility without linking votes to your identity.

🎫 Event Access

Verify credentials for exclusive events without sharing personal data.

🎮 Gaming & Gambling

Comply with age regulations while maintaining user privacy.

---

🔒 Security Model

Privacy Guarantees

Layer	Protection
📱 Device	Passport data encrypted with Android Keystore
🔐 Transmission	Only ZK proofs leave the device, never raw data
⛓️ Blockchain	Proofs verified without revealing inputs
🔄 Verification	Zero-knowledge: verifier learns only true/false

Passport Security Protocols

• ICAO 9303 - International standard compliance
• BAC - Basic Access Control for chip access
• PACE - Password Authenticated Connection Establishment
• EAC - Extended Access Control for biometrics
• Active Authentication - Proves chip authenticity
• CSCA Validation - Country certificate chain verification

---

🛠️ Development

Project Structure

Module	Path	Technology
Android App	PassportAndroidApp/	Kotlin, Android SDK
Smart Contracts	ZK-Minimal-DApp/Foundry-Backend/	Solidity, Foundry
Web Frontend	ZK-Minimal-DApp/frontend/	Next.js, React, TypeScript
ZK Circuits	ZK-Minimal-DApp/zk-passport-auth/	ZoKrates

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Guidelines

• Use functional programming paradigms
• Follow TypeScript best practices
• Write comprehensive tests
• Document new features

---

📚 References

Standards & Protocols

• ICAO 9303 - Machine Readable Travel Documents
• EIP-712 - Typed structured data hashing
• ZoKrates - ZK-SNARK toolbox

Libraries & Tools

• JMRTD - Java Machine Readable Travel Documents
• Foundry - Ethereum development toolkit
• RainbowKit - Web3 wallet integration

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

The Passport Android App component is licensed under Apache License 2.0.

---

🙏 Acknowledgments

• ZoKrates Team - ZK-SNARK framework
• JMRTD Project - Passport reading library
• OpenZeppelin - Smart contract security
• shadcn/ui - UI component library
• The Ethereum and ZK communities for advancing privacy-preserving technologies

---

Built with ❤️ for privacy-preserving identity verification