Feature/services/authenticated endpoints by mazenelabd · Pull Request #336 · Mindtrace/mindtrace

mazenelabd · 2026-01-18T12:31:35Z

Service-Level Authentication and Password Utilities

Overview

This PR introduces an authentication system for Mindtrace services, enabling instance-level authentication with Bearer token support, along with password hashing utilities in the core module.

Key Features

Service-Level Authentication

Instance-based authentication
Scope-based endpoints: Support for PUBLIC and AUTHENTICATED endpoint scopes via Scope enum
Token verification: Flexible token verification with support for both sync and async verifiers
User injection: FastAPI dependency injection for accessing current user information in endpoints

Connection Manager Header Support

Default headers: Set default headers (e.g., Authorization Bearer tokens) on connection managers for all requests
Per-request headers: Override default headers on a per-request basis

Password Hashing Utilities

Secure password hashing: New hash_password() and verify_password() utilities using Argon2 (via pwdlib)
Advanced access: get_password_hasher() for direct access to pwdlib features
Core module integration: Password utilities exported from mindtrace.core for easy access

Samples

CRUD service sample: Complete example of CRUD operations using the services module
Authenticated CRUD service: Full authentication example with MongoDB, JWT tokens, and user management
Header usage examples: Demonstrates both default and per-request header patterns

Technical Changes

Services Module (`mindtrace/services`)

Added set_token_verifier() method to Service class for instance-level token verification
Added get_auth_dependency() and get_current_user_dependency() for FastAPI integration
Enhanced add_endpoint() to support scope parameter for authentication control
Updated ConnectionManager with set_default_headers() and clear_default_headers() methods
Modified generate_connection_manager() to support header forwarding in generated methods

Core Module (`mindtrace/core`)

New password.py utility module with password hashing functions
Added pwdlib>=0.3.0 as a dependency
Updated exports to include password utilities

Testing

100% code coverage for all new lines

Usage

For Services Using Authentication

# Instance-level authentication (new way)
from mindtrace.services import Service, Scope

class MyService(Service):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.set_token_verifier(self.verify_token)
        
        self.add_endpoint("protected", self.get_data, scope=Scope.AUTHENTICATED)
    
    def verify_token(self, token: str) -> dict:
        # Your verification logic
        return {"user_id": "123"}

For Connection Managers Using Headers

# Set default headers (recommended)
cm = MyService.launch()
cm.set_default_headers({"Authorization": f"Bearer {token}"})
result = cm.protected_endpoint()  # Automatically includes headers

# Or use per-request headers
result = cm.protected_endpoint(headers={"Authorization": f"Bearer {token}"})

vik-rant · 2026-01-20T11:42:48Z

mindtrace/services/mindtrace/services/core/auth.py

+class _TokenVerifierState:
+    """Module-level state for token verifier."""
+
+    verifier: Optional[Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]] = None
+
+
+_state = _TokenVerifierState()
+
+
+def set_token_verifier(verifier: Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]):
+    """Set a custom token verification function.
+
+    The verifier function can be either synchronous or asynchronous:
+    - Accept a token string as input
+    - Return a dict with user information if token is valid (or Awaitable[dict] for async)
+    - Raise HTTPException if token is invalid
+
+    Args:
+        verifier: A function that verifies tokens and returns user info (sync or async)
+
+    Example:
+        # Synchronous verifier
+        def verify_token(token: str) -> dict:
+            # Verify JWT token, check signature, etc.
+            # Return user info like {"user_id": "123", "username": "john"}
+            pass
+
+        # Asynchronous verifier
+        async def verify_token_async(token: str) -> dict:
+            # Async token verification (e.g., checking against database)
+            pass
+
+        set_token_verifier(verify_token)  # or verify_token_async
+    """
+    _state.verifier = verifier
+
+
+def get_token_verifier() -> Optional[Callable[[str], dict]]:
+    """Get the current token verification function."""
+    return _state.verifier


module-level global token_verifier ends up getting shared by all services in a process, and cumbersome to test.
consider making it an instance variable of Service.

vik-rant · 2026-01-20T11:45:15Z

mindtrace/services/mindtrace/services/core/auth.py

+    if verifier is None:
+        return {"token": token, "authenticated": True}


failing to call set_token_verifier() (dev oversight or otherwise) on authenticated endpoints will silently grant all access.
should raise exception when no verifier is set, and authentication is expected.

