Koove app-init explicado: qué se genera, qué se guarda y qué no sale de tu máquina

Cuando una app móvil se conecta a Koove por primera vez, se dispara un proceso que aquí llamamos koove app-init: la app se atestigua como dispositivo físico real, se registra ante el backend de Koove y genera el material criptográfico que va a controlar qué secretos puede abrir. Entender qué pasa en ese paso es la mejor forma de confiar (o no) en un gestor de secretos de conocimiento cero.

Qué es exactamente koove app-init

En el SDK móvil (@koove/sdk, React Native/Expo, requiere dev build) este proceso se dispara con un único método:

import { KooveClient } from '@koove/sdk';

const client = new KooveClient({
  apiUrl: 'https://api.koove.io',
  appId: 'app_xxx',
  appToken: 'xxx',
});

await client.init(); // atestigua el dispositivo + lo registra

init() hace dos cosas en un solo paso: pide atestación de hardware real (App Attest en iPhone, Play Integrity en Pixel/Android) y registra el dispositivo en tu proyecto de Koove. No hay bypass de desarrollador en ninguna de las dos plataformas — la verificación corre contra hardware físico real, punto.

Qué se genera: el "controller keyfile" local

Durante init(), el dispositivo genera localmente un par de claves de identidad X25519 (generateIdentityKeyPair, de @koove/crypto, reexportado por el SDK). No necesitas llamarlo tú directamente — client.init() lo gestiona por ti.

A ese par de claves lo llamamos coloquialmente el controller keyfile: es el material que controla qué secretos puede abrir ese dispositivo concreto. La clave privada:

se genera dentro del propio dispositivo,
se guarda en almacenamiento seguro del sistema (Keychain/Keystore),
nunca se transmite en claro a ningún servidor.

La clave pública sí viaja al backend, atada a la atestación del dispositivo mediante computeAttestationBinding. Es la única pieza que Koove necesita para poder "envolver" secretos que ese dispositivo podrá abrir más adelante.

Qué se guarda en el servidor de Koove

Después de init(), en el lado del servidor queda:

la clave pública del dispositivo (registrada vía addRecipient),
el binding de atestación que ata esa clave pública a un dispositivo físico verificado,
los envelopes cifrados (AES-256-GCM, con derivación HKDF-SHA256) de cada secreto que ese dispositivo tenga autorizado.

El servidor de Koove nunca ve el secreto en claro. Solo almacena ciphertext y metadatos de quién puede abrirlo.

Qué no sale nunca de tu máquina

La clave privada X25519 generada en init() — el controller keyfile propiamente dicho.
El valor en claro de cualquier secreto: se descifra en memoria, en el propio dispositivo, detrás de biometría, con decryptSecret.
El mnemonic de recuperación de 24 palabras (BIP39, generado con generateRecoveryCode), salvo que tú decidas guardarlo en otro sitio.

De dónde salen los secretos que ese dispositivo puede abrir

El flujo típico empieza en el CLI, normalmente ejecutado por tu asistente de IA justo después de crear una credencial nueva:

koove set STRIPE_SECRET_KEY sk_live_51... --env prod

El código de tu proyecto solo referencia el nombre (STRIPE_SECRET_KEY), nunca el valor. Cuando un dispositivo queda aprobado como destinatario, Koove re-envuelve ese secreto para su clave pública (sealKey/openKey por debajo) y el dispositivo puede pedirlo y descifrarlo localmente.

Aprobar y revocar dispositivos

La gestión de quién tiene un controller keyfile válido para tu proyecto se hace desde el CLI:

koove devices
koove device-approve dev_8f3a
koove device-revoke dev_8f3a
koove rewrap

device-revoke quita a ese dispositivo de la lista de destinatarios futuros y rewrap regenera los envelopes sin él. Aquí hay que ser honestos: revocar un dispositivo no borra secretos que ese dispositivo ya haya descifrado y tenga en memoria o caché local antes de la revocación. Revocar impide accesos futuros, no deshace descargas ya hechas.

Qué pasa si pierdes el dispositivo

Si pierdes el móvil, el controller keyfile de ese dispositivo se pierde con él (está en su almacenamiento seguro, no en un servidor). Para recuperar acceso desde otro dispositivo autorizado existe:

koove recover-show

Que muestra el mnemonic de 24 palabras derivado con deriveRecoveryIdentity. Con ese mnemonic puedes re-derivar una identidad de recuperación y volver a tener acceso a los secretos para los que sigas autorizado — pero conviene ser claro sobre lo que esto no es: no hay forward secrecy ni ratchet en el esquema de Koove, así que no lo compares con propiedades de mensajería tipo Signal. Es envelope encryption sólido, no un protocolo de mensajería.

Los límites que conviene conocer

La atestación exige hardware real y no tiene bypass de desarrollador en iOS ni Android — cómodo para producción, más lento para pruebas rápidas en emulador.
El esquema es X25519 + AES-256-GCM con HKDF-SHA256, sin ratchet: no hay forward secrecy si una clave privada queda comprometida en el pasado.
Koove no puede "deshacer" una fuga que ya salió del dispositivo antes de que revoques acceso.

Si quieres el detalle completo de la arquitectura y del modelo de confianza, está documentado en /security.

Por qué esto importa cuando el código lo escribe una IA

En proyectos donde buena parte del código sale de un asistente de IA, las claves hardcodeadas en el repo son el fallo número uno que vemos repetirse. Con koove app-init, tu asistente puede ejecutar koove set directamente y tu código solo referencia nombres — nunca valores. Profundizamos en este problema en /ai-security.

Cómo empezar

Toda la referencia de comandos del CLI y del SDK está en /docs/sdk, y los planes disponibles (incluido el gratuito para empezar) en /plans. Si te quedan dudas puntuales sobre atestación, revocación o recuperación, revisa el /faq.

Si quieres ver koove app-init funcionando en tu propio proyecto, regístrate en Koove y ejecuta tu primer client.init() en cuestión de minutos.