localgreenchain/TOR_SETUP.md

# 🧅 Tor Integration Guide for LocalGreenChain

This guide explains how to set up LocalGreenChain with Tor for maximum privacy and anonymity when sharing plant lineages.

## Why Use Tor with LocalGreenChain?

### Privacy Benefits
- **Anonymous Plant Registration**: Register plants without revealing your identity
- **Location Privacy**: Share general area without exposing exact home address
- **IP Protection**: Hide your IP address from other users and the network
- **Censorship Resistance**: Access the network even in restrictive environments
- **Secure Sharing**: Share plant clones with trusted community members anonymously

### Use Cases
- **Privacy-Conscious Growers**: Don't want to advertise exact plant locations
- **Sensitive Species**: Medicinal plants, rare species, or regulated botanicals
- **Community Building**: Connect with local growers without revealing identity
- **Research**: Anonymous data collection for botanical research
- **Security**: Protect against unwanted visitors or theft

## Table of Contents
1. [Quick Start](#quick-start)
2. [Installation Methods](#installation-methods)
3. [Configuration](#configuration)
4. [Running as Hidden Service](#running-as-hidden-service)
5. [Using Tor Browser](#using-tor-browser)
6. [Privacy Best Practices](#privacy-best-practices)
7. [Troubleshooting](#troubleshooting)

---

## Quick Start

### Option 1: Docker Compose (Recommended)

The easiest way to run LocalGreenChain with Tor:

```bash
# Copy environment variables
cp .env.example .env

# Edit .env and enable Tor
nano .env
# Set: TOR_ENABLED=true

# Start with Docker Compose
docker-compose -f docker-compose.tor.yml up -d

# Check if Tor is running
docker logs localgreenchain-tor

# Get your onion address
docker exec localgreenchain-tor cat /var/lib/tor/hidden_service/hostname
```

Your LocalGreenChain instance is now accessible via:
- Local: http://localhost:3001
- Onion: http://[your-address].onion (share this!)

### Option 2: Manual Installation

1. **Install Tor**
2. **Configure Tor for LocalGreenChain**
3. **Start LocalGreenChain with Tor enabled**

---

## Installation Methods

### Linux (Debian/Ubuntu)

```bash
# Install Tor
sudo apt update
sudo apt install tor

# Configure Tor for LocalGreenChain
sudo cp tor/torrc.example /etc/tor/torrc

# Edit configuration
sudo nano /etc/tor/torrc

# Create hidden service directory
sudo mkdir -p /var/lib/tor/localgreenchain
sudo chown -R debian-tor:debian-tor /var/lib/tor/localgreenchain
sudo chmod 700 /var/lib/tor/localgreenchain

# Start Tor
sudo systemctl start tor
sudo systemctl enable tor

# Check status
sudo systemctl status tor

# Get your onion address (wait ~1 minute for generation)
sudo cat /var/lib/tor/localgreenchain/hostname
```

### macOS

```bash
# Install Tor via Homebrew
brew install tor

# Copy configuration
cp tor/torrc.example /usr/local/etc/tor/torrc

# Edit configuration
nano /usr/local/etc/tor/torrc

# Create hidden service directory
mkdir -p ~/Library/Application\ Support/tor/localgreenchain
chmod 700 ~/Library/Application\ Support/tor/localgreenchain

# Update torrc with your path
# HiddenServiceDir ~/Library/Application Support/tor/localgreenchain

# Start Tor
brew services start tor

# Get your onion address
cat ~/Library/Application\ Support/tor/localgreenchain/hostname
```

### Windows (WSL)

```bash
# Install WSL if not already installed
# Then follow Linux instructions above

# Or use Tor Expert Bundle
# Download from: https://www.torproject.org/download/tor/
```

---

## Configuration

### Environment Variables

Edit `.env` file:

```bash
# Enable Tor
TOR_ENABLED=true

# Tor SOCKS proxy (default)
TOR_SOCKS_HOST=127.0.0.1
TOR_SOCKS_PORT=9050

# Tor control port
TOR_CONTROL_PORT=9051

# Hidden service directory
TOR_HIDDEN_SERVICE_DIR=/var/lib/tor/localgreenchain

# Privacy defaults
DEFAULT_PRIVACY_MODE=standard
ALLOW_ANONYMOUS_REGISTRATION=true
LOCATION_OBFUSCATION_DEFAULT=fuzzy
```

### Tor Configuration (torrc)

Minimal configuration in `/etc/tor/torrc`:

```
# SOCKS proxy
SocksPort 9050

# Hidden Service for LocalGreenChain
HiddenServiceDir /var/lib/tor/localgreenchain/
HiddenServicePort 80 127.0.0.1:3001

# Optional: Multiple ports
# HiddenServicePort 443 127.0.0.1:3001

# Logging
Log notice file /var/log/tor/notices.log

# Privacy settings
IsolateDestAddr 1
IsolateDestPort 1
```

---

## Running as Hidden Service

### Start LocalGreenChain

```bash
# Install dependencies
bun install

# Start in production mode
bun run build
bun run start

# Or development mode
bun run dev
```

### Verify Hidden Service

```bash
# Check if Tor created keys
ls -la /var/lib/tor/localgreenchain/

# Should see:
# - hostname (your .onion address)
# - hs_ed25519_public_key
# - hs_ed25519_secret_key

# Get your onion address
cat /var/lib/tor/localgreenchain/hostname
```

### Share Your Onion Address

Your `.onion` address looks like:
```
abc123def456ghi789.onion
```

Share this with trusted community members to allow anonymous access!

---

## Using Tor Browser

### As a User (Accessing LocalGreenChain via Tor)

1. **Download Tor Browser**
   - Visit: https://www.torproject.org/download/
   - Install for your operating system

2. **Connect to Tor Network**
   - Launch Tor Browser
   - Click "Connect" to establish Tor connection

3. **Access LocalGreenChain**
   - Option A: Via onion address (recommended)
     ```
     http://[your-onion-address].onion
     ```
   - Option B: Via clearnet (still anonymous)
     ```
     http://your-domain.com
     ```

4. **Register Plants Anonymously**
   - Go to "Anonymous Registration" page
   - Your connection will be detected as coming from Tor
   - All privacy features automatically enabled

### Privacy Indicators

LocalGreenChain will show you:
- 🧅 "Tor Active" badge when connected via Tor
- Privacy recommendations based on connection type
- Tor circuit information (country, not your IP)

---

## Privacy Best Practices

### For Maximum Anonymity

1. **Always Use Tor Browser**
   - Don't access via regular browser
   - Tor Browser includes additional privacy protections

2. **Enable Anonymous Mode**
   - Use `/plants/register-anonymous` page
   - Generate random IDs and pseudonyms
   - Don't reuse usernames from other sites

3. **Location Privacy**
   - Use "Fuzzy" or "City" level location sharing
   - Never share exact coordinates
   - Consider using "Hidden" for sensitive plants

4. **Operational Security (OpSec)**
   - Don't include identifiable info in plant notes
   - Use different pseudonyms for different plant types
   - Don't correlate with social media accounts
   - Clear browser data after each session

5. **Network Security**
   - Only share your .onion address with trusted people
   - Use secure channels (encrypted messaging) to share addresses
   - Rotate your hidden service periodically if needed

### Privacy Levels Explained

| Level | Location Accuracy | Best For |
|-------|------------------|----------|
| **Exact** | ~100m | Public gardens, commercial nurseries |
| **Fuzzy** | 1-5km radius | Home gardens, privacy-conscious sharing |
| **City** | ~10km grid | Regional plant trading |
| **Country** | ~100km grid | National distribution tracking |
| **Hidden** | No location | Maximum privacy, sensitive species |

---

## Troubleshooting

### Tor Won't Start

```bash
# Check Tor status
sudo systemctl status tor

# View logs
sudo tail -f /var/log/tor/notices.log

# Common issues:
# 1. Port 9050 already in use
sudo lsof -i :9050

# 2. Permission issues
sudo chown -R debian-tor:debian-tor /var/lib/tor
sudo chmod 700 /var/lib/tor/localgreenchain
```

### Hidden Service Not Accessible

```bash
# Verify Tor is running
pgrep tor

# Check if hostname file exists
cat /var/lib/tor/localgreenchain/hostname

# Verify LocalGreenChain is running
curl http://localhost:3001

# Check Tor logs for errors
sudo tail -f /var/log/tor/notices.log
```

### "Tor Status: Not Available"

1. Check if Tor daemon is running
2. Verify SOCKS port (9050) is open
3. Check firewall settings
4. Restart Tor service

```bash
sudo systemctl restart tor
```

### Slow Onion Connection

This is normal! Tor routes through multiple nodes:
- First connection: 30-60 seconds
- Subsequent loads: 5-15 seconds
- Plant operations: Near instant (local blockchain)

---

## Advanced Topics

### Running Multiple Hidden Services

Edit `/etc/tor/torrc`:

```
# LocalGreenChain (public)
HiddenServiceDir /var/lib/tor/localgreenchain-public/
HiddenServicePort 80 127.0.0.1:3001

# LocalGreenChain (private - invite only)
HiddenServiceDir /var/lib/tor/localgreenchain-private/
HiddenServicePort 80 127.0.0.1:3002
```

### Client Authentication (v3 Onions)

Restrict access to authorized users only:

```
# In torrc
HiddenServiceDir /var/lib/tor/localgreenchain/
HiddenServicePort 80 127.0.0.1:3001
HiddenServiceAuthorizeClient stealth alice,bob
```

### Monitoring Tor Traffic

```bash
# Real-time connection monitoring
sudo nyx

# Or arm (older tool)
sudo arm
```

### Backup Your Hidden Service Keys

**IMPORTANT**: Your `.onion` address is tied to your keys!

```bash
# Backup keys
sudo cp -r /var/lib/tor/localgreenchain ~/tor-backup/

# Restore keys (on new server)
sudo cp -r ~/tor-backup/* /var/lib/tor/localgreenchain/
sudo chown -R debian-tor:debian-tor /var/lib/tor/localgreenchain
sudo systemctl restart tor
```

---

## Security Considerations

### What Tor DOES Protect
✅ Your IP address from other users
✅ Your browsing from your ISP
✅ Your location from the network
✅ Your identity when using anonymous mode

### What Tor DOESN'T Protect
❌ Poor operational security (sharing identifying info)
❌ Malware on your computer
❌ Logging in with real accounts
❌ Data you voluntarily share

### Remember
- **Tor provides anonymity, not security**
- Use HTTPS even over Tor (LocalGreenChain supports this)
- Don't mix anonymous and identified activities
- Keep Tor Browser up to date
- Trust the process - Tor has protected millions of users

---

## Getting Help

- **LocalGreenChain Tor Issues**: https://github.com/yourusername/localgreenchain/issues
- **Tor Project**: https://support.torproject.org
- **Privacy Community**: https://www.reddit.com/r/TOR
- **Security Audit**: See SECURITY.md

## Legal Notice

Using Tor is legal in most countries. However:
- Check local laws regarding Tor usage
- Using Tor for illegal activities is still illegal
- LocalGreenChain is for botanical education and legal plant sharing
- Respect plant import/export regulations
- Some plants may be regulated or controlled substances

Stay safe, stay private, and happy growing! 🌱🧅