Upgrade to Sparkle 2 with EdDSA signing and restore auto-updates

[schuyler]

Overview

MacDown's auto-update system is currently using obsolete Sparkle 1.18.1 with deprecated DSA signing. The appcast feeds are returning 503 errors, making auto-updates non-functional. With the new macdown.app domain and access to an Apple Developer account, we can restore auto-updates using modern Sparkle 2.

Current State

Sparkle Version: 1.18.1 (via CocoaPods)
Signing: DSA (deprecated, scheduled for removal)
Appcast URLs:

• Stable: https://macdown.app/sparkle/macdown3000/stable/appcast.xml (503)
• Beta: https://macdown.app/sparkle/macdown3000/testing/appcast.xml (503)

Code: Using deprecated SUUpdater API in MPMainController.m

Required Changes

1. Upgrade Sparkle Framework

• Update Podfile: pod 'Sparkle', '~> 2.0'
• Run bundle exec pod install
• Minimum macOS requirement will increase to 10.11+

2. Migrate Code to Sparkle 2 API

• Replace #import <Sparkle/SUUpdater.h> with #import <Sparkle/SPUStandardUpdaterController.h>
• Update MPMainController.m to use new SPUStandardUpdaterController class
• Remove singleton pattern usage
• Update delegate methods for Sparkle 2

3. Generate EdDSA Signing Keys

• Use Sparkle's tooling to generate new EdDSA (ed25519) keypair
• Store private key securely (offline, NOT in repository)
• Add public key to Info.plist

4. Update Info.plist

• Remove: SUPublicDSAKeyFile and dsa_pub.pem reference
• Add: SUPublicEDKey with new EdDSA public key
• Update appcast URLs if needed

5. Remove DSA Key File

• Delete MacDown/Resources/dsa_pub.pem

6. Set Up Appcast Hosting

• Host appcast.xml files at macdown.app (HTTPS required)
• Use generate_appcast tool for creating signed appcasts
• Document release workflow

Resources

• Sparkle 2 Documentation
• Upgrading from Sparkle 1
• EdDSA Migration Guide

Benefits

• Modern, maintained update framework
• Improved security with EdDSA signing
• Functional auto-updates for users
• Proper code signing with Developer account

Dependencies

• Apple Developer account (available)
• macdown.app domain control (available)
• HTTPS hosting setup for appcast files

[schuyler]

Implementation Plan - Updated with GHA Automation

After consultation with Groucho (architecture agent), here's the complete implementation plan with fully automated appcast generation in GitHub Actions.

---

Key Decisions

1. Sparkle Version: Upgrade to Sparkle 2.6+
2. macOS Minimum: Update from 10.8 → 10.13 (High Sierra)
3. Setup Pattern: Programmatic SPUStandardUpdaterController (remove XIB-based SUUpdater)
4. Feed Switching: Keep existing delegate method (minimal changes needed)
5. Signing: EdDSA with automated appcast generation in CI
6. Release Workflow: Fully automated - tag, push, done!

---

Files to Modify

Code Changes

1. Podfile

• Update: pod 'Sparkle', '~> 2.6' (from ~> 1.18)
• Update: platform :osx, "10.13" (from 10.8)

2. MacDown-Info.plist

• Remove: SUPublicDSAKeyFile and dsa_pub.pem reference
• Add: SUPublicEDKey with EdDSA public key (base64)
• Keep: SUFeedURL and SUBetaFeedURL unchanged

3. MPMainController.h

• Add import: <Sparkle/SPUStandardUpdaterController.h>
• Add property: SPUStandardUpdaterController *updaterController
• Add protocol: <SPUUpdaterDelegate>

4. MPMainController.m

• Replace import: SUUpdater.h → SPUStandardUpdaterController.h
• Initialize updater programmatically in -init
• Update delegate method parameter: SUUpdater * → SPUUpdater *
• Add: -checkForUpdates: IBAction method

5. MainMenu.xib

• Remove: SUUpdater custom object
• Update: "Check for Updates" menu item target → First Responder

6. Delete: MacDown/Resources/dsa_pub.pem

7. Create: MacDownTests/MPUpdaterTests.m (unit tests)

Workflow Changes

8. .github/workflows/release.yml

• Add 7 new steps for appcast automation (after checksums, before notarization)
• Update cleanup step to remove Sparkle secrets

Documentation Changes

9. plans/release-process.md

• Add EdDSA key generation instructions
• Add SSH deployment setup
• Add appcast automation documentation
• Add testing procedures

---

GitHub Actions Automation

New Workflow Steps

The release workflow will automatically:

1. ✅ Determine channel (stable vs testing based on version tag)
2. ✅ Validate secrets (ensure all Sparkle secrets are configured)
3. ✅ Download generate_appcast tool from Sparkle releases
4. ✅ Download existing appcast from server (preserves history)
5. ✅ Generate new appcast with EdDSA signature
6. ✅ Upload appcast to macdown.app via SSH (with retry logic)
7. ✅ Cleanup secrets (remove all temporary keys)

Required GitHub Secrets

Add these 5 secrets to repository settings:

Secret Name	Description	Example
SPARKLE_EDDSA_PRIVATE_KEY	EdDSA private key for signing	PEM format (multiline)
MACDOWN_SSH_PRIVATE_KEY	SSH key for deployment	PEM format (multiline)
MACDOWN_SSH_HOST	Server hostname	macdown.app
MACDOWN_SSH_USER	SSH username	deploy
MACDOWN_SSH_PATH	Base path on server	/var/www/sparkle/macdown3000

Channel Detection Logic

