singlestore-auth-iam 0.4.0__tar.gz

singlestore_auth_iam-0.4.0/.gitignore

@@ -0,0 +1,184 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Go specific
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go build program.
+go/debug_gcp_assume_role/debug-gcp-assume-role
+go/s2iam_example_server/s2iam-example-server
+
+# Go module download cache
+go/pkg/
+go/bin/
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+.temporary/
+
+# local evelopment-specific copilot instructions 
+.github/copilot-dev-guide.md
+
+# Python-specific excludes
+python/LICENSE
+
+# === Project-specific ephemeral artifacts ===
+*-log
+
+# Coverage artifacts aggregated locally after remote download
+go-coverage.out
+python-coverage.xml
+java-coverage.xml
+go-coverage-*.out
+python-coverage-*.xml
+java-coverage-*.xml
+
+# JaCoCo & Maven build outputs (Maven target/ already indirectly covered for python target but add explicit java target)
+java/target/
+
+# test junk
+go/s2iam_test_server_info*.json
+
+# Generated API docs (build with make docs-api-html or CI Pages deploy)
+docs/api/api.html
+docs/api/index.html

singlestore_auth_iam-0.4.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: singlestore-auth-iam
+Version: 0.4.0
+Summary: SingleStore IAM authentication library for cloud providers
+Project-URL: Homepage, https://github.com/singlestore-labs/singlestore-auth-iam
+Project-URL: Repository, https://github.com/singlestore-labs/singlestore-auth-iam
+Project-URL: Issues, https://github.com/singlestore-labs/singlestore-auth-iam/issues
+Author: SingleStore Labs
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: azure-identity>=1.12.0
+Requires-Dist: boto3>=1.26.0
+Requires-Dist: cryptography>=3.4.8
+Requires-Dist: google-auth-oauthlib>=0.8.0
+Requires-Dist: google-auth>=2.15.0
+Requires-Dist: pyjwt>=2.6.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: types-requests>=2.28.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SingleStore Auth IAM - Python Client Library
+
+A Python client library for getting JWTs from SingleStore's IAM service when running in cloud environments (AWS, GCP, Azure).
+
+## Installation
+
+```bash
+pip install singlestore-auth-iam
+```
+
+## Quick Start
+
+```python
+import asyncio
+from s2iam import get_jwt_database
+
+async def main():
+        # Get a JWT for database access
+    jwt = await get_jwt_database("your-workspace-group-id")
+    print(f"JWT: {jwt}")
+
+    # Or without workspace group ID
+    jwt = await get_jwt_database()
+    print(f"JWT: {jwt}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+For API gateway access:
+
+```python
+import asyncio
+from s2iam import get_jwt_api
+
+async def main():
+    # Get a JWT for API gateway access
+    jwt = await get_jwt_api()
+    print(f"JWT: {jwt}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+That's it! The library automatically detects your cloud environment and gets the appropriate JWT.
+
+## Configuration
+
+### Environment Variables
+
+- `S2IAM_SERVER_URL`: Custom authentication server URL (default: https://auth.singlestore.com)
+- `S2IAM_DEBUGGING`: Set to "true" to enable debug logging
+
+## Supported Environments
+
+The library automatically detects and works in:
+
+- **AWS**: EC2 instances, Lambda functions, ECS tasks
+- **Google Cloud**: Compute Engine, Cloud Functions, Cloud Run
+- **Azure**: Virtual Machines, Functions, Container Instances
+
+## Error Handling
+
+```python
+from s2iam import get_jwt_database, CloudProviderNotFound
+
+try:
+    jwt = await get_jwt_database("workspace-id")
+except CloudProviderNotFound:
+    print("Not running in a supported cloud environment")
+```
+
+## Configuration
+
+### Workspace Group ID
+
+The `workspace_group_id` parameter is optional for `get_jwt_database()`. When provided, it scopes the JWT to a specific workspace group. When omitted (or `None`), the JWT may have broader access depending on your SingleStore configuration.
+
+### Environment Variables
+
+- `S2IAM_DEBUGGING`: Set to "true" to enable debug logging
+- `S2IAM_SERVER_URL`: Custom authentication server URL (default: https://auth.singlestore.com)
+
+### Provider-Specific Configuration
+
+#### AWS
+- Uses standard AWS SDK configuration (AWS_REGION, AWS_PROFILE, etc.)
+- Supports IAM roles, EC2 instance profiles, and Lambda execution roles
+
+#### GCP
+- Uses Application Default Credentials (ADC)
+- Supports service account impersonation via `GCE_METADATA_HOST`
+
+#### Azure
+- Uses Azure SDK configuration
+- Supports managed identities and service principals
+
+## API Reference
+
+### Core Functions
+
+#### `detect_provider(timeout=5.0, logger=None, clients=None)`
+
+Automatically detect which cloud provider the application is running on.
+
+**Parameters:**
+- `timeout` (float): Detection timeout in seconds
+- `logger` (Logger): Custom logger instance
+- `clients` (List[CloudProviderClient]): Custom list of provider clients
+
+**Returns:** `CloudProviderClient`
+
+#### `get_jwt(jwt_type, workspace_group_id=None, server_url=None, **kwargs)`
+
+Get a JWT from SingleStore's authentication service.
+
+**Parameters:**
+- `jwt_type` (JWTType): Type of JWT to request
+- `workspace_group_id` (str): Workspace group ID
+- `server_url` (str): Authentication server URL
+- `**kwargs`: Additional provider-specific parameters
+
+**Returns:** `str` (JWT)
+
+### Cloud Provider Clients
+
+All provider clients implement the `CloudProviderClient` interface:
+
+#### Methods
+
+- `detect()`: Test if running on this cloud provider
+- `get_type()`: Get the provider type
+- `assume_role(role_identifier)`: Assume a different role/identity
+- `get_identity_headers(additional_params=None)`: Get authentication headers
+
+### Models
+
+#### `CloudIdentity`
+
+Represents verified identity information:
+
+```python
+@dataclass
+class CloudIdentity:
+    provider: CloudProviderType
+    identifier: str
+    account_id: str
+    region: str
+    resource_type: str
+    additional_claims: Dict[str, str]
+```
+
+#### `CloudProviderType`
+
+Enum of supported cloud providers:
+- `AWS`
+- `GCP`
+- `AZURE`
+
+#### `JWTType`
+
+Enum of JWT types:
+- `DATABASE_ACCESS`
+- `API_GATEWAY_ACCESS`
+
+## Error Handling
+
+The library defines several specific exceptions:
+
+- `CloudProviderNotFound`: No cloud provider could be detected
+- `ProviderNotDetected`: Provider not detected, call `detect()` first
+- `ProviderIdentityUnavailable`: Provider detected but no identity available
+- `AssumeRoleNotSupported`: Assume role not supported by provider
+
+## Development
+
+### Testing
+
+Tests use the Go test server (`s2iam_test_server`) started with the new `--info-file` flag for deterministic startup (no stdout JSON parsing). Async tests require `pytest-asyncio` which is part of the `dev` extras.
+
+```bash
+# Install with dev dependencies
+pip install -e .[dev]
+
+# Run full test suite (cloud‑dependent tests skip outside cloud VMs)
+pytest
+
+# Coverage
+pytest --cov=s2iam --cov-report=html
+
+# Example: Just integration tests
+pytest -k integration
+```
+
+Manual server run example (atomic startup):
+
+```bash
+go build -o s2iam_test_server ../go/cmd/s2iam_test_server
+tmpfile=$(mktemp)
+./s2iam_test_server --port=0 --info-file "$tmpfile" --shutdown-on-stdin-close &
+while [ ! -s "$tmpfile" ]; do sleep 0.05; done
+jq . "$tmpfile"
+```
+
+### Code Quality
+
+```bash
+# Format
+black src tests
+isort src tests
+
+# Static checks
+flake8 src tests
+mypy src
+```
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for your changes
+5. Run the test suite
+6. Submit a pull request
+
+## Support
+
+For issues and questions, please use the [GitHub Issues](https://github.com/singlestore-labs/singlestore-auth-iam/issues) page.

singlestore_auth_iam-0.4.0/README.md

@@ -0,0 +1,232 @@
+# SingleStore Auth IAM - Python Client Library
+
+A Python client library for getting JWTs from SingleStore's IAM service when running in cloud environments (AWS, GCP, Azure).
+
+## Installation
+
+```bash
+pip install singlestore-auth-iam
+```
+
+## Quick Start
+
+```python
+import asyncio
+from s2iam import get_jwt_database
+
+async def main():
+        # Get a JWT for database access
+    jwt = await get_jwt_database("your-workspace-group-id")
+    print(f"JWT: {jwt}")
+
+    # Or without workspace group ID
+    jwt = await get_jwt_database()
+    print(f"JWT: {jwt}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+For API gateway access:
+
+```python
+import asyncio
+from s2iam import get_jwt_api
+
+async def main():
+    # Get a JWT for API gateway access
+    jwt = await get_jwt_api()
+    print(f"JWT: {jwt}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+That's it! The library automatically detects your cloud environment and gets the appropriate JWT.
+
+## Configuration
+
+### Environment Variables
+
+- `S2IAM_SERVER_URL`: Custom authentication server URL (default: https://auth.singlestore.com)
+- `S2IAM_DEBUGGING`: Set to "true" to enable debug logging
+
+## Supported Environments
+
+The library automatically detects and works in:
+
+- **AWS**: EC2 instances, Lambda functions, ECS tasks
+- **Google Cloud**: Compute Engine, Cloud Functions, Cloud Run
+- **Azure**: Virtual Machines, Functions, Container Instances
+
+## Error Handling
+
+```python
+from s2iam import get_jwt_database, CloudProviderNotFound
+
+try:
+    jwt = await get_jwt_database("workspace-id")
+except CloudProviderNotFound:
+    print("Not running in a supported cloud environment")
+```
+
+## Configuration
+
+### Workspace Group ID
+
+The `workspace_group_id` parameter is optional for `get_jwt_database()`. When provided, it scopes the JWT to a specific workspace group. When omitted (or `None`), the JWT may have broader access depending on your SingleStore configuration.
+
+### Environment Variables
+
+- `S2IAM_DEBUGGING`: Set to "true" to enable debug logging
+- `S2IAM_SERVER_URL`: Custom authentication server URL (default: https://auth.singlestore.com)
+
+### Provider-Specific Configuration
+
+#### AWS
+- Uses standard AWS SDK configuration (AWS_REGION, AWS_PROFILE, etc.)
+- Supports IAM roles, EC2 instance profiles, and Lambda execution roles
+
+#### GCP
+- Uses Application Default Credentials (ADC)
+- Supports service account impersonation via `GCE_METADATA_HOST`
+
+#### Azure
+- Uses Azure SDK configuration
+- Supports managed identities and service principals
+
+## API Reference
+
+### Core Functions
+
+#### `detect_provider(timeout=5.0, logger=None, clients=None)`
+
+Automatically detect which cloud provider the application is running on.
+
+**Parameters:**
+- `timeout` (float): Detection timeout in seconds
+- `logger` (Logger): Custom logger instance
+- `clients` (List[CloudProviderClient]): Custom list of provider clients
+
+**Returns:** `CloudProviderClient`
+
+#### `get_jwt(jwt_type, workspace_group_id=None, server_url=None, **kwargs)`
+
+Get a JWT from SingleStore's authentication service.
+
+**Parameters:**
+- `jwt_type` (JWTType): Type of JWT to request
+- `workspace_group_id` (str): Workspace group ID
+- `server_url` (str): Authentication server URL
+- `**kwargs`: Additional provider-specific parameters
+
+**Returns:** `str` (JWT)
+
+### Cloud Provider Clients
+
+All provider clients implement the `CloudProviderClient` interface:
+
+#### Methods
+
+- `detect()`: Test if running on this cloud provider
+- `get_type()`: Get the provider type
+- `assume_role(role_identifier)`: Assume a different role/identity
+- `get_identity_headers(additional_params=None)`: Get authentication headers
+
+### Models
+
+#### `CloudIdentity`
+
+Represents verified identity information:
+
+```python
+@dataclass
+class CloudIdentity:
+    provider: CloudProviderType
+    identifier: str
+    account_id: str
+    region: str
+    resource_type: str
+    additional_claims: Dict[str, str]
+```
+
+#### `CloudProviderType`
+
+Enum of supported cloud providers:
+- `AWS`
+- `GCP`
+- `AZURE`
+
+#### `JWTType`
+
+Enum of JWT types:
+- `DATABASE_ACCESS`
+- `API_GATEWAY_ACCESS`
+
+## Error Handling
+
+The library defines several specific exceptions:
+
+- `CloudProviderNotFound`: No cloud provider could be detected
+- `ProviderNotDetected`: Provider not detected, call `detect()` first
+- `ProviderIdentityUnavailable`: Provider detected but no identity available
+- `AssumeRoleNotSupported`: Assume role not supported by provider
+
+## Development
+
+### Testing
+
+Tests use the Go test server (`s2iam_test_server`) started with the new `--info-file` flag for deterministic startup (no stdout JSON parsing). Async tests require `pytest-asyncio` which is part of the `dev` extras.
+
+```bash
+# Install with dev dependencies
+pip install -e .[dev]
+
+# Run full test suite (cloud‑dependent tests skip outside cloud VMs)
+pytest
+
+# Coverage
+pytest --cov=s2iam --cov-report=html
+
+# Example: Just integration tests
+pytest -k integration
+```
+
+Manual server run example (atomic startup):
+
+```bash
+go build -o s2iam_test_server ../go/cmd/s2iam_test_server
+tmpfile=$(mktemp)
+./s2iam_test_server --port=0 --info-file "$tmpfile" --shutdown-on-stdin-close &
+while [ ! -s "$tmpfile" ]; do sleep 0.05; done
+jq . "$tmpfile"
+```
+
+### Code Quality
+
+```bash
+# Format
+black src tests
+isort src tests
+
+# Static checks
+flake8 src tests
+mypy src
+```
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for your changes
+5. Run the test suite
+6. Submit a pull request
+
+## Support
+
+For issues and questions, please use the [GitHub Issues](https://github.com/singlestore-labs/singlestore-auth-iam/issues) page.