bitwarden · iinuwa · Jan 12, 2026
@@ -44,18 +44,23 @@ LDIF
 libmagic
 LLDB
 Mailcatcher
+makemsix
 minio
+msix
+MSVC
 MVVM
 NGRX
 OIDCS
 Omnisharp
 onboarded
 opid
+osslsigncode
 OTLP
 owasp
 passcode
 passwordless
 pinentry
+PKCS12
 PNSs
 POSIX
 precompiler
@@ -93,6 +98,7 @@ WCAG
 Xcodes.app
 xcworkspace
 xmldoc
+xwin
 Yellowpages
 Yubico
 YubiKey

@@ -68,7 +68,7 @@ npm run build
 #### Windows on ARM
 
 If you're building in Windows on ARM, you might need to run `build.js` with the `cross-platform`
-argument:
+argument to build both arm64 and x64 native binaries:
 
 ```bash
 node desktop_native/build.js cross-platform
@@ -91,6 +91,74 @@ export PKG_CONFIG_ALLOW_CROSS=1
 npm run build -- --target x86_64-unknown-linux-musl # Replace with relevant target
 ```
 
+#### Targeting Windows Appx from macOS
+
+The Windows Appx can be built from macOS[^1]. This can be helpful if you have a macOS development
+machine and an underpowered Windows test machine, like a VM or test laptop.
+
+(Note: If you are using a Windows VM on macOS with Apple Silicon, we recommend using [UTM][utm] with
+a [Windows 11 arm64][win11-arm64] build for the best performance.)
+
+##### Prerequisites
+
+- PowerShell 7.x: Build scripts
+- makemsix from [microsoft/msix-packaging][msix-packaging]: Packages the file in an Appx
+- [osslsigncode][]: Produces signatures in the Appx format using OpenSSL.
+- [cargo-xwin][]: Used to cross-compile native binaries for the Windows MSVC target.
+
+You can install these with the following script:
+
+```shell
+brew install powershell iinuwa/msix-packaging-tap/msix-packaging osslsigncode
+cargo install --version 0.20.2 --locked cargo-xwin
+```
+
+Our build scripts will also automatically attempt to install these utilities when cross-compiling to
+Windows from macOS.
+
+Before building the first time, you must generate a signing certificate and set up your test machine
+to trust it. See the setup instructions in the [Microsoft Store docs][ms-store-docs] for more
+information.
+
+After that, you can build the Appx from macOS using the steps below.
+
+##### Cross-compiling Appx
+
+```sh
+cd apps/desktop
+export CERTIFICATE_PASSWORD="<password>"
+./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath "<path to signing cert>.pfx"
+```
+
+Once complete, you can copy the Appx file from `apps/desktop/dist/Bitwarden-<version>.appx` to your
+Windows test machine and install it there.
+
+Use PowerShell's help system to get more information about the script arguments:
+
+```powershell
+Get-Help ./scripts/appx-cross-build.ps1 -Full
+```
+
+[^1]:
+    <p>
+      Linux is not currently supported for cross-compilation of the Appx. It could work by using the
+      same instructions as for macOS listed above, but we are not aware of a packaged version of
+      `msix-packaging` tools required for building the Appx.
+    </p>
+    <p>
+      Contributions to the documentation on how to build this package for Linux are welcome.
+      Alternatively, you can consider contributing to the third party Homebrew tap to add Linux
+      support at [`iinuwa/msix-packaging-tap/msix-packaging`][msix-packaging-tap].
+    </p>
+
+[cargo-xwin]: https://github.com/rust-cross/cargo-xwin
+[ms-store-docs]: /getting-started/clients/desktop/microsoft-store#macos
+[msix-packaging]: https://github.com/microsoft/msix-packaging
+[msix-packaging-tap]: https://github.com/iinuwa/homebrew-msix-packaging-tap/
+[osslsigncode]: https://github.com/mtrojnar/osslsigncode
+[utm]: https://getutm.app/
+[win11-arm64]: https://www.microsoft.com/en-us/software-download/windows11arm64
+
 ## Build instructions
 
 Build and run:

@@ -5,29 +5,149 @@ sidebar_custom_props:
 
 # Microsoft Store
 
-To debug the Microsoft Store application you need to generate a Code Signing certificate which can
-be done using the following powershell command:
+The Microsoft Store application is packaged as an Appx file. To test the Appx, you must have a
+Windows 10+ machine, but you may have a separate development machine with a different OS.
+
+## Development Machine Setup
+
+The instructions differ based on the OS of your development machine. Regardless of OS, you must
+generate a PKCS12 signing certificate whose subject matches the publisher in the Electron Builder
+configuration, found in `./apps/desktop/electron-builder.json`.
+
+### Windows
+
+#### Prerequisites
+
+- [Windows SDK][sdk]: includes the required `signtool` binary for signing the Appx.
+
+[sdk]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
+
+#### Generating Certificate
+
+On Windows, you can generate the signing certificate using PowerShell.
 
 ```powershell
-New-SelfSignedCertificate -Type Custom `
-  -Subject "CN=ElectronSign, 0=Your Corporation, C=US" `
-  -TextExtension @("2.5.29.19={text}false") `
+$certPath = "<File Path>.pfx"
+
+$publisher = "CN=Bitwarden Inc., O=Bitwarden Inc., L=Santa Barbara, S=California, C=US, SERIALNUMBER=7654941, OID.2.5.4.15=Private Organization, OID.1.3.6.1.4.1.311.60.2.1.2=Delaware, OID.1.3.6.1.4.1.311.60.2.1.3=US"
+$certificate = New-SelfSignedCertificate -Type Custom `
+  -Subject $publisher `
   -KeyUsage DigitalSignature `
   -TextExtension @("2.5.29.37={text}1.3.6.1.5.5.7.3.3", "2.5.29.19={text}") `
