Tor Hidden Service API

A fully-featured Tor hidden service with REST API, authentication, and administration. Creates a .onion service for secure and anonymous access to a web application.

🌟 Key Features

· Tor Hidden Service - automatic .onion address creation · Full Authentication - JWT tokens and API keys · User Management - registration, roles, profiles · Admin Panel - user management, audit logging · Tor Proxy - internet access through Tor network · Security - rate limiting, brute-force protection, audit trails · Monitoring - service statistics, Tor circuit status

📋 Requirements

System Requirements

· Python 3.8+ · Tor (installed and available in PATH) · 1GB+ free memory · Linux/macOS/Windows (with Tor support)

Install Tor

Ubuntu/Debian

sudo apt update
sudo apt install tor -y

macOS

brew install tor

Windows

1. Download Tor Expert Bundle: https://www.torproject.org/download/tor/
2. Extract the archive
3. Add path to tor.exe to system PATH

🚀 Quick Start

1. Clone and Setup

# Clone the repository
git clone https://github.com/LeadRider/TorServer
cd TorServer

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Environment Configuration

Create .env file in root directory (optional, defaults are used):

FLASK_SECRET_KEY=your_secret_key_here
JWT_SECRET_KEY=your_jwt_secret_here
TOR_CONTROL_PORT=9051
TOR_SOCKS_PORT=9050
FLASK_PORT=5000

3. Start the Server

# Start the server
python app.py

On first run:

1. Creates SQLite database
2. Creates admin user (login: admin, password: changeme123)
3. Starts Tor process
4. Generates .onion address

🔧 Configuration

Main Parameters (app.py, Config class)

Parameter Default Description TOR_CONTROL_PORT 9051 Tor control port TOR_SOCKS_PORT 9050 Tor SOCKS5 port FLASK_PORT 5000 Flask server port JWT_EXPIRY 3600 Token lifetime (seconds) MAX_LOGIN_ATTEMPTS 5 Max login attempts before lockout LOCKOUT_TIME 300 Lockout duration (seconds)

Database Structure

Application creates following tables:

· users - users and their data · sessions - active sessions · api_keys - API keys · audit_log - audit journal

📡 Using the API

Getting .onion Address

After starting server, you'll see in console:

✓ Tor hidden service running at: abc123def456ghi789.onion

Use Tor Browser to access at:

http://abc123def456ghi789.onion

Main Endpoints

📍 Without Authentication

· GET /api/v1/docs - API documentation · GET /api/v1/service/status - service status · POST /api/v1/auth/register - user registration · POST /api/v1/auth/login - user login

🔐 With Authentication (token required)

· GET /api/v1/user/profile - user profile · GET/POST /api/v1/user/apikeys - manage API keys · GET /api/v1/proxy/fetch?url= - proxy through Tor

👑 Administrative (admin role required)

· GET /api/v1/admin/users - list users · GET /api/v1/admin/audit - audit log · POST /api/v1/service/renew - renew Tor circuit

Authentication

Method 1: Bearer Token (recommended)

1. Get token via /api/v1/auth/login
2. Use in headers:

Authorization: Bearer your_token_here

Method 2: API Key

1. Create key via /api/v1/user/apikeys
2. Use in headers:

Authorization: APIKey your_key_here

📝 Request Examples

1. User Registration

curl -X POST http://localhost:5000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "securepassword",
    "email": "user@example.com"
  }'

2. Login

curl -X POST http://localhost:5000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "changeme123"
  }'

Response:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": {
    "username": "admin"
  }
}

3. Get Profile

curl -X GET http://localhost:5000/api/v1/user/profile \
  -H "Authorization: Bearer your_token"

4. Use Tor Proxy

curl -X GET "http://localhost:5000/api/v1/proxy/fetch?url=https://check.torproject.org" \
  -H "Authorization: Bearer your_token"

5. Create API Key

curl -X POST http://localhost:5000/api/v1/user/apikeys \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "permissions": "read,write"
  }'

🛠 Administration

Default User

· Username: admin · Password: changeme123 · Role: admin

Change Admin Password

# Login as admin and create new user
# Or use SQLite for direct modification

sqlite3 users.db
UPDATE users SET password_hash = 'new_hash' WHERE username = 'admin';

View Audit Log

