License API para autores de módulos
Cómo se licencia un módulo de pago, la clave del manifiesto, la llamada de activación, el heartbeat y la política de degradación.
Un módulo de pago se licencia con el mismo servidor con el que habla el core, usando el mismo transporte firmado. Lo declaras en el manifiesto; el kernel hace el resto.
La clave del manifiesto#
"licensing": { "product_slug": "your-module" }Que esté presente significa que el módulo está licenciado: el panel
muestra una pantalla de License para él, y el módulo puede preguntar si
los updates están permitidos. Que esté ausente significa que el módulo es
gratis y no se chequea nada. Los módulos de fábrica que vienen con el core
(pagos, gamificación) no llevan ninguna clave licensing.
El product_slug es como el license server conoce al producto, y es lo que
termina en el claim prd del token.
Activación#
El miembro ingresa el serial en Modules > License. El kernel llama al servidor:
POST /v1/activate
{ "serial": "...", "domain": "example.com", "host": "...", "app_version": "1.2.0" }Un éxito trae el token firmado y el entitlement:
{
"ok": true,
"token": "<JWT RS256>",
"license": { "serial": "...", "product": "your-module", "updates_until": 1789000000, "domain": "example.com" },
"features": []
}Un rechazo vuelve con ok: false y una razón: invalid_serial,
domain_in_use, revoked o rate_limited. Llega como HTTP 200; un 4xx
significa que el servidor no está disponible, que es una situación
totalmente distinta.
La licencia de un módulo se activa en el mismo dominio de producción que la licencia del core.
El transporte firmado#
Cada llamada a /v1/* lleva cuatro cabeceras:
X-Bondry-Key: el identificador de la shared key
X-Bondry-Timestamp: hora unix, válida por 300 segundos
X-Bondry-Nonce: uuid v4, un solo uso
X-Bondry-Signature: hex(hmac_sha256(secret, METHOD\nPATH\nTIMESTAMP\nNONCE\nsha256(body)))Nunca construyes esto tú mismo: el license client del kernel firma la llamada. Está documentado aquí para que lo reconozcas en un log.
El token#
RS256, verificado localmente contra la clave pública que viene con Bondry.
Claims: iss, sub (el serial), prd (tu product slug), dom (el
dominio activado), upd (el fin de la ventana de updates), feat, iat,
exp (30 días) y jti.
El token se guarda cifrado y nunca sale de la instalación.
El heartbeat#
Diario, desde el scheduler:
POST /v1/heartbeat
{ "token": "...", "domain": "example.com", "app_version": "1.2.0" }La respuesta refresca el token cuando está por expirar y devuelve el
updates_until actual más flags de revocado y expirado, con un mensaje
humano opcional que se muestra en el panel.
Si no se puede alcanzar el servidor, nada se degrada durante catorce días. Tu módulo no debe tratar un error de red como un rechazo.
La política de degradación#
Esto es una regla del producto, no una sugerencia.
| Estado | Qué puede hacer tu módulo |
|---|---|
| Activa | Todo |
| Ventana de updates vencida | Todo lo que el comprador ya tiene. Updates no disponibles. |
| Revocada | Todo lo que el comprador ya tiene. Un aviso persistente en el panel. Updates no disponibles. |
| Offline más allá del período de gracia | Igual que vencida, reversible al reconectar |
Nunca bloquees contenido ni funcionalidad básica. Una licencia controla los updates y los extras marcados, no el derecho a seguir usando lo que se compró. Un módulo que le cierra a un comprador el acceso a sus propios datos no será aceptado, y es la forma más rápida de ganarse un contracargo.
Preguntar por la licencia#
Pregúntale al kernel, no llames al servidor tú mismo:
if (\App\Kernel\License\ModuleLicenses::allowsUpdates('your-module')) {
// Ofrece el update.
}Probar sin un servidor#
Durante el desarrollo, el license client puede correr sin ningún servidor configurado. Registra la intención y queda desbloqueado, así que nunca estás bloqueado por acceso de red mientras escribes un módulo.