Require API authentication when reachable over the network

Dockerfile

@@ -8,6 +8,12 @@ ENV PYTHONUNBUFFERED=1
 # Enable web auth mode for Docker (binds OAuth to 0.0.0.0)
 ENV WEB_AUTH=true
 
+# Bind on all interfaces inside the container so the published port is
+# reachable. Because this is a non-loopback bind, the app requires an API
+# token: set API_TOKEN to pin one, otherwise a random token is generated at
+# startup and printed to the container logs.
+ENV HOST=0.0.0.0
+
 # Install uv for faster package management
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 

app/api/auth.py

@@ -0,0 +1,95 @@
+"""
+API Authentication
+-------------------
+Guards the API behind a shared secret whenever the server is reachable over
+the network.
+
+Threat model: after a user has OAuth'd their Gmail account, the action and
+status endpoints can read and destroy mail using the stored credentials. They
+must therefore not be callable by anyone who can merely reach the port.
+
+Policy:
+- A loopback-only bind (the default) is treated as trusted single-user use and
+  needs no token.
+- Any non-loopback bind requires a token. If ``API_TOKEN`` is not set, one is
+  generated at startup so the API is never left open by accident.
+
+The same-origin web UI authenticates automatically: the root page sets the
+token as a cookie, which the browser then sends with every ``/api`` request.
+"""
+
+import logging
+import secrets
+
+from fastapi import HTTPException, Request, status
+
+from app.core import settings
+
+logger = logging.getLogger(__name__)
+
+# Token enforced for this process. Resolved once at startup; ``None`` means the
+# server is loopback-only and auth is disabled.
+_effective_token: str | None = None
+# True when the active token was generated rather than supplied via API_TOKEN.
+_token_was_generated = False
+
+
+def resolve_effective_token() -> str | None:
+    """Decide whether API auth is required and which token enforces it.
+
+    Returns the active token (or ``None`` when auth is disabled).
+    """
+    global _effective_token, _token_was_generated
+
+    if settings.api_token:
+        _effective_token = settings.api_token
+        _token_was_generated = False
+    elif not settings.is_loopback_host():
+        # Reachable over the network but no token configured: refuse to run
+        # open. Mint a random one so the operator gets a working, secured app.
+        _effective_token = secrets.token_urlsafe(32)
+        _token_was_generated = True
+    else:
+        _effective_token = None
+        _token_was_generated = False
+
+    return _effective_token
+
+
+def get_effective_token() -> str | None:
+    """Return the token currently enforced (``None`` if auth is disabled)."""
+    return _effective_token
+
+
+def token_was_generated() -> bool:
+    """Return True if the active token was auto-generated at startup."""
+    return _token_was_generated
+
+
+def _extract_token(request: Request) -> str | None:
+    """Pull a presented token from the Authorization header or a cookie."""
+    auth_header = request.headers.get("Authorization", "")
+    if auth_header.startswith("Bearer "):
+        return auth_header[len("Bearer "):].strip()
+
+    explicit = request.headers.get("X-API-Token")
+    if explicit:
+        return explicit.strip()
+
+    return request.cookies.get("api_token")
+
+
+async def require_api_auth(request: Request) -> None:
+    """FastAPI dependency enforcing the API token when one is in effect."""
+    token = _effective_token
+    if not token:
+        # Loopback-only deployment: not network-reachable, no token required.
+        return
+
+    presented = _extract_token(request)
+    if not presented or not secrets.compare_digest(presented, token):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Missing or invalid API token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )

app/core/config.py

@@ -16,6 +16,12 @@ class Settings(BaseSettings):
     app_name: str = "Gmail Cleaner"
     app_version: str = "1.0.0"
     debug: bool = False
+    host: str = Field(
+        default="127.0.0.1",
+        description="Network interface the web server binds to. Defaults to "
+        "loopback so the API is not reachable from the local network. Set to "
+        "0.0.0.0 to listen on all interfaces (required inside Docker).",
+    )
     port: int = 8766
     oauth_port: int = 8767
     oauth_external_port: int | None = Field(
@@ -28,6 +34,12 @@ class Settings(BaseSettings):
         default=False,
         description="Enable web-based authentication mode",
     )
