safeshare

module
v1.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2026 License: MIT

README

SafeShare - Secure Temporary File Sharing

Tests Go Report Card

A self-hosted secure file sharing service for temporary transfers with automatic expiration, cryptographically secure claim codes, and enterprise-grade security features.

Version: 1.5.1

Screenshots

Main Interface

SafeShare Main Interface Modern web interface with drag-drop upload, QR codes, dark mode, and PWA support

Admin Dashboard

Admin Dashboard Comprehensive admin dashboard for file management, user administration, and system configuration

User Dashboard

User Dashboard User dashboard for viewing upload history, managing files, and sharing with advanced features

Admin Login (Dark Theme)

Admin Login Dark Theme Beautiful dark mode with gradient background for admin authentication

Key Features

Core Capabilities
  • Chunked/Resumable Uploads - Large file support (>100MB) with pause/resume
  • Resumable Downloads - Browser-based download resume with progress tracking
  • HTTP/2 Support - Optimized performance with 250 concurrent streams
  • Progressive Web App (PWA) - Installable app with offline support
  • Automatic Expiration - Files auto-delete after configurable time
  • Download Limits - Optional max downloads per file
  • Password Protection - Optional bcrypt-hashed passwords for files
  • Claim Codes - Cryptographically secure, URL-safe identifiers
  • QR Code Generation - One-click QR codes for mobile sharing
  • File Checksums - SHA256 hashes for integrity verification
Security Features
  • Encryption at Rest - AES-256-GCM authenticated encryption
  • Multi-Factor Authentication (MFA/TOTP) - Two-factor authentication with authenticator apps
  • WebAuthn/FIDO2 - Hardware security key support (YubiKey, Windows Hello, Touch ID)
  • Single Sign-On (SSO/OIDC) - Enterprise SSO with Google, Azure AD, Okta, Auth0, Keycloak
  • API Token Authentication - Bearer tokens with scopes, rotation, audit logging, and expiration
  • User Authentication - Invite-only registration with role-based access
  • Admin Dashboard - Web-based administration with CSRF protection
  • IP Blocking - Block malicious IPs from uploads/downloads
  • Rate Limiting - IP-based DoS protection (configurable limits)
  • File Extension Blacklist - Blocks dangerous file types (executables, scripts)
  • Trusted Proxy Validation - Smart proxy header validation (anti-spoofing)
  • Security Headers - CSP, X-Frame-Options, X-Content-Type-Options
  • MIME Type Detection - Server-side content validation
  • Storage Quotas - Configurable per-application limits
  • Audit Logging - Comprehensive JSON-structured logs
User Management
  • Invite-Only Registration - Admin-managed user accounts
  • User Dashboard - View uploads, manage files, share with advanced features
  • File Management - Rename files, edit expiration, regenerate claim codes
  • Session Management - Secure httpOnly cookies with configurable expiry
  • Temporary Passwords - Forced password change on first login
  • Role-Based Access - User and admin roles with different permissions
  • Anonymous Uploads - Configurable (enabled by default, can require authentication)
Admin Dashboard
  • File Management - View all files, search, bulk delete, download statistics
  • User Administration - Create, edit, enable/disable, reset passwords
  • MFA Management - View and manage user MFA status, disable MFA for emergency recovery
  • SSO Provider Management - Configure OIDC providers, test connections, auto-provisioning
  • API Token Management - View all tokens, bulk operations (revoke, extend), usage statistics
  • Webhook Management - Configure webhooks for file lifecycle events (uploaded, downloaded, deleted, expired)
  • Backup Management - Schedule automated backups, download backups, retention policies
  • IP Blocking - Block/unblock IPs with reason tracking
  • Enterprise Features - Runtime feature toggles (MFA, SSO, Webhooks, API Tokens, Backups)
  • Dynamic Settings - Adjust quotas, limits, security settings without restart
  • Configuration Assistant - Intelligent config recommendations based on environment
  • Real-Time Statistics - Storage usage, file counts, user counts, quota metrics
  • Partial Upload Management - Monitor and cleanup abandoned chunked uploads
