[Refactor] Extract the token decoder from get_current_principal

[Robbo-lab]

Issue Type

• Bug
• Feature
• Documentation
• Other

Other: auth boundary cleanup

Description

app/utils/get_principal.py currently handles too many responsibilities in one place:

• FastAPI header handling
• bearer token parsing
• principal creation
• demo auth mapping
• HTTP error handling

This makes the authentication flow harder to reuse and harder to extend later.

A small shared token-decoder interface would improve separation of concerns while keeping the current demo authentication behaviour unchanged.

Steps to Review

1. Open app/utils/get_principal.py
2. Review get_current_principal
3. Observe that FastAPI request handling and auth logic are mixed together

Expected Behaviour

Authentication logic should be separated from FastAPI request handling.

Current Behaviour

Token parsing, principal creation, and HTTP handling are all combined in one function.

Additional Context

Proposed Scope

• Add a small shared token-decoder interface
• Move token parsing and principal creation into shared auth logic
• Keep get_current_principal focused on FastAPI boundary handling only
• Preserve the current demo-token behaviour

Out of Scope

• JWT validation
• Password hashing
• Database authentication
• Role redesign
• Security framework changes

Acceptance Criteria

• A small shared auth/token interface exists
• Token parsing no longer depends directly on FastAPI classes
• get_current_principal becomes a thin FastAPI adapter
• Existing demo-token behaviour remains unchanged

Possible Solution

Create a small token-decoder service that returns Principal objects from bearer tokens, while keeping FastAPI request extraction and HTTP exceptions inside get_current_principal.

Environment

• OS: N/A
• Browser: N/A
• Version: current main branch

[Mudavath-Giri-Naik]

I'd like to work on this — planning to extract a transport-neutral token decoder and keep get_current_principal as a thin FastAPI adapter, preserving demo-token behavior.

[Robbo-lab]

Thanks @Mudavath-Giri-Naik can you expand on how you think your approach will work and benefit the project

[Mudavath-Giri-Naik]

Thanks for the question! @Robbo-lab , Here's the fuller design rationale:

The core problem is that get_current_principal currently mixes four separate concerns in one function: FastAPI header extraction, bearer-token parsing, demo-token → Principal mapping, and HTTP error translation. That makes the auth logic impossible to test without spinning up a FastAPI request context, and it would make any future transport layer (WebSocket, CLI, gRPC) have to re-implement the same parsing from scratch.

What I plan to extract is a single pure-Python function — something like decode_token(token: str) -> Principal — into a new module like app/auth/token.py. This module imports only Pydantic (Principal) and standard library, zero FastAPI. The logic inside it is exactly the current demo-token mapping, byte-for-byte identical, so existing behavior doesn't change.

get_current_principal then becomes a thin adapter — roughly 5 lines: extract the header, strip the Bearer prefix, call decode_token(), catch any ValueError the decoder raises, and translate it into an HTTPException(401). FastAPI-specific code stays in the FastAPI layer where it belongs.

Benefits to the project:

The decoder is now independently unit-testable with plain pytest — no HTTP client, no app fixture needed
When the TODO comment says "replace with JWT claims extraction", the change is isolated to decode_token() only — the FastAPI adapter doesn't need to be touched
Any future transport (MCP WebSocket, CLI tool) can call decode_token() directly without importing FastAPI
The Principal model could also move to app/auth/token.py so it's co-located with the thing that produces it
Out of scope (per the issue): JWT validation, password hashing, database auth, role redesign — I won't touch any of that.

Happy to adjust the module path or naming convention if you have a preference for where shared auth logic should live in this project. Let me know if this aligns with what you had in mind!