Metadata-Version: 2.4
Name: SessionArmor
Version: 0.1.0
Summary: Defense-grade Django middleware: session security, audit logging, and configurable request gates with hooks.
Project-URL: Homepage, https://github.com/Tunet-xyz/session_armor
Project-URL: Documentation, https://github.com/Tunet-xyz/session_armor#readme
Project-URL: Repository, https://github.com/Tunet-xyz/session_armor
Project-URL: Issues, https://github.com/Tunet-xyz/session_armor/issues
Project-URL: Changelog, https://github.com/Tunet-xyz/session_armor/blob/main/CHANGELOG.md
Author-email: Alex C <alex@coded.uk>
License-Expression: MIT
License-File: LICENSE
Keywords: audit,django,gates,middleware,nist,owasp,security,session
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Provides-Extra: dev
Requires-Dist: django-stubs>=4.2.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-django>=4.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# SessionArmor

[![Tests](https://github.com/Tunet-xyz/session_armor/actions/workflows/tests.yaml/badge.svg)](https://github.com/Tunet-xyz/session_armor/actions/workflows/tests.yaml)
[![PyPI version](https://badge.fury.io/py/SessionArmor.svg)](https://pypi.org/project/SessionArmor/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Django 4.2+](https://img.shields.io/badge/django-4.2+-green.svg)](https://www.djangoproject.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Defense-grade Django middleware: session security, audit logging, and configurable request gates with hooks.**

Part of the [Tunet](https://github.com/Tunet-xyz) ecosystem — alongside [SwapLayer](https://github.com/Tunet-xyz/swap_layer) and [InfraGlyph](https://github.com/Tunet-xyz/infra_glyph).

---

## What It Does

SessionArmor provides three drop-in Django middleware classes that harden your application's session layer:

| Middleware | Purpose |
|-----------|---------|
| `SessionSecurityMiddleware` | Fingerprint binding, absolute/idle timeouts, claim drift detection |
| `AuditMiddleware` | Privacy-preserving security audit trail for every authenticated request |
| `GateMiddleware` | Base class for building cacheable conditional gates (compliance, onboarding, feature flags) |

All three are **hookable** — override methods to customize behavior without touching internals.

## References

- [NIST SP 800-53 AC-12](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) (Session Termination)
- [NIST SP 800-53 SC-23](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) (Session Authenticity)
- [NIST SP 800-53 AU-3/AU-12](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final) (Audit Content/Generation)
- [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)

---

## Installation

```bash
pip install SessionArmor
```

## Quick Start

```python
# settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    # ... your auth middleware ...
    'session_armor.session.SessionSecurityMiddleware',
    'session_armor.audit.AuditMiddleware',
    # ... rest of your middleware ...
]

# Optional settings (shown with defaults)
SESSION_ABSOLUTE_TIMEOUT = 28800      # 8 hours
SESSION_IDLE_TIMEOUT = 1800           # 30 minutes
SESSION_BIND_IP = True
SESSION_BIND_USER_AGENT = True
SESSION_DETECT_CLAIM_DRIFT = True
SESSION_ARMOR_TRUSTED_PROXY_DEPTH = 1  # Number of trusted reverse proxies
```

## Building a Gate

```python
from session_armor import GateMiddleware
from django.shortcuts import redirect

class ComplianceGate(GateMiddleware):
    gate_id = 'compliance'
    cache_ttl_setting = 'COMPLIANCE_CACHE_TTL'
    default_cache_ttl = 3600
    fail_open = False  # Block access if check fails

    def check(self, request) -> bool:
        return user_accepted_current_terms(request)

    def on_reject(self, request):
        return redirect('/accept-terms/')
```

## Customizing Session Security

```python
from session_armor import SessionSecurityMiddleware

class MySessionSecurity(SessionSecurityMiddleware):
    exempt_paths = ('/health/', '/static/')

    def get_critical_claims(self, user):
        # Auth0 / OIDC claims that must not change mid-session
        return [user.sub, user.organization_uuid, user.platform]

    def get_login_url(self, request):
        platform = getattr(request.user, 'platform', '')
        return f'/{platform}/login/' if platform else '/login/'
```

## Customizing Audit Logging

```python
from session_armor import AuditMiddleware

class MyAudit(AuditMiddleware):
    exempt_paths = ('/health/', '/static/', '/favicon.ico')

    def get_user_identity(self, request):
        return {
            'uid': request.user.sub,
            'platform': request.user.platform,
            'org': request.user.organization_uuid,
        }
```

---

## Development

```bash
# Clone and install
git clone https://github.com/Tunet-xyz/session_armor.git
cd session_armor
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/session_armor tests

# Type check
mypy src/session_armor
```

## License

MIT — see [LICENSE](LICENSE).
