Metadata-Version: 2.4
Name: fastjwt-kit
Version: 0.1.0
Summary: A small, opinionated JWT toolkit: create, verify, expire, and handle errors without writing the same PyJWT boilerplate every project.
Project-URL: Homepage, https://github.com/yourusername/fastjwt-kit
Project-URL: Issues, https://github.com/yourusername/fastjwt-kit/issues
Author-email: Shreyas G <shreyasg2526@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: auth,authentication,fastapi,jwt,security,token
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: pyjwt>=2.8.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# fastjwt-kit

A small, opinionated wrapper around [PyJWT](https://pyjwt.readthedocs.io/) that
handles the boilerplate every project rewrites: token creation, expiry,
claim validation, and clean error handling — without you having to import
`jwt` exceptions directly.

## Install

```bash
pip install fastjwt-kit
```

## Quickstart

```python
from fastjwt_kit import create_access_token, verify_token, TokenExpiredError

token = create_access_token(subject="user-123", secret="change-me")

try:
    claims = verify_token(token, secret="change-me")
    print(claims["sub"])  # "user-123"
except TokenExpiredError:
    print("Token expired — ask the user to log in again")
```

That's it — no manual `exp` math, no catching raw `jwt.ExpiredSignatureError`.

## Access + refresh tokens

```python
from fastjwt_kit import create_access_token, create_refresh_token

access = create_access_token(subject="user-123", secret="change-me")          # 15 min default
refresh = create_refresh_token(subject="user-123", secret="change-me")        # 7 days default
```

## Custom expiry, issuer, audience, and extra claims

```python
import datetime as dt
from fastjwt_kit import create_token, verify_token

token = create_token(
    subject="user-123",
    secret="change-me",
    expires_in=dt.timedelta(hours=1),
    issuer="my-app",
    audience="my-app-clients",
    extra_claims={"role": "admin"},
)

claims = verify_token(token, secret="change-me", issuer="my-app", audience="my-app-clients")
```

## Error handling

All errors inherit from `TokenError`, so you can catch broadly or specifically:

```python
from fastjwt_kit import TokenError, TokenExpiredError, InvalidTokenError, InvalidClaimsError

try:
    claims = verify_token(token, secret="change-me")
except TokenExpiredError:
    ...  # token was valid but has expired
except InvalidClaimsError:
    ...  # issuer/audience didn't match
except InvalidTokenError:
    ...  # malformed or tampered token
except TokenError:
    ...  # catch-all
```

## API

| Function | Description |
|---|---|
| `create_token(subject, secret, *, expires_in, ...)` | Create a JWT with full control over claims. |
| `create_access_token(subject, secret, ...)` | Create a short-lived token (default 15 min), tagged `type: access`. |
| `create_refresh_token(subject, secret, ...)` | Create a long-lived token (default 7 days), tagged `type: refresh`. |
| `verify_token(token, secret, *, algorithm, issuer, audience)` | Decode and validate a token, raising `fastjwt_kit` exceptions. |

## Why not just use PyJWT directly?

You can! This package just wraps the parts everyone ends up rewriting:
expiry defaults, issuer/audience checks, and exception types that don't
leak the underlying library. If you only need raw encode/decode, PyJWT
alone is enough.

## Roadmap

- [ ] Password hashing module
- [ ] FastAPI signup/login router + `get_current_user` dependency
- [ ] Config/env validation helpers

Feedback and issues welcome — this is an early release and will evolve
based on real usage.

## License

MIT