Metadata-Version: 2.4
Name: larzsession
Version: 0.1.0
Summary: Signed, timestamped cookie sessions + CSRF tokens (HMAC), no server-side store. Pure Python, zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzsession
Project-URL: Repository, https://github.com/larz-scripter/larzsession
Project-URL: Issues, https://github.com/larz-scripter/larzsession/issues
Keywords: session,cookie,sessions,csrf,hmac,signing,itsdangerous-alternative,security,web,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzsession

**Signed cookie sessions + CSRF tokens. Pure Python, zero dependencies.**

Store session data in a tamper-proof cookie the client can't forge — it's
serialized, timestamped, and **HMAC-signed**, so any change invalidates it and you
can expire it by age. No database, no session store: the signature is the
security. Also generates/validates CSRF tokens and formats hardened `Set-Cookie`
headers.

```python
from larzsession import Serializer

s = Serializer("my-secret-key")
token = s.dumps({"user_id": 42, "role": "admin"})   # -> cookie value
s.loads(token, max_age=3600)                        # {'user_id': 42, ...}, or raises
```

## Why

- **No server-side store.** The signed cookie *is* the session — stateless auth
  that scales horizontally with nothing shared.
- **Tamper-proof + expirable.** HMAC-SHA256 with a derived key; a timestamp lets
  you enforce `max_age`. Tampering raises `BadSignature`; old tokens raise
  `SignatureExpired`.
- **CSRF built in.** `CSRF(secret).generate()` / `.validate(token)` for signed,
  expiring CSRF tokens.
- **Hardened cookies.** `cookie()` emits `HttpOnly; Secure; SameSite=Lax` by
  default.
- **Zero dependencies.** Pure `hmac`/`hashlib` — no `itsdangerous`.

## Install

```bash
pip install larzsession
```

## Usage

```python
from larzsession import Serializer, CSRF, cookie

s = Serializer("secret")
tok = s.dumps({"uid": 1})
data = s.loads(tok, max_age=86400)

csrf = CSRF("secret")
t = csrf.generate(); csrf.validate(t)

set_cookie = cookie("session", tok, max_age=86400, samesite="Strict")
# 'session=...; Max-Age=86400; Path=/; Secure; HttpOnly; SameSite=Strict'
```

Lower-level `Signer` / `TimestampSigner` are exposed too. Built on the same HMAC
primitives as [larzcrypt](https://github.com/larz-scripter/larzcrypt).

## Tests

```bash
python -m unittest discover -s tests -v   # 13 tests
```

## The Larz stack

One of 30+ pure-Python, zero-dependency libraries at
[github.com/larz-scripter](https://github.com/larz-scripter).

## License

MIT © larz-scripter
