CIA/e-voting-system/openspec/project.md

Project Context

Purpose

E-Voting System - A secure electronic voting platform with blockchain-based vote recording, post-quantum cryptography, and real-time election management. Allows users to register, authenticate, and participate in elections through a web-based interface while ensuring vote integrity and transparency through distributed ledger technology.

Project Definition (Cryptographie Industrielle Avancée): Conceive and implement a functional prototype of a secure electronic voting system emphasizing correct application of cryptographic principles to address specific challenges of online voting.

Key Goals:

• Provide secure, verifiable electronic voting
• Ensure vote immutability via blockchain
• Support post-quantum cryptographic algorithms (ML-KEM, ML-DSA)
• Enable transparent election results
• Maintain voter privacy and authentication
• Address e-voting challenges: fraud prevention, voter intimidation resistance, anonymity preservation
• Implement correct cryptographic mechanisms for vote security

Deliverables (Per Project Requirements):

1. Complete Source Code & Environment:

   • Full e-voting system source code
   • Independently deployable via Docker configuration
   • Implemented cryptographic security mechanisms
   • Ready for autonomous deployment

2. Technical & Scientific Report:

   • Architecture and design approach
   • Cryptographic tools explanation and principles
   • Security properties and threat analysis
   • Application of cryptography to voting system

Tech Stack

Frontend

• Framework: Next.js 15 (App Router)
• Language: TypeScript 5.3
• Styling: Tailwind CSS 3.3.6
• UI Components: shadcn/ui (custom components)
• Forms: React Hook Form 7.66.0
• Validation: Zod 4.1.12
• Icons: Lucide React
• Environment: Node.js 18+, npm

Backend

• Framework: FastAPI (Python 3.12+)
• Authentication: JWT tokens (30-minute expiry)
• Database: MySQL 8.0+ / SQLite (dev)
• ORM: SQLAlchemy
• Validation: Pydantic
• Cryptography:
  • bcrypt for password hashing
  • Post-quantum algorithms (ML-KEM, ML-DSA)
  • Ballot hashing for vote verification
• Middleware: CORS enabled
• Documentation: Swagger UI & ReDoc

Infrastructure

• Containerization: Docker & Docker Compose
• Development Server: uvicorn (backend), Next.js dev (frontend)
• Production Build: Next.js static export + Node.js server

Cryptography Libraries

• Paillier Homomorphic Encryption: python-paillier - Vote encryption & homomorphic summation
• Kyber (ML-KEM): liboqs-python - Post-quantum key encapsulation
• Dilithium (ML-DSA): liboqs-python - Post-quantum digital signatures
• SHA-256: Built-in hashlib - Blockchain hashing
• ZKP (Zero-Knowledge Proofs): Custom implementation - Ballot validity proofs

Blockchain/Distributed Ledger

• Vote records stored with ballot hashes
• Immutable vote recording via linked blocks
• Transparent result verification
• Chain integrity verification via SHA-256 hashing
• Block signatures with Dilithium PQC

MVP (Minimum Viable Product) Features

Core Components

1. Cryptographic Toolkit (backend/crypto_tools.py)

• Paillier homomorphic encryption (key generation, encryption, decryption, homomorphic addition)
• Kyber (ML-KEM) for post-quantum key encapsulation
• Dilithium (ML-DSA) for post-quantum digital signatures
• Simple Zero-Knowledge Proofs (prove ballot is 0 or 1 without revealing value)
• SHA-256 for blockchain hashing

2. Blockchain Module (backend/blockchain.py)

• Block structure: index, previous hash, timestamp, encrypted votes, block hash, signature
• Chain validation: verify hash chain integrity and block signatures
• Ballot addition: add new encrypted votes to blockchain
• Chain immutability: ensure votes cannot be altered

3. Voting API Endpoints (backend/routes/votes.py)

• POST /api/votes/setup - Initialize election (generate Paillier keys)
• GET /api/votes/public-keys - Retrieve public keys for client encryption
• POST /api/votes/submit - Submit encrypted ballot with signature
• GET /api/votes/blockchain - Retrieve blockchain state
• GET /api/votes/count - Homomorphic vote counting

4. Voter Client (frontend/components/voting-interface.tsx)

