Authentication and Security

Relevant source files

The following files were used as context for generating this wiki page: - [monGARS/api/authentication.py](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS/api/authentication.py) - [monGARS/core/security.py](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS/core/security.py) - [monGARS/api/web_api.py](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS/api/web_api.py) - [tests/test_user_management.py](https://github.com/ales27pm/monGARS/blob/HEAD/tests/test_user_management.py) - [monGARS/core/operator_approvals.py](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS/core/operator_approvals.py) - [monGARS/api/rate_limiter.py](https://github.com/ales27pm/monGARS/blob/HEAD/monGARS/api/rate_limiter.py) - [README.md](https://github.com/ales27pm/monGARS/blob/HEAD/README.md)

The monGARS application employs a robust, multi-layered security model centered around a FastAPI backend. The system has evolved from using in-memory demo users to a persistent, database-backed authentication flow, enhancing security and stability. Core security features include JWT-based authentication, role-based access control (RBAC), per-user rate limiting, and a dedicated workflow for operator approvals on sensitive actions.

Security is managed through a combination of FastAPI dependencies, middleware, and dedicated core service modules. The SecurityManager class is central to handling password hashing and JWT operations, while specific endpoints and dependencies enforce authentication and authorization rules throughout the API.

Authentication

Authentication is handled via OAuth2 with JWT bearer tokens. The system provides endpoints for user registration, login (token issuance), and password management. All user credentials are now persisted in a database, a significant security improvement over previous versions that used hard-coded demo users.

Sources: monGARS/api/web_api.py, monGARS/api/authentication.py, ROADMAP.md:10-12, tests/test_user_management.py

User and Token Management

The SecurityManager class is the primary component for handling security-critical operations like password hashing and token management. It uses passlib for password verification and python-jose for JWT creation and validation.

Sources: monGARS/core/security.py:27-101

The main authentication-related endpoints are:

Endpoint	Method	Description	Authentication
/token	POST	Issues a JWT access token upon successful login.	None
/api/v1/user/register	POST	Registers a new standard user.	None
/api/v1/user/register/admin	POST	Registers the first administrator account. Fails if an admin already exists.	None
/api/v1/user/change-password	POST	Allows an authenticated user to change their own password.	User

Sources: monGARS/api/web_api.py:657-788, tests/test_user_management.py:53-120

Login Flow

The login process involves the user submitting their username and password to the /token endpoint. The authenticate_user function validates the credentials against the database, and if successful, SecurityManager generates a JWT.

This diagram illustrates the user login sequence.

Authorization

Authorization is implemented using role-based access control (RBAC). The JWT payload contains claims indicating the user's role, primarily user or admin. FastAPI dependencies inspect the token from incoming requests to grant or deny access.

Sources: monGARS/api/authentication.py:42-88, tests/test_user_management.py:217-225

Roles and Dependencies

Two key dependencies enforce authorization:

• get_current_user: Ensures a valid JWT is present, regardless of role.
• get_current_admin_user: Ensures the JWT belongs to a user with the admin role.

Endpoints are protected by including one of these as a dependency. For example, listing all users requires admin privileges.

# monGARS/api/web_api.py:738-743
@app.get("/api/v1/user/list", response_model=UserListResponse)
async def list_users(
    current_admin: Annotated[dict, Depends(get_current_admin_user)],
    repo: Annotated[PersistenceRepository, Depends(get_persistence_repository)],
) -> UserListResponse:

This diagram shows the authorization check flow for a request to a protected endpoint.

Operator Approvals

For particularly sensitive operations, monGARS uses an explicit approval mechanism. This system ensures that certain actions cannot be performed without a manual review and approval from a user with the operator role. This adds a layer of human-in-the-loop security.

The OperatorApprovalService and OperatorApprovalRegistry are the core components managing this workflow.

Sources: monGARS/core/operator_approvals.py, monGARS/api/web_api.py:200-233, configs/agents/agents_config.json

Approval Flow

1. An action requiring approval is initiated, and a request is submitted to the OperatorApprovalRegistry.
2. The registry creates a unique, pending approval request with an associated token.
3. An operator reviews the request.
4. The operator calls the /llm/security/approve endpoint, providing the request token and their own operator credentials.
5. The system validates the operator's identity and the request token, then marks the request as approved.

This sequence diagram details the operator approval process.

Rate Limiting

To protect against brute-force attacks and denial-of-service, the API implements rate limiting.

Sources: monGARS/api/web_api.py:255-270, monGARS/api/rate_limiter.py

Chat Endpoint Limiting

The chat endpoint (/api/v1/conversation/chat) is specifically protected by an InMemoryRateLimiter. This limiter is user-specific and configured with a default interval of 1 second between requests.

• Class: InMemoryRateLimiter
• Configuration:
  • interval_seconds: 1.0
  • prune_after_seconds: 60.0
• Behavior: If a user exceeds the limit, the request is rejected, and a warning is logged via the _log_rate_limit callback.

The enforce_chat_rate_limit dependency applies this check to the chat endpoint.

Sources: monGARS/api/rate_limiter.py:13-64, monGARS/api/web_api.py:267-270, monGARS/api/web_api.py:410-414

Global Rate Limiting

In addition to the specific chat limiter, a global rate limiter is applied to all endpoints via SlowAPIMiddleware. This provides a baseline level of protection across the entire API surface.

Sources: monGARS/api/web_api.py:228-231

Summary

The security architecture of monGARS is comprehensive, addressing authentication, authorization, and abuse prevention. By moving to a database-backed user store and implementing features like role-based access, operator approvals for sensitive actions, and multi-level rate limiting, the project establishes a strong security posture. The modular design, with components like SecurityManager and OperatorApprovalService, ensures that security logic is centralized and consistently applied.