Overview

Cerebrum is a cryptographically secure examination paper management and distribution platform that eliminates paper leaks, insider threats, and metadata tampering through a layered security architecture combining modern cryptography, decentralized storage, and blockchain-backed verification.

Traditional examination systems rely on centralized infrastructure with weak access controls and no tamper evidence. Cerebrum addresses this with:

Screenshots

Architecture

Tech Stack

Frontend

Backend

Database & Storage

Cryptography

Blockchain

Security Architecture

Role-Based Access Control

Super Admin and Exam Controller cannot be created via public signup. Use npm run create-admin to provision privileged accounts directly — this prevents privilege escalation through the public registration endpoint.

Smart Contract

Contract Address (Sepolia): 0x080a57357A2fA658237a7d77e49E3998Bb091A1C

function storePaper(string cid, string hash, string signature) onlyOwner
function getPaper(uint256 index) view returns (cid, hash, signature, timestamp, uploadedBy)
function totalPapers() view returns (uint256)
function transferOwnership(address newOwner) onlyOwner

The onlyOwner modifier ensures only the configured backend wallet can write records. At decrypt time, the application reads the on-chain record and cross-checks it against the database — so the blockchain is doing real verification work, not just write-only logging.

Database Schema

User ──────────────────── Paper ─────────────────── AuditLog
│ id (uuid)              │ id (cuid)               │ id
│ email (unique)         │ fileName                │ action (enum)
│ password (bcrypt)      │ encryptedAesKey         │ timestamp
│ name                   │ vaultIv                 │ userId → User
│ role (enum)            │ iv                      │ paperId → Paper
│ createdAt              │ cid
│                        │ hash
│ ──▶ uploadedPapers[]   │ signature
│ ──▶ auditLogs[]        │ publicKey
                         │ txHash
KeyVault                 │ encryptedPath
│ id                     │ decryptedPath (null)
│ publicKey              │ uploadedAt
│ privateKey (encrypted) │ uploadedById → User
│ privateKeyIv           │ unlockAt
│ createdAt              │ isUnlocked
                         │ status (enum)

Setup & Installation

Prerequisites

• Node.js 20+
• PostgreSQL database (Neon free tier works)
• Pinata account for IPFS pinning
• Alchemy account for Sepolia RPC (optional, for testnet)

Local Development

# 1. Clone the repository
git clone https://github.com/AaryanBairagi/Cerebrum.git
cd Cerebrum

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Fill in DATABASE_URL, PINATA_JWT, JWT_SECRET, MASTER_KEY

# 4. Sync database schema
npx prisma db push

# 5. Create a Super Admin account
npm run create-admin

# 6. Start local blockchain (separate terminal)
npx hardhat node

# 7. Compile and deploy contract to local network
npx hardhat compile
npx hardhat run lib/scripts/deploy.js --network localhost
# → Copy printed address to .env as CONTRACT_ADDRESS
# → Set RPC_URL=http://127.0.0.1:8545

# 8. Start the app
npm run dev

Visit http://localhost:3000 and sign in with the Super Admin account.

Testnet Deployment (Sepolia)

# Add to .env:
# SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your-key
# PRIVATE_KEY=0xYourThrowawayWalletKey (fund with free ETH from sepoliafaucet.com)

npx hardhat ignition deploy ignition/modules/Cerebrum.js --network sepolia
# → Copy printed address to .env as CONTRACT_ADDRESS
# → Set RPC_URL to same Alchemy URL

# Run contract tests
npx hardhat test

Environment Variables

Current Status & Known Tradeoffs

This is a working, complete demonstration of the full lifecycle:

encrypt → sign → pin → anchor → time-gate → verify on-chain → decrypt → stream

Future Enhancements

• Multi-signature approval workflows
• Hardware Security Module (HSM) integration
• Cloud KMS for private key management
• Redis-backed rate limiting for multi-instance deployments
• Zero-Knowledge proof verification
• AI-based anomaly detection in audit stream
• Multi-provider IPFS replication
• Hyperledger Fabric migration for private consortium chains

License

MIT — see LICENSE.

Built as an academic/portfolio demonstration of a production-grade secure examination infrastructure. See "Current Status & Known Tradeoffs" above before considering production use.