feat: implement API rate limiting (#318)

* feat: implement rate limiting with slowapi

Adds API rate limiting using slowapi. Configures a global default limit of 100/minute, with stricter limits for authentication (10/minute) and upload (5/minute) endpoints. Rate limits are configurable via environment variables.

* docs: add security and rate limiting documentation

* docs: restructure security documentation

Moves rate-limiting.md and security.md to top-level docs/ directory to sit alongside authentication.md. Updates cross-references.

* docs: clarify in-memory rate limiting limitations

* docs: remove internal reference from rate limiting docs

docs/rate-limiting.md

···
+# Rate Limiting
+
+plyr.fm uses [slowapi](https://github.com/laurentS/slowapi) to implement application-side rate limiting. This protects the backend from abuse, brute-force attacks, and denial-of-service attempts.
+
+## Configuration
+
+Rate limits are configured via environment variables. Defaults are set in `src/backend/config.py`.
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `RATE_LIMIT_ENABLED` | `true` | Enable/disable rate limiting globally. |
+| `RATE_LIMIT_DEFAULT_LIMIT` | `100/minute` | Global limit applied to all endpoints by default. |
+| `RATE_LIMIT_AUTH_LIMIT` | `10/minute` | Strict limit for auth endpoints (`/auth/start`, `/auth/exchange`). |
+| `RATE_LIMIT_UPLOAD_LIMIT` | `5/minute` | Strict limit for file uploads (`/tracks/`). |
+
+## Architecture
+
+The current implementation uses **in-memory storage**.
+
+*   **Per-Instance:** Limits are tracked per application instance (Fly Machine).
+*   **Scaling:** With multiple replicas (e.g., 2 machines), the **effective global limit** scales linearly.
+    *   Example: A limit of `100/minute` with 2 machines results in a total capacity of roughly `200/minute`.
+*   **Keying:** Limits are applied by **IP address** (`get_remote_address`).
+
+### Why in-memory?
+For our current scale, in-memory is sufficient and avoids the complexity/cost of a dedicated Redis cluster. This provides effective protection against single-source flooding (DDoS/brute-force) directed at any specific instance.
+
+### Future State (Redis)
+If strict global synchronization or complex tier-based limiting is required in the future, we will migrate to a Redis-backed limiter. `slowapi` supports Redis out of the box, which would allow maintaining shared counters across all application instances.
+
+## Adding Limits to Endpoints
+
+To apply a specific limit to a route, use the `@limiter.limit` decorator:
+
+```python
+from backend.utilities.rate_limit import limiter
+from backend.config import settings
+
[e-mail]("/my-expensive-endpoint")
[e-mail]("5/minute")
+async def my_endpoint(request: Request):
+    ...
+```
+
+**Requirements:**
+*   The endpoint function **must** accept a `request: Request` parameter.
+*   Use configuration settings instead of hardcoded strings where possible.
+
+## Monitoring
+
+Rate limit hits return `429 Too Many Requests`. These events are logged and will appear in Logfire traces with the `429` status code.

docs/security.md

···
+# Security
+
+Overview of security mechanisms in plyr.fm.
+
+## Authentication
+
+We use **HttpOnly Cookies** for session management to prevent XSS attacks.
+See [Authentication](authentication.md) for details on the OAuth flow, token management, and environment architecture.
+
+For backend implementation details regarding ATProto identity resolution, see [backend/atproto-identity.md](backend/atproto-identity.md).
+
+## Rate Limiting
+
+We enforce application-side rate limits to prevent abuse.
+See [Rate Limiting](rate-limiting.md) for configuration and architecture details.
+
+## HTTP Security Headers
+
+The `SecurityHeadersMiddleware` in `src/backend/main.py` automatically applies industry-standard security headers to all responses:
+
+*   **`Strict-Transport-Security` (HSTS):** Enforces HTTPS (Production only). Max-age set to 1 year.
+*   **`X-Content-Type-Options: nosniff`:** Prevents browsers from MIME-sniffing a response away from the declared content-type.
+*   **`X-Frame-Options: DENY`:** Prevents the site from being embedded in iframes (clickjacking protection).
+*   **`X-XSS-Protection: 1; mode=block`:** Enables browser cross-site scripting filters.
+*   **`Referrer-Policy: strict-origin-when-cross-origin`:** Controls how much referrer information is included with requests.
+
+## CORS
+
+Cross-Origin Resource Sharing (CORS) is configured to allow:
+*   **Localhost:** For development (`http://localhost:5173`).
+*   **Production/Staging Domains:** `plyr.fm`, `stg.plyr.fm`, and Cloudflare Pages preview URLs (via regex).
+
+Configuration is managed in `src/backend/config.py` under `FrontendSettings`.

pyproject.toml

···
     "cachetools>=6.2.1",
     "pytest-asyncio>=0.25.3",
     "aioboto3>=15.5.0",
+    "slowapi>=0.1.9",
 ]
 
 requires-python = ">=3.11"

src/backend/api/auth.py

···
 
 from typing import Annotated
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import JSONResponse, RedirectResponse
 from pydantic import BaseModel
-from starlette.requests import Request
 from starlette.responses import Response
 
 from backend._internal import (
···
     start_oauth_flow,
 )
 from backend.config import settings
+from backend.utilities.rate_limit import limiter
 
 router = APIRouter(prefix="/auth", tags=["auth"])
 
···
 
 
 @router.get("/start")
-async def start_login(handle: str) -> RedirectResponse:
[e-mail](settings.rate_limit.auth_limit)
+async def start_login(request: Request, handle: str) -> RedirectResponse:
     """start OAuth flow for a given handle."""
     auth_url, _state = await start_oauth_flow(handle)
     return RedirectResponse(url=auth_url)
···
 
 
 @router.post("/exchange")
[e-mail](settings.rate_limit.auth_limit)
 async def exchange_token(
-    request: ExchangeTokenRequest,
-    http_request: Request,
+    request: Request,
+    exchange_request: ExchangeTokenRequest,
     response: Response,
 ) -> ExchangeTokenResponse:
     """exchange one-time token for session_id.
···
     for browser requests: sets HttpOnly cookie and still returns session_id in response
     for SDK/CLI clients: only returns session_id in response (no cookie)
     """
-    session_id = await consume_exchange_token(request.exchange_token)
+    session_id = await consume_exchange_token(exchange_request.exchange_token)
 
     if not session_id:
         raise HTTPException(
···
             detail="invalid, expired, or already used exchange token",
         )
 
-    user_agent = http_request.headers.get("user-agent", "").lower()
+    user_agent = request.headers.get("user-agent", "").lower()
     is_browser = any(
         browser in user_agent
         for browser in ["mozilla", "chrome", "safari", "firefox", "edge", "opera"]

src/backend/api/tracks/uploads.py

···
 from typing import Annotated
 
 import logfire
-from fastapi import BackgroundTasks, Depends, File, Form, HTTPException, UploadFile
+from fastapi import (
+    BackgroundTasks,
+    Depends,
+    File,
+    Form,
+    HTTPException,
+    Request,
+    UploadFile,
+)
 from fastapi.responses import StreamingResponse
 from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
···
 from backend.storage import storage
 from backend.utilities.database import db_session
 from backend.utilities.hashing import CHUNK_SIZE
+from backend.utilities.rate_limit import limiter
 
 from .router import router
 from .services import get_or_create_album
···
 
 
 @router.post("/")
[e-mail](settings.rate_limit.upload_limit)
 async def upload_track(
+    request: Request,
     title: Annotated[str, Form()],
     background_tasks: BackgroundTasks,
     auth_session: AuthSession = Depends(require_artist_profile),

src/backend/config.py

···
     )
 
 
+class RateLimitSettings(RelaySettingsSection):
+    """Rate limiting configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="RATE_LIMIT_",
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable API rate limiting",
+    )
+    default_limit: str = Field(
+        default="100/minute",
+        description="Default global rate limit",
+    )
+    auth_limit: str = Field(
+        default="10/minute",
+        description="Rate limit for authentication endpoints",
+    )
+    upload_limit: str = Field(
+        default="5/minute",
+        description="Rate limit for file uploads",
+    )
+
+
 class Settings(RelaySettingsSection):
     """Relay application settings."""
 
···
     storage: StorageSettings = Field(default_factory=StorageSettings)
     atproto: AtprotoSettings = Field(default_factory=AtprotoSettings)
     observability: ObservabilitySettings = Field(default_factory=ObservabilitySettings)
+    rate_limit: RateLimitSettings = Field(
+        default_factory=RateLimitSettings,
+        description="Rate limiting settings",
+    )
     notify: NotificationSettings = Field(
         default_factory=NotificationSettings,
         description="Notification settings",

src/backend/main.py

···
 
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
+from slowapi import _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.middleware import SlowAPIMiddleware
 from starlette.middleware.base import BaseHTTPMiddleware
 
 # filter pydantic warning from atproto library
···
 from backend.api.migration import router as migration_router
 from backend.config import settings
 from backend.models import init_db
+from backend.utilities.rate_limit import limiter
 
 # configure logfire if enabled
 if settings.observability.enabled:
···
     lifespan=lifespan,
 )
 
+# setup rate limiter
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
 # instrument fastapi with logfire
 if logfire:
     logfire.instrument_fastapi(app)
···
     allow_methods=["*"],
     allow_headers=["*"],
 )
+
+# add rate limiting middleware
+app.add_middleware(SlowAPIMiddleware)
 
 # include routers
 app.include_router(auth_router)

src/backend/utilities/rate_limit.py

···
+"""Rate limiting utility."""
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from backend.config import settings
+
+limiter = Limiter(
+    key_func=get_remote_address,
+    enabled=settings.rate_limit.enabled,
+    default_limits=[settings.rate_limit.default_limit],
+    storage_uri="memory://",
+)

uv.lock

···
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.11"
 
 [[package]]
···
     { name = "python-dotenv" },
     { name = "python-jose", extra = ["cryptography"] },
     { name = "python-multipart" },
+    { name = "slowapi" },
     { name = "sqlalchemy" },
     { name = "uvicorn", extra = ["standard"] },
 ]
···
     { name = "python-dotenv", specifier = ">=1.1.0" },
     { name = "python-jose", extras = ["cryptography"], specifier = ">=3.3.0" },
     { name = "python-multipart", specifier = ">=0.0.20" },
+    { name = "slowapi", specifier = ">=0.1.9" },
     { name = "sqlalchemy", specifier = ">=2.0.36" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.34.0" },
 ]
···
 ]
 
 [[package]]
+name = "deprecated"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/49/85/12f0a49a7c4ffb70572b6c2ef13c90c88fd190debda93b23f026b25f9634/deprecated-1.3.1.tar.gz", hash = "sha256:b1b50e0ff0c1fddaa5708a2c6b0a6588bb09b892825ab2b214ac9ea9d92a5223", size = 2932523, upload-time = "2025-10-30T08:19:02.757Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/d0/205d54408c08b13550c733c4b85429e7ead111c7f0014309637425520a9a/deprecated-1.3.1-py2.py3-none-any.whl", hash = "sha256:597bfef186b6f60181535a29fbe44865ce137a5079f295b479886c82729d5f3f", size = 11298, upload-time = "2025-10-30T08:19:00.758Z" },
+]
+
+[[package]]
 name = "dirty-equals"
 version = "0.10.0"
 source = { registry = "https://pypi.org/simple" }
···
 ]
 
 [[package]]
+name = "limits"
+version = "5.6.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "deprecated" },
+    { name = "packaging" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bb/e5/c968d43a65128cd54fb685f257aafb90cd5e4e1c67d084a58f0e4cbed557/limits-5.6.0.tar.gz", hash = "sha256:807fac75755e73912e894fdd61e2838de574c5721876a19f7ab454ae1fffb4b5", size = 182984, upload-time = "2025-09-29T17:15:22.689Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/40/96/4fcd44aed47b8fcc457653b12915fcad192cd646510ef3f29fd216f4b0ab/limits-5.6.0-py3-none-any.whl", hash = "sha256:b585c2104274528536a5b68864ec3835602b3c4a802cd6aa0b07419798394021", size = 60604, upload-time = "2025-09-29T17:15:18.419Z" },
+]
+
+[[package]]
 name = "logfire"
 version = "4.14.2"
 source = { registry = "https://pypi.org/simple" }
···
 sdist = { url = "https://files.pythonhosted.org/packages/94/e7/b2c673351809dca68a0e064b6af791aa332cf192da575fd474ed7d6f16a2/six-1.17.0.tar.gz", hash = "sha256:ff70335d468e7eb6ec65b95b99d3a2836546063f63acc5171de367e834932a81", size = 34031, upload-time = "2024-12-04T17:35:28.174Z" }
 wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
+]
+
+[[package]]
+name = "slowapi"
+version = "0.1.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "limits" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a0/99/adfc7f94ca024736f061257d39118e1542bade7a52e86415a4c4ae92d8ff/slowapi-0.1.9.tar.gz", hash = "sha256:639192d0f1ca01b1c6d95bf6c71d794c3a9ee189855337b4821f7f457dddad77", size = 14028, upload-time = "2024-02-05T12:11:52.13Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2b/bb/f71c4b7d7e7eb3fc1e8c0458a8979b912f40b58002b9fbf37729b8cb464b/slowapi-0.1.9-py3-none-any.whl", hash = "sha256:cfad116cfb84ad9d763ee155c1e5c5cbf00b0d47399a769b227865f5df576e36", size = 14670, upload-time = "2024-02-05T12:11:50.898Z" },
 ]
 
 [[package]]