SessionArmor 0.1.0__py3-none-any.whl

session_armor/__init__.py

@@ -0,0 +1,29 @@
+"""
+SessionArmor — defense-grade Django middleware.
+
+Session security, audit logging, and configurable request gates with hooks.
+
+Three middleware classes, one base class:
+
+    SessionSecurityMiddleware
+        Fingerprint binding, absolute/idle timeouts, claim drift detection.
+
+    AuditMiddleware
+        Privacy-preserving audit trail for every authenticated request.
+
+    GateMiddleware
+        Base class for building cacheable, hookable conditional gates
+        (compliance, onboarding, feature flags, maintenance, etc.).
+"""
+
+from .audit import AuditMiddleware
+from .gate import GateMiddleware
+from .session import SessionSecurityMiddleware
+
+__all__ = [
+    'GateMiddleware',
+    'SessionSecurityMiddleware',
+    'AuditMiddleware',
+]
+
+__version__ = '0.1.0'

session_armor/audit.py

@@ -0,0 +1,163 @@
+"""
+AuditMiddleware — security audit trail for Django requests.
+
+Logs every authenticated request with security-relevant context for
+forensic analysis, anomaly detection, and compliance reporting.
+
+Every log entry captures **WHO** did **WHAT** from **WHERE**, enabling:
+- Post-incident forensics
+- Real-time anomaly detection (via log aggregation / SIEM)
+- Compliance reporting (NIST 800-53 AU-3, AU-12; SOC 2)
+
+Never logs request bodies, tokens, or credentials.
+
+Hooks (override in subclass)::
+
+    get_user_identity(request)              → dict
+    get_extra_fields(request, response)     → dict
+    before_log(request, response, entry)    → dict | None
+    get_log_level(status_code)              → int
+    format_entry(entry)                     → str
+
+Usage::
+
+    # Generic
+    MIDDLEWARE = [..., 'session_armor.audit.AuditMiddleware', ...]
+
+    # Customized (e.g. Auth0-aware)
+    class MyAudit(AuditMiddleware):
+        def get_user_identity(self, request):
+            return {
+                'uid': request.user.sub,
+                'tenant': request.user.organization_uuid,
+            }
+"""
+
+import logging
+import time
+import uuid
+
+from .utils import get_client_ip, hash_value, is_authenticated, sanitize_for_log
+
+logger = logging.getLogger('security.audit')
+
+
+class AuditMiddleware:
+    """
+    Audit logging for authenticated requests.
+
+    Captures:
+        Request ID, user identity, method, path, status, hashed IP,
+        truncated user-agent, and request duration.
+
+    Does NOT capture:
+        Request/response bodies, tokens, passwords, query parameters.
+    """
+
+    # ── Configuration ────────────────────────────────────────────────────
+    logger_name: str = 'security.audit'
+    exempt_paths: tuple[str, ...] = ()
+
+    # ── Django middleware protocol ────────────────────────────────────────
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self._logger = logging.getLogger(self.logger_name)
+
+    def __call__(self, request):
+        if self._is_exempt(request):
+            return self.get_response(request)
+
+        # Attach request ID for correlation
+        request_id = str(uuid.uuid4())[:8]
+        request.META['X_REQUEST_ID'] = request_id
+        start = time.time()
+
+        response = self.get_response(request)
+
+        duration_ms = round((time.time() - start) * 1000)
+
+        # Only audit authenticated requests
+        if is_authenticated(request):
+            self._emit(request, response, request_id, duration_ms)
+
+        return response
+
+    # ── HOOKS (override in subclass) ─────────────────────────────────────
+
+    def get_user_identity(self, request) -> dict:
+        """
+        Extract user identity fields for the audit log entry.
+
+        Override to match your auth system's user model.
+        Default returns ``{'uid': user.pk}``.
+        """
+        user = request.user
+        return {
+            'uid': getattr(user, 'sub', None) or str(getattr(user, 'pk', '')),
+        }
+
+    def get_extra_fields(self, request, response) -> dict:
+        """Return additional fields to include in the audit entry."""
+        return {}
+
+    def before_log(self, request, response, entry: dict) -> dict | None:
+        """
+        Called before the entry is logged.
+
+        Return the (optionally modified) entry, or ``None`` to suppress
+        logging for this request.
+        """
+        return entry
+
+    def get_log_level(self, status_code: int) -> int:
+        """Return the ``logging`` level for a given response status code."""
+        if status_code >= 500:
+            return logging.ERROR
+        if status_code in (401, 403):
+            return logging.WARNING
+        if status_code >= 400:
+            return logging.INFO
+        return logging.DEBUG
+
+    def format_entry(self, entry: dict) -> str:
+        """
+        Format the audit entry for the log message.
+
+        Override to produce structured JSON, CEF, or other formats.
+        """
+        return f"AUDIT {entry}"
+
+    # ── INTERNALS ────────────────────────────────────────────────────────
+
+    def _emit(self, request, response, request_id: str, duration_ms: int):
+        ip = get_client_ip(request)
+
+        entry = {
+            'rid': request_id,
+            **self.get_user_identity(request),
+            'method': request.method,
+            'path': sanitize_for_log(request.path, max_length=500),
+            'status': response.status_code,
+            'ip_hash': hash_value(ip, length=16),
+            'ua': sanitize_for_log(
+                request.META.get('HTTP_USER_AGENT', ''), max_length=80
+            ),
+            'ms': duration_ms,
+            **self.get_extra_fields(request, response),
+        }
+
+        entry = self.before_log(request, response, entry)
+        if entry is None:
+            return
+
+        level = self.get_log_level(response.status_code)
+        message = self.format_entry(entry)
+
+        if response.status_code in (401, 403):
+            self._logger.log(level, message.replace('AUDIT', 'AUDIT_DENIED', 1))
+        else:
+            self._logger.log(level, message)
+
+    def _is_exempt(self, request) -> bool:
+        return any(request.path.startswith(p) for p in self.exempt_paths)

