Gesgocom.PlantillasCorreo 1.1.0
Gesgocom.PlantillasCorreo
Sustitución de variables en plantillas de correo por tipo y contexto, con un analizador de una sola pasada.
- Marcadores:
{{clave}}y{{{clave}}}, conclave=[A-Za-z0-9_]+. Lo que no encaja se copia literal. - Los valores insertados no se vuelven a analizar: no hay sustituciones encadenadas.
SustituirHtml: cuerpo HTML.{{clave}}se escapa; solo vale en contenido de elemento o dentro de un valor de atributo entre comillas.SustituirTexto: cuerpo en texto plano. No escapa;{{{clave}}}solo con conversor (SaneadorContenido.ATexto).SustituirAsunto: asunto. Sin{{{clave}}}y siempre en una sola línea.- Todo marcador rechazado se deja vacío y se registra en
Incidencias; nunca se lanza excepción por el contenido.
Modelo de seguridad
- Una sola pasada: la plantilla se recorre una vez de izquierda a derecha, en tiempo lineal. Lo insertado nunca se
vuelve a analizar, así que un valor que contenga
{{otra}}no se expande. - El catálogo manda: el tipo de cada variable lo decide el catálogo del servidor, no la plantilla. Una clave que no está en el catálogo se deja vacía y se registra.
- Contexto HTML con estados explícitos: el procesador sigue el tokenizador HTML (contenido, apertura de etiqueta,
nombre de etiqueta, entre atributos, nombre de atributo, valor con y sin comillas, comentarios y declaraciones,
texto crudo) alimentado solo con el texto literal de la plantilla. Los valores insertados no cambian el estado: se
escapan (
& < > " ') o, en el caso de{{{ }}}, llegan ya saneados. - Dónde se admite un marcador: en contenido de elemento y en valores de atributo entre comillas. Se rechaza en el
nombre de etiqueta (
<scr{{x}}>), en nombres de atributo o entre atributos (<img {{x}}="…">), en valores sin comillas (title={{x}}), en atributos de evento (on*),srcdocysrcset. - Comentarios y declaraciones:
<!-- … -->(con los cierres del navegador:-->,--!>,<!-->,<!--->),<!…>,<!DOCTYPE …>,<?…>y</1…>: todo marcador se rechaza. Excepción: los comentarios condicionales de Outlook (<!--[if mso | IE]>…<![endif]-->y la forma<!--[if !mso]><!-->…<!--<![endif]-->que genera MJML) se analizan como HTML normal con las mismas reglas, porque Outlook los pinta. - Texto crudo: dentro de
script,style,textarea,title,xmp,iframe,noembedynoframesno se admiten marcadores. El elemento solo se cierra con</nombreseguido de espacio HTML,/o>(no</script-x>). - Bloqueo: tras
<![CDATA[,<svg>,<math>,<plaintext>,<select>,<frameset>o<!--dentro de unscript, el contexto deja de ser determinable con seguridad (contenido extranjero, escapado de script, modos que ignoran etiquetas) y se rechazan todos los marcadores siguientes del documento. - URL: si un valor de
href/xlink:hrefcontiene algún marcador, al cerrarse la comilla se valida el valor final entero: debe empezar porhttps://,mailto:otel:(ignorando espacios iniciales, tabuladores y saltos, como el navegador). Ensrc,background,poster,action,formaction,lowsrc,dynsrc,dataycodebase, solohttps://. Si no vale, el atributo se queda vacío (href="") y se registra. Las URL relativas o//hostse rechazan, y un esquema escrito con entidades también. style: un marcador solo vale como valor completo de una declaración (propiedad: {{x}};o al final del atributo) y el valor debe ser un color hexadecimal o una palabra/medida simple ([A-Za-z0-9.%-]+). Nada deurl(), funciones, escapes ni fragmentos de identificador.- Triple llave:
{{{clave}}}solo inserta HTML si la variable esContenidoEnriquecido, el marcador está en contenido de elemento y se ha pasado un saneador. En cualquier otro caso queda vacío y se registra. - Asunto:
SustituirAsuntono admite{{{ }}}y cambia por un espacio CR, LF, U+0085, U+2028 y U+2029 de cada valor y del resultado final, para que no se puedan partir cabeceras. - Saneador (lista blanca):
SaneadorContenido.Sanearsolo conserva las etiquetas de losFormatoPermitidoelegidos (p,br,strong,b,em,i,ul,ol,li,a). Elimina atributos, clases y propiedades CSS ajenos; loshrefsolo pueden serhttps:omailto:; descarta con su contenidoscript,style,noscript,template,iframe,object,embed,titleytextarea. Añade estilos en línea mínimos y el color de enlace (hexadecimal; si no es válido, el de por defecto). - Límites del contenido enriquecido:
SanearyATextodevuelven cadena vacía si el HTML superaSaneadorContenido.TamanoMaximo(512 K caracteres) o 10 000<(el analizador de AngleSharp es cuadrático con la profundidad); el procesador deja entonces el marcador vacío con una incidencia.ATextorecorre el árbol sin recursión y, más allá de 256 niveles, conserva el texto sin estructura. - Texto plano:
SustituirTextono escapa HTML. Para insertar contenido enriquecido en texto se le pasaSaneadorContenido.ATexto, que no devuelve HTML.
Ejemplo completo
using Gesgocom.PlantillasCorreo;
var catalogo = new Dictionary<string, VariableCatalogo>
{
["nombre"] = new("nombre", "Nombre", TipoVariable.Texto, "Ana"),
["enlace"] = new("enlace", "Enlace de acceso", TipoVariable.Enlace, "https://ejemplo.es"),
["mensaje"] = new("mensaje", "Mensaje", TipoVariable.ContenidoEnriquecido, "<p>Hola</p>"),
};
var valores = new Dictionary<string, string>
{
["nombre"] = "Ana <b>",
["enlace"] = "https://ejemplo.es/acceso?x=1&y=2",
["mensaje"] = "<p>Hola <strong>Ana</strong> <script>alert(1)</script></p>",
};
var html = ProcesadorMarcadores.SustituirHtml(
"<p>Hola {{nombre}}</p><a href=\"{{enlace}}\">Entrar</a>{{{mensaje}}}",
catalogo, valores, SaneadorContenido.Saneador(FormatoPermitido.Todos));
var asunto = ProcesadorMarcadores.SustituirAsunto("Bienvenida, {{nombre}}", catalogo, valores);
var texto = ProcesadorMarcadores.SustituirTexto("Hola {{nombre}}\n\n{{{mensaje}}}", catalogo, valores, SaneadorContenido.ATexto);
foreach (var i in html.Incidencias.Concat(asunto.Incidencias).Concat(texto.Incidencias))
logger.LogWarning("Plantilla: {Incidencia}", i);
// html.Texto, asunto.Texto y texto.Texto son lo que se envía.
Asistente de redacción
AsistenteCorreo no llama a ningún modelo: valida la petición, construye los mensajes y lee la respuesta. La
llamada (proveedor, reintentos, cuota) es de la aplicación. Las cadenas JSON y JsonElement son la frontera.
if (AsistenteCorreo.ValidarProponer(descripcion, "aviso", "formal", variables, out var peticion) is { } error)
return BadRequest(error);
var mensajes = AsistenteCorreo.MensajesProponer(peticion!); // { Role, Content }: sistema y usuario
string? respuesta = await MiModelo.PreguntarAsync(mensajes, AsistenteCorreo.MaxTokens, AsistenteCorreo.Temperatura);
var propuesta = AsistenteCorreo.InterpretarProponer(respuesta); // null si no hay objeto con "documento"
// propuesta.Asunto, propuesta.DocumentoJson, propuesta.ToJson()
ValidarMejorar / MensajesMejorar / InterpretarMejorar hacen lo mismo con la reescritura de un texto en línea.
ValidarMejorar / ValidarProponer aceptan JsonElement o cadenas JSON (null = ausente; con JsonElement ausente usa default(JsonElement), no default a secas, que es ambiguo).
Los tipos de petición y propuesta solo los crean ValidarX / InterpretarX; MensajesX lanzan ArgumentException si les llega una acción, tono o tipo ajeno.
Diferencia con Newtonsoft: los números del JSON se copian tal cual vienen (1e0 sigue siendo 1e0, no se normaliza a 1.0); solo se rechaza el que no sea un double finito (1e400), con el error de «no válido» o null.
Las etiquetas de variable se sanean (SanearEtiqueta) porque llegan al modelo; el ejemplo de la variable nunca viaja.
Imágenes
if (ImagenCorreo.Reconocer(bytes, out var error) is not { } imagen) return BadRequest(error); // formato no admitido / imagen no válida
var nombre = ImagenCorreo.NombreAleatorio(imagen.Formato); // 32 hexadecimales + extensión
Se lee solo la cabecera (no se decodifica) y se exige la firma completa: PNG de 8 bytes, GIF87a/GIF89a, WebP con RIFF…WEBP y chunk VP8/VP8L/VP8X. Pásale el archivo entero: en JPEG las dimensiones pueden estar tras
segmentos EXIF grandes.
Desarrollo
make test # pruebas en Release
NUGET_API_KEY=… make pack-current # pruebas, compilación y publicación de la versión actual
NUGET_API_KEY solo se lee del entorno; sin ella los pack* fallan antes de compilar.
No packages depend on Gesgocom.PlantillasCorreo.
.NET 10.0
- AngleSharp (>= 1.10.0)
- HtmlSanitizer (>= 11.0.26)