PrivacyMesh

Federated learning where the aggregator can compute on your gradients but can never see them — enforced by encryption, not policy.

Clients train locally on their own data and send only homomorphically-encrypted gradients. The aggregator performs the averaging math directly on ciphertext — it never has access to the secret key needed to decrypt anything, by design rather than by policy.

(screenshot placeholder)

What this actually does

In standard federated learning, clients still send somewhat-sensitive gradient information to a central server in plaintext. PrivacyMesh closes that gap using CKKS homomorphic encryption (via TenSEAL): clients encrypt their gradients before sending them, the aggregator performs the sum/average math directly on ciphertexts, and only the clients — who hold the only copy of the secret key — can decrypt the final result.

The aggregator is not simply trusted not to peek. It is structurally incapable of decrypting anything, because it only ever holds a public-key context with the secret key stripped out. This repo includes a standalone proof of that guarantee (key_separation_poc.py) that deliberately tries to decrypt on the aggregator side and shows TenSEAL refusing.

Architecture

┌──────────────┐        encrypted gradient        ┌──────────────────┐
│   Client 1   │ ───────────────────────────────▶ │                  │
│ (local train,│                                    │    Aggregator    │
│  encrypt)    │◀─────────────────────────────────  │  (sums/averages  │
└──────────────┘     encrypted averaged update      │   ciphertexts,   │
                                                      │  never decrypts) │
┌──────────────┐        encrypted gradient          │                  │
│   Client 2   │ ───────────────────────────────▶  │                  │
└──────────────┘◀───────────────────────────────── └──────────────────┘
                     encrypted averaged update

                    ┌─────────────┐
   loss values ────▶ │  Dashboard  │  (loss only — never gradients/data)
   (plaintext,       │  (FastAPI + │
    non-sensitive)   │   live chart)│
                    └─────────────┘

• Encryption: CKKS scheme via TenSEAL — supports real-valued arithmetic on ciphertexts (needed since gradients are floats, not integers)
• Training: PyTorch, CPU-only
• Networking: gRPC between clients and aggregator
• Orchestration: Docker + docker-compose (each component is a separate container)
• Monitoring: FastAPI dashboard, receives only loss values (never gradients or raw data) for live visualization

Proven guarantees

This project isn't just "it runs" — each of these was independently tested and verified before being combined:

1. Homomorphic addition is correct — encrypted sum matches plaintext sum within floating-point tolerance (poc_homomorphic.py)
2. The aggregator cannot decrypt, even if it tries — public/secret key separation is enforced by the library itself, not by convention (key_separation_poc.py)
3. Real multi-layer PyTorch gradients survive the full encrypt → aggregate → decrypt round trip, correctly reconstructed and applied via an optimizer step (real_gradients_poc.py)
4. Multi-round training genuinely converges — loss decreases monotonically across 8 rounds for every client tested
5. Works across independently networked environments — verified running with the aggregator on native Windows (Docker Desktop) and clients inside WSL2's separate Linux environment, communicating over a real network boundary

Running it

Prerequisites

• Docker Desktop
• ~2GB free disk space (CPU-only PyTorch, much smaller than the GPU build)

Setup

1. Generate the shared encryption keys (one-time):

cd shared
docker run --rm -v "${PWD}:/app" -w /app python:3.11-slim sh -c "pip install tenseal numpy && python keygen.py"

This produces secret_context.bin and public_context.bin.

2. Distribute the keys:

cp secret_context.bin ../client/
cp public_context.bin ../aggregator/

Important: secret_context.bin must never end up in the aggregator/ folder — that would defeat the entire security model.

3. Run everything:

cd ..
docker compose up --build

4. Open the live dashboard:

http://localhost:8000

You'll see 8 rounds of federated training run automatically across two simulated clients, with a live-updating loss chart.

Project structure

privacymesh/
├── docker-compose.yml
├── proto/federated.proto        # gRPC message definitions
├── shared/keygen.py             # one-time shared key generation
├── aggregator/                  # holds ONLY the public key context
│   └── server.py                # gRPC server, barrier-synchronized multi-client aggregation
├── client/                      # holds the secret key
│   └── client.py                # local training loop, encryption, gRPC calls
├── dashboard/                   # FastAPI + Chart.js, receives loss values only
│   └── server.py
├── poc_homomorphic.py           # standalone proof: encrypted math is correct
├── key_separation_poc.py        # standalone proof: aggregator cannot decrypt
└── real_gradients_poc.py        # standalone proof: real PyTorch gradients work end-to-end

Design notes & honest limitations

• Key distribution is simulated, not solved. All clients currently share one encryption context generated by a single trusted keygen.py run. Real-world federated learning with genuinely independent, mutually-untrusting clients would need a proper distributed key generation protocol (multi-party computation) — a legitimate direction for future work.
• Barrier synchronization is simple. The aggregator waits for exactly NUM_CLIENTS submissions per round before aggregating. It doesn't yet handle stragglers, dropped clients, or asynchronous rounds — all real considerations in production FL systems.
• Cloud deployment is architected but not yet live. The system is designed to deploy identically to any environment (swap AGGREGATOR_HOST for a public IP) — validated across Windows/WSL2 as a stand-in for genuinely separate machines. Deployment to a cloud provider (Oracle Cloud / Fly.io / GCP) is a natural next step once account verification is sorted out.

Why this exists

Built as a self-directed exploration into combining homomorphic encryption with practical machine learning — extending earlier work on privacy-preserving systems (EncryptedHealthLedger, MediProof) from statistics and credential verification into the ML domain.