# keepSync

A secure backup and synchronization solution for multiple file types with hardware-based encryption.

## Overview

keepSync automatically monitors your files for changes, creates encrypted backups, and optionally synchronizes these backups to cloud storage (currently supporting S3-compatible storage). All encryption keys are securely stored in your device's hardware security module (TPM on Linux, KeyStore on Android).

## Features

- **Automated Monitoring**: Detects when your files are updated
- **Secure Backups**: Creates AES-256-GCM encrypted backups
- **Hardware Security**: Uses TPM 2.0 on Linux and KeyStore on Android
- **Cloud Sync**: Synchronizes encrypted backups to S3-compatible storage
- **Advanced Retention**: Flexible policies for both local and cloud backups
  - Age-based retention (keep backups for specific time periods)
  - Count-based retention (keep specific number of backups)
  - Minimum retention guarantees (always keep N most recent backups)
  - Independent local and cloud retention settings
- **Backup Restoration**: Easily restore from your encrypted backups
  - Restore the latest backup or a specific backup file
  - Verify backup integrity before restoration
  - View detailed backup metadata and information
- **Comprehensive Logging**: Flexible logging system
  - Multiple verbosity levels (debug, info, warning, error, fatal)
  - Log to console and/or file
  - Component-level filtering
  - Configurable formatting options
- **Multiple Cloud Options**: Support for S3-compatible services
- **Cross Platform**: Support for Linux (x86/AMD64) and Android (GrapheneOS)
- **Background Service**: Runs as a system service with minimal resource usage

## Security Model

keepSync follows a zero-knowledge encryption model:

1. Encryption keys are generated and stored solely within hardware security modules (TPM/KeyStore)
2. Keys never leave the secure hardware in plaintext
3. Backups are encrypted using authenticated encryption (AES-256-GCM)
4. Only encrypted data is transmitted to cloud storage
5. The application has no access to your original file content in unencrypted form

## Getting Started

### Requirements

- Linux with TPM 2.0 support or Android with KeyStore
- Go 1.18+ (for building from source)
- Files to be synchronized
- S3-compatible storage account (for cloud sync)

### Installation

#### From Source (Linux)

```bash
# Clone the repository
git clone https://github.com/username/keepsync.git
cd keepsync

# Run the installation script
./scripts/install.sh
```

The installation script will:
1. Build the application from source
2. Create a configuration file
3. Set up a systemd service
4. Check TPM availability
5. Configure automatic startup

#### Android

For Android support, use the provided APK or build from source with the Android compile scripts.

### Configuration

The configuration file is located at:
- System-wide installation: `/etc/keepsync/config.json`
- User installation: `~/.config/keepsync/config.json`

Example configuration:

```json
{
  "watched_paths": ["/home/user/Documents/important_files/", "/home/user/Projects/configs/"],
  "backup_dir": "/home/user/.keepsync/backups",
  "cloud_provider": "s3",
  "cloud_settings": {
    "endpoint": "your-s3-endpoint-url",
    "region": "your-s3-region",
    "bucket": "your-bucket-name",
    "access_key": "your-access-key",
    "secret_key": "your-secret-key",
    "prefix": "keepsync-backups/"
  },
  "retention_count": 5,
  "monitor_interval": 10000000000
}
```

### Setting Up S3 Integration

To configure S3-compatible storage integration, edit your config.json file with your S3 credentials and bucket information. See the S3 setup guide for detailed instructions:

```bash
# View the S3 setup documentation
less docs/s3-setup.md
```

## Usage

### Running Manually

```bash
# Create a backup immediately
keepsync --force-backup

# Run in daemon mode
keepsync --daemon

# Specify a custom watch path
keepsync --watch /path/to/files

# Specify a custom backup directory
keepsync --backup-dir /path/to/backups

# Enable verbose output
keepsync --verbose
```

### Managing the Service

For system-wide installation:
```bash
# Start the service
sudo systemctl start keepsync

# Check status
sudo systemctl status keepsync

# Stop the service
sudo systemctl stop keepsync
```

For user installation:
```bash
# Start the service
systemctl --user start keepsync

# Check status
systemctl --user status keepsync

# Stop the service
systemctl --user stop keepsync
```

## Troubleshooting

### TPM Access Issues

If you encounter TPM access permission issues:

```bash
# Add your user to the tss group
sudo usermod -a -G tss $USER

# Log out and log back in for changes to take effect
```

### Viewing Logs

```bash
# System-wide installation
sudo journalctl -u keepsync

# User installation
journalctl --user -u keepsync
```

## Development

See [PROJECT-STRUCTURE.md](PROJECT-STRUCTURE.md) for detailed information about the project architecture and components.

## License

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