curl -X GET http://localhost:5000/api/v1/admin/audit \
  -H "Authorization: Bearer admin_token"

🔒 Security

Required Actions

1. Change admin password immediately after first run
2. Update secret keys in configuration for production
3. Configure firewall to restrict port access
4. Use HTTPS for real services (requires special .onion certificate)

Recommendations

· Regularly update Tor for latest security patches · Use strong passwords and two-factor authentication · Regularly review audit logs · Restrict access to administrative functions

🐛 Troubleshooting

Issue: Tor Won't Start

Solution:

# Check if Tor is installed
tor --version

# Check if ports are in use
sudo netstat -tulpn | grep :9050
sudo netstat -tulpn | grep :9051

# Run Tor manually for diagnostics
tor --verify-config

Issue: Can't Connect via Tor Browser

Solution:

1. Ensure Tor Browser is updated
2. Check .onion address in server console
3. Verify server is running and responsive
4. Try different .onion address (on Tor restart)

Issue: "Authentication Error"

Solution:

1. Verify token/key correctness
2. Ensure token hasn't expired
3. Check user permissions

Issue: Slow Performance

Solution:

· Tor is slower than regular internet · Use fresh Tor circuits: POST /api/v1/service/renew · Optimize API requests

📊 Monitoring

Service Statistics

curl http://localhost:5000/api/v1/service/status

Response includes:

· Tor service status · .onion address · Usage statistics · Tor circuit information · System statistics

Logging

Logs are written to:

· Console (standard output) · File tor_service.log · Database (audit_log table)

🐳 Docker Deployment

Dockerfile

FROM python:3.9-slim

RUN apt-get update && \
    apt-get install -y tor && \
    apt-get clean

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000

CMD ["python", "app.py"]

Run in Docker

docker build -t tor-hidden-service .
docker run -p 5000:5000 tor-hidden-service

🔄 Production Migration

1. Create Production Configuration

# config_prod.py
class ProductionConfig(Config):
    FLASK_PORT = 80
    TOR_DATA_DIR = Path("/var/lib/tor/hidden_service")
    DATABASE_PATH = "/var/lib/tor-service/users.db"
    JWT_SECRET = os.getenv('JWT_SECRET', secrets.token_hex(32))
    MAX_LOGIN_ATTEMPTS = 3
    LOCKOUT_TIME = 900

2. Configure System Service (systemd)

# /etc/systemd/system/tor-service.service
[Unit]
Description=Tor Hidden Service
After=network.target

[Service]
Type=simple
User=tor
WorkingDirectory=/opt/tor-service
ExecStart=/opt/tor-service/venv/bin/python app.py
Restart=always

[Install]
WantedBy=multi-user.target

3. Configure Permissions

sudo chown -R tor:tor /var/lib/tor/hidden_service
sudo chmod 700 /var/lib/tor/hidden_service

📚 Additional Features

External System Integration

· REST API for integration with other services · Webhook support for notifications · Data export in JSON/CSV formats

Extending Functionality

· Add WebSocket support for real-time features · Integrate with PostgreSQL/MySQL databases · Add plugin/module support

⚖️ Legal Information

Important Warnings

1. Use only for legal purposes
2. Tor does not provide 100% anonymity
3. Store logs responsibly
4. Comply with local data protection laws

Liability

Developers are not responsible for:

· Misuse of the service · User violation of laws · Data loss or information leaks

🤝 Contributing

How to Help

1. Report bugs via Issues
2. Suggest improvements via Pull Requests
3. Share your usage experience
4. Help with documentation

Code Standards

· Follow PEP 8 for Python code · Add comments and documentation · Write tests for new functionality

📞 Support

Useful Resources

· Tor Project Documentation · Flask Security Guide · JWT Best Practices

Community

· Tor Project Forum: https://forum.torproject.net/ · Stack Overflow: tags tor, flask, jwt

---

🎯 Quick Command Reference

# Start server
python app.py

# Check status
curl http://localhost:5000/api/v1/service/status

# Login as admin
curl -X POST http://localhost:5000/api/v1/auth/login \
  -d '{"username":"admin","password":"changeme123"}'

# Create new user
curl -X POST http://localhost:5000/api/v1/auth/register \
  -d '{"username":"user","password":"pass","email":"user@mail.com"}'

---

Version: 1.0.0 Last Updated: 2026 Support: For legal use only