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