Obscure

A secure, encrypted backup tool that supports multiple cloud storage providers. Obscure allows you to create encrypted backups of your data and store them in your own cloud storage buckets (BYOB - Bring Your Own Bucket).

Features

• 🔐 End-to-End Encryption: All backups are encrypted using AES-GCM before being uploaded
• ☁️ Multiple Cloud Providers: Support for Amazon S3, Google Cloud Storage, Backblaze B2, IDrive E2, and S3-compatible services, and Filebase + IPFS (decentralized storage)
• 🔄 Version Control: Tag and version your backups for easy organization
• 🔍 Easy Management: List, restore, and delete backups with simple commands
• 🔒 Secure: No cloud provider credentials stored in the cloud - you control your data
• 🚀 Fast: Uses efficient compression and streaming for large files
• 🐳 Docker Support: Run with Docker for easy deployment

Installation

Option 1: npm (Recommended)

npm install -g obscure-backup
obscure --help

Note for Windows users: If the obscure command is not found after installation, this is a known NPM issue on Windows. Use one of these workarounds:

# Option A: Use npx (recommended)
npx obscure-backup --help
npx obscure-backup signup

# Option B: Try npm link
npm link obscure-backup
obscure --help

# Option C: Use the full path (shown in install output)
node "path/to/obscure/bin/obscure" --help

Option 2: Binary Download

1. Download the latest release from the releases page
2. Extract the binary to a location in your PATH
3. Run obscure signup to create your account

Option 3: Docker

1. Clone this repository
2. Set up your environment variables (see Environment Variables section)
3. Use Docker Compose for easy execution:

   docker-compose run --rm obscure-cli signup

Quick Start

1. Sign up and configure your cloud provider:

   # Using binary
   obscure signup
      
   # Using Docker
   docker-compose run --rm obscure-cli signup

2. Create your first backup:

   # Using binary
   obscure backup --tag=myproject --version=1.0
      
   # Using Docker
   docker-compose run --rm obscure-cli backup --tag=myproject --version=1.0

3. List your backups:

   # Using binary
   obscure ls
      
   # Using Docker
   docker-compose run --rm obscure-cli ls

4. Restore a backup:

   # Using binary
   obscure restore myproject/1.0_myproject.obscure
      
   # Using Docker
   docker-compose run --rm obscure-cli restore myproject/1.0_myproject.obscure

Available Commands

Authentication

• obscure signup - Create a new account
• obscure login - Log in to your account
• obscure logout - Log out of your account
• obscure whoami - Show current user info

Backup Management

• obscure backup [--tag TAG] [--version VERSION] [--direct] - Create a new backup
• obscure restore [backup_path] - Restore a backup
• obscure ls - List all backups
• obscure rm <filename> - Delete a specific backup
• obscure rmdir <tag> - Delete all backups under a tag

Cloud Provider Management

• obscure provider add [s3|gcs|b2|idrive|s3-compatible|filebase-ipfs] - Add a new cloud provider
• obscure provider remove [s3|gcs|b2|idrive|s3-compatible|filebase-ipfs] - Remove a cloud provider
• obscure provider list - List configured providers
• obscure list-providers - Show configured providers with details
• obscure switch-provider [provider] - Switch active provider
• obscure which-provider - Show current provider

Utility

• obscure debug - Show debug information about your session

Scheduler Command

The scheduler command allows you to automate backups at specified intervals.

Provider Selection:

• The scheduler always uses the currently selected provider (set with obscure switch-provider) at the time of each backup.
• To change the provider for future scheduled backups, run obscure switch-provider <provider> before the next backup runs.

Usage Examples:

• Daily at 17:00:

  ./obscure scheduler --time="17:00" --interval=daily --dir="/path/to/dir" --tag="mybackup"

• Every 5 minutes:

  ./obscure scheduler --time="5" --interval=minute --dir="/path/to/dir" --tag="mybackup"

• Custom cron (every 10 minutes):

  ./obscure scheduler --time="*/10 * * * *" --interval=custom --dir="/path/to/dir" --tag="mybackup"