+    api_token: str = Field(
+        default="",
+        description="Shared secret required to call the API. When the server "
+        "binds a non-loopback interface and this is left empty, a random token "
+        "is generated at startup so the API is never exposed without auth.",
+    )
     oauth_host: str = Field(
         default="localhost",
         description="Custom host for OAuth redirect (e.g., your domain or IP)",
@@ -44,6 +56,10 @@ def validate_web_auth(cls, v) -> bool:
             return normalized in ("true", "1", "yes", "on")
         return bool(v)
 
+    def is_loopback_host(self) -> bool:
+        """Return True when the server only listens on the local machine."""
+        return self.host.strip().lower() in ("127.0.0.1", "::1", "localhost", "")
+
     credentials_file: str = "credentials.json"
     token_file: str = "token.json"
 

app/main.py

@@ -9,12 +9,17 @@
 import time
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI, Request
+from fastapi import Depends, FastAPI, Request
 from fastapi.staticfiles import StaticFiles
 from fastapi.templating import Jinja2Templates
 
 from app.core import settings
 from app.api import status_router, actions_router
+from app.api.auth import (
+    get_effective_token,
+    require_api_auth,
+    resolve_effective_token,
+)
 
 templates = Jinja2Templates(directory="templates")
 
@@ -125,6 +130,10 @@ async def lifespan(app: FastAPI):
 def create_app() -> FastAPI:
     """Application factory - creates and configures the FastAPI app."""
 
+    # Decide whether the API must require a token (non-loopback bind) and, if
+    # so, which token enforces it. Done before routers are mounted.
+    resolve_effective_token()
+
     app = FastAPI(
         title=settings.app_name,
         description="Bulk unsubscribe and email management tool for Gmail",
@@ -137,19 +146,34 @@ def create_app() -> FastAPI:
     # Mount static files
     app.mount("/static", StaticFiles(directory="static"), name="static")
 
-    # Include API routers
-    app.include_router(status_router)
-    app.include_router(actions_router)
+    # Include API routers — every /api endpoint is guarded by the token check.
+    # When the server is loopback-only the dependency is a no-op, preserving the
+    # local single-user experience.
+    app.include_router(status_router, dependencies=[Depends(require_api_auth)])
+    app.include_router(actions_router, dependencies=[Depends(require_api_auth)])
 
     # HTML routes
     @app.get("/", include_in_schema=False)
     async def root(request: Request):
         """Serve the main HTML page."""
-        return templates.TemplateResponse(
+        response = templates.TemplateResponse(
             request,
             "index.html",
             {"cache_bust": STARTUP_CACHE_BUST, "version": settings.app_version},
         )
+        # Hand the same-origin browser its API token via a cookie so the UI
+        # keeps working without any client-side changes. Sent only when auth is
+        # actually in effect.
+        token = get_effective_token()
+        if token:
+            response.set_cookie(
+                "api_token",
+                token,
+                httponly=True,
+                samesite="strict",
+                secure=request.url.scheme == "https",
+            )
+        return response
 
     return app
 

docker-compose.yml

@@ -7,9 +7,12 @@ services:
     # Option 2: Build locally (uncomment below, comment out image above)
     # build: .
 
+    # Published ports are bound to host loopback only, so the API is not exposed
+    # to the local network by default. To reach it from other machines, drop the
+    # "127.0.0.1:" prefix AND set API_TOKEN below (see environment).
     ports:
-      - "8766:8766"  # Web UI
-      - "8767:8767"  # OAuth callback
+      - "127.0.0.1:8766:8766"  # Web UI
+      - "127.0.0.1:8767:8767"  # OAuth callback
     volumes:
       - type: bind
         source: ./credentials.json
@@ -28,6 +31,11 @@ services:
     environment:
       - WEB_AUTH=true
 
+      # API authentication: the container binds 0.0.0.0 internally, so the API
+      # requires a token. Pin a stable secret here; if left unset a random token
+      # is generated on each start and printed to the container logs.
+      # - API_TOKEN=change-me-to-a-long-random-secret
+
       # Uncomment and set OAUTH_HOST if accessing via custom domain or server IP
       # - OAUTH_HOST=gmail.example.com
 

main.py

@@ -18,6 +18,7 @@
 
 from app.core import settings
 from app.main import app
+from app.api.auth import get_effective_token, token_was_generated
 
 
 def main():
@@ -44,6 +45,22 @@ def main():
     print(f"\n{settings.credentials_file} found!")
 
     port = int(os.environ.get("PORT", settings.port))
+    host = settings.host
+
+    # Report the API authentication posture so the operator is never surprised.
+    token = get_effective_token()
+    if token:
+        if token_was_generated():
+            print("\nAPI authentication: ENABLED (auto-generated token)")
+            print(f"   API token: {token}")
+            print("   The web UI authenticates automatically in the browser.")
+            print("   Use this token for direct API/CLI calls:")
+            print('   Authorization: Bearer <token>   (or cookie api_token=<token>)')
+            print("   Set API_TOKEN in the environment to pin a stable token.")
+        else:
+            print("\nAPI authentication: ENABLED (API_TOKEN from environment)")
+    else:
+        print(f"\nAPI authentication: disabled (loopback-only bind on {host})")
 
     print(f"\nOpening browser at: http://localhost:{port}")
     print("   (Keep this terminal open)")
@@ -55,8 +72,9 @@ def main():
             1.0, lambda: webbrowser.open(f"http://localhost:{port}")
         ).start()
 
-    # Start FastAPI with Uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=port, log_level="warning")
+    # Start FastAPI with Uvicorn. Host defaults to loopback (see Settings.host);
+    # set HOST=0.0.0.0 to listen on all interfaces (required inside Docker).
+    uvicorn.run(app, host=host, port=port, log_level="warning")
 
 
 if __name__ == "__main__":