Monitoring & Operations
  • Health Check Endpoints - Comprehensive, liveness, and readiness probes
  • Prometheus Metrics - Full metrics export for monitoring and alerting
  • Structured Logging - JSON logs for aggregation tools (ELK, Splunk, Datadog)
  • Graceful Shutdown - Safe container stop with request completion
  • Background Workers - Auto-cleanup of expired files and abandoned uploads
  • Database Migrations - Automatic schema versioning and upgrades
Enterprise Features
  • PostgreSQL Backend - Production-grade database for high-availability deployments
  • S3-Compatible Storage - Object storage support (AWS S3, MinIO, DigitalOcean Spaces)
  • High Availability - Multi-node deployments with shared storage and distributed locking
  • Automated Backups - Scheduled backups with cron expressions and retention policies
  • Webhook Notifications - Real-time event notifications for integrations (Gotify, ntfy.sh, Discord)
  • Advanced API Tokens - Token rotation, usage tracking, bulk operations, expiration warnings
  • Feature Flags - Runtime feature toggles without container restarts
Deployment
  • Single Binary - No external dependencies (pure Go, embedded SQLite)
  • Docker Container - Minimal ~26MB Alpine-based image
  • Reverse Proxy Ready - Works with Traefik, nginx, Caddy, Apache
  • CDN Compatible - Supports Cloudflare and other CDNs
  • PostgreSQL Support - Optional PostgreSQL backend for enterprise deployments
  • S3 Storage Support - Optional S3-compatible object storage backend
  • No CGO Required - Portable across architectures (amd64, arm64)

Quick Start

Web UI

Simply visit the root URL after starting the server:

http://localhost:8080/              # Main upload interface
http://localhost:8080/admin/login   # Admin dashboard (if configured)
http://localhost:8080/login         # User login

Features drag-drop upload, QR code generation, PWA installation, and one-click sharing!

Docker
# Basic deployment (anonymous uploads)
docker run -d \
  -p 8080:8080 \
  -v safeshare-data:/app/data \
  -v safeshare-uploads:/app/uploads \
  --name safeshare \
  fjmerc/safeshare:latest

# Production deployment with encryption and admin dashboard
docker run -d \
  -p 8080:8080 \
  -e ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD="YourSecurePassword123!" \
  -e QUOTA_LIMIT_GB=100 \
  -e TZ=Europe/Berlin \
  -v safeshare-data:/app/data \
  -v safeshare-uploads:/app/uploads \
  --name safeshare \
  fjmerc/safeshare:latest

# Visit http://localhost:8080/admin/login
Binary
# Download latest release
wget https://github.com/fjmerc/safeshare/releases/latest/download/safeshare-linux-amd64

# Make executable
chmod +x safeshare-linux-amd64

# Run (uses default settings)
./safeshare-linux-amd64

# Or with custom configuration
export MAX_FILE_SIZE=209715200  # 200MB
export DEFAULT_EXPIRATION_HOURS=48
export ADMIN_USERNAME=admin
export ADMIN_PASSWORD=admin123
./safeshare-linux-amd64

API Quick Start

Simple Upload & Download
# Upload a file
curl -X POST -F "file=@document.pdf" \
  http://localhost:8080/api/upload | jq .

# Response includes claim code
{
  "claim_code": "Xy9kLm8pQz4vDwE",
  "download_url": "http://localhost:8080/api/claim/Xy9kLm8pQz4vDwE",
  "expires_at": "2025-11-22T10:00:00Z",
  "file_size": 1048576
}

# Download the file
curl -O http://localhost:8080/api/claim/Xy9kLm8pQz4vDwE
With Options
# Upload with expiration, download limit, and password
curl -X POST \
  -F "file=@sensitive.pdf" \
  -F "expires_in_hours=24" \
  -F "max_downloads=1" \
  -F "password=secret123" \
  http://localhost:8080/api/upload | jq .