• Display election details and candidates
• Client-side ballot encryption with Paillier
• Generate simple ZKP for ballot validity
• Sign ballot with voter's Dilithium key
• Submit encrypted, signed ballot to blockchain
• Display confirmation and vote receipt

5. Blockchain Visualizer (frontend/app/dashboard/blockchain/page.tsx)

• Display blockchain as linked blocks
• Show: block index, previous hash, current hash, encrypted vote, signature
• Chain integrity verification button
• Visual representation of vote count progress

6. Scrutator Module (backend/scripts/scrutator.py)

• Access blockchain votes
• Verify chain integrity and all signatures
• Homomorphic summation: multiply all encrypted votes to get encrypted total
• Decrypt result using Paillier private key (protected by Kyber)
• Publish results with verification proofs

MVP Voting Process

Étape 1: Election Setup

• System generates Paillier keypair
• System generates Kyber keypair for private key protection
• System generates Dilithium keypair for block signing
• Public keys published for voters

Étape 2: Voter Registration & Key Generation

• Voter authenticates via JWT
• Voter generates personal Dilithium keypair
• System stores public key for vote verification

Étape 3: Voter's Ballot Submission

1. Voter selects candidate (0 or 1)
2. Frontend encrypts ballot: E(v) = Paillier.encrypt(v, public_key)
3. Frontend generates ZKP: proof that E(v) is valid (0 or 1)
4. Frontend signs: Signature = Dilithium.sign(E(v) || ZKP, voter_private_key)
5. Frontend submits: {voter_id, E(v), ZKP, Signature} to API
6. API verifies signature and ZKP
7. API checks voter hasn't already voted (emission list)
8. API adds to blockchain: Block{index, prev_hash, timestamp, E(v), tx_id, block_signature}
9. API returns confirmation

Étape 4: Vote Counting (Scrutator)

1. Retrieve all blocks from blockchain
2. Verify blockchain integrity (hash chain + all block signatures)
3. Homomorphic operation: E(total) = E(v1) × E(v2) × ... × E(vn)
4. Decrypt: total = Paillier.decrypt(E(total), private_key)
5. Publish results

Security Properties Provided

Property	Mechanism	Implementation
Vote Secrecy	Paillier encryption	Votes encrypted before leaving client
Vote Integrity	Blockchain + Dilithium signatures	Linked blocks + PQC signatures on blocks
Voter Authentication	JWT tokens + Dilithium signatures	JWT for session, Dilithium for ballot auth
Anonymity	Transaction ID instead of voter ID	Voter ID verified once, not stored with vote
Verifiability	ZKP + blockchain verification	Client proves ballot validity, anyone verifies chain
Post-Quantum Ready	Kyber + Dilithium	Protected against future quantum attacks

Project Conventions

Code Style

TypeScript/JavaScript:

• Use TypeScript for all new code (no any types)
• Use arrow functions and const declarations
• Use camelCase for variables and functions
• Use PascalCase for component names and types
• Max line length: 100 characters
• Indent with 2 spaces
• Quote style: Double quotes for JSX, prefer template literals

Python:

• Follow PEP 8 naming conventions
• snake_case for functions and variables
• PascalCase for classes
• 4-space indentation
• Use type hints for all functions
• Docstrings for public functions/classes

Git Formatting:

• ESLint config: .eslintrc.json disables unescaped entities rule
• No Prettier config needed (uses Next.js defaults)

Architecture Patterns

Frontend Architecture:

app/                    # Next.js App Router
├── page.tsx           # Route components
├── layout.tsx         # Route layouts
├── @modal/            # Optional slot routes
components/
├── ui/                # Reusable UI components (shadcn/ui)
└── protected-route.tsx # Authentication wrapper
lib/
├── api.ts             # API client with TypeScript types
├── auth-context.tsx   # Global auth state (React Context)
├── validation.ts      # Zod schemas for form validation
└── utils.ts           # Utility functions

Authentication Flow:

1. User submits form (login/register)
2. Frontend validates with Zod schema
3. API request with JSON payload
4. Backend validates and returns JWT token
5. Frontend stores token in localStorage
6. Token included in Authorization header for all subsequent requests
7. useAuth() hook provides user state across components

