R.Eugenio
556fff3592
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
148 lines
6.5 KiB
Markdown
148 lines
6.5 KiB
Markdown
# zcatp2p - Protocolo P2P para comunicación directa entre empresas
|
|
|
|
> **Tipo:** Librería Zig (sin deploy propio)
|
|
> **Credenciales:** `teamdocs/INFRASTRUCTURE/CREDENCIALES.md`
|
|
> **Cheatsheet:** `teamdocs/CHEATSHEET.md`
|
|
> **VCS:** git (commits frecuentes)
|
|
|
|
## 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
|
|
|
|
1. **Seguridad**: E2E cifrado con TLS 1.3 + ChaCha20-Poly1305
|
|
2. **Descentralizado**: Sin servidor central obligatorio
|
|
3. **Sin dependencias externas**: Implementación completa en Zig puro
|
|
4. **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
|
|
|
|
- [x] Especificación del protocolo (PROTOCOL.md)
|
|
- [x] API design (API.md)
|
|
- [x] Implementación crypto (SHA256, ChaCha20-Poly1305)
|
|
- [x] Implementación TLS 1.3 (X25519, HKDF, handshake completo)
|
|
- [x] Implementación discovery local (UDP broadcast)
|
|
- [x] Implementación STUN client
|
|
- [x] Implementación relay client (con TLS handshake)
|
|
- [x] Tests unitarios (44 tests)
|
|
- [x] Discovery global (HTTPS API)
|
|
- [x] UPnP/NAT-PMP port mapping
|
|
- [x] Integración completa de red
|
|
- [x] **Identity persistence** (Device ID persistente entre reinicios)
|
|
- [x] **Conexión via relay** (para NAT symmetric)
|
|
|
|
## Comandos
|
|
|
|
```bash
|
|
# Ejecutar tests
|
|
zig build test
|
|
|
|
# Compilar ejemplo
|
|
zig build run
|
|
```
|
|
|
|
---
|
|
|
|
## CLAUDE CODE + ZLS (LSP)
|
|
|
|
Claude Code tiene integración LSP con zls (Zig Language Server).
|
|
|
|
**Plugin:** `$HOME/.claude/plugins/zls-lsp/`
|
|
|
|
**Operaciones disponibles:**
|
|
|
|
| Operación | Uso |
|
|
|-----------|-----|
|
|
| `goToDefinition` | Navegar a definición de símbolo |
|
|
| `findReferences` | Encontrar todas las referencias |
|
|
| `hover` | Info de tipo y documentación |
|
|
| `documentSymbol` | Símbolos del archivo actual |
|
|
| `incomingCalls` | Qué funciones llaman a ésta |
|
|
|
|
**Documentación:** `teamdocs/INFRASTRUCTURE/ZLS_LSP_CLAUDE_CODE.md`
|