weaver.vault.utils
==================

.. py:module:: weaver.vault.utils






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

.. py:data:: VaultInputData

.. py:data:: LOGGER

.. py:data:: REGEX_VAULT_TOKEN

.. py:data:: REGEX_VAULT_UUID

.. py:data:: REGEX_VAULT_FILENAME

.. py:function:: get_vault_dir(container: Optional[weaver.typedefs.AnySettingsContainer] = None) -> str

   Get the base directory of the secure file vault.


.. py:function:: get_vault_path(file: weaver.datatype.VaultFile, container: Optional[weaver.typedefs.AnySettingsContainer] = None) -> str

   Get the full path of the vault file.


.. py:function:: get_vault_url(file: Union[weaver.datatype.VaultFile, uuid.UUID, str], container: Optional[weaver.typedefs.AnySettingsContainer] = None) -> str

   Obtain the vault link corresponding to the file.


.. py:function:: map_vault_location(reference: str, container: weaver.typedefs.AnySettingsContainer = None, url: bool = False, exists: bool = True) -> Optional[str]

   Convert back and forth between the URL and local path references of the :term:`Vault` file.

   .. seealso::
       Similar operation to :func:`weaver.wps.utils.map_wps_output_location`.

   .. warning::
       Does not validate access token to retrieve the file. It is assumed that pre-valuation was accomplished.

   :param reference: Local file path or file URL to be mapped.
   :param container: Retrieve application settings.
   :param url: Perform URL mapping (local path -> URL endpoint), or map to local path (URL -> local path).
   :param exists: Ensure that the mapped file exists, otherwise don't map it (otherwise ``None``).
   :returns: Mapped reference if applicable, otherwise ``None``.


.. py:function:: parse_vault_token(header: Optional[str], unique: bool = False) -> Dict[Optional[str], str]

   Parse the authorization header value to retrieve all :term:`Vault` access tokens and optional file UUID.

   .. seealso::
       - Definition of expected format in :ref:`file_vault_token`.
       - :class:`sd.XAuthVaultFileHeader`

   :param header: Authorization header to parse.
   :param unique: Whether only one or multiple tokens must be retrieved.
   :return: Found mapping of UUID to access token. If unique, UUID can be ``None``.


.. py:function:: get_vault_auth(request: pyramid.request.Request) -> Tuple[weaver.typedefs.AnyUUID, Optional[str]]

   Obtain the requested file reference and parsed access token from the :term:`Vault` authorization header.

   :param request: Request containing reference file UUID and authorization headers.
   :return: Extracted file reference and authentication token.
   :raises: Appropriate HTTP exception according to use case.


.. py:function:: get_authorized_file(file_id: weaver.typedefs.AnyUUID, auth_token: str, container: Optional[weaver.typedefs.AnySettingsContainer] = None) -> weaver.datatype.VaultFile

   Obtain the requested file if access is granted.

   :param file_id: Vault storage reference file UUID.
   :param auth_token: Token or multi-token to obtain access to the file.
   :param container: Application settings.
   :return: Authorized file.
   :raises: Appropriate HTTP exception according to use case.


.. py:function:: decrypt_from_vault(vault_file: weaver.datatype.VaultFile, path: str, out_dir: Optional[str] = None, delete_encrypted: bool = False) -> str

   Decrypts a :term:`Vault` file and optionally removes its encrypted version.

   :param vault_file: Reference file in :term:`Vault`.
   :param path: Expected location of the encrypted file.
   :param out_dir: Desired output location, or temporary directory.
   :param delete_encrypted: Delete original encrypted file after decryption for output.
   :return: Output location of the decrypted file.