Metadata-Version: 2.4
Name: uvb-fastapi
Version: 0.2.0
Summary: FastAPI extension for Universal Verification Broker (UVB)
Project-URL: Homepage, https://gitlab.com/sparkz-community/security/uvb
Project-URL: Documentation, https://gitlab.com/sparkz-community/security/uvb/-/blob/main/docs/README.md
Project-URL: Repository, https://gitlab.com/sparkz-community/security/uvb
Project-URL: Issues, https://gitlab.com/sparkz-community/security/uvb/-/issues
Author: UVB Team
License: MIT
Keywords: authentication,extension,fastapi,mfa,security,uvb
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: uvb-client>=0.1.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: httpx>=0.24.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: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# UVB FastAPI Extension

Official FastAPI extension for Universal Verification Broker (UVB).

## Installation

```bash
pip install uvb-fastapi
```

## Quick Start

```python
from fastapi import FastAPI, Depends
from uvb import UVBClient
from uvb_fastapi import UVBAuthMiddleware, require_auth, create_uvb_router

app = FastAPI()

# Initialize UVB client
uvb_client = UVBClient(
    tenant_id="your-tenant-id",
    uvb_url="http://localhost:8080"
)
app.state.uvb_client = uvb_client

# Add authentication middleware
app.add_middleware(
    UVBAuthMiddleware,
    tenant_id="your-tenant-id",
    uvb_url="http://localhost:8080",
    exclude_paths=["/health", "/docs", "/auth"],
)

# Include UVB auth routes
auth_router = create_uvb_router(uvb_client)
app.include_router(auth_router)

# Protected route
@app.get("/protected")
async def protected_route(session = Depends(require_auth)):
    return {
        "user_id": session.user_id,
        "factors_verified": session.factors_verified
    }
```

## Features

### Middleware

The `UVBAuthMiddleware` automatically validates sessions on all requests:

```python
app.add_middleware(
    UVBAuthMiddleware,
    tenant_id="your-tenant-id",
    uvb_url="http://localhost:8080",
    exclude_paths=["/health", "/docs"],  # Skip auth for these paths
    token_header="Authorization",         # Header to read token from
    token_prefix="Bearer",                # Token prefix
)
```

### Dependencies

Use FastAPI dependencies for route-level authentication:

```python
from fastapi import Depends
from uvb_fastapi import require_auth, get_current_user

@app.get("/me")
async def get_me(user_id: str = Depends(get_current_user)):
    return {"user_id": user_id}

@app.get("/session")
async def get_session(session = Depends(require_auth)):
    return session.model_dump()
```

### Pre-built Router

The `create_uvb_router` function provides ready-to-use authentication endpoints:

```python
auth_router = create_uvb_router(uvb_client, prefix="/auth")
app.include_router(auth_router)
```

This creates:

- `POST /auth/verify` - Verify user with a factor
- `POST /auth/enroll` - Enroll a new factor
- `GET /auth/factors/{user_id}` - List user's factors
- `POST /auth/session/validate` - Validate a session
- `DELETE /auth/session/{session_id}` - Revoke a session

## Documentation

For more information, see the [UVB documentation](https://docs.uvb.io).

## License

MIT
