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

85 lines
4.3 KiB
Markdown

# 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.