Metadata-Version: 2.4
Name: authmint
Version: 0.0.1
Summary: A modern Python library for issuing and verifying limited-time, scoped, and replay-protected tokens.
Project-URL: Homepage, https://github.com/shaileshpandit141/authmint
Project-URL: Documentation, https://shaileshpandit141.github.io/authmint
Project-URL: Source, https://github.com/shaileshpandit141/authmint
Project-URL: Issues, https://github.com/shaileshpandit141/authmint/issues
Project-URL: License, https://github.com/shaileshpandit141/authmint/blob/main/LICENSE
Author-email: shaileshpandit141 <shaileshpandit141@gmail.com>
License: # MIT License
        
        Copyright (c) 2025 Shailesh Pandit
        
        Permission is hereby granted, free of charge, to any person
        obtaining a copy of this software and associated documentation
        files (the "Software"), to deal in the Software without
        restriction, including without limitation the rights to use,
        copy, modify, merge, publish, distribute, sublicense, and/or
        sell copies of the Software, and to permit persons to whom
        the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall
        be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
        OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
        NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
        HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
        WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
        OTHER DEALINGS IN THE SOFTWARE.
License-File: LICENSE
Keywords: Ed25519,EdDSA,Redis,api-security,auth,authentication,authorization,cryptography,email-verification,ephemeral-tokens,jwt,key-rotation,magic-link,password-reset,replay-protection,scoped-tokens,secure-tokens,session,time-limited-tokens,token-auth,tokens
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# 🪙 Authmint

**Authmint** is a modern Python library for issuing and verifying **limited-time, scoped, and replay-protected tokens**.
Built for 2025 and beyond, it provides a **production-grade token system** with features like **key rotation, purpose scoping, Redis-backed replay prevention, and secure Ed25519 signatures**.

## ✨ Features

* 🔑 **Key rotation** with `kid` headers for zero-downtime upgrades.
* ⏳ **Limited-time tokens** (short-lived, scoped, expiring).
* 🛡 **Replay protection** using Redis-backed JTI tracking.
* 🎯 **Strict purpose scoping** (e.g., `email-verify`, `password-reset`).
* 🖋 **EdDSA (Ed25519)** signatures for modern cryptographic security.
* 🏗 Production-ready: structured errors, leeway for clock skew, revocation support.
* ⚡ Works with Django, FastAPI, Flask, or standalone services.

### 📦 Installation

```bash
pip install authmint
```

### 🚀 Quick Start

```python
from datetime import timedelta
from authmint import TokenService, TokenConfig, load_key_manager_from_env

# Bootstrap from env (TOKEN_CURRENT_KID, TOKEN_KEYS_* must be set)
km = load_key_manager_from_env()
svc = TokenService(km)

cfg = TokenConfig(
    issuer="myapp.io",
    audience="myapp.web",
    purpose="email-verify",
    ttl=timedelta(minutes=15),
)

# Issue a token
token = svc.issue(
    sub="user:42",
    config=cfg,
    extra_claims={"email": "alice@example.com"},
)

# Verify a token
claims = svc.verify(token, expected=cfg)
print(claims)
```

### 🔐 Key Management

Set keys as environment variables:

```bash
export TOKEN_CURRENT_KID="2025-08-rot-1"
export TOKEN_KEYS_2025-08-rot-1="$(cat ed25519-private.pem)"
```

Rotate keys safely by adding new ones and switching `TOKEN_CURRENT_KID`.

### 📖 Use Cases

* ✅ Email verification links
* ✅ Password reset flows
* ✅ Magic login links
* ✅ Scoped API access with TTL
* ✅ One-time-use session tokens

### 🛠 Roadmap

* [ ] PASETO v4 support
* [ ] Optional JWE (encrypted token)
* [ ] First-class FastAPI / Django integration helpers
