SoroushMoosapour · Aug 30, 2026 · Dec 29, 2025 · Jul 22, 2026 · Jul 22, 2026 · Jul 23, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,28 @@
+# Normalize line endings: treat everything as text and let Git handle EOL,
+# but pin source and config files to LF so formatting stays stable across OSes.
+* text=auto eol=lf
+
+# Source
+*.rs   text eol=lf
+*.py   text eol=lf
+*.pyi  text eol=lf
+
+# Config / data / docs
+*.toml text eol=lf
+*.json text eol=lf
+*.yml  text eol=lf
+*.yaml text eol=lf
+*.md   text eol=lf
+*.lock text eol=lf
+*.cfg  text eol=lf
+*.ini  text eol=lf
+*.sh   text eol=lf
+.gitattributes text eol=lf
+.gitignore     text eol=lf
+
+# Compiled extension artifacts (belt-and-suspenders; also gitignored)
+*.pdb binary
+*.pyd binary
+*.so  binary
+*.whl binary
+*.gz  binary
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -19,6 +19,40 @@ permissions:
   contents: read
 
 jobs:
+  test:
+    name: Test & Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - name: Cache cargo build
+        uses: Swatinem/rust-cache@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: Rust format check
+        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Rust unit & property tests
+        run: cargo test
+      - name: Rust test-vector suites
+        run: cargo test --features test-vectors
+      - name: Build extension module
+        run: uv run --with maturin maturin develop
+      - name: Ruff format check
+        run: uv run ruff format --check .
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Type check (ty)
+        run: uvx ty check
+      - name: Python integration tests
+        run: uv run pytest
+
   linux:
     runs-on: ${{ matrix.platform.runner }}
     strategy:
@@ -155,7 +189,7 @@ jobs:
     name: Release
     runs-on: ubuntu-latest
     if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
-    needs: [linux, musllinux, windows, macos, sdist]
+    needs: [test, linux, musllinux, windows, macos, sdist]
     permissions:
       # Use to sign the release artifacts
       id-token: write

diff --git a/.gitignore b/.gitignore
@@ -39,9 +39,19 @@ Thumbs.db
 .coverage
 htmlcov/
 .tox/
+.hypothesis/
 
 # Maturin
 *.whl
+# Compiled extension artifacts (produced by `maturin develop` into python/fast_paseto/)
+*.pdb
+*.pyd
+*.so
+python/fast_paseto/__pycache__/
 
 # Kiro
 .kiro/specs/
