Metadata-Version: 2.4
Name: hanzoai-iam
Version: 1.1.2
Summary: Hanzo IAM SDK - Identity and Access Management for Python
Project-URL: Homepage, https://hanzo.id
Project-URL: Documentation, https://docs.hanzo.ai/iam
Project-URL: Repository, https://github.com/hanzoai/python-sdk
Author-email: Hanzo AI <dev@hanzo.ai>
License: MIT
Keywords: access-management,authentication,hanzo,iam,identity,oauth2,oidc
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyjwt>=2.8.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Provides-Extra: kms
Requires-Dist: hanzo-kms>=1.0.0; extra == 'kms'
Description-Content-Type: text/markdown

# hanzoai-iam

Identity and Access Management SDK for the Hanzo ecosystem. Built on Casdoor with organization-aware multi-tenancy.

The PyPI distribution is `hanzoai-iam`; the import path is `hanzo_iam`.

## Installation

```bash
pip install hanzoai-iam
```

With FastAPI integration:

```bash
pip install hanzoai-iam[fastapi]
```

With KMS support for certificate management:

```bash
pip install hanzoai-iam[kms]
```

## Quick Start

```python
from hanzo_iam import IAMClient, IAMConfig

config = IAMConfig(
    endpoint="https://iam.hanzo.ai",
    client_id="your-client-id",
    client_secret="your-client-secret",
    org_name="HANZO",
)

client = IAMClient(config)

# Get authorization URL for user login
auth_url = client.get_auth_url(redirect_uri="https://yourapp.com/callback")

# Exchange code for tokens
tokens = client.get_token(code="auth-code-from-callback")

# Get user info
user = client.get_user_info(access_token=tokens.access_token)
```

## Organizations

| Organization | Endpoint | Description |
|-------------|----------|-------------|
| HANZO | https://iam.hanzo.ai | Hanzo AI platform |
| ZOO | https://iam.zoo.dev | Zoo Labs Foundation |
| LUX | https://iam.lux.network | Lux blockchain network |
| PARS | https://iam.pars.dev | Pars development platform |

## Environment Variables

One canonical prefix — `IAM_*`. No upstream-brand aliases, no per-org variants.

```bash
# Required
IAM_ENDPOINT=https://hanzo.id
IAM_CLIENT_ID=your-client-id
IAM_CLIENT_SECRET=your-client-secret

# Optional (defaults shown)
IAM_ORG=hanzo
IAM_APP=app
IAM_CERT=path/to/cert.pem    # PEM file or inline PEM content
```

## FastAPI Integration

```python
from fastapi import FastAPI, Depends
from hanzo_iam.fastapi import IAMAuth, get_current_user
from hanzo_iam import IAMConfig, User

app = FastAPI()

config = IAMConfig.from_env()
auth = IAMAuth(config)

@app.get("/protected")
async def protected_route(user: User = Depends(auth.require_user)):
    return {"user": user.name, "org": user.owner}

@app.get("/optional")
async def optional_auth(user: User | None = Depends(auth.optional_user)):
    if user:
        return {"message": f"Hello, {user.name}"}
    return {"message": "Hello, anonymous"}
```

## Client Credentials Flow

For service-to-service authentication:

```python
from hanzo_iam import IAMClient, IAMConfig

config = IAMConfig(
    endpoint="https://iam.hanzo.ai",
    client_id="service-client-id",
    client_secret="service-client-secret",
    org_name="HANZO",
)

client = IAMClient(config)

# Get service token
tokens = client.get_client_credentials_token()

# Use token for API calls
headers = {"Authorization": f"Bearer {tokens.access_token}"}
```

## Async Client

```python
import asyncio
from hanzo_iam import AsyncIAMClient, IAMConfig

async def main():
    config = IAMConfig.from_env()
    client = AsyncIAMClient(config)

    # All methods are async
    tokens = await client.get_client_credentials_token()
    user = await client.get_user_info(tokens.access_token)

    print(f"Authenticated as: {user.name}")

asyncio.run(main())
```

## API Reference

| Method | Description |
|--------|-------------|
| `get_auth_url(redirect_uri, state, scope)` | Generate OAuth authorization URL |
| `get_token(code)` | Exchange authorization code for tokens |
| `refresh_token(refresh_token)` | Refresh access token |
| `get_client_credentials_token()` | Get token via client credentials flow |
| `get_user_info(access_token)` | Get user info from access token |
| `parse_jwt(token)` | Parse and validate JWT claims |
| `get_user(user_id)` | Get user by ID |
| `get_users()` | List all users in organization |
| `create_user(user)` | Create new user |
| `update_user(user)` | Update existing user |
| `delete_user(user_id)` | Delete user |
| `get_organizations()` | List organizations |
| `get_organization(name)` | Get organization by name |

## License

Apache-2.0
