kiarina-lib-google-auth 1.4.0__py3-none-any.whl

kiarina/lib/google/auth/__init__.py

@@ -0,0 +1,58 @@
+import logging
+from importlib import import_module
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._helpers.get_credentials import get_credentials
+    from ._helpers.get_self_signed_jwt import get_self_signed_jwt
+    from ._types.credentials import Credentials
+    from ._types.credentials_cache import CredentialsCache
+    from ._utils.get_default_credentials import get_default_credentials
+    from ._utils.get_service_account_credentials import get_service_account_credentials
+    from ._utils.get_user_account_credentials import get_user_account_credentials
+    from .settings import GoogleAuthSettings, settings_manager
+
+__version__ = version("kiarina-lib-google-auth")
+
+__all__ = [
+    # ._helpers
+    "get_credentials",
+    "get_self_signed_jwt",
+    # ._types
+    "Credentials",
+    "CredentialsCache",
+    # ._utils
+    "get_default_credentials",
+    "get_service_account_credentials",
+    "get_user_account_credentials",
+    # .settings
+    "GoogleAuthSettings",
+    "settings_manager",
+]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+def __getattr__(name: str) -> object:
+    if name not in __all__:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+    module_map = {
+        # ._helpers
+        "get_credentials": "._helpers.get_credentials",
+        "get_self_signed_jwt": "._helpers.get_self_signed_jwt",
+        # ._types
+        "Credentials": "._types.credentials",
+        "CredentialsCache": "._types.credentials_cache",
+        # ._utils
+        "get_default_credentials": "._utils.get_default_credentials",
+        "get_service_account_credentials": "._utils.get_service_account_credentials",
+        "get_user_account_credentials": "._utils.get_user_account_credentials",
+        # .settings
+        "GoogleAuthSettings": ".settings",
+        "settings_manager": ".settings",
+    }
+
+    globals()[name] = getattr(import_module(module_map[name], __name__), name)
+    return globals()[name]

kiarina/lib/google/auth/_helpers/get_credentials.py

@@ -0,0 +1,63 @@
+import google.auth.compute_engine.credentials
+import google.oauth2.credentials
+import google.oauth2.service_account
+from google.auth import impersonated_credentials
+
+from .._types.credentials import Credentials
+from .._types.credentials_cache import CredentialsCache
+from .._utils.get_default_credentials import get_default_credentials
+from .._utils.get_service_account_credentials import get_service_account_credentials
+from .._utils.get_user_account_credentials import get_user_account_credentials
+from ..settings import GoogleAuthSettings, settings_manager
+
+
+def get_credentials(
+    config_key: str | None = None,
+    *,
+    settings: GoogleAuthSettings | None = None,
+    scopes: list[str] | None = None,
+    cache: CredentialsCache | None = None,
+) -> Credentials:
+    if settings is None:
+        settings = settings_manager.get_settings_by_key(config_key)
+
+    credentials: Credentials
+
+    if settings.type == "default":
+        credentials = get_default_credentials()
+
+    elif settings.type == "service_account":
+        credentials = get_service_account_credentials(
+            service_account_file=settings.service_account_file,
+            service_account_data=settings.get_service_account_data(),
+        )
+
+    elif settings.type == "user_account":
+        credentials = get_user_account_credentials(
+            authorized_user_file=settings.authorized_user_file,
+            authorized_user_data=settings.get_authorized_user_data(),
+            scopes=scopes or settings.scopes,
+            cache=cache,
+        )
+
+    else:
+        raise ValueError(f"Unsupported credentials type: {settings.type}")
+
+    if settings.impersonate_service_account:
+        credentials = impersonated_credentials.Credentials(  # type: ignore[no-untyped-call]
+            source_credentials=credentials,
+            target_principal=settings.impersonate_service_account,
+            target_scopes=scopes or settings.scopes,
+        )
+
+    assert isinstance(
+        credentials,
+        (
+            google.auth.compute_engine.credentials.Credentials,
+            google.oauth2.service_account.Credentials,
+            google.oauth2.credentials.Credentials,
+            impersonated_credentials.Credentials,
+        ),
+    ), f"Invalid credentials type: {type(credentials)}"
+
+    return credentials

