# 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`