How merixstudio/django-trench works
1. What this repository is
django-trench is a reusable Django app, not a standalone service. Its job is to add multi-factor authentication to Django REST Framework apps, with support for two main auth flows: DRF token auth and JWT-based auth.
2. Public integration surface
The package exposes API routes through trench/urls/, with separate endpoint sets for token auth and JWT auth. Matching view implementations live under trench/views/, so the library can plug into an existing Django project without owning the whole application.
3. Request handling shape
The views are likely thin orchestration layers: they receive REST requests, validate payloads through serializers, invoke command/use-case objects, and return structured responses. This keeps HTTP concerns separate from MFA business logic.
4. Core MFA domain
The persistent MFA state is modeled in trench/models.py and managed through Django migrations. This is the source of truth for things like MFA methods, activation status, primary method choice, and backup codes. The root app is a Django app with admin integration via trench/admin.py.
5. Use-case / command layer
The trench/command/ package is the main business-logic boundary. It contains explicit operations such as:
- authenticating the user’s first factor
- creating and validating OTPs
- generating secrets and backup codes
- activating/deactivating MFA methods
- selecting a primary MFA method
This suggests a command-oriented architecture where each endpoint maps to a small, named MFA action.
6. Backend abstraction for delivering second factors
The trench/backends/ package is the delivery/integration layer. base.py and provider.py define the backend abstraction, while concrete backends implement delivery via:
- SMS APIs
- Twilio
- AWS services
- YubiKey
- authenticator-app style flows
This is the main boundary between core MFA logic and external communication services.
7. OTP and secret generation flow
Second-factor setup and verification depend on generated OTPs and secrets. Those concerns are separated into commands rather than being embedded in views or backends, which means the backend is responsible for delivery or device-specific interaction, while the command layer owns the security workflow.
8. Configuration and lookup
trench/settings.py and trench/query/get_mfa_config_by_name.py indicate that MFA backends and policies are configured declaratively, then resolved at runtime. That means the app is designed to be customized per host project rather than hardcoding a single MFA policy.
9. Response and serialization boundary
trench/serializers.py, trench/responses.py, and trench/exceptions.py define the contract for API payloads and error handling. This keeps the package’s external API predictable for DRF consumers and separates domain failures from transport-level responses.
10. Email delivery assets
The templates under trench/templates/trench/backends/email/ show that at least the email backend renders both HTML and text code messages. That means email delivery is an integrated part of the library, not delegated entirely to the host app.
11. Consumer test harness
The testproject/ directory is a full Django project used to exercise the package in realistic conditions. It contains app models, URLs, serializers, migrations, and tests for first-step auth, second-step auth, token login, backends, commands, and query behavior. This is the clearest representation of how a real host project integrates trench.
12. Architecture summary
The main data flow is: client request → DRF endpoint in views/ → serializer validation → command/use-case execution → model/query access → backend delivery or verification → response token/result. The important architectural boundary is between the reusable MFA engine (models, commands, backends) and the host application’s auth stack (authtoken or JWT integration via URLs/views).
Main entry points: base.py Base View · models.py MFA Models · provider.py Provider API · create_secret.py Secrets & Codes
Components 24
Trench app
Reusable Django app providing MFA domain, commands, backends, and DRF integration.
- Base URLs · Shared endpoint definitions for the reusable MFA API.
trench/urls/base.py - Token URLs · DRF token-auth MFA endpoints.
trench/urls/authtoken.py - JWT URLs · JWT-auth MFA endpoints.
trench/urls/jwt.py - Base View · Shared REST orchestration for MFA endpoints.
trench/views/base.py - Token View · Token-auth endpoint implementation.
trench/views/authtoken.py - JWT View · JWT-auth endpoint implementation.
trench/views/jwt.py - Serializers · Request and response validation for MFA API payloads.
trench/serializers.py - Responses · Structured API response helpers.
trench/responses.py - Exceptions · Domain and API exception types.
trench/exceptions.py - MFA Models · Persistent MFA state and activation data.
trench/models.py - Settings · Declarative MFA backend and policy configuration.
trench/settings.py - Config Query · Resolves MFA configuration by name at runtime.
trench/query/get_mfa_config_by_name.py - Authenticate User · First-factor authentication use case.
trench/command/authenticate_user.py - Second Factor · Verifies second-factor credentials and OTPs.
trench/command/authenticate_second_factor.py - MFA Methods · Create, activate, deactivate, and select primary MFA methods.
trench/command/create_mfa_method.py - Secrets & Codes · Generates secrets, OTPs, and backup codes.
trench/command/create_secret.py - Backend Base · Core interface for delivering or integrating second factors.
trench/backends/base.py - Provider API · Backend provider contract and shared integration layer.
trench/backends/provider.py - Delivery Backends · Concrete backends for email, SMS, Twilio, AWS, YubiKey, and app-style flows.
trench/backends/basic_mail.py - Email Templates · HTML and text templates for email-based codes.
trench/templates/trench/backends/email/code.txt - Admin · Admin integration for managing MFA state.
trench/admin.py
Test project
Host Django project used to exercise the package in realistic integrations.
- Test URLs · Example project URL configuration for integration testing.
testproject/testapp/urls.py - Test Serializers · Example host serializers used by the test project.
testproject/testapp/serializers.py - Test Models · Example host models used to validate integration behavior.
testproject/testapp/models.py
Connections 23
- Base URLs → Base View: routes · Shared route definitions point to the base orchestration layer
- Token URLs → Token View: routes · Token endpoints map to token-auth views
- JWT URLs → JWT View: routes · JWT endpoints map to JWT views
- Base View → Serializers: validates · Views validate request payloads through serializers
- Base View → Responses: returns · Views format structured responses
- Base View → Exceptions: raises · Domain failures are surfaced as API exceptions
- Base View → Authenticate User: invokes · Endpoints start the authentication flow through commands
- Base View → Second Factor: invokes · Endpoints verify second factor through commands
- Authenticate User → MFA Models: reads/writes · Authentication commands inspect and update MFA state
- Second Factor → MFA Models: reads/writes · Second-factor verification depends on persisted MFA data
- MFA Methods → MFA Models: manages · Method commands create and update MFA method records
- Secrets & Codes → MFA Models: creates · Secret and code commands derive security material stored in the MFA domain
- Secrets & Codes → Backend Base: uses · Code generation feeds backend delivery or device workflows
- Backend Base → Provider API: extends · Provider contract builds on the backend abstraction
- Provider API → Delivery Backends: implements · Concrete adapters provide email, SMS, Twilio, AWS, and YubiKey delivery
- Delivery Backends → Email Templates: renders · Email backend uses templates for code messages
- Settings → Config Query: resolves · Configured backend names are looked up at runtime
- Config Query → Provider API: selects · Configuration lookup chooses a backend/provider implementation
- Admin → MFA Models: manages · Admin UI exposes the MFA domain model
- Test URLs → Token URLs: integrates · Test project wires the package into a host URL config
- Test URLs → JWT URLs: integrates · Test project exercises JWT endpoint wiring
- Test Serializers → Serializers: mirrors · Host serializers validate integration contracts
- Test Models → MFA Models: extends · Test project models demonstrate host-side storage patterns