ndaedzo-shared-lib 0.1.0__tar.gz

ndaedzo_shared_lib-0.1.0/.env.example

@@ -0,0 +1,35 @@
+# Copy this file to .env and fill in real values. Never commit .env.
+
+# Algorithm used to sign and verify JWTs.
+#
+# RS256 (recommended for microservices): asymmetric. The service that issues
+# tokens holds the private key; every other service only needs the public
+# key to verify tokens, so a leak of a verifying service doesn't expose the
+# signing key.
+#
+# HS256: symmetric and simpler, but every service that verifies tokens must
+# hold the same shared secret as the issuer, which widens the blast radius
+# of a leak. Only use it for a single-service setup or trusted internal use.
+JWT_ALGORITHM=RS256
+
+# --- RS256 / other asymmetric algorithms (RS384, RS512, ES256, ...) ---
+# Provide EITHER the *_PATH variant (recommended) OR the raw PEM in the
+# matching non-PATH variable below - not both. Generate a dev key pair with:
+#   uv run python scripts/generate_keys.py
+JWT_PRIVATE_KEY_PATH=keys/private_key.pem
+JWT_PUBLIC_KEY_PATH=keys/public_key.pem
+# JWT_PRIVATE_KEY=
+# JWT_PUBLIC_KEY=
+
+# --- HS256 / other symmetric algorithms ---
+# Required only when JWT_ALGORITHM is HS256/HS384/HS512.
+JWT_SECRET_KEY=
+
+# Token lifetimes.
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
+JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
+
+# Optional standard claims. When set, they are stamped onto every issued
+# token and enforced on every verified token.
+JWT_ISSUER=pt-web-app
+JWT_AUDIENCE=pt-web-app-services

ndaedzo_shared_lib-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }} --all-groups
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run python -m unittest discover -s tests -t . -v
+
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Build distribution
+        run: uv build

ndaedzo_shared_lib-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Secrets and local config
+.env
+.env.*.local
+keys/
+*.pem
+*.key
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

