Skip to content

🧠 Overview

jwtlib is a small, focused authentication library. It keeps transport concerns out of auth logic so the same code backs an API service and a CLI or test harness.

🏗️ Architecture

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
┌─────────────────────────────────────────────────────────────┐
│                        Your application                      │
│   (FastAPI / Flask / CLI / tests)                            │
└───────────────────────────┬─────────────────────────────────┘
                            │ coroutine API
┌───────────────────────────▼─────────────────────────────────┐
│  jwtlib.app                                                 │
│  register_user · login_user · get_logged_in_user            │
│  logout_user · introspect_token                             │
├───────────────────────────┬─────────────────────────────────┤
│  jwtlib.introspection     │  jwtlib.security (token ops)    │
│  authenticate_request     │                                 │
├───────────────────────────▼─────────────────────────────────┤
│  jwtlib.models                                            │
│  RegisterRequest · LoginRequest · LoginResponse            │
│  PublicUser · IntrospectRequest · IntrospectResponse       │
│  TokenPayload · User                                      │
├───────────────────────────┬─────────────────────────────────┤
│  jwtlib.repository                                       │
│  UserRepository (MongoDB-backed default)                  │
│                     ▲                                      │
│   inject your own repository for other backends            │
└───────────────────────────┴─────────────────────────────────┘

🧩 Public API layers

Authentication operations (jwtlib.app)

Function Purpose
register_user(user, repo=None) Create a user from RegisterRequest
login_user(user, repo=None) Verify credentials, issue an access token
get_logged_in_user(token, repo=None) Resolve the token's subject to a user
logout_user() Model the client-side logout signal
introspect_token(token, repo=None) Verify a token and produce an introspection verdict

Every operation is an async function; the default UserRepository is a MongoDB-backed implementation of the repository contract.

Introspection helpers (jwtlib.introspection)

  • introspect_token(token) — decode and validate the JWT.
  • authenticate_request(token) — pure authorization decision for request guards (no framework context required).

Domain models (jwtlib.models)

  • Requests: RegisterRequest (username, email, password), LoginRequest (username, password), IntrospectRequest (token).
  • Responses: LoginResponse (access_token + user), LogoutResponse (message), IntrospectResponse (active + user or null).
  • Payloads: TokenPayload (subject + expiry).
  • Persistence: User (identity, active state) with optional email.
  • Mixins: IdentityMixin, PasswordMixin, ActiveStateMixin for custom repository models.

Errors (jwtlib.exceptions)

AuthError is the base for InvalidToken, InvalidAuthorizationHeader, UserNotFound, AuthServiceUnavailable, and NotAuthenticated.

🔒 Security posture

  • Passwords are hashed during registration and compared only through the repository's authenticate_user; hashes never leave the persistence layer.
  • Tokens are validated at introspection time (signature, expiry, subject).
  • The library returns typed verdict objects instead of raw framework errors, so callers can map failures to their own HTTP semantics.