Posts

Cómo distribuir una app de macOS fuera de la Mac App Store: firma, DMG y notarización

Arturo Rivas Arias

Publicar una aplicación para macOS en la Mac App Store permite delegar en Apple buena parte de la distribución, pero no siempre encaja con el producto. Algunas aplicaciones necesitan un sistema propio de licencias, actualizaciones independientes, acceso a capacidades que no funcionan bien dentro del sandbox o, sencillamente, venderse desde la web del desarrollador.

Distribuir fuera de la tienda no significa entregar directamente el .app generado por Xcode. Para que macOS pueda identificar al desarrollador, comprobar que el contenido no se ha modificado y evaluar la aplicación con el Gatekeeper, hay que preparar una cadena de confianza completa: firmar el código, activar el Hardened Runtime, notarizar el binario final y adjuntar el ticket emitido por la propia Apple.

Firma, notarización y Gatekeeper no son lo mismo

Aunque estos conceptos aparecen siempre juntos, cada uno responde a una pregunta diferente.

  • La firma de código demuestra qué certificado produjo el binario y permite detectar cualquier modificación posterior.
  • El Hardened Runtime activa protecciones adicionales durante la ejecución y es un requisito para la notarización moderna.
  • La notarización envía el software al servicio de Apple, que realiza comprobaciones automáticas de seguridad y busca problemas habituales de firma o contenido malicioso.
  • El ticket adjunto, conocido habitualmente como stapling, incorpora al propio artefacto la prueba de que Apple lo ha aceptado.
  • Gatekeeper utiliza toda esa información cuando el usuario abre por primera vez una aplicación descargada de Internet.

La notarización no es una revisión editorial como la de la Mac App Store. Apple no evalúa el modelo de negocio, la interfaz ni el contenido de la aplicación. El proceso es automático y está orientado a verificar su integridad y seguridad.

Preparar el proyecto en Xcode

El camino más sencillo comienza en el propio Xcode. En el target de macOS hay que seleccionar el equipo correcto, utilizar firma automática si el proyecto lo permite y añadir la capacidad Hardened Runtime. App Sandbox es opcional para una distribución directa, pero Hardened Runtime no lo es si se pretende notarizar la aplicación.

Algunas aplicaciones necesitan excepciones del runtime ampliadas. Por ejemplo, un motor que genere código durante la ejecución puede requerir com.apple.security.cs.allow-jit. Estas excepciones deben añadirse solo cuando sean imprescindibles: cada entitlement relaja una protección pero amplía la superficie de ataque.

Para crear el binario de distribución se selecciona un destino genérico de macOS y se ejecuta Product > Archive. Desde Organizer, la opción Distribute App > Direct Distribution permite exportar una aplicación firmada con un certificado Developer ID Application y enviarla a notarizar mediante Xcode.

Conviene distinguir este certificado de otros con nombres parecidos:

  • Apple Development sirve para desarrollar y probar.
  • Mac App Distribution está destinado a la Mac App Store.
  • Developer ID Application firma aplicaciones y otros ejecutables distribuidos fuera de la tienda.
  • Developer ID Installer firma paquetes .pkg, pero no es necesario para un .dmg.

La identidad disponible en el llavero puede comprobarse desde Terminal:

security find-identity -v -p codesigning

Verificar el .app antes de empaquetarlo

Un DMG correctamente firmado no corrige una aplicación mal firmada. Antes de crear la imagen de disco hay que validar el paquete exportado y todos sus componentes internos.

Para los siguientes ejemplos utilizaremos una aplicación ficticia llamada FocusBoard:

APP_NAME="FocusBoard"
RELEASE_DIR="$PWD/Release"
APP_PATH="$RELEASE_DIR/${APP_NAME}.app"

codesign --verify --deep --strict --verbose=2 "$APP_PATH"
codesign --display --verbose=4 "$APP_PATH"
spctl --assess --type execute --verbose=4 "$APP_PATH"

codesign --verify comprueba la estructura y la firma de los ejecutables anidados. codesign --display permite inspeccionar la autoridad, el identificador de equipo y la presencia de permisos ampliados de runtime. Finalmente, spctl solicita al Gatekeeper una evaluación similar a la que realizará en el equipo del usuario.

En una exportación válida, la última orden debería mostrar accepted y una procedencia asociada a Developer ID o Notarized Developer ID. El texto exacto puede variar entre versiones de macOS.

