Quipu

Librería de codificación con protección criptográfica y simbología propia.

🇬🇧 Quipu is a free/libre (AGPL-3.0) library that encrypts and encodes data using only vetted cryptographic primitives (XChaCha20-Poly1305, Argon2id, HKDF), with a hybrid post-quantum mode (X25519 + ML-KEM-1024) and a verifiable online hardening mode (RFC 9497 VOPRF + DLEQ). It never invents primitives — security lives in the keys, not in hiding the format.

Filosofía "rueda y oruga": donde existe buena criptografía, la reutilizamos (XChaCha20-Poly1305, Argon2id, HKDF, ML-KEM, X25519); donde hay terreno nuevo (representación, simbología, formato), innovamos. Nunca inventamos primitivas criptográficas: la seguridad vive en la clave + el AEAD, no en la representación.

Qué hace

Protege datos y los representa como símbolos (texto denso, glifos, o una imagen), de forma reversible y autenticada.

datos → KDF(passphrase+pepper) → AEAD → contenedor → codec base-N → diccionario → símbolos

Modos

Custodia de claves (k-de-n, feature escrow)

quipu::shamir reparte un secreto en n comparticiones de las que k cualesquiera lo reconstruyen y k-1 no revelan nada. Va tras un feature gate opt-in: es una herramienta de escrow, no del núcleo de cifrado, y quien no la necesite no la lleva compilada. Sirve para respaldar la clave del servidor OPRF, custodiar la clave de firma de un integrador o montar un escrow contractual — sin red y sin HSM, que es la condición de un despliegue air-gapped.

let comparticiones = quipu::shamir::split(&clave, 3, 5)?;   // 3 de 5
let clave = quipu::shamir::combine(&comparticiones[..3])?;

Cada compartición lleva un verificador, así que una corrupta o de otro reparto se detecta en vez de devolver basura. Ese verificador permitiría comprobar conjeturas de un secreto adivinable, así que el módulo rechaza secretos más cortos que el material de clave más pequeño que produce la propia arquitectura (kdf::KEY_LEN, 32 bytes): es para claves, y para lo adivinable está honey. No es firma umbral — el secreto se reconstruye en memoria para usarlo.

