Metadata-Version: 2.4
Name: cacl
Version: 0.1.4
Summary: Stop fighting auth in FastAPI: JWT access/refresh, DB-backed blacklist & rotation, cookie or Bearer modes.
Author: Anton Serebriakov
License-Expression: MIT
Keywords: fastapi,authentication,jwt,security,access-token,refresh-token,cookie-auth,bearer-token,token-blacklist,auth,tokens,refresh-rotation,sqlalchemy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Framework :: FastAPI
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.100.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: python-jose>=3.3.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Requires-Dist: greenlet>=3.0.0; extra == "postgres"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Dynamic: license-file

<p align="center">
  <img
    src="https://raw.githubusercontent.com/CACL-project/CACL/main/docs/assets/logo2.jpeg"
    alt="CACL logo"
    width="360"
  />
</p>

<h1 align="center">CACL — Clear Authentication Control Library</h1>

<p align="center">
  <strong>Stop fighting authentication in FastAPI.</strong><br/>
  Controlled JWT auth with database-backed tokens, blacklist, and rotation.
</p>

---

## What is CACL?

**CACL is a production-grade authentication library for FastAPI.**

It provides **explicit, database-backed control** over JWT authentication:

- access & refresh tokens  
- forced token invalidation (blacklist)  
- refresh token rotation  
- cookie **or** Bearer header modes — switched by a single flag  

No hidden state.  
No opinionated framework behavior.  
No surprises in production.

You own the database and transactions — **CACL handles token mechanics.**

---

## Cookie or Bearer — without the headache

CACL supports both browser and API authentication flows:

- **Cookie-based auth** for web applications
- **Bearer tokens** via `Authorization` header for APIs and services

Switching between them requires **changing a single configuration flag**.

No duplicated logic.  
No conditional dependencies in routes.  
No separate auth implementations to maintain.

---

## Why CACL exists

Most JWT libraries treat tokens as **stateless forever**.

That approach breaks down the moment you need:
- real logout
- forced session invalidation
- compromised token handling
- refresh token reuse protection

CACL treats tokens as **controlled entities** stored in your database.

This allows you to:
- revoke tokens instantly
- track token lifecycle
- enforce refresh rotation
- audit authentication behavior

This is how authentication works in real production systems.

---

## Authentication philosophy

CACL follows a simple principle:

> **Authentication must be explicit, inspectable, and revocable.**

Stateless JWTs optimize for simplicity, not for control.  
CACL optimizes for **operational clarity**.

The library intentionally:
- does **not** create database engines
- does **not** manage transactions
- does **not** hide side effects

Your application owns the session lifecycle.  
CACL integrates into it — cleanly and predictably.

---

## Core principles

- **Library, not framework** — no imposed app structure
- **Database-backed** — tokens are real records
- **Explicit ownership** — you control commits and rollbacks
- **FastAPI-native** — async, dependencies, SQLAlchemy 2.x

---

## Installation

```bash
pip install cacl
```

---

## Minimal mental model

**Your application:**
- creates DB engine
- manages transactions
- verifies user credentials

**CACL:**
- creates JWT tokens
- verifies JWT tokens
- blacklists tokens
- enforces authentication rules

---

## Documentation & demo

- **Library documentation:** [cacl/](https://github.com/CACL-project/CACL/tree/main/cacl)
- **Demo FastAPI application:** [app/](https://github.com/CACL-project/CACL/tree/main/app)
- Design notes, testing, and verification docs are included in the repository

---

## When should you use CACL?

Use CACL if you need:

- real logout (not "just delete the cookie")
- forced token invalidation
- refresh token rotation without hacks
- clear and auditable auth boundaries

If you want "just slap JWT and forget about it" — this library is intentionally not for you.
