Initial commit: Open sourcing all of the Maple Open Technologies code.

2025-12-02 14:33:08 -05:00 · 2025-12-02 14:33:08 -05:00 · 755d54a99d
commit 755d54a99d
2010 changed files with 448675 additions and 0 deletions
--- a/native/desktop/maplefile/docs/CODE_SIGNING.md
+++ b/native/desktop/maplefile/docs/CODE_SIGNING.md
@ -0,0 +1,234 @@
+# Code Signing Guide for MapleFile Desktop
+
+This document outlines the code signing requirements and procedures for MapleFile desktop application releases.
+
+## Why Code Signing is Important
+
+Code signing provides:
+1. **Integrity Verification**: Ensures the binary hasn't been tampered with since signing
+2. **Publisher Authentication**: Confirms the software comes from MapleFile/Maple Open Technologies
+3. **User Trust**: Operating systems trust signed applications more readily
+4. **Malware Protection**: Unsigned apps trigger security warnings that users may ignore
+
+## Platform Requirements
+
+### macOS
+
+**Certificate Types:**
+- **Developer ID Application**: Required for distribution outside the Mac App Store
+- **Developer ID Installer**: Required for signed `.pkg` installers
+
+**Requirements:**
+1. Apple Developer Program membership ($99/year)
+2. Developer ID certificates from Apple Developer portal
+3. Notarization through Apple's notary service
+
+**Signing Process:**
+```bash
+# Sign the application
+codesign --force --options runtime --sign "Developer ID Application: Your Name (TEAM_ID)" \
+    --timestamp MapleFile.app
+
+# Create a signed DMG
+hdiutil create -volname "MapleFile" -srcfolder MapleFile.app -ov -format UDZO MapleFile.dmg
+codesign --sign "Developer ID Application: Your Name (TEAM_ID)" MapleFile.dmg
+
+# Notarize (required for macOS 10.15+)
+xcrun notarytool submit MapleFile.dmg --apple-id your@email.com --team-id TEAM_ID --wait
+xcrun stapler staple MapleFile.dmg
+```
+
+**Wails Build Integration:**
+```bash
+# Wails supports code signing via environment variables
+export MACOS_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAM_ID)"
+export MACOS_NOTARIZATION_TEAM_ID="TEAM_ID"
+export MACOS_NOTARIZATION_APPLE_ID="your@email.com"
+export MACOS_NOTARIZATION_PASSWORD="@keychain:AC_PASSWORD"
+
+wails build -platform darwin/universal
+```
+
+### Windows
+
+**Certificate Types:**
+- **EV Code Signing Certificate**: Extended Validation - highest trust, required for SmartScreen reputation
+- **Standard Code Signing Certificate**: Basic signing, builds reputation over time
+
+**Requirements:**
+1. Code signing certificate from a trusted CA (DigiCert, Sectigo, GlobalSign, etc.)
+2. Hardware token (required for EV certificates)
+3. SignTool from Windows SDK
+
+**Signing Process:**
+```powershell
+# Sign with timestamp (important for validity after certificate expiry)
+signtool sign /tr http://timestamp.digicert.com /td sha256 /fd sha256 ^
+    /a /n "Maple Open Technologies" MapleFile.exe
+
+# Verify signature
+signtool verify /pa /v MapleFile.exe
+```
+
+**Wails Build Integration:**
+```powershell
+# Set environment variables before build
+$env:WINDOWS_SIGNING_CERTIFICATE = "path/to/certificate.pfx"
+$env:WINDOWS_SIGNING_PASSWORD = "certificate_password"
+
+wails build -platform windows/amd64
+```
+
+### Linux
+
+Linux doesn't have a universal code signing requirement, but you can:
+
+1. **GPG Signing**: Sign release artifacts with GPG
+   ```bash
+   gpg --armor --detach-sign MapleFile.tar.gz
+   ```
+
+2. **AppImage Signing**: Sign AppImage files
+   ```bash
+   # Import your signing key
+   ./appimagetool --sign MapleFile.AppImage
+   ```
+
+3. **Package Signatures**: Use distribution-specific signing
+   - `.deb`: `dpkg-sig --sign builder package.deb`
+   - `.rpm`: `rpm --addsign package.rpm`
+
+## Secure Update Mechanism
+
+### Current State
+MapleFile currently does not include automatic updates.
+
+### Recommended Implementation
+
+1. **Update Server**: Host update manifests with signed checksums
+2. **Version Checking**: Application checks for updates on startup (optional)
+3. **Download Verification**: Verify signature before applying update
+4. **Rollback Support**: Keep previous version for rollback on failure
+
+**Update Manifest Format:**
+```json
+{
+  "version": "1.2.3",
+  "release_date": "2025-01-15",
+  "platforms": {
+    "darwin-arm64": {
+      "url": "https://releases.maplefile.com/v1.2.3/MapleFile-darwin-arm64.dmg",
+      "sha256": "abc123...",
+      "signature": "base64-encoded-signature"
+    },
+    "darwin-amd64": {
+      "url": "https://releases.maplefile.com/v1.2.3/MapleFile-darwin-amd64.dmg",
+      "sha256": "def456...",
+      "signature": "base64-encoded-signature"
+    },
+    "windows-amd64": {
+      "url": "https://releases.maplefile.com/v1.2.3/MapleFile-windows-amd64.exe",
+      "sha256": "ghi789...",
+      "signature": "base64-encoded-signature"
+    }
+  }
+}
+```
+
+**Verification Process:**
+```go
+// Pseudocode for update verification
+func verifyUpdate(downloadPath, expectedSHA256, signature string) error {
+    // 1. Verify SHA256 hash
+    actualHash := sha256sum(downloadPath)
+    if actualHash != expectedSHA256 {
+        return errors.New("hash mismatch")
+    }
+
+    // 2. Verify signature (using embedded public key)
+    if !verifySignature(downloadPath, signature, publicKey) {
+        return errors.New("signature verification failed")
+    }
+
+    return nil
+}
+```
+
+## Certificate Management
+
+### Storage
+- **Never** commit private keys to version control
+- Store certificates in secure vault (e.g., HashiCorp Vault, AWS Secrets Manager)
+- Use CI/CD secrets for automated builds
+
+### Rotation
+- Set calendar reminders for certificate expiry (typically 1-3 years)
+- Plan for certificate rotation before expiry
+- Test signing process after certificate renewal
+
+### Revocation
+- Maintain list of compromised certificates
+- Have incident response plan for key compromise
+- Document process for certificate revocation
+
+## Build Pipeline Integration
+
+### GitHub Actions Example
+```yaml
+name: Release Build
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Import Code Signing Certificate
+        env:
+          CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE }}
+          CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+        run: |
+          echo $CERTIFICATE_BASE64 | base64 --decode > certificate.p12
+          security create-keychain -p "" build.keychain
+          security import certificate.p12 -k build.keychain -P "$CERTIFICATE_PASSWORD" -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "" build.keychain
+
+      - name: Build and Sign
+        env:
+          MACOS_SIGNING_IDENTITY: ${{ secrets.MACOS_SIGNING_IDENTITY }}
+        run: |
+          wails build -platform darwin/universal
+          # Notarize here...
+```
+
+## Verification Commands
+
+### macOS
+```bash
+# Check signature
+codesign -dvv MapleFile.app
+
+# Verify notarization
+spctl -a -vv MapleFile.app
+```
+
+### Windows
+```powershell
+# Check signature
+signtool verify /pa /v MapleFile.exe
+
+# PowerShell alternative
+Get-AuthenticodeSignature MapleFile.exe
+```
+
+## References
+
+- [Apple Developer Code Signing](https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution)
+- [Microsoft Authenticode](https://docs.microsoft.com/en-us/windows/win32/seccrypto/cryptography-tools)
+- [Wails Build Documentation](https://wails.io/docs/guides/signing)
+- [OWASP Code Signing Guidelines](https://cheatsheetseries.owasp.org/cheatsheets/Code_Signing_Cheat_Sheet.html)