Introduction and Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• mkdocs.yml
• tests/README.md
• AGENTS.md
• src/flext_auth/history.json
• examples/refactored_system_showcase_04.py

FLEXT Auth is an enterprise-grade Authentication and Authorization service designed as part of the FLEXT platform. It provides a robust, typed framework for managing identities, sessions, and security tokens using a clean architecture that emphasizes scalability and security. The system is built on Python 3.13+ and integrates deeply with flext-core to provide a consistent developer experience across the platform.

Sources: README.md:1-10, pyproject.toml:22-35, src/flext_auth/history.json:20-40

System Architecture

The project follows a layered architecture pattern, separating domain logic from infrastructure and application services. This ensures that the core authentication business rules remain independent of external frameworks or storage implementations.

Architectural Layers

• Domain Layer: Contains pure constants, entities, and value objects (e.g., FlextUser, FlextSession).
• Application Layer: Orchestrates authentication workflows and use cases.
• Infrastructure Layer: Implements technical details like JWT generation and Bcrypt password hashing.

Sources: tests/README.md:25-35, tests/unit/README.md:25-45

Core Components

The system exposes a public facade via the FlextAuth class, which serves as the primary entry point for consumers.

Installation and Requirements

Environment Prerequisites

FLEXT Auth requires a modern Python environment and specific core dependencies to function correctly.

Requirement	Value	Source
Python Version	3.13+	pyproject.toml:34
Build System	hatchling	pyproject.toml:5-7
Core Dependency	flext-core	pyproject.toml:27
Security Libs	bcrypt, cryptography, pyjwt	pyproject.toml:25-31

Setup via CLI

The project provides a CLI entry point for administrative tasks and service management.

# General CLI usage
flext-auth --help

# Legacy support
flext-auth-legacy --help

Sources: pyproject.toml:132-134, README.md:43-45

Project Configuration

Configuration is managed through FlextAuthSettings, which utilizes pydantic-settings for environment-based configuration. The system uses the prefix defined in pyproject.toml for environment variables.

Key Configuration Constants

The system defines strict limits and defaults within its constant registry.

Constant	Default Value	Description
DEFAULT_JWT_ALGORITHM	HS256	Default algorithm for token signatures
MIN_PASSWORD_LENGTH	8	Minimum allowed password length
MAX_SESSIONS_PER_USER	5	Default session concurrency limit
LOCKOUT_DURATION_MINUTES	30	Duration of account lockout after failure

Sources: src/flext_auth/history.json:150-200, examples/refactored_system_showcase_04.py:53-54

Development and Quality Gates

The project maintains high quality standards through automated checks and a comprehensive test suite. Development is governed by the "Universal Agent Law" to ensure consistency across multiple contributors.

Quality Commands

• make check: Runs static analysis and linting.
• make test: Executes the test suite with a 95% minimum coverage requirement.
• make docs: Generates technical documentation via MkDocs.

Sources: README.md:43-45, tests/README.md:73-76, AGENTS.md:15-30

Testing Strategy

The testing architecture follows a pyramid strategy:

1. Unit Tests: Isolated validation of domain logic and service methods (< 100ms execution).
2. Integration Tests: Validation of service interactions and database repositories (< 1s execution).
3. E2E Tests: Complete user journey validation including registration and authentication.

Sources: tests/README.md:25-35, tests/unit/README.md:15-22

Initializing the Service

Developers can quickly start the service using the quick_start factory method, which provides a pre-configured instance of the FlextAuth service.

from flext_auth import FlextAuth

# Initialize with default settings
auth_service = FlextAuth.quick_start(create_admin_user=True)

# Register a new user
result = auth_service.register_user(
    "admin", 
    "admin@example.com", 
    "SecurePass123!"
)

Sources: examples/refactored_system_showcase_04.py:35-42, src/flext_auth/history.json:100-115

Summary

FLEXT Auth provides a structured, enterprise-ready authentication solution. By adhering to the provided setup guidelines and architectural patterns, developers can integrate secure identity management into the FLEXT platform while maintaining high code quality through established gates and strict typing.