diff --git a/DESKTOP_XMPP_CLIENT_FIX.md b/DESKTOP_XMPP_CLIENT_FIX.md deleted file mode 100644 index e69de29..0000000 diff --git a/Dockerfile.multiarch b/Dockerfile.multiarch index 812da8b..f14e5ce 100644 --- a/Dockerfile.multiarch +++ b/Dockerfile.multiarch @@ -40,9 +40,16 @@ RUN apk add --no-cache \ RUN adduser -D -s /bin/sh -u 1011 appuser # Create application directories -RUN mkdir -p /opt/hmac-file-server/{data/{uploads,duplicates,temp,logs},config} \ +RUN mkdir -p /opt/hmac-file-server/data/uploads \ + /opt/hmac-file-server/data/duplicates \ + /opt/hmac-file-server/data/temp \ + /opt/hmac-file-server/data/logs \ + /opt/hmac-file-server/config \ && chown -R appuser:appuser /opt/hmac-file-server \ - && chmod 750 /opt/hmac-file-server/data/{uploads,duplicates,temp,logs} + && chmod 750 /opt/hmac-file-server/data/uploads \ + && chmod 750 /opt/hmac-file-server/data/duplicates \ + && chmod 750 /opt/hmac-file-server/data/temp \ + && chmod 750 /opt/hmac-file-server/data/logs WORKDIR /opt/hmac-file-server diff --git a/ENHANCED_SECURITY_ARCHITECTURE.md b/ENHANCED_SECURITY_ARCHITECTURE.md deleted file mode 100644 index 4b8e2f2..0000000 --- a/ENHANCED_SECURITY_ARCHITECTURE.md +++ /dev/null @@ -1,248 +0,0 @@ -# ๐Ÿ” Enhanced Security Architecture for Network Switching - -## HMAC File Server 3.3.0 "Nexus Infinitum" - Smart Re-Authentication - -**Date:** August 26, 2025 -**Version:** 3.3.0 with Enhanced Security -**Author:** AI Assistant - ---- - -## Executive Summary - -Your question about **re-asking for secrets when clients switch networks or wake from standby** is not only valid but represents a **critical security enhancement**. This document outlines the implementation of a progressive security system that intelligently handles re-authentication while maintaining the seamless user experience required for XMPP mobile clients. - -## Security Challenge Analysis - -### Original Problem -- **404 errors during 5G โ†” WiFi switching** due to session loss -- **Long-lived sessions** creating security vulnerabilities -- **No differentiation** between trusted and suspicious scenarios -- **Lack of standby detection** for security evaluation - -### Enhanced Solution -- **Progressive security levels** (1-3) based on risk assessment -- **Smart re-authentication triggers** for network changes and standby -- **Challenge-response mechanism** for medium-risk scenarios -- **Full re-authentication** for high-risk situations - ---- - -## Security Architecture - -### 1. Progressive Security Levels - -| Level | Scenario | Action | User Experience | -|-------|----------|--------|-----------------| -| **1** | Normal operation | Standard session refresh | Transparent | -| **2** | Network change, medium standby | Challenge-response | Automatic | -| **3** | Long standby, suspicious activity | Full re-authentication | User prompted | - -### 2. Security Triggers - -#### Network Change Detection -``` -๐ŸŒ NETWORK CHANGE #1: 192.168.1.100 โ†’ 10.0.0.50 for session abc123 -๐Ÿ” SECURITY LEVEL 2: Network change requires challenge-response -``` - -#### Standby Detection -``` -๐Ÿ”’ STANDBY DETECTED: 45m since last activity for session abc123 -๐Ÿ” SECURITY LEVEL 2: Medium standby (45m) requires challenge-response -``` - -#### Long Standby Protection -``` -๐Ÿ’ค STANDBY RECOVERY: Token expired 7200 seconds ago (2h) -๐Ÿ” SECURITY LEVEL 3: Long standby (2h) requires full re-authentication -``` - -#### Suspicious Activity -``` -๐Ÿ” SECURITY LEVEL 3: User agent change detected - potential device hijacking -๐Ÿ” SECURITY LEVEL 3: Multiple network changes (4) requires full re-authentication -``` - -### 3. Implementation Components - -#### Enhanced Session Structure -```go -type NetworkResilientSession struct { - // Existing fields... - SecurityLevel int `json:"security_level"` // 1-3 - LastSecurityCheck time.Time `json:"last_security_check"` - NetworkChangeCount int `json:"network_change_count"` - StandbyDetected bool `json:"standby_detected"` - LastActivity time.Time `json:"last_activity"` -} -``` - -#### Security Evaluation Function -```go -func evaluateSecurityLevel(session *NetworkResilientSession, currentIP string, userAgent string) int { - // Standby detection - timeSinceLastActivity := time.Since(session.LastActivity) - if timeSinceLastActivity > 2*time.Hour { - return 3 // Full re-authentication - } - if timeSinceLastActivity > 30*time.Minute { - return 2 // Challenge-response - } - - // Network change detection - if session.LastIP != currentIP { - session.NetworkChangeCount++ - if session.NetworkChangeCount > 3 { - return 3 // Suspicious multiple changes - } - return 2 // Single network change - } - - return 1 // Normal operation -} -``` - -#### Challenge-Response Mechanism -```go -func generateSecurityChallenge(session *NetworkResilientSession, secret string) (string, error) { - timestamp := time.Now().Unix() - challengeData := fmt.Sprintf("%s:%s:%d", session.SessionID, session.UserJID, timestamp) - h := hmac.New(sha256.New, []byte(secret)) - h.Write([]byte(challengeData)) - return hex.EncodeToString(h.Sum(nil)), nil -} -``` - ---- - -## Configuration Options - -### Enhanced Security Settings -```toml -[security] -# Enhanced Security Features (NEW in 3.3.0) -enhanced_security = true # Enable enhanced security evaluation -challenge_on_network_change = true # Require challenge-response on network change -reauth_on_long_standby = true # Require full re-auth after long standby -standby_threshold_minutes = 30 # Minutes to detect standby -long_standby_threshold_hours = 2 # Hours to require full re-auth -``` - -### Configurable Thresholds -- **Standby Detection:** 30 minutes (configurable) -- **Long Standby:** 2 hours (configurable) -- **Network Change Limit:** 3 changes (configurable) -- **Challenge Window:** 5 minutes (configurable) - ---- - -## XEP-0363 Compliance - -### HTTP Headers for Client Guidance -```http -HTTP/1.1 401 Unauthorized -WWW-Authenticate: HMAC-Challenge challenge="a1b2c3d4e5f6..." -X-Security-Level: 2 -X-Auth-Required: challenge-response -``` - -### Client Implementation Guide -```javascript -// XMPP client handling for enhanced security -if (response.status === 401) { - const securityLevel = response.headers['X-Security-Level']; - const challenge = response.headers['WWW-Authenticate']; - - switch(securityLevel) { - case '2': - // Generate challenge response automatically - const challengeResponse = generateHMACResponse(challenge, session); - retry(request, {'X-Challenge-Response': challengeResponse}); - break; - case '3': - // Prompt user for re-authentication - promptForCredentials(); - break; - } -} -``` - ---- - -## Security Benefits - -### 1. **Prevents Token Hijacking** -- Network transitions require fresh authentication -- Stolen tokens become useless after network change -- Time-based challenges prevent replay attacks - -### 2. **Device Theft Protection** -- Long standby triggers full re-authentication -- Multiple suspicious network changes escalate security -- User agent changes detected and blocked - -### 3. **Maintains Usability** -- Level 1: Zero user interaction (trusted scenarios) -- Level 2: Automatic challenge-response (transparent) -- Level 3: User prompted only when necessary - -### 4. **Standards Compliance** -- XEP-0363 compliant authentication flow -- Standard HTTP 401 Unauthorized responses -- Compatible with existing XMPP clients - ---- - -## Implementation Timeline - -### โœ… Phase 1: Foundation (Completed) -- Enhanced session structure -- Security level evaluation -- Basic challenge-response mechanism -- Configuration options - -### ๐Ÿ”„ Phase 2: Integration (In Progress) -- Complete security header implementation -- Client guidance documentation -- Comprehensive testing - -### ๐Ÿ“… Phase 3: Optimization (Planned) -- Machine learning for anomaly detection -- Geographic location validation -- Advanced threat detection - ---- - -## Testing & Validation - -### Test Scenarios -1. **Normal Operation:** Transparent session refresh -2. **5G โ†” WiFi Switch:** Challenge-response required -3. **Device Standby:** Progressive security escalation -4. **Multiple Changes:** Full re-authentication triggered -5. **Suspicious Activity:** Security escalation and logging - -### Performance Impact -- **Minimal overhead:** Security evaluation adds <1ms per request -- **Memory efficient:** Enhanced session structure adds ~200 bytes -- **Network efficient:** Challenge-response requires single round-trip - ---- - -## Conclusion - -The enhanced security architecture for **HMAC File Server 3.3.0** successfully addresses your concern about re-authentication during network switching and standby recovery. This implementation: - -โœ… **Solves the original 404 problem** with persistent sessions -โœ… **Enhances security** with intelligent re-authentication -โœ… **Maintains usability** through progressive security levels -โœ… **Provides standards compliance** with XEP-0363 -โœ… **Offers configurability** for different deployment scenarios - -**Your insight about re-asking for secrets was absolutely correct** - it's a critical security enhancement that makes the system both more secure and more robust for mobile XMPP scenarios. - ---- - -*HMAC File Server 3.3.0 "Nexus Infinitum" - Enhanced Security Edition* -*Smart re-authentication for the connected world* diff --git a/GIT_RELEASE_NOTES_3.2.2.md b/GIT_RELEASE_NOTES_3.2.2.md deleted file mode 100644 index 42bd1da..0000000 --- a/GIT_RELEASE_NOTES_3.2.2.md +++ /dev/null @@ -1,28 +0,0 @@ -## HMAC File Server 3.3.0 - Enhanced MIME Types & XMPP Compatibility - -### ๐Ÿš€ New Features -- **Enhanced MIME Types**: Added 80+ file format mappings (.flac, .webm, .epub, .docx, .py, .go, etc.) -- **XMPP Client Ecosystem**: Comprehensive compatibility with Conversations, Dino, Gajim, Monal -- **Network Resilience**: Optimized mobile WLAN โ†” 5G switching - -### ๐Ÿ”ง Improvements -- Better Content-Type headers for downloads -- Enhanced browser file handling -- Future-proof file format support -- Zero breaking changes - -### ๐Ÿ“ฆ Deployment -```bash -# Docker -docker pull hmac-file-server:3.3.0 - -# Binary -wget https://git.uuxo.net/uuxo/hmac-file-server/releases/download/v3.3.0/hmac-file-server-linux-amd64 -``` - -### ๐Ÿ›ก๏ธ Security -- HMAC authentication core unchanged -- 100% backward compatible -- All XMPP protocols supported - -**Drop-in upgrade** - no configuration changes required! diff --git a/MIME_TYPE_ENHANCEMENT_REPORT.md b/MIME_TYPE_ENHANCEMENT_REPORT.md deleted file mode 100644 index e0c3e79..0000000 --- a/MIME_TYPE_ENHANCEMENT_REPORT.md +++ /dev/null @@ -1,180 +0,0 @@ -# MIME Type Enhancement Report -*HMAC File Server 3.3.0 "Nexus Infinitum" - Enhanced Content Type Support* - -## โœ… ENHANCEMENT SUMMARY - -### ๐Ÿ”ง **WHAT WAS IMPROVED** -- **Enhanced MIME Type Detection**: Added 80+ additional file type mappings -- **Better Modern Format Support**: Comprehensive coverage of contemporary file formats -- **Maintained Compatibility**: All existing functionality preserved -- **HMAC Core Untouched**: Authentication system remains exactly as before - -### ๐Ÿ“Š **NEW SUPPORTED FORMATS** - -#### Audio Formats -- `.flac` โ†’ `audio/flac` -- `.ogg` โ†’ `audio/ogg` -- `.opus` โ†’ `audio/opus` -- `.aac` โ†’ `audio/aac` -- `.m4a` โ†’ `audio/mp4` -- `.wma` โ†’ `audio/x-ms-wma` - -#### Video Formats -- `.webm` โ†’ `video/webm` -- `.mkv` โ†’ `video/x-matroska` -- `.m4v` โ†’ `video/x-m4v` -- `.3gp` โ†’ `video/3gpp` -- `.flv` โ†’ `video/x-flv` - -#### Archive Formats -- `.7z` โ†’ `application/x-7z-compressed` -- `.rar` โ†’ `application/vnd.rar` -- `.bz2` โ†’ `application/x-bzip2` -- `.xz` โ†’ `application/x-xz` -- `.zst` โ†’ `application/zstd` - -#### Document Formats -- `.epub` โ†’ `application/epub+zip` -- `.docx` โ†’ `application/vnd.openxmlformats-officedocument.wordprocessingml.document` -- `.xlsx` โ†’ `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` -- `.odt` โ†’ `application/vnd.oasis.opendocument.text` - -#### Programming Formats -- `.py` โ†’ `text/x-python` -- `.go` โ†’ `text/x-go` -- `.rs` โ†’ `text/x-rust` -- `.toml` โ†’ `application/toml` -- `.yaml` โ†’ `application/x-yaml` - -#### Package Formats -- `.apk` โ†’ `application/vnd.android.package-archive` -- `.deb` โ†’ `application/vnd.debian.binary-package` -- `.rpm` โ†’ `application/x-rpm` -- `.dmg` โ†’ `application/x-apple-diskimage` - -#### Font Formats -- `.woff` โ†’ `font/woff` -- `.woff2` โ†’ `font/woff2` -- `.ttf` โ†’ `font/ttf` -- `.otf` โ†’ `font/otf` - -#### 3D Model Formats -- `.stl` โ†’ `model/stl` -- `.obj` โ†’ `model/obj` -- `.ply` โ†’ `model/ply` - -#### Database Formats -- `.sqlite` โ†’ `application/x-sqlite3` -- `.db` โ†’ `application/x-sqlite3` - -## ๐ŸŽฏ **TECHNICAL IMPLEMENTATION** - -### Core Function: `GetContentType(filename string) string` -```go -// Enhanced MIME type detection with fallback support -func GetContentType(filename string) string { - ext := strings.ToLower(filepath.Ext(filename)) - - // First try Go's built-in MIME detection - if mimeType := mime.TypeByExtension(ext); mimeType != "" { - return mimeType - } - - // Try enhanced mappings - if mimeType, found := enhancedMimeTypes[ext]; found { - return mimeType - } - - // Fallback to generic binary type - return "application/octet-stream" -} -``` - -### Integration Points -1. **HMAC Authentication** (`validateHMAC`): Uses `GetContentType()` for v2/token protocols -2. **File Downloads** (`handleDownload`): Sets proper `Content-Type` headers -3. **Fallback Support**: Maintains `application/octet-stream` for unknown types - -## ๐Ÿš€ **BENEFITS FOR XMPP ECOSYSTEM** - -### Client Compatibility -- **Conversations (Android)**: Better file type recognition -- **Dino (Linux)**: Improved download handling -- **Gajim (Desktop)**: Enhanced MIME type awareness -- **Web Clients**: Proper browser file handling - -### Network Resilience -- **Content-Type headers**: Help clients handle network switches better -- **Proper MIME detection**: Reduces client-side guessing -- **Fallback support**: Maintains compatibility with unknown types - -## โœ… **VALIDATION RESULTS** - -### Compilation Tests -- โœ… Clean compilation with no errors -- โœ… All imports properly managed -- โœ… No deprecated function usage - -### Functionality Tests -- โœ… Server starts correctly with enhanced MIME types -- โœ… HMAC authentication works unchanged -- โœ… Download Content-Type headers set properly -- โœ… Fallback to `application/octet-stream` works - -### Compatibility Tests -- โœ… Existing configurations work unchanged -- โœ… XMPP client authentication preserved -- โœ… All protocol versions (v, v2, token, v3) supported - -## ๐Ÿ”’ **SECURITY & STABILITY** - -### HMAC Core Protection -- **Authentication Logic**: Completely untouched -- **Protocol Compatibility**: All XMPP clients continue working -- **Signature Validation**: Exact same behavior as before - -### Error Handling -- **Unknown Extensions**: Graceful fallback to `application/octet-stream` -- **Empty Extensions**: Proper handling maintained -- **Case Sensitivity**: Normalized to lowercase for consistency - -## ๐Ÿ“ˆ **PERFORMANCE IMPACT** - -### Memory Usage -- **Minimal Overhead**: Static map lookup O(1) -- **No Allocations**: String constants used throughout -- **Efficient Fallback**: Quick detection path - -### CPU Usage -- **Fast Lookups**: Hash map for enhanced types -- **Cached Results**: Go's built-in MIME cache still used first -- **Zero Regression**: Same performance for existing types - -## ๐ŸŽญ **DEPLOYMENT NOTES** - -### Backward Compatibility -- **100% Compatible**: No configuration changes required -- **Drop-in Replacement**: Existing servers can upgrade seamlessly -- **Protocol Preservation**: All XMPP authentication methods work - -### Configuration -- **No Changes Needed**: Enhancement is transparent -- **Extension Lists**: Existing `allowed_extensions` still respected -- **File Validation**: Same extension checking logic - -## ๐Ÿ **CONCLUSION** - -The MIME type enhancement provides **significant improvement** in file type handling while maintaining **absolute compatibility** with existing XMPP clients and server configurations. - -### Key Achievements -- โœ… **80+ new file types** supported -- โœ… **HMAC core completely untouched** -- โœ… **Zero breaking changes** -- โœ… **Enhanced XMPP client experience** -- โœ… **Future-proof file format support** - -The enhancement ensures our HMAC File Server provides **best-in-class MIME type detection** while preserving the **rock-solid authentication system** that makes it compatible with the entire XMPP client ecosystem. - ---- -*Generated by HMAC File Server 3.3.0 "Nexus Infinitum" - MIME Enhancement Team* -*Date: August 24, 2025* diff --git a/NETWORK_RESILIENCE_FIX_REPORT.md b/NETWORK_RESILIENCE_FIX_REPORT.md deleted file mode 100644 index e69de29..0000000 diff --git a/QUICKINSTALL.md b/QUICKINSTALL.md deleted file mode 100644 index aff36d4..0000000 --- a/QUICKINSTALL.md +++ /dev/null @@ -1,311 +0,0 @@ -# HMAC File Server 3.3.0 "Nexus Infinitum" - Quick Install Guide โšก - -**Get started in under 2 minutes!** - ---- - -## ๐Ÿš€ **Super Quick Start (30 seconds)** - -```bash -# Option A: Use pre-built local binaries (if available) -cd hmac-file-server -./builds/hmac-file-server-linux-amd64 -genconfig > config.toml -./builds/hmac-file-server-linux-amd64 -config config.toml - -# Option B: Download from releases (when available) -wget https://git.uuxo.net/uuxo/hmac-file-server/releases/download/v3.3.0/hmac-file-server-linux-amd64 -chmod +x hmac-file-server-linux-amd64 -./hmac-file-server-linux-amd64 -genconfig > config.toml -./hmac-file-server-linux-amd64 -config config.toml -``` - -**That's it!** Your server is running on `http://localhost:8080` ๐ŸŽ‰ - ---- - -## ๐Ÿ“ฆ **Choose Your Installation Method** - -### 1. **Binary Download** (Recommended) -```bash -# Option A: Use local builds (if cloned from git) -cd hmac-file-server -./builds/hmac-file-server-linux-amd64 -genconfig > config.toml -# Available: builds/hmac-file-server-linux-{amd64,arm64,arm} -# Also: builds/hmac-file-server-darwin-{amd64,arm64} - -# Option B: Download from releases -wget https://git.uuxo.net/uuxo/hmac-file-server/releases/download/v3.3.0/hmac-file-server-linux-amd64 -# ARM64: hmac-file-server-linux-arm64 -# ARM32: hmac-file-server-linux-arm - -chmod +x hmac-file-server-linux-amd64 - -# Generate configuration -./hmac-file-server-linux-amd64 -genconfig > config.toml - -# Edit these 3 essential settings in config.toml: -# bind_ip = "0.0.0.0" # Listen on all interfaces -# listenport = "8080" # Your desired port -# storage_path = "./uploads" # Where to store files - -./hmac-file-server-linux-amd64 -config config.toml -``` - -### 2. **Docker** (Container Deployment) -```bash -# Pull and run -docker pull hmac-file-server:3.3.0 -docker run -d --name hmac-server \ - -p 8080:8080 \ - -v ./uploads:/app/uploads \ - hmac-file-server:3.3.0 -``` - -### 3. **Automated Installer** (Full Setup) -```bash -# Download and run installer (when available) -wget https://git.uuxo.net/uuxo/hmac-file-server/raw/main/installer.sh -chmod +x installer.sh -sudo ./installer.sh - -# Or use local installer if cloned -sudo ./installer.sh -``` - -### 4. **Build from Source** (Developers) -```bash -# Clone and build -git clone https://git.uuxo.net/uuxo/hmac-file-server.git -cd hmac-file-server - -# Option A: Interactive multi-arch builder -./build-multi-arch.sh -# Then use: ./builds/hmac-file-server-linux-amd64 - -# Option B: Quick single build -go build -o hmac-file-server ./cmd/server/ -./hmac-file-server -genconfig > config.toml -./hmac-file-server -config config.toml -``` - ---- - -## โš™๏ธ **Essential Configuration (2 minutes)** - -### Minimal Configuration (Just Works!) -```toml -# config.toml - Only 2 lines needed! -[server] -storage_path = "./uploads" -``` - -### Basic Production Configuration -```toml -[server] -bind_ip = "0.0.0.0" -listenport = "8080" -storage_path = "/data/uploads" -hmac_secret = "your-secret-key-here" -max_upload_size = "100MB" - -[security] -require_hmac = true -``` - -### Mobile-Optimized Configuration -```toml -[server] -bind_ip = "0.0.0.0" -listenport = "8080" -storage_path = "./uploads" - -[network_resilience] -enable_network_resilience = true -grace_period_hours = 72 -detect_network_changes = true - -[client_network_support] -enable_client_network_support = true -mobile_grace_hours = 72 -desktop_grace_hours = 48 -``` - ---- - -## ๐Ÿ”ง **Quick Configuration Options** - -### Using Pre-Built Binaries - -If you cloned the repository, you'll find ready-to-use binaries in the `builds/` directory: - -```bash -# List available architectures -ls builds/ -# hmac-file-server-darwin-amd64 # macOS Intel -# hmac-file-server-darwin-arm64 # macOS Apple Silicon -# hmac-file-server-linux-386 # Linux 32-bit -# hmac-file-server-linux-amd64 # Linux 64-bit (most common) -# hmac-file-server-linux-arm # Linux ARM 32-bit (Raspberry Pi 3) -# hmac-file-server-linux-arm64 # Linux ARM 64-bit (Raspberry Pi 4+) - -# Use the appropriate one for your system -./builds/hmac-file-server-linux-amd64 -genconfig > config.toml -``` - -### Build More Architectures - -```bash -# Interactive builder for all platforms -./build-multi-arch.sh - -# Quick Docker multi-arch build -./docker-multiarch-build.sh --local -``` - -### Generate Configuration Templates -```bash -# Using local builds -./builds/hmac-file-server-linux-amd64 -genconfig > config.toml # Basic config -./builds/hmac-file-server-linux-amd64 -genconfig-mobile > mobile.toml # Mobile-optimized -./builds/hmac-file-server-linux-amd64 -genconfig-enterprise > enterprise.toml # Enterprise config - -# Or using downloaded binary -./hmac-file-server -genconfig > config.toml # Basic config -./hmac-file-server -genconfig-mobile > mobile.toml # Mobile-optimized -./hmac-file-server -genconfig-enterprise > enterprise.toml # Enterprise config -``` - -### Validate Configuration -```bash -./hmac-file-server -config config.toml --validate # Check configuration -./hmac-file-server -config config.toml --validate-quiet # Silent validation -``` - -### Test Configuration -```bash -./hmac-file-server -config config.toml --check # Dry run test -``` - ---- - -## ๐ŸŒ **Integration with XMPP** - -### ejabberd Configuration -```yaml -# ejabberd.yml - Add to modules section -modules: - mod_http_upload: - put_url: "http://your-server:8080/upload" - get_url: "http://your-server:8080/file" - secret: "your-hmac-secret" - max_size: 104857600 # 100MB -``` - -### Prosody Configuration -```lua --- prosody.cfg.lua -Component "upload.yourdomain.com" "http_upload" - http_upload_url = "http://your-server:8080/upload" - http_upload_file_size_limit = 100 * 1024 * 1024 -- 100MB -``` - ---- - -## ๐Ÿ” **Verify Installation** - -### Check Server Status -```bash -# Test server is running -curl http://localhost:8080/health - -# Check version (using local builds) -./builds/hmac-file-server-linux-amd64 -version - -# Or using downloaded binary -./hmac-file-server -version - -# View configuration -./hmac-file-server -config config.toml --validate -``` - -### Test Upload (with XMPP client) -1. **Configure your XMPP client** with the server URL -2. **Send a file** in any chat -3. **Verify upload** in the `uploads` directory - ---- - -## ๐Ÿ†˜ **Troubleshooting** - -### Common Issues - -**โŒ Port already in use** -```bash -# Change port in config.toml -listenport = "8081" # Use different port -``` - -**โŒ Permission denied** -```bash -# Create uploads directory with proper permissions -mkdir -p uploads -chmod 755 uploads -``` - -**โŒ XMPP upload fails** -```bash -# Use the XMPP client fixing tool -./fix_xmpp_clients.sh -``` - -**โŒ Network switching issues** -```bash -# Test network resilience -./verify_network_resilience.sh -``` - -### Get Help - -- **Documentation**: [Complete WIKI](WIKI.MD) -- **Issues**: [Git Issues](https://git.uuxo.net/uuxo/hmac-file-server/issues) -- **Support**: [Git Repository](https://git.uuxo.net/uuxo/hmac-file-server/) - ---- - -## ๐ŸŽฏ **Next Steps** - -### Production Deployment -1. **Set up reverse proxy** (nginx/Apache) -2. **Configure SSL/TLS** certificates -3. **Set up systemd service** for auto-start -4. **Configure monitoring** and logging -5. **Set up backup** for uploads directory - -### Advanced Features -- **Multi-architecture deployment** with `./build-multi-arch.sh` -- **Docker multi-platform** with `./docker-multiarch-build.sh` -- **Network resilience testing** with `./verify_network_resilience.sh` -- **Desktop client optimization** with `./fix_xmpp_clients.sh` - ---- - -## ๐Ÿš€ **You're Ready!** - -Your HMAC File Server 3.3.0 "Nexus Infinitum" is now running and ready for infinite connectivity! - -**What you get:** -- โœ… **Secure file uploads** with HMAC authentication -- โœ… **Multi-architecture support** (AMD64, ARM64, ARM32v7) -- โœ… **Network resilience** for mobile scenarios -- โœ… **Desktop XMPP client** optimization -- โœ… **Zero-downtime** network switching -- โœ… **Enterprise-grade** reliability - -**Server URL**: `http://your-server:8080` -**Health Check**: `http://your-server:8080/health` - -Enjoy boundless file sharing! ๐ŸŒŸ - ---- - -*HMAC File Server 3.3.0 "Nexus Infinitum" - Where Infinite Connectivity Meets Simplicity* diff --git a/RELEASE_NOTES_3.3.0.md b/RELEASE_NOTES_3.3.0.md deleted file mode 100644 index 60cc77f..0000000 --- a/RELEASE_NOTES_3.3.0.md +++ /dev/null @@ -1,186 +0,0 @@ -# HMAC File Server 3.3.0 โ€“ "Nexus Infinitum" Release ๐Ÿš€ - -**Release Date**: August 26, 2025 -**Type**: Major Feature Release -**Codename**: Nexus Infinitum -**Focus**: Infinite Connectivity & Network Resilience - ---- - -## ๐ŸŒŸ **"Nexus Infinitum" - Where Infinite Connectivity Meets Enterprise Power** - -HMAC File Server 3.3.0 "Nexus Infinitum" represents the pinnacle of network resilience and connectivity. This release transforms the server into a boundless nexus of file sharing capabilities, providing infinite reach across all network topologies and client ecosystems. - ---- - -## ๐ŸŽฏ **Major Enhancements in 3.3.0** - -### ๐Ÿ–ฅ๏ธ **Desktop XMPP Client Revolution** -- **48-hour session restoration** for Dino and Gajim clients -- **Intelligent cache recovery** after application restarts -- **Enhanced detection** of desktop vs mobile XMPP scenarios -- **Seamless authentication persistence** across client restarts - -### ๐ŸŒ **Network Resilience Perfection** -- **WiFi โ†” LTE switching** with zero interruption -- **Multi-interface detection** for complex network topologies -- **Router NAT intelligence** for consistent connectivity -- **Ultra-flexible grace periods** (8h โ†’ 12h โ†’ 24h โ†’ 72h cascade) - -### ๐Ÿ“ฑ **Mobile Client Optimization** -- **72-hour ultra-grace periods** for critical mobile scenarios -- **Automatic client detection** (Conversations, Dino, Gajim, ChatSecure) -- **Network change adaptation** with real-time IP detection -- **Standby recovery logic** for device sleep/wake cycles - -### ๐Ÿ”ง **Developer Experience** -- **Enhanced debugging tools** with comprehensive logging -- **Client cache management utilities** for troubleshooting -- **Network diagnostic capabilities** for complex setups -- **Automated testing framework** for all scenarios - ---- - -## ๐Ÿ› ๏ธ **Technical Achievements** - -### Authentication & Security -- โœ… **5 different HMAC payload formats** for maximum compatibility -- โœ… **Bearer token validation** with ultra-flexible grace periods -- โœ… **Session restoration** for cached authentication scenarios -- โœ… **Network switching detection** via proxy headers - -### Network Intelligence -- โœ… **Real-time IP change detection** (X-Forwarded-For, X-Real-IP) -- โœ… **Multi-interface support** (WLAN + Ethernet scenarios) -- โœ… **Router/NAT compatibility** with automatic adaptation -- โœ… **Client-specific timeout management** based on device type - -### Client Ecosystem -- โœ… **Desktop XMPP clients** (Dino, Gajim) with 24h grace periods -- โœ… **Mobile XMPP clients** (Conversations, ChatSecure) with enhanced timeouts -- โœ… **Cross-platform compatibility** with automatic optimization -- โœ… **Session cache management** for seamless user experience - ---- - -## ๐Ÿš€ **Installation & Upgrade** - -### Quick Installation -```bash -# Download 3.3.0 "Nexus Infinitum" -wget https://git.uuxo.net/uuxo/hmac-file-server/releases/download/v3.3.0/hmac-file-server-linux-amd64 -chmod +x hmac-file-server-linux-amd64 - -# Deploy with mobile-resilient configuration -./hmac-file-server-linux-amd64 -config config-mobile-resilient.toml -``` - -### Docker Deployment -```bash -# Pull 3.3.0 image -docker pull hmac-file-server:3.3.0 - -# Run with enhanced network resilience -docker run -d --name hmac-server \ - -p 8080:8080 -p 9090:9090 \ - -v ./uploads:/app/uploads \ - -v ./config-mobile-resilient.toml:/app/config.toml:ro \ - hmac-file-server:3.3.0 -``` - -### Upgrade from 3.2.x -```bash -# Backup current installation -cp hmac-file-server hmac-file-server-3.2.backup -cp config.toml config-3.2.backup.toml - -# Install 3.3.0 -wget https://git.uuxo.net/uuxo/hmac-file-server/releases/download/v3.3.0/hmac-file-server-linux-amd64 -mv hmac-file-server-linux-amd64 hmac-file-server -chmod +x hmac-file-server - -# Configuration is backward compatible -./hmac-file-server -config config.toml -``` - ---- - -## ๐Ÿ” **Problem Resolution** - -### Desktop Client Issues (SOLVED) -- **Problem**: Dino/Gajim upload failures after restart -- **Solution**: 48-hour session restoration + cache management tools -- **Tools**: `fix_xmpp_clients.sh` for automated cache clearing - -### Network Switching (PERFECTED) -- **Problem**: WiFi โ†” LTE transitions causing 404 errors -- **Solution**: Multi-layer grace period system with intelligent detection -- **Result**: Seamless connectivity across all network changes - -### Mobile Resilience (ENHANCED) -- **Problem**: Device standby breaking authentication -- **Solution**: 72-hour ultra-grace periods for mobile scenarios -- **Benefit**: Uninterrupted service even after extended offline periods - ---- - -## ๐Ÿ“Š **Performance & Compatibility** - -### Network Performance -- โœ… **Zero-downtime** network switching -- โœ… **Sub-second** authentication recovery -- โœ… **99.9% uptime** across network transitions -- โœ… **Multi-gigabit** transfer rates maintained - -### Client Compatibility -- โœ… **Conversations** (Android) - Full mobile optimization -- โœ… **Dino** (Desktop) - 48h session restoration -- โœ… **Gajim** (Desktop) - Enhanced cache management -- โœ… **ChatSecure** (iOS) - Network resilience features -- โœ… **All XMPP clients** - Universal compatibility layer - -### Platform Support -- โœ… **Linux** (amd64, arm64, armv7) -- โœ… **Docker** & **Podman** containers -- โœ… **systemd** integration -- โœ… **Multi-architecture** deployment - ---- - -## ๐ŸŽ‰ **What Makes "Nexus Infinitum" Special** - -### The Vision -"Nexus Infinitum" represents the concept of infinite connectivity - a server that adapts to any network topology, survives any connectivity challenge, and provides seamless file sharing across the boundless expanse of modern communication networks. - -### The Reality -- **Infinite reach** across network boundaries -- **Boundless compatibility** with all XMPP clients -- **Limitless resilience** to network changes -- **Endless reliability** for enterprise deployments - -### The Impact -This release eliminates the final barriers to seamless file sharing in complex network environments, creating a truly universal solution that works everywhere, every time, for everyone. - ---- - -## ๐Ÿ”ฎ **Looking Forward** - -HMAC File Server 3.3.0 "Nexus Infinitum" establishes the foundation for next-generation file sharing capabilities. Future releases will build upon this infinite connectivity platform to deliver even more advanced features and optimizations. - ---- - -## ๐Ÿ™ **Acknowledgments** - -Special thanks to the network resilience testing community and XMPP client developers who helped identify and resolve the complex interaction scenarios that 3.3.0 now handles seamlessly. - ---- - -*HMAC File Server 3.3.0 "Nexus Infinitum" - Infinite Connectivity, Boundless Possibilities* - -**Download:** https://git.uuxo.net/uuxo/hmac-file-server/releases/tag/v3.3.0 -**Documentation:** https://git.uuxo.net/uuxo/hmac-file-server/wiki -**Support:** https://git.uuxo.net/uuxo/hmac-file-server/issues - ---- - -๐Ÿš€ **Welcome to the age of Infinite Connectivity!** ๐Ÿš€ diff --git a/STABILITY_AUDIT_PLAN.md b/STABILITY_AUDIT_PLAN.md deleted file mode 100644 index e69de29..0000000 diff --git a/XMPP_CLIENT_ECOSYSTEM_ANALYSIS.md b/XMPP_CLIENT_ECOSYSTEM_ANALYSIS.md deleted file mode 100644 index 6ee8ee8..0000000 --- a/XMPP_CLIENT_ECOSYSTEM_ANALYSIS.md +++ /dev/null @@ -1,234 +0,0 @@ -# XMPP Client Ecosystem Analysis: XEP-0363 Compatibility -*HMAC File Server 3.3.0 "Nexus Infinitum" - Client Connectivity Research* - -## Executive Summary - -Our research reveals a robust XMPP client ecosystem with **excellent XEP-0363 support** across all major platforms. The **CORE HMAC authentication function remains untouchable** - it's the standardized protocol that ensures cross-client compatibility. - -## ๐ŸŒ Platform Coverage Analysis - -### ๐Ÿ“ฑ Android Clients -- **Conversations** (Primary Recommendation) - - โœ… **XEP-0363 HTTP File Upload**: NATIVE SUPPORT - - โœ… **HMAC Compatibility**: Uses standard XMPP authentication - - โœ… **Network Resilience**: Mobile-optimized with XEP-0198 Stream Management - - โœ… **Connection Switching**: WLANโ†”5G seamless transitions - - ๐Ÿ“Š **Market Position**: Most popular Android XMPP client (Google Play Store) - - ๐Ÿ›ก๏ธ **Security**: OMEMO encryption, GPLv3 open source - -- **Kaidan** (Cross-platform) - - โœ… **XEP-0363 Support**: Full implementation - - โœ… **Multi-Platform**: Android, iOS, Linux, Windows - - โœ… **Modern UI**: Native mobile experience - -### ๐Ÿ–ฅ๏ธ Desktop Clients (Linux/Windows/macOS) -- **Dino** (Linux Primary) - - โœ… **XEP-0363 HTTP File Upload**: Native support - - โœ… **HMAC Compatible**: Standard XMPP authentication - - โœ… **GTK4/Libadwaita**: Modern Linux integration - - ๐Ÿ“Š **Status**: Active development, v0.5 released 2025 - -- **Gajim** (Cross-platform Desktop) - - โœ… **XEP-0363 Support**: Full implementation - - โœ… **Python/GTK**: Windows, macOS, Linux - - โœ… **Feature Rich**: Professional chat client - - ๐Ÿ“Š **Status**: v2.3.4 released August 2025 - -- **Psi/Psi+** (Cross-platform) - - โœ… **Qt-based**: Windows, Linux, macOS - - โœ… **XEP-0363**: Supported - -### ๐ŸŽ iOS Clients -- **Monal** (Dedicated iOS/macOS) - - โœ… **XEP-0363 Support**: Full implementation - - โœ… **iOS Native**: App Store available - - โœ… **OMEMO**: End-to-end encryption - -- **ChatSecure** (iOS) - - โœ… **XEP-0363 Compatible** - - โœ… **Security Focus**: Tor support - -### ๐ŸŒ Web Clients -- **Converse.js** (Browser-based) - - โœ… **XEP-0363 Support**: Web implementation - - โœ… **CORS Compatible**: Works with our server - - โœ… **JavaScript**: Universal browser support - -- **Movim** (Web Platform) - - โœ… **XEP-0363 Support**: Social platform integration - -## ๐Ÿ”ง Technical Compatibility Matrix - -### XEP-0363 HTTP File Upload Protocol -``` -Standard Flow (ALL clients use this): -1. Client โ†’ XMPP Server: Request upload slot -2. XMPP Server โ†’ HTTP Upload Server: Generate slot with HMAC -3. HTTP Upload Server โ†’ Client: PUT URL + HMAC headers -4. Client โ†’ HTTP Upload Server: PUT file with HMAC authentication -5. HTTP Upload Server: Validates HMAC โ†’ 201 Created -``` - -### ๐Ÿ” HMAC Authentication Flow (IMMUTABLE) -Our server supports the **standard XEP-0363 authentication methods**: - -#### Method 1: Authorization Header (Most Common) -```http -PUT /upload/file.jpg -Authorization: Basic base64(hmac_signature) -Content-Length: 12345 -``` - -#### Method 2: Cookie Header -```http -PUT /upload/file.jpg -Cookie: auth=hmac_signature -Content-Length: 12345 -``` - -#### Method 3: Custom Headers (Extended) -```http -PUT /upload/file.jpg -X-HMAC-Signature: sha256=hmac_value -X-HMAC-Timestamp: 1234567890 -Content-Length: 12345 -``` - -## ๐Ÿš€ Network Resilience Client Support - -### Mobile Connection Switching (WLAN โ†” 5G) -- **XEP-0198 Stream Management**: **ALL modern clients support this** - - โœ… Conversations (Android) - - โœ… Monal (iOS) - - โœ… Dino (Linux) - - โœ… Gajim (Desktop) - - โœ… Kaidan (Cross-platform) - -### Connection Recovery Features -1. **5-minute resumption window** (XEP-0198) -2. **Automatic reconnection** -3. **Message queue preservation** -4. **Upload resumption** (client-dependent) - -## ๐ŸŽฏ RECOMMENDATIONS FOR WIDE CLIENT COMPATIBILITY - -### 1. โœ… KEEP HMAC CORE UNCHANGED -```toml -# This configuration ensures maximum compatibility -[hmac] -secret = "production_secret_here" -algorithm = "sha256" -v1_support = true # filename + " " + content_length -v2_support = true # filename + "\x00" + content_length + "\x00" + content_type -token_support = true # Simple token validation -``` - -### 2. โœ… HTTP Headers We Support (XEP-0363 Standard) -```go -// Our server correctly implements these headers for ALL clients -allowedHeaders := []string{ - "Authorization", // Most common - HMAC signature - "Cookie", // Alternative authentication - "Expires", // Upload timeout -} -``` - -### 3. โœ… CORS Configuration (Web Client Support) -```toml -[http] -cors_enabled = true -cors_origins = ["*"] -cors_methods = ["OPTIONS", "HEAD", "GET", "PUT"] -cors_headers = ["Authorization", "Content-Type", "Content-Length"] -cors_credentials = true -``` - -### 4. โœ… Network Resilience Integration -```toml -[network_resilience] -enabled = true -detection_interval = "1s" -quality_threshold = 0.7 -mobile_optimization = true -``` - -## ๐ŸŒŸ CLIENT ECOSYSTEM STRENGTHS - -### Cross-Platform Coverage -- **Android**: Conversations (dominant market share) -- **iOS**: Monal, ChatSecure -- **Linux**: Dino (GNOME), Gajim -- **Windows**: Gajim, Psi -- **macOS**: Gajim, Monal, Psi -- **Web**: Converse.js, Movim - -### Protocol Compliance -- **ALL major clients implement XEP-0363** -- **Standard HMAC authentication supported** -- **No custom modifications needed** -- **Forward compatibility assured** - -### Network Resilience -- **XEP-0198 Stream Management**: Universal support -- **Mobile optimization**: Built into protocol -- **Connection switching**: Transparent to users - -## โšก IMPLEMENTATION STRATEGY - -### Phase 1: Maintain Standards Compliance โœ… -- Keep HMAC authentication exactly as is -- Support standard XEP-0363 headers -- Maintain protocol compatibility - -### Phase 2: Enhanced Features (Optional) -- Extended CORS support for web clients -- Enhanced network resilience logging -- Upload resumption for mobile clients - -### Phase 3: Performance Optimization -- Chunked upload support (advanced clients) -- CDN integration (enterprise deployments) -- Load balancing (high-traffic scenarios) - -## ๐Ÿ” CRITICAL SUCCESS FACTORS - -### 1. Protocol Stability -- **HMAC authentication is CORE protocol** -- **Breaking changes would disconnect ALL clients** -- **Standards compliance ensures compatibility** - -### 2. Network Resilience -- **XEP-0198 handles connection switching** -- **Client-side resumption works automatically** -- **Our server provides robust upload handling** - -### 3. Security Maintenance -- **HMAC-SHA256 remains industry standard** -- **No security compromises for compatibility** -- **End-to-end encryption handled by clients** - -## ๐Ÿ“Š CONCLUSION - -The XMPP ecosystem provides **excellent coverage** for your connectivity requirements: - -### โœ… ACHIEVEMENTS -- **Wide client variety** across all platforms -- **Standard XEP-0363 support** in all major clients -- **HMAC authentication** works universally -- **Network resilience** built into XMPP protocol -- **Mobile optimization** native in modern clients - -### ๐ŸŽฏ ACTION ITEMS -1. **Deploy current server** - All fixes are compatible -2. **Keep HMAC unchanged** - It's the standard that works -3. **Document client recommendations** - Guide users to best clients -4. **Test with major clients** - Verify compatibility - -### ๐Ÿš€ FINAL VERDICT -**Our HMAC implementation is PERFECT for the XMPP ecosystem.** The wide variety of clients you requested already exists and works seamlessly with our server. The connectivity issues were server deployment problems, not protocol incompatibilities. - -**The CORE function with HMAC helps the entire range of clients stay connected through XEP-0363 perfectly!** - ---- -*Generated by HMAC File Server 3.3.0 "Nexus Infinitum" - Network Resilience Team* -*Date: August 24, 2025* diff --git a/XMPP_NETWORK_SWITCHING_SOLUTION.md b/XMPP_NETWORK_SWITCHING_SOLUTION.md deleted file mode 100644 index 2e8d070..0000000 --- a/XMPP_NETWORK_SWITCHING_SOLUTION.md +++ /dev/null @@ -1,511 +0,0 @@ -# ๐Ÿ”ง XMPP Network Switching Solution - 404 Error Fix - -## ๐Ÿšจ Problem Analysis: 5G โ†” WiFi Switching 404 Errors - -**Date:** August 26, 2025 -**Issue:** 404 errors when switching between 5G and WiFi networks during XMPP file uploads -**Root Cause:** Authentication tokens don't persist across network interface changes - ---- - -## ๐Ÿ” Technical Root Cause Analysis - -### XEP-0363 Protocol Requirements -Based on [XEP-0363 specification](https://xmpp.org/extensions/xep-0363.html): - -1. **Authorization Headers**: `Authorization`, `Cookie`, `Expires` are the only allowed headers -2. **Slot Timeout**: PUT URLs should have ~300s timeout for immediate upload -3. **Token Persistence**: No specification for cross-network authentication -4. **Upload Resumption**: Not defined in XEP-0363 core standard - -### Current Implementation Limitations - -```go -// Current bearer token validation - NO session storage -func validateBearerToken(r *http.Request, secret string) (*BearerTokenClaims, error) { - // โŒ ISSUE: Token only exists in memory during HTTP request - // โŒ ISSUE: No persistent session store for network switches - // โŒ ISSUE: IP change invalidates authentication context -} -``` - -**Problems Identified:** -1. **No Session Persistence**: Tokens aren't cached between network switches -2. **IP-Bound Authentication**: Authentication tied to network interface -3. **No Token Refresh**: No mechanism to refresh expiring tokens -4. **Memory-Only Storage**: Session state lost on connection drop - ---- - -## ๐Ÿ›ก๏ธ Comprehensive Solution: Session-Based Authentication - -### Phase 1: Session Storage Implementation - -```go -// NEW: Persistent session storage for network resilience -type NetworkResilientSession struct { - SessionID string `json:"session_id"` - UserJID string `json:"user_jid"` - OriginalToken string `json:"original_token"` - CreatedAt time.Time `json:"created_at"` - LastSeen time.Time `json:"last_seen"` - NetworkHistory []NetworkEvent `json:"network_history"` - UploadContext *UploadContext `json:"upload_context,omitempty"` - RefreshCount int `json:"refresh_count"` - MaxRefreshes int `json:"max_refreshes"` -} - -type NetworkEvent struct { - Timestamp time.Time `json:"timestamp"` - FromNetwork string `json:"from_network"` - ToNetwork string `json:"to_network"` - ClientIP string `json:"client_ip"` - UserAgent string `json:"user_agent"` -} - -type UploadContext struct { - Filename string `json:"filename"` - TotalSize int64 `json:"total_size"` - UploadedBytes int64 `json:"uploaded_bytes"` - ChunkSize int64 `json:"chunk_size"` - LastChunk int `json:"last_chunk"` - ETag string `json:"etag,omitempty"` -} - -// Global session store with Redis/Memory backend -var sessionStore *SessionStore - -type SessionStore struct { - storage map[string]*NetworkResilientSession - mutex sync.RWMutex - cleanupTicker *time.Ticker - redisClient *redis.Client // Optional Redis backend -} -``` - -### Phase 2: Enhanced Bearer Token Validation with Session Recovery - -```go -// ENHANCED: Bearer token validation with session recovery -func validateBearerTokenWithSession(r *http.Request, secret string) (*BearerTokenClaims, error) { - // Step 1: Try standard token validation - claims, err := validateBearerToken(r, secret) - if err == nil { - // Token valid - create/update session - sessionID := generateSessionID(claims.User, claims.Filename) - session := &NetworkResilientSession{ - SessionID: sessionID, - UserJID: claims.User, - OriginalToken: getBearerToken(r), - CreatedAt: time.Now(), - LastSeen: time.Now(), - MaxRefreshes: 10, // Allow 10 token refreshes - } - - // Detect network change - currentNetwork := detectNetworkContext(r) - if existingSession := sessionStore.GetSession(sessionID); existingSession != nil { - session.NetworkHistory = append(existingSession.NetworkHistory, NetworkEvent{ - Timestamp: time.Now(), - FromNetwork: getLastNetwork(existingSession), - ToNetwork: currentNetwork, - ClientIP: getClientIP(r), - UserAgent: r.Header.Get("User-Agent"), - }) - } - - sessionStore.StoreSession(sessionID, session) - - // Add session headers to response - setSessionHeaders(r, sessionID) - return claims, nil - } - - // Step 2: Token failed - try session recovery - sessionID := r.Header.Get("X-Session-ID") - if sessionID == "" { - sessionID = r.URL.Query().Get("session_id") - } - - if sessionID != "" { - session := sessionStore.GetSession(sessionID) - if session != nil { - // Check if session is still valid - if time.Since(session.CreatedAt) < 72*time.Hour { // 72-hour max session life - log.Infof("๐Ÿ”„ Session recovery: User %s, Session %s", session.UserJID, sessionID) - - // Generate new token for this session - newToken, err := refreshSessionToken(session, secret) - if err == nil { - // Update session - session.LastSeen = time.Now() - session.RefreshCount++ - sessionStore.StoreSession(sessionID, session) - - // Return claims from session - return &BearerTokenClaims{ - User: session.UserJID, - Filename: extractFilenameFromRequest(r), - Size: extractSizeFromRequest(r), - Expiry: time.Now().Add(24 * time.Hour).Unix(), - }, nil - } - } - } - } - - // Step 3: No valid token or session - return nil, fmt.Errorf("authentication failed: no valid token or session") -} -``` - -### Phase 3: XEP-0363 Compliant Token Refresh - -```go -// XEP-0363 compliant token refresh mechanism -func refreshSessionToken(session *NetworkResilientSession, secret string) (string, error) { - if session.RefreshCount >= session.MaxRefreshes { - return "", fmt.Errorf("maximum token refreshes exceeded") - } - - // Generate new HMAC token with extended validity - timestamp := time.Now().Unix() - expiry := timestamp + 86400 // 24 hours - - // Use network-resilient payload format - payload := fmt.Sprintf("%s\x00%s\x00%d\x00%d\x00%d\x00session_refresh", - session.UserJID, - "refresh", // Special filename for refresh - 0, // Size 0 for refresh - timestamp, - expiry) - - h := hmac.New(sha256.New, []byte(secret)) - h.Write([]byte(payload)) - token := base64.StdEncoding.EncodeToString(h.Sum(nil)) - - log.Infof("๐Ÿ†• Generated refresh token for session %s (refresh #%d)", - session.SessionID, session.RefreshCount+1) - - return token, nil -} - -// Network context detection for intelligent switching -func detectNetworkContext(r *http.Request) string { - clientIP := getClientIP(r) - userAgent := r.Header.Get("User-Agent") - xForwardedFor := r.Header.Get("X-Forwarded-For") - - // Detect network type based on IP ranges and headers - if strings.Contains(xForwardedFor, "10.") || strings.Contains(clientIP, "10.") { - return "cellular_lte" - } else if strings.Contains(clientIP, "192.168.") { - return "wifi_private" - } else if strings.Contains(userAgent, "Mobile") || strings.Contains(userAgent, "Android") { - return "mobile_unknown" - } - - return "wired_ethernet" -} -``` - -### Phase 4: Enhanced Upload Handler with Session Support - -```go -// Enhanced upload handler with session persistence -func handleUpload(w http.ResponseWriter, r *http.Request) { - // Step 1: Validate with session recovery - claims, err := validateBearerTokenWithSession(r, viper.GetString("hmac.secret")) - if err != nil { - http.Error(w, "Authentication failed", http.StatusUnauthorized) - return - } - - // Step 2: Handle upload with resumption support - sessionID := r.Header.Get("X-Session-ID") - if sessionID != "" { - session := sessionStore.GetSession(sessionID) - if session != nil && session.UploadContext != nil { - // Resume existing upload - return handleResumeUpload(w, r, session) - } - } - - // Step 3: Start new upload with session tracking - session := sessionStore.GetSession(sessionID) - if session != nil { - session.UploadContext = &UploadContext{ - Filename: claims.Filename, - TotalSize: claims.Size, - UploadedBytes: 0, - ChunkSize: 5 * 1024 * 1024, // 5MB chunks - } - sessionStore.StoreSession(sessionID, session) - } - - // Continue with standard upload handling... - handleStandardUpload(w, r, claims) -} - -// Session-aware upload resumption -func handleResumeUpload(w http.ResponseWriter, r *http.Request, session *NetworkResilientSession) { - ctx := session.UploadContext - - // Check upload progress - currentRange := r.Header.Get("Content-Range") - if currentRange != "" { - // Parse range and resume from last position - rangeStart, rangeEnd := parseContentRange(currentRange) - if rangeStart != ctx.UploadedBytes { - log.Warnf("โš ๏ธ Upload range mismatch: expected %d, got %d", ctx.UploadedBytes, rangeStart) - // Reset to last known good position - ctx.UploadedBytes = rangeStart - } - } - - log.Infof("๐Ÿ”„ Resuming upload for %s: %d/%d bytes (%0.1f%%)", - ctx.Filename, ctx.UploadedBytes, ctx.TotalSize, - float64(ctx.UploadedBytes)/float64(ctx.TotalSize)*100) - - // Continue upload from last position - // ... implement chunked upload logic -} -``` - ---- - -## ๐Ÿ”ง Implementation Steps - -### Step 1: Add Session Storage to main.go - -```bash -# Add to imports -import ( - "github.com/go-redis/redis/v8" // For Redis backend - "github.com/patrickmn/go-cache" // For memory fallback -) - -# Add global variables -var ( - sessionStore *SessionStore - sessionCache *cache.Cache -) -``` - -### Step 2: Initialize Session Store - -```go -// Add to main() function initialization -func initializeSessionStore() { - sessionCache = cache.New(72*time.Hour, 1*time.Hour) // 72h TTL, 1h cleanup - - sessionStore = &SessionStore{ - storage: make(map[string]*NetworkResilientSession), - cleanupTicker: time.NewTicker(30 * time.Minute), - } - - // Optional: Initialize Redis if available - if redisURL := viper.GetString("redis.url"); redisURL != "" { - opt, err := redis.ParseURL(redisURL) - if err == nil { - sessionStore.redisClient = redis.NewClient(opt) - log.Infof("๐Ÿ“Š Session store: Redis backend initialized") - } - } - - if sessionStore.redisClient == nil { - log.Infof("๐Ÿ“Š Session store: Memory backend initialized") - } - - // Start cleanup routine - go sessionStore.cleanupRoutine() -} -``` - -### Step 3: Update HTTP Handlers - -```go -// Replace validateBearerToken calls with validateBearerTokenWithSession -func uploadHandler(w http.ResponseWriter, r *http.Request) { - // Use enhanced validation - claims, err := validateBearerTokenWithSession(r, secret) - // ... rest of handler -} - -func statusHandler(w http.ResponseWriter, r *http.Request) { - // Add session status endpoint - if sessionID := r.URL.Query().Get("session_id"); sessionID != "" { - session := sessionStore.GetSession(sessionID) - if session != nil { - json.NewEncoder(w).Encode(session) - return - } - } - // ... standard status -} -``` - -### Step 4: Enhanced Configuration - -```toml -# Add to config.toml -[session_store] -enabled = true -backend = "memory" # or "redis" -max_sessions = 10000 -cleanup_interval = "30m" -max_session_age = "72h" -redis_url = "redis://localhost:6379/0" # Optional - -[network_resilience] -enabled = true -session_recovery = true -max_token_refreshes = 10 -upload_resumption = true -chunk_size = "5MB" -resume_timeout = "10m" -``` - ---- - -## ๐ŸŒ Internet Research: XEP-0363 Best Practices - -### XMPP Community Recommendations - -**From XEP-0363 Specification:** -- โœ… Use `Authorization` header for authentication -- โœ… Support `Cookie` header as alternative -- โœ… Include `Expires` header for timeout handling -- โœ… 300s recommended timeout for upload slots -- โš ๏ธ No standard for session persistence across networks - -**Community Solutions:** -1. **Prosody mod_http_upload**: Uses file-based session storage -2. **Ejabberd mod_http_upload**: Implements token refresh via IQ -3. **Tigase HTTP Upload**: Redis-based session management -4. **MongooseIM**: Event-driven session recovery - -### Industry Standards for Mobile Networks - -**3GPP Network Switching:** -- Session continuity during handovers -- IP address preservation mechanisms -- Application-layer session recovery - -**HTTP/2 and HTTP/3:** -- Connection migration support -- Stream resumption capabilities -- Network-aware retry strategies - ---- - -## ๐Ÿš€ Deployment Plan - -### Phase 1: Immediate Fix (30 minutes) -```bash -# 1. Add session storage to main.go -cp cmd/server/main.go cmd/server/main.go.backup -# Apply session storage patches - -# 2. Update configuration -cp config-mobile-resilient.toml config-session-resilient.toml -# Add session_store section - -# 3. Test network switching -./test_network_switching.sh -``` - -### Phase 2: Full Implementation (2 hours) -```bash -# 1. Implement Redis backend -go get github.com/go-redis/redis/v8 - -# 2. Add upload resumption -# Implement chunked upload handlers - -# 3. Add monitoring -# Implement session metrics -``` - -### Phase 3: Production Deployment (1 day) -```bash -# 1. Performance testing -# Load testing with network switches - -# 2. XMPP client testing -# Test with Conversations, Dino, Gajim - -# 3. Production rollout -# Gradual deployment with monitoring -``` - ---- - -## ๐Ÿ“Š Expected Results - -### Before (Current State) -``` -WiFi โ†’ 5G Switch: โŒ 404 Authentication Failed -Device Standby: โŒ Token expired, re-auth required -Upload Resume: โŒ Restart from beginning -Session Recovery: โŒ No session persistence -``` - -### After (With Session Storage) -``` -WiFi โ†’ 5G Switch: โœ… Seamless session recovery -Device Standby: โœ… 72-hour session persistence -Upload Resume: โœ… Resume from last chunk -Session Recovery: โœ… Cross-network authentication -``` - -### Performance Metrics -- **Session Recovery Success Rate**: >99% -- **Network Switch Tolerance**: 5G โ†” WiFi โ†” Ethernet -- **Upload Resumption**: Chunk-level precision -- **Authentication Persistence**: 72-hour maximum - ---- - -## ๐Ÿ” Security Considerations - -### Session Security -- โœ… **Session ID entropy**: 256-bit random session IDs -- โœ… **Token refresh limits**: Maximum 10 refreshes per session -- โœ… **Network validation**: Verify network transition patterns -- โœ… **Audit logging**: Complete session lifecycle tracking - -### XEP-0363 Compliance -- โœ… **Standard headers**: Authorization, Cookie, Expires only -- โœ… **Token format**: HMAC-SHA256 base64 encoding -- โœ… **Timeout handling**: 300s slot timeout + session recovery -- โœ… **Error responses**: Standard HTTP status codes - ---- - -## ๐Ÿงช Testing Strategy - -### Network Switching Tests -1. **WiFi โ†’ 5G transition** -2. **5G โ†’ WiFi transition** -3. **Ethernet โ†’ WiFi โ†’ 5G chain** -4. **Carrier IP address changes** -5. **Device standby scenarios** - -### XMPP Client Compatibility -1. **Conversations** (Android) -2. **Dino** (Linux/Windows) -3. **Gajim** (Cross-platform) -4. **Monal** (iOS/macOS) -5. **Siskin IM** (iOS) - -### Load Testing -1. **Concurrent sessions**: 1000+ simultaneous uploads -2. **Network switching**: 100 clients switching every 10s -3. **Session recovery**: 500 interrupted uploads -4. **Memory usage**: Session store efficiency - ---- - -*Generated by HMAC File Server 3.3.0 Analysis Team* -*Date: August 26, 2025* diff --git a/builds/hmac-file-server-darwin-amd64 b/builds/hmac-file-server-darwin-amd64 index e17b744..b70ad7b 100755 Binary files a/builds/hmac-file-server-darwin-amd64 and b/builds/hmac-file-server-darwin-amd64 differ diff --git a/builds/hmac-file-server-darwin-arm64 b/builds/hmac-file-server-darwin-arm64 index 7e65df5..3603366 100755 Binary files a/builds/hmac-file-server-darwin-arm64 and b/builds/hmac-file-server-darwin-arm64 differ diff --git a/builds/hmac-file-server-linux-386 b/builds/hmac-file-server-linux-386 index 446c230..b283fc4 100755 Binary files a/builds/hmac-file-server-linux-386 and b/builds/hmac-file-server-linux-386 differ diff --git a/builds/hmac-file-server-linux-amd64 b/builds/hmac-file-server-linux-amd64 index d624ad5..2b5706d 100755 Binary files a/builds/hmac-file-server-linux-amd64 and b/builds/hmac-file-server-linux-amd64 differ diff --git a/builds/hmac-file-server-linux-arm b/builds/hmac-file-server-linux-arm index aaabc33..ae410f7 100755 Binary files a/builds/hmac-file-server-linux-arm and b/builds/hmac-file-server-linux-arm differ diff --git a/builds/hmac-file-server-linux-arm64 b/builds/hmac-file-server-linux-arm64 index b3622fe..92ae039 100755 Binary files a/builds/hmac-file-server-linux-arm64 and b/builds/hmac-file-server-linux-arm64 differ diff --git a/ejabberd-module/EJABBERD_MODULE_PROPOSAL.md b/ejabberd-module/EJABBERD_MODULE_PROPOSAL.md deleted file mode 100644 index e225a10..0000000 --- a/ejabberd-module/EJABBERD_MODULE_PROPOSAL.md +++ /dev/null @@ -1,218 +0,0 @@ -# Ejabberd HMAC File Server Integration Module Proposal - -## Problem Analysis - -### Current Issues -- **Authentication Complexity**: XMPP clients need manual HMAC secret configuration -- **Re-authentication Failures**: Clients lose connection during network switches -- **Secret Management**: Shared secrets must be distributed to all clients -- **404 Upload Errors**: Direct HTTP upload authentication failures -- **Configuration Burden**: Each client needs individual HMAC setup - -## Proposed Solution: `mod_http_upload_hmac` - -### Architecture Overview -``` -XMPP Client โ†’ Ejabberd โ†’ mod_http_upload_hmac โ†’ HMAC File Server - โ†“ โ†“ โ†“ โ†“ - XEP-0363 Auth Check Generate Token Store File - Request & Quotas & Upload URL & Validate -``` - -### Module Features - -#### 1. Seamless Authentication -```erlang -% User authentication via existing XMPP session -authenticate_user(User, Server) -> - case ejabberd_auth:check_password(User, Server, undefined) of - true -> {ok, generate_upload_token(User, Server)}; - false -> {error, unauthorized} - end. -``` - -#### 2. Dynamic Token Generation -```erlang -% Generate time-limited upload tokens -generate_upload_token(User, Filename, Size) -> - Timestamp = unix_timestamp(), - Payload = iolist_to_binary([User, $\0, Filename, $\0, integer_to_binary(Size)]), - Token = crypto:mac(hmac, sha256, get_hmac_secret(), Payload), - {ok, base64:encode(Token), Timestamp + 3600}. % 1 hour expiry -``` - -#### 3. XEP-0363 Response Generation -```erlang -% Generate XEP-0363 compliant slot response -generate_slot_response(User, Filename, Size, ContentType) -> - {ok, Token, Expiry} = generate_upload_token(User, Filename, Size), - UUID = uuid:generate(), - PutURL = iolist_to_binary([get_upload_base_url(), "/", UUID, "/", Filename, - "?token=", Token, "&user=", User]), - GetURL = iolist_to_binary([get_download_base_url(), "/", UUID, "/", Filename]), - - #xmlel{name = <<"slot">>, - attrs = [{<<"xmlns">>, ?NS_HTTP_UPLOAD}], - children = [ - #xmlel{name = <<"put">>, - attrs = [{<<"url">>, PutURL}], - children = [ - #xmlel{name = <<"header">>, - attrs = [{<<"name">>, <<"Authorization">>}], - children = [{xmlcdata, <<"Bearer ", Token/binary>>}]} - ]}, - #xmlel{name = <<"get">>, - attrs = [{<<"url">>, GetURL}]} - ]}. -``` - -## Integration Benefits - -### For XMPP Clients -- โœ… **Zero Configuration**: No HMAC secrets needed -- โœ… **Automatic Authentication**: Uses existing XMPP session -- โœ… **Standard XEP-0363**: Full compliance with all clients -- โœ… **Error Reduction**: No more 404/authentication failures - -### For Administrators -- โœ… **Centralized Management**: All configuration in ejabberd -- โœ… **User Quotas**: Per-user upload limits -- โœ… **Audit Logging**: Complete upload tracking -- โœ… **Security**: Temporary tokens, no shared secrets - -### For HMAC File Server -- โœ… **Token Validation**: Simple Bearer token authentication -- โœ… **User Context**: Know which XMPP user uploaded files -- โœ… **Quota Integration**: Enforce limits from ejabberd -- โœ… **Simplified Auth**: No complex HMAC verification needed - -## Implementation Plan - -### Phase 1: Core Module -```erlang --module(mod_http_upload_hmac). --behaviour(gen_mod). - --export([start/2, stop/1, process_iq/1, mod_options/1]). - -% XEP-0363 IQ handler -process_iq(#iq{type = get, sub_el = #xmlel{name = <<"request">>}} = IQ) -> - User = jid:user(IQ#iq.from), - Server = jid:server(IQ#iq.from), - - % Extract file info from request - {Filename, Size, ContentType} = extract_file_info(IQ#iq.sub_el), - - % Check quotas and permissions - case check_upload_permission(User, Server, Size) of - ok -> - % Generate upload slot - SlotResponse = generate_slot_response(User, Filename, Size, ContentType), - IQ#iq{type = result, sub_el = SlotResponse}; - {error, Reason} -> - IQ#iq{type = error, sub_el = generate_error(Reason)} - end. -``` - -### Phase 2: HMAC Server Integration -```go -// Enhanced token validation in HMAC File Server -func validateBearerToken(token, user, filename string, size int64) error { - // Verify token with ejabberd shared secret - payload := fmt.Sprintf("%s\x00%s\x00%d", user, filename, size) - expectedToken := generateHMAC(payload, ejabberdSecret) - - if !hmac.Equal([]byte(token), []byte(expectedToken)) { - return errors.New("invalid token") - } - - // Check token expiry and user permissions - return validateTokenExpiry(token) -} -``` - -### Phase 3: Configuration Integration -```yaml -# ejabberd.yml -modules: - mod_http_upload_hmac: - hmac_server_url: "http://localhost:8080" - hmac_shared_secret: "your-secure-secret" - max_size: 104857600 # 100MB - quota_per_user: 1073741824 # 1GB - token_expiry: 3600 # 1 hour - allowed_extensions: [".jpg", ".png", ".pdf", ".mp4"] -``` - -## Migration Path - -### Current Setup โ†’ Module Integration -1. **Install Module**: Deploy `mod_http_upload_hmac` to ejabberd -2. **Configure Integration**: Set HMAC server URL and shared secret -3. **Update HMAC Server**: Add Bearer token authentication support -4. **Test Integration**: Verify XMPP clients work seamlessly -5. **Migrate Users**: Remove client-side HMAC configuration - -### Backward Compatibility -- โœ… **Dual Authentication**: Support both Bearer tokens and legacy HMAC -- โœ… **Gradual Migration**: Clients can migrate one by one -- โœ… **Fallback Support**: Legacy mode for non-integrated setups - -## Technical Specifications - -### Token Format -``` -Bearer -``` - -### API Enhancement -```http -PUT /upload/uuid/filename.ext?token=bearer_token&user=username -Authorization: Bearer -Content-Length: 12345 - -[file content] -``` - -### Response Format (Success) -```http -HTTP/1.1 201 Created -Content-Type: application/json - -{ - "success": true, - "filename": "filename.ext", - "size": 12345, - "user": "username@example.org", - "uploaded_at": "2025-08-25T10:30:00Z" -} -``` - -## Development Priority - -### High Priority Benefits -1. **Eliminate 404 Errors**: Solves current XMPP client issues -2. **Simplify Deployment**: No more client-side HMAC configuration -3. **Enhance Security**: Temporary tokens instead of shared secrets -4. **Improve UX**: Seamless file uploads for all XMPP clients - -### Implementation Effort -- **Ejabberd Module**: ~2-3 days development -- **HMAC Server Updates**: ~1 day integration -- **Testing & Documentation**: ~1 day -- **Total**: ~1 week for complete solution - -## Conclusion - -An ejabberd module would **dramatically improve** the HMAC File Server ecosystem by: -- โœ… Eliminating authentication complexity -- โœ… Providing seamless XMPP integration -- โœ… Solving current 404/re-auth issues -- โœ… Following XEP-0363 standards perfectly -- โœ… Enabling enterprise-grade user management - -**This is definitely worth implementing!** It would make HMAC File Server the most user-friendly XEP-0363 solution available. - ---- -*HMAC File Server 3.3.0 + Ejabberd Integration Proposal* -*Date: August 25, 2025*