ndaedzo_shared_lib-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ndaedzo_shared_lib-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.5
+Name: ndaedzo-shared-lib
+Version: 0.1.0
+Summary: Production-ready JWT access/refresh token issuance and verification library for microservices.
+Requires-Python: >=3.10
+Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Dist: python-dotenv>=1.0.1
+Description-Content-Type: text/markdown
+
+# shared-lib
+
+A production-ready JWT authentication library for issuing and verifying access and refresh tokens across microservices, built on [PyJWT](https://pyjwt.readthedocs.io/) and managed with [uv](https://docs.astral.sh/uv/).
+
+## Features
+
+- Access token + refresh token issuance, individually or as a pair
+- Token verification with signature, expiry, not-before, issuer, and audience checks
+- Strict token-type separation - a refresh token can never be used where an access token is expected, and vice versa
+- Refresh token rotation (`refresh_access_token(..., rotate_refresh_token=True)`)
+- Pluggable revocation - pass an `is_revoked(jti) -> bool` callback backed by whatever store you use (Redis, a database, ...) to reject tokens by ID before they expire
+- Asymmetric (RS256/ES256/PS256) and symmetric (HS256) algorithm support, configured entirely via environment variables
+- Typed dataclasses (`TokenPair`, `TokenPayload`) and a small, specific exception hierarchy instead of stringly-typed errors
+- Full unittest suite and GitHub Actions CI
+
+## Why RS256 for microservices
+
+With a symmetric algorithm (HS256), every service that needs to verify a token must hold the exact same secret used to sign it - so the secret has to be distributed to every service, and any one of them leaking it lets an attacker forge tokens for the whole system.
+
+With an asymmetric algorithm (RS256), only the service that issues tokens (e.g. an auth service) holds the private key. Every other service is configured with just the public key, which is enough to verify a token's signature but not to create new ones. This is the recommended default for a microservices setup and is what this library uses out of the box.
+
+## Installation
+
+This repo is managed with `uv`. From the project root:
+
+```bash
+uv sync
+```
+
+To use `jwt_auth` from another project in this workspace/monorepo, add it as a path or git dependency with `uv add`.
+
+## Quickstart
+
+1. Copy the example environment file and generate a dev key pair:
+
+   ```bash
+   cp .env.example .env
+   uv run python scripts/generate_keys.py
+   ```
+
+   This writes `keys/private_key.pem` and `keys/public_key.pem` (both gitignored). The default `.env` already points `JWT_PRIVATE_KEY_PATH` / `JWT_PUBLIC_KEY_PATH` at these files.
+
+2. Run the demo:
+
+   ```bash
+   uv run main.py
+   ```
+
+3. Use it in code:
+
+   ```python
+   from jwt_auth import JWTManager, TokenExpiredError, InvalidTokenError
+
+   manager = JWTManager()  # reads configuration from the environment
+
+   tokens = manager.create_token_pair(subject="user-123", extra_claims={"role": "trainer"})
+   # tokens.access_token, tokens.refresh_token, tokens.expires_in
+
+   try:
+       payload = manager.verify_access_token(tokens.access_token)
+       user_id = payload.sub
+   except TokenExpiredError:
+       ...  # ask the client to hit the refresh endpoint
+   except InvalidTokenError:
+       ...  # reject the request, log the attempt
+   ```
+
+4. Refreshing an access token:
+
+   ```python
+   new_tokens = manager.refresh_access_token(refresh_token, rotate_refresh_token=True)
+   ```
+
+## Auth service vs. downstream services
+
+Because RS256 keys are asymmetric, a downstream service that only ever needs to *verify* tokens should be configured with just the public key - it will raise `ConfigurationError` if you try to issue a token with it:
+
+```python
+# Auth service - has both keys, can issue and verify.
+issuer = JWTManager()  # JWT_PRIVATE_KEY_PATH and JWT_PUBLIC_KEY_PATH set
+
+# Downstream service - only distribute the public key.
+verifier = JWTManager(JWTSettings(algorithm="RS256", public_key=public_key_pem))
+verifier.verify_access_token(incoming_token)  # OK
+verifier.create_access_token("user-1")        # raises ConfigurationError
+```
+
+## Revocation
+
+This library doesn't ship a storage backend, since that choice (Redis, Postgres, ...) belongs to the application. Instead, `JWTManager` accepts an `is_revoked` callback:
+
+```python
+def is_revoked(jti: str) -> bool:
+    return redis_client.sismember("revoked-jtis", jti)
+
+manager = JWTManager(is_revoked=is_revoked)
+```
+
+Every `verify_access_token` / `verify_refresh_token` call runs the token's `jti` through this callback, so revoking a token (on logout, on rotation, or by an admin) just means adding its `jti` to your store.
+
+## Configuration reference
+
+All configuration is read from the environment (optionally via a `.env` file, loaded automatically the first time `JWTSettings.from_env()` runs).
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `JWT_ALGORITHM` | no | `RS256` | Any PyJWT-supported algorithm: `RS256/384/512`, `ES256/384/512`, `PS256/384/512`, `HS256/384/512` |
+| `JWT_PRIVATE_KEY_PATH` / `JWT_PRIVATE_KEY` | for asymmetric algorithms, to issue tokens | - | Path to a PEM file, or the raw PEM (with `\n` escapes) |
+| `JWT_PUBLIC_KEY_PATH` / `JWT_PUBLIC_KEY` | for asymmetric algorithms, to verify tokens | - | Path to a PEM file, or the raw PEM (with `\n` escapes) |
+| `JWT_SECRET_KEY` | for symmetric algorithms | - | Shared secret |
+| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | no | `15` | Keep this short - access tokens are bearer credentials |
+| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | no | `7` | |
+| `JWT_ISSUER` | no | - | Stamped as `iss` and enforced on verify when set |
+| `JWT_AUDIENCE` | no | - | Stamped as `aud` and enforced on verify when set |
+
+See `.env.example` for a template.
+
+## Testing
+
+```bash
+uv run python -m unittest discover -s tests -t . -v
+```
+
+Tests cover both HS256 and RS256 code paths, token-type separation, tampering/wrong-key/wrong-audience rejection, expiry, refresh rotation, revocation, and configuration validation - no network or external services required.
+
+## CI
+
+`.github/workflows/ci.yml` runs on every push and pull request to `main`: it lints with `ruff`, runs the full test suite across Python 3.10-3.13 via `uv`, and does a final build check. Update this library, push, and CI will catch regressions before they reach any service that depends on it.
+
+## Security notes
+
+- Keep access token lifetimes short (minutes) and refresh token lifetimes as short as your product allows (days, not months).
+- Prefer RS256 (or another asymmetric algorithm) over HS256 whenever more than one service needs to verify tokens.
+- Use `rotate_refresh_token=True` and pair it with the `is_revoked` callback so a stolen, already-rotated refresh token can be rejected on reuse.
+- Never log full tokens. `TokenPayload.jti` is safe to log; the raw token string is a bearer credential.
+- Always serve token endpoints over HTTPS.
+- `keys/`, `.env`, and `*.pem` are gitignored - do not commit real key material or secrets.

ndaedzo_shared_lib-0.1.0/README.md

@@ -0,0 +1,137 @@
+# shared-lib
+
+A production-ready JWT authentication library for issuing and verifying access and refresh tokens across microservices, built on [PyJWT](https://pyjwt.readthedocs.io/) and managed with [uv](https://docs.astral.sh/uv/).
+
+## Features
+
+- Access token + refresh token issuance, individually or as a pair
+- Token verification with signature, expiry, not-before, issuer, and audience checks
+- Strict token-type separation - a refresh token can never be used where an access token is expected, and vice versa
+- Refresh token rotation (`refresh_access_token(..., rotate_refresh_token=True)`)
+- Pluggable revocation - pass an `is_revoked(jti) -> bool` callback backed by whatever store you use (Redis, a database, ...) to reject tokens by ID before they expire
+- Asymmetric (RS256/ES256/PS256) and symmetric (HS256) algorithm support, configured entirely via environment variables
+- Typed dataclasses (`TokenPair`, `TokenPayload`) and a small, specific exception hierarchy instead of stringly-typed errors
+- Full unittest suite and GitHub Actions CI
+
+## Why RS256 for microservices
+
+With a symmetric algorithm (HS256), every service that needs to verify a token must hold the exact same secret used to sign it - so the secret has to be distributed to every service, and any one of them leaking it lets an attacker forge tokens for the whole system.
+
+With an asymmetric algorithm (RS256), only the service that issues tokens (e.g. an auth service) holds the private key. Every other service is configured with just the public key, which is enough to verify a token's signature but not to create new ones. This is the recommended default for a microservices setup and is what this library uses out of the box.
+
+## Installation
+
+This repo is managed with `uv`. From the project root:
+
+```bash
+uv sync
+```
+
+To use `jwt_auth` from another project in this workspace/monorepo, add it as a path or git dependency with `uv add`.
+
+## Quickstart
+
+1. Copy the example environment file and generate a dev key pair:
+
+   ```bash
+   cp .env.example .env
+   uv run python scripts/generate_keys.py
+   ```
+
+   This writes `keys/private_key.pem` and `keys/public_key.pem` (both gitignored). The default `.env` already points `JWT_PRIVATE_KEY_PATH` / `JWT_PUBLIC_KEY_PATH` at these files.
+
+2. Run the demo:
+
+   ```bash
+   uv run main.py
+   ```
+
+3. Use it in code:
+
+   ```python
+   from jwt_auth import JWTManager, TokenExpiredError, InvalidTokenError
+
+   manager = JWTManager()  # reads configuration from the environment
+
+   tokens = manager.create_token_pair(subject="user-123", extra_claims={"role": "trainer"})
+   # tokens.access_token, tokens.refresh_token, tokens.expires_in
+
+   try:
+       payload = manager.verify_access_token(tokens.access_token)
+       user_id = payload.sub
+   except TokenExpiredError:
+       ...  # ask the client to hit the refresh endpoint
+   except InvalidTokenError:
+       ...  # reject the request, log the attempt
+   ```
+
+4. Refreshing an access token:
+
+   ```python
+   new_tokens = manager.refresh_access_token(refresh_token, rotate_refresh_token=True)
+   ```
+
+## Auth service vs. downstream services
+
+Because RS256 keys are asymmetric, a downstream service that only ever needs to *verify* tokens should be configured with just the public key - it will raise `ConfigurationError` if you try to issue a token with it:
+
+```python
+# Auth service - has both keys, can issue and verify.
+issuer = JWTManager()  # JWT_PRIVATE_KEY_PATH and JWT_PUBLIC_KEY_PATH set
+
+# Downstream service - only distribute the public key.
+verifier = JWTManager(JWTSettings(algorithm="RS256", public_key=public_key_pem))
+verifier.verify_access_token(incoming_token)  # OK
+verifier.create_access_token("user-1")        # raises ConfigurationError
+```
+
+## Revocation
+
+This library doesn't ship a storage backend, since that choice (Redis, Postgres, ...) belongs to the application. Instead, `JWTManager` accepts an `is_revoked` callback:
+
+```python
+def is_revoked(jti: str) -> bool:
+    return redis_client.sismember("revoked-jtis", jti)
+
+manager = JWTManager(is_revoked=is_revoked)
+```
+
+Every `verify_access_token` / `verify_refresh_token` call runs the token's `jti` through this callback, so revoking a token (on logout, on rotation, or by an admin) just means adding its `jti` to your store.
+
+## Configuration reference
+
+All configuration is read from the environment (optionally via a `.env` file, loaded automatically the first time `JWTSettings.from_env()` runs).
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `JWT_ALGORITHM` | no | `RS256` | Any PyJWT-supported algorithm: `RS256/384/512`, `ES256/384/512`, `PS256/384/512`, `HS256/384/512` |
+| `JWT_PRIVATE_KEY_PATH` / `JWT_PRIVATE_KEY` | for asymmetric algorithms, to issue tokens | - | Path to a PEM file, or the raw PEM (with `\n` escapes) |
+| `JWT_PUBLIC_KEY_PATH` / `JWT_PUBLIC_KEY` | for asymmetric algorithms, to verify tokens | - | Path to a PEM file, or the raw PEM (with `\n` escapes) |
+| `JWT_SECRET_KEY` | for symmetric algorithms | - | Shared secret |
+| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | no | `15` | Keep this short - access tokens are bearer credentials |
+| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | no | `7` | |
+| `JWT_ISSUER` | no | - | Stamped as `iss` and enforced on verify when set |
+| `JWT_AUDIENCE` | no | - | Stamped as `aud` and enforced on verify when set |
+
+See `.env.example` for a template.
+
+## Testing
+
+```bash
+uv run python -m unittest discover -s tests -t . -v
+```
+
+Tests cover both HS256 and RS256 code paths, token-type separation, tampering/wrong-key/wrong-audience rejection, expiry, refresh rotation, revocation, and configuration validation - no network or external services required.
+
+## CI
+
+`.github/workflows/ci.yml` runs on every push and pull request to `main`: it lints with `ruff`, runs the full test suite across Python 3.10-3.13 via `uv`, and does a final build check. Update this library, push, and CI will catch regressions before they reach any service that depends on it.
+
+## Security notes
+
+- Keep access token lifetimes short (minutes) and refresh token lifetimes as short as your product allows (days, not months).
+- Prefer RS256 (or another asymmetric algorithm) over HS256 whenever more than one service needs to verify tokens.
+- Use `rotate_refresh_token=True` and pair it with the `is_revoked` callback so a stolen, already-rotated refresh token can be rejected on reuse.
+- Never log full tokens. `TokenPayload.jti` is safe to log; the raw token string is a bearer credential.
+- Always serve token endpoints over HTTPS.
+- `keys/`, `.env`, and `*.pem` are gitignored - do not commit real key material or secrets.

ndaedzo_shared_lib-0.1.0/main.py

@@ -0,0 +1,55 @@
+"""Runnable demo of the jwt_auth library.
+
+Usage:
+    uv run python scripts/generate_keys.py   # first time only, creates keys/
+    uv run main.py
+"""
+
+from jwt_auth import (
+    InvalidTokenTypeError,
+    JWTManager,
+    TokenExpiredError,
+    TokenRevokedError,
+)
+
+
+def main() -> None:
+    # In a real service, is_revoked would look up a denylist (e.g. Redis) of
+    # jti's for tokens that were revoked before their natural expiry (logout,
+    # rotation, admin action, ...).
+    revoked_jtis: set[str] = set()
+    manager = JWTManager(is_revoked=lambda jti: jti in revoked_jtis)
+
+    tokens = manager.create_token_pair(subject="user-123", extra_claims={"role": "trainer"})
+    print(f"access_token:  {tokens.access_token}")
+    print(f"refresh_token: {tokens.refresh_token}")
+    print(f"expires_in:    {tokens.expires_in}s")
+
+    payload = manager.verify_access_token(tokens.access_token)
+    print(f"\nverified access token for subject={payload.sub!r} claims={payload.claims}")
+
+    refreshed = manager.refresh_access_token(tokens.refresh_token, rotate_refresh_token=True)
+    print(f"\nrotated refresh_token: {refreshed.refresh_token}")
+
+    old_refresh_payload = manager.verify_refresh_token(tokens.refresh_token)
+    revoked_jtis.add(old_refresh_payload.jti)
+    try:
+        manager.verify_refresh_token(tokens.refresh_token)
+    except TokenRevokedError as exc:
+        print(f"\nold refresh token correctly rejected after rotation: {exc}")
+
+    try:
+        manager.verify_access_token(tokens.refresh_token)
+    except InvalidTokenTypeError as exc:
+        print(f"refresh token correctly rejected when used as an access token: {exc}")
+
+    try:
+        manager.verify_access_token("not-a-jwt")
+    except TokenExpiredError:
+        pass
+    except Exception as exc:  # noqa: BLE001 - demo only
+        print(f"malformed token correctly rejected: {exc}")
+
+
+if __name__ == "__main__":
+    main()

ndaedzo_shared_lib-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "ndaedzo-shared-lib"
+version = "0.1.0"
+description = "Production-ready JWT access/refresh token issuance and verification library for microservices."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pyjwt[crypto]>=2.10.1",
+    "python-dotenv>=1.0.1",
+]
+
+[dependency-groups]
+dev = [
+    "build>=1.6.0",
+    "ruff>=0.8.0",
+    "twine>=7.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jwt_auth"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

ndaedzo_shared_lib-0.1.0/scripts/generate_keys.py

@@ -0,0 +1,48 @@
+"""Generate an RSA key pair for RS256-signed JWTs.
+
+Usage:
+    uv run python scripts/generate_keys.py [output_dir]
+
+Writes private_key.pem and public_key.pem into `output_dir` (default: ./keys).
+The private key must stay on the service that issues tokens; only distribute
+the public key to services that need to verify them. Never commit
+private_key.pem to version control (the keys/ directory is gitignored).
+"""
+
+import sys
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+
+def generate_key_pair(output_dir: Path, key_size: int = 2048) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=key_size)
+
+    private_path = output_dir / "private_key.pem"
+    public_path = output_dir / "public_key.pem"
+
+    private_path.write_bytes(
+        private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.PKCS8,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    public_path.write_bytes(
+        private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+    )
+
+    print(f"Wrote {private_path}")
+    print(f"Wrote {public_path}")
+    print("Keep private_key.pem secret - it is gitignored, but verify that before committing.")
+
+
+if __name__ == "__main__":
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("keys")
+    generate_key_pair(target)

ndaedzo_shared_lib-0.1.0/src/jwt_auth/__init__.py

@@ -0,0 +1,40 @@
+"""jwt_auth: production-ready JWT access/refresh token issuance and verification.
+
+Typical usage:
+
+    from jwt_auth import JWTManager
+
+    manager = JWTManager()  # reads configuration from the environment
+    tokens = manager.create_token_pair(subject="user-123")
+    payload = manager.verify_access_token(tokens.access_token)
+"""
+
+from .config import JWTSettings
+from .exceptions import (
+    ConfigurationError,
+    InvalidTokenError,
+    InvalidTokenTypeError,
+    JWTError,
+    TokenExpiredError,
+    TokenRevokedError,
+)
+from .manager import ACCESS_TOKEN_TYPE, REFRESH_TOKEN_TYPE, JWTManager
+from .models import TokenPair, TokenPayload
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "JWTManager",
+    "JWTSettings",
+    "TokenPair",
+    "TokenPayload",
+    "JWTError",
+    "ConfigurationError",
+    "TokenExpiredError",
+    "InvalidTokenError",
+    "InvalidTokenTypeError",
+    "TokenRevokedError",
+    "ACCESS_TOKEN_TYPE",
+    "REFRESH_TOKEN_TYPE",
+    "__version__",
+]

ndaedzo_shared_lib-0.1.0/src/jwt_auth/config.py

@@ -0,0 +1,92 @@
+"""Environment-driven configuration for JWTManager."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from .exceptions import ConfigurationError
+
+_dotenv_loaded = False
+
+
+def _ensure_dotenv_loaded() -> None:
+    global _dotenv_loaded
+    if not _dotenv_loaded:
+        load_dotenv()
+        _dotenv_loaded = True
+
+
+def _read_key_material(raw: str | None, path: str | None) -> str | None:
+    """Resolve key material from either a raw PEM env var or a path to a PEM file.
+
+    Raw values may contain literal ``\\n`` sequences (common when a PEM is
+    stored as a single-line environment variable) and are unescaped.
+    """
+    if raw:
+        return raw.replace("\\n", "\n")
+    if path:
+        key_path = Path(path)
+        if not key_path.is_file():
+            raise ConfigurationError(f"Key file not found: {key_path}")
+        return key_path.read_text(encoding="utf-8")
+    return None
+
+
+@dataclass(frozen=True)
+class JWTSettings:
+    """Configuration for a JWTManager.
+
+    Prefer building this via `JWTSettings.from_env()`. Construct it directly
+    when wiring up tests or when configuration comes from somewhere other
+    than the process environment (e.g. a secrets manager).
+    """
+
+    algorithm: str = "RS256"
+    private_key: str | None = None
+    public_key: str | None = None
+    secret_key: str | None = None
+    access_token_expire_minutes: int = 15
+    refresh_token_expire_days: int = 7
+    issuer: str | None = None
+    audience: str | None = None
+
+    @classmethod
+    def from_env(cls, *, load_dotenv_file: bool = True) -> "JWTSettings":
+        """Build settings from environment variables (optionally loading a .env file first).
+
+        Recognized variables:
+            JWT_ALGORITHM                     default "RS256"
+            JWT_PRIVATE_KEY / JWT_PRIVATE_KEY_PATH   (asymmetric algorithms)
+            JWT_PUBLIC_KEY  / JWT_PUBLIC_KEY_PATH    (asymmetric algorithms)
+            JWT_SECRET_KEY                    (symmetric algorithms, e.g. HS256)
+            JWT_ACCESS_TOKEN_EXPIRE_MINUTES   default 15
+            JWT_REFRESH_TOKEN_EXPIRE_DAYS     default 7
+            JWT_ISSUER                        optional
+            JWT_AUDIENCE                      optional
+        """
+        if load_dotenv_file:
+            _ensure_dotenv_loaded()
+
+        private_key = _read_key_material(
+            os.getenv("JWT_PRIVATE_KEY"), os.getenv("JWT_PRIVATE_KEY_PATH")
+        )
+        public_key = _read_key_material(
+            os.getenv("JWT_PUBLIC_KEY"), os.getenv("JWT_PUBLIC_KEY_PATH")
+        )
+
+        return cls(
+            algorithm=os.getenv("JWT_ALGORITHM", "RS256").upper(),
+            private_key=private_key,
+            public_key=public_key,
+            secret_key=os.getenv("JWT_SECRET_KEY") or None,
+            access_token_expire_minutes=int(
+                os.getenv("JWT_ACCESS_TOKEN_EXPIRE_MINUTES", "15")
+            ),
+            refresh_token_expire_days=int(
+                os.getenv("JWT_REFRESH_TOKEN_EXPIRE_DAYS", "7")
+            ),
+            issuer=os.getenv("JWT_ISSUER") or None,
+            audience=os.getenv("JWT_AUDIENCE") or None,
+        )