zcatp2p - Protocolo P2P para comunicación directa entre empresas

VCS: jj (no git). Ver /mnt/cello2/arno/re/recode/teamdocs/NORMAS_ESENCIALES.md

Descripción

Librería Zig para comunicación P2P segura entre instancias de Simifactu. Permite intercambio directo de documentos (facturas, certificados) entre empresas sin necesidad de email ni servicios cloud.

Disclaimer de Seguridad (TLS)

⚠️ Implementación TLS específica: Esta librería incluye una implementación de TLS 1.3 escrita en Zig puro, optimizada para el protocolo BEP (Block Exchange Protocol) de Syncthing.

Importante:

NO es un stack TLS de propósito general - está diseñado específicamente para este protocolo P2P
NO ha sido auditado profesionalmente - no debe usarse como reemplazo de OpenSSL, BearSSL u otras librerías TLS establecidas
Las primitivas criptográficas subyacentes (X25519, ChaCha20-Poly1305) sí provienen de std.crypto de Zig, que es código bien probado

Uso recomendado: Para comunicación P2P entre instancias de Simifactu en redes controladas. Para aplicaciones que requieran TLS auditado, usar librerías establecidas.

Objetivos

Seguridad: E2E cifrado con TLS 1.3 + ChaCha20-Poly1305
Descentralizado: Sin servidor central obligatorio
Sin dependencias externas: Implementación completa en Zig puro
Compatible con NAT: STUN + relay para atravesar firewalls

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                    zcatp2p Library                       │
├─────────────────────────────────────────────────────────┤
│  API Layer                                               │
│  ├── p2p.init() / p2p.deinit()                          │
│  ├── p2p.connect(device_id)                             │
│  ├── p2p.send(data)                                     │
│  └── p2p.receive() -> data                              │
├─────────────────────────────────────────────────────────┤
│  Protocol Layer                                          │
│  ├── Message framing (Header + Payload)                 │
│  ├── Compression (LZ4)                                  │
│  └── Encryption (ChaCha20-Poly1305)                     │
├─────────────────────────────────────────────────────────┤
│  Connection Layer                                        │
│  ├── TLS 1.3 handshake                                  │
│  ├── Certificate-based identity                         │
│  └── Connection multiplexing                            │
├─────────────────────────────────────────────────────────┤
│  Discovery Layer                                         │
│  ├── Local: UDP broadcast/multicast                     │
│  ├── Global: HTTPS announce/query                       │
│  └── Cache de direcciones conocidas                     │
├─────────────────────────────────────────────────────────┤
│  NAT Traversal Layer                                     │
│  ├── STUN client                                        │
│  ├── UPnP/NAT-PMP port mapping                          │
│  └── Relay fallback                                     │
└─────────────────────────────────────────────────────────┘

Estructura de archivos

zcatp2p/
├── CLAUDE.md           # Este archivo
├── PROTOCOL.md         # Especificación detallada del protocolo
├── API.md              # Documentación de la API
├── build.zig           # Build system
└── src/
    ├── main.zig        # Exports públicos
    ├── identity.zig    # Device ID, certificados
    ├── crypto.zig      # ChaCha20-Poly1305, SHA256, etc.
    ├── tls.zig         # TLS 1.3 implementation
    ├── http.zig        # HTTP/1.1 client
    ├── protocol.zig    # Message framing
    ├── discovery.zig   # Local + global discovery
    ├── stun.zig        # STUN client
    ├── relay.zig       # Relay protocol
    ├── nat.zig         # UPnP IGD / NAT-PMP port mapping
    └── connection.zig  # Connection management

Referencias

Syncthing BEP (Block Exchange Protocol): /mnt/cello2/arno/re/recode/referencias/syncthing/
RFC 5389 (STUN)
RFC 8446 (TLS 1.3)
RFC 8439 (ChaCha20-Poly1305)

Estado

Especificación del protocolo (PROTOCOL.md)
API design (API.md)
Implementación crypto (SHA256, ChaCha20-Poly1305)
Implementación TLS 1.3 (X25519, HKDF, handshake completo)
Implementación discovery local (UDP broadcast)
Implementación STUN client
Implementación relay client (con TLS handshake)
Tests unitarios (44 tests)
Discovery global (HTTPS API)
UPnP/NAT-PMP port mapping
Integración completa de red
Identity persistence (Device ID persistente entre reinicios)
Conexión via relay (para NAT symmetric)

Comandos

# Ejecutar tests
zig build test

# Compilar ejemplo
zig build run

5.8 KiB Raw Blame History