# Download with password
curl -O "http://localhost:8080/api/claim/Xy9kLm8pQz4vDwE?password=secret123"
Get File Info (Without Downloading)
# Check file metadata
curl "http://localhost:8080/api/claim/Xy9kLm8pQz4vDwE/info" | jq .

# Response
{
  "claim_code": "Xy9kLm8pQz4vDwE",
  "original_filename": "document.pdf",
  "file_size": 1048576,
  "downloads_remaining": 4,
  "expires_at": "2025-11-22T10:00:00Z",
  "password_protected": false,
  "sha256_hash": "a3b2c1d4..."
}

Full API Documentation: See docs/API_REFERENCE.md for complete endpoint details, authentication, user management, admin operations, health checks, and Prometheus metrics.

Configuration

SafeShare is configured via environment variables. Common settings:

Variable Default Description
PORT 8080 HTTP server port
MAX_FILE_SIZE 104857600 Max file size in bytes (100MB)
DEFAULT_EXPIRATION_HOURS 24 Default file expiration
ENCRYPTION_KEY (empty) AES-256 key (64 hex chars) - enables encryption
ADMIN_USERNAME (empty) Admin username - enables dashboard
ADMIN_PASSWORD (empty) Admin password (min 8 chars)
REQUIRE_AUTH_FOR_UPLOAD false Require user authentication for uploads
QUOTA_LIMIT_GB 0 Storage quota in GB (0 = unlimited)
RATE_LIMIT_UPLOAD 10 Uploads per hour per IP
RATE_LIMIT_DOWNLOAD 50 Downloads per hour per IP
PUBLIC_URL (empty) Public URL for download links (e.g., https://share.domain.com)
DOWNLOAD_URL (empty) Separate URL for downloads (bypasses CDN timeouts)
CHUNKED_UPLOAD_ENABLED true Enable chunked uploads
CHUNK_SIZE 10485760 Chunk size in bytes (10MB)
READ_TIMEOUT 120 HTTP read timeout (seconds)
WRITE_TIMEOUT 120 HTTP write timeout (seconds)
TZ UTC Timezone for container

Advanced Configuration:

  • TRUST_PROXY_HEADERS - Proxy header validation (auto, true, false)
  • TRUSTED_PROXY_IPS - Comma-separated trusted proxy IPs/CIDR ranges
  • MAX_EXPIRATION_HOURS - Maximum allowed expiration (default: 168 hours / 7 days)
  • BLOCKED_EXTENSIONS - Comma-separated blocked file extensions
  • DB_PATH, UPLOAD_DIR, CLEANUP_INTERVAL_MINUTES, SESSION_EXPIRY_HOURS
  • CHUNKED_UPLOAD_THRESHOLD, PARTIAL_UPLOAD_EXPIRY_HOURS, HTTPS_ENABLED

Configuration Assistant: The admin dashboard includes an intelligent configuration assistant that analyzes your deployment environment and provides optimized settings recommendations.

Documentation

Comprehensive documentation is available in the docs/ directory:

Document Description
API_REFERENCE.md Complete API documentation with all endpoints, authentication, and examples
SECURITY.md Enterprise security features, encryption, admin dashboard security, best practices
SSO_SETUP.md SSO/OIDC configuration guide with provider-specific examples
MFA_SETUP.md Multi-factor authentication setup guide
BACKUP_RESTORE.md Backup and restore system documentation
CHUNKED_UPLOAD.md Chunked/resumable upload API, architecture, client implementation guide
REVERSE_PROXY.md Reverse proxy configuration (Traefik, nginx, Caddy, Apache)
PROMETHEUS.md Prometheus metrics, Grafana dashboards, alerting rules
HTTP_RANGE_SUPPORT.md Resumable downloads, HTTP Range requests (RFC 7233)
PRODUCTION.md Production deployment guide with security hardening
INFRASTRUCTURE_PLANNING.md CDN timeouts, upload speed testing, configuration planning
ARCHITECTURE.md Detailed technical architecture, PostgreSQL/S3 backends
FRONTEND.md Web UI features, customization guide, browser compatibility
TESTING.md Testing guide, test suite, coverage requirements
VERSION_STRATEGY.md Semantic versioning, Git Flow, release process
CHANGELOG.md Complete version history with all changes
CLAUDE.md Developer guide, architecture overview, build commands

Quick Links:

Architecture

SafeShare Application
├── HTTP Server (net/http) with HTTP/2 support
│   ├── Public API: Upload, Download, Claim Info, Health, Metrics
│   ├── Chunked Upload: Init, Chunk, Complete, Status
│   ├── User Auth: Login, Logout, Dashboard, File Management
│   └── Admin Dashboard: Files, Users, IPs, Settings, Config Assistant
├── SQLite Database (modernc.org/sqlite - pure Go, no CGO)
│   ├── Tables: files, users, sessions, partial_uploads, blocked_ips, settings
│   └── Migrations: Automatic schema versioning (6 migrations)
├── File Storage
│   ├── Completed files: UUID filenames (encrypted if ENCRYPTION_KEY set)
│   └── Partial uploads: .partial/{upload_id}/chunk_{number}
├── Middleware
│   ├── Authentication (user & admin), IP Blocking, Rate Limiting
│   ├── CSRF Protection, Security Headers, Logging, Metrics Collection
│   └── Proxy Header Validation (anti-spoofing)
└── Background Workers
    ├── Expired File Cleanup (configurable interval)
    ├── Partial Upload Cleanup (abandoned uploads)
    ├── Assembly Recovery (interrupted chunked uploads)
    └── Session Cleanup (expired auth sessions)

Key Technologies:

  • Go 1.21+ - Single binary, no external dependencies
  • SQLite - Embedded database with WAL mode (modernc.org/sqlite)
  • HTTP/2 - Concurrent stream multiplexing (h2c support)
  • Embedded Frontend - HTML/CSS/JS bundled in binary (27KB total)
  • Service Worker - PWA with offline support

Building from Source

Prerequisites
  • Go 1.21 or later
  • Docker (optional, for containerized builds)
Build Binary
# Clone repository
git clone https://github.com/fjmerc/safeshare
cd safeshare

# Build
go build -o safeshare ./cmd/safeshare

# Run
./safeshare
Build Docker Image
# Build image
docker build -t safeshare:latest .

# Check image size (~26MB)
docker images safeshare

# Run container
docker run -d -p 8080:8080 --name safeshare safeshare:latest

Performance

  • Startup time: < 1 second
  • Memory usage: ~10-20 MB baseline
  • Disk usage: File size + ~2KB per file record
  • Concurrent requests: 1000+ concurrent connections
  • SQLite optimizations: WAL mode, performance indexes, temp_store=MEMORY
  • Chunked upload: 250 concurrent streams (HTTP/2)
  • Encryption throughput: ~50-60 MB/s (tested on ARM VPS)

Security Best Practices

Production Deployments:

  1. Always use encryption: Set ENCRYPTION_KEY (64 hex chars)
  2. Enable admin authentication: Set ADMIN_USERNAME and ADMIN_PASSWORD
  3. Use HTTPS: Configure reverse proxy with TLS certificates
  4. Set storage quota: Use QUOTA_LIMIT_GB to prevent disk abuse
  5. Configure rate limits: Adjust RATE_LIMIT_UPLOAD and RATE_LIMIT_DOWNLOAD
  6. Block dangerous extensions: Customize BLOCKED_EXTENSIONS
  7. Use trusted proxies only: Configure TRUST_PROXY_HEADERS=auto (default)
  8. Enable audit logging: Forward logs to SIEM/log aggregation
  9. Monitor metrics: Set up Prometheus + Grafana dashboards
  10. Regular backups: Backup database and encryption key securely

Security Guide: See docs/SECURITY.md for complete security documentation, compliance mapping (HIPAA, SOC 2, GDPR, PCI-DSS), and security audit checklist.

Troubleshooting

Container Won't Start
# Check logs
docker logs safeshare

# Common issues:
# - Port 8080 already in use
# - Insufficient volume permissions
# - Invalid environment variables
Upload Fails

Check:

  • File size is within MAX_FILE_SIZE limit
  • Disk space available (requires >1GB free)
  • Storage quota not exceeded
  • File extension not in BLOCKED_EXTENSIONS
  • Rate limit not exceeded
Large Files Timeout

For files >100MB:

  • Ensure CHUNKED_UPLOAD_ENABLED=true (default)
  • Increase READ_TIMEOUT and WRITE_TIMEOUT if needed
  • Configure DOWNLOAD_URL to bypass CDN timeouts
  • See docs/INFRASTRUCTURE_PLANNING.md
Database Issues
# Reset database (CAUTION: deletes all data)
docker stop safeshare
docker rm safeshare
docker volume rm safeshare-data
docker run -d -p 8080:8080 \
  -v safeshare-data:/app/data \
  -v safeshare-uploads:/app/uploads \
  safeshare:latest

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes following Git Flow (docs/VERSION_STRATEGY.md)
  4. Add tests if applicable (minimum 60% coverage)
  5. Update documentation (README, CHANGELOG, API docs)
  6. Submit a pull request to develop branch

Development Guide: See CLAUDE.md for architecture overview, build commands, testing procedures, and Git Flow workflow.

License

MIT License - See LICENSE file for details.

Changelog

See docs/CHANGELOG.md for complete version history.

Latest Release (v1.5.0):

  • Single Sign-On (SSO/OIDC) support for enterprise deployments
  • WebAuthn/FIDO2 hardware key and MFA/TOTP authentication
  • PostgreSQL database backend and S3-compatible storage
  • Automated backup scheduler with retention policies
  • Enterprise feature management UI

Support

Built with Go

Directories

Path Synopsis
cmd
import-file command
migrate-chunks command
migrate-encryption command
safeshare command
safeshare-backup command
internal
auth/sso
Package sso provides Single Sign-On authentication providers.
 Package sso provides Single Sign-On authentication providers.
backup
Package backup provides functionality for creating and restoring SafeShare backups.
 Package backup provides functionality for creating and restoring SafeShare backups.
config
database
handlers
Package handlers provides HTTP request handlers for the SafeShare application.
 Package handlers provides HTTP request handlers for the SafeShare application.
metrics
middleware
models
repository
Package repository provides interfaces for data access.
 Package repository provides interfaces for data access.
repository/mock
Package mock provides mock implementations of repository interfaces for testing.
 Package mock provides mock implementations of repository interfaces for testing.
repository/postgres
Package postgres provides PostgreSQL implementations of repository interfaces.
 Package postgres provides PostgreSQL implementations of repository interfaces.
repository/sqlite
Package sqlite provides SQLite implementations of repository interfaces.
 Package sqlite provides SQLite implementations of repository interfaces.
static
storage
Package storage provides abstraction for file storage operations.
 Package storage provides abstraction for file storage operations.
storage/filesystem
Package filesystem implements the StorageBackend interface for local filesystem storage.
 Package filesystem implements the StorageBackend interface for local filesystem storage.
storage/mock
Package mock provides a mock implementation of the storage.StorageBackend interface for testing.
 Package mock provides a mock implementation of the storage.StorageBackend interface for testing.
storage/s3
Package s3 implements encrypted storage for S3 using SFSE1 streaming encryption.
 Package s3 implements encrypted storage for S3 using SFSE1 streaming encryption.
testutil
utils
Package utils provides utility functions for SafeShare.
 Package utils provides utility functions for SafeShare.
webauthn
Package webauthn provides WebAuthn/FIDO2 authentication support for SafeShare.
 Package webauthn provides WebAuthn/FIDO2 authentication support for SafeShare.
webhooks
sdk
go module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.