kiarina/lib/google/auth/_helpers/get_self_signed_jwt.py

@@ -0,0 +1,23 @@
+from google.auth import jwt
+from google.auth.transport.requests import Request
+
+from .get_credentials import get_credentials
+from ..settings import GoogleAuthSettings
+
+
+def get_self_signed_jwt(
+    config_key: str | None = None,
+    *,
+    settings: GoogleAuthSettings | None = None,
+    audience: str,
+) -> str:
+    """
+    Get a self-signed JWT
+    """
+    credentials = get_credentials(config_key, settings=settings)
+
+    jwt_creds = jwt.Credentials.from_signing_credentials(credentials, audience=audience)  # type: ignore[no-untyped-call]
+    # Generate a self-signed JWT. Does not communicate over the network
+    jwt_creds.refresh(Request())  # type: ignore[no-untyped-call]
+
+    return jwt_creds.token.decode("utf-8")  # type: ignore[no-any-return]

kiarina/lib/google/auth/_types/credentials.py

@@ -0,0 +1,13 @@
+from typing import TypeAlias
+
+import google.auth.compute_engine.credentials
+import google.oauth2.credentials
+import google.oauth2.service_account
+from google.auth import impersonated_credentials
+
+Credentials: TypeAlias = (
+    google.auth.compute_engine.credentials.Credentials
+    | google.oauth2.service_account.Credentials
+    | google.oauth2.credentials.Credentials
+    | impersonated_credentials.Credentials
+)

kiarina/lib/google/auth/_types/credentials_cache.py

@@ -0,0 +1,21 @@
+from typing import Protocol
+
+
+class CredentialsCache(Protocol):
+    """Protocol for a credentials cache."""
+
+    def get(self) -> str | None:
+        """Retrieve cached credentials.
+
+        Returns:
+            The cached credentials as a JSON string, or None if not found.
+        """
+        ...
+
+    def set(self, value: str) -> None:
+        """Store credentials in the cache.
+
+        Args:
+            value: The credentials to store as a JSON string.
+        """
+        ...

kiarina/lib/google/auth/_utils/get_default_credentials.py

@@ -0,0 +1,35 @@
+import google.auth.compute_engine.credentials
+import google.oauth2.credentials
+import google.oauth2.service_account
+from google.auth import default
+
+
+def get_default_credentials() -> (
+    google.auth.compute_engine.credentials.Credentials
+    | google.oauth2.credentials.Credentials
+    | google.oauth2.service_account.Credentials
+):
+    """
+    Get default Google credentials
+
+    Default credentials are determined in the following priority order:
+
+    - `google.oauth2.service_account.Credentials`
+        - When the GOOGLE_APPLICATION_CREDENTIALS environment variable is set
+    - `google.oauth2.credentials.Credentials`
+        - When credentials set by the gcloud auth application-default login command exist
+    - `google.auth.compute_engine.credentials.Credentials`
+        - When running on GCP and the metadata server is available
+    """
+    credentials, _ = default()  # type: ignore[no-untyped-call]
+
+    assert isinstance(
+        credentials,
+        (
+            google.auth.compute_engine.credentials.Credentials,
+            google.oauth2.credentials.Credentials,
+            google.oauth2.service_account.Credentials,
+        ),
+    ), f"Invalid credentials type: {type(credentials)}"
+
+    return credentials

kiarina/lib/google/auth/_utils/get_service_account_credentials.py

