294 lines
6.4 KiB
Markdown
294 lines
6.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|