From 05460237ee8b4273c31be92f7535ba6557478e22 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 27 Feb 2026 21:24:53 +0000 Subject: [PATCH 1/2] Implement Bellhop: Matrix-authenticated *arr request portal - FastAPI backend with async SQLite session storage - Matrix homeserver authentication (login/logout/session validation via whoami) - Server-side proxy for Radarr, Sonarr, and Lidarr search & add APIs - Fire-and-forget Matrix audit log bot for request tracking - Rate-limited login endpoint (5 req/min per IP via slowapi) - Single-page Alpine.js frontend with dark theme, media type tabs, search grid - Dockerfile for single-container deployment - Secure session cookies (httponly, samesite=strict, secure) https://claude.ai/code/session_018iMt5qm4j9bk8wzytLC3E6 --- .dockerignore | 5 + .env.example | 29 ++++ .gitignore | 6 + Dockerfile | 12 ++ app/__init__.py | 0 app/arr.py | 234 ++++++++++++++++++++++++++ app/audit.py | 51 ++++++ app/auth.py | 131 +++++++++++++++ app/config.py | 42 +++++ app/database.py | 73 ++++++++ app/main.py | 48 ++++++ app/static/.gitkeep | 0 app/templates/index.html | 355 +++++++++++++++++++++++++++++++++++++++ requirements.txt | 9 + 14 files changed, 995 insertions(+) create mode 100644 .dockerignore create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 Dockerfile create mode 100644 app/__init__.py create mode 100644 app/arr.py create mode 100644 app/audit.py create mode 100644 app/auth.py create mode 100644 app/config.py create mode 100644 app/database.py create mode 100644 app/main.py create mode 100644 app/static/.gitkeep create mode 100644 app/templates/index.html create mode 100644 requirements.txt diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..d7600d5 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,5 @@ +.git +__pycache__ +*.pyc +.env +bellhop.db diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..4d65e96 --- /dev/null +++ b/.env.example @@ -0,0 +1,29 @@ +# Matrix homeserver +MATRIX_HOMESERVER_URL=https://matrix.example.com + +# Matrix audit bot (pre-authenticated) +MATRIX_AUDIT_ROOM_ID=!roomid:example.com +MATRIX_BOT_USER_ID=@bot:example.com +MATRIX_BOT_ACCESS_TOKEN=syt_bot_token_here + +# Radarr +RADARR_URL=https://radarr.example.com +RADARR_API_KEY=your_radarr_api_key +RADARR_QUALITY_PROFILE_ID=1 +RADARR_ROOT_FOLDER=/movies + +# Sonarr +SONARR_URL=https://sonarr.example.com +SONARR_API_KEY=your_sonarr_api_key +SONARR_QUALITY_PROFILE_ID=1 +SONARR_ROOT_FOLDER=/tv + +# Lidarr +LIDARR_URL=https://lidarr.example.com +LIDARR_API_KEY=your_lidarr_api_key +LIDARR_QUALITY_PROFILE_ID=1 +LIDARR_ROOT_FOLDER=/music + +# App +SESSION_SECRET_KEY=change-me-to-a-random-secret +DATABASE_PATH=bellhop.db diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c52f830 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +__pycache__/ +*.pyc +.env +bellhop.db +*.sqlite +*.sqlite3 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..385ccd3 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM python:3.12-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY . . + +EXPOSE 8000 + +CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"] diff --git a/app/__init__.py b/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/app/arr.py b/app/arr.py new file mode 100644 index 0000000..2f11806 --- /dev/null +++ b/app/arr.py @@ -0,0 +1,234 @@ +"""Proxy layer for Radarr, Sonarr, and Lidarr APIs.""" + +import httpx +from fastapi import APIRouter, Request +from fastapi.responses import JSONResponse + +from app.auth import require_session +from app.audit import send_audit_message +from app.config import ( + LIDARR_API_KEY, + LIDARR_QUALITY_PROFILE_ID, + LIDARR_ROOT_FOLDER, + LIDARR_URL, + RADARR_API_KEY, + RADARR_QUALITY_PROFILE_ID, + RADARR_ROOT_FOLDER, + RADARR_URL, + SONARR_API_KEY, + SONARR_QUALITY_PROFILE_ID, + SONARR_ROOT_FOLDER, + SONARR_URL, +) + +router = APIRouter(tags=["arr"]) + +SERVICE_CONFIG = { + "movie": { + "url": RADARR_URL, + "api_key": RADARR_API_KEY, + "quality_profile_id": RADARR_QUALITY_PROFILE_ID, + "root_folder": RADARR_ROOT_FOLDER, + "lookup_path": "/api/v3/movie/lookup", + "add_path": "/api/v3/movie", + "label": "Movie", + }, + "tv": { + "url": SONARR_URL, + "api_key": SONARR_API_KEY, + "quality_profile_id": SONARR_QUALITY_PROFILE_ID, + "root_folder": SONARR_ROOT_FOLDER, + "lookup_path": "/api/v3/series/lookup", + "add_path": "/api/v3/series", + "label": "Show", + }, + "music": { + "url": LIDARR_URL, + "api_key": LIDARR_API_KEY, + "quality_profile_id": LIDARR_QUALITY_PROFILE_ID, + "root_folder": LIDARR_ROOT_FOLDER, + "lookup_path": "/api/v1/artist/lookup", + "add_path": "/api/v1/artist", + "label": "Artist", + }, +} + +VALID_TYPES = set(SERVICE_CONFIG.keys()) + + +def _headers(api_key: str) -> dict[str, str]: + return {"X-Api-Key": api_key} + + +def _safe_result_movie(item: dict) -> dict: + return { + "title": item.get("title", ""), + "year": item.get("year"), + "tmdbId": item.get("tmdbId"), + "overview": item.get("overview", ""), + "remotePoster": item.get("remotePoster", ""), + "hasFile": item.get("hasFile", False), + } + + +def _safe_result_tv(item: dict) -> dict: + return { + "title": item.get("title", ""), + "year": item.get("year"), + "tvdbId": item.get("tvdbId"), + "overview": item.get("overview", ""), + "remotePoster": item.get("remotePoster", ""), + "statistics": item.get("statistics", {}), + } + + +def _safe_result_music(item: dict) -> dict: + return { + "artistName": item.get("artistName", ""), + "foreignArtistId": item.get("foreignArtistId", ""), + "overview": item.get("overview", ""), + "remotePoster": (item.get("images") or [{}])[0].get("remoteUrl", "") if item.get("images") else "", + } + + +SAFE_MAPPERS = { + "movie": _safe_result_movie, + "tv": _safe_result_tv, + "music": _safe_result_music, +} + + +@router.get("/search/{media_type}") +async def search(media_type: str, term: str, request: Request) -> JSONResponse: + session = await require_session(request) + if not session: + return JSONResponse({"error": "Not authenticated"}, status_code=401) + + if media_type not in VALID_TYPES: + return JSONResponse({"error": f"Invalid type. Must be one of: {', '.join(VALID_TYPES)}"}, status_code=400) + + if not term or not term.strip(): + return JSONResponse({"error": "Search term is required"}, status_code=400) + + cfg = SERVICE_CONFIG[media_type] + if not cfg["url"] or not cfg["api_key"]: + return JSONResponse({"error": f"{cfg['label']} service is not configured"}, status_code=503) + + lookup_url = f"{cfg['url'].rstrip('/')}{cfg['lookup_path']}" + params = {"term": term.strip()} + + async with httpx.AsyncClient() as client: + try: + resp = await client.get( + lookup_url, + params=params, + headers=_headers(cfg["api_key"]), + timeout=15.0, + ) + except httpx.RequestError: + return JSONResponse({"error": f"Could not reach {cfg['label']} service"}, status_code=502) + + if resp.status_code != 200: + return JSONResponse({"error": f"{cfg['label']} lookup failed"}, status_code=resp.status_code) + + results = resp.json() + mapper = SAFE_MAPPERS[media_type] + safe_results = [mapper(item) for item in results[:25]] + + return JSONResponse(safe_results) + + +@router.post("/request/{media_type}") +async def add_request(media_type: str, request: Request) -> JSONResponse: + session = await require_session(request) + if not session: + return JSONResponse({"error": "Not authenticated"}, status_code=401) + + if media_type not in VALID_TYPES: + return JSONResponse({"error": f"Invalid type. Must be one of: {', '.join(VALID_TYPES)}"}, status_code=400) + + body = await request.json() + cfg = SERVICE_CONFIG[media_type] + + if not cfg["url"] or not cfg["api_key"]: + return JSONResponse({"error": f"{cfg['label']} service is not configured"}, status_code=503) + + add_url = f"{cfg['url'].rstrip('/')}{cfg['add_path']}" + + if media_type == "movie": + payload = _build_movie_payload(body, cfg) + title_display = f"\"{body.get('title', 'Unknown')}\" ({body.get('year', '?')})" + elif media_type == "tv": + payload = _build_tv_payload(body, cfg) + title_display = f"\"{body.get('title', 'Unknown')}\" ({body.get('year', '?')})" + else: + payload = _build_music_payload(body, cfg) + title_display = f"\"{body.get('artistName', 'Unknown')}\" ({body.get('foreignArtistId', '?')})" + + async with httpx.AsyncClient() as client: + try: + resp = await client.post( + add_url, + json=payload, + headers=_headers(cfg["api_key"]), + timeout=15.0, + ) + except httpx.RequestError: + return JSONResponse({"error": f"Could not reach {cfg['label']} service"}, status_code=502) + + if resp.status_code not in (200, 201): + error_detail = "" + try: + error_body = resp.json() + if isinstance(error_body, list): + error_detail = "; ".join(e.get("errorMessage", "") for e in error_body if e.get("errorMessage")) + elif isinstance(error_body, dict): + error_detail = error_body.get("message", "") or error_body.get("errorMessage", "") + except Exception: + pass + msg = f"Failed to add to {cfg['label']}" + if error_detail: + msg += f": {error_detail}" + return JSONResponse({"error": msg}, status_code=resp.status_code) + + # Fire-and-forget audit message + user_id = session["matrix_user_id"] + audit_msg = f"[REQUEST] {user_id} → [{cfg['label']}] {title_display}" + send_audit_message(audit_msg) + + return JSONResponse({"ok": True, "message": f"{cfg['label']} added successfully"}) + + +def _build_movie_payload(body: dict, cfg: dict) -> dict: + return { + "title": body.get("title", ""), + "tmdbId": body.get("tmdbId"), + "year": body.get("year"), + "qualityProfileId": cfg["quality_profile_id"], + "rootFolderPath": cfg["root_folder"], + "monitored": True, + "addOptions": {"searchForMovie": True}, + } + + +def _build_tv_payload(body: dict, cfg: dict) -> dict: + return { + "title": body.get("title", ""), + "tvdbId": body.get("tvdbId"), + "year": body.get("year"), + "qualityProfileId": cfg["quality_profile_id"], + "rootFolderPath": cfg["root_folder"], + "monitored": True, + "addOptions": {"searchForMissingEpisodes": True}, + } + + +def _build_music_payload(body: dict, cfg: dict) -> dict: + return { + "artistName": body.get("artistName", ""), + "foreignArtistId": body.get("foreignArtistId", ""), + "qualityProfileId": cfg["quality_profile_id"], + "rootFolderPath": cfg["root_folder"], + "monitored": True, + "addOptions": {"searchForMissingAlbums": True}, + } diff --git a/app/audit.py b/app/audit.py new file mode 100644 index 0000000..76c8b52 --- /dev/null +++ b/app/audit.py @@ -0,0 +1,51 @@ +"""Matrix audit log — fire-and-forget messages to an unencrypted room.""" + +import asyncio +import logging + +import httpx + +from app.config import ( + MATRIX_AUDIT_ROOM_ID, + MATRIX_BOT_ACCESS_TOKEN, + MATRIX_HOMESERVER_URL, +) + +logger = logging.getLogger(__name__) + + +def send_audit_message(message: str) -> None: + """Schedule an audit message to be sent without blocking the caller.""" + if not MATRIX_AUDIT_ROOM_ID or not MATRIX_BOT_ACCESS_TOKEN: + logger.debug("Audit log not configured, skipping") + return + + try: + loop = asyncio.get_running_loop() + except RuntimeError: + return + + loop.create_task(_send(message)) + + +async def _send(message: str) -> None: + import time + + room_id = MATRIX_AUDIT_ROOM_ID + txn_id = str(int(time.time() * 1000)) + + url = ( + f"{MATRIX_HOMESERVER_URL.rstrip('/')}/_matrix/client/v3/rooms/" + f"{room_id}/send/m.room.message/{txn_id}" + ) + body = { + "msgtype": "m.text", + "body": message, + } + headers = {"Authorization": f"Bearer {MATRIX_BOT_ACCESS_TOKEN}"} + + try: + async with httpx.AsyncClient() as client: + await client.put(url, json=body, headers=headers, timeout=10.0) + except Exception: + logger.warning("Failed to send audit message: %s", message, exc_info=True) diff --git a/app/auth.py b/app/auth.py new file mode 100644 index 0000000..30300f3 --- /dev/null +++ b/app/auth.py @@ -0,0 +1,131 @@ +import httpx +from fastapi import APIRouter, Request, Response +from fastapi.responses import JSONResponse + +from app.config import MATRIX_HOMESERVER_URL +from app.database import create_session, delete_session, get_session + +router = APIRouter(prefix="/auth", tags=["auth"]) + +SESSION_COOKIE = "bellhop_session" +MAX_SESSION_AGE = 60 * 60 * 24 * 7 # 7 days + + +@router.post("/login") +async def login(request: Request) -> Response: + body = await request.json() + username: str = body.get("username", "").strip() + password: str = body.get("password", "") + + if not username or not password: + return JSONResponse({"error": "Username and password are required"}, status_code=400) + + # Build the Matrix user identifier + if username.startswith("@"): + user_identifier = username + else: + user_identifier = username # let the homeserver resolve it + + login_url = f"{MATRIX_HOMESERVER_URL.rstrip('/')}/_matrix/client/v3/login" + payload = { + "type": "m.login.password", + "identifier": {"type": "m.id.user", "user": user_identifier}, + "password": password, + } + + async with httpx.AsyncClient() as client: + try: + resp = await client.post(login_url, json=payload, timeout=15.0) + except httpx.RequestError: + return JSONResponse({"error": "Could not reach Matrix homeserver"}, status_code=502) + + if resp.status_code != 200: + error_msg = resp.json().get("error", "Authentication failed") + return JSONResponse({"error": error_msg}, status_code=401) + + data = resp.json() + matrix_user_id: str = data["user_id"] + matrix_access_token: str = data["access_token"] + + session_id = await create_session(matrix_user_id, matrix_access_token) + + response = JSONResponse({"user_id": matrix_user_id}) + response.set_cookie( + key=SESSION_COOKIE, + value=session_id, + httponly=True, + samesite="strict", + secure=True, + max_age=MAX_SESSION_AGE, + ) + return response + + +@router.post("/logout") +async def logout(request: Request) -> Response: + session_id = request.cookies.get(SESSION_COOKIE) + if session_id: + await delete_session(session_id) + response = JSONResponse({"ok": True}) + response.delete_cookie(key=SESSION_COOKIE) + return response + + +@router.get("/me") +async def me(request: Request) -> Response: + session_id = request.cookies.get(SESSION_COOKIE) + if not session_id: + return JSONResponse({"error": "Not authenticated"}, status_code=401) + + session = await get_session(session_id) + if not session: + return JSONResponse({"error": "Not authenticated"}, status_code=401) + + # Verify token is still valid with the homeserver + whoami_url = f"{MATRIX_HOMESERVER_URL.rstrip('/')}/_matrix/client/v3/account/whoami" + async with httpx.AsyncClient() as client: + try: + resp = await client.get( + whoami_url, + headers={"Authorization": f"Bearer {session['matrix_access_token']}"}, + timeout=10.0, + ) + except httpx.RequestError: + # If homeserver is unreachable, trust the local session + return JSONResponse({"user_id": session["matrix_user_id"]}) + + if resp.status_code != 200: + await delete_session(session_id) + response = JSONResponse({"error": "Session expired"}, status_code=401) + response.delete_cookie(key=SESSION_COOKIE) + return response + + return JSONResponse({"user_id": session["matrix_user_id"]}) + + +async def require_session(request: Request) -> dict | None: + """Utility: extract and validate session from a request. Returns session dict or None.""" + session_id = request.cookies.get(SESSION_COOKIE) + if not session_id: + return None + session = await get_session(session_id) + if not session: + return None + + # Verify token is still valid + whoami_url = f"{MATRIX_HOMESERVER_URL.rstrip('/')}/_matrix/client/v3/account/whoami" + async with httpx.AsyncClient() as client: + try: + resp = await client.get( + whoami_url, + headers={"Authorization": f"Bearer {session['matrix_access_token']}"}, + timeout=10.0, + ) + except httpx.RequestError: + return session # trust local session if homeserver unreachable + + if resp.status_code != 200: + await delete_session(session_id) + return None + + return session diff --git a/app/config.py b/app/config.py new file mode 100644 index 0000000..dce343e --- /dev/null +++ b/app/config.py @@ -0,0 +1,42 @@ +import os +from pathlib import Path + +from dotenv import load_dotenv + +load_dotenv() + + +def _require(name: str) -> str: + val = os.getenv(name) + if not val: + raise RuntimeError(f"Missing required environment variable: {name}") + return val + + +# Matrix +MATRIX_HOMESERVER_URL: str = _require("MATRIX_HOMESERVER_URL") +MATRIX_AUDIT_ROOM_ID: str = os.getenv("MATRIX_AUDIT_ROOM_ID", "") +MATRIX_BOT_USER_ID: str = os.getenv("MATRIX_BOT_USER_ID", "") +MATRIX_BOT_ACCESS_TOKEN: str = os.getenv("MATRIX_BOT_ACCESS_TOKEN", "") + +# Radarr +RADARR_URL: str = os.getenv("RADARR_URL", "") +RADARR_API_KEY: str = os.getenv("RADARR_API_KEY", "") +RADARR_QUALITY_PROFILE_ID: int = int(os.getenv("RADARR_QUALITY_PROFILE_ID", "1")) +RADARR_ROOT_FOLDER: str = os.getenv("RADARR_ROOT_FOLDER", "/movies") + +# Sonarr +SONARR_URL: str = os.getenv("SONARR_URL", "") +SONARR_API_KEY: str = os.getenv("SONARR_API_KEY", "") +SONARR_QUALITY_PROFILE_ID: int = int(os.getenv("SONARR_QUALITY_PROFILE_ID", "1")) +SONARR_ROOT_FOLDER: str = os.getenv("SONARR_ROOT_FOLDER", "/tv") + +# Lidarr +LIDARR_URL: str = os.getenv("LIDARR_URL", "") +LIDARR_API_KEY: str = os.getenv("LIDARR_API_KEY", "") +LIDARR_QUALITY_PROFILE_ID: int = int(os.getenv("LIDARR_QUALITY_PROFILE_ID", "1")) +LIDARR_ROOT_FOLDER: str = os.getenv("LIDARR_ROOT_FOLDER", "/music") + +# App +SESSION_SECRET_KEY: str = _require("SESSION_SECRET_KEY") +DATABASE_PATH: str = os.getenv("DATABASE_PATH", "bellhop.db") diff --git a/app/database.py b/app/database.py new file mode 100644 index 0000000..674c66c --- /dev/null +++ b/app/database.py @@ -0,0 +1,73 @@ +import secrets +import time + +import aiosqlite + +from app.config import DATABASE_PATH + +_db: aiosqlite.Connection | None = None + + +async def get_db() -> aiosqlite.Connection: + global _db + if _db is None: + _db = await aiosqlite.connect(DATABASE_PATH) + _db.row_factory = aiosqlite.Row + await _db.execute("PRAGMA journal_mode=WAL") + await _db.execute( + """ + CREATE TABLE IF NOT EXISTS sessions ( + session_id TEXT PRIMARY KEY, + matrix_user_id TEXT NOT NULL, + matrix_access_token TEXT NOT NULL, + created_at REAL NOT NULL, + last_seen REAL NOT NULL + ) + """ + ) + await _db.commit() + return _db + + +async def close_db() -> None: + global _db + if _db is not None: + await _db.close() + _db = None + + +async def create_session(matrix_user_id: str, matrix_access_token: str) -> str: + db = await get_db() + session_id = secrets.token_urlsafe(32) + now = time.time() + await db.execute( + "INSERT INTO sessions (session_id, matrix_user_id, matrix_access_token, created_at, last_seen) " + "VALUES (?, ?, ?, ?, ?)", + (session_id, matrix_user_id, matrix_access_token, now, now), + ) + await db.commit() + return session_id + + +async def get_session(session_id: str) -> dict | None: + db = await get_db() + cursor = await db.execute( + "SELECT session_id, matrix_user_id, matrix_access_token, created_at, last_seen " + "FROM sessions WHERE session_id = ?", + (session_id,), + ) + row = await cursor.fetchone() + if row is None: + return None + await db.execute( + "UPDATE sessions SET last_seen = ? WHERE session_id = ?", + (time.time(), session_id), + ) + await db.commit() + return dict(row) + + +async def delete_session(session_id: str) -> None: + db = await get_db() + await db.execute("DELETE FROM sessions WHERE session_id = ?", (session_id,)) + await db.commit() diff --git a/app/main.py b/app/main.py new file mode 100644 index 0000000..ff8bd50 --- /dev/null +++ b/app/main.py @@ -0,0 +1,48 @@ +from contextlib import asynccontextmanager +from pathlib import Path + +from fastapi import FastAPI, Request +from fastapi.responses import HTMLResponse +from fastapi.staticfiles import StaticFiles +from slowapi import Limiter, _rate_limit_exceeded_handler +from slowapi.errors import RateLimitExceeded +from slowapi.util import get_remote_address + +from app.auth import router as auth_router +from app.arr import router as arr_router +from app.database import close_db, get_db + +BASE_DIR = Path(__file__).resolve().parent + +limiter = Limiter(key_func=get_remote_address) + + +@asynccontextmanager +async def lifespan(app: FastAPI): + await get_db() + yield + await close_db() + + +app = FastAPI(title="Bellhop", lifespan=lifespan) +app.state.limiter = limiter +app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler) + +# Mount static files +app.mount("/static", StaticFiles(directory=str(BASE_DIR / "static")), name="static") + +# Apply rate limit to login specifically +original_login = auth_router.routes +for route in auth_router.routes: + if hasattr(route, "path") and route.path == "/login" and hasattr(route, "endpoint"): + route.endpoint = limiter.limit("5/minute")(route.endpoint) + break + +app.include_router(auth_router) +app.include_router(arr_router) + + +@app.get("/", response_class=HTMLResponse) +async def index(): + html_path = BASE_DIR / "templates" / "index.html" + return HTMLResponse(html_path.read_text()) diff --git a/app/static/.gitkeep b/app/static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/app/templates/index.html b/app/templates/index.html new file mode 100644 index 0000000..72d3d0e --- /dev/null +++ b/app/templates/index.html @@ -0,0 +1,355 @@ + + + + + + Bellhop + + + + +
+ + + + + + + + + +
+ + + + diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..46ca906 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,9 @@ +fastapi==0.115.6 +uvicorn[standard]==0.34.0 +httpx==0.28.1 +aiosqlite==0.20.0 +python-dotenv==1.0.1 +matrix-nio==0.24.0 +slowapi==0.1.9 +jinja2==3.1.5 +itsdangerous==2.2.0 From 003792f7449e74f8e435da85236b3f2cf50bddff Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 27 Feb 2026 21:29:21 +0000 Subject: [PATCH 2/2] Add comprehensive README with setup, API reference, and architecture docs https://claude.ai/code/session_018iMt5qm4j9bk8wzytLC3E6 --- README.md | 267 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 266 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d7f78f9..bb0e498 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,267 @@ # Bellhop -Frontend interface for placing requests to *arr instances. + +A Matrix-authenticated web portal for submitting media requests to Radarr, Sonarr, and Lidarr. Users sign in with their Matrix homeserver credentials, search for movies, TV shows, or music, and submit requests — all through a clean single-page interface. Every request is logged to a Matrix room for auditing. + +## Architecture + +``` +Browser ──► FastAPI app ──► Matrix homeserver (authentication) + ──► Radarr / Sonarr / Lidarr (search + add) + ──► Matrix room (audit log) + ──► SQLite (session storage) +``` + +All *arr communication happens server-side. API keys and service URLs are never exposed to the browser. + +## Requirements + +- Python 3.12+ +- A Matrix homeserver (Synapse, Dendrite, Conduit, etc.) +- At least one of: Radarr, Sonarr, or Lidarr accessible over HTTPS +- (Optional) A Matrix bot account for audit logging + +## Quick Start + +### 1. Clone and configure + +```bash +git clone https://github.com/prosolis/Bellhop.git +cd Bellhop +cp .env.example .env +``` + +Edit `.env` with your actual values (see [Environment Variables](#environment-variables) below). + +### 2. Run locally + +```bash +pip install -r requirements.txt +uvicorn app.main:app --host 0.0.0.0 --port 8000 +``` + +Open `http://localhost:8000` in your browser. + +### 3. Run with Docker + +```bash +docker build -t bellhop . +docker run -d \ + --name bellhop \ + --env-file .env \ + -p 8000:8000 \ + -v bellhop-data:/app \ + bellhop +``` + +The SQLite database file is created at the path specified by `DATABASE_PATH` (default: `bellhop.db` in the working directory). Mount a volume if you want persistence across container recreations. + +## Environment Variables + +Create a `.env` file in the project root (or pass variables via Docker `--env-file`). See `.env.example` for a template. + +### Required + +| Variable | Description | +|---|---| +| `MATRIX_HOMESERVER_URL` | Base URL of your Matrix homeserver (e.g. `https://matrix.example.com`) | +| `SESSION_SECRET_KEY` | Random secret used internally. Generate one with `python -c "import secrets; print(secrets.token_urlsafe(32))"` | + +### *arr Services + +Configure one or more. If a service's URL or API key is left empty, that media type will return a "not configured" error when used. + +| Variable | Default | Description | +|---|---|---| +| `RADARR_URL` | _(empty)_ | Radarr instance URL (e.g. `https://radarr.example.com`) | +| `RADARR_API_KEY` | _(empty)_ | Radarr API key (Settings > General in Radarr) | +| `RADARR_QUALITY_PROFILE_ID` | `1` | Quality profile ID to assign to new movies | +| `RADARR_ROOT_FOLDER` | `/movies` | Root folder path for movie storage | +| `SONARR_URL` | _(empty)_ | Sonarr instance URL | +| `SONARR_API_KEY` | _(empty)_ | Sonarr API key | +| `SONARR_QUALITY_PROFILE_ID` | `1` | Quality profile ID for new series | +| `SONARR_ROOT_FOLDER` | `/tv` | Root folder path for TV storage | +| `LIDARR_URL` | _(empty)_ | Lidarr instance URL | +| `LIDARR_API_KEY` | _(empty)_ | Lidarr API key | +| `LIDARR_QUALITY_PROFILE_ID` | `1` | Quality profile ID for new artists | +| `LIDARR_ROOT_FOLDER` | `/music` | Root folder path for music storage | + +**Finding quality profile IDs:** Open your *arr instance, go to Settings > Profiles. The ID is visible in the URL when you click a profile, or query the API directly: + +```bash +curl -H "X-Api-Key: YOUR_KEY" https://radarr.example.com/api/v3/qualityprofile +``` + +### Audit Bot (optional) + +| Variable | Default | Description | +|---|---|---| +| `MATRIX_AUDIT_ROOM_ID` | _(empty)_ | Room ID for audit messages (e.g. `!abc123:example.com`) | +| `MATRIX_BOT_USER_ID` | _(empty)_ | Bot's Matrix user ID (e.g. `@bellhop-bot:example.com`) | +| `MATRIX_BOT_ACCESS_TOKEN` | _(empty)_ | Pre-authenticated access token for the bot | + +If any of these are left empty, audit logging is silently disabled. The room must be **unencrypted** and the bot must already be joined to it. + +**Getting a bot access token:** + +```bash +curl -X POST https://matrix.example.com/_matrix/client/v3/login \ + -H "Content-Type: application/json" \ + -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"@bellhop-bot:example.com"},"password":"bot-password"}' +``` + +Copy the `access_token` from the response. + +### Other + +| Variable | Default | Description | +|---|---|---| +| `DATABASE_PATH` | `bellhop.db` | Path to the SQLite database file | + +## API Reference + +### Authentication + +| Method | Path | Description | +|---|---|---| +| `POST` | `/auth/login` | Authenticate with Matrix credentials. Rate-limited to 5 requests/minute per IP. | +| `POST` | `/auth/logout` | Destroy the current session. | +| `GET` | `/auth/me` | Return the current user's Matrix ID, or 401 if not authenticated. | + +**Login request body:** + +```json +{ + "username": "@user:example.com", + "password": "your-password" +} +``` + +The username can be a full Matrix ID (`@user:example.com`) or a localpart (`user`) — the homeserver resolves it. + +**Login response (200):** + +```json +{ + "user_id": "@user:example.com" +} +``` + +A `bellhop_session` cookie is set automatically. + +### Search + +| Method | Path | Description | +|---|---|---| +| `GET` | `/search/movie?term=...` | Search Radarr for movies | +| `GET` | `/search/tv?term=...` | Search Sonarr for TV shows | +| `GET` | `/search/music?term=...` | Search Lidarr for artists | + +All search endpoints require an active session (cookie). Results are capped at 25 items. Response fields are sanitized — only safe metadata (title, year, poster URL, IDs) is returned. + +### Request + +| Method | Path | Description | +|---|---|---| +| `POST` | `/request/movie` | Add a movie to Radarr | +| `POST` | `/request/tv` | Add a series to Sonarr | +| `POST` | `/request/music` | Add an artist to Lidarr | + +**Movie request body:** + +```json +{ + "title": "Movie Title", + "tmdbId": 12345, + "year": 2024 +} +``` + +**TV request body:** + +```json +{ + "title": "Show Title", + "tvdbId": 67890, + "year": 2024 +} +``` + +**Music request body:** + +```json +{ + "artistName": "Artist Name", + "foreignArtistId": "mbid-uuid-here" +} +``` + +All items are added as monitored with "search on add" enabled. Quality profile and root folder are set from the corresponding environment variables. + +**Success response (200):** + +```json +{ + "ok": true, + "message": "Movie added successfully" +} +``` + +### Frontend + +| Method | Path | Description | +|---|---|---| +| `GET` | `/` | Serves the single-page Alpine.js frontend | + +## Project Structure + +``` +Bellhop/ +├── app/ +│ ├── __init__.py +│ ├── main.py # FastAPI app, lifespan, rate limiter, route mounting +│ ├── config.py # Environment variable loading +│ ├── database.py # Async SQLite session CRUD +│ ├── auth.py # /auth/* routes, session cookie management +│ ├── arr.py # /search/* and /request/* routes, *arr API proxying +│ ├── audit.py # Fire-and-forget Matrix room messaging +│ ├── static/ # Static assets (served at /static) +│ └── templates/ +│ └── index.html # Alpine.js single-page frontend +├── Dockerfile +├── requirements.txt +├── .env.example +└── README.md +``` + +## Security + +- **Session cookies** are set with `httponly`, `samesite=strict`, and `secure` flags. The `secure` flag means cookies are only sent over HTTPS — use a reverse proxy with TLS in production. +- **Login rate limiting** — 5 attempts per minute per IP address via slowapi. +- **Token validation** — every protected route verifies the Matrix access token against the homeserver's `/_matrix/client/v3/account/whoami` endpoint. If the token has been revoked, the session is deleted immediately. If the homeserver is unreachable, the local session is trusted as a fallback. +- **No credential leakage** — *arr API keys, URLs, and internal IDs are never included in any response to the browser. Search results are mapped to a safe subset of fields before returning. +- **Sessions expire** after 7 days (cookie `max_age`). + +### Production Recommendations + +- Run behind a reverse proxy (nginx, Caddy, Traefik) with TLS termination so the `secure` cookie flag works. +- Set `SESSION_SECRET_KEY` to a strong random value. +- Restrict network access to your *arr instances — only the Bellhop container needs to reach them. +- Use a dedicated Matrix bot account for audit logging rather than a personal account. + +## How It Works + +1. **User signs in** — the frontend POSTs Matrix credentials to `/auth/login`. The backend authenticates against the Matrix homeserver's Client-Server API (`m.login.password`), stores the resulting access token in SQLite, and returns a session cookie. + +2. **User searches** — the frontend sends a search query to `/search/{type}`. The backend proxies the request to the appropriate *arr instance, strips internal fields, and returns sanitized results with poster URLs. + +3. **User requests** — clicking "Request" on a result POSTs it to `/request/{type}`. The backend sends the add command to the *arr API with preconfigured quality profile and root folder. On success, an audit message is fired asynchronously to the configured Matrix room. + +4. **Audit trail** — every successful request posts a message like `[REQUEST] @user:example.com → [Movie] "Title" (2024)` to the Matrix audit room. This is fire-and-forget — failures are logged but never block the user's request. + +## Lidarr Notes + +Lidarr uses MusicBrainz IDs (`foreignArtistId`) rather than TMDB/TVDB IDs. The lookup response includes this field and it is passed through directly to the add call. No independent MBID resolution is needed. + +## License + +See repository for license details.