# Automatic channel detection from version tag:
v1.0.0         → stable
v1.0.0-beta.1  → testing
v1.0.0-alpha   → testing
v1.0.0-rc.2    → testing

---

Implementation Phases

Phase 1: Preparation (Do First)

1. Generate EdDSA key pair (locally, one-time)

   curl -L https://github.com/sparkle-project/Sparkle/releases/latest/download/generate_appcast.tar.xz | tar -xJ
   ./generate_appcast --generate-keys
   # Creates: eddsa_private.pem, eddsa_public.pem

2. Generate SSH deployment key

   ssh-keygen -t ed25519 -C "macdown-deploy" -f macdown_deploy_key
   # Add macdown_deploy_key.pub to server's ~/.ssh/authorized_keys

3. Configure server

   • Create directories: /var/www/sparkle/macdown3000/{stable,testing}/
   • Set permissions for deploy user
   • Configure web server to serve appcast.xml

4. Add secrets to GitHub

   • All 5 secrets listed above

Phase 2: Code Migration

5. Update Podfile and run bundle exec pod install
6. Update Info.plist with SUPublicEDKey
7. Delete dsa_pub.pem
8. Update MPMainController (header + implementation)
9. Update MainMenu.xib
10. Write unit tests

Phase 3: Workflow Integration

11. Add 7 new steps to .github/workflows/release.yml
12. Update cleanup step
13. Update release-process.md documentation

Phase 4: Testing

14. Create test release: v0.1.0-beta.1
15. Push tag to trigger workflow
16. Monitor GitHub Actions execution
17. Verify appcast uploaded to testing channel
18. Validate appcast XML
19. Test Sparkle update detection in app

Phase 5: Production

20. Create stable release: v1.0.0
21. Verify workflow success
22. Verify appcast uploaded to stable channel
23. Test auto-updates with real app

---

Workflow Integration Details

Exact Placement in release.yml

Insert location: After "Generate checksums" step (line ~250), before "Submit DMG for notarization"

Why this placement?

• DMG must exist for appcast generation
• Appcast generation is fast (~30 seconds)
• Notarization is async and doesn't block
• If appcast fails, release won't be created
• Keeps workflow atomic

Complete Step List

# 1. Determine appcast channel (stable vs testing)
# 2. Validate Sparkle secrets (fail fast if missing)
# 3. Download generate_appcast tool
# 4. Download existing appcast from server (preserve history)
# 5. Generate Sparkle appcast with EdDSA signature
# 6. Upload appcast to hosting (with retry logic)
# 7. Cleanup Sparkle secrets

Error Handling

• ✅ Secret validation (fail fast if missing)
• ✅ DMG verification before appcast generation
• ✅ SSH connection with retry (4 attempts, exponential backoff)
• ✅ Comprehensive error messages
• ✅ Automatic cleanup even on failure
• ✅ Workflow fails if appcast upload fails (critical feature)

---

Security Considerations

1. Private keys stored as GitHub encrypted secrets
2. Temporary files (keys) deleted in cleanup step (even on failure)
3. SSH known_hosts verification to prevent MITM
4. File permissions (chmod 600 on keys)
5. Separate keys for EdDSA signing vs SSH deployment
6. Server SSH key restricted to only appcast upload path

---

Testing Strategy

Unit Tests

• Updater controller initialization
• Feed URL switching (stable ↔ beta)
• Info.plist configuration validation

Integration Tests

• Manual testing with test appcast
• Beta channel verification
• Update detection and installation

CI Tests

• All tests run on macOS via GitHub Actions
• Test on every push to feature branch

---

Benefits of GHA Automation

✅ Fully automated releases - No manual appcast generation
✅ No human error - Consistent process every time
✅ Atomic releases - DMG and appcast published together
✅ History maintained - Appcast includes all previous releases
✅ Channel detection - Automatic stable/testing routing
✅ Fast releases - Tag and push, everything else is automatic

---

Post-Notarization Note

After the DMG is stapled (manual step post-notarization), we should ideally regenerate the appcast to point to the stapled DMG. This is a future enhancement - initial implementation will reference un-stapled DMG (which still works, just warns offline users).

Future enhancement: Automate stapling in workflow (requires waiting 5-45 minutes for notarization)

---

Documentation Deliverables

The release-process.md will be updated with:

• EdDSA key generation guide
• SSH deployment setup
• Secrets configuration instructions
• Appcast automation workflow
• Testing procedures
• Troubleshooting guide

---

Next Steps

Once you approve this plan, I will:

1. Document requirements on this issue ✅ (this comment)
2. Create feature branch
3. Consult with specialized agents (Zeppo for tests, Chico for review, Harpo for docs)
4. Implement all changes
5. Push and monitor CI
6. Create pull request

Ready to proceed with implementation?

[schuyler]

Decision: Deferred Post-v0.1

After discussion, we've decided to defer Sparkle 2 auto-updates until after the v0.1 release.

Rationale:

• No access to original DSA private key - Cannot maintain Sparkle 1.x appcast
• Full Sparkle 2 migration is significant work - Code changes + workflow automation + infrastructure setup
• v0.1 priority: Ship a solid release quickly
• Manual downloads work fine - GitHub releases are sufficient for early adopters

Plan:

v0.1: Ship without auto-updates (remove Sparkle entirely or leave dormant)
Post-v0.1: Implement Sparkle 2 with full GHA automation when time permits

Users who install v0.1 manually can upgrade to v1.0 (or v0.2) manually, then enjoy auto-updates going forward.

---

This issue remains open for future implementation. The complete plan with GHA automation is documented above and ready to execute when prioritized.