Documentation Index

Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt

Use this file to discover all available pages before exploring further.

​

Sparkle Updates with Stats.store Integration

​

Overview

• Sparkle Framework - Industry-standard macOS update framework for automatic updates
• Stats.store - Privacy-first analytics backend that proxies appcast requests
• GitHub Releases - Hosts the actual DMG files and appcast XML files

​

System Architecture

​

Update Check Flow

VibeTunnel App → Stats.store (Proxy) → GitHub (appcast.xml) → Stats.store → VibeTunnel App
                                                                    ↓
                                                             GitHub (DMG download)

1. App initiates update check: VibeTunnel queries Stats.store endpoint
2. Stats.store logs analytics: Records anonymous data (OS version, CPU type, daily unique users)
3. Stats.store proxies request: Fetches appcast.xml from GitHub
4. Appcast returned: Stats.store returns the appcast to the app
5. Signature verification: Sparkle verifies the EdDSA signature
6. Direct download: If valid, app downloads DMG directly from GitHub (not through Stats.store)

​

Update Endpoints

• Stable channel: https://stats.store/api/v1/appcast/appcast.xml
• Pre-release channel: https://stats.store/api/v1/appcast/appcast-prerelease.xml

​

Initial Setup and Registration

​

Prerequisites

1. Register your application with Stats.store
2. Configure your app to use Stats.store endpoints
3. Ensure proper User-Agent headers are sent

​

Stats.store Registration

1. Visit stats.store and create an account
2. Add your application with:
   • App name: VibeTunnel
   • Bundle ID: sh.vibetunnel.vibetunnel
   • GitHub repository: amantus-ai/vibetunnel
3. Configure the appcast URLs to proxy to:
   • Stable: https://raw.githubusercontent.com/amantus-ai/vibetunnel/main/appcast.xml
   • Pre-release: https://raw.githubusercontent.com/amantus-ai/vibetunnel/main/appcast-prerelease.xml

​

Verifying Configuration

# This will fail with "Application not found" if not registered
curl -H "User-Agent: VibeTunnel/1.0.0-beta.9 Sparkle/2.7.1" \
     https://stats.store/api/v1/appcast/appcast-prerelease.xml

# Check your app's stats page (replace with your app ID)
# https://stats.store/app/YOUR_APP_ID

​

Configuration Details

​

App Configuration (Info.plist)

<!-- Sparkle Public Key for signature verification -->
<key>SUPublicEDKey</key>
<string>AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI=</string>

<!-- Update feed URL (configured in UpdateChannel.swift) -->
<key>SUFeedURL</key>
<string>https://stats.store/api/v1/appcast/appcast-prerelease.xml</string>

​

HTTP Requirements

User-Agent: VibeTunnel/1.0.0-beta.8 Sparkle/2.7.1

{"error":"Application not found"}

​

Key Management and Signatures

​

Public Key

• Location: Info.plist (SUPublicEDKey)
• Value: AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI=
• Purpose: Verifies EdDSA signatures of updates

​

Private Key

• Location: private/sparkle_private_key
• Purpose: Signs DMG files for appcast entries
• Critical: Must match the public key in Info.plist

​

Signature Generation

# ALWAYS use the -f flag with the correct private key file
sign_update -f /path/to/private/sparkle_private_key /path/to/VibeTunnel-1.0.0-beta.8.dmg

# Output format:
# sparkle:edSignature="..." length="44748347"

​

Appcast XML Format

​

Structure

<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
    <channel>
        <title>VibeTunnel</title>
        <item>
            <title>VibeTunnel 1.0.0-beta.8</title>
            <sparkle:version>172</sparkle:version>
            <sparkle:shortVersionString>1.0.0-beta.8</sparkle:shortVersionString>
            <description><![CDATA[
                <h2>Release Notes</h2>
                <!-- HTML formatted release notes -->
            ]]></description>
            <pubDate>Tue, 08 Jul 2025 10:18:00 +0100</pubDate>
            <enclosure url="https://github.com/amantus-ai/vibetunnel/releases/download/v1.0.0-beta.8/VibeTunnel-1.0.0-beta.8.dmg" 
                       sparkle:version="172" 
                       sparkle:shortVersionString="1.0.0-beta.8" 
                       length="44748347" 
                       type="application/x-apple-diskimage" 
                       sparkle:edSignature="/538z6L/qhhnHkfWU1hVoqeKvFdHubFRobfq6Vfmwz4UCpDVhJrqG+W28xW1wU4W9+xt41NMgei+DLJr1JV8Cg=="/>
        </item>
    </channel>
</rss>

​

Critical Fields

• sparkle:version: Build number (must be incrementing)
• sparkle:shortVersionString: Human-readable version
• length: Exact file size in bytes
• sparkle:edSignature: EdDSA signature of the DMG file
• url: Direct download link to GitHub release

​

Testing and Verification

​

Manual Testing

# Test Stats.store endpoint (will fail without User-Agent)
curl https://stats.store/api/v1/appcast/appcast-prerelease.xml

# Test with proper User-Agent (should return XML)
curl -H "User-Agent: VibeTunnel/1.0.0-beta.8 Sparkle/2.7.1" \
     https://stats.store/api/v1/appcast/appcast-prerelease.xml

# Verify a specific signature
sign_update -f private/sparkle_private_key ~/Downloads/VibeTunnel-1.0.0-beta.8.dmg

​

Stats.store Caching

• Wait at least 1 minute before testing
• The old version may be served during this cache period
• Force-refresh won’t bypass this server-side cache

​

Current Release Signatures

​

Fallback Options Without Stats.store

​

