saamfi-sdk 0.1.0__py3-none-any.whl

saamfi_sdk/__init__.py

@@ -0,0 +1,49 @@
+"""
+Saamfi SDK for Python
+
+Python SDK to connect to SAAMFI services - Authentication and Authorization.
+
+This SDK is equivalent to saamfi-security (Java SDK) and provides the same
+functionality for systems that require integration with the Saamfi service.
+
+Basic usage:
+    >>> from saamfi_sdk import SaamfiClient
+    >>> client = SaamfiClient("https://saamfi.example.com", system_id=123)
+    >>> # Client is ready for authentication and token validation
+
+Equivalent to: co.edu.icesi.dev.saamfi.saamfisecurity (Java package)
+"""
+
+__version__ = "0.1.0"
+
+from .client import SaamfiClient
+from .exceptions import (
+    SaamfiAuthenticationError,
+    SaamfiConnectionError,
+    SaamfiException,
+    SaamfiInvalidSystemError,
+    SaamfiNotFoundError,
+    SaamfiTokenValidationError,
+    SaamfiUnauthorizedError,
+)
+from .models import LoginBody, LoginResponse, UserDetailToken, UserInfo
+
+__all__ = [
+    # Main client
+    "SaamfiClient",
+    # Models
+    "LoginBody",
+    "LoginResponse",
+    "UserInfo",
+    "UserDetailToken",
+    # Exceptions
+    "SaamfiException",
+    "SaamfiAuthenticationError",
+    "SaamfiTokenValidationError",
+    "SaamfiConnectionError",
+    "SaamfiInvalidSystemError",
+    "SaamfiUnauthorizedError",
+    "SaamfiNotFoundError",
+    # Metadata
+    "__version__",
+]

saamfi_sdk/client.py