Firma en un dispositivo (HSM/PKCS#11, feature hsm)

La clave privada de firma puede vivir en un HSM, token o tarjeta PKCS#11 y no salir de ahí. Es la respuesta a la primera pregunta de un comité de seguridad, y funciona con la firma híbrida completa: las dos mitades —Ed25519 y ML-DSA-87— se generan y se usan dentro del dispositivo; de la librería solo salen firmas y la clave pública.

El trait firmante::Custodio separa quién guarda la clave de cómo se arma la firma. Pide operaciones, nunca material: no existe forma de sacar la clave, porque el punto entero es que no salga. Una firma hecha en un HSM y una hecha en memoria son idénticas byte a byte y las verifica el mismo verificador.

// El custodio en memoria de siempre (predeterminado, sin feature):
let firma = firmante::firmar(&firmante::EnMemoria::nuevo(sk), mensaje)?;

// O contra un dispositivo PKCS#11, con la clave dentro (feature `hsm`):
let custodio = CustodioPkcs11::por_etiqueta(sesion, "firma-ed", "firma-ml")?;
let firma = firmante::firmar(&custodio, mensaje)?;  // la clave nunca cruza aquí

Con escrow, firmar_con_comparticiones reconstruye desde Shamir, firma y borra en una sola llamada de Rust, sin que la clave cruce a los bindings. Probado de punta a punta —128 firmas concurrentes contra un token real, cada una verificada— y en el binding de Python (quipu.CustodioHsm), que va en la rueda.

Diccionarios (simbología enchufable)

• dictionaries::ascii94() — 94 símbolos ASCII (copy-paste universal).
• dictionaries::flagship() — 4096 glifos (12 bits/símbolo, ~2× más denso).
• dictionaries::from_range(start, count) — alfabeto a medida.
• glyphopt — selección de glifos por máxima separabilidad (base para glifos por IA).

Galería de glifos

La misma carga cifrada puede representarse como texto denso, como una imagen PNG, o con un alfabeto de glifos propio (geométrico o generado orgánicamente). La simbología es pública (Kerckhoffs): no aporta ni resta seguridad, solo representación.

Alfabeto de glifos	Secreto en glifos	Glifos nativos	Glifos generativos

Seguridad y endurecimiento

• Precapas: normalización NFKC, pepper, padding Padmé (oculta longitud), binding de contexto (AAD), HKDF (separación de subclaves).

• Antihacker: borrado de claves en memoria (zeroize), comparación en tiempo constante, validación de parámetros KDF, errores uniformes.

• Fallo de entropía, no sustitución silenciosa: cuando el sistema operativo no puede dar aleatoriedad, Quipu no cae a una fuente más débil — ninguna clave nace de un RNG muerto. El fallo se informa como un error accionable (¿reintento yo, o arreglo el despliegue?) con un reintento acotado para el único caso transitorio, en vez de un panic: así la limpieza de memoria (Drop/zeroize) se ejecuta incluso ahí, que es justo cuando más importa. Es el modo de fallo de Debian OpenSSL 2008 —claves predecibles que parecen correctas— prevenido por construcción, y hay una autoprueba que avisa al arrancar en vez de matar el proceso.

• Autopruebas de arranque (quipu::selftest): 14 vectores de respuesta conocida sobre el binario que realmente se ejecuta, no sobre el build de CI. Corren una vez por proceso al entrar por cualquier punto del núcleo, y si alguna falla el módulo se niega a operar en vez de producir resultados silenciosamente incorrectos.

  Una autoprueba fallida no significa que Quipu falle: significa que la máquina no está ejecutando la criptografía correctamente — una rueda compilada para otro procesador, un archivo dañado o sustituido, memoria defectuosa. No introducen modos de fallo, hacen visibles los que ya existían.

  Van más allá de lo que exigen FIPS 140-3 y los GM/T chinos en tres puntos: usan vectores publicados donde existen (HKDF contra el RFC 5869, no vectores propios que solo demuestran consistencia consigo mismos), incluyen pruebas negativas (lo manipulado debe fallar), y vigilan la salud del RNG en continuo. Cada comprobación está probada de que discrimina: una que devolviera siempre true pasaría una batería convencional igual que una correcta.

  Verificadas con 1300 operaciones simuladas —200 pasadas, 100 hebras concurrentes, 1000 llamadas repetidas— y con inyección de fallo para ejercitar el camino de error, ambas en CI.

• Hackerbot: red-team interno (tamper/truncation/uniqueness). Encontró y se corrigió un DoS por parámetros Argon2 maliciosos.

• Security Lab (features lab / lab-offline, no viajan en el build publicado): red-team adaptativo que se ataca a sí mismo. Núcleo en CI (fuga de formato + falsificación de firmas) con corpus encadenado y meta-tests que fallan si se debilita una defensa antihacker; y un banco offline aislado (contenedor sin red) para timing y coste de guessing acelerado por IA. cargo run --example securitylab --features lab · bash lab/run.sh. Ver lab/README.md y THREAT_MODEL.md §9.

Uso (Rust)

use quipu::api::{encode, decode, Options};
use quipu::dictionaries;

let dict = dictionaries::ascii94();
let sym = encode(b"secreto", "passphrase", &dict, &Options::default());
let data = decode(&sym, "passphrase", &dict, b"").unwrap();

Firma híbrida (autenticidad verificable por terceros, post-cuántica):

use quipu::api::{encode_signed, decode_verified};
use quipu::{dictionaries, pqsign};

let dict = dictionaries::ascii94();
let (vk, sk) = pqsign::generate_keypair();
let signed = encode_signed(b"acta oficial", &sk, &dict);
let msg = decode_verified(&signed, &vk, &dict).unwrap(); // falla si se altera

Uso (Python)

pip install quipu-crypto   # se instala como "quipu-crypto", se importa como "quipu"

import quipu
s = quipu.encode(b"secreto", "passphrase")
assert quipu.decode(s, "passphrase") == b"secreto"

# Post-cuántico
pub, sec = quipu.generate_keypair()
s = quipu.encode_to_recipient(b"secreto", pub)
assert quipu.decode_as_recipient(s, sec) == b"secreto"

# Firma híbrida (autenticidad, post-cuántica)
vk, sk = quipu.generate_signing_keypair()
signed = quipu.encode_signed(b"acta oficial", sk)
assert quipu.decode_verified(signed, vk) == b"acta oficial"  # falla si se altera

# Streaming AEAD para datos grandes (salida binaria, no símbolos)
blob = quipu.encrypt_stream(b"...datos grandes...", "passphrase")
assert quipu.decrypt_stream(blob, "passphrase") == b"...datos grandes..."

Uso (Node.js)

npm install quipu-crypto   # binarios precompilados: linux-x64, darwin-x64, darwin-arm64, win32-x64 (sin toolchain de Rust)

import * as quipu from 'quipu-crypto';

const blob = quipu.encryptStream(Buffer.from('...datos grandes...'), 'passphrase');
quipu.decryptStream(blob, 'passphrase'); // -> Buffer

const { publicKey, secretKey } = quipu.generateKeypair(); // post-cuántico
const c = quipu.encryptToRecipient(Buffer.from('secreto'), publicKey);
quipu.decryptAsRecipient(c, secretKey);

La API es síncrona (corre Argon2id; para servidores, invócala desde un worker_thread). Ver bindings/node/README.md.

Uso (Go)

go get github.com/isazajuancarlos/quipu/bindings/go@v0.9.0   # cgo: requiere CGO_ENABLED=1 y un compilador de C

import quipu "github.com/isazajuancarlos/quipu/bindings/go"

blob, err := quipu.EncryptStream([]byte("...datos grandes..."), "passphrase", quipu.StreamOptions{})
plain, err := quipu.DecryptStream(blob, "passphrase", nil)

API idiomática (result, error); errores centinela con errors.Is. Nota: hoy el enlazado requiere un checkout del repo (cgo enlaza target/release/libquipu_capi.a); compila el staticlib con cargo build -p quipu-capi --release primero. Ver bindings/go/README.md.

Uso (C / otros lenguajes)

Un ABI de C estable vive en bindings/c (crate quipu-capi). Compila una librería compartida/estática y un header quipu.h generado con cbindgen, de modo que cualquier lenguaje con FFI de C (Node.js, Go, Ruby, …) puede consumir Quipu. La superficie es paritaria con los bindings de Python. Ver bindings/c/README.md.

#include "quipu.h"
uint8_t *blob = NULL; size_t n = 0;
if (quipu_encrypt_stream(data, len, "passphrase", NULL, 0, 0, &blob, &n) == QUIPU_OK) {
    /* ... usar blob ... */
    quipu_bytes_free(blob, n);   /* se limpia al liberar: sin residuo de secretos */
}

Ejemplos funcionales

Round-trip de todos los modos, listo para correr:

cargo run --example quickstart          # Rust  (examples/quickstart.rs)
python examples/quickstart.py           # Python (examples/quickstart.py)

Construir y probar

cargo test                      # tests unit + property
cargo clippy --all-targets      # lint
cargo run --example demo        # demo simétrico + glifos
cargo run --example v2demo      # post-cuántico + OPRF + imagen
cargo run --example hackerbot   # red-team
cargo run --example testplatform --release   # batería completa
cargo run --example securitylab --features lab   # laboratorio de seguridad (red-team adaptativo)
cargo run --example redteam --features "lab slh honey" --release   # red-team consolidado (todas las superficies)
bash lab/run.sh   # banco offline aislado (timing + guessing) — Etapa B

# Fuzzing coverage-guided (libFuzzer, nightly). Targets: parse_container,
# honey_decrypt, unpad, codec_roundtrip.
cargo +nightly fuzz run honey_decrypt

# Bindings Python
source venv/bin/activate
maturin develop --features python
python tests/python/test_quipu.py

Estado

v1 + v1.1 + v2 + streaming AEAD (QST1) + honey (QHNY) + firmas (híbrida Ed25519+ML-DSA-87 y triple con SLH-DSA) implementados con TDD estricto. 207 tests Rust + Wycheproof + 15 Python verdes, clippy limpio, fuzzing sin crashes, Miri sin UB. Bindings multi-lenguaje sobre la C ABI, cada uno con interop cross-language: 10 tests de ABI + integración C, 12 Node, 12 Go. Parámetros post-cuánticos en categoría de seguridad NIST 5 (CNSA 2.0): ML-KEM-1024 y ML-DSA-87. Modo online con VOPRF conforme a RFC 9497 (ristretto255-SHA512), verificado contra los vectores oficiales del Apéndice A.1.2, KEM híbrido con transcript ligado estilo X-Wing, firma híbrida Ed25519 + ML-DSA-87 (combinador AND), y pre-auditoría propia (ver INFORME_PREAUDITORIA.txt y MODELO_DE_AMENAZA.txt). Security Lab (red-team adaptativo auto-hospedado): 14 ataques en CI (--features lab) + banco offline de timing/guessing (--features lab-offline).

⚠️ Proyecto en desarrollo. La pre-auditoría interna NO sustituye una auditoría criptográfica independiente: no usar para proteger datos críticos reales hasta ese sello externo.

Endurecimiento de contraseñas (servicio OPRF)

Argon2 solo:  robas la BD -> fuerza bruta offline, a la velocidad de tu GPU.
Con VOPRF:    robas la BD -> no derivas nada sin la clave del servidor. Cada
              intento exige una petición que el operador ve, limita y corta.

Hay una instancia gestionada en https://oprf.xiliux.com (beta). El cliente va aparte y es Apache-2.0: no arrastra la AGPL de este núcleo a tu servidor de autenticación.

pip install quipu-oprf-django   # Django: solo toca PASSWORD_HASHERS
pip install quipu-voprf         # las primitivas, para cualquier otro stack

La contraseña sale cegada (el servidor nunca la ve) y el servidor no puede mentir: adjunta una prueba DLEQ que el cliente verifica contra una clave pública fijada fuera de banda. Falla cerrado: si el servicio no responde o la prueba no valida, no se degrada a "sin endurecer".

• crates/quipu-voprf — primitivas VOPRF (RFC 9497), Apache-2.0
• crates/quipu-oprf-server — el servidor, auto-hospedable
• integrations/ — Django (publicado), Express y Go (sin publicar)

Documentación

• docs/SPEC.md — especificación técnica (formato del contenedor, KDF, modo híbrido, VOPRF/DLEQ, separación de dominios).
• docs/THREAT_MODEL.md — modelo de amenaza (EN) · original MODELO_DE_AMENAZA.txt (ES).
• docs/PRE_AUDIT.md — pre-auditoría interna (EN) · original INFORME_PREAUDITORIA.txt (ES).
• SECURITY.md — política de seguridad y reporte de fallos.
• docs/RELEASES.md — cómo verificar la autenticidad de un release (attestations PEP 740 + firmas sigstore/cosign).
• CONTRIBUTING.md — cómo contribuir · CHANGELOG.md.
• LICENSING.md — modelo de licenciamiento dual.
• docs/announcement.md — artículo de diseño (EN/ES).
• docs/superpowers/specs/2026-07-01-quipu-security-lab-design.md — diseño del Security Lab (red-team adaptativo, feature lab).

⚠️ La pre-auditoría interna es preparación, no sustituye una auditoría independiente. Ese sello externo es el siguiente paso del proyecto (solicitud enviada al OTF Security Lab).

Licencia

Modelo de licencia dual (open-core). No todo el repositorio es AGPL: lo que un cliente del servicio OPRF enlaza dentro de su propio servidor es permisivo.

Qué se cobra, exactamente

Quipu es libre y siempre lo será. Puedes usarlo hoy sin pagar nada. La única condición es publicar el código de lo que construyas encima. Si eso no te sirve, te vendemos la exención de esa obligación.

Dicho de otro modo: no se cobra por el uso, se cobra por el derecho a no publicar. El copyleft no prohíbe cobrar —la GPL dice literalmente que puedes cobrar cualquier precio o ninguno—; lo que restringe es el secreto, no el precio.

• Licencia comercial — para producto propietario cerrado o SaaS sin abrir código. Términos en LICENSE-COMMERCIAL. Es una concesión adicional y paralela a la AGPL, no una sustitución: con contrato o sin él conservas todo lo que la AGPL concede a cualquiera —usar, estudiar, modificar, redistribuir, vender, bifurcar e incluso competir—. Lo único que añade es la exención del copyleft de red.
• Servidor OPRF gestionado — negocio distinto y complementario: ahí no se vende exención sino no tener que operar la infraestructura ni custodiar la clave.

Si puedes cumplir el copyleft, no necesitas comprarnos nada. Un proyecto libre, uno académico o una entidad con política de software abierto usan Quipu gratis, y nos interesa que lo hagan.

Por qué AGPL y no GPL: con GPL a secas, quien corre el software como servicio en red nunca lo distribuye, así que nunca dispara el copyleft. El artículo 13 de la AGPL cierra ese hueco. No fue una elección ideológica.

Es la misma estructura que Qt o MySQL: licencia libre para quien cumple, licencia comercial para quien necesita términos propietarios.

Copyright (c) 2024-2026 Juan Carlos Isaza Arenas — titular único; ver COPYRIGHT. El uso del nombre «Quipu» se rige por TRADEMARK.md.

Las primitivas VOPRF viven en un crate separado (no solo con otra etiqueta): la licencia de un envoltorio no relicencia su dependencia. Detalles y el porqué en LICENSING.md §0. Contacto: isazajuancarlos@gmail.com