proof.it - Veridicus

Veridicus: A Zero-Knowledge Proof System for Digital Identity

proof.it is a robust platform for generating and verifying privacy-preserving digital proofs. It leverages Zero-Knowledge (ZK) cryptography to enable users to prove statements about their identity without revealing sensitive underlying data.

📋 Table of Contents

• proof.it - Veridicus
  • 📋 Table of Contents
  • 🔍 About
  • 🛠️ Technology Stack
  • ✨ Features
  • 🏗️ Project Structure
  • 🚀 Getting Started
    • Prerequisites
    • Installation & Startup
  • 💻 Development
    • Available Commands
  • 📡 API Endpoints
    • Document Verification
    • Health & Monitoring
    • Development
  • 🛡️ Security
  • 🤝 Contributing
  • 📄 License

🔍 About

proof.it (codename Veridicus) is an advanced verification system designed for digital identity. It uses ZK-SNARKs (specifically PLONK with Circom) to create a trustless environment where identity attributes like age, authenticity, or sybil resistance can be verified without compromising user privacy.

The system is composed of a Python backend providing a secure API, a vanilla JS frontend for user interaction and proof generation, and a suite of Circom circuits that define the logic for the ZK proofs. The entire environment is containerized with Docker for consistent and straightforward deployment.

🛠️ Technology Stack

• Backend: Python, FastAPI, Neo4j (Graph DB), Redis, PyJWT
• Frontend: Vanilla JavaScript, HTML5, CSS3, @noble/crypto libraries
• ZK Proofs: Circom, PLONK, snarkjs
• DevOps: Docker, Docker Compose, Make, GitHub Actions

✨ Features

• Privacy-Preserving Proofs: Utilizes ZK-PLONK circuits for verifications like age, authenticity, and sybil resistance.
• Secure Backend API: A robust Python/FastAPI backend manages verification requests and serves data.
• Graph-Based Identity: Leverages a Neo4j database to model complex identity relationships and social recovery paths.
• Containerized Environment: Docker-compose setup for one-command startup of all services (backend, database, etc.).
• Automated Workflows: Cross-platform Makefile for streamlined installation, testing, and development.
• Security-Focused Design: Pinned dependencies, security scanners (safety, bandit), and a hardened build process.
• Identity Management: Includes concepts for social recovery and cross-chain identity bridges.

🏗️ Project Structure

proof.it/
├── backend-python/       # Python FastAPI backend, ZK runners, and identity logic
│   ├── api/              # API endpoints
│   ├── auth/             # JWT and security handling
│   ├── identity/         # Social recovery and identity logic
│   └── zkp/              # ZK circuit artifacts and JS runners
│       ├── circuits/     # Circom source files
│       └── artifacts/    # Compiled circuits and verification keys
├── frontend/             # Vanilla JS frontend application
├── docker/               # Docker Compose configuration
├── docs/                 # Project documentation
├── Makefile              # Automation for build, test, and run commands
└── refresh-circuits.ps1  # Script for rebuilding ZK circuits

🚀 Getting Started

This project is designed for a simple, one-command startup using make.

Prerequisites

• Docker and Docker Compose
• Make (On Windows, install via choco install make or use Git Bash/WSL)
• Node.js (v18+)
• Python (v3.9+)
• OpenSSL

You can validate your environment by running:

make check

Installation & Startup

The make install command handles everything: installing dependencies, building ZK circuits, and pulling Docker images.

# 1. Clone the repository
git clone https://github.com/bonapart3/proof.it.git
cd proof.it

# 2. Install all dependencies and build artifacts
make install

# 3. Start all services in detached mode
make start

Once started, the frontend should be accessible at http://localhost:3000 and the backend API at http://localhost:8000.

💻 Development

Available Commands

The Makefile provides a comprehensive set of commands for development.

# See all available commands
make help

# Start all services (with hot-reloading for the backend)
make start

# Stop all services
make stop

# View logs for all running containers
make logs

# Run the primary security test suite
make test

# Rebuild ZK circuits quickly
make circuits

# Clean the environment (removes containers, volumes, and artifacts)
make clean

📡 API Endpoints

Document Verification

• POST /vault/upload - Upload and verify documents
• GET /share/{token} - View proof details
• GET /share/{token}/bundle - Get proof bundle with ZK data

Health & Monitoring

• GET /health - Service health check
• GET /capabilities - API capabilities and ZK proof types

Development

• GET /docs - Interactive API documentation
• GET /openapi.json - OpenAPI specification

🛡️ Security

The project includes several measures to ensure code quality and security:

• Dependency Pinning: All Python and Node.js dependencies are pinned to specific, audited versions in requirements-secure.txt and package-secure.json.
• Vulnerability Scanning: The make test command runs safety and bandit to scan for vulnerabilities and bad practices.
• Secure Dependencies: Uses @noble/crypto libraries, which are audited and have zero dependencies.
• Automated Security Checks: A dedicated GitHub Actions workflow runs security scans on every push.

🤝 Contributing

Contributions are welcome! Please fork the repository, create a feature branch, and open a pull request. Ensure your changes pass the linting and testing checks.

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m 'Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Open a pull request.

📄 License

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