D4 PGP Extension

A powerful VS Code extension for PGP encryption and decryption, providing seamless integration with the d4 Python library for secure file and text handling.

✨ Features

• 🔐 File Encryption/Decryption: Interactive file picker for encrypting and decrypting files with PGP symmetric encryption
• 📝 Text Encryption/Decryption: Encrypt and decrypt text content directly in VS Code editor
• 🔑 Smart Passphrase Management: Auto-load from PGP_PASSKEY environment variable or set manually
• ⚙️ Auto-Configuration: Automatically detects Python path, installs d4 module, and configures GPG binary
• 📊 Status Monitoring: Real-time status bar indicator showing extension readiness
• 📋 Comprehensive Logging: Detailed logging for debugging and monitoring
• 💾 Flexible Save Options: Decrypt files and choose when/where to save the decrypted content

🚀 Quick Start

1. Install the extension from VSIX or VS Code Marketplace
2. Set environment variable (optional but recommended):

   # Windows PowerShell
   $env:PGP_PASSKEY = "your-passphrase"
   
   # Or set permanently
   [System.Environment]::SetEnvironmentVariable('PGP_PASSKEY', 'your-passphrase', 'User')
   

3. Reload VS Code - Extension will auto-configure and load passphrase
4. Start encrypting/decrypting files and text!

📋 Commands

File Operations

• D4 PGP: Encrypt File - Select any file to encrypt (creates .gpg file)
• D4 PGP: Decrypt File - Select encrypted .gpg file to decrypt (shows content in editor, save when ready)

Text Operations

• D4 PGP: Encrypt Text - Encrypt selected text or enter text to encrypt
• D4 PGP: Decrypt Text - Decrypt selected encrypted text

Configuration & Management

• D4 PGP: Set Passphrase - Manually set or update PGP passphrase
• D4 PGP: Configure PGP - Configure Python path, GPG binary, secrets file, and log level
• D4 PGP: Show PGP Status - Display current status and configuration
• D4 PGP: View Logs - Open the extension output channel for detailed logs

🎯 Usage Workflows

Encrypting a File

1. Run D4 PGP: Encrypt File from Command Palette (Ctrl+Shift+P)
2. Select the file you want to encrypt
3. Encrypted .gpg file is created in the same directory
4. Choose to open encrypted file or show in file explorer

Decrypting a File

1. Run D4 PGP: Decrypt File from Command Palette
2. Select the .gpg file to decrypt
3. Decrypted content appears in a new editor tab
4. Click "Save As..." when ready to save, or just close without saving

Context Menu Integration

• Editor Context: Right-click in editor to access encryption/decryption commands
• Explorer Context: Right-click files in explorer to encrypt/decrypt directly

Configuration

The extension can be configured via VS Code settings:

{
  "d4-pgp.pythonPath": "", // Path to Python executable (auto-detect if empty)
  "d4-pgp.gpgBinary": "",   // Path to GPG binary (auto-detect if empty)
  "d4-pgp.defaultSecretsFile": "", // Default secrets file path
  "d4-pgp.logLevel": "info" // Log level: debug, info, warning, error
}

📦 Requirements

The extension automatically installs and configures most requirements, but you may need:

• Python 3.9+ (auto-detected from system)
• d4 Python package (auto-installed from local repo or GitHub)
• GnuPG (bundled with d4 package - no separate installation needed on Windows)

Manual Installation (if needed)

If auto-installation fails, install manually:

# Install d4 Python package
pip install d4

# Or install from local repository
cd d:\myCode\gitHub\d4
pip install -e .

# Verify installation
python -c "from d4.d4_pgp import get_gpg_exe; print(get_gpg_exe())"

Platform-Specific Notes

Windows:

• GPG binary is bundled with d4 package (no separate installation needed)
• Python path auto-detected using py launcher
• Full Python executable path shown in configuration

macOS/Linux:

• May need to install GnuPG separately: brew install gnupg or apt-get install gnupg
• Python path auto-detected from system

🔒 Security Notes

• Passphrase Storage: Passphrases stored in memory only, cleared on extension deactivation
• Environment Variable: PGP_PASSKEY is read from environment but never written
• Encryption Method: Uses symmetric PGP encryption with AES-256
• Temporary Files: Python scripts created in temp directory and deleted after execution
• File Path Security: All file paths normalized to prevent injection attacks
• No Persistent Storage: Extension does not store any sensitive information on disk

🛠️ Troubleshooting

Extension Not Activating

1. Check Output panel: View > Output > D4 PGP Manager
2. Look for initialization errors
3. Verify Python is installed: python --version or py --version

"PGP client not ready" Error

1. Check if passphrase is set: Run D4 PGP: Set Passphrase
2. Or set PGP_PASSKEY environment variable and reload VS Code
3. Check logs for initialization errors

"d4 module not found" Error

# Verify d4 installation
python -c "import d4.d4_pgp"

# Reinstall if needed
pip install d4 --force-reinstall

File Decryption Fails with Unicode Error

• Fixed in latest version - file paths are now properly normalized
• Update to latest extension version
• If issue persists, check Output logs for details

GPG Binary Not Found

• Windows: GPG is bundled with d4 package (auto-configured)
• Check configuration: D4 PGP: Show PGP Status
• Manually set GPG path if needed: D4 PGP: Configure PGP > GPG Binary

Python Path Shows "py" Instead of Full Path

• Clear cached setting: Open Settings (JSON) and remove "d4-pgp.pythonPath"
• Reload window: Developer: Reload Window
• Extension will auto-detect full Python executable path

💻 Development

Building from Source

# Clone repository
git clone https://github.com/internetics-net/d4-extension.git
cd d4-extension

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package extension
npm run package

Development Mode

# Watch mode for development
npm run watch

# Or press F5 in VS Code to launch Extension Development Host

Testing

# Run tests
npm test

# Lint code
npm run lint

See TESTING.md for comprehensive testing guide.

📄 License

MIT License - see LICENSE.txt for details

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📞 Support

For issues and support:

• GitHub Issues: d4-extension Issues
• Documentation: See TESTING.md for detailed testing guide
• Email: help@internetics.net

🙏 Acknowledgments

Built with the d4 Python library for PGP operations.