diff --git a/docs/oss/signing.md b/docs/oss/signing.md new file mode 100644 index 0000000..c3ca80e --- /dev/null +++ b/docs/oss/signing.md @@ -0,0 +1,84 @@ +# 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.