Firmas RSA

Todas las operaciones con STP se autentican mediante firmas digitales RSA-SHA256. Las claves se almacenan en AWS Secrets Manager, nunca en el código.

Algoritmo

• Firma (outgoing): crypto.createSign('RSA-SHA256') con clave privada en formato PEM codificada en Base64
• Verificación (incoming): crypto.createVerify('SHA256') con clave pública de STP en Base64
• Formato de salida: Base64

Clases disponibles (lib/cryptoHandler.js)

Cada tipo de operación tiene su propia clase que construye la cadena original correcta:

Clase	Uso
CryptoHandlerOrdenPago	Orden de pago SPEI saliente
CryptoHandlerCuenta	Registro de cuenta en STP
CryptoHandlerAbono	Verificar abono entrante de STP
CryptoHandlerSaldoCuenta	Consulta de saldo
CryptoHandlerConciliacion	Consulta de conciliación
CryptoHandlerNotificacionEstadoCuenta	Verificar notificación de cuenta
CryptoHandlerNotificacionEstadoTransaccion	Verificar notificación de transacción

Cadenas originales

Las cadenas originales usan el separador | y siempre empiezan y terminan con ||.

Orden de pago (CryptoHandlerOrdenPago)

||{institucionContraparte}|{empresa}|||{claveRastreo}|{institucionOperante}|{monto}|{tipoPago}|{tipoCuentaOrdenante}|{nombreOrdenante}|{cuentaOrdenante}|{rfcCurpOrdenante}|{tipoCuentaBeneficiario}|{nombreBeneficiario}|{cuentaBeneficiario}|{rfcCurpBeneficiario}||||||{conceptoPago}|||||||{referenciaNumerica}|||||||{nombreParticipanteIndirecto}|{cuentaParticipanteIndirecto}|{rfcParticipanteIndirecto}||

Registro de cuenta (CryptoHandlerCuenta)

||{empresa}|{cuenta}|{rfcCurp}||

Abono entrante (CryptoHandlerAbono)

||{id}|{fechaOperacion}|{institucionOrdenante}|{institucionBeneficiaria}|{claveRastreo}|{monto}|{nombreOrdenante}|{tipoCuentaOrdenante}|{cuentaOrdenante}|{rfcCurpOrdenante}|{nombreBeneficiario}|{tipoCuentaBeneficiario}|{cuentaBeneficiario}|{nombreBeneficiario2}|{tipoCuentaBeneficiario2}|{cuentaBeneficiario2}|{rfcCurpBeneficiario}|{conceptoPago}|{referenciaNumerica}|{empresa}|{tipoPago}|{tsLiquidacion}|{folioCodi}||

Saldo de cuenta (CryptoHandlerSaldoCuenta)

||{empresa}|{cuentaOrdenante}|{fecha}||

Conciliación (CryptoHandlerConciliacion)

||{empresa}|{tipoOrden}|{fechaOperacion}||

Notificación estado de cuenta (CryptoHandlerNotificacionEstadoCuenta)

||{cuenta}|{empresa}|{estado}|{observaciones}||

Notificación estado de transacción (CryptoHandlerNotificacionEstadoTransaccion)

||{id}|{empresa}|{folioOrigen}|{estado}|{causaDevolucion}|{tsLiquidacion}||

Uso en código

Firmar una operación (outgoing)

const CryptoHandler = require('./lib/cryptoHandler');

// Construir la clase con los datos de la operación
const crypto = new CryptoHandler.CryptoHandlerCuenta({
  empresa: 'FINALITIX',
  cuenta: '64618001000001237',
  rfcCurp: 'PEGJ800101ABC'
});

// Obtener la firma en Base64
const firma = crypto.getSign(
  bankSecretData.secret.passphrase,
  bankSecretData.secret.privateKey  // PEM en Base64
);

// Incluir en el body de la petición a STP
accountData.firma = firma;

Verificar firma entrante (incoming desde STP)

// Solo se ejecuta en ENV === 'prod'
if (process.env.ENV === 'prod') {
  const { firma } = body;
  delete body.firma; // La firma NO se incluye en la cadena original

  const crypto = new CryptoHandler.CryptoHandlerAbono(body);
  const valid = crypto.verify(firma, bankSecretData.secret.publicKey); // PEM en Base64

  if (!valid) {
    return { status: 500, message: 'error validando firma' };
  }
}

Solo en producción

La verificación de firma RSA está desactivada en desarrollo (ENV !== 'prod'). Configura ENV=prod antes de exponer los endpoints /stp/v1/* al exterior.

Almacenamiento de claves

Las claves se obtienen de AWS Secrets Manager en cada sesión y se cachean en memoria:

lib/helper.js

const bankSecretData = await Helper.retrieveSecret(null, process.env.STP_SECRET_NAME);

// Estructura del secreto
{
  "privateKey": "<PEM privado codificado en Base64>",
  "publicKey":  "<PEM público de STP codificado en Base64>",
  "passphrase": "<passphrase de la clave privada>"
}