vik-rant · 2026-01-20T11:48:14Z

mindtrace/services/mindtrace/services/core/auth.py

+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Token verification failed: {str(e)}",
+            headers={"WWW-Authenticate": "Bearer"},
+        ) from e


implementation details, stack traces, file paths etc. might end up in the API responses.
consider using a general response "Token verification failed" and logging the actual error server-side.

I would say it is a better practice to keep the 401 but we can replace it if you think it is better to raise some other error message
https://security.stackexchange.com/questions/110759/unauthorized-access-to-a-page-when-or-if-you-should-return-401-http-status-cod#/

Yes, I am not suggesting to remove the 401.
We should return a 401 response but without the details of e (which may include local implementation-specific details.
Instead log the error details from e and then continue raising 401.

Makes sense

vik-rant · 2026-01-20T12:00:03Z

mindtrace/services/mindtrace/services/core/auth.py

+class _TokenVerifierState:
+    """Module-level state for token verifier."""
+
+    verifier: Optional[Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]] = None


Suggested change

verifier: Optional[Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]] = None

verifier: Callable[[str], dict | Awaitable[dict]] | None = None

vik-rant · 2026-01-20T12:00:34Z

mindtrace/services/mindtrace/services/core/auth.py

+_state = _TokenVerifierState()
+
+
+def set_token_verifier(verifier: Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]):


Suggested change

def set_token_verifier(verifier: Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]):

def set_token_verifier(verifier: Callable[[str], dict | Awaitable[dict]]):

vik-rant · 2026-01-20T12:01:15Z

mindtrace/services/mindtrace/services/core/auth.py

+    _state.verifier = verifier
+
+
+def get_token_verifier() -> Optional[Callable[[str], dict]]:


Suggested change

def get_token_verifier() -> Optional[Callable[[str], dict]]:

def get_token_verifier() -> Callable[[str], dict | Awaitable[dict]] | None:

vik-rant · 2026-01-20T12:03:25Z

mindtrace/services/mindtrace/services/core/auth.py

+
+    try:
+        # Check if verifier is async
+        if inspect.iscoroutinefunction(verifier):


Suggested change

if inspect.iscoroutinefunction(verifier):

if inspect.isawaitable(verifier):

Thanks for the suggestion. inspect.isawaitable() doesn't work on function objects, it only works on coroutines/futures. We need to check before calling whether the function is async, so I think iscoroutinefunction() is the right approach here. I also came across this aio-libs/sphinxcontrib-asyncio#4.
Please let me know if I am missing something.

You're right.
I missed adding a key line in the suggestion.
The general idea is:

async def verify_token(token: str) -> dict: try: user_info = verifier(token) # missed this line earlier. If sync, we already have a result, otherwise check if we need to await if inspect.isawaitable(user_info): user_info = await user_info return user_info except HTTPException: raise except Exception as e: raise HTTPException(401) from e

Sometimes sync functions may return awaitables (Future, a wrapped async def, or something with an __await__ or an async __call__), or if token verifier is decorated (logging, retry, caching, tracing, etc.), then:

inspect.iscoroutinefunction(verifier)

will return False. But:

res = verifier(token) inspect.isawaitable(res)

will handle all these cases.

iscoroutinefunction() answers "was this written as async def?"
isawaitable() answers "do we need to await this now?"
Runtime execution should care about the second one IMO.

vik-rant · 2026-01-20T12:06:37Z

mindtrace/services/mindtrace/services/core/service.py

+        if isinstance(scope, str):
+            try:
+                scope = Scope(scope.lower())
+            except ValueError:
+                self.logger.warning("Invalid scope '%s', defaulting to PUBLIC", scope)
+                scope = Scope.PUBLIC


let's prefer to raise and fail fast when an incorrect scope str is provided while adding endpoints.
currently a typo like scope="authenticate" will just log a warning and make the endpoint public.

vik-rant · 2026-01-20T12:07:43Z

mindtrace/services/mindtrace/services/core/service.py

+        # Add authentication dependency if required
+        dependencies = list(api_route_kwargs.get("dependencies", []))
+        if auth_dependency is not None:
+            dependencies.append(auth_dependency)


auth_dependency should be inserted first to perform auth check first and fail fast?

vik-rant · 2026-01-20T12:18:39Z