+
+# Profiling
+# profiling/benchmark.py is tracked; only its machine-specific output is not.
+profiling/results.json
diff --git a/.hypothesis/examples/04e6b3400353b141/7367e70b57312087 b/.hypothesis/examples/04e6b3400353b141/7367e70b57312087
diff --git a/.hypothesis/examples/04e6b3400353b141/afb31efeee4d6d24 b/.hypothesis/examples/04e6b3400353b141/afb31efeee4d6d24
diff --git a/.hypothesis/examples/04e6b3400353b141/d7f05bfe3a056c03 b/.hypothesis/examples/04e6b3400353b141/d7f05bfe3a056c03
diff --git a/.hypothesis/examples/7367e70b57312087/5228a5805998c2a1 b/.hypothesis/examples/7367e70b57312087/5228a5805998c2a1
diff --git a/.hypothesis/examples/afb31efeee4d6d24/cd54d6e90a8bc3c3 b/.hypothesis/examples/afb31efeee4d6d24/cd54d6e90a8bc3c3
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/2918fc45eb893f31 b/.hypothesis/examples/d7f05bfe3a056c03/2918fc45eb893f31
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/35882644b0886c64 b/.hypothesis/examples/d7f05bfe3a056c03/35882644b0886c64
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/51fc316317743639 b/.hypothesis/examples/d7f05bfe3a056c03/51fc316317743639
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/6034f18d32c4135e b/.hypothesis/examples/d7f05bfe3a056c03/6034f18d32c4135e
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/81698e4375b9dee7 b/.hypothesis/examples/d7f05bfe3a056c03/81698e4375b9dee7
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/84f3f57a1c1bf82a b/.hypothesis/examples/d7f05bfe3a056c03/84f3f57a1c1bf82a
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/b257a0043c2a89b1 b/.hypothesis/examples/d7f05bfe3a056c03/b257a0043c2a89b1
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/b57ed71e766ef56e b/.hypothesis/examples/d7f05bfe3a056c03/b57ed71e766ef56e
diff --git a/.hypothesis/examples/d7f05bfe3a056c03/dfe210a25d4fdd6e b/.hypothesis/examples/d7f05bfe3a056c03/dfe210a25d4fdd6e
diff --git a/.hypothesis/tmp/tmp1zlcrvd4 b/.hypothesis/tmp/tmp1zlcrvd4
diff --git a/.hypothesis/tmp/tmp2owxeye9 b/.hypothesis/tmp/tmp2owxeye9
diff --git a/.hypothesis/tmp/tmp3xvw_6q9 b/.hypothesis/tmp/tmp3xvw_6q9
diff --git a/.hypothesis/tmp/tmp4ar9mb22 b/.hypothesis/tmp/tmp4ar9mb22
diff --git a/.hypothesis/tmp/tmp59bq68j1 b/.hypothesis/tmp/tmp59bq68j1
diff --git a/.hypothesis/tmp/tmp5yh_vyz0 b/.hypothesis/tmp/tmp5yh_vyz0
diff --git a/.hypothesis/tmp/tmp6oowax72 b/.hypothesis/tmp/tmp6oowax72
diff --git a/.hypothesis/tmp/tmp9ulmd1j1 b/.hypothesis/tmp/tmp9ulmd1j1
diff --git a/.hypothesis/tmp/tmp_bjh0uwy b/.hypothesis/tmp/tmp_bjh0uwy
diff --git a/.hypothesis/tmp/tmpaa85lrcu b/.hypothesis/tmp/tmpaa85lrcu
diff --git a/.hypothesis/tmp/tmpbeyiu0tm b/.hypothesis/tmp/tmpbeyiu0tm
diff --git a/.hypothesis/tmp/tmpbsv5aums b/.hypothesis/tmp/tmpbsv5aums
diff --git a/.hypothesis/tmp/tmpd5264j_8 b/.hypothesis/tmp/tmpd5264j_8
diff --git a/.hypothesis/tmp/tmpe7b9su8z b/.hypothesis/tmp/tmpe7b9su8z
diff --git a/.hypothesis/tmp/tmpegf1l9fa b/.hypothesis/tmp/tmpegf1l9fa
diff --git a/.hypothesis/tmp/tmpf5gwhwtz b/.hypothesis/tmp/tmpf5gwhwtz
diff --git a/.hypothesis/tmp/tmpgtvya09b b/.hypothesis/tmp/tmpgtvya09b
diff --git a/.hypothesis/tmp/tmpizpu1rty b/.hypothesis/tmp/tmpizpu1rty
diff --git a/.hypothesis/tmp/tmpkg878c69 b/.hypothesis/tmp/tmpkg878c69
diff --git a/.hypothesis/tmp/tmpntuzs9z9 b/.hypothesis/tmp/tmpntuzs9z9
diff --git a/.hypothesis/tmp/tmpqthhe1ul b/.hypothesis/tmp/tmpqthhe1ul
diff --git a/.hypothesis/tmp/tmpr97eqx5y b/.hypothesis/tmp/tmpr97eqx5y
diff --git a/.hypothesis/tmp/tmpriqnkyl8 b/.hypothesis/tmp/tmpriqnkyl8
diff --git a/.hypothesis/tmp/tmptekuru68 b/.hypothesis/tmp/tmptekuru68
diff --git a/.hypothesis/tmp/tmpwpsvf8f4 b/.hypothesis/tmp/tmpwpsvf8f4
diff --git a/.hypothesis/tmp/tmpwu9biw6k b/.hypothesis/tmp/tmpwu9biw6k
diff --git a/.hypothesis/tmp/tmpya1fi1fh b/.hypothesis/tmp/tmpya1fi1fh
diff --git a/.hypothesis/tmp/tmpyf6cleyn b/.hypothesis/tmp/tmpyf6cleyn
diff --git a/.hypothesis/tmp/tmpzduinlm1 b/.hypothesis/tmp/tmpzduinlm1
diff --git a/.hypothesis/unicode_data/14.0.0/charmap.json.gz b/.hypothesis/unicode_data/14.0.0/charmap.json.gz
diff --git a/.hypothesis/unicode_data/14.0.0/codec-utf-8.json.gz b/.hypothesis/unicode_data/14.0.0/codec-utf-8.json.gz
diff --git a/.kiro/steering/product.md b/.kiro/steering/product.md
@@ -1,56 +1,51 @@
----
-inclusion: always
----
-
 # Product Overview
 