Notes:

• The scheduler will keep only the latest 5 backups by default (use --retain to change this).
• Versioning is automatic unless overridden with --version.
• The process must be running for scheduled backups to occur.
• You can run the scheduler in the background using OS tools (see documentation for details).

Supported Cloud Providers

• Amazon S3: Standard S3 buckets with access keys
• Google Cloud Storage: GCS buckets with service account authentication
• Backblaze B2: B2 storage with application keys
• IDrive E2: S3-compatible storage with custom endpoint
• S3-compatible: Generic support for any S3-compatible service (Wasabi, MinIO, etc.)
• Filebase + IPFS: Decentralized storage via Filebase's S3-compatible API (requires AWS CLI for fallback uploads)

Google Cloud Storage (GCS) Provider

For GCS, you need a service account JSON file. The app will automatically look for your service account file in multiple locations:

Service Account File Locations (in order of priority):

1. Custom path (if specified during setup)
2. ~/.obscure/gcs-service-account.json (recommended for NPM users)
3. ./gcs-service-account.json (current directory)
4. GOOGLE_APPLICATION_CREDENTIALS environment variable

Setup:

obscure provider add gcs
# You'll be prompted for:
# - Google Cloud Project ID
# - Service account file path (optional - can be skipped)

For NPM users: Simply place your GCS service account JSON file at ~/.obscure/gcs-service-account.json and skip the path prompt during setup.

Filebase + IPFS Provider

Filebase+IPFS allows you to store your backups on the IPFS decentralized network using Filebase's S3-compatible API.

To add Filebase+IPFS as a provider:

obscure provider add filebase-ipfs
# You'll be prompted for:
# - Custom name (e.g., "Filebase IPFS")
# - Bucket name
# - Access Key ID
# - Secret Access Key
# - Filebase endpoint URL (default: https://s3.filebase.com)

Note:

• Filebase+IPFS uses the S3-compatible API, but some uploads may require the AWS CLI as a fallback for compatibility. Make sure the AWS CLI is installed and available in your PATH.
• If the Go SDK upload fails with "access denied", the app will automatically use the AWS CLI to upload your backup.

S3-compatible Provider

For S3-compatible services, you can specify a custom name that will be displayed in the provider list:

obscure provider add s3-compatible
# You'll be prompted for:
# - Custom name (e.g., "Wasabi", "MinIO", "Custom S3")
# - Bucket name
# - Region
# - Access Key ID
# - Secret Access Key
# - Custom endpoint URL

Backup Formats

Backups can be created in two formats:

1. Encrypted (default): Files are encrypted and compressed (.obscure extension)
2. Direct: Files are stored as a tar archive without encryption (.tar extension)

Docker Usage

Using Docker Compose (Recommended)

# Run any command
docker-compose run --rm obscure-cli --help
docker-compose run --rm obscure-cli list-providers
docker-compose run --rm obscure-cli backup --tag=test --version=1.0

Using Docker directly

docker run --rm \
  -e FIREBASE_API_KEY="your-api-key" \
  -e FIREBASE_CREDENTIALS="/root/firebase.json" \
  -v "${PWD}/firebase-key.json:/root/firebase.json" \
  ghcr.io/shah1011/obscure-cli --help

Security

• All backups are encrypted using AES-GCM
• Encryption keys are derived from your password using PBKDF2
• Cloud provider credentials are stored locally only
• No sensitive data is stored in the cloud

Important Security Notes

• Never commit .env, service account files, or API keys to version control
• Copy .env.example to .env and fill in your actual credentials
• Use the CLI commands to configure cloud providers securely

Environment Variables

Required for Docker

• FIREBASE_API_KEY: Your Firebase API key
• FIREBASE_CREDENTIALS: Path to Firebase service account key file

Cloud Provider Specific

• AWS_ACCESS_KEY_ID: Your AWS access key
• AWS_SECRET_ACCESS_KEY: Your AWS secret key
• AWS_REGION: Your AWS region
• GOOGLE_APPLICATION_CREDENTIALS: Path to your GCP service account key

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.