kiarina-lib-firebase 2.0.0__tar.gz

kiarina_lib_firebase-2.0.0/.env.sample

@@ -0,0 +1 @@
+KIARINA_LIB_FIREBASE_TEST_SETTINGS_FILE=/path/to/your/test_settings.yaml

kiarina_lib_firebase-2.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# uv
+.uv_cache/
+
+# Virtual environments & config
+.venv/
+.env
+
+# OS
+.DS_Store
+
+# Project specific
+*.log
+tmp/
+packages/*/test_settings.yaml
+
+# Test data
+tests/data/large/
+
+# mise tasks (always include)
+!.mise/tasks/
+!.mise/tasks/**

kiarina_lib_firebase-2.0.0/.python-version

@@ -0,0 +1 @@
+3.12

kiarina_lib_firebase-2.0.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

kiarina_lib_firebase-2.0.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to kiarina-lib-firebase will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-06-10
+
+### Changed
+- No changes
+
+## [1.37.0] - 2026-05-27
+
+### Changed
+- No changes
+
+## [1.35.0] - 2026-01-31
+
+### Added
+- `TokenDataCache` protocol for persistent token storage implementations
+- `TokenManager` now supports `token_data_cache` parameter for automatic token persistence
+- Automatic token data loading from cache on first `get_id_token()` call
+- Automatic token data saving to cache after refresh
+
+### Changed
+- `TokenManager.refresh_token` and `TokenManager.token_data` are now properties that raise `AssertionError` if accessed before initialization
+
+## [1.34.0] - 2026-01-31
+
+### Changed
+- **BREAKING**: Renamed `TokenResponse` to `TokenData` for better semantic clarity
+- **BREAKING**: Changed `TokenData.expires_in` field to `TokenData.expires_at` (datetime) for improved usability
+- **BREAKING**: Changed `TokenManager.__init__` to use keyword-only arguments with `api_key` required and either `refresh_token` or `token_data` required
+- **BREAKING**: Changed `TokenManager.refresh()` return type from `TokenResponse` to `TokenData`
+
+### Added
+- `TokenData.from_api_response()` classmethod for creating TokenData from Firebase API responses
+- Field order in `TokenData`: `refresh_token`, `id_token`, `expires_at` for better readability
+
+### Fixed
+- Fixed bug where `expires_at` property calculated incorrect expiration time on each access
+
+## [1.33.1] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.33.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.32.0] - 2026-01-30
+
+### Added
+- Initial release with Firebase authentication REST API integration
+- `exchange_custom_token()` function for custom token exchange
+- `refresh_id_token()` function for ID token refresh
+- `TokenManager` service class for automatic ID token lifecycle management
+- `TokenResponse` schema for Firebase token exchange responses
+- `FirebaseAuthSettings` for configuration management
+- Exception classes: `FirebaseAuthError`, `InvalidCustomTokenError`, `InvalidRefreshTokenError`, `FirebaseAPIError`
+- Secure API key management with SecretStr
+- Multi-configuration support via pydantic-settings-manager
+- Thread-safe token refresh with asyncio.Lock
+- Automatic token refresh 5 minutes before expiration
+- Async-only API for modern Python applications
+- Environment variable configuration with `KIARINA_LIB_FIREBASE_AUTH_` prefix

kiarina_lib_firebase-2.0.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.4
+Name: kiarina-lib-firebase
+Version: 2.0.0
+Summary: Firebase authentication 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-firebase/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-firebase#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License-Expression: MIT
+Keywords: authentication,client,firebase,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: httpx>=0.28.1
+Requires-Dist: pydantic-settings-manager>=3.2.0
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic>=2.10.6
+Description-Content-Type: text/markdown
+
+# kiarina-lib-firebase
+
+Firebase authentication library with REST API integration and automatic token management.
+
+## Purpose
+
+`kiarina-lib-firebase` provides a simple and secure way to manage Firebase authentication using REST APIs. This library enables custom token exchange and automatic ID token lifecycle management with configuration management using pydantic-settings-manager.
+
+Key features:
+- Custom token exchange for refresh/ID tokens via Firebase REST API
+- Automatic ID token lifecycle management with `TokenManager`
+- Token refresh 5 minutes before expiration
+- Thread-safe token refresh with `asyncio.Lock`
+- Secure API key management with SecretStr
+- Multi-configuration support for different projects/environments
+- Async-only API for modern Python applications
+- Environment variable configuration
+
+## Installation
+
+```bash
+pip install kiarina-lib-firebase
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from kiarina.lib.firebase import (
+    TokenManager,
+    exchange_custom_token,
+    settings_manager,
+)
+
+# Configure settings
+settings_manager.user_config = {
+    "default": {
+        "project_id": "your-project-id",
+        "api_key": "your-firebase-api-key",
+    }
+}
+
+# Get settings
+settings = settings_manager.get_settings()
+api_key = settings.api_key.get_secret_value()
+
+# Exchange custom token for ID and refresh tokens
+custom_token = "your_custom_token_here"
+token_data = await exchange_custom_token(custom_token, api_key)
+
+# Create token manager for automatic token refresh
+manager = TokenManager(
+    api_key=api_key,
+    token_data=token_data,
+)
+
+# Get ID token (automatically refreshes when needed)
+id_token = await manager.get_id_token()
+print(f"ID Token: {id_token}")
+
+# Use the ID token for Firebase API calls
+# The token will be automatically refreshed 5 minutes before expiration
+```
+
+### Manual Token Refresh
+
+```python
+from kiarina.lib.firebase import refresh_id_token
+
+# Manually refresh ID token using refresh token
+token_data = await refresh_id_token(
+    refresh_token="your_refresh_token",
+    api_key="your_api_key",
+)
+
+print(f"New ID Token: {token_data.id_token}")
+print(f"Expires at: {token_data.expires_at}")
+```
+
+## API Reference
+
+### Settings
+
+#### `FirebaseSettings`
+
+Configuration for Firebase authentication.
+
+```python
+from pydantic import SecretStr
+from kiarina.lib.firebase import FirebaseSettings
+
+settings = FirebaseSettings(
+    project_id="your-project-id",
+    api_key=SecretStr("your-firebase-api-key"),
+)
+```
+
+**Fields:**
+- `project_id: str` - Firebase project ID
+- `api_key: SecretStr` - Firebase Web API Key (obtain from Firebase Console)
+
+### Functions
+
+#### `exchange_custom_token(custom_token: str, api_key: str) -> TokenData`
+
+Exchange a Firebase custom token for an ID token and refresh token.
+
+**Parameters:**
+- `custom_token: str` - Firebase custom token (JWT)
+- `api_key: str` - Firebase Web API Key
+
+**Returns:**
+- `TokenData` - Contains `refresh_token`, `id_token`, and `expires_at`
+
+**Raises:**
+- `InvalidCustomTokenError` - If the custom token is invalid or expired
+- `FirebaseAPIError` - If Firebase API returns an error
+
+#### `refresh_id_token(refresh_token: str, api_key: str) -> TokenData`
+
+Refresh ID token using refresh token.
+
+**Parameters:**
+- `refresh_token: str` - Firebase refresh token
+- `api_key: str` - Firebase Web API Key
+
+**Returns:**
+- `TokenData` - Contains new `refresh_token`, `id_token`, and `expires_at`
+
+**Raises:**
+- `InvalidRefreshTokenError` - If refresh token is invalid or expired
+- `FirebaseAPIError` - If Firebase API returns an error
+
+### Classes
+
+#### `TokenManager`
+
+Service class for automatic ID token lifecycle management.
+
+```python
+from kiarina.lib.firebase import TokenManager, TokenData
+
+# Option 1: With token_data (recommended)
+manager = TokenManager(
+    api_key="your_api_key",
+    token_data=token_data,
+    refresh_buffer_seconds=300,  # Default: 5 minutes
+)
+
+# Option 2: With refresh_token only
+manager = TokenManager(
+    api_key="your_api_key",
+    refresh_token="your_refresh_token",
+    refresh_buffer_seconds=300,  # Default: 5 minutes
+)
+
+# Option 3: With token_data_cache for persistent storage
+manager = TokenManager(
+    api_key="your_api_key",
+    token_data_cache=my_cache_implementation,
+    refresh_buffer_seconds=300,  # Default: 5 minutes
+)
+```
+
+**Constructor Parameters (all keyword-only):**
+- `api_key: str` - **Required.** Firebase Web API Key
+- `refresh_token: str | None` - Firebase refresh token (at least one of `refresh_token`, `token_data`, or `token_data_cache` is required)
+- `token_data: TokenData | None` - Initial token data (at least one of `refresh_token`, `token_data`, or `token_data_cache` is required)
+- `token_data_cache: TokenDataCache | None` - Cache implementation for persistent token storage (at least one of `refresh_token`, `token_data`, or `token_data_cache` is required)
+- `refresh_buffer_seconds: int` - Refresh buffer time in seconds (default: 300)
+
+**Methods:**
+- `async get_id_token() -> str` - Get current ID token (auto-refreshes if needed)
+- `async refresh() -> TokenData` - Manually refresh ID token
+
+**Properties:**
+- `id_token: str` - Current ID token
+- `expires_at: datetime` - Token expiration time (UTC)
+
+#### `TokenData`
+
+Schema for Firebase authentication token data.
+
+**Fields:**
+- `refresh_token: str` - Refresh token for getting new ID tokens
+- `id_token: str` - Firebase ID token (JWT)
+- `expires_at: datetime` - ID token expiration time (UTC)
+
+**Class Methods:**
+- `from_api_response(id_token: str, refresh_token: str, expires_in: int, *, issued_at: datetime | None = None) -> TokenData` - Create TokenData from Firebase API response
+
+#### `TokenDataCache`
+
+Protocol for token data cache implementations.
+
+Implementations should provide persistent storage for `TokenData`, allowing `TokenManager` to automatically save and restore token state.
+
+```python
+from kiarina.lib.firebase import TokenDataCache, TokenData
+
+class MyTokenCache(TokenDataCache):
+    async def get(self) -> TokenData:
+        # Load token data from persistent storage
+        ...
+    
+    async def set(self, token_data: TokenData) -> None:
+        # Save token data to persistent storage
+        ...
+
+# Use with TokenManager
+manager = TokenManager(
+    api_key="your_api_key",
+    token_data_cache=MyTokenCache(),
+)
+```
+
+**Methods:**
+- `async get() -> TokenData` - Retrieve cached token data
+- `async set(token_data: TokenData) -> None` - Store token data in cache
+
+### Exceptions
+
+#### `FirebaseAuthError`
+
+Base exception for Firebase Auth errors.
+
+#### `InvalidCustomTokenError`
+
+Raised when custom token is invalid or expired.
+
+#### `InvalidRefreshTokenError`
+
+Raised when refresh token is invalid or expired.
+
+#### `FirebaseAPIError`
+
+Raised when Firebase API returns an error response.
+
+**Attributes:**
+- `status_code: int | None` - HTTP status code
+- `error_code: str | None` - Firebase error code
+
+## Configuration
+
+### YAML Configuration
+
+```yaml
+kiarina.lib.firebase:
+  default:
+    project_id: your-project-id
+    api_key: your-firebase-api-key
+
+  production:
+    project_id: prod-project-id
+    api_key: ${FIREBASE_API_KEY}  # From environment variable
+```
+
+### Environment Variables
+
+Settings can be configured via environment variables with the `KIARINA_LIB_FIREBASE_` prefix:
+
+```bash
+export KIARINA_LIB_FIREBASE_PROJECT_ID=your-project-id
+export KIARINA_LIB_FIREBASE_API_KEY=your-firebase-api-key
+```
+
+### Multi-Configuration Support
+
+```python
+from kiarina.lib.firebase import settings_manager
+
+# Configure multiple environments
+settings_manager.user_config = {
+    "development": {
+        "project_id": "dev-project",
+        "api_key": "dev-api-key",
+    },
+    "production": {
+        "project_id": "prod-project",
+        "api_key": "prod-api-key",
+    },
+}
+
+# Get settings for specific environment
+dev_settings = settings_manager.get_settings("development")
+prod_settings = settings_manager.get_settings("production")
+```
+
+## Testing
+
+This package includes integration tests that require Firebase Admin SDK and Google Cloud authentication.
+
+### Setup
+
+1. Create a test settings file:
+
+```yaml
+# test_settings.yaml
+kiarina.lib.google:
+  default:
+    type: service_account
+    project_id: your-project-id
+    service_account_email: your-service-account@your-project.iam.gserviceaccount.com
+    service_account_file: ~/.gcp/service-account/your-project/key.json
+
+kiarina.lib.firebase:
+  default:
+    project_id: your-project-id
+    api_key: your-firebase-api-key
+```
+
+2. Set environment variable:
+
+```bash
+export KIARINA_LIB_FIREBASE_TEST_SETTINGS_FILE=/path/to/test_settings.yaml
+```
+
+3. Run tests:
+
+```bash
+pytest tests/
+```
+
+## Dependencies
+
+- `httpx>=0.28.1` - Async HTTP client for Firebase REST API
+- `pydantic>=2.10.6` - Data validation and settings management
+- `pydantic-settings>=2.10.1` - Settings management from environment
+- `pydantic-settings-manager>=2.3.0` - Multi-configuration settings management
+
+### Development Dependencies
+
+- `firebase-admin>=6.6.0` - Firebase Admin SDK (for testing)
+- `kiarina-lib-google>=1.22.0` - Google Cloud authentication (for testing)
+
+## License
+
+This project is licensed under the MIT License.
+
+## Related Projects
+
+- [kiarina-lib-google](https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-google) - Google Cloud authentication library
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Multi-configuration settings management