cacl 0.2.1

Stop fighting auth in FastAPI: JWT access/refresh, DB-backed blacklist & rotation, cookie or Bearer modes.

CACL — Clear Authentication Control Library

Stop fighting authentication in FastAPI.
Controlled JWT auth with database-backed tokens, blacklist, and rotation.

---

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

---

DB schema and integration contract

No FK to your users table

CACL does not define a foreign key from jwt_tokens.user_id to your users.id column.

This is intentional to avoid forcing your application models to use CACL's Base. You keep full control of your own schema and ORM hierarchy.

Token verification still loads the current user and rejects tokens if the user does not exist or is inactive — so the security guarantee is fully preserved at the application layer.

If your app hard-deletes users, delete their JWT tokens in your application layer or run a cleanup job — there is no DB-level cascade without the FK.

Alembic setup with separate Base classes

# alembic/env.py

from your_app.core.base import Base as AppBase   # your application's Base
from cacl.models.base import Base as CACLBase    # CACL's Base

# Import models so metadata is populated before autogenerate runs
from your_app.models.users import User           # noqa
from cacl.models.jwt_token import JWTToken       # noqa

# Pass both metadata objects — Alembic autogenerate sees all tables
target_metadata = [AppBase.metadata, CACLBase.metadata]

---

Installation

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: packages/cacl/cacl/
• Demo FastAPI application: examples/demo_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.