@@ -0,0 +1,27 @@
+import os
+
+from google.oauth2.service_account import Credentials
+
+
+def get_service_account_credentials(
+    *,
+    service_account_file: str | os.PathLike[str] | None = None,
+    service_account_data: dict[str, object] | None = None,
+) -> Credentials:
+    if service_account_data:
+        return Credentials.from_service_account_info(service_account_data)  # type: ignore[no-untyped-call, no-any-return]
+
+    elif service_account_file:
+        service_account_file = os.path.expanduser(
+            os.path.expandvars(os.fspath(service_account_file))
+        )
+
+        if not os.path.exists(service_account_file):
+            raise ValueError(
+                f"Service account file does not exist: {service_account_file}"
+            )
+
+        return Credentials.from_service_account_file(service_account_file)  # type: ignore[no-untyped-call, no-any-return]
+
+    else:
+        raise ValueError("No valid service account credentials found.")

kiarina/lib/google/auth/_utils/get_user_account_credentials.py

@@ -0,0 +1,81 @@
+import json
+import os
+
+from google.oauth2.credentials import Credentials
+from google.auth.transport.requests import Request
+
+from .._types.credentials_cache import CredentialsCache
+
+
+def get_user_account_credentials(
+    *,
+    authorized_user_file: str | os.PathLike[str] | None = None,
+    authorized_user_data: dict[str, object] | None = None,
+    scopes: list[str],
+    cache: CredentialsCache | None = None,
+) -> Credentials:
+    if authorized_user_data:
+        credentials = Credentials.from_authorized_user_info(  # type: ignore[no-untyped-call]
+            authorized_user_data,
+            scopes=scopes,
+        )
+
+        return _check_and_refresh_credentials(
+            credentials,
+            scopes=scopes,
+            cache=cache,
+        )
+
+    elif authorized_user_file:
+        authorized_user_file = os.path.expanduser(
+            os.path.expandvars(os.fspath(authorized_user_file))
+        )
+
+        if not os.path.exists(authorized_user_file):
+            raise ValueError(
+                f"Authorized user file does not exist: {authorized_user_file}"
+            )
+
+        credentials = Credentials.from_authorized_user_file(  # type: ignore[no-untyped-call]
+            authorized_user_file,
+            scopes=scopes,
+        )
+
+        return _check_and_refresh_credentials(
+            credentials,
+            scopes=scopes,
+            cache=cache,
+        )
+
+    else:
+        raise ValueError("No valid user account credentials found.")
+
+
+def _check_and_refresh_credentials(
+    credentials: Credentials,
+    *,
+    scopes: list[str],
+    cache: CredentialsCache | None = None,
+) -> Credentials:
+    if credentials.valid:
+        return credentials
+
+    if cache:
+        if cached_json_str := cache.get():
+            cached_credentials = Credentials.from_authorized_user_info(  # type: ignore[no-untyped-call]
+                json.loads(cached_json_str),
+                scopes=scopes,
+            )
+
+            if cached_credentials.valid:
+                return cached_credentials  # type: ignore[no-any-return]
+
+            credentials = cached_credentials
+
+    if credentials.expired and credentials.refresh_token:
+        credentials.refresh(Request())  # type: ignore[no-untyped-call]
+
+        if cache:
+            cache.set(credentials.to_json())  # type: ignore[no-untyped-call]
+
+    return credentials

kiarina/lib/google/auth/settings.py

