Files
waggle-os/docs/oss/signing.md
shumeiko.it 9806afbced docs(oss): propose how to sign the installers (P2.5)
Developer ID and notarization on macOS (including the bundled node and
native libraries), the owner's existing Azure Artifact Signing on Windows
with SignPath Foundation or a CA certificate as alternatives, and signed
checksums on Linux. Lists the decisions the owner has to make.
2026-11-01 01:39:49 +01:00

4.3 KiB

Signing the community edition installers (P2.5)

A proposal for the project owner. Nothing here is set up yet: the release workflow builds unsigned installers, and signing needs accounts that only the owner can open.

What happens without signing

System What the user sees Workaround we document
Windows SmartScreen: "Windows protected your PC" More info → Run anyway
macOS Gatekeeper: the app "cannot be opened because the developer cannot be verified" Right-click → Open, or xattr -dr com.apple.quarantine /Applications/Waggle.app
Linux Nothing blocks the install Compare the file with SHA256SUMS

The server archive is already protected in transit: the installer refuses an archive whose SHA-256 does not match the .sha256 published next to it (ADR-0009). That proves the file was not damaged or swapped on the way, but not who built it, which is what signing adds.

Proposal per system

macOS: Developer ID and notarization

  • Account: an Apple Developer Program membership in the owner's company name. An organization account needs a D-U-N-S number.
  • What it signs: the app bundle with a Developer ID Application certificate and the hardened runtime, then Apple notarizes the DMG and the ticket is stapled to it.
  • Work on our side: notarization rejects any unsigned Mach-O file inside the bundle. Contents/Resources/resources holds the bundled node, the .node addons and the onnxruntime and libvips dylibs, so a signing step before tauri build must sign each of them with the same identity. Tauri then signs the app and runs notarization when these CI secrets are set: APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD, APPLE_SIGNING_IDENTITY, APPLE_API_ISSUER, APPLE_API_KEY and the API key file.
  • The server archive for macOS should carry the same signed node and libraries, so a quarantined download does not block them either.

Windows: reuse the owner's existing signing service

The commercial release pipeline signed Windows builds with Microsoft's Azure Artifact Signing (formerly Trusted Signing; Microsoft.ArtifactSigning.Client in the old release.yml). If the owner keeps that account, the simplest path is to sign the community edition with it as well: the publisher shown to users stays the owner's company, and no new identity check is needed.

Alternatives, if that account cannot be used for an open-source release:

  • SignPath Foundation: free signing for open-source projects that meet its rules (an OSI license, a public repository, a reproducible build in public CI). The certificate belongs to SignPath Foundation, so Windows shows it, not the owner, as the publisher.
  • A certificate from a public CA (OV or EV), kept on a hardware token or a cloud HSM.

Whatever the certificate, SmartScreen builds reputation per publisher over downloads, so the first releases can still show a warning for a while.

What to sign: the NSIS and MSI installers, the Waggle.exe inside them, and the bundled node.exe and .node addons in the server archive.

Linux: signed checksums

Linux packages are not signed by default. We propose signing the release's SHA256SUMS file:

  • Keyless with Sigstore (cosign) in GitHub Actions: no key to store; the signature binds the file to the workflow run that produced it. This needs the repository on GitHub (Q9).
  • Or a GPG key held by the owner, with the public key published in the repository.

A signed apt repository can come later, if the owner wants apt install instead of a downloaded .deb.

npm package of the installer

When the installer package is published to npm, publish it with provenance (npm publish --provenance from GitHub Actions), so npm shows which workflow built it.

Not needed for v1

The Tauri auto-updater needs its own signing key pair (TAURI_SIGNING_PRIVATE_KEY). The updater is disabled in v1, so this key is not needed yet.

Decisions for the owner

  1. Who owns the signing accounts: the owner's company (recommended), or a new open-source entity.
  2. Windows: reuse the existing Azure Artifact Signing, or SignPath Foundation, or a CA certificate.
  3. Whether the first release may ship unsigned, with the workarounds above in the install guide.

Once the accounts exist, the release workflow gets one signing step per system and the secrets listed above. The build steps do not change.