samples/services/crud_auth/auth_crud_service.py

+from mindtrace.core import TaskSchema
+from mindtrace.database import MindtraceDocument, MongoMindtraceODM
+from mindtrace.services import Scope, Service, set_token_verifier
+from mindtrace.services.core.auth import verify_token as get_current_user


confusing alias change from verify_token (semantically f(token: str) -> bool) to get_current_user (semantically f(?) -> User/dict/?) in the very first sample usage a user encounters. What is this function supposed to do?

vik-rant · 2026-01-20T12:21:06Z

samples/services/crud_auth/auth_crud_service.py

+            updated_at=user.updated_at.isoformat(),
+        )
+
+    async def get_user(self, user_id: str, current_user: dict = Depends(get_current_user)) -> UserOutput:


Depends(get_current_user) will run the auth check a second time. Would have already been called once when we hit the endpoint since it is added as Scope.AUTHENTICATED in add_endpoint()?

mindtrace/services/mindtrace/services/core/auth.py

…a service level instead of module level

This reverts commit 1f7dc12.

This reverts commit 8eea53d.

… a return value

vik-rant · 2026-01-27T13:22:33Z

samples/services/crud_auth/auth_crud_service.py

+        set_service_instance(self)
+
+        # Set up token verification (use async version)
+        self.set_user_authenticator(verify_token_async)


instead of a module-level verify_token_async and a freestanding set_service_instance, can it be a bound method on the service, e.g. self.verify_token_async and no need for global set_service_instance stuff.
Overall i think we should clarify the following processes:

extraction of token via schemes

verifying a token, and extracting claims

loading user details from verified claims

usage of scope.AUTHENTICATED on self.add_endpoint() vs (or +) current_user=Depends(self.get_current_user) on the endpoint function definition. Which one does what, how to use them, is it one vs the other or both? Is the result from one cached and fed to the other, or is JWT decoding + DB fetch being repeated?

example flow for an endpoint seems to be:

Request to /get_user with Bearer token │ ├─► scope=Scope.AUTHENTICATED triggers _create_verify_token_dependency() │ └─► calls verify_token_async(token) ← FIRST CALL (DB lookup, JWT decode) │ └─► Depends(get_current_user) triggers _create_get_user_dependency() └─► calls verify_token_async(token) ← SECOND CALL (same work repeated)

vik-rant · 2026-01-27T15:01:45Z

samples/services/crud_auth/auth_crud_service.py

+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash.
+
+    Uses pwdlib with Argon2 as recommended by FastAPI.
+
+    Args:
+        plain_password: Plain text password
+        hashed_password: Hashed password from database
+
+    Returns:
+        True if password matches, False otherwise
+    """
+    return password_hash.verify(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    """Hash a password using Argon2.
+
+    Uses pwdlib with Argon2 as recommended by FastAPI.
+
+    Args:
+        password: Plain text password
+
+    Returns:
+        Hashed password string
+    """
+    return password_hash.hash(password)


We can use hash_password and verify_password from mindtrace.core now.
There is also a convenience util verify_and_maybe_upgrade which should be useful for login flows.

uzairali19 · 2026-01-29T14:15:08Z

mindtrace/services/mindtrace/services/core/service.py

+    def get_auth_dependency(self, scope: Scope):
+        """Get authentication dependency based on scope for this service instance.
+
+        Args:
+            scope: The endpoint scope (PUBLIC or AUTHENTICATED)
+
+        Returns:
+            Security dependency for AUTHENTICATED scope, None for PUBLIC
+        """
+        if scope == Scope.AUTHENTICATED:
+            return Security(self._create_verify_token_dependency())
+        return None
+
+    def get_current_user_dependency(self):
+        """Get a FastAPI dependency for accessing the current authenticated user.
+
+
+        Returns:
+            A FastAPI dependency function that returns the current user dict
+
+        Example:
+            get_current_user = service.get_current_user_dependency()
+
+            async def my_endpoint(
+                self,
+                current_user: Annotated[dict, Depends(get_current_user)]
+            ):
+                user_id = current_user["user_id"]
+                # Use user data for authorization, etc.
+        """
+        return self._create_get_user_dependency()
+


We are creating a new HTTPBearer() instance, inside both _create_verify_token_dependency() and _create_get_user_dependency().

Since get_auth_dependency() and get_current_user_dependency() call these methods during route registration, this results in multiple security scheme instances being created and duplicated entries in the OpenAPI specification.

We should create a single HTTPBearer instance (for example, in __init__ or set_user_authenticator()) and reuse it across.

fastapi/fastapi#2750

uzairali19 · 2026-01-29T14:21:23Z

mindtrace/services/mindtrace/services/core/service.py

+                )
+
+            try:
+                result = authenticator(token)


If I have an endpoint that uses both, the scope as Scope.AUTHENTICATED and Depends(get_current_user), the authenticator function is executed twice per request:
• once via the route-level Security dependency
• once via the Depends(get_current_user) injection

Both are calling the authenticator independently, and they don't share the state. FastAPI’s dependency caching does not apply here because these are different dependency functions.

This results in duplicate JWT verification/database lookups per request and could be avoided by sharing or caching the authentication result per request.

https://fastapi.tiangolo.com/tutorial/dependencies/#caching-dependencies

Interesting. The fastapi link shared here has no section #caching-dependencies. AI-generated link?

That is interesting indeed 😁
There isn’t a public changelog for documentation anchors.

The behavior I’m referring to is still documented under “Using the same dependency multiple times”:
https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times

FastAPI caches dependencies per request only when the same dependency callable is reused.
Using both Security(...) and Depends(get_current_user) creates dependency entries, so the auth logic runs twice.

The behavior itself hasn't changed

uzairali19 · 2026-01-29T14:23:11Z

mindtrace/services/mindtrace/services/core/service.py

+
+            service.set_user_authenticator(authenticate_user)  # or authenticate_user_lightweight or authenticate_user_async
+        """
+        self.user_authenticator = authenticator


