# ZNTRPHY

Una idea original del equipo de [fnalysis.com](https://fnalysis.com).

Generador air-gapped de claves Bitcoin para autocustodia: semillas BIP39,
passphrase opcional, single-sig y multisig (2-de-3, etc.), calculadora de
la última palabra por checksum (completa una semilla propia generada a
mano, por ejemplo con dados físicos), con exportación cifrada por PIN
(Argon2id + AES-256-GCM). Pensado para correr **sin ninguna conexión a
internet**, con el código fuente incluido para que cualquier usuario
pueda auditarlo antes de confiarle fondos reales.

Ver el manual de usuario (disponible en español,
[`manual/manual_source.md`](manual/manual_source.md) / `manual/manual.pdf`,
y en inglés, [`manual/manual_source_en.md`](manual/manual_source_en.md) /
`manual/manual_en.pdf`) para las instrucciones pensadas para el usuario
final. La GUI también tiene selector de idioma (ES/EN) integrado. Este
README es para quien quiera correr desde el código fuente, auditar, o
generar su propio build.

## Estructura del proyecto

```
zentrophy/
├── src/keygen/
│   ├── core/            # lógica criptográfica pura (sin GUI): entropía, BIP39,
│   │                     BIP32, descriptors single-sig/multisig
│   ├── crypto_at_rest/   # cifrado del archivo exportado (Argon2id + AES-256-GCM)
│   ├── gui/              # interfaz tkinter en español (el producto final)
│   ├── util/             # higiene de portapapeles/memoria
│   └── cli.py            # harness de línea de comandos para desarrollo/QA
├── tests/                # suite de tests (vectores oficiales BIP32/39,
│                           cross-checks independientes, roundtrip de cifrado,
│                           escaneo estático "sin red")
├── packaging/            # spec de PyInstaller, scripts de build por SO
├── manual/                # manual de usuario (fuente + PDF)
├── branding/              # logo e íconos (.icns/.ico)
├── mobile-companion/      # ZNTRPHY Verify, PWA de solo verificación (ver su README)
├── SECURITY.md
└── pyproject.toml
```

## App móvil: ZNTRPHY Verify

`mobile-companion/` es una PWA (web app instalable) de **solo
verificación**: nunca genera semillas ni maneja claves privadas, dado
que un teléfono no puede ofrecer garantías de air-gapped comparables a
una laptop dedicada. Sirve para derivar/verificar direcciones desde un
descriptor público, como paso de verificación adicional descrito en el
manual. Ver [`mobile-companion/README.md`](mobile-companion/README.md).

## Requisitos

- **Python 3.12.x exactamente** (`pyproject.toml` lo fija con
  `>=3.12,<3.13`). No se ha probado con 3.13 ni 3.14; `coincurve`
  (dependencia de `bip_utils`, usada solo para los tests de
  verificación cruzada, nunca en la app final) suele tardar en dar
  soporte a versiones de Python muy recientes, y ha fallado en el
  pasado al compilar en 3.14.
- **tkinter debe estar instalado**, no es un paquete de `pip`, va ligado
  al propio intérprete de Python:
  - macOS: `brew install python@3.12 python-tk@3.12`.
  - Linux (Debian/Ubuntu): `sudo apt install python3.12-tk` (o el
    equivalente en tu distribución, ej. `python3-tkinter` en Fedora).
    Si al ejecutar `python -m keygen` ves
    `ModuleNotFoundError: No module named '_tkinter'`, es justo esto:
    falta el paquete del sistema, no basta con `pip install`.
  - Windows: el instalador oficial de python.org ya incluye tkinter,
    no hace falta nada aparte.

### Solución de problemas frecuentes

- **`ModuleNotFoundError: No module named '_tkinter'`** (Linux sobre
  todo): falta el paquete de tkinter del sistema operativo, ver arriba.
- **Falla al compilar `coincurve`/`bip_utils`** durante
  `pip install --require-hashes -r packaging/requirements.txt`: casi
  siempre es la versión de Python. Confirma con `python --version` que
  sea exactamente 3.12.x antes de seguir.
- **`pip install --require-hashes` falla con hashes que no coinciden**:
  asegúrate de estar en un venv limpio (`python3.12 -m venv .venv`
  desde cero) y de no tener `pip.conf`/mirrors propios que sirvan
  paquetes distintos a PyPI.
- **En Linux, la app no arranca y no da ningún error visible**: prueba
  a lanzarla desde una terminal (`python -m keygen`) en vez de hacer
  doble clic, así se ve el traceback real en vez de que la ventana se
  cierre sola.

## Setup para desarrollo

```bash
python3.12 -m venv .venv
source .venv/bin/activate  # o .venv\Scripts\activate en Windows
pip install --upgrade pip
pip install --require-hashes -r packaging/requirements.txt
pip install pyinstaller pytest bip_utils
pip install -e .
```

## Correr la app (GUI)

```bash
python -m keygen
```

## Harness de desarrollo/QA (CLI)

Herramienta interna para ejercitar el pipeline completo sin la GUI. Ver el
docstring de [`src/keygen/cli.py`](src/keygen/cli.py) para la lista completa
de subcomandos y advertencias de seguridad sobre pasar mnemonics como
argumento de línea de comandos.

```bash
python -m keygen.cli mnemonic-new --words 24
python -m keygen.cli last-word --words "abandon abandon abandon ... abandon"
python -m keygen.cli --help
```

## Tests

```bash
python -m pytest tests/ -v
```

Incluye: vectores oficiales BIP32 (bip-0032.mediawiki) y BIP39
(Trezor/python-mnemonic), cross-checks independientes contra `bip_utils` y
contra el test suite del propio Bitcoin Core (`descriptor_tests.cpp`) para
`sortedmulti`/`wsh`, roundtrip de cifrado (PIN correcto/incorrecto,
manipulación detectada), y un escaneo estático (AST) que falla si aparece
cualquier import de red en `src/keygen/`.

## Build (generar el ejecutable)

```bash
bash packaging/build_macos.sh      # macOS (probado)
bash packaging/build_linux.sh      # Linux (no probado en una máquina Linux real)
.\packaging\build_windows.ps1      # Windows (no probado en una máquina Windows real)
```

Cada script: instala dependencias con hash verificado
(`packaging/requirements.txt`), corre la suite de tests completa (incluido
el escaneo "sin red") como gate antes de compilar, construye con
PyInstaller (`packaging/keygen.spec`), y genera `packaging/SHA256SUMS.txt`
con el hash del artefacto final distribuible.

**PyInstaller no cross-compila**: cada build debe correr nativamente en su
propio SO. `packaging/requirements.txt` está hash-pinneado para macOS
arm64; para Windows/Linux hay que regenerarlo repitiendo la receta descrita
en el encabezado de ese archivo (descargar los wheels de esa plataforma con
`pip download --no-deps` y calcular su hash).

## Auditoría / verificación de "cero red"

Ver [`SECURITY.md`](SECURITY.md) para el modelo de amenaza completo y cómo
verificar independientemente que la app nunca se conecta a internet.

## Licencia

ZNTRPHY es software libre, publicado bajo la [licencia MIT](LICENSE.txt).
Puedes usarlo, modificarlo y redistribuirlo libremente, incluso con fines
comerciales, siempre que conserves el aviso de copyright y la propia
licencia.

## Créditos

ZNTRPHY es un producto de [fnalysis.com](https://fnalysis.com).

© 2026 fnalysis.com.