API Client Pattern:

• Centralized in lib/api.ts
• Grouped by resource: authApi, electionsApi, votesApi
• Returns { data?, error?, status } structure
• Automatic token injection in headers
• Type-safe responses with TypeScript interfaces

Protected Routes:

• ProtectedRoute component wraps dashboard
• Checks useAuth() context before rendering
• Redirects to login if not authenticated
• Shows loading spinner during auth check

Backend Architecture:

backend/
├── main.py            # FastAPI app entry point
├── routes/            # Endpoint handlers
│   ├── auth.py       # Authentication endpoints
│   ├── elections.py   # Election management
│   └── votes.py       # Vote recording
├── models.py          # SQLAlchemy ORM models
├── schemas.py         # Pydantic request/response schemas
├── services.py        # Business logic
├── auth.py            # JWT and password utilities
├── database.py        # Database connection
└── crypto/            # Cryptographic utilities

Testing Strategy

Manual Testing (Current):

• Test registration with form validation
• Test login/logout flow
• Test protected routes redirect
• Test election data loading
• Test form validation errors
• Test API error handling

Future Testing:

• Unit Tests: Jest for frontend components
• E2E Tests: Cypress for user workflows
• Backend Tests: pytest for API endpoints
• Integration Tests: Full stack with Docker

Git Workflow

Branching Strategy:

• paul/evoting - Main development branch
• UI - Current frontend branch with Next.js rebuild
• backup - Old React CRA frontend (preserved)
• Feature branches off main development branch

Commit Conventions: Format: <type>: <subject>

Types:

• feat: - New feature
• fix: - Bug fix
• refactor: - Code restructuring
• docs: - Documentation updates
• chore: - Dependencies, config changes
• test: - Test additions/updates

Example:

feat: Integrate backend API with frontend - Authentication & Elections
fix: Update Docker config for Next.js frontend
docs: Add comprehensive project status document

Commit Messages:

• Use imperative mood ("add" not "added")
• Keep subject under 50 characters
• Include context in body if needed
• Sign with: 🤖 Generated with Claude Code
• Co-author: Co-Authored-By: Claude <noreply@anthropic.com>

Domain Context

E-Voting Concepts

• Election: A voting event with candidates and a deadline
• Candidate: Options users can vote for
• Voter/User: Authenticated user who can vote in elections
• Vote: Immutable record of voter choice (with ballot hash for verification)
• Ballot Hash: Cryptographic hash of vote details for verification without exposing vote

Election States

• Pending/Upcoming: Not yet started, no voting allowed
• Active: Currently accepting votes
• Completed: Voting finished, results available

Security Model

• User authentication via JWT tokens (30-minute expiry)
• Password hashing with bcrypt
• Post-quantum cryptography for future-proofing
• Vote recording with ballot hashes for transparency
• Vote immutability via blockchain/ledger
• No voter identification in vote records (privacy)

French Language Convention

• All UI text in French
• Error messages: Erreur, validation messages, etc.
• Date format: DD/MM/YYYY

Important Constraints

Technical Requirements