Over here, the set_user_authenticator() directly assigns self.user_authenticator with no safeguards.

If this method is called again at runtime (or set to None), the service's authentication behaviour would silently change or break.

We should restrict this to one-time initialization at startup or guard it against reassignment after service is launched.

https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/02-Configuration_and_Deployment_Management_Testing/

uzairali19 · 2026-01-29T14:26:33Z

mindtrace/services/mindtrace/services/core/service.py

+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Token verification failed",
+                    headers={"WWW-Authenticate": "Bearer"},
+                ) from e


Over here, even if the HTTP response body is sanitized, the original exception is still attached as __cause__ and can be exploited by logging, middleware, or a monitoring system.

If e contains sensitive information (such as database or infrastructure details), this could unintentionally leak through logs or error pipelines. If full suppression is intended, from None would be safer.

https://owasp.org/www-community/Improper_Error_Handling

uzairali19 · 2026-01-29T14:30:33Z

mindtrace/services/mindtrace/services/core/service.py

+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+
+            token = credentials.credentials


This is bad, we are sending raw credentials.credentials value without any validation directly to the authenticator.

I could give this some random large strings on the Authentication header, potentially triggering expensive JWT parsing or database lookups and creating a denial-of-service vector.

We should add some basic safeguards, max length format validation, before invoking the authenticator.

https://owasp.org/www-community/attacks/Denial_of_Service

uzairali19 · 2026-01-29T14:42:11Z

mindtrace/services/mindtrace/services/core/service.py