Temporary Direct Configuration

// Stable channel
case .stable:
    return URL(string: "https://raw.githubusercontent.com/amantus-ai/vibetunnel/main/appcast.xml")!

// Pre-release channel
case .preRelease:
    return URL(string: "https://raw.githubusercontent.com/amantus-ai/vibetunnel/main/appcast-prerelease.xml")!

​

Implications of Direct URLs

• Works immediately without registration
• No dependency on third-party service
• Updates still function normally

• No analytics or usage statistics
• No geographic CDN benefits
• No A/B testing capabilities
• Missing crash/update correlation data

​

Migration Path

1. Release with direct URLs if Stats.store isn’t ready
2. Register with Stats.store when convenient
3. Update app in next release to use Stats.store endpoints
4. Existing users will update and start using Stats.store

​

Benefits of Stats.store

1. Privacy-First Analytics:
   • Track update adoption rates without collecting personal data
   • Monitor OS version distribution and hardware stats
   • Daily unique users via salted IP hashes (change daily)
   • No IP tracking, device IDs, or fingerprinting
2. Anonymous Data Collection:
   • macOS version and CPU architecture
   • App version numbers
   • Hardware info (RAM, Mac model, core count)
   • System language (no location data)
3. Technical Benefits:
   • Transparent proxy (doesn’t host files)
   • 1-minute appcast caching
   • GitHub outage protection
   • Free for open source projects
4. Future Features (Planned):
   • A/B testing for gradual rollouts
   • Custom update channels
   • Geographic CDN capabilities

​

Troubleshooting Guide

​

Common Issues

​

”Application not found” Error

1. App not registered with Stats.store
   • Solution: Register at stats.store
   • Create account and add VibeTunnel as an application
   • Configure GitHub repository URLs for appcast proxying
2. Incorrect User-Agent header
   • Required format: VibeTunnel/VERSION Sparkle/VERSION
   • Example: VibeTunnel/1.0.0-beta.9 Sparkle/2.7.1
   • Fix: Ensure Sparkle framework is properly integrated
3. Bundle ID mismatch
   • Expected: sh.vibetunnel.vibetunnel
   • Check: Verify in Info.plist that CFBundleIdentifier matches
4. Testing before registration
   • Note: You can still release without Stats.store
   • Alternative: Use direct GitHub URLs in Info.plist temporarily
   • Update later: Once registered, update SUFeedURL to Stats.store endpoints

​

Signature Verification Failed

• Cause: Wrong private key used for signing
• Fix: Use sign_update -f private/sparkle_private_key

​

Updates Not Detected

• Cause: Stats.store cache or incorrect version numbers
• Fix: Wait 1 minute after updating appcast, verify version increments

​

File Size Mismatch

• Cause: DMG was modified after signing
• Fix: Re-download and re-sign the DMG

​

Debugging Commands

# Check current appcast
curl -H "User-Agent: VibeTunnel/1.0.0-beta.8 Sparkle/2.7.1" \
     https://stats.store/api/v1/appcast/appcast-prerelease.xml | xmllint --format -

# Verify DMG signature
sign_update -f private/sparkle_private_key downloaded.dmg

# Compare with appcast signature
grep "sparkle:edSignature" appcast-prerelease.xml

​

The Beta 8 Update Incident (July 2025)

​

Timeline of Events

1. Initial Success: Updates from beta 1 through beta 7 worked correctly
2. Problem Detected: Users updating from beta 7 to beta 8 received error:

   “The update is improperly signed and could not be validated”

3. Investigation: Discovered multiple Sparkle private keys on the system
4. Root Cause: Wrong private key used to generate appcast signatures
5. Resolution: Updated appcast with correct signature

​

Technical Details

​

The Problem

1. File-based key (private/sparkle_private_key)
   • Base64: SMYPxE98bJ5iLdHTLHTqGKZNFcZLgrT5Hyjh79h3TaU=
   • Matches public key: AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI=
   • This is the correct key
2. Keychain key (accessed without -f flag)
   • Different key stored in macOS keychain
   • Produces incompatible signatures
   • This was incorrectly used

​

The Investigation

# Wrong way (uses keychain)
sign_update VibeTunnel-1.0.0-beta.8.dmg
# Result: XcdsjTw01IMbHGVnRVAq1cZ4ii4bY69CE+xqRHO/XXHP+05xzqndwlQ3cv22Ju083zbU2eu8W1J5AoCa75jLBw==

# Correct way (uses file)
sign_update -f private/sparkle_private_key VibeTunnel-1.0.0-beta.8.dmg
# Result: /538z6L/qhhnHkfWU1hVoqeKvFdHubFRobfq6Vfmwz4UCpDVhJrqG+W28xW1wU4W9+xt41NMgei+DLJr1JV8Cg==

​

The Mystery

• DMGs might have been originally signed with the keychain key
• The keychain key might have changed between releases
• There could have been a different issue masking the problem

​

The Solution

1. Identified the correct private key file
2. Generated the correct signature using -f flag
3. Updated only the appcast XML (no DMG changes needed)
4. Waited for Stats.store cache to expire (1 minute)
5. Verified updates now work correctly

​

Key Lessons Learned

1. Always use -f flag: sign_update -f private/sparkle_private_key
2. Document key locations: Keep clear records of which keys to use
3. Understand the architecture: Signatures live in appcast, not DMG files
4. Remember caching: Stats.store has a 1-minute cache
5. Test thoroughly: Verify signatures match before releasing

​

Prevention Measures

• Created this comprehensive documentation
• Added warnings about multiple keys
• Established correct signing procedure
• Documented all historical signatures for reference