Python implementation of Better Auth - a multi-repository, multi-language authentication protocol.
This is a full Python port of the TypeScript reference implementation with both client and server components.
- ✅ Client + Server - Full protocol implementation
- ✅ Type-Safe - Comprehensive type hints using Python's typing system
- ✅ Async First - Built with async/await throughout
- ✅ Complete Test Suite - Unit tests covering all authentication flows
- ✅ Example Server - HTTP server for integration testing
This repository is a submodule of the main spec repository. For the full multi-language setup, see the parent repository.
make setup # Create venv and install dependenciesmake test # Run pytest
make type-check # Run mypy type checker
make lint # Run ruff linter
make format-check # Check code formattingmake server # Start HTTP server on localhost:8080This implementation uses:
- Python 3.11+ for modern type hints and async support
- pytest for testing
- mypy for type checking
- black for formatting
- ruff for linting
All development commands use standardized make targets:
make setup # Create venv and pip install -e ".[dev]"
make test # Run pytest
make type-check # Type check with mypy
make lint # Lint with ruff
make format # Format with black
make format-check # Check formatting
make clean # Remove venv and build artifacts
make server # Run example serverSee CLAUDE.md for detailed architecture documentation including:
- Directory structure and key components
- Python-specific patterns (Protocol types, dataclasses, async/await)
- Interface definitions and message types
- Usage examples and API patterns
- Protocol Types: Uses Python's
Protocoltype for structural subtyping - Dataclasses: All messages defined as
@dataclasswith type hints - Async Throughout: All operations use Python's
async/await - Custom Exceptions:
BetterAuthError,AuthenticationError,VerificationError, etc.
The tests/implementation/ directory contains reference implementations using:
- blake3 for cryptographic hashing
- cryptography library for ECDSA P-256 signing/verification
- secrets module for secure random nonce generation
- datetime for RFC3339 timestamps
- gzip for token compression
This Python implementation can be used:
- As a client for testing against TypeScript, Rust, Go, or Ruby servers
- As a server for testing TypeScript, Python, Rust, Swift, Dart, or Kotlin clients
See examples/server.py for the HTTP server implementation.
Full Implementations (Client + Server):
- TypeScript - Reference implementation
- Python - This repository
- Rust
Server-Only:
Client-Only:
MIT