Add TMS credential management to dapi

Add check_credentials(), establish_credentials(), and revoke_credentials()
to manage Tapis Managed Secrets (TMS) SSH keys on TACC execution systems.
Includes CredentialError exception, 31 tests, docs, and example notebook.
Also fixes missing comma bug in __init__.py __all__ list.

Author: kks32

dapi/__init__.py

@@ -61,6 +61,7 @@
     FileOperationError,
     AppDiscoveryError,
     SystemInfoError,
+    CredentialError,
     JobSubmissionError,
     JobMonitorError,
 )
@@ -94,6 +95,8 @@
     "AuthenticationError",
     "FileOperationError",
     "AppDiscoveryError",
-    "SystemInfoError" "JobSubmissionError",
+    "SystemInfoError",
+    "CredentialError",
+    "JobSubmissionError",
     "JobMonitorError",
 ]

dapi/client.py

@@ -287,6 +287,81 @@ def list_queues(self, system_id: str, verbose: bool = True) -> List[Any]:
             self._tapis, system_id, verbose=verbose
         )
 
+    def check_credentials(
+        self, system_id: str, username: str = None
+    ) -> bool:
+        """Check whether TMS credentials exist for a user on a system.
+
+        Args:
+            system_id (str): The ID of the Tapis system (e.g., 'frontera').
+            username (str, optional): Username to check. Defaults to
+                the authenticated user.
+
+        Returns:
+            bool: True if credentials exist, False otherwise.
+
+        Raises:
+            CredentialError: If the credential check fails unexpectedly.
+            ValueError: If system_id is empty.
+        """
+        return systems_module.check_credentials(
+            self._tapis, system_id, username=username
+        )
+
+    def establish_credentials(
+        self,
+        system_id: str,
+        username: str = None,
+        force: bool = False,
+        verbose: bool = True,
+    ) -> None:
+        """Establish TMS credentials for a user on a Tapis system.
+
+        Idempotent: skips creation if credentials already exist (unless force=True).
+        Only supported for systems using TMS_KEYS authentication.
+
+        Args:
+            system_id (str): The ID of the Tapis system (e.g., 'frontera').
+            username (str, optional): Username. Defaults to the authenticated user.
+            force (bool, optional): Re-create even if credentials exist.
+                Defaults to False.
+            verbose (bool, optional): Print status messages. Defaults to True.
+
+        Raises:
+            CredentialError: If the system is not TMS_KEYS or creation fails.
+            ValueError: If system_id is empty.
+        """
+        return systems_module.establish_credentials(
+            self._tapis,
+            system_id,
+            username=username,
+            force=force,
+            verbose=verbose,
+        )
+
+    def revoke_credentials(
+        self,
+        system_id: str,
+        username: str = None,
+        verbose: bool = True,
+    ) -> None:
+        """Remove TMS credentials for a user on a Tapis system.
+
+        Idempotent: succeeds silently if credentials do not exist.
+
+        Args:
+            system_id (str): The ID of the Tapis system (e.g., 'frontera').
+            username (str, optional): Username. Defaults to the authenticated user.
+            verbose (bool, optional): Print status messages. Defaults to True.
+
+        Raises:
+            CredentialError: If credential removal fails unexpectedly.
+            ValueError: If system_id is empty.
+        """
+        return systems_module.revoke_credentials(
+            self._tapis, system_id, username=username, verbose=verbose
+        )
+
 
 class JobMethods:
     """Interface for Tapis job submission, monitoring, and management.

dapi/exceptions.py

@@ -117,6 +117,26 @@ class SystemInfoError(DapiException):
     pass
 
 
+class CredentialError(DapiException):
+    """Exception raised when credential management operations fail.
+
+    This exception is raised when operations involving Tapis Managed Secrets (TMS)
+    credentials fail, such as checking, establishing, or revoking user credentials
+    on a Tapis execution system.
+
+    Args:
+        message (str): Description of the credential operation failure.
+
+    Example:
+        >>> try:
+        ...     client.systems.establish_credentials("frontera")
+        ... except CredentialError as e:
+        ...     print(f"Credential operation failed: {e}")
+    """
+
+    pass
+
+
 class JobSubmissionError(DapiException):
     """Exception raised when job submission or validation fails.
 

