# Plan — Firma digital de recibos (microservicio `novasis-firmador-pdf`)

> Estado: **en producción** desde el 17/11/2026, apagado en todas las empresas (ramas `feat/firma-recibos` mergeadas a `pos`/`main`; firmador en `kdbf23/novasis-firmador-pdf`). Falta: prenderlo en DOBA y su prueba con un supermercado (paso 8).
> Pedido de origen: DOBA (los supermercados le piden los recibos firmados por email). Se hace **estándar**: opción por empresa.

## 1. Qué se quiere

Que el PDF del recibo salga **firmado digitalmente con el certificado F1 de la empresa** (el mismo de la factura electrónica) y con un **sello visible**:

```
Firmado digitalmente por: <CN del certificado>
RUC <ruc>-<dv> · 13/11/2026 11:47:05
```

Tiene que ser una firma real (PKCS#7 detached sobre el PDF), no solo el texto: Adobe tiene que mostrar el panel de firmas y avisar si el archivo se modificó.

## 2. Análisis del ejemplo (`firmador_pdf_recibo-main.zip`)

Express + `node-signpdf` 3. Viene del pipeline de Futura (`futura15-prod`): **se toma la idea, no se copia el código**. De todos modos el núcleo es el patrón estándar de las librerías open source (pdf-lib + signpdf).

**Cómo funciona**
1. `POST /api/sign-pdf` recibe `{ empresa: { ruc, dv }, pdfBuffer }`, en base64 o como Buffer serializado.
2. Lee de S3 o de un directorio local los archivos de `<ruc>-<dv>/`: `privateKey.pem`, `publicKey.pem`, `cert.p12` y `pin.txt`.
3. Dibuja el texto «Firmado digitalmente por: CN / Fecha» como **PNG**. Para eso usa canvas, opentype y Jimp.
4. Busca con pdfjs la palabra «Firma» en el PDF y estampa la imagen arriba de cada aparición, en el original y en el duplicado. Si no la encuentra, la pone abajo a la derecha de cada página.
5. Crea con pdf-lib el placeholder (`/Sig`, `ByteRange`, `Contents`, `AcroForm`) y firma con `node-signpdf` (adbe.pkcs7.detached).

**Qué se rescata**
- El flujo placeholder → firma.
- La ubicación por marcador de texto, con posición fija como fallback.
- El sello con CN y fecha en hora de Asunción.
- Un widget de firma por documento.

**Problemas que no se deben repetir**

| # | Problema | Riesgo |
|---|---|---|
| 1 | `/api/sign-pdf` **sin autenticación**, CORS abierto a cualquier origen | Cualquiera que llegue al puerto firma cualquier PDF con el certificado de cualquier empresa |
| 2 | `signPDF` devuelve `{status:'error'}` y la ruta igual lee `.signedPdfBuffer.length` | El error real se pierde: siempre responde «Error al firmar el PDF» |
| 3 | Excepciones por RUC en el código (`80007941` sin texto) y una carpeta `firmas/80146250/` a medida | Contra «nada a medida»: tiene que ser configuración por empresa |
| 4 | `node-signpdf` 3 está **deprecado** (reemplazado por `@signpdf/*` 4.0.0) | Sin mantenimiento |
| 5 | canvas + Jimp + opentype para dibujar texto como imagen | Dependencias nativas (cairo/pango) y sello pixelado. pdf-lib dibuja texto vectorial |
| 6 | Necesita `pin.txt` en texto plano junto al `.p12` | El ERP no guarda el PIN: guarda la clave ya descifrada |
| 7 | Loguea el objeto `empresa` completo; body de 200 MB; `knex` y `db.js` sin usar; `.env.example` con un `SECRET` real | Ruido y superficie de ataque |
| 8 | No valida el vencimiento del certificado | Firmaría con un certificado vencido |
| 9 | El README dice «Timestamp», pero **no hay sello de tiempo (TSA)**: la hora sale del reloj del servidor | Se acepta en la fase 1. TSA queda como fase 2 opcional |

## 3. Cómo encaja con lo que ya existe

- **Certificado**: al subirlo en Configuración › Empresa, el backend guarda en `PATH_CERT/<ruc>/` los archivos `cert.p12`, `privatekey.pem` (PKCS#8, **ya descifrada**, 0600) y `publickey.pem` (el certificado en PEM). Ver `EmpresasService.persistCertificateArtifacts`. El microservicio firma con `privatekey.pem` + `publickey.pem` y **no necesita el PIN**.
- **PDF del recibo**: lo arma `generador-pdf` (`src/recibos/v2/recibo_a4_multi.js`, pdfkit). Lo piden dos lugares:
  - `RecibosService.pdfA4Multi`, que atiende `GET /recibos/:id/pdf`;
  - `CobrosService` (línea ~5643, también contra `/api/v2/generate-recibo`).

  La plantilla **no tiene lugar de firma** ni la palabra «Firma».
- **Flag por empresa**: `empresas` ya tiene columnas booleanas de configuración (`kude_personalizado`, `usar_correo_propio`…). Se suma `recibo_firma_digital Boolean @default(false)`.
- **Topología**: el microservicio corre **en el mismo droplet** que el backend (prod `167.99.127.42` / test `143.198.100.72`), con pm2 y escuchando solo en `127.0.0.1`. Lee `PATH_CERT` en modo solo lectura. La clave privada **nunca viaja por la red**.

## 4. Diseño del microservicio

Repo nuevo **`novasis-firmador-pdf`**: NestJS 11 (el mismo major que el backend), TypeScript, Node 24, pnpm.

```
src/
  main.ts                       escucha en HOST=127.0.0.1, body máx 15 MB, sin CORS
  config/envs.ts                Joi: PORT, HOST, CERT_DIR, FIRMADOR_API_KEY, TZ, MAX_PDF_MB
  common/api-key.guard.ts       x-firmador-key (comparación timingSafeEqual)
  salud/salud.controller.ts     GET /api/v1/salud (sin key; no revela nada)
  firma/
    firma.controller.ts         POST /api/v1/firmar  (application/pdf + ?ruc=&dv=)
    firma.service.ts            orquesta: certificado → sello → placeholder → firma
    certificados.service.ts     lee CERT_DIR/<ruc>/, valida vigencia y que clave y cert coincidan; caché por mtime
    sello.service.ts            dibuja el sello vectorial con pdf-lib (Helvetica, WinAnsi: á é ñ)
    marcador.service.ts         pdfjs-dist: busca el marcador «Firma digital» (página, x, y)
    firmante-forge.ts           Signer de @signpdf/utils con node-forge (PKCS#7 detached + signingTime)
    errores.ts                  códigos: SIN_CERTIFICADO, CERTIFICADO_VENCIDO, PDF_INVALIDO, YA_FIRMADO
test/
  certificado-prueba.ts         genera en memoria un cert autofirmado con forge (no hay certificados en el repo)
  firma.e2e-spec.ts             firma un PDF y verifica la firma: forge sobre ByteRange + `pdfsig` si está instalado
```

**API**

- **Pedido**: `POST /api/v1/firmar?ruc=80000000&dv=1`, con header `x-firmador-key` y el PDF en crudo (`Content-Type: application/pdf`). Sin base64: es un tercio menos de bytes.
- **200**: devuelve `application/pdf` firmado y el header `X-Firma-Titular: <CN>`.
- **422**: devuelve `{ codigo, mensaje }`, con `codigo` igual a `SIN_CERTIFICADO`, `CERTIFICADO_VENCIDO`, `PDF_INVALIDO` o `YA_FIRMADO`.
- **401**: falta la key o no coincide.

**Decisiones tomadas**:
- **Ubicación**: `generador-pdf` reserva un recuadro con el título «Firma digital» sobre el pie de la última página, y el sello se dibuja adentro. Sin marcador, abajo a la derecha de la última página (fallback del ejemplo). Se descarta la búsqueda de «Firma» a secas: en un recibo puede aparecer esa palabra en otro lado.
- **Original y duplicado**: el A4 multi es un solo ejemplar, así que hay un sello y un widget. Si después se firma el ticket o el formato con duplicado, se estampa en cada marcador y el widget queda en el último (igual que el ejemplo).
- **Sin excepciones por RUC**. Si alguna empresa quiere firma invisible, se agrega `sello_visible` como opción del pedido, no un `if` por RUC.
- **Hora**: la del servidor, en `America/Asuncion`, en el sello y en `signingTime`. Sin TSA en la fase 1.
- **Logs**: RUC, tamaño, ms y resultado. Nunca el PDF, la clave ni el CN completo en errores.

## 5. Cambios en el ERP

| Dónde | Cambio |
|---|---|
| `backend/prisma` | Migración `empresas.recibo_firma_digital boolean not null default false` (directorio + `migration.sql` idempotente) |
| `backend/src/config/envs.ts` | `FIRMADOR_PDF_URL` y `FIRMADOR_PDF_KEY`, opcionales: sin ellas la opción no se ofrece |
| `backend/src/recibos` | `FirmaReciboService.firmarSiCorresponde(empresa, pdf)`, que usan `pdfA4Multi` y `CobrosService`. Si el firmador falla, el recibo **sale igual sin firma** y la respuesta lleva `X-Firma: error` + motivo (no se frena la cobranza) |
| `backend/src/empresas` | `recibo_firma_digital` en el DTO de configuración. Al activarla se valida que haya certificado vigente |
| `generador-pdf` | Con `firma_digital: true` en el payload, recuadro «Firma digital» antes del pie (salto de página si no entra) |
| `frontend` (`src/features`, kit) | Interruptor «Firmar los recibos digitalmente» en Configuración › Empresa, con el aviso de Adobe. Toast si el recibo salió sin firma |
| Permisos | El endpoint de recibos no cambia. La opción usa el permiso que ya protege la configuración de la empresa |
| Docs | Esta página, la guía de NovaIA de Cobros (cómo activarlo, qué ve el cliente, aviso de Adobe) y la topología de los servidores |

## 6. Orden de ejecución

1. **Repo y esqueleto**: `nest new`, lint/prettier/jest como el backend, `.env.example` sin secretos, README con cómo correrlo. Remoto en GitHub: lo crea el usuario o Derlis (`novasis-firmador-pdf`, privado).
2. **Núcleo de firma** con tests:
   - cert autofirmado en memoria → firmar → verificar el PKCS#7 sobre el ByteRange;
   - un PDF modificado después de firmar tiene que **fallar** la verificación;
   - certificado vencido → 422;
   - `pdfsig` local para confirmar que lo lee un tercero.
3. **Sello y marcador**: PDF de prueba con y sin el recuadro, con captura (pdftoppm) para ver la ubicación.
4. **API, key y límites**: guard, throttle, 15 MB, errores con código y e2e del controller.
5. **ERP**: migración, envs, `FirmaReciboService`, `generador-pdf` y frontend, con sus tests (jest/vitest) y la regla de guards.
6. **Test** (`143.198.100.72`):
   - pm2 `novasis-firmador-pdf` en `127.0.0.1:7100`;
   - envs en backend y firmador;
   - un certificado de **prueba** en una empresa de test (Kety no tiene SIFEN);
   - e2e Playwright: activar la opción → descargar el recibo → `pdfsig` dice «Signature is Valid» (la cadena puede quedar «not trusted»).
7. **Producción**, con OK explícito:
   - deploy del firmador (pm2, `nvm use 24`) y del backend/generador/frontend;
   - la migración la corre el usuario;
   - se activa **solo en DOBA**.
8. **Validación con DOBA**: mandan un recibo firmado a un supermercado. Si lo acepta, se cierra. Si piden ver una firma «de puño», se evalúa la imagen de firma como opción aparte (plan B).

## 7. Riesgos y avisos

- **Adobe muestra «validez desconocida»**: la raíz de la PKI paraguaya no está en la lista de confianza de Adobe (AATL). La firma es válida, pero el supermercado ve un aviso amarillo salvo que confíe en la raíz. Hay que avisarle a DOBA antes de la prueba.
- **Sin TSA** la fecha la pone nuestro servidor: alcanza para un recibo. Si alguien pide sello de tiempo, se agrega como fase 2 (TSA RFC 3161) sin cambiar la API.
- **Certificado vencido o rotado**: el ERP ya reescribe `PATH_CERT/<ruc>/` al subir uno nuevo, y el firmador lo relee por mtime, sin reinicio.
- **Mismo droplet**: el firmador comparte servidor con el backend. Es liviano (sin canvas ni Chromium), pero se le pone `max_memory_restart` en pm2.
- **Código de terceros**: el ejemplo es de Futura. Se reescribe desde cero sobre `@signpdf` 4 y no se copia texto ni estructura.

## 9. Imagen de firma y sello (pedido DOBA, 18/11/2026)

DOBA pide, además de la firma digital, poder cargar una **imagen**: la firma manuscrita escaneada o una foto de la firma con el sello, impresa en el recibo. Se hace estándar y **convive** con la firma digital: cada empresa usa una, la otra o las dos.

| Dónde | Cambio |
|---|---|
| `backend/prisma` | `empresas.recibo_firma_imagen_key` (VARCHAR 300, null = sin imagen). Migración `20261118120000_empresas_recibo_firma_imagen`, solo agrega la columna |
| `backend/src/firma-digital/firma-imagen.service.ts` | Guarda la imagen en Spaces con **ACL privada** (`empresas/<id>/firma-recibo-<uuid>.png`): con URL pública cualquiera copiaría la firma. Al subirla: gira por EXIF, **vuelve transparente el papel** (estima su tono por la propia imagen), recorta el borde, achica a 800×400 y la guarda en PNG con paleta (~30 KB). La pantalla la ve con URL firmada de 10 min. Para el recibo se baja y se cachea en memoria (30 min) por clave |
| `FirmaReciboService.paraRecibo` | Devuelve las dos firmas del recibo A4 (`firmante` digital e `imagen` en base64). Si la imagen no se puede bajar, el recibo sale sin ella (no se frena la cobranza) |
| `RecibosService.pdfA4Multi`, `CobrosService.generateReciboPdf` | Mandan `firma_imagen` al generador junto con `firma_digital` |
| `EmpresasController` | `GET/POST/DELETE /empresas/:id/firma-recibo` (VER / EDITAR / EDITAR, submódulo ADM_EMPRESAS, alcance `propia_o_superior`). Quitar no borra el archivo de Spaces |
| `generador-pdf` | `utils.reservarFirmas`: una fila al pie, alineada a la derecha, `[FIRMA Y SELLO][FIRMA DIGITAL]`. La imagen se dibuja con línea de firma debajo; el recuadro digital sigue con `Info.NovasisFirma`. Imagen ilegible → el recibo sale sin ella |
| `frontend` | Bloque nuevo **«Firma de los recibos»** en Datos de la empresa (`BloqueFirmaRecibos.tsx`), debajo de Certificado: la imagen (vista previa → «Guardar imagen» → muestra cómo sale; «Quitar imagen» con confirmación) y el interruptor de la firma digital, que se mudó desde el bloque Certificado y pasó a llamarse «Firma digital con el certificado de la empresa» |
| Docs | Guías de NovaIA `guia-empresa.md` y `guia-cobros-finanzas.md` |

## 8. Registro de cambios en el ERP

| Fecha | Cambio | Entorno |
|---|---|---|
| 13/11/2026 | Plan escrito | — |
| 13/11/2026 | Microservicio `novasis-firmador-pdf` (repo kdbf23): firma, sello, API con clave, 17 tests (incluye `pdfsig`). Contrato con el generador: `Info.NovasisFirma = "pagina;x;y;ancho;alto"`. Encontrado y corregido: forge codifica dos veces el emisor no ASCII en el SignerInfo | local |
| 13/11/2026 | Backend: columna `empresas.recibo_firma_digital` (migración `20261113210000_empresas_recibo_firma_digital`, sólo agrega la columna), envs `FIRMADOR_PDF_URL`/`FIRMADOR_PDF_KEY` (opcionales), `src/firma-digital/` (`FirmaReciboService`, `validarActivacionFirmaRecibos`), `RecibosService.pdfA4Multi` y `CobrosService.generateReciboPdf` firman si corresponde (sólo A4), headers `X-Firma-Digital`/`X-Firma-Motivo` + `exposedHeaders` en el CORS de `main.ts`, `PUT /empresas/:id` acepta `recibo_firma_digital` (exige firmador y certificado vigente) | local |
| 13/11/2026 | generador-pdf: con `firma_digital: true` los recibos A4 (`recibo_a4`, `recibo_a4_multi`) reservan el recuadro «FIRMA DIGITAL» y dejan `Info.NovasisFirma` (`utils.reservarRecuadroFirma`) | local |
| 13/11/2026 | Frontend: interruptor en Configuración › Empresa › Certificado (`FirmaRecibos.tsx`); los visores de recibos (Recibos y Cobros) leen el resultado y avisan si salió sin firma (`cobranzas/recibos/pdfRecibo.ts`); e2e `e2e/firma-recibos.real.spec.js` | local |
| 13/11/2026 | **Test** (143.198.100.72): firmador en `/var/www/html/novasis-firmador-pdf` (pm2 `novasis-firmador-pdf`, 127.0.0.1:7100, `CERT_DIR=/opt/certificados`; subido por rsync porque el server no tiene acceso al repo de kdbf23). Backend en `feat/firma-recibos` con `FIRMADOR_PDF_URL`/`FIRMADOR_PDF_KEY` (backup del `.env` en `.env.bak-firma-*`); `migrate deploy` aplicó además 4 migraciones de `pos` que faltaban en test. Generador en `feat/firma-recibos`. Frontend en la rama local `test/firma-recibos` = `feat/soporte-ia-nueva-ui` + `feat/firma-recibos` (para no sacar Soporte IA de test). Kety tiene un certificado **de prueba** autofirmado (`/opt/certificados/2156747` + fila en `certificados`, usuario `prueba-firma-recibos`). e2e 2/2 y `pdfsig` «Signature is Valid» | test |
| 17/11/2026 | **Producción** (167.99.127.42): backend `pos` b015fbe8 (migración `20261113210000_empresas_recibo_firma_digital`), generador-pdf `main` e4b751f (aplicado desde un `git bundle`: el remoto del generador en prod es HTTPS sin credenciales), frontend `main` d088d7d3 por rsync (backup `dist.bak-*`). Firmador en `/var/www/html/novasis-firmador-pdf` (rsync, pm2 `novasis-firmador-pdf`, 127.0.0.1:7100, `--max-memory-restart 300M`, en `pm2 save`); clave nueva generada en el server, en su `.env` y en `FIRMADOR_PDF_*` del backend (backup `.env.bak-firma-*`). El certificado de DOBA ya estaba en `PATH_CERT/<ruc>/` con la clave descifrada: no hace falta el PIN. Ojo: el daemon de pm2 se reinició a mitad del pase y lo levantó desde un dump sin el firmador: al agregar un proceso nuevo, `pm2 save` enseguida | prod |
| 18/11/2026 | Imagen de firma y sello (§9): backend, generador y frontend en `feat/firma-imagen-recibos` | local |
| 18/11/2026 | **Test**: §9 desplegado (backend `test/integracion` + migración `20261118120000_empresas_recibo_firma_imagen`, generador `test/integracion`, frontend `test/firma-recibos`). e2e `firma-imagen-recibos.real.spec.js` 5/5 y `firma-recibos.real.spec.js` 2/2 en Kety; con las dos firmas `pdfsig` sigue «Signature is Valid». Kety quedó sin imagen y con la firma digital apagada | test |
| 18/11/2026 | **Producción**: §9 desplegado. Backend fast-forward 07371076 → fb7d17f3 (sin el 0213af3c de Derlis, que estaba en origin/pos sin desplegar), migración `20261118120000_empresas_recibo_firma_imagen` aplicada; generador e4b751f → 2d92aa1 por `git bundle`; frontend 812b567b (= main) por rsync, backup `dist.bak-*`. Nadie tiene imagen cargada: los recibos salen igual hasta que una empresa la suba | prod |
| 18/11/2026 | **Fix**: DOBA subió un PNG con el fondo ya transparente; lo visible era solo la tinta, se la tomó por el papel y la imagen guardada quedó toda transparente (recuadro «Firma y sello» vacío). Ahora `quitarFondo` no toca imágenes que ya traen transparencia, ni sin papel claro dominante, ni cuando el resultado borraría la firma; el recorte de bordes solo corre con fondo transparente; y una imagen que queda sin nada visible se rechaza con mensaje en vez de guardarse. Rama `fix/firma-imagen-transparente` | local |
