Metadata-Version: 2.4
Name: common-auth-sdk
Version: 0.1.0
Summary: Common Auth SDK for Python
Author-email: Common Team <team@example.com>
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: cachetools>=5.3
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyjwt[crypto]>=2.8
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=3.0; extra == 'flask'
Description-Content-Type: text/markdown

# Common Auth SDK Python

Python implementation of the Common Auth SDK.

This SDK provides authentication and authorization middleware for Flask and FastAPI applications, compatible with the Common Auth system.

## Installation

```bash
pip install common-auth-sdk
# For Flask support
pip install "common-auth-sdk[flask]"
# For FastAPI support
pip install "common-auth-sdk[fastapi]"
```

## Usage

### Configuration

Create a `CommonAuthConfig` object:

```python
from common_auth_sdk.schema import CommonAuthConfig

auth_config = CommonAuthConfig(
    public_jwks_path="https://auth.example.com/.well-known/jwks.json",
    jwt_issuer="common-auth",
    jwt_pub_cache_ttl=1800, # 30 minutes
    app_name="my-service",
    use_app_scope_prefix=True
)
```

### Flask Integration

```python
from flask import Flask
from common_auth_sdk.middleware_flask import CommonAuthFlask

app = Flask(__name__)
auth = CommonAuthFlask(auth_config)

@app.route("/api/private")
@auth.auth({"required_scopes": ["read"]})
def private_route():
    return {"message": "Hello Authorized User"}
```

Access auth context via `g.auth`:
```python
from flask import g

@app.route("/me")
@auth.auth()
def me():
    return {"user_id": g.auth['payload'].sub}
```

### FastAPI Integration

```python
from fastapi import FastAPI, Depends
from common_auth_sdk.middleware_fastapi import CommonAuthFastAPI, CommonAuthContext

app = FastAPI()
auth = CommonAuthFastAPI(auth_config)

@app.get("/api/private")
async def private_route(context: CommonAuthContext = Depends(auth.auth({"required_scopes": ["read"]}))):
    return {"message": "Hello Authorized User", "user_id": context.payload.sub}
```

## Features

- **JWT Verification**: Validates tokens against JWKs (local or remote).
- **Scope Validation**: Supports wildcards (e.g. `app.*`), resource paths (e.g. `read::/api/v1/*`), and app prefixes.
- **Policy Resolution**: Fetches policies from remote endpoints or config.
- **Async Support**: Native async support for FastAPI using `httpx`.

### Policy Metadata

Policy objects preserve inherited role metadata returned by the policy service:

```python
from common_auth_sdk.schema import CommonAuthPolicy

policy = CommonAuthPolicy(
    role="manager",
    inherited_role=["member"],
    scopes=["project.write"]
)
```
