Secrets en el Playbook

Ningún valor de secret vive en el Playbook. El frontmatter declara solo los nombres, en required_secrets, y esa lista es una lista de permitidos: solo lo que está en ella llega a esa ejecución.

El camino de un secret en producción

1. El valor queda en la bóveda de Kadu, registrado por entorno en Configuración → Secrets.
2. Al comienzo de la ejecución, Kadu entrega solo los secrets listados en required_secrets de la tarea, como variables de entorno, y los registra para el enmascaramiento.
3. El cuerpo de la skill lee $KOBANA_ACCESS_TOKEN, $FINTERA_TOKEN directo del entorno.
4. Antes de enviar cualquier evento, log, pendiente o resultado a la consola, la instrumentación cambia el valor de cada secret por una máscara.

El enmascaramiento vale para toda variable de required_secrets, sea cual sea su nombre, y detecta el valor tal cual, escapado en JSON (incluso JSON dentro de JSON) y, en un valor de varias líneas, línea por línea. Ignora los valores de menos de 6 caracteres y no reconoce un valor transformado (base64, URL).

El enmascaramiento es la última línea de defensa; la primera es no producir la filtración. Nunca imprimas, registres ni incluyas el valor de un secret en el resultado, en eventos o en pendientes.

Provisionar un secret nuevo: el orden importa

1. Agrega el nombre en required_secrets de la tarea y haz el merge.
2. Verifica que la sincronización corrió y listó la tarea en "Tareas actualizadas". Antes de eso, la lista antigua sigue vigente.
3. Registra el valor en el entorno, antes del próximo horario si la tarea tiene schedules.

En el orden inverso, la ejecución llama al sistema externo con la variable vacía y falla a mitad de camino, y no al principio.

La configuración también es secret

La lista de permitidos es el único canal de variables de entorno de Kadu. Entra en ella también lo que no es secreto pero necesita poder cambiar por organización: el id de un proyecto en Linear, el id de una entidad en el ERP (REPORT_LINEAR_PROJECT_ID, FINTERA_ENTITY_ID).

Esto atrapa a quien escribe ${VAR:-padrão} en el cuerpo: una variable leída con valor predeterminado y fuera de la lista de permitidos nunca puede ser sobrescrita por Kadu. La skill funciona, el valor predeterminado vale siempre, y nadie se da cuenta hasta que necesita cambiar el valor sin un deploy. Para verificarlo, cruza las variables que lee el cuerpo con required_secrets. Lo que sobre tiene que ser exportado por el propio cuerpo (directorio de trabajo, por ejemplo), nunca configuración.

Agregar una variable opcional a la lista es seguro: sin valor en la bóveda, simplemente no llega. La excepción es el endpoint de lanzamiento, que rechaza la llamada con 422 missing_secrets cuando un secret de la lista no tiene valor en el entorno.

Inventario en el kadu.yaml

Cada entorno del kadu.yaml puede listar las claves que debe tener. Esto no entrega nada a ninguna tarea: sirve para que la sincronización avise cuando una clave esperada no tiene valor en ese entorno.

	required_secrets (en la tarea)	secrets (en el entorno del kadu.yaml)
Qué es	lista de permitidos de la ejecución	inventario esperado del entorno
Efecto	la variable llega a la ejecución	aviso en la sincronización si falta el valor

En desarrollo local

No hay bóveda: los valores de prueba vienen de un .env fuera de git (por ejemplo sandbox/.env, a partir de un sandbox/.env.example versionado solo con los nombres). Fuera de Kadu la instrumentación corre en modo de simulación, así que ningún secret se envía a ninguna parte. Ver Desarrollo local.