dapi/systems.py

@@ -1,8 +1,8 @@
 # dapi/systems.py
 from tapipy.tapis import Tapis
-from tapipy.errors import BaseTapyException
+from tapipy.errors import BaseTapyException, UnauthorizedError, NotFoundError
 from typing import List, Any, Optional
-from .exceptions import SystemInfoError
+from .exceptions import SystemInfoError, CredentialError
 
 
 def list_system_queues(t: Tapis, system_id: str, verbose: bool = True) -> List[Any]:
@@ -95,3 +95,200 @@ def list_system_queues(t: Tapis, system_id: str, verbose: bool = True) -> List[A
         raise SystemInfoError(
             f"An unexpected error occurred while fetching queues for system '{system_id}': {e}"
         ) from e
+
+
+def _resolve_username(t: Tapis, username: Optional[str] = None) -> str:
+    """Resolve the effective username from an explicit parameter or the Tapis client.
+
+    Args:
+        t: Authenticated Tapis client instance.
+        username: Explicit username. If None, falls back to t.username.
+
+    Returns:
+        The resolved username string.
+
+    Raises:
+        ValueError: If username cannot be determined from either source.
+    """
+    effective = username or getattr(t, "username", None)
+    if not effective:
+        raise ValueError(
+            "Username must be provided or available on the Tapis client (t.username)."
+        )
+    return effective
+
+
+def check_credentials(
+    t: Tapis, system_id: str, username: Optional[str] = None
+) -> bool:
+    """Check whether TMS credentials exist for a user on a Tapis system.
+
+    Args:
+        t: Authenticated Tapis client instance.
+        system_id: The ID of the Tapis system (e.g., 'frontera', 'stampede3').
+        username: The username to check. If None, auto-detected from t.username.
+
+    Returns:
+        True if credentials exist, False if they do not.
+
+    Raises:
+        ValueError: If system_id is empty or username cannot be determined.
+        CredentialError: If an unexpected API error occurs during the check.
+    """
+    if not system_id:
+        raise ValueError("system_id cannot be empty.")
+
+    effective_username = _resolve_username(t, username)
+
+    try:
+        t.systems.checkUserCredential(
+            systemId=system_id, userName=effective_username
+        )
+        return True
+    except (UnauthorizedError, NotFoundError):
+        return False
+    except BaseTapyException as e:
+        raise CredentialError(
+            f"Failed to check credentials for user '{effective_username}' "
+            f"on system '{system_id}': {e}"
+        ) from e
+    except Exception as e:
+        raise CredentialError(
+            f"Unexpected error checking credentials for user '{effective_username}' "
+            f"on system '{system_id}': {e}"
+        ) from e
+
+
+def establish_credentials(
+    t: Tapis,
+    system_id: str,
+    username: Optional[str] = None,
+    force: bool = False,
+    verbose: bool = True,
+) -> None:
+    """Establish TMS credentials for a user on a Tapis system.
+
+    Idempotent: if credentials already exist and force is False, no action is taken.
+    Only systems with defaultAuthnMethod 'TMS_KEYS' are supported.
+
+    Args:
+        t: Authenticated Tapis client instance.
+        system_id: The ID of the Tapis system (e.g., 'frontera', 'stampede3').
+        username: The username. If None, auto-detected from t.username.
+        force: If True, create credentials even if they already exist.
+        verbose: If True, prints status messages.
+
+    Raises:
+        ValueError: If system_id is empty or username cannot be determined.
+        CredentialError: If the system does not use TMS_KEYS, if the system is
+            not found, or if credential creation fails.
+    """
+    if not system_id:
+        raise ValueError("system_id cannot be empty.")
+
+    effective_username = _resolve_username(t, username)
+
+    # Verify system exists and uses TMS_KEYS authentication
+    try:
+        system_details = t.systems.getSystem(systemId=system_id)
+        authn_method = getattr(system_details, "defaultAuthnMethod", None)
+    except BaseTapyException as e:
+        if hasattr(e, "response") and e.response and e.response.status_code == 404:
+            raise CredentialError(
+                f"System '{system_id}' not found."
+            ) from e
+        raise CredentialError(
+            f"Failed to retrieve system '{system_id}': {e}"
+        ) from e
+
+    if authn_method != "TMS_KEYS":
+        raise CredentialError(
+            f"System '{system_id}' uses authentication method '{authn_method}', "
+            f"not 'TMS_KEYS'. TMS credential management is only supported "
+            f"for TMS_KEYS systems."
+        )
+
+    # Check existing credentials unless force is True
+    if not force:
+        if check_credentials(t, system_id, effective_username):
+            if verbose:
+                print(
+                    f"Credentials already exist for user '{effective_username}' "
+                    f"on system '{system_id}'. No action taken."
+                )
+            return
+
+    # Create credentials
+    try:
+        t.systems.createUserCredential(
+            systemId=system_id,
+            userName=effective_username,
+            createTmsKeys=True,
+        )
+        if verbose:
+            print(
+                f"TMS credentials established for user '{effective_username}' "
+                f"on system '{system_id}'."
+            )
+    except BaseTapyException as e:
+        raise CredentialError(
+            f"Failed to create credentials for user '{effective_username}' "
+            f"on system '{system_id}': {e}"
+        ) from e
+    except Exception as e:
+        raise CredentialError(
+            f"Unexpected error creating credentials for user '{effective_username}' "
+            f"on system '{system_id}': {e}"
+        ) from e
+
+
+def revoke_credentials(
+    t: Tapis,
+    system_id: str,
+    username: Optional[str] = None,
+    verbose: bool = True,
+) -> None:
+    """Remove TMS credentials for a user on a Tapis system.
+
+    Idempotent: if credentials do not exist, no error is raised.
+
+    Args:
+        t: Authenticated Tapis client instance.
+        system_id: The ID of the Tapis system (e.g., 'frontera', 'stampede3').
+        username: The username. If None, auto-detected from t.username.
+        verbose: If True, prints status messages.
+
+    Raises:
+        ValueError: If system_id is empty or username cannot be determined.
+        CredentialError: If credential removal fails unexpectedly.
+    """
+    if not system_id:
+        raise ValueError("system_id cannot be empty.")
+
+    effective_username = _resolve_username(t, username)
+
+    try:
+        t.systems.removeUserCredential(
+            systemId=system_id, userName=effective_username
+        )
+        if verbose:
+            print(
+                f"Credentials revoked for user '{effective_username}' "
+                f"on system '{system_id}'."
+            )
+    except (UnauthorizedError, NotFoundError):
+        if verbose:
+            print(
+                f"No credentials found for user '{effective_username}' "
+                f"on system '{system_id}'. No action taken."
+            )
+    except BaseTapyException as e:
+        raise CredentialError(
+            f"Failed to revoke credentials for user '{effective_username}' "
+            f"on system '{system_id}': {e}"
+        ) from e
+    except Exception as e:
+        raise CredentialError(
+            f"Unexpected error revoking credentials for user '{effective_username}' "
+            f"on system '{system_id}': {e}"
+        ) from e

docs/api/exceptions.md

@@ -22,6 +22,10 @@ Custom exception classes for DAPI error handling and debugging.
 
 ::: dapi.exceptions.SystemInfoError
 
+## Credential Management Exceptions
+
+::: dapi.exceptions.CredentialError
+
 ## Job Management Exceptions
 
 ::: dapi.exceptions.JobSubmissionError

docs/api/systems.md

@@ -1,7 +1,23 @@
 # Systems
 
-System information and queue management for DesignSafe execution systems.
+System information, queue management, and TMS credential management for DesignSafe execution systems.
 
 ## System Queues
 
-::: dapi.systems.list_system_queues
+::: dapi.systems.list_system_queues
+
+## TMS Credential Management
+
+Manage Tapis Managed Secrets (TMS) credentials on execution systems. TMS credentials are SSH key pairs that allow Tapis to access TACC systems (Frontera, Stampede3, Lonestar6) on behalf of a user. They must be established once per system before submitting jobs.
+
+### Check Credentials
+
+::: dapi.systems.check_credentials
+
+### Establish Credentials
+
+::: dapi.systems.establish_credentials
+
+### Revoke Credentials
+
+::: dapi.systems.revoke_credentials