rl-core-api 0.19.7 → 0.19.8

package/README.md

@@ -139,6 +139,23 @@ Swagger, o remetente dos emails e o emissor exibido no app autenticador:
 Quem já declarava `TOTP_ISSUER` ou `EMAIL_FROM_NAME` continua igual: eles só
 caem no `APP_NAME` quando estão ausentes.
 
+### Os emails
+
+O HTML das três mensagens do core — código 2FA, redefinição de senha e
+primeiro acesso — mora em `src/core/mailer/templates/`, um arquivo `.hbs` por
+mensagem, mais o `layout.hbs` (cabeçalho, título e rodapé) e o `header.hbs`
+(logo ou nome). O `MailerService` só monta os dados e chama o
+`MailTemplateService`, que compila e guarda o template compilado.
+
+Handlebars escapa o que interpola, então nome de usuário entra no email sem
+ninguém precisar lembrar de escapar. O que é HTML montado pelo próprio serviço
+— o corpo dentro da moldura — passa por `raw()`, que é a única porta de
+entrada sem escape.
+
+Os `.hbs` viajam no pacote publicado (`assets` do `nest-cli.json` os copia
+para o `dist`) e são resolvidos por `__dirname`, então valem igual em
+desenvolvimento e instalados em `node_modules`.
+
 Para acrescentar variáveis suas, estenda o schema:
 
 ```ts

package/dist/core/mailer/mailTemplate.service.d.ts

@@ -0,0 +1,10 @@
+import * as Handlebars from "handlebars";
+export type MailTemplateContext = Record<string, string | number | boolean | null | undefined | Handlebars.SafeString>;
+export declare class MailTemplateService {
+    private readonly directory;
+    private readonly compiled;
+    render(name: string, context: MailTemplateContext): string;
+    raw(html: string): Handlebars.SafeString;
+    private templateOf;
+    private sourceOf;
+}

package/dist/core/mailer/mailTemplate.service.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MailTemplateService = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const common_1 = require("@nestjs/common");
+const Handlebars = __importStar(require("handlebars"));
+let MailTemplateService = class MailTemplateService {
+    constructor() {
+        this.directory = (0, node_path_1.join)(__dirname, "templates");
+        this.compiled = new Map();
+    }
+    render(name, context) {
+        return this.templateOf(name)(context);
+    }
+    raw(html) {
+        return new Handlebars.SafeString(html);
+    }
+    templateOf(name) {
+        const cached = this.compiled.get(name);
+        if (cached) {
+            return cached;
+        }
+        const template = Handlebars.compile(this.sourceOf(name));
+        this.compiled.set(name, template);
+        return template;
+    }
+    sourceOf(name) {
+        try {
+            return (0, node_fs_1.readFileSync)((0, node_path_1.join)(this.directory, `${name}.hbs`), "utf8");
+        }
+        catch {
+            throw new Error(`Template de email não encontrado: ${name}.hbs`);
+        }
+    }
+};
+exports.MailTemplateService = MailTemplateService;
+exports.MailTemplateService = MailTemplateService = __decorate([
+    (0, common_1.Injectable)()
+], MailTemplateService);

package/dist/core/mailer/mailer.module.js

@@ -9,13 +9,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MailerModule = void 0;
 const common_1 = require("@nestjs/common");
 const mailer_service_1 = require("./mailer.service");
+const mailTemplate_service_1 = require("./mailTemplate.service");
 let MailerModule = class MailerModule {
 };
 exports.MailerModule = MailerModule;
 exports.MailerModule = MailerModule = __decorate([
     (0, common_1.Global)(),
     (0, common_1.Module)({
-        providers: [mailer_service_1.MailerService],
+        providers: [mailTemplate_service_1.MailTemplateService, mailer_service_1.MailerService],
         exports: [mailer_service_1.MailerService],
     })
 ], MailerModule);

package/dist/core/mailer/mailer.service.d.ts

@@ -1,12 +1,12 @@
 import { EnvService } from "../config/env.service";
+import { MailTemplateService } from "./mailTemplate.service";
 export declare class MailerService {
     private readonly env;
+    private readonly templates;
     private readonly logger;
     private readonly transporter;
-    constructor(env: EnvService);
+    constructor(env: EnvService, templates: MailTemplateService);
     private send;
-    private escapeHtml;
-    private header;
     private layout;
     sendTwoFactorCode(to: string, code: string, userName: string): Promise<void>;
     sendPasswordReset(to: string, token: string, userName: string): Promise<void>;

package/dist/core/mailer/mailer.service.js

@@ -47,9 +47,11 @@ exports.MailerService = void 0;
 const common_1 = require("@nestjs/common");
 const nodemailer = __importStar(require("nodemailer"));
 const env_service_1 = require("../config/env.service");
+const mailTemplate_service_1 = require("./mailTemplate.service");
 let MailerService = MailerService_1 = class MailerService {
-    constructor(env) {
+    constructor(env, templates) {
         this.env = env;
+        this.templates = templates;
         this.logger = new common_1.Logger(MailerService_1.name);
         this.transporter = nodemailer.createTransport({
             host: this.env.get("EMAIL_HOST"),
@@ -72,64 +74,35 @@ let MailerService = MailerService_1 = class MailerService {
             throw error;
         }
     }
-    escapeHtml(value) {
-        return value
-            .replace(/&/g, "&")
-            .replace(/</g, "&lt;")
-            .replace(/>/g, "&gt;")
-            .replace(/"/g, "&quot;")
-            .replace(/'/g, "&#39;");
-    }
-    header(brand) {
-        if (brand.logoUrl) {
-            return `<img src="${brand.logoUrl}" alt="${this.escapeHtml(brand.name)}" style="max-height:40px;max-width:200px;">`;
-        }
-        return `<span style="font-size:20px;font-weight:bold;color:${brand.color};">${this.escapeHtml(brand.name)}</span>`;
-    }
     layout(title, body) {
         const brand = this.env.brand();
-        return `
-      <div style="font-family: Arial, sans-serif; padding: 20px; max-width: 600px; margin: 0 auto;">
-        <div style="padding-bottom:20px;border-bottom:1px solid #ddd;margin-bottom:24px;">
-          ${this.header(brand)}
-        </div>
-        <h2 style="color: #333;">${title}</h2>
-        ${body}
-        <hr style="border: none; border-top: 1px solid #ddd; margin: 30px 0;">
-        <p style="color: #999; font-size: 12px;">
-          Mensagem automática de ${this.escapeHtml(brand.name)}, não responda.
-        </p>
-      </div>`;
+        return this.templates.render("layout", {
+            title,
+            body: this.templates.raw(body),
+            header: this.templates.raw(this.templates.render("header", {
+                logoUrl: brand.logoUrl,
+                name: brand.name,
+                color: brand.color,
+            })),
+            brandName: brand.name,
+        });
     }
     async sendTwoFactorCode(to, code, userName) {
-        const expiry = this.env.get("TWO_FACTOR_EMAIL_CODE_EXPIRY");
-        const color = this.env.brand().color;
-        const body = `
-      <p>Olá ${this.escapeHtml(userName)},</p>
-      <p>Seu código de verificação (2FA) é:</p>
-      <div style="text-align:center;margin:30px 0;">
-        <div style="background:#f5f5f5;padding:20px;border-radius:5px;display:inline-block;">
-          <h1 style="margin:0;font-size:36px;letter-spacing:8px;color:${color};">${code}</h1>
-        </div>
-      </div>
-      <p><strong>Este código expira em ${expiry} minutos.</strong></p>
-      <p>Se você não tentou fazer login, proteja sua conta imediatamente.</p>`;
+        const body = this.templates.render("twoFactorCode", {
+            userName,
+            code,
+            color: this.env.brand().color,
+            expiry: this.env.get("TWO_FACTOR_EMAIL_CODE_EXPIRY"),
+        });
         await this.send(to, "Seu código de verificação (2FA)", this.layout("Autenticação em duas etapas", body));
     }
     async sendPasswordReset(to, token, userName) {
-        const url = `${this.env.get("APP_URL")}/reset-password?token=${token}`;
-        const expiry = this.env.get("PASSWORD_RESET_TOKEN_EXPIRY");
-        const color = this.env.brand().color;
-        const body = `
-      <p>Olá ${this.escapeHtml(userName)},</p>
-      <p>Recebemos uma solicitação para redefinir sua senha. Clique no botão abaixo:</p>
-      <div style="text-align:center;margin:30px 0;">
-        <a href="${url}" style="background:${color};color:#fff;padding:12px 30px;text-decoration:none;border-radius:5px;display:inline-block;">Redefinir senha</a>
-      </div>
-      <p>Ou copie e cole este link no navegador:</p>
-      <p style="word-break:break-all;color:#666;">${url}</p>
-      <p><strong>Este link expira em ${expiry} minutos.</strong></p>
-      <p>Se você não solicitou, ignore este email.</p>`;
+        const body = this.templates.render("passwordReset", {
+            userName,
+            url: this.templates.raw(`${this.env.get("APP_URL")}/reset-password?token=${token}`),
+            color: this.env.brand().color,
+            expiry: this.env.get("PASSWORD_RESET_TOKEN_EXPIRY"),
+        });
         await this.send(to, "Redefinição de senha", this.layout("Redefinição de senha", body));
     }
     formatExpiry(minutes) {
@@ -140,24 +113,20 @@ let MailerService = MailerService_1 = class MailerService {
         return hours === 1 ? "1 hora" : `${hours} horas`;
     }
     async sendFirstAccess(to, token, userName) {
-        const url = `${this.env.get("APP_URL")}/reset-password?token=${token}`;
-        const expiry = this.formatExpiry(this.env.get("FIRST_ACCESS_TOKEN_EXPIRY"));
         const brand = this.env.brand();
-        const body = `
-      <p>Olá ${this.escapeHtml(userName)},</p>
-      <p>Sua conta em ${this.escapeHtml(brand.name)} foi criada. Para acessar, defina sua senha clicando no botão abaixo:</p>
-      <div style="text-align:center;margin:30px 0;">
-        <a href="${url}" style="background:${brand.color};color:#fff;padding:12px 30px;text-decoration:none;border-radius:5px;display:inline-block;">Definir minha senha</a>
-      </div>
-      <p>Ou copie e cole este link no navegador:</p>
-      <p style="word-break:break-all;color:#666;">${url}</p>
-      <p><strong>Este link expira em ${expiry}.</strong></p>
-      <p>No primeiro login você também precisará configurar a autenticação em duas etapas (2FA).</p>`;
+        const body = this.templates.render("firstAccess", {
+            userName,
+            brandName: brand.name,
+            url: this.templates.raw(`${this.env.get("APP_URL")}/reset-password?token=${token}`),
+            color: brand.color,
+            expiry: this.formatExpiry(this.env.get("FIRST_ACCESS_TOKEN_EXPIRY")),
+        });
         await this.send(to, "Defina sua senha de primeiro acesso", this.layout("Primeiro acesso", body));
     }
 };
 exports.MailerService = MailerService;
 exports.MailerService = MailerService = MailerService_1 = __decorate([
     (0, common_1.Injectable)(),
-    __metadata("design:paramtypes", [env_service_1.EnvService])
+    __metadata("design:paramtypes", [env_service_1.EnvService,
+        mailTemplate_service_1.MailTemplateService])
 ], MailerService);

package/dist/core/mailer/templates/firstAccess.hbs

@@ -0,0 +1,9 @@
+<p>Olá {{userName}},</p>
+<p>Sua conta em {{brandName}} foi criada. Para acessar, defina sua senha clicando no botão abaixo:</p>
+<div style="text-align:center;margin:30px 0;">
+  <a href="{{url}}" style="background:{{color}};color:#fff;padding:12px 30px;text-decoration:none;border-radius:5px;display:inline-block;">Definir minha senha</a>
+</div>
+<p>Ou copie e cole este link no navegador:</p>
+<p style="word-break:break-all;color:#666;">{{url}}</p>
+<p><strong>Este link expira em {{expiry}}.</strong></p>
+<p>No primeiro login você também precisará configurar a autenticação em duas etapas (2FA).</p>

package/dist/core/mailer/templates/header.hbs

@@ -0,0 +1,12 @@
+{{!--
+  O cabeçalho da marca: a logo quando houver uma, senão o nome.
+
+  A logo precisa ser URL absoluta e pública (`APP_LOGO_URL`) — o cliente de
+  email busca a imagem do servidor dele e não alcança os assets da interface.
+  O `alt` com o nome cobre quem bloqueia imagem por padrão, que é a maioria.
+--}}
+{{#if logoUrl}}
+  <img src="{{logoUrl}}" alt="{{name}}" style="max-height:40px;max-width:200px;">
+{{else}}
+  <span style="font-size:20px;font-weight:bold;color:{{color}};">{{name}}</span>
+{{/if}}

package/dist/core/mailer/templates/layout.hbs

@@ -0,0 +1,18 @@
+{{!--
+  A moldura de toda mensagem: cabeçalho da marca, título, corpo e rodapé.
+
+  `header` e `body` chegam como HTML pronto, marcado por `raw()` no serviço; o
+  resto é escapado pelo Handlebars, que é o que tira do serviço o trabalho de
+  lembrar do escape em cada nome de usuário interpolado.
+--}}
+<div style="font-family: Arial, sans-serif; padding: 20px; max-width: 600px; margin: 0 auto;">
+  <div style="padding-bottom:20px;border-bottom:1px solid #ddd;margin-bottom:24px;">
+    {{header}}
+  </div>
+  <h2 style="color: #333;">{{title}}</h2>
+  {{body}}
+  <hr style="border: none; border-top: 1px solid #ddd; margin: 30px 0;">
+  <p style="color: #999; font-size: 12px;">
+    Mensagem automática de {{brandName}}, não responda.
+  </p>
+</div>

package/dist/core/mailer/templates/passwordReset.hbs

@@ -0,0 +1,9 @@
+<p>Olá {{userName}},</p>
+<p>Recebemos uma solicitação para redefinir sua senha. Clique no botão abaixo:</p>
+<div style="text-align:center;margin:30px 0;">
+  <a href="{{url}}" style="background:{{color}};color:#fff;padding:12px 30px;text-decoration:none;border-radius:5px;display:inline-block;">Redefinir senha</a>
+</div>
+<p>Ou copie e cole este link no navegador:</p>
+<p style="word-break:break-all;color:#666;">{{url}}</p>
+<p><strong>Este link expira em {{expiry}} minutos.</strong></p>
+<p>Se você não solicitou, ignore este email.</p>

package/dist/core/mailer/templates/twoFactorCode.hbs

@@ -0,0 +1,9 @@
+<p>Olá {{userName}},</p>
+<p>Seu código de verificação (2FA) é:</p>
+<div style="text-align:center;margin:30px 0;">
+  <div style="background:#f5f5f5;padding:20px;border-radius:5px;display:inline-block;">
+    <h1 style="margin:0;font-size:36px;letter-spacing:8px;color:{{color}};">{{code}}</h1>
+  </div>
+</div>
+<p><strong>Este código expira em {{expiry}} minutos.</strong></p>
+<p>Se você não tentou fazer login, proteja sua conta imediatamente.</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rl-core-api",
-  "version": "0.19.7",
+  "version": "0.19.8",
   "description": "Core NestJS: autenticação com 2FA, RBAC, auditoria, notificações e listagens com filtro dinâmico",
   "author": "Rodrigo Liberti",
   "license": "MIT",
@@ -84,6 +84,7 @@
     "cookie-parser": "^1.4.7",
     "dotenv": "^17.4.2",
     "exceljs": "^4.4.0",
+    "handlebars": "^4.7.9",
     "helmet": "^8.3.0",
     "ioredis": "^5.11.1",
     "mysql2": "^3.23.2",