{"id":30453476,"url":"https://github.com/anans-dev/cirrussync-api","last_synced_at":"2026-04-21T03:31:06.512Z","repository":{"id":310810084,"uuid":"1041350031","full_name":"anans-dev/CirrusSync-API","owner":"anans-dev","description":"🔐 Secure, end-to-end encrypted cloud storage API built with Go. Features SRP authentication, multi-factor auth, file sharing, S3 storage, and comprehensive security. Production-ready with Docker, PostgreSQL, Redis, and extensive API documentation. ","archived":false,"fork":false,"pushed_at":"2025-08-20T11:05:28.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-20T11:58:18.399Z","etag":null,"topics":["gin-framework","go","redis","srp"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anans-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-20T11:05:26.000Z","updated_at":"2025-08-20T11:17:28.000Z","dependencies_parsed_at":"2025-08-20T11:58:21.645Z","dependency_job_id":"ec633896-a723-4091-8cff-a67ddbde8eb6","html_url":"https://github.com/anans-dev/CirrusSync-API","commit_stats":null,"previous_names":["anans-dev/cirrussync-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/anans-dev/CirrusSync-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anans-dev%2FCirrusSync-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anans-dev%2FCirrusSync-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anans-dev%2FCirrusSync-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anans-dev%2FCirrusSync-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anans-dev","download_url":"https://codeload.github.com/anans-dev/CirrusSync-API/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anans-dev%2FCirrusSync-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271755339,"owners_count":24815379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gin-framework","go","redis","srp"],"created_at":"2025-08-23T16:00:42.474Z","updated_at":"2026-04-21T03:31:06.484Z","avatar_url":"https://github.com/anans-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CirrusSync API\n\nA secure, end-to-end encrypted cloud storage API built with Go, featuring advanced authentication, file sharing, and multi-tenant storage management.\n\n## 🚀 Features\n\n### Core Functionality\n- **Secure File Storage**: End-to-end encrypted file storage with AWS S3 backend\n- **Drive Volumes**: Multi-tenant storage volumes with configurable size limits\n- **File Sharing**: Advanced sharing capabilities with permission management\n- **File Versioning**: Complete revision history and rollback capabilities\n- **Thumbnail Generation**: Automatic thumbnail generation for media files\n\n### Authentication \u0026 Security\n- **SRP Authentication**: Secure Remote Password protocol implementation\n- **Multi-Factor Authentication**: TOTP, Email, and SMS-based 2FA\n- **JWT Tokens**: RSA-signed access and refresh tokens\n- **CSRF Protection**: Built-in Cross-Site Request Forgery protection\n- **Security Events**: Comprehensive audit logging and monitoring\n- **Device Management**: Track and manage user devices\n\n### User Management\n- **User Profiles**: Complete user account management\n- **Session Management**: Secure session handling with Redis\n- **Recovery Kits**: Account recovery mechanisms\n- **Billing Integration**: Stripe integration for subscriptions\n- **Notification System**: Email and SMS notifications\n\n### Infrastructure\n- **Graceful Shutdown**: Proper cleanup and shutdown procedures\n- **Health Monitoring**: Sentry integration for error tracking\n- **Redis Caching**: High-performance caching layer\n- **Database Migrations**: Automated schema management\n- **CORS Support**: Cross-origin resource sharing configuration\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Frontend      │────│   CirrusSync    │────│   PostgreSQL    │\n│   Applications  │    │   API Server    │    │   Database      │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n                              │\n                              ├─────────────────┐\n                              │                 │\n                       ┌─────────────────┐    ┌─────────────────┐\n                       │   Redis Cache   │    │   AWS S3        │\n                       │   \u0026 Sessions    │    │   File Storage  │\n                       └─────────────────┘    └─────────────────┘\n```\n\n## 🛠️ Technology Stack\n\n- **Language**: Go 1.24.2\n- **Web Framework**: Gin\n- **Database**: PostgreSQL with GORM ORM\n- **Cache**: Redis\n- **File Storage**: AWS S3\n- **Authentication**: JWT + SRP\n- **Monitoring**: Sentry\n- **Development**: Air (hot reload)\n\n## 📦 Installation\n\n### Prerequisites\n\n- Go 1.24.2 or higher\n- PostgreSQL 12+\n- Redis 6+\n- AWS S3 bucket (or S3-compatible storage)\n\n### Clone Repository\n\n```bash\ngit clone https://github.com/anans9/cirrussync-api.git\ncd cirrussync-api\n```\n\n### Install Dependencies\n\n```bash\ngo mod download\n```\n\n### Generate RSA Keys\n\n```bash\nmkdir -p keys\n# Generate private key\nopenssl genrsa -out keys/private.pem 2048\n# Generate public key\nopenssl rsa -in keys/private.pem -pubout -out keys/public.pem\n```\n\n## ⚙️ Configuration\n\nCreate environment configuration files:\n\n### `.env` (Base Configuration)\n\n```env\n# Server Configuration\nPORT=8000\nHOST=localhost\nENVIRONMENT=development\nREQUEST_TIMEOUT=30\nSHUTDOWN_TIMEOUT=10\n\n# Database Configuration\nDB_HOST=localhost\nDB_PORT=5432\nDB_NAME=cirrussync\nDB_USER=postgres\nDB_PASSWORD=your_password\nDB_SSL_MODE=disable\nDB_TIMEZONE=UTC\nDB_MAX_OPEN_CONNS=25\nDB_MAX_IDLE_CONNS=10\nDB_CONN_MAX_LIFETIME=300\nMIGRATE_ON_BOOT=true\n\n# Redis Configuration\nREDIS_ADDR=localhost:6379\nREDIS_PASSWORD=\nREDIS_DB=0\nREDIS_MAX_RETRIES=3\nREDIS_POOL_SIZE=10\n\n# AWS S3 Configuration\nS3_REGION=us-east-1\nS3_BUCKET_NAME=your-bucket-name\nS3_ACCESS_KEY_ID=your-access-key\nS3_SECRET_ACCESS_KEY=your-secret-key\nS3_ENDPOINT=  # Optional: for S3-compatible services\n\n# CSRF Protection\nCSRF_SECRET=your-32-char-secret-key-here\nCSRF_SECURE=false\n\n# Mail Configuration (SMTP)\nMAIL_SMTP_HOST=smtp.gmail.com\nMAIL_SMTP_PORT=587\nMAIL_SMTP_USERNAME=your-email@gmail.com\nMAIL_SMTP_PASSWORD=your-app-password\nMAIL_FROM_ADDRESS=noreply@cirrussync.com\nMAIL_FROM_NAME=CirrusSync\n\n# TOTP Configuration\nTOTP_ISSUER=CirrusSync\nTOTP_ACCOUNT_NAME=CirrusSync Account\n\n# Monitoring (Optional)\nSENTRY_DSN=your-sentry-dsn\nAPP_VERSION=1.0.0\n```\n\n### Database Setup\n\n```bash\n# Create database\ncreatedb cirrussync\n\n# The application will automatically run migrations on startup\n# when MIGRATE_ON_BOOT=true\n```\n\n## 🚀 Running the Application\n\n### Development Mode (with hot reload)\n\n```bash\n# Install Air for hot reloading\ngo install github.com/cosmtrek/air@latest\n\n# Run with hot reload\nair\n```\n\n### Production Mode\n\n```bash\n# Build the application\ngo build -o cirrussync-api cmd/main.go\n\n# Run the application\n./cirrussync-api\n```\n\n### Using Docker (Optional)\n\n```dockerfile\n# Dockerfile example\nFROM golang:1.24.2-alpine AS builder\n\nWORKDIR /app\nCOPY go.mod go.sum ./\nRUN go mod download\n\nCOPY . .\nRUN go build -o cirrussync-api cmd/main.go\n\nFROM alpine:latest\nRUN apk --no-cache add ca-certificates\nWORKDIR /root/\n\nCOPY --from=builder /app/cirrussync-api .\nCOPY --from=builder /app/keys ./keys\n\nCMD [\"./cirrussync-api\"]\n```\n\n## 📚 API Documentation\n\n### Base URL\n```\nhttp://localhost:8000/api/v1\n```\n\n### Authentication\n\nThe API uses JWT tokens for authentication. Most endpoints require a valid JWT token in the Authorization header:\n\n```\nAuthorization: Bearer \u003cyour-jwt-token\u003e\n```\n\n### Core Endpoints\n\n#### Authentication\n- `POST /auth/register` - User registration\n- `POST /auth/login/challenge` - SRP login challenge\n- `POST /auth/login/verify` - SRP login verification\n- `POST /auth/refresh` - Refresh JWT token\n- `POST /auth/logout` - User logout\n- `GET /auth/me` - Get current user info\n\n#### Users\n- `GET /users/profile` - Get user profile\n- `PUT /users/profile` - Update user profile\n- `DELETE /users/account` - Delete user account\n\n#### Sessions\n- `GET /sessions` - List user sessions\n- `DELETE /sessions/:id` - Revoke specific session\n- `DELETE /sessions/all` - Revoke all sessions\n\n#### Multi-Factor Authentication\n- `GET /mfa/methods` - List MFA methods\n- `POST /mfa/totp/setup` - Setup TOTP\n- `POST /mfa/totp/verify` - Verify TOTP\n- `POST /mfa/email/send` - Send email code\n- `POST /mfa/sms/send` - Send SMS code\n\n#### Drive \u0026 Files\n- `GET /drive/volumes` - List drive volumes\n- `POST /drive/volumes` - Create new volume\n- `GET /drive/volumes/:id/items` - List items in volume\n- `POST /drive/upload` - Upload file\n- `GET /drive/download/:id` - Download file\n- `POST /drive/share` - Share file/folder\n- `GET /drive/shared` - List shared items\n\n#### Utility\n- `GET /csrf/token` - Get CSRF token\n\n## 🔒 Security Features\n\n### SRP Authentication\nThe API implements the Secure Remote Password (SRP) protocol for zero-knowledge password authentication:\n\n1. Client requests login challenge\n2. Server responds with salt and challenge\n3. Client computes proof using password\n4. Server verifies proof without knowing password\n\n### Encryption\n- All file data is encrypted at rest\n- Transport layer security with HTTPS\n- JWT tokens signed with RSA keys\n- Password hashing with bcrypt\n\n### Security Headers\n- CSRF protection enabled\n- CORS properly configured\n- Security headers set automatically\n\n## 🧪 Development\n\n### Project Structure\n\n```\n├── api/v1/              # API handlers\n│   ├── auth/           # Authentication endpoints\n│   ├── drive/          # File storage endpoints\n│   ├── mfa/            # Multi-factor auth endpoints\n│   ├── sessions/       # Session management\n│   └── users/          # User management\n├── cmd/                # Application entry point\n├── internal/           # Private application code\n│   ├── auth/          # Authentication service\n│   ├── drive/         # Drive service\n│   ├── jwt/           # JWT service\n│   ├── middleware/    # HTTP middleware\n│   ├── models/        # Database models\n│   └── user/          # User service\n├── pkg/               # Public packages\n│   ├── config/        # Configuration\n│   ├── db/            # Database connection\n│   ├── redis/         # Redis connection\n│   └── s3/            # S3 client\n└── router/            # HTTP router setup\n```\n\n## 🐛 Debugging\n\n### Enable Debug Logging\n\nSet environment variable:\n```bash\nexport GIN_MODE=debug\n```\n\n### Health Checks\n\nThe application provides several health check endpoints:\n\n- Database connectivity\n- Redis connectivity\n- S3 connectivity\n\n### Monitoring\n\nIntegration with Sentry for error monitoring:\n- Automatic error collection\n- Performance monitoring\n- Custom event tracking\n\n## 🚀 Deployment\n\n### Environment Variables\n\nEnsure all required environment variables are set in production:\n\n```bash\n# Security\nCSRF_SECURE=true\nENVIRONMENT=production\n\n# SSL/TLS\nDB_SSL_MODE=require\n\n# Monitoring\nSENTRY_DSN=your-production-sentry-dsn\n```\n\n### Systemd Service (Linux)\n\n```ini\n[Unit]\nDescription=CirrusSync API Server\nAfter=network.target\n\n[Service]\nType=simple\nUser=cirrussync\nWorkingDirectory=/opt/cirrussync\nExecStart=/opt/cirrussync/cirrussync-api\nRestart=always\nRestartSec=5\nEnvironment=ENVIRONMENT=production\n\n[Install]\nWantedBy=multi-user.target\n```\n\n### Nginx Reverse Proxy\n\n```nginx\nserver {\n    listen 80;\n    server_name api.cirrussync.com;\n\n    location / {\n        proxy_pass http://localhost:8000;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n}\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Contribution Guidelines\n\n- Follow Go conventions and best practices\n- Write tests for new features\n- Update documentation as needed\n- Ensure all tests pass before submitting PR\n- Use conventional commit messages\n\n## 🎯 Roadmap\n\n- [ ] Billing support\n- [ ] GraphQL API support\n- [ ] API rate limiting\n\n---\n\n**CirrusSync API** - Secure, scalable cloud storage for the modern web.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanans-dev%2Fcirrussync-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanans-dev%2Fcirrussync-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanans-dev%2Fcirrussync-api/lists"}