Firma de Codigo y Notarizacion

Esta guia explica como preparar releases de escritorio confiables para Windows y macOS.

Objetivo:

• Instalador de Windows firmado con un certificado valido.
• App de macOS firmada y notarizada con Apple Developer ID.
• Artefactos de release publicados con checksums y trazabilidad del build.

Integracion Actual en CI

La automatizacion de release de KuaDashboard esta en .github/workflows/electron-build.yml y usa:

• CSC_LINK / CSC_KEY_PASSWORD para firma en Windows.
• APPLE_TEAM_ID / APPLE_API_KEY / APPLE_API_KEY_ID / APPLE_API_ISSUER para notarizacion en macOS.

La configuracion de Electron esta en package.json, y la notarizacion se ejecuta en electron/notarize.js.

Windows: Generar y Exportar Certificado

Usa un certificado de firma de codigo emitido por una CA (OV o EV).

Importante:

• EV normalmente acelera la reputacion de SmartScreen.
• OV funciona correctamente, pero SmartScreen puede tardar mas en confiar.

1. Recibir certificado de la CA

Sigue el proceso de tu CA (DigiCert, Sectigo, GlobalSign, etc.) e instala el certificado en el almacén de certificados de Windows o importa el archivo .pfx entregado.

2. Exportar PFX (si aplica)

Si tu certificado esta instalado en Windows Certificate Store:

1. Abre certmgr.msc.
2. Ve a Personal -> Certificates.
3. Busca tu certificado de code signing.
4. Click derecho -> All Tasks -> Export.
5. Elige Yes, export the private key.
6. Elige Personal Information Exchange - PKCS #12 (.PFX).
7. Define una contraseña robusta.
8. Guarda el archivo, por ejemplo: kuadashboard-codesign.pfx.

3. Convertir PFX a base64 para GitHub Secret

PowerShell:

[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\kuadashboard-codesign.pfx")) | Set-Content -NoNewline .\codesign-pfx-base64.txt

Usa el contenido de codesign-pfx-base64.txt como valor de CSC_LINK.

Define CSC_KEY_PASSWORD con la contraseña del PFX.

macOS: Preparar Firma y Notarizacion

Requisitos:

• Membresia activa en Apple Developer Program.
• Certificado Developer ID Application.
• API key de App Store Connect para notarizacion.

Estos pasos se hacen desde tu Mac.

1. Crear o importar certificado Developer ID

En Keychain Access:

1. Importa tu certificado Developer ID Application.
2. Verifica que la clave privada aparezca bajo el certificado.

2. Exportar certificado como P12

1. Abre Keychain Access.
2. Selecciona el certificado Developer ID Application y su clave privada.
3. Click derecho -> Export 2 items....
4. Guarda como .p12 y define una contraseña de exportacion.

3. Convertir P12 a base64 para CI

En terminal macOS:

base64 -i kuadashboard-developer-id.p12 | tr -d '\n' > apple-cert-base64.txt

Puedes usar este valor como CSC_LINK en GitHub Secrets si tu workflow firma macOS con la misma variable.

Nota:

• Si Windows y macOS usan materiales distintos de certificado, separa secretos por plataforma o por environment/workflow.

4. Crear API key de App Store Connect

En App Store Connect:

1. Users and Access -> Keys.
2. Crea una API key nueva.
3. Descarga el archivo .p8 (solo una vez).
4. Guarda:
   • Key ID
   • Issuer ID
   • Team ID (de tu cuenta Apple).

5. Preparar GitHub secrets para notarizacion

Define:

• APPLE_API_KEY = contenido completo del .p8 (texto crudo incluyendo BEGIN/END).
• APPLE_API_KEY_ID = key ID.
• APPLE_API_ISSUER = issuer ID.
• APPLE_TEAM_ID = Apple Team ID.

Configuracion de Secrets en GitHub

En GitHub -> Settings -> Secrets and variables -> Actions, agrega:

• CSC_LINK
• CSC_KEY_PASSWORD
• APPLE_TEAM_ID
• APPLE_API_KEY
• APPLE_API_KEY_ID
• APPLE_API_ISSUER

Recomendado:

• Usar secrets por environment (por ejemplo production) con aprobacion requerida.
• Ejecutar releases solo desde tags protegidos.

Checklist de Validacion de Release

Antes de crear tag:

1. Verificar certificados vigentes (sin expiracion).
2. Verificar que todos los secrets requeridos existen.
3. Probar un release con tag temporal.
4. Verificar firmas:
   • Windows: validar firmante en propiedades del .exe.
   • macOS: ejecutar codesign --verify --deep --strict --verbose=2 /Applications/KuaDashboard.app.
   • macOS: ejecutar spctl -a -vv /Applications/KuaDashboard.app.
5. Confirmar que SHA256SUMS.txt esta adjunto al release.
6. Confirmar que la atestacion del build esta disponible.

Troubleshooting

SmartScreen sigue mostrando advertencia en Windows

Posibles causas:

• El certificado es valido, pero la reputacion de SmartScreen aun esta calentando.
• Cambio de nombre de producto o publisher entre versiones.
• El binario fue modificado despues de firmar.

La app de macOS no abre despues de instalar

Posibles causas:

• La notarizacion no corrio por falta de secretos Apple.
• Certificado o API key de otro Team.
• El artefacto fue modificado/re-empaquetado luego de firma/notarizacion.

GitHub Action marca secret context invalid

El editor puede advertir esto cuando no encuentra metadata local de secretos. No bloquea la ejecucion real si los secrets existen en el repositorio.