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

```bash
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)

```bash
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

```bash
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

```bash
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:

```bash
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