imaging_api.utils.internal_auth
===============================

.. py:module:: imaging_api.utils.internal_auth

.. autoapi-nested-parse::

   Trust-internal service authentication for the imaging-api.

   The imaging-api proxies privileged XNAT operations using a service account.
   Without caller authentication, any container on the trust Docker network or
   any operator with SSM port-forward access can drive those operations as the
   service account. This module enforces a shared-secret check on every router
   that is not ``/health``: callers (trust-api, fl-client) send the plaintext
   ``TRUST_INTERNAL_SERVICE_KEY`` in a header, and imaging-api compares it to
   its own copy of the same key using constant-time comparison.

   The key is held in plaintext by every trust-internal service (sender or
   receiver) because the trust-internal trust boundary is the trust itself —
   all containers in a single trust can already talk to each other on the
   Docker network. The earlier hash-only-on-receivers split provided no real
   defence within that boundary while complicating deploy config; we collapsed
   it to a single plaintext env var.

   This is the trust-side analogue of ``flip-api``'s ``INTERNAL_SERVICE_KEY``
   (which protects fl-server → flip-api on the Central Hub). The two keys are
   deliberately distinct: a leaked trust key only compromises that trust's
   APIs, and a leaked hub key cannot drive any trust.



Attributes
----------

.. autoapisummary::

   imaging_api.utils.internal_auth._settings
   imaging_api.utils.internal_auth.internal_key_header_scheme


Functions
---------

.. autoapisummary::

   imaging_api.utils.internal_auth.authenticate_internal_service


Module Contents
---------------

.. py:data:: _settings

.. py:data:: internal_key_header_scheme

.. py:function:: authenticate_internal_service(api_key: str | None = Security(internal_key_header_scheme)) -> None

   Authenticate a trust-internal caller (trust-api, fl-client).

   :param api_key: The plaintext key from the request header.
   :type api_key: str | None

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