ZeroID — Retención Cero
Demuestra que eres una persona real y mayor de edad en cualquier sitio web sin entregar tu pasaporte, tu foto ni tu nombre.
ZeroID verifica atributos, no personas. Lee tu pasaporte y tu rostro una sola vez, en memoria, y descarta las imágenes al instante. Te entrega una credencial firmada que vive en tu dispositivo. Cuando un sitio pregunta "¿es mayor de edad?", recibe un sí o un no, nunca tus datos.
Cómo funciona
- Registro: fotografías la página de datos de tu pasaporte y te tomas una selfie con prueba de vida. El servidor lee la MRZ, compara tu rostro con la foto del pasaporte y descarta ambas imágenes.
- Sin duplicados y sin identidad: solo se guarda un hash irreversible del documento (HMAC con un secreto del servidor) y un embedding facial, para impedir que la misma persona se registre dos veces.
- Credencial en tu dispositivo: recibes un JWT firmado y ligado a una llave criptográfica que nunca sale de tu navegador o teléfono. Tus datos personales opcionales viajan cifrados en una bóveda que el servidor no puede leer.
- Inicio de sesión con ZeroID: los sitios integran el SDK y muestran el botón "Continuar con ZeroID". Tú apruebas en el teléfono con tu huella, y el sitio recibe solo lo que pidió.
Estructura
| Carpeta | Qué es | Stack |
|---|
frontend/ | Web: landing, registro, panel del usuario y el SDK (/sdk/zeroid.js) | Next.js 16, React 19 |
backend/ | Oráculo: verificación, credenciales y API para sitios | FastAPI, DeepFace, Gemini, PostgreSQL + pgvector |
app/ | App móvil: vincula el teléfono, aprueba inicios de sesión y muestra tus conexiones | Expo SDK 58, expo-router |
docs/ | Arquitectura y guía de despliegue | |
Producción
| Parte | Dónde |
|---|
| Web | Vercel: platanus-hack-14.vercel.app |
| Demo de Expreso Caribe | Vercel, desde su propio repo (ver abajo) |
| Backend | DigitalOcean App Platform: https://octopus-app-h5zq3.ondigitalocean.app (docs de la API) |
| Base de datos | Neon (Postgres con pgvector) |
Para publicar cambios, sigue docs/despliegue.md.
Desarrollo local
Requisitos
- Node.js 20 o superior
- Python 3.11
- Docker Desktop (para la base de datos local)
- Una API key de Gemini
- Expo Go en tu teléfono (para la app)
1. Base de datos
cd backend
docker compose up -d db
Levanta Postgres 16 con pgvector en localhost:5432 (usuario, contraseña y base zeroid). Las tablas se crean solas cuando arranca el backend.
2. Backend
cd backend
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -r requirements-dev.txt
cp .env.example .env
Completa backend/.env:
| Variable | Valor en local |
|---|
DATABASE_URL | postgresql://zeroid:zeroid@localhost:5432/zeroid |
DATABASE_URL_UNPOOLED | Vacía |
JWT_PRIVATE_KEY | Una llave RSA en PEM (ver abajo) |
HASH_PEPPER | Un secreto aleatorio (ver abajo); el backend no arranca con el valor de ejemplo |
GEMINI_API_KEY | Tu key de Gemini |
CORS_ORIGINS | http://localhost:3000 |
Para generar los dos secretos:
python -c "from cryptography.hazmat.primitives.asymmetric import rsa; from cryptography.hazmat.primitives import serialization as s; k=rsa.generate_private_key(public_exponent=65537,key_size=2048); print(k.private_bytes(s.Encoding.PEM,s.PrivateFormat.PKCS8,s.NoEncryption()).decode())"
python -c "import secrets; print(secrets.token_hex(32))"
Arranca el servidor desde backend/, porque ahí es donde lee el .env:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
--host 0.0.0.0 permite que el teléfono llegue al backend por la red local. En Windows, autoriza el puerto 8000 en el firewall.
3. Web
cd frontend
npm install
cp .env.example .env.local
npm run dev
La web queda en http://localhost:3000.
4. Demo de Expreso Caribe
La demo de una empresa que integra el SDK es un proyecto independiente, en su propio repo. Clónalo junto a este, en una carpeta expreso-caribe al mismo nivel que este repo.
Registra el cliente de la demo. El script escribe sus llaves en ../expreso-caribe/.env.local; si la clonaste en otro lugar, usa --env-file:
cd backend
python -m scripts.demo_client
Luego, en el repo de la demo:
npm install
npm run dev
La demo queda en http://localhost:3001. Por defecto carga el SDK desde http://localhost:3000 y canjea los inicios de sesión contra http://localhost:8000.
5. App
cd app
npm install --legacy-peer-deps
cp .env.example .env
npx expo start -c
En app/.env, pon EXPO_PUBLIC_API_URL con la IP de tu computador en la red (por ejemplo http://192.168.1.10:8000), no localhost. Escanea el QR con Expo Go.
Pruebas
cd backend
pytest -m "not integration" -q # sin base de datos
pytest -q # todas; requieren Postgres en DATABASE_URL
Para la web y la app no hay pruebas automáticas; antes de subir cambios comprueba que compilan:
cd frontend && npx next build
cd app && npx tsc --noEmit
Scripts útiles
Desde backend/:
| Comando | Qué hace |
|---|
python -m scripts.demo_client [--origin URL] [--env-file RUTA] | Registra Expreso Caribe como cliente del SDK |
python -m scripts.reset_db --yes | Borra usuarios, cuentas, conexiones y solicitudes. Conserva las tablas y los clientes del SDK. Usa la base de DATABASE_URL: revisa que no sea la de producción. |
Más documentación
