termcloud/README.md

TermCloud Storage Platform

A cloud storage platform with Mullvad-style anonymity, usage-based billing, and S3-compatible bucket policies.

Quick Start

1. Set up the Server

git clone https://git.keircn.com/keiran/termcloud
cd termcloud
psql -d termcloud -f internal/db/schema.sql

cp .env.example .env
# Edit .env with your settings

make build
./termcloud

2. Install and Use CLI

go build -o tcman cmd/tcman/main.go

# Create account
./tcman account create

# Configure server (if not localhost:8080)
./tcman config set server-url https://your-server.com

# Add funds to activate account
./tcman account top-up 10.00

# Check account status
./tcman account info

CLI Usage (tcman)

Account Management

# Create new account
tcman account create

# Login with existing credentials
tcman account login 1234567890123456 your-access-token

# View account information
tcman account info

# Add funds via Bitcoin
tcman account top-up 25.00

# Check payment history
tcman account payments

# View usage and billing info
tcman account usage

Bucket Management

# List all buckets
tcman bucket list

# Create new bucket
tcman bucket create my-files

# Get bucket information
tcman bucket info my-files

# Delete bucket (with confirmation)
tcman bucket delete my-files

# Delete bucket without confirmation
tcman bucket delete my-files --force

File Operations

# Upload file
tcman file upload my-files ./local-file.txt

# Upload file with custom remote name
tcman file upload my-files ./local-file.txt remote-name.txt

# Upload with custom content type
tcman file upload my-files ./image.jpg --content-type image/jpeg

# Download file
tcman file download my-files remote-file.txt

# Download file with custom local name
tcman file download my-files remote-file.txt ./local-file.txt

# List files in bucket
tcman file list my-files

# Delete file
tcman file delete my-files remote-file.txt

Configuration

# Show current configuration
tcman config show

# Set server URL
tcman config set server-url https://api.termcloud.com

# Reset configuration (logout and clear settings)
tcman config reset

Authentication System

1. Create Account: Generate anonymous 16-digit account number + access token
2. Add Funds: Pay $5+ worth of Bitcoin to activate account
3. Usage Billing: Charged monthly for peak storage usage ($0.50/GB default)
4. No Personal Info: No emails, usernames, or personal information required

Server Configuration

Variable	Default	Description
PRICE_PER_GB_USD	0.50	Monthly charge per GB of peak storage
DATABASE_URL	-	PostgreSQL connection string
PORT	8080	Server port
STORAGE_DIR	storage	Directory for file storage
MAX_FILE_SIZE	100MB	Maximum file upload size
RATE_LIMIT	100	Requests per second per IP

API Endpoints

Account Management

# Create account (public endpoint)
POST /api/accounts

# Get account info (requires auth)
GET /api/account
Headers: X-Access-Token: your-token

# Create Bitcoin payment
POST /api/payments
Headers: X-Access-Token: your-token
Body: {"usd_amount": 10.00}

# Check payment status
GET /api/payments/123
Headers: X-Access-Token: your-token

# List all payments
GET /api/payments
Headers: X-Access-Token: your-token

Bucket Operations

# List buckets
GET /api/buckets
Headers: X-Access-Token: your-token

# Create bucket
PUT /api/buckets/my-bucket
Headers: X-Access-Token: your-token

# Get bucket info
GET /api/buckets/my-bucket
Headers: X-Access-Token: your-token

# Delete bucket
DELETE /api/buckets/my-bucket
Headers: X-Access-Token: your-token

Object Operations

# Upload file
PUT /api/buckets/my-bucket/objects/file.txt
Headers: X-Access-Token: your-token
Headers: Content-Type: text/plain
Body: [file contents]

# Download file
GET /api/buckets/my-bucket/objects/file.txt
Headers: X-Access-Token: your-token

# List objects
GET /api/buckets/my-bucket/objects
Headers: X-Access-Token: your-token

# Delete object
DELETE /api/buckets/my-bucket/objects/file.txt
Headers: X-Access-Token: your-token

Bucket Policies (S3-Compatible)

Set access control policies using AWS S3-compatible JSON syntax:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "User": ["john"] },
      "Action": ["termcloud:GetObject", "termcloud:ListObjects"],
      "Resource": ["arn:termcloud:s3:::my-bucket/*"]
    }
  ]
}

Supported Actions

• termcloud:GetObject - Download files
• termcloud:PutObject - Upload files
• termcloud:DeleteObject - Delete files
• termcloud:ListObjects - List files
• termcloud:GetBucket - Get bucket info
• termcloud:DeleteBucket - Delete bucket

Policy Management

# Set bucket policy
PUT /api/buckets/my-bucket/policy
Headers: X-Access-Token: your-token
Body: [JSON policy]

# Get bucket policy
GET /api/buckets/my-bucket/policy
Headers: X-Access-Token: your-token

# Delete bucket policy
DELETE /api/buckets/my-bucket/policy
Headers: X-Access-Token: your-token

Billing System

• Activation: $5.00 minimum Bitcoin payment required
• Monthly Billing: Charged on 1st of each month for previous month's peak usage
• Rate: $0.50 per GB per month (configurable)
• Usage Tracking: Automatic tracking of peak storage across all buckets
• Account Deactivation: Account becomes inactive when balance reaches $0

Payment Flow

1. Create payment request with desired USD amount
2. System generates Bitcoin address and calculates BTC amount
3. Send exact BTC amount to provided address
4. System confirms payment and credits account
5. Account activates and storage becomes available

Security Features

• Anonymous Accounts: No personal information required
• Access Tokens: Cryptographically secure 256-bit access tokens
• Resource Limits: Prevents uploads exceeding account balance capacity
• Rate Limiting: Configurable request rate limits
• Bucket Policies: Granular access control for shared storage

Building from Source

# Build server
go build -o termcloud cmd/termcloud/main.go

# Build CLI
go build -o tcman cmd/tcman/main.go

# Run tests
go test ./...

# Format code
go fmt ./...

License

MIT License