@@ -0,0 +1,116 @@
+import json
+import os
+from typing import Any, Literal
+
+from pydantic import Field, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings_manager import SettingsManager
+
+
+class GoogleAuthSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="KIARINA_LIB_GOOGLE_AUTH_")
+
+    type: Literal["default", "service_account", "user_account"] = "default"
+
+    # --------------------------------------------------
+    # Fields (service_account)
+    # --------------------------------------------------
+
+    service_account_email: str | None = None
+
+    service_account_file: str | None = None
+    """Path to the service account key file"""
+
+    service_account_data: SecretStr | None = None
+    """Service account key data in JSON format"""
+
+    # --------------------------------------------------
+    # Fields (user_account)
+    # --------------------------------------------------
+
+    user_account_email: str | None = None
+
+    client_secret_file: str | None = None
+    """Path to the client secret file"""
+
+    client_secret_data: SecretStr | None = None
+    """Client secret data in JSON format"""
+
+    authorized_user_file: str | None = None
+    """Path to the authorized user file"""
+
+    authorized_user_data: SecretStr | None = None
+    """
+    Authorized user data in JSON format
+
+    If expired, retrieve from cache.
+    If cache is not available, use for refresh.
+    Refreshed credentials will be cached.
+    """
+
+    # --------------------------------------------------
+    # Fields (common)
+    # --------------------------------------------------
+
+    impersonate_service_account: str | None = None
+    """
+    Email address of the service account to impersonate
+
+    The source principal requires the roles/iam.serviceAccountTokenCreator role.
+    Note that this required permission is not included in the roles/owner role.
+    """
+
+    scopes: list[str] = Field(
+        default_factory=lambda: [
+            "https://www.googleapis.com/auth/cloud-platform",  # All GCP resources
+            "https://www.googleapis.com/auth/drive",  # Google Drive resources
+            "https://www.googleapis.com/auth/spreadsheets",  # Google Sheets resources
+        ]
+    )
+    """
+    List of scopes to request during the authentication
+
+    Specify the scopes required for impersonation authentication.
+    Specify the scopes required for user account authentication.
+    """
+
+    project_id: str | None = None
+
+    # --------------------------------------------------
+    # Validators
+    # --------------------------------------------------
+
+    @field_validator(
+        "service_account_file",
+        "client_secret_file",
+        "authorized_user_file",
+        mode="before",
+    )
+    @classmethod
+    def expand_user(cls, v: str | None) -> str | None:
+        return os.path.expanduser(v) if isinstance(v, str) else v
+
+    # --------------------------------------------------
+    # Methods
+    # --------------------------------------------------
+
+    def get_service_account_data(self) -> dict[str, Any] | None:
+        if not self.service_account_data:
+            return None
+
+        return json.loads(self.service_account_data.get_secret_value())  # type: ignore[no-any-return]
+
+    def get_client_secret_data(self) -> dict[str, Any] | None:
+        if not self.client_secret_data:
+            return None
+
+        return json.loads(self.client_secret_data.get_secret_value())  # type: ignore[no-any-return]
+
+    def get_authorized_user_data(self) -> dict[str, Any] | None:
+        if not self.authorized_user_data:
+            return None
+
+        return json.loads(self.authorized_user_data.get_secret_value())  # type: ignore[no-any-return]
+
+
+settings_manager = SettingsManager(GoogleAuthSettings, multi=True)

kiarina_lib_google_auth-1.4.0.dist-info/METADATA