@@ -0,0 +1,311 @@
+"""
+Main client entry point for the Saamfi SDK.
+
+This module now composes several service classes to keep responsibilities
+focused and the public API unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+from cryptography.hazmat.primitives.asymmetric import rsa
+from dotenv import load_dotenv
+
+from .models import LoginResponse, UserDetailToken, UserInfo
+from .services import (
+    AuthenticationService,
+    InstitutionService,
+    SystemService,
+    TokenService,
+    UserService,
+)
+
+# Load environment variables from .env file
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class SaamfiClient:
+    """
+    Main client for interacting with the Saamfi platform.
+
+    The class delegates most of the work to specialized service classes while
+    preserving the public interface exposed by previous versions.
+    """
+
+    ROLE_CLAIM = TokenService.ROLE_CLAIM
+    SYSTEM_CLAIM = TokenService.SYSTEM_CLAIM
+    USERNAME_CLAIM = TokenService.USERNAME_CLAIM
+    ID_CLAIM = TokenService.ID_CLAIM
+
+    def __init__(
+        self,
+        saamfi_url: Optional[str] = None,
+        system_id: Optional[int] = None,
+        client_id: Optional[int] = None,
+        client_secret: Optional[str] = None,
+        tenant_id: Optional[int] = None,
+    ):
+        """
+        Create a Saamfi client instance.
+
+        Args:
+            saamfi_url: Base URL of the Saamfi server. Falls back to the
+                `SAAMFI_BASE_URL`/`SAAMFI_URL` environment variables.
+            system_id: Tenant/system identifier. Falls back to the
+                `SAAMFI_SYS_ID`/`SAAMFI_SYSTEM_ID` environment variables.
+            client_id: OAuth-style client identifier. Falls back to the
+                `SAAMFI_CLIENT_ID` environment variable.
+            client_secret: Client secret used for confidential flows.
+                Falls back to `SAAMFI_CLIENT_SECRET`.
+            tenant_id: Institution/tenant identifier for institution-specific
+                requests. Falls back to `SAAMFI_TENANT_ID`/`SAAMFI_INST_ID`.
+
+        Raises:
+            ValueError: Missing or invalid configuration values.
+        """
+        resolved_url = saamfi_url or self._get_first_env("SAAMFI_BASE_URL", "SAAMFI_URL")
+        if not resolved_url:
+            raise ValueError(
+                "saamfi_url must be provided either as parameter or through "
+                "the SAAMFI_BASE_URL/SAAMFI_URL environment variables"
+            )
+
+        if system_id is None:
+            system_id_raw = self._get_first_env("SAAMFI_SYS_ID", "SAAMFI_SYSTEM_ID")
+            if system_id_raw is None:
+                raise ValueError(
+                    "system_id must be provided either as parameter or through "
+                    "the SAAMFI_SYS_ID/SAAMFI_SYSTEM_ID environment variables"
+                )
+            try:
+                system_id = int(system_id_raw)
+            except ValueError as exc:
+                raise ValueError(
+                    "SAAMFI_SYS_ID/SAAMFI_SYSTEM_ID environment variables must contain a valid "
+                    f"integer, got: {system_id_raw}"
+                ) from exc
+
+        if client_id is None:
+            client_id_raw = self._get_first_env("SAAMFI_CLIENT_ID")
+            if client_id_raw is not None:
+                try:
+                    client_id = int(client_id_raw)
+                except ValueError as exc:
+                    raise ValueError(
+                        "SAAMFI_CLIENT_ID environment variable must be a valid integer, "
+                        f"got: {client_id_raw}"
+                    ) from exc
+
+        if tenant_id is None:
+            tenant_id_raw = self._get_first_env("SAAMFI_TENANT_ID", "SAAMFI_INST_ID")
+            if tenant_id_raw is not None:
+                try:
+                    tenant_id = int(tenant_id_raw)
+                except ValueError as exc:
+                    raise ValueError(
+                        "SAAMFI_TENANT_ID/SAAMFI_INST_ID environment variables must contain a "
+                        f"valid integer, got: {tenant_id_raw}"
+                ) from exc
+
+        self._saamfi_url = resolved_url.rstrip("/")
+        self._system_id = system_id
+        self._client_id = client_id
+        self._client_secret = client_secret or self._get_first_env("SAAMFI_CLIENT_SECRET")
+        self._tenant_id = tenant_id
+        self._session = requests.Session()
+
+        self._token_service = TokenService(self._saamfi_url, self._session)
+        self._auth_service = AuthenticationService(
+            self._saamfi_url,
+            self._session,
+            self._system_id,
+            self._token_service,
+        )
+        self._user_service = UserService(self._saamfi_url, self._session)
+        self._institution_service = InstitutionService(self._saamfi_url, self._session)
+        self._system_service = SystemService(self._saamfi_url, self._session)
+
+        self._public_key: Optional[bytes] = None
+
+        try:
+            self._public_key = self._token_service.fetch_public_key_bytes()
+        except Exception as exc:  # pragma: no cover - initialization is best-effort
+            logger.warning("Error obtaining public key during initialization: %s", exc)
+
+    @staticmethod
+    def _get_first_env(*names: str) -> Optional[str]:
+        """Return the first non-empty environment variable among the provided names."""
+        for env_name in names:
+            value = os.getenv(env_name)
+            if value:
+                return value
+        return None
+
+    def _get_public_key(self) -> bytes:
+        """
+        Retrieve the cached raw public key (DER encoded) or fetch it from Saamfi.
+
+        Returns:
+            bytes: DER-encoded public key.
+
+        Raises:
+            SaamfiConnectionError: If the Saamfi service cannot be reached.
+        """
+        key_bytes = self._token_service.fetch_public_key_bytes()
+        self._public_key = key_bytes
+        return key_bytes
+
+    def get_public_key(self) -> rsa.RSAPublicKey:
+        """
+        Return the RSA public key used to validate Saamfi JWT tokens.
+
+        Raises:
+            SaamfiConnectionError: If the public key cannot be fetched or parsed.
+        """
+        public_key = self._token_service.get_rsa_public_key()
+        self._public_key = self._token_service.public_key_bytes
+        return public_key
+
+    @property
+    def saamfi_url(self) -> str:
+        """Base URL of the Saamfi server."""
+        return self._saamfi_url
+
+    @property
+    def system_id(self) -> int:
+        """Current tenant/system identifier."""
+        return self._system_id
+
+    @property
+    def client_id(self) -> Optional[int]:
+        """Client identifier configured for this SDK instance."""
+        return self._client_id
+
+    @property
+    def client_secret(self) -> Optional[str]:
+        """Client secret configured for this SDK instance."""
+        return self._client_secret
+
+    @property
+    def tenant_id(self) -> Optional[int]:
+        """Tenant/Institution identifier configured for this SDK instance."""
+        return self._tenant_id
+
+    def login(self, username: str, password: str) -> Optional[LoginResponse]:
+        """
+        Authenticate a user and return the login payload if successful.
+
+        Returns:
+            LoginResponse or None.
+
+        Raises:
+            SaamfiConnectionError: Request errors while contacting Saamfi.
+        """
+        return self._auth_service.login(username, password)
+
+    def get_roles_from_jwt(self, auth_token: str) -> List[str]:
+        """
+        Extract roles from a JWT token.
+
+        Returns:
+            List of role strings. Returns an empty list on any error.
+        """
+        return self._auth_service.get_roles_from_jwt(auth_token)
+
+    def validate_token(self, auth_token: str) -> UserDetailToken:
+        """
+        Validate a JWT token and return the associated user details.
+
+        Raises:
+            SaamfiTokenValidationError: Invalid or expired tokens.
+        """
+        return self._auth_service.validate_token(auth_token)
+
+    def get_user_info(self, auth_token: str, user_id: int) -> Optional[UserInfo]:
+        """
+        Retrieve complete user information by ID.
+
+        Returns:
+            UserInfo or None if the request fails or the user does not exist.
+        """
+        return self._user_service.get_user_info(auth_token, user_id)
+
+    def get_user_by_username(self, auth_token: str, username: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve a user by username.
+
+        Raises:
+            SaamfiAuthenticationError: Invalid credentials (HTTP 401).
+            SaamfiConnectionError: Other request errors.
+        """
+        return self._user_service.get_user_by_username(auth_token, username)
+
+    def get_users_by_document(self, auth_token: str, user_documents: List[str]) -> List[Dict[str, Any]]:
+        """
+        Retrieve users by document numbers.
+
+        Raises:
+            SaamfiAuthenticationError: Invalid credentials (HTTP 401).
+            SaamfiConnectionError: Other request errors.
+        """
+        return self._user_service.get_users_by_document(auth_token, user_documents)
+
+    def get_users_from_list(self, auth_token: str, user_ids: List[int]) -> Optional[str]:
+        """Retrieve multiple users by their IDs."""
+        return self._user_service.get_users_from_list(auth_token, user_ids)
+
+    def get_users_by_param_and_value(self, auth_token: str, param: str, value: str) -> Optional[str]:
+        """Retrieve users using the generic param/value endpoint."""
+        return self._user_service.get_users_by_param_and_value(auth_token, param, value)
+
+    def get_institution_by_nit(self, auth_token: str, nit: str) -> Optional[str]:
+        """Retrieve institution metadata by NIT."""
+        return self._institution_service.get_institution_by_nit(auth_token, nit)
+
+    def get_institutions_by_ids(self, auth_token: str, institution_ids: List[int]) -> Optional[str]:
+        """Retrieve multiple institutions by ID list."""
+        return self._institution_service.get_institutions_by_ids(auth_token, institution_ids)
+
+    def list_public_institutions(self) -> Optional[List[Dict[str, Any]]]:
+        """Retrieve the list of public institutions exposed by Saamfi."""
+        return self._institution_service.list_public_institutions()
+
+    def get_institution_params(
+        self, auth_token: str, institution_id: Optional[int] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Retrieve configuration parameters for an institution."""
+        target_institution = institution_id or self._tenant_id
+        if target_institution is None:
+            raise ValueError(
+                "institution_id must be provided either as parameter or configured via "
+                "SAAMFI_TENANT_ID/SAAMFI_INST_ID"
+            )
+        return self._institution_service.get_institution_params(auth_token, target_institution)
+
+    def list_public_systems(self) -> Optional[List[Dict[str, Any]]]:
+        """Retrieve the list of systems available in Saamfi."""
+        return self._system_service.list_public_systems()
+
+    def get_system_roles(
+        self, auth_token: str, system_id: Optional[int] = None
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Retrieve roles configured in a system."""
+        target_system = system_id or self._system_id
+        return self._system_service.get_system_roles(auth_token, target_system)
+
+    def __repr__(self) -> str:
+        """Object representation for debugging."""
+        return (
+            "SaamfiClient("
+            f"saamfi_url='{self._saamfi_url}', "
+            f"system_id={self._system_id}, "
+            f"tenant_id={self._tenant_id}, "
+            f"client_id={self._client_id}"
+            ")"
+        )

saamfi_sdk/exceptions.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+"""
+Custom exceptions for the Saamfi SDK.
+
+This module defines exceptions that can be raised by the SDK
+during interaction with the Saamfi service.
+"""
+
+
+class SaamfiException(Exception):
+    """
+    Base exception for all Saamfi SDK exceptions.
+
+    Parameters
+    ----------
+    message:
+        Optional custom error message. When omitted, a class-specific default
+        message is used.
+    details:
+        Optional dictionary with extra information to aid debugging or error
+        handling.
+    """
+
+    default_message = "An unexpected Saamfi SDK error occurred."
+
+    def __init__(self, message: str | None = None, *, details: dict | None = None):
+        if message is None:
+            message = self.default_message
+        super().__init__(message)
+        self.details = details or {}
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging helper
+        return f"{self.__class__.__name__}({self.args[0]!r}, details={self.details!r})"
+
+
+class SaamfiAuthenticationError(SaamfiException):
+    """Exception raised when authentication with Saamfi fails."""
+
+    default_message = "Authentication with Saamfi failed due to invalid credentials."
+
+
+class SaamfiTokenValidationError(SaamfiException):
+    """Exception raised when JWT token validation fails."""
+
+    default_message = "The provided Saamfi token is invalid or has expired."
+
+
+class SaamfiConnectionError(SaamfiException):
+    """Exception raised when there are connection issues with the Saamfi server."""
+
+    default_message = "Unable to connect or communicate with the Saamfi service."
+
+
+class SaamfiUnauthorizedError(SaamfiException):
+    """Exception raised when the caller lacks permissions for a Saamfi operation."""
+
+    default_message = "Operation not permitted: insufficient Saamfi permissions."
+
+
+class SaamfiNotFoundError(SaamfiException):
+    """Exception raised when a requested Saamfi resource cannot be found."""
+
+    default_message = "The requested Saamfi resource could not be found."
+
+
+class SaamfiInvalidSystemError(SaamfiException):
+    """Exception raised when the system_id in the token doesn't match the expected one."""
+
+    default_message = "The Saamfi token belongs to a different system than expected."

saamfi_sdk/models.py

@@ -0,0 +1,141 @@
+"""
+Data models for the Saamfi SDK.
+
+This module defines the data classes used for communication with the Saamfi service.
+All models use Pydantic for data validation.
+"""
+
+from typing import List, Optional
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+
+class LoginBody(BaseModel):
+    """
+    DTO for login requests.
+
+    Equivalent to: LoginBody.java
+    """
+
+    model_config = ConfigDict(populate_by_name=True, str_strip_whitespace=True, extra="forbid")
+
+    username: str = Field(..., description="Username")
+    password: str = Field(..., description="User password")
+    system_id: int = Field(
+        ...,
+        description="System/tenant ID",
+        serialization_alias="sysid",
+    )
+
+
+class LoginResponse(BaseModel):
+    """
+    DTO for successful authentication response.
+
+    Equivalent to: LoginResponse.java
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    id: int = Field(..., description="User ID")
+    username: str = Field(..., description="Username")
+    email: str = Field(..., description="Email address")
+    phone: Optional[str] = Field(None, description="Phone number")
+    name: str = Field(..., description="First name")
+    lastname: str = Field(..., description="Last name")
+    document_id: str = Field(
+        ...,
+        description="Document ID or ID card",
+        validation_alias=AliasChoices("documentId", "document_id"),
+        serialization_alias="documentId",
+    )
+    token: str = Field(
+        ...,
+        description="JWT access token",
+        validation_alias=AliasChoices("accessToken", "token"),
+        serialization_alias="accessToken",
+    )
+    token_type: str = Field(
+        ...,
+        description="Token type (e.g., Bearer)",
+        validation_alias=AliasChoices("tokenType", "token_type"),
+        serialization_alias="tokenType",
+    )
+    system_home_page: str = Field(
+        ...,
+        description="System home page URL",
+        validation_alias=AliasChoices("systemHomePage", "system_home_page"),
+        serialization_alias="systemHomePage",
+    )
+
+    @property
+    def access_token(self) -> str:
+        """Backwards compatibility with previous attribute name."""
+        return self.token
+
+
+class UserInfo(BaseModel):
+    """
+    DTO for detailed user information.
+
+    Equivalent to: UserInfo.java
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    email: str = Field(..., description="Email address")
+    document_id: str = Field(
+        ...,
+        description="Document ID or ID card",
+        validation_alias=AliasChoices("documentId", "document_id"),
+        serialization_alias="documentId",
+    )
+    username: str = Field(..., description="Username")
+    name: str = Field(..., description="First name")
+    lastname: str = Field(..., description="Last name")
+    phone: Optional[str] = Field(None, description="Phone number")
+    password: Optional[str] = Field(None, description="Password (usually not returned)")
+    institution: Optional[int] = Field(None, description="Institution ID")
+    institution_name: Optional[str] = Field(
+        None,
+        description="Institution name",
+        validation_alias=AliasChoices("institutionName", "institution_name"),
+        serialization_alias="institutionName",
+    )
+    system: Optional[int] = Field(None, description="System ID")
+    is_active: Optional[str] = Field(
+        None,
+        description="User active status",
+        validation_alias=AliasChoices("isActive", "is_active"),
+        serialization_alias="isActive",
+    )
+
+
+class UserDetailToken(BaseModel):
+    """
+    User information extracted from JWT token.
+
+    Equivalent to: UserDetailToken.java (Spring Security UserDetails implementation)
+
+    In Python we don't need to implement an interface like UserDetails,
+    but we maintain the same data structure.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    username: str = Field(..., description="Username")
+    system: int = Field(..., description="System ID")
+    pers_id: str = Field(
+        ...,
+        description="Person ID",
+        validation_alias=AliasChoices("persId", "pers_id"),
+        serialization_alias="persId",
+    )
+    roles: List[str] = Field(default_factory=list, description="User roles and permissions")
+
+    def __str__(self) -> str:
+        """String representation of the object, equivalent to Java's toString()."""
+        return (
+            f"UserDetailToken [persId={self.pers_id}, roles={self.roles}, "
+            f"system={self.system}, username={self.username}]"
+        )

saamfi_sdk/py.typed

@@ -0,0 +1,2 @@
+
+

saamfi_sdk/services/__init__.py

@@ -0,0 +1,18 @@
+"""Service-layer helpers used by the Saamfi client."""
+
+from .auth import AuthenticationService
+from .base import SaamfiServiceBase
+from .institutions import InstitutionService
+from .systems import SystemService
+from .token import TokenService
+from .users import UserService
+
+__all__ = [
+    "AuthenticationService",
+    "InstitutionService",
+    "SystemService",
+    "SaamfiServiceBase",
+    "TokenService",
+    "UserService",
+]
+

saamfi_sdk/services/auth.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from saamfi_sdk.exceptions import (
+    SaamfiAuthenticationError,
+    SaamfiConnectionError,
+    SaamfiTokenValidationError,
+)
+from saamfi_sdk.models import LoginBody, LoginResponse, UserDetailToken
+
+from .base import SaamfiServiceBase
+from .token import TokenService
+
+logger = logging.getLogger(__name__)
+
+
+class AuthenticationService(SaamfiServiceBase):
+    """Authentication-related operations."""
+
+    def __init__(
+        self,
+        base_url: str,
+        session,
+        system_id: int,
+        token_service: TokenService,
+    ):
+        super().__init__(base_url, session)
+        self._system_id = system_id
+        self._token_service = token_service
+
+    def login(self, username: str, password: str) -> Optional[LoginResponse]:
+        """Authenticate a user and return the login response."""
+        login_body = LoginBody(username=username, password=password, system_id=self._system_id)
+
+        try:
+            response = self._post(
+                "public/authentication/login",
+                json=login_body.model_dump(by_alias=True),
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.error("Error in authentication request: %s", exc)
+            raise SaamfiConnectionError(f"Error during authentication: {exc}") from exc
+
+        if self._is_success(response.status_code):
+            try:
+                login_response = LoginResponse(**response.json())
+            except Exception as exc:
+                logger.warning("Unexpected login response payload: %s", exc)
+                return None
+
+            logger.info("User '%s' authenticated successfully", username)
+            return login_response
+
+        if response.status_code == 401:
+            logger.warning("Authentication failed for user '%s': 401", username)
+            return None
+
+        logger.warning("Authentication failed for user '%s': %s", username, response.status_code)
+        return None
+
+    def get_roles_from_jwt(self, auth_token: str) -> list[str]:
+        """Return roles stored in the JWT token."""
+        return self._token_service.extract_roles(auth_token)
+
+    def validate_token(self, auth_token: str) -> UserDetailToken:
+        """Validate a JWT token and return user details."""
+        decoded_token = self._token_service.validate_token(auth_token)
+
+        try:
+            username = str(decoded_token.get(TokenService.USERNAME_CLAIM))
+            system = int(decoded_token.get(TokenService.SYSTEM_CLAIM))
+            pers_id = str(decoded_token.get(TokenService.ID_CLAIM))
+        except (TypeError, ValueError, KeyError) as exc:
+            logger.error("Missing required claim in token: %s", exc)
+            raise SaamfiTokenValidationError(f"Missing required claim in token: {exc}") from exc
+
+        roles = self.get_roles_from_jwt(auth_token)
+
+        user_detail = UserDetailToken(
+            username=username,
+            system=system,
+            pers_id=pers_id,
+            roles=roles,
+        )
+        logger.info("Token validated successfully for user '%s'", username)
+        return user_detail
+