Metadata-Version: 2.4
Name: passmanai
Version: 0.1.0
Summary: Official Python SDK for PassmanAI OIDC Authentication
Author-email: PassmanAI <support@passmanai.com>
Project-URL: Homepage, https://passmanai.com
Project-URL: Bug Tracker, https://github.com/AshishKumarJena/passmanai-python-sdk/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Authlib>=1.3.0
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# PassmanAI Python SDK

> Official Python SDK for integrating **"Sign in with Passman"** into any Python web framework (FastAPI, Django, Flask, etc.).

PassmanAI is a decentralized, post-quantum password manager with zero-knowledge architecture. This SDK provides a robust, PKCE-secured OpenID Connect (OIDC) client that makes it trivial to authenticate users via Passman.

## Quick Start

### 1. Install

```bash
pip install passmanai
```

### 2. Configure Environment Variables

Set your Passman API credentials in your environment:

```env
PASSMAN_CLIENT_ID=your_client_id
PASSMAN_CLIENT_SECRET=your_client_secret
PASSMAN_REDIRECT_URI=http://localhost:8000/auth/callback
PASSMAN_ISSUER_URL=http://localhost:4010
```

> Get your client credentials by registering an OIDC client in your [PassmanAI dashboard](https://passmanai.com).

### 3. Basic Usage (Framework Agnostic)

The SDK provides a `PassmanClient` that handles OIDC discovery, PKCE generation, and token exchange.

```python
from passmanai import PassmanClient

# Initialize the client (automatically loads from env vars)
passman = PassmanClient()

# 1. Generate the authorization URL and PKCE state
auth_url, state, code_verifier = passman.get_authorization_url()

# Save `state` and `code_verifier` in your session, then redirect the user to `auth_url`.
# ... user logs in on Passman and gets redirected to your callback ...

# 2. Exchange the authorization code for a token and user profile
# In your callback route, reconstruct the full URL requested:
callback_url = "http://localhost:8000/auth/callback?code=...&state=..."

profile, tokens = passman.fetch_user_profile(
    authorization_response_url=callback_url,
    state=saved_state_from_session,
    code_verifier=saved_code_verifier_from_session
)

print(f"Logged in as: {profile['preferred_username']} (ID: {profile['sub']})")
```

## Advanced Configuration

You can explicitly pass credentials if you prefer not to use environment variables:

```python
passman = PassmanClient(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="https://myapp.com/auth/callback",
    issuer_url="https://passmanai.com" # Defaults to https://passmanai.com if not set
)
```

## Security

- **PKCE enforced** — Prevents authorization code interception attacks.
- **State parameter** — Protects against CSRF attacks.
- Built on top of **Authlib**, the industry standard for Python OAuth/OIDC.
