flip_api.auth.access_manager ============================ .. py:module:: flip_api.auth.access_manager Attributes ---------- .. autoapisummary:: flip_api.auth.access_manager.API_KEY_HEADER_NAME flip_api.auth.access_manager.api_key_header_scheme flip_api.auth.access_manager.INTERNAL_SERVICE_KEY_HEADER_NAME flip_api.auth.access_manager.internal_key_header_scheme flip_api.auth.access_manager._internal_service_key_hash_cache Functions --------- .. autoapisummary:: flip_api.auth.access_manager.can_access_project flip_api.auth.access_manager.can_modify_project flip_api.auth.access_manager.can_contribute_to_project flip_api.auth.access_manager.can_modify_model flip_api.auth.access_manager.can_access_model flip_api.auth.access_manager.can_access_cohort_query flip_api.auth.access_manager._get_internal_service_key_hash flip_api.auth.access_manager.authenticate_internal_service flip_api.auth.access_manager.authenticate_trust Module Contents --------------- .. py:function:: can_access_project(user_id: uuid.UUID, project_id: uuid.UUID, db: sqlmodel.Session) -> bool Check if a user has access to a specific project. :param user_id: ID of the user :type user_id: UUID :param project_id: ID of the project :type project_id: UUID :param db: Database session :type db: Session :returns: True if the user has access to the project, False otherwise :rtype: bool .. py:function:: can_modify_project(user_id: uuid.UUID, project_id: uuid.UUID, db: sqlmodel.Session) -> bool Check if a user can perform project-level write operations (edit / stage / delete the project itself). Returns True for Admins (CAN_MANAGE_PROJECTS) and the project owner. Project membership alone does NOT unlock project-level writes — see :func:`can_contribute_to_project` for the looser check used by model-write endpoints. Ownership is deliberately NOT re-checked against the owner's current role: a user who created a project keeps project-level writes (edit / stage / delete, and cohort-submit via ``submit_cohort_query``) even if later demoted to Viewer. Ownership is the authority here, not the active role. This is an accepted gap — to fully revoke an owner's access, transfer ownership or delete the project. See the Viewer role notes in ``docs/source/sys-admin/admin-user-roles.rst``. :param user_id: ID of the user :type user_id: UUID :param project_id: ID of the project :type project_id: UUID :param db: Database session :type db: Session :returns: True if the user can modify the project, False otherwise :rtype: bool .. py:function:: can_contribute_to_project(user_id: uuid.UUID, project_id: uuid.UUID, db: sqlmodel.Session) -> bool Check if a user can contribute artefacts (e.g. models) to a project. Looser than :func:`can_modify_project`: a Researcher who has been added to a project via ``ProjectUserAccess`` can contribute their own models even though they cannot edit the project itself. Viewers — who hold no permissions — are excluded by the ``CAN_CREATE_PROJECTS`` clause, so membership alone does not unlock writes for them. Returns True when any of the following holds: - The caller has ``CAN_MANAGE_PROJECTS`` (Admin), or - The caller is the project owner, or - The caller has a ``ProjectUserAccess`` row for the project AND holds ``CAN_CREATE_PROJECTS`` (Researcher member). :param user_id: ID of the user :type user_id: UUID :param project_id: ID of the project :type project_id: UUID :param db: Database session :type db: Session :returns: True if the user can contribute to the project, False otherwise. :rtype: bool .. py:function:: can_modify_model(user_id: uuid.UUID, model_id: uuid.UUID, db: sqlmodel.Session) -> bool Check if a user can perform write operations on a model. Allows: - Admins (``CAN_MANAGE_PROJECTS``). - The project owner (unrestricted across all models on the project). - The model's own ``owner_id``, but only if they could still contribute to the project (per :func:`can_contribute_to_project`). The contribution check is defence-in-depth: it locks a Viewer out even if they somehow ended up as ``Model.owner_id``. :param user_id: ID of the user :type user_id: UUID :param model_id: ID of the model :type model_id: UUID :param db: Database session :type db: Session :returns: True if the user can modify the model, False otherwise :rtype: bool .. py:function:: can_access_model(user_id: uuid.UUID, model_id: uuid.UUID, db: sqlmodel.Session) -> bool Check if a user has access to a specific model. :param user_id: ID of the user :type user_id: UUID :param model_id: ID of the model :type model_id: UUID :param db: Database session :type db: Session :returns: True if the user has access to the model, False otherwise :rtype: bool :raises HTTPException: If there is an error during the access check .. py:function:: can_access_cohort_query(user_id: uuid.UUID, query_id: uuid.UUID, db: sqlmodel.Session) -> bool Check if the user has access to the specified cohort query. :param user_id: ID of the user :type user_id: UUID :param query_id: ID of the cohort query :type query_id: UUID :param db: Database session :type db: Session :returns: True if the user has access to the cohort query, False otherwise :rtype: bool :raises HTTPException: If there is an error during the access check .. py:data:: API_KEY_HEADER_NAME .. py:data:: api_key_header_scheme .. py:data:: INTERNAL_SERVICE_KEY_HEADER_NAME .. py:data:: internal_key_header_scheme .. py:data:: _internal_service_key_hash_cache :type: str | None :value: None .. py:function:: _get_internal_service_key_hash() -> str Get internal service key hash from env var (dev) or AWS Secrets Manager (prod). Cached after first call — the hash does not change during the lifetime of a process. :returns: SHA-256 hex digest of the internal service key, or empty string if not configured. :rtype: str .. py:function:: authenticate_internal_service(api_key: str = Security(internal_key_header_scheme)) -> None Authenticate an internal service (e.g., fl-server on the Central Hub). The fl-server sends an internal service key in the X-Internal-Service-Key header. This dependency hashes the provided key and compares it against the stored hash using constant-time comparison. :param api_key: The internal service key from the request header. :type api_key: str :raises HTTPException: 401 if the key is missing, unconfigured, or invalid. .. py:function:: authenticate_trust(api_key: str = Security(api_key_header_scheme), db: sqlmodel.Session = Depends(get_session)) -> flip_api.db.models.main_models.Trust Authenticate a trust by its per-trust API key and return the resolved row. The ``trust`` DB table is the sole registry: each row carries an ``api_key_hash`` set when the trust is registered (admin UI or deploy-time CLI). This dependency hashes the provided key and walks every trust row whose ``api_key_hash`` is set, returning the matching ``Trust`` row. Identity (the row's ``id`` and ``name``) is then available to handlers without re-querying. Constant-time comparison (``hmac.compare_digest``) on every candidate prevents timing side-channels (would otherwise leak which trust the key belongs to via early-exit timing). :param api_key: The API key extracted from the request header. :type api_key: str :param db: DB session for the per-request hash lookup. :type db: Session :returns: The authenticated trust row. :rtype: Trust :raises HTTPException: 401 if the key is missing or does not match any trust.