+                if user_info is None:
+                    raise HTTPException(
+                        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                        detail="User authenticator returned None. get_current_user_dependency() requires an authenticator that returns user data (dict).",
+                        headers={"WWW-Authenticate": "Bearer"},


We are exposing the internal method name here and the implementation details. Is this intended? Why are we doing this?

We should have a generic internal error message for this case

https://owasp.org/www-community/Improper_Error_Handling

uzairali19 · 2026-01-29T14:46:06Z

mindtrace/services/mindtrace/services/core/service.py

We should enforce Authentication for the MCP tools as well.

When this is called on the service level, the tool will bypass the authentication regardless of the scope parameter.

Tools are externally callable as well

…cation to use a shared dependency for efficiency

…ime disabling

…ndling

…tication process

vik-rant · 2026-02-11T10:27:02Z

mindtrace/services/mindtrace/services/core/connection_manager.py

+            # All subsequent requests will include the Authorization header
+            result = cm.some_endpoint(...)
+        """
+        self._default_headers.update(headers)


this function is updating, not setting.

mazenelabd added 6 commits January 16, 2026 17:52

feature/services: support authentcation using the scope flag

6e221a7

test/services: auth feature

cf90c84

test/services: auth features

8a9b4b8

feat/services: increase test coverage and update ruff linting

592a46d

sample/services: crud sample to using the services module

48b777a

sample/services: auth crud operations

8f149e9

mazenelabd requested a review from vik-rant January 18, 2026 12:31

mazenelabd self-assigned this Jan 18, 2026

mazenelabd added 4 commits January 18, 2026 12:36

update: ruff linting

f2bc906

update: exclude .md from ruff parsing

fa3fb1f

rollback: docker import change

b2f242c

fix: ruff import sorting in test_docker_env.py

b214502

mazenelabd linked an issue Jan 19, 2026 that may be closed by this pull request

Add authenticated endpoints to the services module #340

Open

vik-rant reviewed Jan 20, 2026

View reviewed changes

mindtrace/services/mindtrace/services/core/auth.py Outdated Show resolved Hide resolved

mazenelabd added 5 commits January 21, 2026 14:34

services/feature: get_current_user_dependency and making the auth on …

8b6d302

…a service level instead of module level

services/auth: integration tests

90af1f7

services/feature: pass headers from the connection manager

4e922f6

services/update: replace the iscoroutinefunction with an isawaitable

9445e18

Merge branch 'dev' into feature/services/authenticated-endpoints

3529933

mazenelabd and others added 6 commits January 22, 2026 11:18

feat(core): Add password hashing utilities using pwdlib

8eea53d

fix(core): Fix ruff formatting in password.py

1f7dc12

Revert "fix(core): Fix ruff formatting in password.py"

2c2c852

This reverts commit 1f7dc12.

Revert "feat(core): Add password hashing utilities using pwdlib"

df78fde

This reverts commit 8eea53d.

core: add fingerprint and password hash utils with unit tests

6685aca

feat(services): rename verify to authenticate_user and accept none as…

c950266

… a return value

vik-rant reviewed Jan 27, 2026

View reviewed changes

uzairali19 requested changes Jan 29, 2026

View reviewed changes

mazenelabd added 8 commits February 10, 2026 11:54

feat(services): enhance authentication flow and refactor token verifi…

79921b5

…cation to use a shared dependency for efficiency

refactor(auth): replace pwdlib with core password hashing utilities

8ab4b41

Merge branch 'dev' into feature/services/authenticated-endpoints

67e419a

fix(auth): enforce single user authenticator setting and prevent runt…

618bd1f

…ime disabling

fix(auth): suppress exception chaining in token verification error ha…

c6e685c

…ndling

feat(auth): add maximum length validation for Bearer tokens in authen…

33f051c

…tication process

fix(auth): update error message for authentication configuration failure

a96c7af

feat(auth): implement authenticated tool wrapper for MCP service tools

f818c64

vik-rant reviewed Feb 11, 2026

View reviewed changes

		if verifier is None:
		return {"token": token, "authenticated": True}

	verifier: Optional[Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]] = None
	verifier: Callable[[str], dict \| Awaitable[dict]] \| None = None

		_state = _TokenVerifierState()


		def set_token_verifier(verifier: Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]):

	def set_token_verifier(verifier: Union[Callable[[str], dict], Callable[[str], Awaitable[dict]]]):
	def set_token_verifier(verifier: Callable[[str], dict \| Awaitable[dict]]):

		_state.verifier = verifier


		def get_token_verifier() -> Optional[Callable[[str], dict]]:

	def get_token_verifier() -> Optional[Callable[[str], dict]]:
	def get_token_verifier() -> Callable[[str], dict \| Awaitable[dict]] \| None:

	if inspect.iscoroutinefunction(verifier):
	if inspect.isawaitable(verifier):

Conversation

mazenelabd commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Service-Level Authentication and Password Utilities

Overview

Key Features

Service-Level Authentication

Connection Manager Header Support

Password Hashing Utilities

Samples

Technical Changes

Services Module (mindtrace/services)

Core Module (mindtrace/core)

Testing

Usage

For Services Using Authentication

For Connection Managers Using Headers

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vik-rant Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

uzairali19 Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

mazenelabd commented Jan 18, 2026 •

edited

Loading

Services Module (`mindtrace/services`)

Core Module (`mindtrace/core`)

vik-rant Jan 27, 2026 •

edited

Loading

uzairali19 Jan 29, 2026 •

edited

Loading