flip_api.auth.access_manager

Attributes

API_KEY_HEADER_NAME

api_key_header_scheme

INTERNAL_SERVICE_KEY_HEADER_NAME

internal_key_header_scheme

_internal_service_key_hash_cache

Functions

can_access_project(→ bool)

Check if a user has access to a specific project.

can_modify_project(→ bool)

Check if a user can perform project-level write operations (edit / stage / delete the project itself).

can_contribute_to_project(→ bool)

Check if a user can contribute artefacts (e.g. models) to a project.

can_modify_model(→ bool)

Check if a user can perform write operations on a model.

can_access_model(→ bool)

Check if a user has access to a specific model.

can_access_cohort_query(→ bool)

Check if the user has access to the specified cohort query.

_get_internal_service_key_hash(→ str)

Get internal service key hash from env var (dev) or AWS Secrets Manager (prod).

authenticate_internal_service() → None)

Authenticate an internal service (e.g., fl-server on the Central Hub).

authenticate_trust(, db)

Authenticate a trust by its per-trust API key and return the resolved row.

Module Contents

flip_api.auth.access_manager.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.

Parameters:

  • user_id (UUID) – ID of the user

  • project_id (UUID) – ID of the project

  • db (Session) – Database session

Returns:

True if the user has access to the project, False otherwise

Return type:

bool

flip_api.auth.access_manager.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 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.

Parameters:

  • user_id (UUID) – ID of the user

  • project_id (UUID) – ID of the project

  • db (Session) – Database session

Returns:

True if the user can modify the project, False otherwise

Return type:

bool

flip_api.auth.access_manager.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 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).

Parameters:

  • user_id (UUID) – ID of the user

  • project_id (UUID) – ID of the project

  • db (Session) – Database session

Returns:

True if the user can contribute to the project, False otherwise.

Return type:

bool

flip_api.auth.access_manager.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 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.

Parameters:

  • user_id (UUID) – ID of the user

  • model_id (UUID) – ID of the model

  • db (Session) – Database session

Returns:

True if the user can modify the model, False otherwise

Return type:

bool

flip_api.auth.access_manager.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.

Parameters:

  • user_id (UUID) – ID of the user

  • model_id (UUID) – ID of the model

  • db (Session) – Database session

Returns:

True if the user has access to the model, False otherwise

Return type:

bool

Raises:

HTTPException – If there is an error during the access check

flip_api.auth.access_manager.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.

Parameters:

  • user_id (UUID) – ID of the user

  • query_id (UUID) – ID of the cohort query

  • db (Session) – Database session

Returns:

True if the user has access to the cohort query, False otherwise

Return type:

bool

Raises:

HTTPException – If there is an error during the access check

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: str | None = None
flip_api.auth.access_manager._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.

Return type:

str

flip_api.auth.access_manager.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.

Parameters:

api_key (str) – The internal service key from the request header.

Raises:

HTTPException – 401 if the key is missing, unconfigured, or invalid.

flip_api.auth.access_manager.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).

Parameters:

  • api_key (str) – The API key extracted from the request header.

  • db (Session) – DB session for the per-request hash lookup.

Returns:

The authenticated trust row.

Return type:

Trust

Raises:

HTTPException – 401 if the key is missing or does not match any trust.