README

Cliente oficial para integración con BSLSAC el Messenger API.

Este paquete encapsula la comunicación con el servicio centralizado Messenger, proporcionando una interfaz simple para enviar notificaciones desde aplicaciones Laravel sin que los sistemas consumidores tengan que implementar lógica de seguridad, construcción de solicitudes HTTP o generación de firmas.

Descripción

BSLSAC Messenger Client fue creado para estandarizar la comunicación entre aplicaciones PHP y el Messenger API de BSLSAC.

El objetivo principal es separar responsabilidades:

• Las aplicaciones consumidoras únicamente definen la notificación que desean enviar.
• El paquete administra la comunicación segura.
• Messenger API administra la autenticación, procesamiento y entrega.

La aplicación consumidora no debe conocer detalles internos del protocolo como:

• generación de timestamps;
• construcción de cadenas de firma;
• generación de HMAC;
• creación de headers de seguridad;
• estructura interna de autenticación.

Características

Actualmente el paquete incluye:

• Cliente HTTP para Messenger API.
• Integración nativa con Laravel mediante Service Provider.
• DTO para construcción de notificaciones.
• Generación automática de timestamps.
• Autenticación mediante HMAC-SHA256.
• Generación automática de firmas digitales.
• Creación automática de headers de seguridad.
• Serialización automática del contenido.
• Configuración mediante variables de entorno independientes.

Requisitos

• PHP >= 8.2
• Laravel >= 10
• Composer
• Extensión OpenSSL habilitada.

Instalación

Instalar mediante Composer:

composer require bslsac/messenger-client

Laravel detectará automáticamente el Service Provider mediante Package Discovery.

Publicación de configuración

Después de instalar el paquete, publicar la configuración:

php artisan vendor:publish --tag=messenger-config

Esto generará:

config/messenger.php

Configuración

El paquete utiliza variables propias para evitar dependencia de configuraciones internas de Laravel.

Agregar al archivo .env:

SAC_MESSENGER_URL=http://localhost/messenger/public
SAC_MESSENGER_KEY=erp_main
SAC_MESSENGER_SECRET=your_secret_key

Variables de entorno

Configuración interna

Archivo:

config/messenger.php

Ejemplo:

return [

    'url' => env('SAC_MESSENGER_URL'),

    'key' => env('SAC_MESSENGER_KEY'),

    'secret' => env('SAC_MESSENGER_SECRET'),

    'security' => [

        'timestamp_tolerance' => 300,

        'signature_ttl' => 300,

    ],

];

Seguridad

Messenger utiliza autenticación mediante firma HMAC-SHA256.

Cada solicitud enviada al servicio Messenger contiene una firma generada utilizando:

HMAC-SHA256

La firma utiliza:

• secreto privado de la aplicación;
• método HTTP;
• ruta;
• timestamp;
• contenido del request.

Construcción de la firma

La cadena utilizada para generar la firma tiene la siguiente estructura:

METHOD|PATH|TIMESTAMP|BODY

Ejemplo:

POST|api/v1/notifications|1784049124|{"channel":"email","recipient":"test@test.com"}

La firma generada:

HMAC-SHA256(
    cadena,
    SAC_MESSENGER_SECRET
)

Headers generados

El paquete agrega automáticamente:

X-Application-Key
X-Timestamp
X-Signature

Ejemplo:

X-Application-Key: erp_main

X-Timestamp: 1784049124

X-Signature:
cc2100fe807c06faa900deab7a5fba6c091fc34f67e1b010cb4a0c21b1fb5dcd

Validaciones realizadas por Messenger API

Messenger valida cada solicitud recibida.

Validación de aplicación

Se verifica:

• existencia de la aplicación;
• credencial registrada;
• estado activo;
• fecha de expiración.

Validación de timestamp

Cada solicitud incluye un timestamp Unix.

Messenger valida que la diferencia entre cliente y servidor no exceda el límite permitido.

Esto evita solicitudes antiguas.

Ejemplo:

SAC_MESSENGER_TIMESTAMP

Validación HMAC

Messenger genera nuevamente la firma utilizando el secreto almacenado.

Comparación:

firma_cliente == firma_servidor

Si no coincide:

{
  "success": false,
  "code": "INVALID_SIGNATURE",
  "message": "Invalid request signature."
}

Prevención de Replay Attack

Cada firma utilizada es registrada temporalmente.

Una misma firma no puede utilizarse nuevamente.

El registro contiene:

• aplicación;
• firma;
• timestamp;
• fecha de expiración.

Uso

Ejemplo básico:

use Sac\Messenger\DTO\Notification;
use Sac\Messenger\MessengerManager;


$notification = new Notification(

    channel: 'email',

    recipient: 'usuario@example.com',

    type: 'password_reset',

    payload: [

        'template' => 1,

        'data' => [

            'name' => 'Carlos'

        ]

    ]

);


$response = app(MessengerManager::class)
    ->send($notification);

Estructura de una notificación

Ejemplo:

{
  "channel": "email",
  "recipient": "usuario@example.com",
  "type": "password_reset",
  "payload": {
    "template": 1,
    "data": {
      "name": "Carlos"
    }
  }
}

DTO Notification

La notificación representa la información necesaria para Messenger:

Arquitectura

El paquete sigue una arquitectura donde cada componente tiene una responsabilidad definida.

Aplicación Laravel
        |
        |
        v
Messenger Laravel Client
        |
        |
        v
Messenger API
        |
        |
        v
Servicios de entrega

Responsabilidades

Aplicación consumidora

Responsable de:

• definir la notificación;
• indicar destinatario;
• definir canal;
• enviar datos necesarios.

No debe:

• generar firmas;
• manejar headers;
• construir requests manualmente.

Messenger Laravel Client

Responsable de:

• comunicación HTTP;
• generación de timestamp;
• construcción de firma;
• autenticación;
• serialización.

Messenger API

Responsable de:

• autenticación;
• validación;
• almacenamiento;
• procesamiento;
• entrega.

Manejo de secretos

Los secretos deben almacenarse únicamente mediante variables de entorno.

Ejemplo:

SAC_MESSENGER_SECRET=3d512e4830796cb4903950f5e807749e845abce8f0706146ea2e504a3e78dc54

Los secretos deben generarse utilizando valores aleatorios seguros.

Ejemplo:

bin2hex(random_bytes(32))

No utilizar valores predecibles.

Independencia de APP_KEY

El paquete no utiliza:

APP_KEY

de Laravel para autenticación.

La identidad criptográfica de Messenger es independiente:

SAC_MESSENGER_SECRET

Esto permite:

• cambiar APP_KEY de una aplicación Laravel;
• mantener integraciones existentes;
• separar seguridad del framework y seguridad entre servicios.

Compatibilidad

Diseñado para funcionar con:

• Laravel 10
• Laravel 11
• Laravel 12
• Laravel 13

Roadmap

Próximas mejoras:

• Reintentos configurables.
• Soporte para nuevos canales.
• Versionado estable.
• Mejoras de observabilidad.
• Publicación oficial mediante Composer. s

Versión

0.1.0

Primera versión funcional.

Incluye:

• Cliente HTTP.
• Service Provider.
• DTO Notification.
• Configuración propia.
• Firma HMAC-SHA256.
• Headers de seguridad.
• Comunicación segura con Messenger API.

Licencia

MIT