Plugin and Registry Development
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Plugin and Registry Development in the FLEXT Auth ecosystem provides the structural foundation for extending enterprise authentication and authorization services. The system utilizes a centralized registry of constants, protocols, and utility managers to ensure type-safe integration and strict adherence to the FLEXT architecture patterns. This modular approach allows for the dynamic loading of skills, verification of slot registries, and enforcement of parent MRO (Method Resolution Order) chains across the platform.
The development focus centers on maintaining a "zero-debt baseline" where all extensions must comply with canonical pre-change checklists. This includes verifying the scope bootstrap and ensuring that all plugin components are registered within the FlextAuthConstants domain, which acts as the single source of truth for the entire authentication module.
Sources: README.md:14-25, AGENTS.md:9-12, src/flext_auth/history.json:28-45
Core Registry Architecture
The registry system is built upon a multi-layered constant architecture that defines the boundaries of the authentication domain. It leverages advanced Python 3.13+ features such as StrEnum for type-safe enumerations and PEP 695 type aliases to enforce strict literal types across all registered components.
Domain Constants Registry
The FlextAuthConstants class serves as the Layer 1 registry, extending core constants to provide domain-specific identifiers for token types, provider types, and security roles.
The diagram shows the hierarchical organization of the Auth registry, where enumerations are automatically converted into immutable sets for O(1) validation.
Sources: src/flext_auth/history.json:28-85
Registry Component Definitions
| Component | Registry Key | Description |
|---|---|---|
| Token Registry | Auth.TokenTypes | Registers valid token formats: access, refresh, api, bearer. |
| Provider Registry | Auth.ProviderTypes | Registers auth backends: basic, jwt, oauth2, saml, ldap. |
| Role Registry | Auth.RoleTypes | Defines system roles: admin, user, moderator, guest. |
| Method Registry | Auth.AuthMethod | Validates active auth methods like JWT or APIKEY. |
Sources: src/flext_auth/history.json:87-135, src/flext_auth/history.json:285-300
Utility and Manager Registration
The registry extends beyond pure constants into functional managers through the _utilities package. This package uses lazy loading patterns to install exports only when required, reducing the initialization overhead of the authentication service.
Manager Hierarchy
Registered managers handle specific domains of the authentication lifecycle, including session persistence, user CRUD operations, and rate limiting.
This diagram illustrates the relationship between the centralized utility registry and the specific functional managers it exports.
Sources: src/flext_auth/_utilities/__init__.py:13-60
Plugin Development Standards
Development of new plugins or extensions must follow the "Universal Agent Law" established in the project governance. This ensures that every new component maintains the architectural integrity of the MRO chain.
- Strict Typing: Plugins must use the most restrictive types available. Bare
Anyorobjecttypes are prohibited in the registry. - SSOT (Single Source of Truth): Every plugin must reference the
FlextAuthConstantsregistry for its configuration rather than defining local strings. - DI / DIP (Dependency Injection): Plugins must depend on registered protocols (
FlextAuthProtocols) rather than hard-wired logic.
Sources: AGENTS.md:35-50, README.md:21-25
Validation and Quality Gates
Every registry change is subjected to strict quality gates. The project requires a minimum of 95% test coverage for all registered logic, with specific thresholds for branch and line coverage.
The sequence shows the validation flow required before any plugin or registry mutation is committed.
Sources: tests/README.md:14-25, AGENTS.md:55-65
Registry Mutation and State Management
Registry mutations are tracked via a history.json and governed by specialized mutation classes. The system ensures that role and permission mappings remain consistent throughout the lifecycle of the application.
Security Event Registry
The system registers specific security events to monitor the state of plugins:
LOGIN_SUCCESSLOGIN_FAILURETOKEN_CREATEDTOKEN_REVOKED
Sources: src/flext_auth/history.json:340-350
Lockout and Security Registry
The registry defines critical security thresholds that plugins must respect:
- MAX_LOGIN_ATTEMPTS: Defaulted to 5.
- LOCKOUT_DURATION_MINUTES: Defaulted to 15-30 minutes depending on context.
- PERFORMANCE_THRESHOLD_MS: Set at 1000.0ms for warning thresholds.
Sources: src/flext_auth/history.json:200-220, src/flext_auth/history.json:255-265
Conclusion
Plugin and Registry Development in FLEXT Auth is a highly structured process focused on type safety, architectural consistency, and strict quality enforcement. By utilizing a centralized constant registry and lazy-loaded utility managers, the system provides a robust framework for extending enterprise authentication capabilities without compromising core system stability. Developers are mandated to follow the fixed-forward-only and SSOT principles to ensure that every extension is a first-class citizen of the FLEXT ecosystem.