qts.py

#! /usr/bin/env python3
# -*- coding: utf-8; py-indent-offset: 4 -*-
#
# Author:  Linuxfabrik GmbH, Zurich, Switzerland
# Contact: info (at) linuxfabrik (dot) ch
#          https://www.linuxfabrik.ch/
# License: The Unlicense, see LICENSE file.

# https://github.com/Linuxfabrik/lib/blob/main/CONTRIBUTING.md

"""This library assists the communication with QNAP's QTS
operating system via its API.
"""

__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
__version__ = '2026082501'

import base64

from . import txt, url

try:
    import xmltodict

    LIB_XMLTODICT_FOUND = True
except ImportError:
    LIB_XMLTODICT_FOUND = False


def get_auth_sid(args):
    """
    Authenticate against the QNAP QTS API.

    This function authenticates against the QNAP QTS API and retrieves an auth SID token needed for
    other API operations.

    Parameters
    ----------
    args : object
        An argument object containing:

          - `USERNAME` (`str`): API Username.
          - `PASSWORD` (`str`): API Password.
          - `URL` (`str`): API base URL.
          - `INSECURE` (`bool`): Whether to allow insecure SSL connections.
          - `NO_PROXY` (`bool`): Whether to disable proxy usage.
          - `PROXY` (`str`, optional): Proxy to reach the target through, overriding the
            proxy the environment names.
          - `TIMEOUT` (`int`): Request timeout in seconds.

    Returns
    -------
    tuple (bool, str or error)
        - `True` and the `auth_sid` if authentication succeeds.
        - `False` and an error message if authentication fails.

    Notes
    -----
    - Requires the `xmltodict` Python library.
    - Refer to API doc: https://download.qnap.com/dev/API_QNAP_QTS_Authentication.pdf

    Examples
    --------
    >>> success, auth_sid = get_auth_sid(args)
    """
    if not LIB_XMLTODICT_FOUND:
        return False, 'Python module "xmltodict" is not installed.'

    api_url = f'{args.URL.rstrip("/")}/cgi-bin/authLogin.cgi'
    login_payload = {
        'user': args.USERNAME,
        'pwd': txt.to_text(base64.b64encode(txt.to_bytes(args.PASSWORD))),
    }
    success, result = url.fetch(
        api_url,
        data=login_payload,
        insecure=args.INSECURE,
        no_proxy=args.NO_PROXY,
        proxy=getattr(args, 'PROXY', None),
        timeout=args.TIMEOUT,
    )

    if not success:
        return False, result

    try:
        auth_result = xmltodict.parse(result)['QDocRoot']
    except Exception as e:
        return False, f'Failed to parse XML: {e}'

    if auth_result.get('authPassed') == '0':
        return False, 'Failed to authenticate.'

    return True, auth_result.get('authSid')