• Password Requirements:
  • Minimum 8 characters
  • At least 1 uppercase letter
  • At least 1 digit
  • At least 1 special character (!@#$%^&*)
• Token Expiry: 30 minutes
• Build Output: Static pre-rendered pages + Node.js server
• Database: MySQL for production, SQLite for development
• API URL: Environment variable NEXT_PUBLIC_API_URL
• Docker Deployment: System must be deployable autonomously via Docker
• Cryptographic Implementation: All chosen cryptographic mechanisms must be implemented

Security Properties & Design Challenges

E-Voting Challenges to Address:

• Fraud Prevention: Prevent vote tampering and false result reporting
• Voter Intimidation Resistance: Ensure no voter can prove how they voted
• Anonymity Preservation: Disconnect voter identity from vote content
• Vote Integrity: Guarantee votes cannot be altered after submission
• Coercion Resistance: System prevents voter coercion while voting
• Universal Verifiability: Anyone can verify election results are correct
• Voter Verifiability: Voter can verify their vote was recorded correctly

Cryptographic Security:

• CORS: Currently allow all origins (restrict to frontend domain in production)
• HTTPS: Required for production
• HttpOnly Cookies: Recommended instead of localStorage for production
• Rate Limiting: Should be implemented on auth endpoints in production
• Audit Logging: Should be added for compliance
• Post-Quantum Ready: Support ML-KEM and ML-DSA algorithms

Business/Regulatory

• Election Integrity: Votes must be immutable once recorded
• Voter Privacy: Vote contents never tied to voter identity
• Transparency: Results and vote counts must be verifiable
• Blockchain: All votes stored with cryptographic verification
• Compliance: Consider GDPR and voting regulations
• Audit Trail: System must support accountability and verification

Development

• No destructive git commands without explicit user confirmation
• Always commit before major changes
• Preserve working tree cleanly
• Test Docker builds before deployment

Report Structure Requirements

Technical & Scientific Report Must Include:

1. Introduction & Design Choices

   • Motivation and context (e-voting challenges)
   • System architecture (client/server, blockchain-based, mixing servers)
   • Justification of technology choices (languages, frameworks, database)
   • Detailed voting process (registration to results publication)

2. Analysis & Cryptographic Application

   • Fundamental cryptographic tools explanation
   • Principles behind chosen algorithms
   • Application of cryptography to voting security
   • How tools guarantee chosen security properties

3. Security Properties & Threat Analysis

   • Voting security properties the system satisfies
   • Potential vulnerabilities evaluation
   • How design choices (especially cryptographic) address threats
   • Resistance to identified threats

External Dependencies

APIs/Services

• Backend Database: MySQL server (localhost:3306 in dev)
• CORS-enabled: Frontend communicates with backend via REST API

Libraries/Packages

• shadcn/ui: Component library (via npm)
• Radix UI: Primitive components for shadcn/ui
• FastAPI: Built-in Swagger/ReDoc documentation
• SQLAlchemy: ORM for database abstraction

Infrastructure

• Docker Hub: Alpine Linux images for containers
• npm Registry: Frontend dependencies
• PyPI: Python backend dependencies
• MariaDB/MySQL: Database provider

Key Endpoints

• Backend Health: GET /health
• Backend Docs: GET /docs (Swagger)
• Backend ReDoc: GET /redoc
• Frontend: http://localhost:3000
• Backend: http://localhost:8000

Implementation Plan

Phase 1: Cryptographic Foundations

Goal: Build secure crypto toolkit for PQC-based voting

Tasks:

1. Create backend/crypto_tools.py with:

   • Paillier homomorphic encryption (key generation, encrypt, decrypt, homomorphic ops)
   • Kyber (ML-KEM) integration via liboqs-python
   • Dilithium (ML-DSA) integration via liboqs-python
   • Simple ZKP implementation (prove 0 or 1 without revealing)
   • SHA-256 blockchain hashing utilities

2. Create backend/blockchain.py with:

   • Block class (index, prev_hash, timestamp, encrypted_votes, block_hash, signature)
   • Blockchain class (chain management, validation, immutability)
   • Hash verification and signature verification methods
   • Homomorphic vote summation

3. Update requirements.txt:

   • python-paillier
   • liboqs-python
   • pycryptodome for additional crypto utilities

Deliverables:

• ✅ Functional crypto toolkit
• ✅ Blockchain data structure
• ✅ Unit tests for crypto operations

---

Phase 2: Backend API Integration

Goal: Implement secure voting endpoints

Tasks:

1. Update backend/routes/votes.py:

   • POST /api/votes/setup - Initialize election, generate Paillier/Kyber/Dilithium keys
   • GET /api/votes/public-keys - Return public keys for client encryption
   • POST /api/votes/register-voter - Register voter, generate their Dilithium keys
   • POST /api/votes/submit - Receive encrypted ballot, verify signature, add to blockchain
   • GET /api/votes/blockchain - Return blockchain state for verification
   • GET /api/votes/results - Run scrutator, return homomorphic count

2. Update backend/models.py:

   • Add Dilithium key storage for voters
   • Add blockchain block storage
   • Add vote submission tracking (emission list)

3. Create backend/scripts/scrutator.py:

   • Verify blockchain integrity
   • Compute homomorphic sum
   • Decrypt final results
   • Generate verification report

Deliverables:

• ✅ Secure API endpoints
• ✅ Blockchain persistence
• ✅ Vote scrutiny module

---

Phase 3: Frontend Voting Interface

Goal: Build client-side secure voting experience

Tasks:

1. Create frontend/components/voting-interface.tsx:

   • Display election details
   • Fetch public keys from backend
   • Client-side Paillier encryption
   • Generate ballot validity ZKP
   • Sign with voter's Dilithium key
   • Submit encrypted ballot
   • Show vote confirmation

2. Create frontend/lib/crypto-client.ts:

   • Paillier encryption operations
   • Dilithium signature operations
   • ZKP generation
   • Ballot serialization

3. Update frontend/app/dashboard/votes/active/page.tsx:

   • Integrate voting interface
   • Show election details
   • Display vote submission form

Deliverables:

• ✅ Secure voting UI
• ✅ Client-side crypto operations
• ✅ Vote submission workflow

---

Phase 4: Blockchain Visualization & Verification

Goal: Display blockchain and enable verification

Tasks:

1. Create frontend/app/dashboard/blockchain/page.tsx:

   • Fetch blockchain from API
   • Display blocks as linked chain
   • Show: index, prev_hash, current_hash, encrypted_vote, signature
   • Display vote count progress
   • Integrity verification button

2. Create frontend/components/blockchain-viewer.tsx:

   • Block display component
   • Chain visualization
   • Hash verification UI

3. Create frontend/lib/blockchain-verify.ts:

   • Verify hash chain locally
   • Verify block signatures
   • Display verification results

Deliverables:

• ✅ Blockchain visualization
• ✅ Verification interface
• ✅ Results display

---

Phase 5: Results & Reporting

Goal: Display counting results and verification proofs

Tasks:

1. Create frontend/app/dashboard/votes/results/page.tsx:

   • Display final vote count
   • Show homomorphic verification
   • Display blockchain integrity report
   • Show audit trail

2. Update backend scrutator:

   • Generate detailed results
   • Create verification proofs
   • Provide transparency report

Deliverables:

• ✅ Results display page
• ✅ Verification proofs
• ✅ Audit report

---

Phase 6: Testing & Documentation

Goal: Ensure security and create technical report

Tasks:

1. Create technical report document:

   • Section 1: Introduction & Design Choices

     • Motivation and e-voting challenges
     • System architecture (client/server + blockchain)
     • Technology justification
     • Voting process walkthrough

   • Section 2: Analysis & Cryptographic Application

     • Explain Paillier homomorphic encryption
     • Explain Kyber (ML-KEM) key encapsulation
     • Explain Dilithium (ML-DSA) signatures
     • Explain simple ZKP implementation
     • Explain blockchain hashing
     • How crypto tools guarantee properties

   • Section 3: Security Properties & Threat Analysis

     • Security properties provided
     • Threat analysis and mitigation
     • Resistance evaluation

2. Add tests:

   • Unit tests for crypto operations
   • Integration tests for voting workflow
   • Blockchain integrity tests

3. Docker testing:

   • Ensure full deployment via docker-compose
   • Test all endpoints
   • Verify blockchain functionality

Deliverables:

• ✅ Complete technical & scientific report
• ✅ Test suite
• ✅ Deployment documentation

---

Development Progress Tracking

Phase 1: Cryptographic Foundations

• Paillier toolkit implementation
• Kyber integration
• Dilithium integration
• ZKP implementation
• Blockchain module
• Crypto tests

Phase 2: Backend API Integration

• Voting endpoints
• Database models
• Blockchain persistence
• Scrutator module
• API tests

Phase 3: Frontend Voting Interface

• Voting component
• Crypto client library
• Vote submission flow
• Confirmation display

Phase 4: Blockchain Visualization

• Blockchain viewer page
• Block display component
• Verification UI
• Hash verification

Phase 5: Results & Reporting

• Results page
• Verification proofs
• Audit report
• Results display

Phase 6: Testing & Documentation

• Technical report (Section 1)
• Technical report (Section 2)
• Technical report (Section 3)
• Unit tests
• Integration tests
• Docker verification