El parámetro --deep es útil para verificar, pero no conviene convertir codesign --deep --force en una solución automática para cualquier fallo. Al firmar una aplicación compleja, los frameworks, extensiones, servicios XPC y ejecutables auxiliares deben firmarse desde dentro hacia fuera, conservando los entitlements que correspondan a cada componente. Volver a firmar todo indiscriminadamente puede ocultar el origen del problema o producir un paquete diferente del que Xcode había preparado.

Crear un DMG para la instalación

Una aplicación puede distribuirse dentro de un ZIP, un PKG o un DMG. La imagen de disco es habitual porque permite presentar el icono de la aplicación junto a un acceso directo a /Applications, de forma que la instalación consista en arrastrar un elemento sobre el otro.

Para personalizar el aspecto del instalador se utiliza primero una imagen temporal con permisos de escritura. Después de copiar la aplicación, el enlace a Aplicaciones y, si se desea, una imagen de fondo, se convierte en un DMG comprimido y de solo lectura.

VOLUME_NAME="FocusBoard Installer"
TEMP_DMG="$RELEASE_DIR/FocusBoard-temporal.dmg"
FINAL_DMG="$RELEASE_DIR/FocusBoard.dmg"
MOUNT_DIR="$(mktemp -d /tmp/focusboard-dmg.XXXXXX)"

hdiutil create \
  -size 250m \
  -fs HFS+ \
  -volname "$VOLUME_NAME" \
  -format UDRW \
  "$TEMP_DMG"

hdiutil attach \
  "$TEMP_DMG" \
  -readwrite \
  -noverify \
  -noautoopen \
  -mountpoint "$MOUNT_DIR"

ditto "$APP_PATH" "$MOUNT_DIR/${APP_NAME}.app"
ln -s /Applications "$MOUNT_DIR/Applications"

hdiutil detach "$MOUNT_DIR"

hdiutil convert \
  "$TEMP_DMG" \
  -format UDZO \
  -imagekey zlib-level=9 \
  -o "$FINAL_DMG"

Los 250 MB del ejemplo son solo una reserva para la imagen temporal; hay que ajustarlos al tamaño real de la aplicación. ditto resulta preferible a copiar recursivamente con opciones genéricas porque conserva correctamente la estructura, los enlaces y los atributos del paquete.

Si se quiere añadir un fondo y fijar las posiciones de los iconos, se puede montar la imagen temporal en Finder, guardar la ilustración dentro de una carpeta oculta .background y configurar la vista de iconos. Finder almacenará la presentación en el archivo .DS_Store del volumen. Estas operaciones son puramente visuales y no sustituyen ninguna comprobación de seguridad.

Firmar también la imagen de disco

La aplicación del interior y el DMG son dos artefactos distintos. Aunque el .app ya tenga una firma válida, conviene firmar también la imagen final con Developer ID Application antes de enviarla a Apple.

SIGNING_IDENTITY="Developer ID Application: Example Studio (ABCDE12345)"

codesign \
  --force \
  --timestamp \
  --sign "$SIGNING_IDENTITY" \
  "$FINAL_DMG"

codesign --verify --verbose=2 "$FINAL_DMG"
codesign --display --verbose=4 "$FINAL_DMG"

El nombre completo funciona cuando solo existe una identidad coincidente. En equipos que gestionan varios certificados con el mismo nombre resulta más seguro utilizar el hash SHA-1 mostrado por security find-identity, porque identifica una entrada concreta del llavero.

Cualquier cambio posterior invalida la firma del DMG. Por eso la personalización, la compresión y el nombre definitivo deben estar resueltos antes de firmar y notarizar.

Guardar las credenciales de notarytool

Desde noviembre de 2023, el servicio de notarización ya no acepta envíos realizados con altool. El flujo actual utiliza notarytool, incluido con las herramientas de desarrollo de Xcode.

Para un proceso manual se puede guardar una contraseña específica de aplicación en el llavero. Así el secreto no aparece en los scripts ni en el historial de la shell:

xcrun notarytool store-credentials "FocusBoard-Notary" \
  --apple-id "developer@example.com" \
  --team-id "ABCDE12345" \
  --password "xxxx-xxxx-xxxx-xxxx"

La contraseña de ejemplo debe sustituirse al ejecutar el comando, pero nunca almacenarse en el repositorio. En integración continua suele ser más adecuado autenticarse con una clave de la API de App Store Connect y guardar su contenido, identificador e issuer en el almacén de secretos del proveedor.

Enviar el DMG a notarización

Apple recomienda enviar el mismo contenedor que recibirán los usuarios. En este caso es el DMG final, ya comprimido y firmado:

xcrun notarytool submit "$FINAL_DMG" \
  --keychain-profile "FocusBoard-Notary" \
  --wait

--wait mantiene el proceso activo hasta obtener un estado definitivo. Un resultado correcto termina con status: Accepted. Si Apple rechaza el envío, la respuesta incluye un identificador que permite descargar el registro detallado:

xcrun notarytool log "SUBMISSION_ID" \
  --keychain-profile "FocusBoard-Notary"

Entre los errores más frecuentes se encuentran un framework sin firmar, una firma realizada con el certificado equivocado, la ausencia del Hardened Runtime, un ejecutable anidado después de firmar el contenedor o entitlements que no coinciden con el perfil y las capabilities del proyecto.

No debe intentarse solucionar un rechazo enviando el mismo archivo una y otra vez. El registro indica la ruta exacta del componente problemático y el mensaje de validación; la solución consiste en corregir el proceso de build, generar de nuevo el artefacto y repetir todas las verificaciones locales.

Adjuntar y validar el ticket

Cuando el servicio acepta el DMG, Apple conserva un ticket asociado a su contenido. El Gatekeeper puede consultarlo por Internet, pero adjuntarlo al archivo evita depender de esa conexión durante la primera apertura.

xcrun stapler staple "$FINAL_DMG"
xcrun stapler validate "$FINAL_DMG"

Después se realiza una última evaluación del contenedor completo:

spctl \
  --assess \
  --type open \
  --context context:primary-signature \
  --verbose=4 \
  "$FINAL_DMG"

El resultado esperado es accepted con origen Notarized Developer ID. También conviene montar el DMG final, volver a verificar el .app que contiene y confirmar que puede copiarse a Aplicaciones sin alterar su firma.

Una verificación real necesita la cuarentena de macOS

Las comprobaciones locales son necesarias, pero no reproducen por completo una descarga. El Gatekeeper presta especial atención al atributo de cuarentena que navegadores y otras aplicaciones añaden a los archivos obtenidos de Internet. Si el DMG se abre directamente desde la carpeta de compilación, parte de la experiencia real puede quedar sin probar.

Antes de publicar una versión resulta recomendable subirla a un entorno privado, descargarla mediante un navegador en otro Mac o en una máquina virtual limpia y completar la instalación desde cero. Esa prueba permite detectar certificados ausentes, tickets no adjuntos, diálogos inesperados y fallos que solo aparecen fuera del llavero y del entorno del desarrollador.

También es útil calcular y publicar un hash del archivo definitivo. El hash no reemplaza la firma, pero facilita comprobar que el servidor, la red de distribución o una caché no han entregado un archivo diferente:

shasum -a 256 "$FINAL_DMG"

Automatizar sin perder las comprobaciones

La distribución directa se presta a la automatización, pero el orden forma parte de la seguridad del proceso. Una canalización de entrega debería generar un único candidato de lanzamiento y mover exactamente esos mismos bytes por estas etapas:

  1. Compilar y archivar con configuración Release.
  2. Firmar cada componente con su identidad y sus entitlements correctos.
  3. Verificar la aplicación antes de empaquetarla.
  4. Construir y cerrar el DMG definitivo.
  5. Firmar el DMG.
  6. Enviarlo a notarización y esperar un resultado aceptado.
  7. Adjuntar el ticket.
  8. Ejecutar codesign, stapler y spctl sobre el artefacto que se publicará.
  9. Calcular su hash y subirlo sin volver a modificarlo.

Si cualquiera de los comandos falla, el proceso debe detenerse. Un script puede imponer este comportamiento desde el principio con set -euo pipefail, aunque también debe gestionar explícitamente el desmontaje de imágenes temporales para no dejar volúmenes abiertos después de un error.

El artefacto final es la unidad de confianza

La parte más importante del proceso no es memorizar cada orden, sino entender que la confianza se aplica al archivo exacto que se entrega. Si el DMG cambia después de firmarlo, la firma deja de ser válida. Si se reemplaza la aplicación después de notarizar, el ticket ya no corresponde con el contenido. Si se publica un archivo distinto del que pasó las comprobaciones, toda la cadena pierde su valor.

Una distribución directa sólida trata el DMG aceptado, con su ticket adjunto y sus verificaciones superadas, como un artefacto inmutable. A partir de ese momento solo queda copiarlo al servidor de descargas, publicar su hash y conservarlo junto a la información de la versión. Ese enfoque permite ofrecer una instalación profesional fuera de la Mac App Store sin renunciar a las garantías de seguridad que esperan los usuarios de macOS.