hmac-file-server/ejabberd-module/README.md

Ejabberd HMAC File Server Integration Module

This directory contains mod_http_upload_hmac, an ejabberd module that provides seamless integration between XMPP clients and the HMAC File Server, implementing XEP-0363 HTTP File Upload with automatic authentication.

🎯 Problem Solved

Before: XMPP clients needed manual HMAC secret configuration, suffered from re-authentication failures, and experienced 404 upload errors.

After: Zero client configuration, automatic authentication via existing XMPP session, and seamless file uploads for all XEP-0363 compatible clients.

✨ Features

• 🔐 Seamless Authentication - Uses existing XMPP user session
• 🎫 Bearer Token Generation - Temporary, secure upload tokens
• 📱 Universal Client Support - Works with Conversations, Dino, Gajim, Monal
• 👥 User Management - Per-user quotas and permissions
• 📊 Audit Logging - Complete upload tracking
• 🔒 Enhanced Security - No shared secrets in clients
• ⚡ XEP-0363 Compliant - Standard HTTP File Upload protocol

🏗️ Architecture

XMPP Client → Ejabberd → mod_http_upload_hmac → HMAC File Server
     ↓           ↓              ↓                    ↓
  XEP-0363    Auth Check    Generate Token       Store File
  Request     & Quotas      & Upload URL         & Validate

📦 Installation

Quick Install

cd ejabberd-module
sudo ./install.sh

Manual Installation

1. Compile the module:

erlc -I /opt/ejabberd/lib/ejabberd-*/include -o . mod_http_upload_hmac.erl

2. Install to ejabberd:

sudo cp mod_http_upload_hmac.beam /opt/ejabberd/lib/ejabberd-*/ebin/
sudo chown ejabberd:ejabberd /opt/ejabberd/lib/ejabberd-*/ebin/mod_http_upload_hmac.beam

3. Configure 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"
      - ".mp3"
    iqdisc: one_queue

# Disable default mod_http_upload
# mod_http_upload: []

4. Update HMAC File Server:

[ejabberd_integration]
enabled = true
bearer_token_auth = true
shared_secret = "your-secure-secret"  # Same as ejabberd

5. Restart services:

sudo systemctl restart ejabberd
sudo systemctl restart hmac-file-server

🔧 Configuration Options

Option	Type	Default	Description
hmac_server_url	string	"http://localhost:8080"	HMAC File Server base URL
hmac_shared_secret	string	"default-secret-change-me"	Shared secret for token generation
max_size	integer	104857600	Maximum file size in bytes (100MB)
quota_per_user	integer	1073741824	User storage quota in bytes (1GB)
token_expiry	integer	3600	Token validity in seconds (1 hour)
allowed_extensions	list	[]	Allowed file extensions (empty = all)
iqdisc	atom	one_queue	IQ processing discipline

🚀 Usage

For XMPP Clients

No configuration required! Just use your XMPP client as normal:

1. Open any XEP-0363 compatible client (Conversations, Dino, Gajim)
2. Send a file in any chat
3. File uploads automatically using your XMPP credentials
4. No HMAC secrets or special configuration needed

For Administrators

Monitor uploads and manage users:

# Check ejabberd logs
journalctl -u ejabberd -f

# Check HMAC server logs  
journalctl -u hmac-file-server -f

# View user quotas (if implemented)
ejabberdctl get_user_quota username@domain.tld

🔐 Security

Authentication Flow

1. XMPP Client requests upload slot via XEP-0363
2. Ejabberd validates user via existing XMPP session
3. Module generates time-limited Bearer token with HMAC
4. Client uploads file with Bearer token to HMAC server
5. HMAC Server validates token and stores file

Token Format

Bearer <base64(hmac-sha256(user + filename + size + timestamp, secret))>

Security Benefits

• ✅ No shared secrets in XMPP clients
• ✅ Time-limited tokens (default 1 hour)
• ✅ User-based authentication via XMPP session
• ✅ Per-user quotas and permissions
• ✅ Audit trail for all uploads

🧪 Testing

Test Installation

# Check module loading
sudo ejabberdctl module_check mod_http_upload_hmac

# Test with XMPP client
# 1. Connect to your ejabberd server
# 2. Try uploading a file
# 3. Check logs for Bearer token authentication

Debug Mode

# In ejabberd.yml
log_level: debug

# Check detailed logs
journalctl -u ejabberd -f | grep "mod_http_upload_hmac"

📱 Client Compatibility

Client	Platform	Status	Notes
Conversations	Android	✅ Full Support	Native XEP-0363
Dino	Linux/Windows	✅ Full Support	Native XEP-0363
Gajim	Cross-platform	✅ Full Support	Plugin required
Monal	iOS/macOS	✅ Full Support	Native XEP-0363
Movim	Web	✅ Full Support	Web interface
Siskin IM	iOS	✅ Full Support	Native XEP-0363

🔄 Migration from Manual HMAC

Gradual Migration

1. Install module alongside existing setup
2. Test with one client to verify functionality
3. Remove HMAC config from clients one by one
4. Monitor logs to ensure all clients switch over
5. Disable legacy HMAC when all clients migrated

Backward Compatibility

The HMAC File Server supports both authentication methods simultaneously:

• ✅ Bearer tokens (ejabberd module)
• ✅ Legacy HMAC (manual client configuration)
• ✅ JWT tokens (if enabled)

🐛 Troubleshooting

Common Issues

"Module compilation failed"

# Install Erlang development tools
sudo apt-get install erlang-dev erlang-tools

"Authentication failed"

# Check shared secret matches
grep "hmac_shared_secret" /opt/ejabberd/conf/ejabberd.yml
grep "shared_secret" /etc/hmac-file-server/config.toml

"404 Upload errors"

# Verify HMAC server is running
systemctl status hmac-file-server

# Check URLs are correct
curl -I http://localhost:8080/health

Debug Steps

1. Check module loading:

sudo ejabberdctl modules | grep http_upload

2. Verify configuration:

sudo ejabberdctl get_option modules

3. Test token generation:

# Enable debug logging in ejabberd.yml
log_level: debug

4. Monitor both services:

# Terminal 1
journalctl -u ejabberd -f

# Terminal 2  
journalctl -u hmac-file-server -f

📋 Requirements

• ejabberd 20.01+ (tested with 23.x)
• Erlang/OTP 23+
• HMAC File Server 3.2.2+
• XMPP Client with XEP-0363 support

🔄 Updates

Version Compatibility

Module Version	ejabberd	HMAC Server	Features
1.0.0	20.01+	3.2.2+	Bearer tokens, basic auth
1.1.0	23.01+	3.2.2+	User quotas, audit logging

Upgrade Path

# Stop services
sudo systemctl stop ejabberd

# Update module
sudo cp new_mod_http_upload_hmac.beam /opt/ejabberd/lib/ejabberd-*/ebin/

# Start services  
sudo systemctl start ejabberd

🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Test with multiple XMPP clients
4. Submit pull request

Development Setup

# Clone repository
```bash
git clone https://git.uuxo.net/uuxo/hmac-file-server.git
cd hmac-file-server/ejabberd-module

# Test compilation
erlc -I /opt/ejabberd/lib/ejabberd-*/include mod_http_upload_hmac.erl

# Run tests
./test.sh

📄 License

Same as HMAC File Server - see main repository LICENSE file.

🆘 Support

• Issues: Git Issues
• Discussions: Git Discussions
• XMPP Chat: hmac-support@conference.example.org

---

🎉 Enjoy seamless XMPP file uploads with zero client configuration!