How rca/gpgmail works
Project Type and Purpose
• This is a macOS “bundle‐injection” plugin for Apple’s Mail.app. It uses Objective-C categories and method swizzling to hook into Mail’s message compose and view workflows, adding GPG encryption, decryption, signature, and key-management features.
Top-Level Components
• Host Application: Mail.app (not in your repo, but the environment into which your code is injected)
• Plugin Bundle: GPGMailBundle (the .bundle loaded by Mail)
• Frameworks/Dependencies:
• MacGPGME (wrapping the GPG binary and keyrings)
• Sparkle.framework (self-update mechanism)
• External Services:
• GPG binary (spawned as a subprocess via GPGTask)
• Public keyservers (as defined in KeyServers.plist)
• Build & Release Tools:
• Makefile and build-gpgme.sh (compile/assemble everything)
• Ruby scripts (generate_keys.rb, sign_update.rb)
• appcast.xml (update feed)
Internal Plugin Structure
• Source/Category Hooks: a large set of +GPGMail categories on Mail’s private headers (Message, MimePart, ComposeBackEnd, etc.)
• UI Components: NIBs for compose accessory, preference panels, key-download dialogs (in Resources/)
• Core Encryption Logic: GPGKeyDownload, GPGPassphraseController, GPGHandler, GPGSignature, GPGTask
• Preferences & Keychain Integration: NSPreferences_GPGMail, MessageKeychainManager+GPGMail
Data Flows & Interactions
a. Compose/Send Flow (Encryption & Signing)
• User writes email in Mail.app → plugin intercepts via ComposeBackEnd+GPGMail → passes cleartext to GPGME APIs → GPGTask spawns gpg subprocess → returns encrypted MIME parts → Mail.app continues to send.
b. Receive/Viewing Flow (Decryption & Verification)
• Mail.app delivers inbound message → plugin intercepts via MessageViewer+GPGMail → passes encrypted blob to GPGME → spawns gpg → returns decrypted body or signature status → plugin renders results in accessory view.
c. Key Management & Download
• Preferences UI or Compose UI triggers GPGKeyDownload → HTTP fetch from keyservers → stores keys in local keyring via GPGME.
d. Self-Update via Sparkle
• Sparkle.framework checks appcast.xml → downloads signed update → invokes sign_update.rb and generate_keys.rb → installs new plugin bundle.
Architectural Patterns & Principles
• Dynamic Plugin/Inversion-of-Control: code is delivered as a .bundle and loaded into a host process at runtime.
• Adapter/Facade: MacGPGME wraps underlying GPG command-line interface.
• Category / Swizzling (Cross-Cutting Concern): augment Mail’s classes without modifying Mail.app directly.
• Modular Localization: hundreds of .lproj folders with NIB/UI and .strings.