-fast-paseto is a high-performance PASETO library: Rust core with Python bindings via PyO3.
-
-## What This Library Does
+fast-paseto is a high-performance [PASETO](https://paseto.io/) (Platform-Agnostic Security Tokens) library: a Rust core exposed to Python via PyO3. It aims to be significantly faster than pure-Python alternatives (benchmarked against `pyseto`) while keeping a clean, type-hinted Python API.
 
-| Token Type | Crypto | Use Case |
-|------------|--------|----------|
-| `local` (symmetric) | XChaCha20-Poly1305 | Encrypted confidential data |
-| `public` (asymmetric) | Ed25519 | Signed verifiable data (not encrypted) |
+## Token Types
 
-Supported versions: v4 (default), v3 (NIST), v2 (legacy)
+| Type | Crypto (v4) | Use Case |
+|------|-------------|----------|
+| `local` (symmetric) | XChaCha20-Poly1305 | Encrypted, confidential data |
+| `public` (asymmetric) | Ed25519 signatures | Signed, verifiable data (NOT encrypted) |
 
-## API Patterns
+## Supported Versions
 
-Two usage styles exist:
+| Version | Local (encryption) | Public (signatures) |
+|---------|--------------------|----------------------|
+| v4 (default) | XChaCha20-Poly1305 | Ed25519 |
+| v3 (NIST) | AES-256-CTR + HMAC-SHA384 | ECDSA P-384 |
+| v2 (legacy) | XChaCha20-Poly1305 | Ed25519 |
 
-1. **Module functions** â€” `encode()`, `decode()` for one-off operations
-2. **Paseto class** â€” Configurable instance with defaults (expiration, serializer, etc.)
+## API Surface
 
-Key behaviors:
-- Auto-injects `exp` and `iat` claims when configured
-- JSON serialization by default; custom serializers via Protocol
-- Returns immutable `Token` objects from decode operations
+Two usage styles:
 
-## Code Generation Rules
+1. **Module functions** â€” `encode()`, `decode()`, `generate_symmetric_key()`, `generate_keypair()` for one-off operations.
+2. **`Paseto` class** â€” Configurable instance with defaults: `default_exp`, `include_iat`, `leeway`.
 
-When generating code for this library:
-
-| Do | Don't |
-|----|-------|
-| Use `generate_symmetric_key()` for local tokens | Hardcode or generate keys manually |
-| Use `generate_asymmetric_keypair()` for public tokens | Implement any crypto in Python |
-| Default to v4 unless user specifies otherwise | Mix key types across token purposes |
-| Validate key lengths (32B symmetric, 64B secret, 32B public) | Put sensitive data in public tokens |
-| Use type stubs from `fast_paseto.pyi` for signatures | Add Python runtime dependencies |
+Additional capabilities:
+- **PASERK** â€” key serialization (`to_paserk_local/secret/public`, `from_paserk`), key IDs (`generate_lid/sid/pid`), key wrapping (`local_wrap/unwrap`, `secret_wrap/unwrap`), password protection with Argon2id (`local_pw_encrypt/decrypt`, `secret_pw_encrypt/decrypt`).
+- **PEM loading** â€” `ed25519_from_pem`, `ed25519_public_from_pem`.
+- **Footers & implicit assertions** â€” supported on encode/decode.
+- **Custom serialization** â€” JSON by default; pass an object implementing the `Serializer`/`Deserializer` protocol.
+- Auto-injects `exp`/`iat` claims when configured on a `Paseto` instance.
+- `decode()` returns an immutable `Token` (supports attribute access, `[]`, `in`, `to_dict()`).
 
 ## Key Lengths
 
 | Key Type | Length | Token Type |
 |----------|--------|------------|
 | Symmetric | 32 bytes | local |
-| Secret (private) | 64 bytes | public |
-| Public | 32 bytes | public |
+| Ed25519 secret | 64 bytes | public (signing) |
+| Ed25519 public | 32 bytes | public (verification) |
 
-## Common Mistakes to Prevent
+## Code Generation Rules
 
-- Using public tokens for confidential data (they're signed, not encrypted)
-- Reusing keys between local and public token operations
-- Implementing cryptographic operations outside Rust
-- Using PASETO for long-lived session storage (prefer short expiration)
-- Forgetting to rebuild with `maturin develop` after Rust changes
+| Do | Don't |
+|----|-------|
+| Use `generate_symmetric_key()` for local tokens | Hardcode or hand-roll keys |
+| Use `generate_keypair()` for public tokens | Implement any crypto in Python |
+| Default to v4 unless the user specifies otherwise | Mix key types across purposes |
+| Validate key lengths (32B symmetric, 64B secret, 32B public) | Put confidential data in public tokens (signed, not encrypted) |
+| Match signatures to `python/fast_paseto/_fast_paseto.pyi` | Use PASETO for long-lived session storage (prefer short exp) |