# Implementation Tasks

Change ID: `add-pqc-voting-mvp`

## Phase 1: Cryptographic Foundations

### Task 1.1: Create crypto_tools.py
- [ ] Implement Paillier key generation
- [ ] Implement Paillier encryption/decryption
- [ ] Implement Paillier homomorphic operations
- [ ] Integrate Kyber (ML-KEM) key encapsulation
- [ ] Integrate Dilithium (ML-DSA) signing/verification
- [ ] Implement simple ZKP (prove 0 or 1)
- [ ] Implement SHA-256 hashing utilities
- [ ] Add comprehensive docstrings
- [ ] Write unit tests for all operations

### Task 1.2: Create blockchain.py
- [ ] Design Block class (index, prev_hash, timestamp, encrypted_votes, hash, signature)
- [ ] Implement Blockchain class
- [ ] Implement hash chain verification
- [ ] Implement signature verification
- [ ] Implement immutability guarantees
- [ ] Implement homomorphic vote summation
- [ ] Add comprehensive docstrings
- [ ] Write unit tests for blockchain operations

### Task 1.3: Update requirements.txt
- [ ] Add python-paillier
- [ ] Add liboqs-python
- [ ] Add pycryptodome
- [ ] Verify all dependencies resolve

## Phase 2: Backend API Integration

### Task 2.1: Implement voting endpoints
- [ ] POST /api/votes/setup - Initialize election with crypto keys
- [ ] GET /api/votes/public-keys - Return public keys
- [ ] POST /api/votes/register-voter - Register voter and Dilithium keys
- [ ] POST /api/votes/submit - Submit encrypted ballot
- [ ] GET /api/votes/blockchain - Retrieve blockchain state
- [ ] GET /api/votes/results - Homomorphic vote counting
- [ ] Add error handling and validation
- [ ] Add comprehensive docstrings

### Task 2.2: Update database models
- [ ] Add VoterKey model (store Dilithium public keys)
- [ ] Add BlockchainBlock model (persist blocks)
- [ ] Add VoteRecord model (track emission list)
- [ ] Add CryptoKey model (store Paillier/Kyber keys)
- [ ] Write database migrations

### Task 2.3: Create scrutator.py
- [ ] Retrieve blockchain blocks
- [ ] Verify blockchain integrity (hash chain)
- [ ] Verify all block signatures (Dilithium)
- [ ] Compute homomorphic sum: E(total) = E(v1) × E(v2) × ... × E(vn)
- [ ] Decrypt using Paillier private key
- [ ] Generate verification report
- [ ] Add comprehensive docstrings

### Task 2.4: Write integration tests
- [ ] Test vote submission workflow
- [ ] Test blockchain integrity
- [ ] Test homomorphic summation
- [ ] Test results accuracy
- [ ] Test error handling

## Phase 3: Frontend Voting Interface

### Task 3.1: Create voting-interface.tsx
- [ ] Display election details
- [ ] Fetch public keys from backend
- [ ] Implement Paillier encryption UI
- [ ] Implement ballot selection
- [ ] Generate ZKP
- [ ] Sign with Dilithium
- [ ] Submit encrypted ballot
- [ ] Show vote confirmation
- [ ] Add error handling

### Task 3.2: Create crypto-client.ts
- [ ] Implement Paillier encryption operations
- [ ] Implement Dilithium signature operations
- [ ] Implement ZKP generation
- [ ] Implement ballot serialization
- [ ] Add comprehensive JSDoc

### Task 3.3: Update active votes page
- [ ] Integrate voting interface
- [ ] Display election details
- [ ] Show candidate options
- [ ] Add vote confirmation flow

## Phase 4: Blockchain Visualization

### Task 4.1: Create blockchain page
- [ ] Fetch blockchain from API
- [ ] Display blocks in linked chain view
- [ ] Show: index, prev_hash, current_hash, encrypted_vote, signature
- [ ] Display vote count progress
- [ ] Add integrity verification button

### Task 4.2: Create blockchain-viewer.tsx
- [ ] Implement block display component
- [ ] Show block details (formatted)
- [ ] Implement chain visualization
- [ ] Add hash verification indicator
- [ ] Add signature verification indicator

### Task 4.3: Create blockchain-verify.ts
- [ ] Implement hash chain verification
- [ ] Implement signature verification UI
- [ ] Display verification results
- [ ] Add error handling

## Phase 5: Results & Reporting

### Task 5.1: Create results page
- [ ] Display final vote count
- [ ] Show homomorphic verification details
- [ ] Display blockchain integrity report
- [ ] Show audit trail
- [ ] Add verification proof display

### Task 5.2: Update scrutator with reporting
- [ ] Generate detailed results object
- [ ] Create verification proofs
- [ ] Provide transparency report
- [ ] Add result export functionality

## Phase 6: Testing & Technical Report

### Task 6.1: Write technical report
- [ ] Section 1: Introduction & Design Choices
  - [ ] Motivation and e-voting challenges
  - [ ] System architecture overview
  - [ ] Technology justification
  - [ ] Detailed voting process

- [ ] Section 2: Cryptographic Analysis
  - [ ] Paillier homomorphic encryption
  - [ ] Kyber key encapsulation
  - [ ] Dilithium signatures
  - [ ] ZKP implementation
  - [ ] Blockchain hashing
  - [ ] How crypto ensures security properties

- [ ] Section 3: Security Properties & Threat Analysis
  - [ ] Security properties provided
  - [ ] Threat analysis and mitigation
  - [ ] Resistance evaluation

### Task 6.2: Write comprehensive tests
- [ ] Unit tests for all crypto operations (90%+ coverage)
- [ ] Integration tests for voting workflow
- [ ] Blockchain integrity tests
- [ ] End-to-end tests for full voting cycle

### Task 6.3: Verify Docker deployment
- [ ] Test docker-compose up
- [ ] Verify all services start
- [ ] Test all endpoints
- [ ] Verify blockchain functionality
- [ ] Test full voting scenario

## Validation Checklist

- [ ] All crypto operations produce correct results
- [ ] Blockchain is immutable and verifiable
- [ ] API endpoints follow REST conventions
- [ ] Frontend securely handles encryption
- [ ] Voting process is complete and usable
- [ ] Results are verifiable and accurate
- [ ] Technical report is comprehensive and clear
- [ ] Code is well-documented
- [ ] Tests cover all critical paths
- [ ] Docker deployment is stable

## Estimated Timeline

- Phase 1: 2-3 days (cryptographic foundations)
- Phase 2: 2-3 days (backend integration)
- Phase 3: 2 days (frontend voting interface)
- Phase 4: 1-2 days (blockchain visualization)
- Phase 5: 1 day (results display)
- Phase 6: 2-3 days (testing & report)

**Total**: ~11-14 days of development