Skip to main content

​
Current Authentication Status

The OfflineTube API currently has NO authentication implemented. All API endpoints are publicly accessible without any form of authentication, authorization, or API keys.

​
Security Implications

​
Current State

Since the API runs locally on http://localhost:8001, it is designed for:
  • Local development - Single-user access on your machine
  • Personal use - No external network exposure
  • Trusted environment - Behind your firewall

​
CORS Configuration

The API is configured with fully open CORS: 
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
This allows any web application running in a browser to access the API.

​
Production Considerations

WARNING: If you plan to deploy this API to a production environment or make it accessible over a network, you MUST implement security measures.

​
1. API Key Authentication

Implement API key-based authentication: 
from fastapi import Security, HTTPException
from fastapi.security import APIKeyHeader

API_KEY = "your-secret-api-key"
api_key_header = APIKeyHeader(name="X-API-Key")

def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key != API_KEY:
        raise HTTPException(status_code=403, detail="Invalid API Key")
    return api_key

# Apply to endpoints
@app.post("/api/download", dependencies=[Depends(verify_api_key)])
async def start_download(...):
    ...

​
2. JWT Authentication

For multi-user scenarios, implement JWT tokens: 
from fastapi import Depends
from fastapi.security import HTTPBearer
import jwt

security = HTTPBearer()

def verify_token(credentials = Depends(security)):
    token = credentials.credentials
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        return payload
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")

​
3. Rate Limiting

Prevent abuse with rate limiting: 
from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter

@app.post("/api/download")
@limiter.limit("5/minute")
async def start_download(request: Request, ...):
    ...

​
4. Restrict CORS Origins

Limit which domains can access your API: 
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://yourdomain.com",
        "https://app.yourdomain.com"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "DELETE"],
    allow_headers=["Content-Type", "Authorization"],
)

​
5. HTTPS/TLS

Always use HTTPS in production: 
uvicorn main:app --host 0.0.0.0 --port 8001 \
  --ssl-keyfile=./key.pem \
  --ssl-certfile=./cert.pem

​
6. Input Validation

Validate and sanitize all user inputs to prevent:
  • URL injection attacks
  • Path traversal vulnerabilities
  • Command injection through yt-dlp

​
7. User Quotas

Implement per-user download limits:
  • Maximum concurrent downloads
  • Daily download quota
  • Storage limits per user

​
File Access Security

​
Current Implementation

Files are served directly from the filesystem:
  • /api/download/{download_id}/file - Direct file download
  • /api/stream/{filename} - File streaming
  • /api/thumbnails/{task_id} - Thumbnail access

​
Production Recommendations

  1. Validate ownership - Ensure users can only access their own files
  2. Sanitize paths - Prevent directory traversal attacks
  3. Use signed URLs - Temporary, expiring URLs for file access
  4. Implement access logs - Track who accesses what files
import hmac
import hashlib
from datetime import datetime, timedelta

def generate_signed_url(download_id: str, user_id: str, expires_in: int = 3600):
    expires = int((datetime.now() + timedelta(seconds=expires_in)).timestamp())
    message = f"{download_id}:{user_id}:{expires}"
    signature = hmac.new(SECRET_KEY.encode(), message.encode(), hashlib.sha256).hexdigest()
    return f"/api/download/{download_id}/file?expires={expires}&signature={signature}&user={user_id}"

​
Network Exposure

​
Current Configuration

The server binds to 0.0.0.0:8001, making it accessible from:
  • Localhost (127.0.0.1)
  • Local network (if firewall allows)
  • Internet (if port-forwarded)

​
Recommendations

For local use only: 
uvicorn.run(app, host="127.0.0.1", port=8001)
For production with authentication: 
uvicorn.run(app, host="0.0.0.0", port=8001)

​
Summary

The OfflineTube API is currently:
  • Unauthenticated - No login or API keys required
  • Open CORS - Accessible from any web application
  • Local-first - Designed for personal, local use
  • Not production-ready - Requires security hardening for deployment
Implement the recommended security measures before exposing this API to untrusted networks or users.

Build docs developers (and LLMs) love

Get started for freeTalk to us