session_armor/gate.py

@@ -0,0 +1,213 @@
+"""
+GateMiddleware — configurable conditional gate for Django middleware stacks.
+
+A gate checks a condition on each request (with session caching) and either
+passes the request through or rejects it. Subclass this to build:
+
+- Compliance gates (legal document acceptance)
+- Onboarding gates (step completion)
+- Feature gates (entitlement / feature-flag checks)
+- Maintenance gates (scheduled downtime)
+- Any "must satisfy X before proceeding" pattern
+
+Follows the before/after hooks pattern for maximum customizability::
+
+    class ComplianceGate(GateMiddleware):
+        gate_id = 'compliance'
+        cache_ttl_setting = 'COMPLIANCE_CACHE_TTL'
+        default_cache_ttl = 3600
+
+        def check(self, request) -> bool:
+            return user_accepted_terms(request)
+
+        def on_reject(self, request):
+            return redirect('/accept-terms/')
+
+Hooks execute in this order::
+
+    before_check  →  check  →  after_check  →  on_pass / on_reject
+                       ↓ (exception)
+                    on_error
+"""
+
+import logging
+import time
+
+from django.conf import settings
+
+from .utils import is_authenticated
+
+logger = logging.getLogger('session_armor.gate')
+
+
+class GateMiddleware:
+    """
+    Base class for conditional gate middleware with session caching and hooks.
+
+    Configuration (set as class attributes on your subclass):
+
+        gate_id             Unique ID used for session-key namespacing.
+        cache_ttl_setting   Name of a Django setting that holds the TTL override.
+        default_cache_ttl   Fallback TTL in seconds (default 300).
+        exempt_paths        Tuple of path prefixes that bypass this gate.
+        requires_auth       Only check authenticated requests (default True).
+        fail_open           Pass through on errors (default False).
+
+    Hooks (override any combination in your subclass):
+
+        before_check(request) → bool | None
+        check(request) → bool                       **required**
+        after_check(request, passed: bool)
+        on_reject(request) → HttpResponse
+        on_pass(request)
+        on_error(request, error) → bool
+        get_rejection_context(request) → dict
+    """
+
+    # ── Configuration (override in subclass) ─────────────────────────────
+    gate_id: str = ''
+    cache_ttl_setting: str = ''
+    default_cache_ttl: int = 300
+    exempt_paths: tuple[str, ...] = ()
+    requires_auth: bool = True
+    fail_open: bool = False
+
+    # ── Django middleware protocol ────────────────────────────────────────
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        if not self.gate_id:
+            self.gate_id = self.__class__.__name__.lower()
+
+    def __call__(self, request):
+        # Exempt paths bypass the gate entirely
+        if self._is_exempt(request):
+            return self.get_response(request)
+
+        # Auth guard
+        if self.requires_auth and not is_authenticated(request):
+            return self.get_response(request)
+
+        # ── before_check hook ──
+        should_check = self.before_check(request)
+        if should_check is False:
+            return self.get_response(request)
+
+        now = time.time()
+        prefix = self._cache_prefix
+        ttl = self._get_cache_ttl()
+
+        # ── Session-cache fast path ──
+        checked_at = request.session.get(f'{prefix}_at', 0)
+        if (now - checked_at) < ttl and f'{prefix}_result' in request.session:
+            passed = request.session[f'{prefix}_result']
+            if not passed:
+                return self.on_reject(request)
+            self.on_pass(request)
+            return self.get_response(request)
+
+        # ── Run the check ──
+        try:
+            passed = self.check(request)
+        except Exception as exc:
+            passed = self.on_error(request, exc)
+
+        # ── after_check hook ──
+        self.after_check(request, passed)
+
+        # ── Cache the result ──
+        request.session[f'{prefix}_at'] = now
+        request.session[f'{prefix}_result'] = passed
+
+        if not passed:
+            ctx = self.get_rejection_context(request)
+            if ctx:
+                request.session[f'{prefix}_context'] = ctx
+            return self.on_reject(request)
+
+        self.on_pass(request)
+        return self.get_response(request)
+
+    # ── HOOKS (override in subclass) ─────────────────────────────────────
+
+    def before_check(self, request) -> bool | None:
+        """Called before ``check()``. Return ``False`` to skip the gate."""
+        return True
+
+    def check(self, request) -> bool:
+        """
+        The main condition.
+
+        Return ``True`` to let the request through, ``False`` to reject it.
+        **Must** be overridden in every subclass.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement check()"
+        )
+
+    def after_check(self, request, passed: bool) -> None:
+        """Called after ``check()`` with the result. Logging, metrics, side effects."""
+        pass
+
+    def on_reject(self, request):
+        """Called when the gate rejects. Return an ``HttpResponse``."""
+        from django.http import HttpResponseForbidden
+        return HttpResponseForbidden("Access denied")
+
+    def on_pass(self, request) -> None:
+        """Called when the gate passes. Side effects only (no return value)."""
+        pass
+
+    def on_error(self, request, error: Exception) -> bool:
+        """
+        Called when ``check()`` raises an exception.
+
+        Return ``True`` to pass through (fail-open), ``False`` to reject.
+        """
+        logger.error(
+            "%s check error: %s", self.__class__.__name__, error,
+            exc_info=True,
+        )
+        return self.fail_open
+
+    def get_rejection_context(self, request) -> dict:
+        """
+        Return extra data to store in session when the gate rejects.
+
+        Accessible later via ``cls.get_context(request)`` from views.
+        """
+        return {}
+
+    # ── CLASS UTILITIES (call from views) ────────────────────────────────
+
+    @classmethod
+    def invalidate(cls, request):
+        """
+        Clear cached gate state, forcing a re-check on the next request.
+
+        Call this from views when the underlying condition changes
+        (e.g. user just accepted terms, completed an onboarding step).
+        """
+        prefix = f'_gate_{cls.gate_id or cls.__name__.lower()}'
+        for suffix in ('_at', '_result', '_context'):
+            request.session.pop(f'{prefix}{suffix}', None)
+
+    @classmethod
+    def get_context(cls, request) -> dict:
+        """Read the cached rejection context from the session."""
+        prefix = f'_gate_{cls.gate_id or cls.__name__.lower()}'
+        return request.session.get(f'{prefix}_context', {})
+
+    # ── INTERNALS ────────────────────────────────────────────────────────
+
+    @property
+    def _cache_prefix(self) -> str:
+        return f'_gate_{self.gate_id}'
+
+    def _get_cache_ttl(self) -> int:
+        if self.cache_ttl_setting:
+            return getattr(settings, self.cache_ttl_setting, self.default_cache_ttl)
+        return self.default_cache_ttl
+
+    def _is_exempt(self, request) -> bool:
+        return any(request.path.startswith(p) for p in self.exempt_paths)

session_armor/session.py

@@ -0,0 +1,263 @@
+"""
+SessionSecurityMiddleware — defense-grade session protection.
+
+Enforces:
+- Client fingerprint binding (IP + User-Agent hash)
+- Absolute session timeout (force re-auth after N hours)
+- Idle session timeout (force re-auth after inactivity)
+- JWT claim drift detection (critical claims must not change mid-session)
+
+All behavior is customizable via hooks so different auth systems
+(Auth0, WorkOS, Django allauth, etc.) can plug in seamlessly.
+
+References:
+    NIST SP 800-53 AC-12 (Session Termination)
+    NIST SP 800-53 SC-23 (Session Authenticity)
+    OWASP Session Management Cheat Sheet
+
+Hooks (override in subclass)::
+
+    get_fingerprint_parts(request) → list[str]
+    get_critical_claims(user)      → list[str]
+    get_login_url(request)         → str
+    on_violation(request, reason)  → HttpResponse | None
+    on_timeout(request, kind)      → None
+    on_session_init(request)       → None
+
+Usage::
+
+    # Generic (works with any Django auth)
+    MIDDLEWARE = [
+        ...
+        'session_armor.session.SessionSecurityMiddleware',
+        ...
+    ]
+
+    # Customized
+    class MySessionSecurity(SessionSecurityMiddleware):
+        def get_critical_claims(self, user):
+            return [user.sub, user.tenant_id]
+
+        def get_login_url(self, request):
+            return reverse('my_login')
+"""
+
+import hashlib
+import logging
+import time
+
+from django.conf import settings
+from django.shortcuts import redirect
+
+from .utils import get_client_ip, is_authenticated
+
+logger = logging.getLogger('session_armor.session')
+
+
+class SessionSecurityMiddleware:
+    """
+    Session binding, timeouts, and anomaly detection.
+
+    Must run **after** your authentication middleware (needs ``request.user``).
+
+    Settings (read from Django settings with secure defaults):
+
+        SESSION_ABSOLUTE_TIMEOUT    int — seconds (default 28800 / 8 h)
+        SESSION_IDLE_TIMEOUT        int — seconds (default 1800 / 30 min)
+        SESSION_BIND_IP             bool (default True)
+        SESSION_BIND_USER_AGENT     bool (default True)
+        SESSION_DETECT_CLAIM_DRIFT  bool (default True)
+
+    Session keys (all prefixed ``_ss_``):
+
+        _ss_fingerprint   Client fingerprint hash
+        _ss_auth_time     Absolute session start (epoch)
+        _ss_last_active   Last activity timestamp (epoch)
+        _ss_claims_hash   Hash of critical JWT claims
+    """
+
+    # ── Configuration ────────────────────────────────────────────────────
+    exempt_paths: tuple[str, ...] = ()
+
+    # ── Django middleware protocol ────────────────────────────────────────
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if self._is_exempt(request):
+            return self.get_response(request)
+
+        if not is_authenticated(request):
+            return self.get_response(request)
+
+        now = time.time()
+        user = request.user
+
+        # ── Binding check ──
+        violation = self._check_binding(request)
+        if violation:
+            logger.warning(
+                "Session binding violation (%s) for user %s, path=%s",
+                violation, getattr(user, 'sub', '?'), request.path,
+            )
+            return self._terminate(request, reason=violation)
+
+        # ── Absolute timeout ──
+        auth_time = request.session.get('_ss_auth_time')
+        timeout = getattr(settings, 'SESSION_ABSOLUTE_TIMEOUT', 28800)
+        if auth_time and (now - auth_time) > timeout:
+            logger.info("Absolute timeout for user %s", getattr(user, 'sub', '?'))
+            self.on_timeout(request, 'absolute')
+            return self._terminate(request, reason='absolute_timeout')
+
+        # ── Idle timeout ──
+        last_active = request.session.get('_ss_last_active')
+        idle_timeout = getattr(settings, 'SESSION_IDLE_TIMEOUT', 1800)
+        if last_active and (now - last_active) > idle_timeout:
+            logger.info("Idle timeout for user %s", getattr(user, 'sub', '?'))
+            self.on_timeout(request, 'idle')
+            return self._terminate(request, reason='idle_timeout')
+
+        # ── Claim drift ──
+        if getattr(settings, 'SESSION_DETECT_CLAIM_DRIFT', True):
+            drift = self._check_claim_drift(request)
+            if drift:
+                logger.warning(
+                    "JWT claim drift for user %s: %s",
+                    getattr(user, 'sub', '?'), drift,
+                )
+                return self._terminate(request, reason='claim_drift')
+
+        # ── Initialize on first authenticated request ──
+        if '_ss_auth_time' not in request.session:
+            self._init_session(request, now)
+            self.on_session_init(request)
+
+        # ── Update last-active ──
+        request.session['_ss_last_active'] = now
+
+        return self.get_response(request)
+
+    # ── HOOKS (override in subclass) ─────────────────────────────────────
+
+    def get_fingerprint_parts(self, request) -> list[str]:
+        """
+        Return the parts that make up the client fingerprint.
+
+        Override to add custom binding factors (client certs, device ID, etc.).
+        Each part is joined with ``|`` and SHA-256 hashed.
+        """
+        parts = []
+        if getattr(settings, 'SESSION_BIND_IP', True):
+            parts.append(get_client_ip(request))
+        if getattr(settings, 'SESSION_BIND_USER_AGENT', True):
+            parts.append(request.META.get('HTTP_USER_AGENT', ''))
+        return parts
+
+    def get_critical_claims(self, user) -> list[str]:
+        """
+        Return claim values that must not change mid-session.
+
+        Override to match your auth system's user model. The values are
+        hashed together; if the hash changes, the session is terminated.
+
+        Default extracts ``sub`` and ``email`` (works for most OIDC setups).
+        """
+        return [
+            getattr(user, 'sub', '') or '',
+            getattr(user, 'email', '') or '',
+        ]
+
+    def get_login_url(self, request) -> str:
+        """
+        Return the URL to redirect to when a session is terminated.
+
+        Override to implement platform-specific or tenant-specific routing.
+        Default uses Django's ``LOGIN_URL`` setting.
+        """
+        return getattr(settings, 'LOGIN_URL', '/')
+
+    def on_violation(self, request, reason: str):
+        """
+        Called on security violation, before session flush.
+
+        Return an ``HttpResponse`` to override the default redirect.
+        Return ``None`` to use the default behavior (flush → login redirect).
+        """
+        return None
+
+    def on_timeout(self, request, kind: str) -> None:
+        """
+        Called on absolute or idle timeout, before session flush.
+
+        ``kind`` is ``'absolute'`` or ``'idle'``.
+        Use for logging, metrics, or pre-flush cleanup.
+        """
+        pass
+
+    def on_session_init(self, request) -> None:
+        """
+        Called when session security metadata is initialized for a new session.
+
+        Use to set additional session values at auth time.
+        """
+        pass
+
+    # ── INTERNALS ────────────────────────────────────────────────────────
+
+    def _check_binding(self, request) -> str | None:
+        stored = request.session.get('_ss_fingerprint')
+        if not stored:
+            return None  # First request — will be initialized
+
+        parts = self.get_fingerprint_parts(request)
+        current = hashlib.sha256('|'.join(parts).encode('utf-8')).hexdigest()
+        if current != stored:
+            return 'fingerprint_mismatch'
+        return None
+
+    def _check_claim_drift(self, request) -> str | None:
+        stored = request.session.get('_ss_claims_hash')
+        if not stored:
+            return None
+
+        current = self._hash_claims(request.user)
+        if current != stored:
+            return 'critical_claims_changed'
+        return None
+
+    def _hash_claims(self, user) -> str:
+        parts = self.get_critical_claims(user)
+        raw = '|'.join(str(p) for p in parts)
+        return hashlib.sha256(raw.encode('utf-8')).hexdigest()
+
+    def _init_session(self, request, now: float):
+        # Rotate session ID to prevent fixation attacks (OWASP A7)
+        request.session.cycle_key()
+
+        parts = self.get_fingerprint_parts(request)
+        request.session['_ss_fingerprint'] = hashlib.sha256(
+            '|'.join(parts).encode('utf-8')
+        ).hexdigest()
+        request.session['_ss_auth_time'] = now
+        request.session['_ss_last_active'] = now
+        request.session['_ss_claims_hash'] = self._hash_claims(request.user)
+        logger.debug(
+            "Session security initialized for user %s",
+            getattr(request.user, 'sub', '?'),
+        )
+
+    def _terminate(self, request, reason: str):
+        # Get login URL BEFORE flushing (user info may be needed)
+        custom = self.on_violation(request, reason)
+        login_url = self.get_login_url(request)
+
+        request.session.flush()
+
+        if custom is not None:
+            return custom
+        return redirect(login_url)
+
+    def _is_exempt(self, request) -> bool:
+        return any(request.path.startswith(p) for p in self.exempt_paths)

session_armor/utils.py

@@ -0,0 +1,93 @@
+"""
+Shared utilities for SessionArmor middleware.
+"""
+
+import hashlib
+import re
+
+from django.conf import settings
+
+# Characters that can corrupt structured log parsing (newlines, ANSI escapes,
+# null bytes, control characters).
+_LOG_UNSAFE_RE = re.compile(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\x1b\[\]\r\n]')
+
+
+def hash_value(value: str, length: int = 0) -> str:
+    """SHA-256 hash of a string. Optionally truncate to ``length`` chars."""
+    h = hashlib.sha256(value.encode('utf-8')).hexdigest()
+    return h[:length] if length else h
+
+
+def get_client_ip(request) -> str:
+    """
+    Extract the originating client IP with proxy-depth awareness.
+
+    When ``SESSION_ARMOR_TRUSTED_PROXY_DEPTH`` is set in Django settings,
+    only that many rightmost ``X-Forwarded-For`` entries are trusted.
+    The client IP is the entry just before the trusted proxies.
+
+    If the header has fewer entries than the proxy depth (i.e. the request
+    didn't traverse enough proxies), we fall back to ``REMOTE_ADDR`` to
+    avoid trusting a spoofed header.
+
+    Examples with ``SESSION_ARMOR_TRUSTED_PROXY_DEPTH = 1``::
+
+        X-Forwarded-For: spoofed, real, proxy1
+        → returns "real"
+
+        X-Forwarded-For: real, proxy1
+        → returns "real"
+
+        X-Forwarded-For: spoofed_only
+        → returns REMOTE_ADDR (not enough hops)
+    """
+    depth = getattr(settings, 'SESSION_ARMOR_TRUSTED_PROXY_DEPTH', 0)
+    forwarded = request.META.get('HTTP_X_FORWARDED_FOR', '')
+
+    if not forwarded:
+        return request.META.get('REMOTE_ADDR', '')
+
+    parts = [p.strip() for p in forwarded.split(',')]
+
+    if depth and depth > 0:
+        # The client is at index -(depth + 1) from the right.
+        # If the header is shorter than depth + 1, it's spoofed — use REMOTE_ADDR.
+        client_index = len(parts) - depth - 1
+        if client_index < 0:
+            return request.META.get('REMOTE_ADDR', '')
+        return parts[client_index]
+
+    # No proxy depth configured — legacy behavior (leftmost, less safe).
+    return parts[0]
+
+
+def get_client_fingerprint(request, parts: list[str] | None = None) -> str:
+    """
+    Build a privacy-preserving fingerprint from client connection properties.
+
+    By default hashes IP + User-Agent. Pass *parts* to override.
+    """
+    if parts is None:
+        parts = [
+            get_client_ip(request),
+            request.META.get('HTTP_USER_AGENT', ''),
+        ]
+    raw = '|'.join(parts)
+    return hash_value(raw)
+
+
+def is_authenticated(request) -> bool:
+    """Check whether the request has an authenticated user."""
+    user = getattr(request, 'user', None)
+    return bool(user and getattr(user, 'is_authenticated', False))
+
+
+def sanitize_for_log(value: str, max_length: int = 200) -> str:
+    """
+    Sanitize a user-controlled string for safe inclusion in log entries.
+
+    Strips control characters, ANSI escape sequences, null bytes, and
+    truncates to ``max_length`` to prevent log injection / log flooding.
+    """
+    clean = _LOG_UNSAFE_RE.sub('', value)
+    return clean[:max_length]

sessionarmor-0.1.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+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).

sessionarmor-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+session_armor/__init__.py,sha256=7TpN2B6RmBAtkDFKFQs3q9AMq0tiywVYzBwf2mcus1w,768
+session_armor/audit.py,sha256=ZFG0O5Vlkzy7j4bP95qU9dmuLo7j-1HN5Fw1enZ9OgM,5594
+session_armor/gate.py,sha256=vWFj9pyQcdBNCnrFtgayL2R5_OBHzsHRVe8rz4yIH7Q,7677
+session_armor/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_armor/session.py,sha256=n0kXie7RTiXhRstR9ncUo_j5BJ3xnEzIsFf4TbYHN2k,9590
+session_armor/utils.py,sha256=7tRlsX-5M7bzj-7QqF6NbNvx4DHzUL2ShgqNeV82akA,3050
+sessionarmor-0.1.0.dist-info/METADATA,sha256=BIMpHqRuNyHY3Aum2uam-CEIh7rlaB8UlTX0Xz9Z8GQ,6024
+sessionarmor-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sessionarmor-0.1.0.dist-info/licenses/LICENSE,sha256=Y0CO8lj8gytK0m9xyNBIteUiW0n9A0k5tBaVXaB2beE,1068
+sessionarmor-0.1.0.dist-info/RECORD,,

sessionarmor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sessionarmor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Alex C
+
+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.