from __future__ import annotations

from fastapi import HTTPException

from backend.mcp_server.common import access_control as shared_access


def require_api_permission(role_header: str | None, action: str) -> str:
    """
    Normalize the caller role from headers and ensure it can perform the action.
    Raises HTTPException 403 if not permitted.
    Returns the normalized role for downstream logging if needed.
    """
    role = shared_access.normalize_role(role_header)
    if not shared_access.role_allows(role, action):
        allowed_roles = shared_access.describe_allowed_roles(action)
        raise HTTPException(
            status_code=403,
            detail=f"Role '{role}' lacks permission for '{action}'. Allowed roles: {allowed_roles}."
        )
    return role