-  -FriendlyName ElectronSign `
+  -FriendlyName "Bitwarden Local Developer Signing Certificate" `
   -CertStoreLocation "Cert:\CurrentUser\My"
+# Export this certificate to a file so you can configure the machine to trust
+# Appx applications signed with it, and optionally sign the Appx on another
+# machine.
+$password = Read-Host -AsSecureString
+Export-PfxCertificate -cert "Cert:\CurrentUser\My\${$cert.Thumbprint}" -FilePath $certPath -Password $password
 ```
 
-The generated certificate needs to be copied into to `Cert:\CurrentUser\Trusted People`, which tells
-the OS to trust the certificate. This is easiest done using the `certmgr` tool.
+See [Microsoft's documentation][ms-appx-cert-docs] for more information.
+
+After generating the signing certificate, make sure you follow the [steps below to trust the
+certificate][trust-docs] on your test machine.
+
+[ms-appx-cert-docs]:
+  https://learn.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing
+[trust-docs]: #trusting-the-certificate
 
-The [Windows SDK][sdk] is required in order to access the signtool.
+#### Signing Appx
+
+On Windows, our build scripts will automatically sign the Appx file when packaging the appx if you
+set the following environment variables:
+
+```powershell
+$env:ELECTRON_BUILDER_SIGN_CERT = "<path to cert>.pfx"
+$env:ELECTRON_BUILDER_SIGN_CERT_PW = "<cert password>"
+cd apps/desktop/
+npm run dist:win
+```
+
+You can also manually sign the Appx using `signtool` directly.
 
 ```powershell
 npm run dist:win
 
 cd dist
-"C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe" sign /v /fd sha256 /n "14D52771-DE3C-4886-B8BF-825BA7690418" .\Bitwarden-2022.<version>.appx
+"C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\signtool.exe" sign /v /fd sha256 /n "CN=Bitwarden Inc., O=Bitwarden Inc., L=Santa Barbara, S=California, C=US, SERIALNUMBER=7654941, OID.2.5.4.15=Private Organization, OID.1.3.6.1.4.1.311.60.2.1.2=Delaware, OID.1.3.6.1.4.1.311.60.2.1.3=US" .\Bitwarden-<version>.appx
 ```
 
-[sdk]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
+### macOS
+
+#### Prerequisites
+
+See the prerequisites for [cross-compiling][cross-compile-docs] the Windows Appx.
+
+[cross-compile-docs]: /getting-started/clients/desktop/#cross-compile
+
+#### Generating a Signing Certificate
+
+If you are building the Appx using a non-Windows machine, you can generate a certificate on Windows
+and copy it to your development machine, or you can use OpenSSL to generate the signing certificate:
+
+```shell
+pkcs="<file path>.pfx"
+
+publisher="/jurisdictionCountryName=US/jurisdictionStateOrProvinceName=Delaware/businessCategory=Private Organization/serialNumber=7654941/C=US/ST=California/L=Santa Barbara/O=Bitwarden Inc./CN=Bitwarden Inc."
+key=$(mktemp)
+cert=$(mktemp)
+openssl req -x509 -newkey rsa:2048 -days 3650 -nodes \
+  -addext 'keyUsage=critical,digitalSignature' \
+  -addext 'extendedKeyUsage=critical,codeSigning' \
+  -addext 'basicConstraints=critical,CA:FALSE' \
+  -subj "$publisher" -keyout $key -out $cert
+openssl pkcs12 -inkey $key -in $cert -export -out $pkcs
+# clean up temp files
+rm "$key" "$cert"
+```
+
+After generating the signing certificate, make sure you follow the [steps below to trust the
+certificate][trust-docs] on your test machine.
+
+#### Signing the Appx
+
+On macOS, the `apps/desktop/scripts/appx-cross-build.ps1` script will sign the Appx when the
+`-CertificatePath` and `-CertificatePassword` arguments are passed:
+
+```powershell
+cd apps/desktop
+./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath ~/Development/code-signing.pfx -CertificatePassword (Read-Host -AsSecureString)
+```
+
+You can alternatively specify the certificate password using the `CERTIFICATE_PASSWORD` environment
+variable, which allows using a shell besides PowerShell to invoke the request:
+
+```sh
+cd apps/desktop
+export CERTIFICATE_PASSWORD="<password>"
+./scripts/appx-cross-build.ps1 -Architecture arm64 -CertificatePath "<path to signing cert>.pfx"
+```
+
+### Linux
+
+Linux is not currently supported for cross-platform Appx signing. See the [footnote in the
+cross-compiling docs][cross-compile-footnotes] for how we can support this in the future.
+
+[cross-compile-footnotes]: /getting-started/clients/desktop/#footnote-label
+[msix-packaging-tap]: https://github.com/iinuwa/homebrew-msix-packaging-tap/
+
+## Test Machine Setup
+
+### Prerequisites
+
+The only requirement for running the Microsoft Store application on the test machine is Windows 10+,
+although Windows 11 is recommended for testing all features.
+
+### Trusting the certificate
+
+The generated certificate needs to be copied onto the test machine and imported into to
+`Cert:\CurrentUser\Trusted People`, which tells the OS to trust the certificate. You can do this
+with a PowerShell command:
+
+```powershell
+$password = Read-Host -AsSecureString
+Import-PfxCertificate -CertStoreLocation "Cert:\LocalMachine\TrustedPeople" -Password $password -FilePath <FilePath>.pfx
+```
+
+You only need to do this the first time you use a certificate.