=============================================
Criptografía y Gestión de Llaves IPNS Ed25519
=============================================

Identificador Técnico: [TECH-006]

Fundamento y Soberanía Criptográfica
====================================
El protocolo IPFS utiliza el Sistema de Nombres Interplanetario (IPNS) como una infraestructura de clave pública (PKI) descentralizada. A diferencia de DNSLink, que depende de la zona DNS convencional y de proveedores externos como Cloudflare, IPNS permite firmar y publicar actualizaciones del catálogo maestro de manera puramente criptográfica y soberana.

Para la red de espejos de MxOS, la identidad criptográfica autoritativa no debe depender del nodo individual (llave predeterminada ``self``), ya que la sustitución o mantenimiento de un servidor invalidaría la ruta canónica. Por ello, se establece un par de llaves asimétricas dedicado denominado ``mxos-mirrors`` basado en la curva elíptica Ed25519.

Parámetros Criptográficos de la Llave
=====================================

* **Nombre en el almacén de Kubo:** ``mxos-mirrors``
* **Algoritmo:** Ed25519 (RFC 8032)
* **Formato de codificación:** Multibase base36 (prefijo ``k51...``)
* **Identificador permanente (Key ID o PeerID):**
  ``k51qzi5uqu5di6ed3qtnwrdlvpmfil07ib6qfzb1t259nux49jenn8my4dtg0v``
* **Ruta de direccionamiento global:**
  ``/ipns/k51qzi5uqu5di6ed3qtnwrdlvpmfil07ib6qfzb1t259nux49jenn8my4dtg0v``

Ciclo de Vida y Generación
==========================
La creación de la llave se realiza en el nodo mantenedor mediante el comando nativo de Kubo:

.. code-block:: bash

   ipfs key gen --type=ed25519 mxos-mirrors

Para verificar que la llave se encuentra registrada en el almacén de Kubo (``~/.ipfs/keystore/``):

.. code-block:: bash

   ipfs key list -l

Publicación de Actualizaciones
==============================
Cada vez que finaliza un ciclo de ingesta UnixFS y se obtiene un nuevo CID raíz, el catálogo se firma y publica en IPNS:

.. code-block:: bash

   ./nodo/bin/mxos-ipns-publish.bash <CID_RAÍZ>

Dicho comando ejecuta internamente:

.. code-block:: bash

   ipfs name publish \
      --key=mxos-mirrors \
      --lifetime=720h \
      --ttl=5m \
      /ipfs/<CID_RAÍZ>

* **Vigencia (lifetime):** 720 horas (30 días), garantizando que los registros firmados permanezcan válidos en la DHT incluso durante ventanas de mantenimiento.
* **Tiempo de vida en caché (TTL):** 5 minutos, permitiendo que los resolutores refresquen rápidamente los metadatos tras sincronizaciones continuas.

Estrategia de Respaldo y Cifrado
================================
La pérdida de la llave privada impediría firmar nuevas versiones del catálogo bajo la misma identidad IPNS, forzando a reconfigurar los clientes. En consecuencia, el respaldo de la llave es una operación crítica que debe seguir los estándares de seguridad de datos en reposo.

1. Exportación Criptográfica Estándar
-------------------------------------
Kubo permite exportar la llave en formato estándar PEM PKCS#8 o en formato nativo Protobuf libp2p. Se utiliza un archivo temporal en memoria compartida (``/dev/shm``) para evitar dejar rastros magnéticos o en memorias no volátiles:

.. code-block:: bash

   # Formato estándar PEM PKCS#8
   ipfs key export mxos-mirrors --format=pem-pkcs8-cleartext -o /dev/shm/mxos-mirrors.pem
   chmod 0600 /dev/shm/mxos-mirrors.pem

   # Formato nativo libp2p
   ipfs key export mxos-mirrors -o /dev/shm/mxos-mirrors.key
   chmod 0600 /dev/shm/mxos-mirrors.key

2. Respaldo Cifrado con Age (Recomendado)
-----------------------------------------
El cifrado con ``age`` proporciona protección moderna basada en X25519 o mediante clave simétrica derivada con scrypt/passphrase:

.. code-block:: bash

   # Utilizando el script automatizado
   ./nodo/bin/mxos-key-backup.bash backup-age /ruta/segura/mxos-mirrors-$(date +%F).key.age

   # Procedimiento manual equivalente
   ipfs key export mxos-mirrors -o /dev/shm/temp.key
   age -p -o /ruta/segura/mxos-mirrors.key.age /dev/shm/temp.key
   shred -u /dev/shm/temp.key

3. Respaldo Cifrado con GPG Simétrico
-------------------------------------
Como alternativa POSIX universal, se puede generar un contenedor cifrado con AES-256:

.. code-block:: bash

   # Utilizando el script automatizado
   ./nodo/bin/mxos-key-backup.bash backup-gpg /ruta/segura/mxos-mirrors-$(date +%F).key.gpg

   # Procedimiento manual equivalente
   ipfs key export mxos-mirrors -o - | gpg --symmetric --cipher-algo AES256 -o /ruta/segura/mxos-mirrors.key.gpg

Custodia y Almacenamiento en Frío
=================================

* El archivo cifrado resultante (``.age`` o ``.gpg``) debe almacenarse en al menos dos medios independientes fuera de línea (discos cifrados LUKS, almacenamiento en frío o bóveda de contraseñas de infraestructura).
* Nunca debe almacenarse la llave en texto claro en repositorios Git ni en servidores sin cifrado a nivel de bloque.

Procedimiento de Restauración e Importación
===========================================
Para restaurar la identidad en un nodo réplica (como ``web0.mx-os.mx``) o en caso de recuperación ante desastres en una nueva máquina:

1. Descifrar el archivo de respaldo en memoria temporal:

.. code-block:: bash

   # Con age
   age -d /ruta/segura/mxos-mirrors.key.age > /dev/shm/mxos-mirrors.key

   # Con GPG
   gpg -d /ruta/segura/mxos-mirrors.key.gpg > /dev/shm/mxos-mirrors.key

2. Importar la llave en el almacén de Kubo:

.. code-block:: bash

   # Importación manual o con script
   ./nodo/bin/mxos-key-backup.bash import /dev/shm/mxos-mirrors.key

   # O directamente con Kubo
   ipfs key import mxos-mirrors /dev/shm/mxos-mirrors.key

3. Destruir de forma segura el archivo en memoria:

.. code-block:: bash

   shred -u /dev/shm/mxos-mirrors.key

4. Validar que el Key ID restaurado coincide con el canónico:

.. code-block:: bash

   ipfs key list -l | grep mxos-mirrors

Debe devolver invariablemente:
``k51qzi5uqu5di6ed3qtnwrdlvpmfil07ib6qfzb1t259nux49jenn8my4dtg0v mxos-mirrors``