factuges-document-signing-service/docs/development-secrets.md

Development Secrets & Test Certificates

Este documento describe cómo generar y configurar secretos de prueba para el entorno development del Factuges Document Signing Service.

⚠️ IMPORTANTE Este procedimiento es solo para desarrollo y pruebas internas. NO usar certificados reales ni secretos de producción.

---

Objetivo

En development queremos:

• Probar el flujo completo de firmado de PDFs
• Usar certificados de prueba (autofirmados)
• Almacenar secretos en Infisical
• Mantener el mismo flujo que en producción

La validez legal NO es un objetivo en development.

---

Qué secretos necesita el Signing Service

Para firmar documentos PDF se necesitan exactamente dos secretos:

Secreto	Descripción
PDF_CERT_PFX_B64	Certificado PKCS#12 (.pfx) codificado en base64
PDF_CERT_PASSWORD	Password del certificado

Estos secretos solo existen en Infisical, nunca en el repositorio.

---

1. Generar un certificado de prueba (local)

Usamos un certificado autofirmado, válido técnicamente pero no legalmente.

1.1 Generar clave privada y certificado

openssl req -x509 -newkey rsa:2048 \
  -keyout dev.key \
  -out dev.crt \
  -days 3600 \
  -nodes \
  -subj "/C=ES/O=ACME DEV/CN=ACME DEV TEST CERT"

Esto genera:

• dev.key → clave privada
• dev.crt → certificado autofirmado
• expiración: 3600 días

1.2 Crear el archivo PFX (PKCS#12)

openssl pkcs12 -export \
  -out dev.pfx \
  -inkey dev.key \
  -in dev.crt \
  -password pass:devpassword

Resultado:

• archivo: dev.pfx
• password: devpassword
• ⚠️ Password solo para development

2. Convertir el certificado a base64

base64 dev.pfx > dev.pfx.b64

Comprueba que:

• el archivo no esté vacío
• contiene texto base64 válido

3. Guardar los secretos en Infisical (environment = development)

3.1 Desde la UI de Infisical

• Accede a Infisical Cloud
• Selecciona el Project
• Selecciona el Environment: development
• Ve a Secrets
• Crea los siguientes secretos:

Secreto 1

• Key: PDF_CERT_PFX_B64
• Value: contenido de dev.pfx.b64
• Type: secret

Secreto 2

• Key: PDF_CERT_PASSWORD
• Value: devpassword
• Type: secret

Guarda los cambios.

3.2 (Opcional) Usando Infisical CLI

infisical secrets set PDF_CERT_PFX_B64="$(cat dev.pfx.b64)"
infisical secrets set PDF_CERT_PASSWORD="devpassword"

##4. Configuración local del Signing Service

Ejemplo de .env local:

APP_ENV=development
SECRET_PROVIDER=infisical

INFISICAL_PROJECT_ID=your_project_id
INFISICAL_ENV_SLUG=development
INFISICAL_TOKEN_AUTH=your_dev_token_auth

CERT_SECRET_NAME=certificate_secret_name
CERT_PASSWORD_SECRET_NAME=certificate_password_secret_name

📌 El archivo .env NO debe commitearse.

5. Comprobación manual

• 1. Arranca el Signing Service
• 2. Llama al endpoint de firmado con un PDF de prueba
• 3. Abre el PDF firmado con:
  • Adobe Reader
  • Okular
  • Foxit

Resultado esperado:

• La firma aparece como válida técnicamente
• El visor muestra advertencia:

“El certificado no es de confianza”

✔️ Esto es correcto en development.

6. Casos de prueba recomendados

En development se recomienda probar:

Certificado caducado

• Generar un certificado con -days -1
• Verificar que el servicio bloquea la firma

Password incorrecto

• Cambiar PDF_CERT_PASSWORD
• Verificar error controlado

Certificado eliminado

• Borrar los secretos en Infisical
• Verificar error CERT_NOT_CONFIGURED

Rotación manual

• Reemplazar PDF_CERT_PFX_B64 por otro certificado
• Verificar que el servicio sigue firmando

7. Qué NO hacer nunca

❌ No usar certificados reales ❌ No reutilizar secretos de producción ❌ No commitear .pfx, .key, .crt ❌ No loguear secretos ❌ No compartir tokens de Infisical