Metadata-Version: 2.4
Name: cl4im
Version: 0.2.2
Summary: Python client for the Identora authorizer (OIDC + RBAC)
Project-URL: Homepage, https://github.com/xlucvvs/cl4im-python
Project-URL: Repository, https://github.com/xlucvvs/cl4im-python
Project-URL: Bug Tracker, https://github.com/xlucvvs/cl4im-python/issues
Author-email: Lucas Ribeiro <lucasribeiro.sec@gmail.com>
License: CC0 1.0 Universal
        
        Statement of Purpose
        
        The laws of most jurisdictions throughout the world automatically confer
        exclusive Copyright and Related Rights (defined below) upon the creator and
        subsequent owner(s) of an original work of authorship and/or a database
        (each, a "Work").
        
        Certain owners wish to permanently relinquish those rights to a Work for the
        purpose of contributing to a commons of creative, cultural and scientific works
        that the public can reliably and without fear of infringement build upon,
        modify, incorporate in other works, cite, and distribute, as freely as
        possible, without legal restriction.
        
        To the greatest extent permitted by, but not in contravention of, applicable
        law, Affirmer hereby overtly, fully, permanently, irrevocably and
        unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
        and Related Rights and associated claims and causes of action, in the Work.
        
        Should any part of this dedication be judged legally invalid or ineffective
        under applicable law, the dedication shall be preserved to the maximum extent
        permitted by law.
        
        For more information, please see:
        https://creativecommons.org/publicdomain/zero/1.0/
License-File: LICENSE
Keywords: auth,authorization,identora,jwt,oidc,rbac
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: FastAPI
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: python-jose[cryptography]>=3.3
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: django>=4.0; extra == 'dev'
Requires-Dist: flask>=2.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.0; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.111; extra == 'fastapi'
Requires-Dist: starlette>=0.37; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.0; extra == 'flask'
Description-Content-Type: text/markdown

# cl4im

Python client for the **Identora** authorizer — handles app authentication,
JWT validation, permission checking and automatic operation sync.

## Installation

```bash
pip install cl4im
# With FastAPI support
pip install "cl4im[fastapi]"
```

## Quick start with FastAPI

```python
from fastapi import FastAPI, Request
from cl4im.adapters.fastapi import Cl4im, operation

app = FastAPI()

cl4im = Cl4im(
    app,
    authorizer_url="http://localhost:4000/api",
    app_id="your-app-uuid",
    secret="your-app-secret",
)


@app.get("/public")
@operation(id="public.info", level="public")
async def public_info():
    """Anyone can call this — no token needed."""
    return {"message": "Hello, world!"}


@app.get("/items")
@operation(id="items.list", level="private")
async def list_items(request: Request):
    """Requires any authenticated user (token with non-empty groups)."""
    user = request.state.user  # TokenClaims
    return {"user": user.sub, "items": []}


@app.delete("/items/{item_id}")
@operation(id="items.delete", level="protected")
async def delete_item(item_id: str, request: Request):
    """Requires a user whose group has explicit permission for items.delete."""
    return {"deleted": item_id}
```

## Standalone client

```python
import asyncio
from cl4im import Cl4imClient, OperationDescriptor

client = Cl4imClient(
    authorizer_url="http://localhost:4000/api",
    app_id="your-app-uuid",
    secret="your-app-secret",
)

client.register_operation(
    OperationDescriptor(identifier="items.list", method="read", level="private")
)

async def main():
    await client.startup()

    # Validate a token from an incoming request
    claims = await client.validate_token("<bearer-token>")

    # Check whether the token has permission
    allowed = client.check_permission(claims, "items.list", "read")
    print(f"Allowed: {allowed}")

asyncio.run(main())
```

## Operation levels

| Level       | Who can access |
|-------------|----------------|
| `public`    | Everyone — no token required |
| `private`   | Any authenticated user (token with at least one group) |
| `protected` | Only users whose groups intersect the operation's `allowed_groups` |

## Method auto-detection

The `@operation` decorator infers the method from the function name:

| Function name prefix/keyword | Detected method |
|------------------------------|-----------------|
| `get_`, `list_`, `fetch_`, `read_` | `read` |
| `delete_`, `remove_`, `destroy_` | `delete` |
| contains `stream`, `subscribe`, `watch` | `stream` |
| anything else | `write` |

## Configuration

| Parameter | Description |
|-----------|-------------|
| `authorizer_url` | Base URL of Identora, including the API prefix (e.g. `http://host/api`) |
| `app_id` | UUID of the app registered in `auth.apps` |
| `secret` | Plain-text app secret (never committed — use env vars) |

```python
import os
from cl4im.adapters.fastapi import Cl4im

cl4im = Cl4im(
    app,
    authorizer_url=os.environ["AUTHORIZER_URL"],
    app_id=os.environ["APP_ID"],
    secret=os.environ["APP_SECRET"],
)
```
