Metadata-Version: 2.5
Name: dj-auth-engine
Version: 0.1.0
Summary: A production-ready Python authentication engine — OAuth 2.1, OIDC, JWT, Argon2, token rotation, and JWKS out of the box.
Project-URL: Homepage, https://github.com/dhanunjairam/DJ-Auth-CLI-private
Project-URL: Repository, https://github.com/dhanunjairam/DJ-Auth-CLI-private
Project-URL: Issues, https://github.com/dhanunjairam/DJ-Auth-CLI-private/issues
Author: DJ
License-Expression: MIT
License-File: LICENSE
Keywords: argon2,auth,authentication,fastapi,jwt,oauth,oidc,sqlalchemy,token
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: click>=8.4.2
Requires-Dist: dotenv>=0.9.9
Requires-Dist: psycopg2>=2.9.12
Requires-Dist: pwdlib[argon2]>=0.3.1
Requires-Dist: pydantic-settings>=2.15.0
Requires-Dist: pyjwt[crypto]>=2.13.0
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlalchemy>=2.0.52
Description-Content-Type: text/markdown

# 🔒 DJ-Auth

> A production-ready Python authentication engine — OAuth 2.1, OIDC, JWT, Argon2, token rotation, and JWKS out of the box.

[![PyPI version](https://img.shields.io/pypi/v/dj-auth.svg)](https://pypi.org/project/dj-auth/)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## ✨ Features

- **🔐 OAuth 2.1** — RFC 9068 compliant JWT access tokens
- **🪪 OIDC** — OpenID Connect compliant ID tokens
- **🔄 Token Rotation** — Automatic refresh token rotation with revocation
- **🔑 EdDSA + RS256** — Modern Ed25519 keys with RSA fallback
- **🛡️ Argon2** — Industry-leading password hashing via pwdlib
- **📋 JWKS** — Built-in JSON Web Key Set endpoint support
- **🗄️ SQLAlchemy** — PostgreSQL-backed user & token storage
- **⚙️ Pydantic** — Type-safe configuration from environment

---

## 📦 Installation

```bash
pip install dj-auth
```

---

## 🚀 Quick Start

### 1. Initialize

```python
import dj_auth

# Initialize with default settings (reads from .env)
dj_auth.initiate()

# Or pass settings explicitly
dj_auth.initiate(
    DB_HOST="localhost",
    DB_PORT="5432",
    DB_NAME="mydb",
    DB_USER="postgres",
    DB_PASSWORD="password",
)
```

### 2. Sign Up

```python
user = await dj_auth.signup({
    "email": "user@example.com",
    "password": "secure_password",
})
```

### 3. Log In

```python
tokens = await dj_auth.login("user@example.com", "secure_password")
# Returns: { access_token, id_token, refresh_token, token_type, expires_in }
```

### 4. Validate Token

```python
payload = dj_auth.validate_token(tokens["access_token"])
# Returns decoded JWT claims: { sub, iss, exp, iat, ... }
```

### 5. Refresh Tokens

```python
new_tokens = await dj_auth.refresh_tokens(tokens["refresh_token"])
# Rotates the refresh token and issues new access + id tokens
```

### 6. Log Out

```python
await dj_auth.logout(user_id)
# Revokes all active refresh tokens for the user
```

---

## ⚙️ Environment Variables

| Variable | Default | Description |
|---|---|---|
| `DB_HOST` | `localhost` | PostgreSQL host |
| `DB_PORT` | `5433` | PostgreSQL port |
| `DB_NAME` | `postgres` | Database name |
| `DB_USER` | `postgres` | Database user |
| `DB_PASSWORD` | `password` | Database password |
| `DATABASE_URL` | — | Full DB URL (overrides above) |
| `access_token_expire_minutes` | `15` | Access token TTL |
| `id_token_expire_minutes` | `15` | ID token TTL |
| `refresh_token_expire_days` | `30` | Refresh token TTL |

---

## 🖥️ CLI

After installation, run `dj-auth` in your terminal:

```bash
dj-auth          # Show banner + features
dj-auth guide    # Step-by-step quickstart
dj-auth api      # API reference table
dj-auth env      # Environment variable reference
dj-auth info     # All of the above
dj-auth --help   # Available commands
```

---

## 📋 API Reference

| Function | Description | Async |
|---|---|---|
| `dj_auth.initiate()` | Initialize auth engine with settings | ✗ |
| `dj_auth.signup(data)` | Register a new user | ✓ |
| `dj_auth.login(email, pw)` | Authenticate & issue tokens | ✓ |
| `dj_auth.validate_token(t)` | Decode & verify a JWT token | ✗ |
| `dj_auth.refresh_tokens(t)` | Rotate refresh token | ✓ |
| `dj_auth.logout(user_id)` | Revoke all refresh tokens | ✓ |
| `dj_auth.hash_password(pw)` | Hash a password (Argon2) | ✓ |
| `dj_auth.verify_password(pw, h)` | Verify password against hash | ✓ |

---

## 📄 License

MIT © DJ
