Suscripción y licencias por módulo

Estado honesto

La consola emisora de licencias, las llaves por módulo y la sincronización del core están implementadas y en operación en el entorno de demostración, sin bancos reales: la única instalación que las usa hoy es la propia instalación piloto de FINORA, que recibió por sincronización sus primeras concesiones de módulos nuevos. En esa instalación el interruptor que bloquea los módulos nuevos sin concesión está apagado: los módulos nuevos se ven como licenciados o no, pero todavía no se cierran. Qué módulos y planes se venden a cada institución lo define el área comercial; esta página explica el mecanismo.

El problema: una licencia que no se deja vender por partes

La licencia clásica de un core es un archivo con una lista fija de casillas: «clientes sí, créditos sí, tarjetas no». Tiene tres defectos. Para agregar un módulo nuevo hay que cambiar el programa. No se puede vender un módulo suelto con su propia fecha de vencimiento. Y se emite a mano, sin un registro de qué cliente tiene qué plan ni cuándo renueva.

Una analogía: el llavero del edificio

En lugar de una sola llave maestra que abre «lo que diga la llave», cada módulo tiene su propia llave, con su fecha de vencimiento grabada y el número del apartamento al que pertenece. Una llave de otro apartamento no entra en tu cerradura, y una llave vencida deja de girar sola, aunque el cerrajero no esté localizable.

Las piezas

Pieza	Dónde vive	Qué hace
Catálogo de módulos	Core y consola emisora	Código, nombre y superficies (menús, pantallas y rutas de API) de cada módulo licenciable
Plan	Consola emisora	Un paquete de módulos con precio y límites por defecto
Suscripción	Consola emisora	Un plan, más módulos adicionales, para una instalación, con periodicidad, inicio, fin y límites
Concesión FNM1	Consola emisora → core	Una llave firmada por cada módulo de la suscripción
Revocación FNR1	Consola emisora → core	Una lista firmada de concesiones anuladas, con un número de secuencia que solo crece
Sincronización	Core	El core pide sus llaves a la consola emisora; la consola nunca llama a los bancos

El catálogo: 21 módulos

El core declara hoy 21 módulos licenciables:

• 16 heredados, que ya existían como casillas de la licencia clásica: clientes, cuentas, transacciones, créditos, depósitos a plazo, tarjetas, chequeras, giros, comercio exterior, recaudación, contabilidad, reportes regulatorios, CRM, activos fijos, cuentas por pagar y la API externa.
• 5 nuevos, que solo se conceden con llave por módulo: la API contable, el acceso por el gateway, la mensajería SWIFT, divisas por API y presupuesto por API.

El catálogo también vive en una tabla del core. La tabla solo añade superficies a lo que declara el código: no puede quitarle a un módulo una pantalla o una ruta que el código le asigna.

La llave FNM1

Una concesión es un texto con tres partes separadas por punto:

FNM1.<datos en base64url>.<firma en base64url>

Los datos dicen qué módulo, para qué instalación, desde y hasta cuándo, con qué límites y con qué clave (kid) se firmó. La firma es Ed25519 y cubre los bytes exactos de los datos: el core comprueba la firma antes de leer nada más y nunca vuelve a serializar el texto.

El core revisa cada llave en este orden y, si la rechaza, dice por qué con un código estable:

Comprobación	Código si falla
Forma: prefijo, dos segmentos, datos legibles	MALFORMED
La clave kid es una de las conocidas	UNKNOWN_KID
La firma es válida	BAD_SIGNATURE
La instalación de la llave es esta	INSTALLATION_MISMATCH (o INSTALLATION_UNBOUND si el core no tiene instalación definida)
Ya empezó y no ha vencido	NOT_YET_VALID, EXPIRED
El módulo existe en el catálogo	UNKNOWN_MODULE
No fue revocada	REVOKED

Como la instalación va dentro de los datos firmados, una llave emitida para un banco no sirve en otro. Importar dos veces la misma llave no tiene efecto: responde ALREADY_IMPORTED.

La revocación FNR1

Revocar exige un motivo. La consola emisora publica una lista FNR1 firmada con todas las concesiones revocadas de la instalación que aún no han vencido y un número de secuencia (seq) mayor que el anterior. El core aplica una lista solo si su secuencia es mayor que la última que aplicó: una lista vieja que llegue tarde se ignora (STALE_REVOCATION). Al importar un lote, las revocaciones se aplican primero.

Cuando cambian las condiciones de una suscripción (renovación, límites, un módulo retirado, una clave de firma nueva), la consola revoca la concesión anterior y emite la nueva: un core nunca conserva dos llaves distintas del mismo módulo.

La rotación de claves de firma

La clave privada vive solo en la consola emisora, en su entorno, nunca en una base de datos ni en el banco. El core guarda solo claves públicas, como una lista kid:clave. Para rotar:

1. Se genera un par nuevo con un kid nuevo y se despliega en la consola emisora.
2. Se vuelven a emitir las suscripciones: las llaves nuevas salen firmadas con el kid nuevo.
3. El core lista el kid nuevo y los anteriores mientras queden llaves vigentes firmadas con ellos.

Reutilizar un kid con otra clave pública se rechaza al arrancar la consola.

La sincronización: el core tira, nunca empujan

sequenceDiagram
  participant C as Core de la institución
  participant E as Consola emisora
  Note over C: al arrancar (con una espera breve), cada 6 h o bajo demanda
  C->>E: pide sus llaves (instalación + clave de sincronización)
  E-->>C: concesiones FNM1 vigentes + última FNR1
  C->>C: verifica firma, instalación y vigencia de cada una
  C->>C: aplica la revocación y luego importa las concesiones
  Note over C,E: sin conexión, lo ya importado sigue valiendo hasta su fecha de fin

• Cuándo. Una vez poco después de arrancar, cada seis horas y cuando alguien pulsa «Sincronizar ahora» o llama a la API de sincronización. Si ya hay una en curso, la nueva espera o responde 409.
• Con qué. Cada instalación tiene una clave de sincronización que la consola muestra una sola vez y de la que solo guarda su huella SHA-256. Generar otra anula la anterior al instante.
• Sin conexión. Si la consola no responde, el core no pierde nada: lo importado sigue vigente hasta su fecha de fin o hasta que llegue una revocación. La verificación es local, con la clave pública.
• Instalación suspendida. La consola responde 423 y el core no recibe concesiones nuevas.

La regla que no rompe nada: aplicación aditiva

Un módulo está habilitado si su casilla heredada está encendida o si existe una concesión FNM1 vigente y no revocada. La llave por módulo solo puede añadir permisos: ningún módulo que hoy funciona deja de funcionar por instalar este mecanismo.

Situación	Resultado
Casilla heredada encendida	Habilitado (origen LEGACY)
Concesión FNM1 vigente	Habilitado (origen GRANT)
Módulo heredado sin casilla ni concesión	Bloqueado (si el core tiene una licencia registrada; sin ella no aplica restricciones de módulo)
Módulo nuevo sin concesión	Se bloquea solo si se enciende el interruptor de módulos nuevos; apagado, sigue abierto

Siguientes pasos

• Emite las llaves de una institución: instalación, plan, suscripción y emisión en la consola emisora.
• Sincroniza y verifica las licencias en el core: qué ver en las pantallas del core.
• SaaS en nube propia: la arquitectura de celdas: dónde entra la emisión en el alta de una institución.