@@ -0,0 +1,502 @@
+Metadata-Version: 2.4
+Name: kiarina-lib-google-auth
+Version: 1.4.0
+Summary: Google Cloud client library for kiarina namespace
+Project-URL: Homepage, https://github.com/kiarina/kiarina-python
+Project-URL: Repository, https://github.com/kiarina/kiarina-python
+Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
+Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-lib-google-auth/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-google-auth#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License-Expression: MIT
+Keywords: client,cloud,gcp,google,google-cloud,pydantic,settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: google-api-python-client>=2.184.0
+Requires-Dist: pydantic-settings-manager>=2.1.0
+Requires-Dist: pydantic-settings>=2.10.1
+Description-Content-Type: text/markdown
+
+# kiarina-lib-google-auth
+
+A Python client library for Google Cloud authentication with configuration management and support for multiple credential types.
+
+## Features
+
+- **Multiple Authentication Methods**: Support for default credentials, service accounts, and user accounts
+- **Service Account Impersonation**: Impersonate service accounts for delegated access
+- **Configuration Management**: Use `pydantic-settings-manager` for flexible configuration
+- **Credentials Caching**: Cache and refresh user account credentials automatically
+- **Self-Signed JWT**: Generate self-signed JWTs for service accounts
+- **Type Safety**: Full type hints and Pydantic validation
+
+## Installation
+
+```bash
+pip install kiarina-lib-google-auth
+```
+
+## Quick Start
+
+### Basic Usage with Default Credentials
+
+```python
+from kiarina.lib.google.auth import get_credentials
+
+# Get default credentials (ADC, service account, or compute engine)
+credentials = get_credentials()
+```
+
+### Service Account Authentication
+
+```python
+from kiarina.lib.google.auth import get_credentials, GoogleAuthSettings
+
+# From service account key file
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_file="~/path/to/service-account-key.json"
+    )
+)
+
+# From service account key data (JSON string)
+import json
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_data=json.dumps({
+            "type": "service_account",
+            "project_id": "your-project",
+            "private_key_id": "...",
+            "private_key": "...",
+            "client_email": "...",
+            # ... other fields
+        })
+    )
+)
+```
+
+### User Account Authentication
+
+```python
+from kiarina.lib.google.auth import get_credentials, GoogleAuthSettings
+
+# From authorized user file (OAuth2 credentials)
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="user_account",
+        authorized_user_file="~/path/to/authorized-user.json",
+        scopes=["https://www.googleapis.com/auth/drive"]
+    )
+)
+
+# From authorized user data (JSON string)
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="user_account",
+        authorized_user_data=json.dumps({
+            "type": "authorized_user",
+            "client_id": "...",
+            "client_secret": "...",
+            "refresh_token": "..."
+        }),
+        scopes=["https://www.googleapis.com/auth/drive"]
+    )
+)
+```
+
+### Service Account Impersonation
+
+```python
+from kiarina.lib.google.auth import get_credentials, GoogleAuthSettings
+
+# Impersonate a service account using source credentials
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_file="~/path/to/source-sa-key.json",
+        impersonate_service_account="target-sa@project.iam.gserviceaccount.com",
+        scopes=["https://www.googleapis.com/auth/cloud-platform"]
+    )
+)
+
+# Note: Source principal requires roles/iam.serviceAccountTokenCreator role
+```
+
+### Credentials Caching
+
+```python
+from kiarina.lib.google.auth import get_credentials, GoogleAuthSettings, CredentialsCache
+
+# Implement a cache (e.g., in-memory, Redis, file-based)
+class InMemoryCache(CredentialsCache):
+    def __init__(self):
+        self._cache: str | None = None
+    
+    def get(self) -> str | None:
+        return self._cache
+    
+    def set(self, value: str) -> None:
+        self._cache = value
+
+cache = InMemoryCache()
+
+# Use cache for user account credentials
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="user_account",
+        authorized_user_file="~/path/to/authorized-user.json",
+        scopes=["https://www.googleapis.com/auth/drive"]
+    ),
+    cache=cache
+)
+```
+
+### Self-Signed JWT
+
+```python
+from kiarina.lib.google.auth import get_self_signed_jwt, GoogleAuthSettings
+
+# Generate a self-signed JWT for service account
+jwt_token = get_self_signed_jwt(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_file="~/path/to/service-account-key.json"
+    ),
+    audience="https://your-service.example.com/"
+)
+```
+
+## Configuration
+
+This library uses [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) for flexible configuration management.
+
+### Environment Variables
+
+Configure authentication using environment variables:
+
+```bash
+# Authentication type
+export KIARINA_LIB_GOOGLE_AUTH_TYPE="service_account"
+
+# Service account configuration
+export KIARINA_LIB_GOOGLE_AUTH_SERVICE_ACCOUNT_FILE="~/path/to/sa-key.json"
+export KIARINA_LIB_GOOGLE_AUTH_SERVICE_ACCOUNT_EMAIL="sa@project.iam.gserviceaccount.com"
+
+# User account configuration
+export KIARINA_LIB_GOOGLE_AUTH_AUTHORIZED_USER_FILE="~/path/to/authorized-user.json"
+export KIARINA_LIB_GOOGLE_AUTH_USER_ACCOUNT_EMAIL="user@example.com"
+
+# Impersonation
+export KIARINA_LIB_GOOGLE_AUTH_IMPERSONATE_SERVICE_ACCOUNT="target-sa@project.iam.gserviceaccount.com"
+
+# Scopes (comma-separated)
+export KIARINA_LIB_GOOGLE_AUTH_SCOPES="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/drive"
+
+# Project ID
+export KIARINA_LIB_GOOGLE_AUTH_PROJECT_ID="your-project-id"
+```
+
+### Programmatic Configuration
+
+```python
+from kiarina.lib.google.auth import settings_manager, get_credentials
+
+# Configure multiple environments
+settings_manager.user_config = {
+    "development": {
+        "type": "user_account",
+        "authorized_user_file": "~/.config/gcloud/application_default_credentials.json",
+        "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
+    },
+    "production": {
+        "type": "service_account",
+        "service_account_file": "/secrets/prod-sa-key.json",
+        "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
+    }
+}
+
+# Switch to production configuration
+settings_manager.active_key = "production"
+credentials = get_credentials()
+```
+
+## API Reference
+
+### Main Functions
+
+#### `get_credentials(config_key=None, *, settings=None, scopes=None, cache=None)`
+
+Get Google Cloud credentials based on configuration.
+
+**Parameters:**
+- `config_key` (str | None): Configuration key for multi-config setup
+- `settings` (GoogleAuthSettings | None): Settings object (overrides config_key)
+- `scopes` (list[str] | None): OAuth2 scopes (overrides settings.scopes)
+- `cache` (CredentialsCache | None): Credentials cache for user accounts
+
+**Returns:**
+- `Credentials`: Google Cloud credentials object
+
+**Supported credential types:**
+- `google.auth.compute_engine.credentials.Credentials` (Compute Engine)
+- `google.oauth2.service_account.Credentials` (Service Account)
+- `google.oauth2.credentials.Credentials` (User Account)
+- `google.auth.impersonated_credentials.Credentials` (Impersonated)
+
+#### `get_self_signed_jwt(config_key=None, *, settings=None, audience)`
+
+Generate a self-signed JWT for service account authentication.
+
+**Parameters:**
+- `config_key` (str | None): Configuration key for multi-config setup
+- `settings` (GoogleAuthSettings | None): Settings object (overrides config_key)
+- `audience` (str): JWT audience (target service URL)
+
+**Returns:**
+- `str`: Self-signed JWT token
+
+### Utility Functions
+
+#### `get_default_credentials()`
+
+Get default Google credentials using Application Default Credentials (ADC).
+
+**Returns:**
+- `Credentials`: Default credentials (ADC, service account, or compute engine)
+
+#### `get_service_account_credentials(*, service_account_file=None, service_account_data=None)`
+
+Get service account credentials from file or data.
+
+**Parameters:**
+- `service_account_file` (str | PathLike | None): Path to service account key file
+- `service_account_data` (dict | None): Service account key data
+
+**Returns:**
+- `google.oauth2.service_account.Credentials`: Service account credentials
+
+#### `get_user_account_credentials(*, authorized_user_file=None, authorized_user_data=None, scopes, cache=None)`
+
+Get user account credentials from file or data.
+
+**Parameters:**
+- `authorized_user_file` (str | PathLike | None): Path to authorized user file
+- `authorized_user_data` (dict | None): Authorized user data
+- `scopes` (list[str]): OAuth2 scopes
+- `cache` (CredentialsCache | None): Credentials cache
+
+**Returns:**
+- `google.oauth2.credentials.Credentials`: User account credentials
+
+### Configuration Classes
+
+#### `GoogleAuthSettings`
+
+Pydantic settings model for Google Cloud authentication.
+
+**Fields:**
+- `type` (Literal["default", "service_account", "user_account"]): Authentication type (default: "default")
+- `service_account_email` (str | None): Service account email
+- `service_account_file` (str | None): Path to service account key file
+- `service_account_data` (str | None): Service account key data (JSON string)
+- `user_account_email` (str | None): User account email
+- `client_secret_file` (str | None): Path to client secret file
+- `client_secret_data` (str | None): Client secret data (JSON string)
+- `authorized_user_file` (str | None): Path to authorized user file
+- `authorized_user_data` (str | None): Authorized user data (JSON string)
+- `impersonate_service_account` (str | None): Target service account email for impersonation
+- `scopes` (list[str]): OAuth2 scopes (default: cloud-platform, drive, spreadsheets)
+- `project_id` (str | None): GCP project ID
+
+**Methods:**
+- `get_service_account_data()`: Parse service_account_data JSON string
+- `get_client_secret_data()`: Parse client_secret_data JSON string
+- `get_authorized_user_data()`: Parse authorized_user_data JSON string
+
+#### `CredentialsCache` (Protocol)
+
+Protocol for implementing credentials cache.
+
+**Methods:**
+- `get() -> str | None`: Retrieve cached credentials (JSON string)
+- `set(value: str) -> None`: Store credentials in cache (JSON string)
+
+## Authentication Types
+
+### 1. Default Credentials
+
+Uses Application Default Credentials (ADC) in the following priority:
+
+1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (service account key file)
+2. `gcloud auth application-default login` credentials (user account)
+3. Compute Engine metadata server (compute engine credentials)
+
+```python
+credentials = get_credentials(
+    settings=GoogleAuthSettings(type="default")
+)
+```
+
+### 2. Service Account
+
+Authenticates using a service account key file or data.
+
+```python
+# From file
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_file="~/sa-key.json"
+    )
+)
+
+# From data
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_data='{"type": "service_account", ...}'
+    )
+)
+```
+
+### 3. User Account
+
+Authenticates using OAuth2 user credentials (authorized user file).
+
+```python
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="user_account",
+        authorized_user_file="~/.config/gcloud/application_default_credentials.json",
+        scopes=["https://www.googleapis.com/auth/drive"]
+    )
+)
+```
+
+**Note:** User account credentials support automatic refresh and caching.
+
+### 4. Service Account Impersonation
+
+Impersonate a target service account using source credentials.
+
+```python
+credentials = get_credentials(
+    settings=GoogleAuthSettings(
+        type="service_account",
+        service_account_file="~/source-sa-key.json",
+        impersonate_service_account="target-sa@project.iam.gserviceaccount.com",
+        scopes=["https://www.googleapis.com/auth/cloud-platform"]
+    )
+)
+```
+
+**Required IAM Role:** The source principal must have the `roles/iam.serviceAccountTokenCreator` role on the target service account.
+
+## Default Scopes
+
+The library includes the following default scopes:
+
+- `https://www.googleapis.com/auth/cloud-platform` - All GCP resources
+- `https://www.googleapis.com/auth/drive` - Google Drive resources
+- `https://www.googleapis.com/auth/spreadsheets` - Google Sheets resources
+
+You can override these by specifying custom scopes in the configuration or function call.
+
+## Error Handling
+
+```python
+from kiarina.lib.google.auth import get_credentials, GoogleAuthSettings
+
+try:
+    credentials = get_credentials(
+        settings=GoogleAuthSettings(
+            type="service_account",
+            service_account_file="~/sa-key.json"
+        )
+    )
+except ValueError as e:
+    print(f"Configuration error: {e}")
+except FileNotFoundError as e:
+    print(f"Key file not found: {e}")
+except Exception as e:
+    print(f"Authentication failed: {e}")
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.12+
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/kiarina/kiarina-python.git
+cd kiarina-python
+
+# Setup development environment
+mise run setup
+```
+
+### Running Tests
+
+```bash
+# Run format, lint, type checks and tests
+mise run package kiarina-lib-google-auth
+
+# Coverage report
+mise run package:test kiarina-lib-google-auth --coverage
+```
+
+### Test Configuration
+
+Some tests require actual GCP credentials. Set the following environment variables:
+
+```bash
+# Service account key file
+export KIARINA_LIB_GOOGLE_AUTH_TEST_GCP_SA_KEY_FILE="~/path/to/sa-key.json"
+
+# Service account key data (JSON string)
+export KIARINA_LIB_GOOGLE_AUTH_TEST_GCP_SA_KEY_DATA='{"type": "service_account", ...}'
+
+# Authorized user file
+export KIARINA_LIB_GOOGLE_AUTH_TEST_GCP_AUTHORIZED_USER_FILE="~/.config/gcloud/application_default_credentials.json"
+
+# Authorized user data (JSON string)
+export KIARINA_LIB_GOOGLE_AUTH_TEST_GCP_AUTHORIZED_USER_DATA='{"type": "authorized_user", ...}'
+
+# Target service account for impersonation tests
+export KIARINA_LIB_GOOGLE_AUTH_TEST_GCP_IMPERSONATE_SA="target-sa@project.iam.gserviceaccount.com"
+```
+
+Tests will be skipped (xfail) if these environment variables are not set.
+
+## Dependencies
+
+- [google-api-python-client](https://github.com/googleapis/google-api-python-client) - Google API client library
+- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Contributing
+
+This is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.
+
+## Related Projects
+
+- [kiarina-python](https://github.com/kiarina/kiarina-python) - The main monorepo containing this package
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library used by this package

kiarina_lib_google_auth-1.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+kiarina/lib/google/auth/__init__.py,sha256=SdD3zDQ0MebC3qbtyjpZx3HZeUL5G-4fQ3mtqQT32us,2014
+kiarina/lib/google/auth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/google/auth/settings.py,sha256=kaOFOLl7xGQ6jOiBSjUZWLdWzj_Gic-lOAKZEE6yasg,3803
+kiarina/lib/google/auth/_helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/google/auth/_helpers/get_credentials.py,sha256=htDgNumKBwX3b11LHjRjSR-Ciou3NBWek8f7-caPy1g,2298
+kiarina/lib/google/auth/_helpers/get_self_signed_jwt.py,sha256=rAFZXBk-xM5YNCiwi9bJzY4CxpR96NRUMJbCJ8bdH4k,756
+kiarina/lib/google/auth/_types/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/google/auth/_types/credentials.py,sha256=8gjsjUydlbhW56JHfMHymbeoej5zp8ZopMQ2dYSvT70,415
+kiarina/lib/google/auth/_types/credentials_cache.py,sha256=LrcJUAxEvDJoqqX0Gq84LKp6pJz1eiAg2_530SOZeuc,483
+kiarina/lib/google/auth/_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kiarina/lib/google/auth/_utils/get_default_credentials.py,sha256=2mkQ4eWM-lpM-1L7aprw9O2U3ZB-DE75cmpYj6d2fQs,1230
+kiarina/lib/google/auth/_utils/get_service_account_credentials.py,sha256=XGV8VRTHB9fNLKN9q66cV27lBPDExYG0UUag8mU3mEg,945
+kiarina/lib/google/auth/_utils/get_user_account_credentials.py,sha256=ihko1Xf_e5EkZ1c5CjAYl8NOvjj6dKtvHl8TH_oLbTU,2353
+kiarina_lib_google_auth-1.4.0.dist-info/METADATA,sha256=_SKLvKqDNMu2Afk2Lg1WaT_It1JGyKora7Bw3y6gp-c,15973
+kiarina_lib_google_auth-1.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kiarina_lib_google_auth-1.4.0.dist-info/RECORD,,

kiarina_lib_google_auth-1.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any