auth-tls-patterns

name	auth-tls-patterns
description	Use when your service needs authentication that works without friction locally but secures remote access, automatic TLS certificate setup, or token-based auth with auto-generation and localhost bypass.

Authentication & TLS

The Pattern

Problem: Your tool serves a web UI. Locally it should just work — no passwords, no login screens. Remotely it needs real authentication and HTTPS. You don't want to configure either manually.

Approach: Socket-level localhost bypass (unforgeable), cascading auth strategies with auto-generation, and a TLS setup cascade that picks the best available method automatically.

Pattern proven in production across multiple Python CLI tools and web services.

Key Design Decisions

1. Localhost bypass — socket-level IP, not headers

The single most important auth decision: localhost connections skip all auth checks. But you MUST use the socket-level client IP, not HTTP headers:

_LOCALHOST_ADDRS = {"127.0.0.1", "::1"}

async def dispatch(self, request: Request, call_next) -> Response:
    # client.host is the socket-level IP — cannot be forged by the client
    client_host = request.client.host if request.client else ""
    if client_host in _LOCALHOST_ADDRS:
        return await call_next(request)

This is unforgeable — unlike X-Forwarded-For or the Host header, request.client.host comes from the TCP connection's source address. A remote attacker cannot set it to 127.0.0.1.

A simpler approach checks at the CLI level:

auth_required = resolved_host != "127.0.0.1" and not no_auth

2. Auth cascade: PAM > password file > auto-generate

Resolve auth mode through a fallback chain:

def _resolve_auth() -> tuple[str, str]:
    """Fallback chain for non-localhost:
      1. PAM available → ("pam", "")
      2. MY_TOOL_PASSWORD env → ("password", <env value>)
      3. ~/.config/my-tool/password file → ("password", <file value>)
      4. Auto-generate → ("password", <generated>)
    """

Auto-generation writes a random password to a file with restricted permissions:

def generate_and_save_password() -> str:
    pw = secrets.token_urlsafe(20)
    path = get_password_path()
    _config_dir()  # ensures dir exists with mode 0700
    path.write_text(pw + "\n")
    path.chmod(0o600)
    return pw

3. Token-based auth with auto-generation

A simpler bearer token approach:

def ensure_token() -> str:
    """Return the existing auth token or generate and persist a new one."""
    if TOKEN_FILE.exists():
        token = TOKEN_FILE.read_text().strip()
        if token:
            return token
    token = secrets.token_urlsafe(32)
    TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
    TOKEN_FILE.write_text(token + "\n")
    TOKEN_FILE.chmod(0o600)
    return token

The middleware checks Bearer tokens on protected paths:

class AuthMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        if not request.app.state.auth_required:
            return await call_next(request)
        path = request.url.path
        if not _is_protected(path):
            return await call_next(request)
        auth_header = request.headers.get("authorization", "")
        if auth_header.startswith("Bearer "):
            token = auth_header[7:]
            if token == request.app.state.auth_token:
                return await call_next(request)
        return JSONResponse(status_code=401, content={"detail": "Unauthorized"})

4. TLS cascade: Tailscale > mkcert > self-signed

Implement a three-tier TLS cascade, trying the best option first:

Tailscale available + cert domains? → Real Let's Encrypt cert, auto-renewed
mkcert installed?                   → Locally-trusted cert, no browser warnings
Neither?                            → Self-signed via Python cryptography library

Self-signed generation is pure Python — no openssl binary needed:

def generate_self_signed(cert_path, key_path, hostnames=None, days_valid=3650):
    from cryptography import x509
    from cryptography.hazmat.primitives import hashes, serialization
    from cryptography.hazmat.primitives.asymmetric import rsa

    private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
    # Build SAN with DNS names + loopback IPs
    san_entries = [x509.DNSName(h) for h in hostnames]
    san_entries.append(x509.IPAddress(ipaddress.IPv4Address("127.0.0.1")))
    san_entries.append(x509.IPAddress(ipaddress.IPv6Address("::1")))
    # ... build and sign cert ...
    key_path.touch(mode=0o600, exist_ok=True)   # restrictive perms BEFORE write
    key_path.write_bytes(key_pem)
    key_path.chmod(0o600)

5. Constant-time comparison for secrets

Secrets and API tokens should use hmac.compare_digest to prevent timing attacks:

if hmac.compare_digest(token, expected_key):
    return await call_next(request)

Template / Starter Code

# auth.py — localhost bypass + auto-generated token
import secrets
from pathlib import Path
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import JSONResponse

TOKEN_PATH = Path.home() / ".config" / "my-tool" / "token"
_LOCALHOST = {"127.0.0.1", "::1"}
_PUBLIC_PATHS = frozenset({"/health", "/auth/status"})

def ensure_token() -> str:
    if TOKEN_PATH.exists():
        token = TOKEN_PATH.read_text().strip()
        if token:
            return token
    token = secrets.token_urlsafe(32)
    TOKEN_PATH.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
    TOKEN_PATH.write_text(token + "\n")
    TOKEN_PATH.chmod(0o600)
    return token

class AuthMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        # Localhost bypass — socket-level IP, unforgeable
        client_host = request.client.host if request.client else ""
        if client_host in _LOCALHOST:
            return await call_next(request)
        # Public paths
        if request.url.path in _PUBLIC_PATHS:
            return await call_next(request)
        # Bearer token check
        auth = request.headers.get("authorization", "")
        if auth.startswith("Bearer ") and auth[7:] == request.app.state.auth_token:
            return await call_next(request)
        return JSONResponse(status_code=401, content={"detail": "Unauthorized"})

Note: Without initializing app.state.auth_token and app.state.auth_required, the middleware will raise AttributeError: 'State' object has no attribute 'auth_token' on the first non-localhost request. Add to your FastAPI lifespan or startup:

# In your FastAPI lifespan or startup:
app.state.auth_token = ensure_token()
app.state.auth_required = resolved_host != "127.0.0.1" and not no_auth

Gotchas & Lessons Learned

1. WebSocket connections bypass HTTP middleware. FastAPI's BaseHTTPMiddleware is only invoked for HTTP requests, not WebSocket upgrades. Implement a separate _ws_auth_check() function that verifies session cookies and bearer tokens on WebSocket connections.

2. Secrets read fresh from disk per request. Reading secrets from disk on every request rather than caching at startup lets you rotate them without restarting the server. The alternative (caching at startup) means a rotated secret doesn't take effect until restart.

3. Self-signed certs need SAN entries, not just CN. Modern browsers require Subject Alternative Name entries. Include DNS names AND IP addresses in the SAN extension. Without SANs, Chrome rejects the cert even if the CN matches.

4. Key file permissions: touch(0o600) then write_bytes() then chmod(0o600). The touch creates the file with restrictive permissions before any content is written. The final chmod ensures permissions survive regardless of umask. This belt-and-suspenders approach prevents the window where the key file exists with world-readable permissions.

5. The redaction-wipe bug. When GET /api/settings returns secret keys as "" for security, a naive PATCH back to the server overwrites real keys with empty strings. The fix preserves existing keys by identifier match with a positional fallback. Any API that redacts secrets in GET responses must handle this in the PATCH/PUT path.