django-session-security-continued 3.0.0a1__py3-none-any.whl

django_session_security_continued-3.0.0a1.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: django-session-security-continued
+Version: 3.0.0a1
+Summary: Client and server-side session timeout enforcement with warnings for Django 4.2+.
+Author: Matt Bosworth (https://github.com/mattbo), Fabio Caritas Barrionuevo da Luz (https://github.com/luzfcb), Pēteris Caune (https://github.com/cuu508), John David Giese (https://github.com/johndgiese), Jose Antonio Martin Prieto (https://github.com/jantoniomartin), Richard Moorhead (https://github.com/autodidacticon), Jean-Michel Nirgal Vourgère (https://github.com/nirgal), Michał Pasternak (https://github.com/mpasternak), James Pic (https://github.com/jpic), Matthew Schettler (https://github.com/mschettler), Scott Sexton (https://github.com/scottsexton), Jacek Ostański (https://github.com/jacoor), Aaron Krill (https://github.com/krillr), @yscumc (https://github.com/yscumc), Marco Fucci (https://github.com/marcofucci), Andrei Coman (https://github.com/comandrei), Ali Hasan Imam (https://github.com/alihasanimam), Joel Hillacre (https://github.com/jhillacre), Peter Mack (https://github.com/pmack)
+Maintainer-email: Arrai Innovations <support@arrai.com>
+Project-URL: repository, https://github.com/arrai-innovations/django-session-security-continued
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django<5.3,>=4.2
+Dynamic: license-file
+
+# django-session-security-continued
+
+[![code style: ruff][]][ruff] [![code style: prettier][]][prettier] ![ruff status][] ![pip-audit status][]
+
+![python 3.9 status][]
+![python 3.10 status][]
+![python 3.11 status][]
+![python 3.12 status][]
+![coverage status][]
+
+<!--prettier-ignore-start-->
+<!--TOC-->
+
+- [About](#about)
+- [Requirements / Compatibility](#requirements--compatibility)
+- [Installation](#installation)
+- [Single Sign-On (SSO) Considerations](#single-sign-on-sso-considerations)
+- [Development](#development)
+- [Testing](#testing)
+  - [JavaScript coverage](#javascript-coverage)
+- [Contributing](#contributing)
+
+<!--TOC-->
+<!--prettier-ignore-end-->
+
+## About
+
+A minimal JavaScript and Django middleware app that automatically logs out users after inactivity. It tracks activity across all browser tabs, warns users before logging them out, and protects sensitive data.
+
+Built for CRMs, intranets, and similar applications, it prevents abandoned sessions from staying open when users leave their workstations. Unlike simply setting session expiry, this approach ensures users aren’t logged out while reading, reviewing data, or filling out forms; preserving their work and reducing frustration while still enforcing inactivity-based security.
+
+This fork is maintained by Arrai Innovations Inc. based on the original [`django-session-security`](https://github.com/yourlabs/django-session-security) by Yourlabs.
+
+## Requirements / Compatibility
+
+- **Django:** 4.2, 5.2
+    - `django.contrib.staticfiles`
+- **Python:** 3.9, 3.10, 3.11, 3.12
+
+## Installation
+
+```console
+# Install the package
+$ pip install django-session-security-continued
+```
+
+```python
+# settings.py
+
+INSTALLED_APPS = [
+    # Add the app
+    'session_security',
+    # ...
+]
+
+MIDDLEWARE = [
+    # Make sure this comes AFTER the authentication middleware
+    'django.contrib.auth.middleware.AuthenticationMiddleware',
+    'session_security.middleware.SessionSecurityMiddleware',
+    # ...
+]
+
+TEMPLATES = [
+    {
+        # ...
+        'OPTIONS': {
+            'context_processors': [
+                # Ensure this is present
+                'django.template.context_processors.request',
+                # ...
+            ],
+        },
+    },
+]
+
+# Optional settings (see configuration section for details)
+SESSION_SECURITY_WARN_AFTER = 540          # Warn user after 9 minutes
+SESSION_SECURITY_EXPIRE_AFTER = 600        # Log out after 10 minutes
+SESSION_SECURITY_PASSIVE_URLS = []         # URLs that won’t reset the timer
+SESSION_SECURITY_REDIRECT_TO_LOGOUT = False  # Set True for SSO setups
+SESSION_SECURITY_PING_URL = '/session_security/ping/'  # Activity endpoint
+SESSION_SECURITY_JS_PATH = 'session_security/script.js'  # Override to load custom bundles (tests/coverage)
+```
+
+```python
+# urls.py
+
+from django.urls import include, path
+
+urlpatterns = [
+    # Add this route to enable the session security endpoints
+    path('session_security/', include('session_security.urls')),
+    # ...
+]
+```
+
+```html
+<!-- base.html (or equivalent) -->
+{% load static %}
+...
+{% include "session_security/all.html" %}
+<script>
+    // optional: disable form discard confirmation dialog
+    sessionSecurity.confirmFormDiscard = undefined;
+    // optional: register custom activity
+    sessionSecurity.activity();
+</script>
+```
+
+## Single Sign-On (SSO) Considerations
+
+When using SSO, the default page reload after timeout may cause automatic re-login if the SSO session remains valid. Set `SESSION_SECURITY_REDIRECT_TO_LOGOUT = True` to explicitly end the app session by redirecting to `LOGOUT_REDIRECT_URL`. Note that this does **not** terminate the SSO provider session; configure a matching timeout on your SSO server for full coverage.
+
+## Development
+
+This project uses `uv` for managing the development environment. To set up the development environment, follow these steps:
+
+```console
+# Clone the repository
+$ git clone https://github.com/arrai-innovations/django-session-security-continued.git
+$ cd django-session-security-continued
+
+# Ensure a compatible Python (>=3.9) is installed
+
+# Install uv if not already installed
+$ pip install --user --upgrade uv
+
+# Create and sync the dev environment
+#  (default group includes dev dependencies)
+$ uv sync
+
+# (Optional) Run Git hooks setup
+$ uv run pre-commit install
+
+# Install JS tooling for the client bundle / coverage builds
+$ npm install
+```
+
+## Testing
+
+Chrome is required for the Selenium end-to-end tests (Selenium Manager will download the matching chromedriver automatically). Run the full suite with pytest:
+
+```console
+$ uv run pytest
+```
+
+If Chrome isn’t available (or you only want the fast unit tests), skip the browser suite with `uv run pytest -m "not selenium"`.
+
+Add extra breathing room to the Selenium waits (in CI) by exporting `SESSION_SECURITY_TIMEOUT_PADDING` (in seconds). For example, `SESSION_SECURITY_TIMEOUT_PADDING=5 uv run pytest -k selenium` gives each warning/expiry wait up to five additional seconds before failing.
+
+### JavaScript coverage
+
+We ship a Vite + Istanbul build that instruments the client bundle and collects coverage from the Selenium run:
+
+1. `npm run build:coverage`
+2. `SESSION_SECURITY_JS_COVERAGE=1 uv run pytest -k selenium`
+3. `npm run coverage:report` (writes reports to `coverage-js/` and `lcov.info`)
+
+The `SESSION_SECURITY_JS_COVERAGE` flag makes the Django test settings load the instrumented bundle and dumps `window.__coverage__` into `.nyc_output/` after each Selenium test.
+
+## Contributing
+
+Contributions are welcome. Please fork the repository and create a pull request with your changes. We reserve the right to review and modify your contributions before merging them into the main branch. By submitting a change you confirm that:
+
+- You wrote the code (or have the right to contribute it), and
+- You’re happy for it to be released under this project’s MIT license.
+
+[code style: ruff]: https://img.shields.io/badge/code%20style-ruff-000000.svg?style=for-the-badge
+[ruff]: https://docs.astral.sh/ruff/formatter/#style-guide
+[code style: prettier]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=for-the-badge
+[prettier]: https://github.com/prettier/prettier
+[python 3.9 status]: https://docs.arrai.dev/dssc/artifacts/main/python_3.9.svg
+[python 3.10 status]: https://docs.arrai.dev/dssc/artifacts/main/python_3.10.svg
+[python 3.11 status]: https://docs.arrai.dev/dssc/artifacts/main/python_3.11.svg
+[python 3.12 status]: https://docs.arrai.dev/dssc/artifacts/main/python_3.12.svg
+[coverage status]: https://docs.arrai.dev/dssc/artifacts/main/python_3.9.coverage.svg
+[ruff status]: https://docs.arrai.dev/dssc/artifacts/main/ruff.svg
+[pipenv]: https://github.com/pypa/pipenv
+[pip-audit status]: https://docs.arrai.dev/dssc/artifacts/main/pip-audit.svg

django_session_security_continued-3.0.0a1.dist-info/RECORD

@@ -0,0 +1,25 @@
+django_session_security_continued-3.0.0a1.dist-info/licenses/LICENSE,sha256=sTEwnChiEDBXv8ZDFVYDAhXfIA1wjpwuIhTVDhGLssw,1107
+session_security/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_security/middleware.py,sha256=matyK1lCSv5ZeIRWoxj-yThKNDMHRUM1Xf929pWTVmE,4008
+session_security/models.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_security/settings.py,sha256=pIxklXg3F1uyvsb0dl7ArQ0vquWLCie0CC5vy_fICas,2242
+session_security/urls.py,sha256=QK_diUsqjyQkU6UQpUW9SV_3kpf0223glrtnM7jft7M,510
+session_security/utils.py,sha256=d19NpP7f5kEdrVdZIae95c-Oeuw9gk0m4pATzuzlw3w,466
+session_security/views.py,sha256=ktla3T5Pk8qajdVTIhatWKprm10iIjM-Ek495APDBLs,879
+session_security/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_security/templatetags/session_security_tags.py,sha256=Vhrxe0ThWpEbQZUlqxKl9XXOx8HhF96EoBmVk5hxhrc,627
+session_security/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_security/tests/conftest.py,sha256=MFGSYiQ_9ViCKgr0BL0x9cB4eJR29m1XjMkoY1J6SeE,4756
+session_security/tests/test_base.py,sha256=bvqz385wyyBQNhrpeTyUTY0fWosLB9wOhPOBrt0tOBM,1775
+session_security/tests/test_middleware.py,sha256=iLFlXXfoBwUBNUJPhyRvPR657y-MORj1nyjh3GXFNPc,3612
+session_security/tests/test_script.py,sha256=y-gNGt6vLgsjfvqIk7GsuS5RijoSVo50kzKpKkUXcJs,2707
+session_security/tests/test_templates.py,sha256=qXukArdCZvvthGLyHZzise9xV6Q8kFx-eUy8TCxsYXU,471
+session_security/tests/test_views.py,sha256=97Ssf4nXGj0OIGc-fFf3_LdjC3k9yFMr6QD9CRsTrLc,1183
+session_security/tests/project/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+session_security/tests/project/settings.py,sha256=BAN820rroRvYMKQPtTYvqkdjmy9ce5fznFWelrBG58c,2999
+session_security/tests/project/urls.py,sha256=wFMGt1wQLCdoaAsJRltFypR473RJnkxbqReWh0FMFWE,1136
+session_security/tests/project/wsgi.py,sha256=VFz8yKLbSm4-C5ejuLJ_ZuPoKZ1WP17WJVMx2R17Z8M,426
+django_session_security_continued-3.0.0a1.dist-info/METADATA,sha256=jSCRkYxzDg-MpeqLKPxe23zGuccNJg4oBE1LUZsr5Kg,8935
+django_session_security_continued-3.0.0a1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+django_session_security_continued-3.0.0a1.dist-info/top_level.txt,sha256=sUgnA1DNG4V434n9luYoNsltkfMgkCnI6GBZV6oKWJI,17
+django_session_security_continued-3.0.0a1.dist-info/RECORD,,

django_session_security_continued-3.0.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_session_security_continued-3.0.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2018 YourLabs
+Copyright (c) 2025 Arrai Innovations Inc.
+
+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.

django_session_security_continued-3.0.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+session_security

session_security/middleware.py

@@ -0,0 +1,119 @@
+"""
+SessionSecurityMiddleware is the heart of the security that this application
+attemps to provide.
+
+To install this middleware, add to ``settings.MIDDLEWARE``::
+
+    'session_security.middleware.SessionSecurityMiddleware'
+
+Place it after authentication middleware.
+"""
+
+from datetime import datetime
+from datetime import timedelta
+
+from django.conf import settings as django_settings
+from django.urls import Resolver404
+from django.urls import resolve
+from django.urls import reverse
+from django.utils.deprecation import MiddlewareMixin
+
+from session_security.utils import get_last_activity
+from session_security.utils import set_last_activity
+
+
+class SessionSecurityMiddleware(MiddlewareMixin):
+    """
+    In charge of maintaining the real 'last activity' time, and log out the
+    user if appropriate.
+    """
+
+    def is_passive_request(self, request):
+        """Should we skip activity update on this URL/View."""
+        from session_security.settings import PASSIVE_URL_NAMES as DEFAULT_PASSIVE_URL_NAMES
+        from session_security.settings import PASSIVE_URLS as DEFAULT_PASSIVE_URLS
+
+        passive_urls = getattr(
+            django_settings,
+            "SESSION_SECURITY_PASSIVE_URLS",
+            DEFAULT_PASSIVE_URLS,
+        )
+        passive_url_names = getattr(
+            django_settings,
+            "SESSION_SECURITY_PASSIVE_URL_NAMES",
+            DEFAULT_PASSIVE_URL_NAMES,
+        )
+
+        if request.path in passive_urls:
+            return True
+
+        try:
+            match = resolve(request.path)
+            # TODO: check namespaces too
+            if match.url_name in passive_url_names:
+                return True
+        except Resolver404:
+            pass
+
+        return False
+
+    def get_expire_seconds(self, request):
+        """Return time (in seconds) before the user should be logged out."""
+        from session_security.settings import EXPIRE_AFTER
+
+        return EXPIRE_AFTER
+
+    def process_request(self, request):
+        """Update last activity time or logout."""
+        if not self.is_authenticated(request):
+            return
+
+        now = datetime.now()
+        if "_session_security" not in request.session:
+            set_last_activity(request.session, now)
+            return
+
+        delta = now - get_last_activity(request.session)
+        expire_seconds = self.get_expire_seconds(request)
+        if delta >= timedelta(seconds=expire_seconds):
+            self.do_logout(request)
+        elif request.path == reverse("session_security_ping") and "idleFor" in request.GET:
+            self.update_last_activity(request, now)
+        elif not self.is_passive_request(request):
+            set_last_activity(request.session, now)
+
+    def update_last_activity(self, request, now):
+        """
+        If ``request.GET['idleFor']`` is set, check if it refers to a more
+        recent activity than ``request.session['_session_security']`` and
+        update it in this case.
+        """
+        last_activity = get_last_activity(request.session)
+        server_idle_for = (now - last_activity).seconds
+
+        # Gracefully ignore non-integer values
+        try:
+            client_idle_for = int(request.GET["idleFor"])
+        except ValueError:
+            return
+
+        # Disallow negative values, causes problems with delta calculation
+        if client_idle_for < 0:
+            client_idle_for = 0
+
+        if client_idle_for < server_idle_for:
+            # Client has more recent activity than we have in the session
+            last_activity = now - timedelta(seconds=client_idle_for)
+
+        # Update the session
+        set_last_activity(request.session, last_activity)
+
+    def is_authenticated(self, request):
+        """Provide a hook for subclasses that want custom auth logic."""
+        return request.user.is_authenticated
+
+    def do_logout(self, request):
+        """Provide a hook for subclasses that want a custom logout implementation."""
+        from django.contrib.auth import logout
+
+        logout(request)

session_security/settings.py

@@ -0,0 +1,53 @@
+"""
+Settings for django-session-security.
+
+WARN_AFTER
+    Time (in seconds) before the user should be warned that is session will
+    expire because of inactivity. Default 540. Overridable in
+    ``settings.SESSION_SECURITY_WARN_AFTER``.
+
+EXPIRE_AFTER
+    Time (in seconds) before the user should be logged out if inactive. Default
+    is 600. Overridable in ``settings.SESSION_SECURITY_EXPIRE_AFTER``.
+
+PASSIVE_URLS
+    List of urls that should be ignored by the middleware. For example the ping
+    ajax request of session_security is made without user intervention, as such
+    it should not be used to update the user's last activity datetime.
+    Overridable in ``settings.SESSION_SECURITY_PASSIVE_URLS``.
+
+PASSIVE_URL_NAMES
+    Same as PASSIVE_URLS, but takes Django URL names instead of a path. This
+    is useful in case path names change, or contain parameterized values, and
+    thus cannot be described statically. NOTE: currently namespaces are not
+    handled. Overridable in ``settings.SESSION_SECURITY_PASSIVE_URL_NAMES``.
+
+SESSION_SECURITY_INSECURE
+    Set this to True in your settings if you want the project to run without
+    having to set SESSION_EXPIRE_AT_BROWSER_CLOSE=True, which you should
+    because it makes no sense to use this app with
+    ``SESSION_EXPIRE_AT_BROWSER_CLOSE`` to False.
+
+SESSION_SECURITY_JS_PATH
+    Override the static path for the client bundle. Defaults to
+    ``session_security/script.js``; useful for loading instrumented builds in tests.
+"""
+
+from django.conf import settings
+
+
+__all__ = ["EXPIRE_AFTER", "PASSIVE_URLS", "WARN_AFTER"]
+
+# WARNING:  These values cannot be reconfigured by tests
+EXPIRE_AFTER = getattr(settings, "SESSION_SECURITY_EXPIRE_AFTER", 600)
+
+WARN_AFTER = getattr(settings, "SESSION_SECURITY_WARN_AFTER", 540)
+
+PASSIVE_URLS = getattr(settings, "SESSION_SECURITY_PASSIVE_URLS", [])
+PASSIVE_URL_NAMES = getattr(settings, "SESSION_SECURITY_PASSIVE_URL_NAMES", [])
+
+expire_at_browser_close = getattr(settings, "SESSION_EXPIRE_AT_BROWSER_CLOSE", False)
+force_insecurity = getattr(settings, "SESSION_SECURITY_INSECURE", False)
+
+if not (expire_at_browser_close or force_insecurity):
+    raise Exception("Enable SESSION_EXPIRE_AT_BROWSER_CLOSE or SESSION_SECURITY_INSECURE")

session_security/templatetags/session_security_tags.py

@@ -0,0 +1,29 @@
+from django import template
+from django.conf import settings
+
+from session_security.settings import EXPIRE_AFTER
+from session_security.settings import WARN_AFTER
+
+
+register = template.Library()
+
+
+@register.filter
+def expire_after(request):
+    return EXPIRE_AFTER
+
+
+@register.filter
+def warn_after(request):
+    return WARN_AFTER
+
+
+@register.filter
+def redirect_to_logout(request):
+    redirect = getattr(settings, "SESSION_SECURITY_REDIRECT_TO_LOGOUT", False)
+    return redirect
+
+
+@register.simple_tag
+def session_security_script_path():
+    return getattr(settings, "SESSION_SECURITY_JS_PATH", "session_security/script.js")

session_security/tests/conftest.py

@@ -0,0 +1,149 @@
+import json
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from datetime import timedelta
+from pathlib import Path
+
+import pytest
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options as ChromeOptions
+from selenium.webdriver.common.by import By
+
+
+@dataclass
+class ActivityWindow:
+    min_warn_after: float
+    max_warn_after: float
+    min_expire_after: float
+    max_expire_after: float
+
+
+@pytest.fixture
+def admin_user(db, django_user_model):
+    return django_user_model.objects.create_superuser(
+        username="test",
+        email="test@example.com",
+        password="test",
+    )
+
+
+@pytest.fixture
+def user(db, django_user_model):
+    return django_user_model.objects.create_user(
+        username="regular",
+        email="user@example.com",
+        password="test",
+    )
+
+
+@pytest.fixture
+def authenticated_client(client, admin_user):
+    assert client.login(username="test", password="test")
+    return client
+
+
+TIMEOUT_PADDING_ENV = "SESSION_SECURITY_TIMEOUT_PADDING"
+
+
+def _timeout_padding_seconds() -> float:
+    raw_value = os.environ.get(TIMEOUT_PADDING_ENV)
+    if not raw_value:
+        return 0.0
+    try:
+        padding = float(raw_value)
+    except ValueError as exc:
+        raise RuntimeError(
+            f"{TIMEOUT_PADDING_ENV} must be a number representing seconds of extra wait time; got {raw_value!r}."
+        ) from exc
+    return max(0.0, padding)
+
+
+@pytest.fixture
+def activity_window(settings):
+    expire_after = settings.SESSION_SECURITY_EXPIRE_AFTER
+    warn_after = settings.SESSION_SECURITY_WARN_AFTER
+    padding = _timeout_padding_seconds()
+    warn_margin = 0.5  # always keep at least this much headroom before expiry
+    max_warn_cap = max(warn_after, expire_after - warn_margin)
+    max_warn_after = min(expire_after * 0.9 + padding, max_warn_cap)
+    return ActivityWindow(
+        min_warn_after=warn_after,
+        max_warn_after=max_warn_after,
+        min_expire_after=expire_after,
+        max_expire_after=expire_after * 1.5 + padding,
+    )
+
+
+@pytest.fixture
+def frozen_time(monkeypatch):
+    class FrozenDateTime:
+        def __init__(self):
+            self._current = datetime.now()
+
+        def now(self):
+            return self._current
+
+        def advance(self, seconds: float):
+            self._current += timedelta(seconds=seconds)
+
+    freezer = FrozenDateTime()
+    monkeypatch.setattr("session_security.middleware.datetime", freezer)
+    monkeypatch.setattr("session_security.views.datetime", freezer)
+    return freezer
+
+
+JS_COVERAGE_ENV = "SESSION_SECURITY_JS_COVERAGE"
+JS_COVERAGE_STATIC_PATH = "session_security/coverage/script.js"
+REPO_ROOT = Path(__file__).resolve().parents[2]
+NYC_DIR = Path(".nyc_output")
+
+
+@pytest.fixture
+def selenium_browser(live_server, admin_user, settings):
+    use_js_coverage = bool(os.environ.get(JS_COVERAGE_ENV))
+    if use_js_coverage:
+        settings.SESSION_SECURITY_JS_PATH = JS_COVERAGE_STATIC_PATH
+        coverage_bundle = REPO_ROOT / "session_security" / "static" / "session_security" / "coverage" / "script.js"
+        if not coverage_bundle.exists():
+            raise RuntimeError(
+                "Instrumented session security bundle not found. "
+                "Run `npm install` (once) and `npm run build:coverage` before running Selenium coverage tests."
+            )
+
+    options = ChromeOptions()
+    options.add_argument("--headless=new")
+    options.add_argument("--disable-gpu")
+    options.add_argument("--no-sandbox")
+    options.add_argument("--disable-dev-shm-usage")
+
+    driver = webdriver.Chrome(options=options)
+    driver.get(f"{live_server.url}/admin/")
+    driver.find_element(By.NAME, "username").send_keys("test")
+    driver.find_element(By.NAME, "password").send_keys("test")
+    driver.find_element(By.XPATH, '//input[@value="Log in"]').click()
+    driver.execute_script('window.open("/admin/", "other")')
+
+    if use_js_coverage:
+        script_sources = driver.execute_script(
+            "return Array.from(document.getElementsByTagName('script')).map(s => s.src);"
+        )
+        if not any("session_security/coverage/script.js" in src for src in script_sources):
+            raise RuntimeError(
+                "Instrumented session security script was not loaded; check SESSION_SECURITY_JS_PATH configuration."
+            )
+
+    yield driver
+
+    if use_js_coverage:
+        NYC_DIR.mkdir(exist_ok=True)
+        try:
+            coverage_data = driver.execute_script("return window.__coverage__ || null;")
+        except Exception:
+            coverage_data = None
+        if coverage_data:
+            filename = f"{uuid.uuid4().hex}.json"
+            (NYC_DIR / filename).write_text(json.dumps(coverage_data))
+
+    driver.quit()

session_security/tests/project/settings.py

@@ -0,0 +1,112 @@
+"""
+Django settings for project project.
+
+Generated by 'django-admin startproject' using Django 1.8.3.dev20150604012123.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/dev/topics/settings/
+
+For the full list of settings and their values, see
+https://docs.djangoproject.com/en/dev/ref/settings/
+"""
+
+# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
+import os
+
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+# Quick-start development settings - unsuitable for production
+# See https://docs.djangoproject.com/en/dev/howto/deployment/checklist/
+
+# SECURITY WARNING: keep the secret key used in production secret!
+SECRET_KEY = "#vhyi-*846#q09+him)ogenb#j7^3(w5($c8c1@)sy781(!8fm"
+
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = True
+
+ALLOWED_HOSTS = []
+
+
+# Application definition
+
+INSTALLED_APPS = (
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "session_security",
+)
+MIDDLEWARE = (
+    "django.middleware.common.CommonMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "session_security.middleware.SessionSecurityMiddleware",
+    # Uncomment the next line for simple clickjacking protection:
+    # 'django.middleware.clickjacking.XFrameOptionsMiddleware',
+)
+
+ROOT_URLCONF = "session_security.tests.project.urls"
+
+TEMPLATE_DIRS = [os.path.join(BASE_DIR, "templates"), "templates"]
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": TEMPLATE_DIRS,
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.debug",
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ]
+        },
+    },
+]
+
+STATICFILES_DIRS = (os.path.join(BASE_DIR, "static"),)
+
+WSGI_APPLICATION = "session_security.tests.project.wsgi.application"
+
+
+# Database
+# https://docs.djangoproject.com/en/dev/ref/settings/#databases
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": os.path.join(BASE_DIR, "db.sqlite3"),
+    }
+}
+
+
+# Internationalization
+# https://docs.djangoproject.com/en/dev/topics/i18n/
+
+LANGUAGE_CODE = "en-us"
+
+TIME_ZONE = "UTC"
+
+USE_I18N = True
+
+USE_L10N = True
+
+USE_TZ = True
+
+
+# Static files (CSS, JavaScript, Images)
+# https://docs.djangoproject.com/en/dev/howto/static-files/
+
+STATIC_URL = "/static/"
+
+SESSION_SECURITY_EXPIRE_AFTER = 10
+SESSION_SECURITY_WARN_AFTER = 5
+SESSION_EXPIRE_AT_BROWSER_CLOSE = True
+SESSION_SECURITY_PASSIVE_URL_NAMES = ["ignore"]

session_security/tests/project/urls.py

@@ -0,0 +1,33 @@
+import time
+
+from django.contrib import admin
+from django.contrib.auth.decorators import login_required
+from django.urls import include
+from django.urls import path
+from django.views import generic
+
+
+class SleepView(generic.TemplateView):
+    def get(self, request, *args, **kwargs):
+        time.sleep(int(request.GET.get("seconds", 0)))
+        return super().get(request, *args, **kwargs)
+
+
+urlpatterns = [
+    path("", generic.TemplateView.as_view(template_name="home.html")),
+    path("sleep/", login_required(SleepView.as_view(template_name="home.html")), name="sleep"),
+    path("admin/", admin.site.urls),
+    path("auth/", include("django.contrib.auth.urls")),
+    path("session_security/", include("session_security.urls")),
+    path("ignore/", login_required(generic.TemplateView.as_view(template_name="home.html")), name="ignore"),
+    path(
+        "passive/",
+        login_required(generic.TemplateView.as_view(template_name="home.html")),
+        name="passive",
+    ),
+    path(
+        "template/",
+        login_required(generic.TemplateView.as_view(template_name="template.html")),
+        name="template",
+    ),
+]

session_security/tests/project/wsgi.py

@@ -0,0 +1,20 @@
+"""
+WSGI config for project project.
+
+It exposes the WSGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/
+"""
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+
+os.environ.setdefault(
+    "DJANGO_SETTINGS_MODULE",
+    "session_security.tests.project.settings",
+)
+
+application = get_wsgi_application()

session_security/tests/test_base.py

@@ -0,0 +1,50 @@
+import os
+
+from django.contrib.staticfiles.testing import StaticLiveServerTestCase
+from django.test import LiveServerTestCase
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options as ChromeOptions
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+
+from session_security.settings import EXPIRE_AFTER
+from session_security.settings import WARN_AFTER
+
+
+WAIT_TIME = 5 if not os.environ.get("CI", False) else 30
+
+
+class SettingsMixin:
+    def setUp(self):
+        # Give some time for selenium lag
+        self.min_warn_after = WARN_AFTER
+        self.max_warn_after = EXPIRE_AFTER * 0.9
+        self.min_expire_after = EXPIRE_AFTER
+        self.max_expire_after = EXPIRE_AFTER * 1.5
+        super().setUp()
+
+
+class BaseLiveServerTestCase(SettingsMixin, StaticLiveServerTestCase, LiveServerTestCase):
+    fixtures = ["session_security_test_user"]
+
+    def setUp(self):
+        super().setUp()
+        options = ChromeOptions()
+        options.add_argument("--headless=new")
+        options.add_argument("--disable-gpu")
+        options.add_argument("--no-sandbox")
+        options.add_argument("--disable-dev-shm-usage")
+        self.sel = webdriver.Chrome(options=options)
+        self.sel.get(f"{self.live_server_url}/admin/")
+        self.sel.find_element(By.NAME, "username").send_keys("test")
+        self.sel.find_element(By.NAME, "password").send_keys("test")
+        self.sel.find_element(By.XPATH, '//input[@value="Log in"]').click()
+        self.sel.execute_script('window.open("/admin/", "other")')
+
+    def press_space(self):
+        body = self.sel.find_element(By.TAG_NAME, "body")
+        body.send_keys(Keys.SPACE)
+
+    def tearDown(self):
+        self.sel.quit()
+        super().tearDown()

session_security/tests/test_middleware.py

@@ -0,0 +1,87 @@
+from datetime import datetime
+from datetime import timedelta
+
+import pytest
+from django.test import override_settings
+
+from session_security.utils import get_last_activity
+from session_security.utils import set_last_activity
+
+
+pytestmark = pytest.mark.django_db
+
+
+def test_auto_logout(authenticated_client, activity_window, frozen_time):
+    authenticated_client.get("/admin/")
+    assert "_auth_user_id" in authenticated_client.session
+    frozen_time.advance(activity_window.max_expire_after)
+    authenticated_client.get("/admin/")
+    assert "_auth_user_id" not in authenticated_client.session
+
+
+def test_last_activity_in_future(authenticated_client, activity_window):
+    now = datetime.now()
+    future = now + timedelta(seconds=activity_window.max_expire_after * 2)
+    set_last_activity(authenticated_client.session, future)
+    authenticated_client.get("/admin/")
+    assert "_auth_user_id" in authenticated_client.session
+
+
+def test_non_javascript_browse_no_logout(authenticated_client, activity_window, frozen_time):
+    authenticated_client.get("/admin/")
+    frozen_time.advance(activity_window.max_warn_after)
+    authenticated_client.get("/admin/")
+    assert "_auth_user_id" in authenticated_client.session
+    frozen_time.advance(activity_window.min_warn_after)
+    authenticated_client.get("/admin/")
+    assert "_auth_user_id" in authenticated_client.session
+
+
+def test_javascript_activity_no_logout(authenticated_client, activity_window, frozen_time):
+    authenticated_client.get("/admin/")
+    frozen_time.advance(activity_window.max_warn_after)
+    authenticated_client.get("/session_security/ping/?idleFor=1")
+    assert "_auth_user_id" in authenticated_client.session
+    frozen_time.advance(activity_window.min_warn_after)
+    authenticated_client.get("/admin/")
+    assert "_auth_user_id" in authenticated_client.session
+
+
+def test_url_names(authenticated_client, activity_window, frozen_time):
+    authenticated_client.get("/admin/")
+    activity1 = get_last_activity(authenticated_client.session)
+    frozen_time.advance(min(2, activity_window.min_warn_after))
+    authenticated_client.get("/admin/")
+    activity2 = get_last_activity(authenticated_client.session)
+    assert activity2 > activity1
+    frozen_time.advance(min(2, activity_window.min_warn_after))
+    authenticated_client.get("/ignore/")
+    activity3 = get_last_activity(authenticated_client.session)
+    assert activity2 == activity3
+
+
+@override_settings(SESSION_SECURITY_PASSIVE_URLS=["/passive/"])
+def test_passive_urls(authenticated_client, activity_window, frozen_time):
+    authenticated_client.get("/admin/")
+    activity1 = get_last_activity(authenticated_client.session)
+    frozen_time.advance(min(2, activity_window.min_warn_after))
+    authenticated_client.get("/passive/")
+    activity2 = get_last_activity(authenticated_client.session)
+    assert activity1 == activity2
+
+
+def test_idle_for_non_integer(authenticated_client):
+    authenticated_client.get("/admin/")
+    activity1 = get_last_activity(authenticated_client.session)
+    authenticated_client.get("/session_security/ping/?idleFor=not-a-number")
+    activity2 = get_last_activity(authenticated_client.session)
+    assert activity1 == activity2
+
+
+def test_idle_for_negative(authenticated_client):
+    authenticated_client.get("/admin/")
+    activity1 = get_last_activity(authenticated_client.session)
+    authenticated_client.get("/session_security/ping/?idleFor=-5")
+    activity2 = get_last_activity(authenticated_client.session)
+    # Negative values are coerced to zero, so activity should stay unchanged.
+    assert activity1 == activity2

session_security/tests/test_script.py

@@ -0,0 +1,77 @@
+import datetime
+import time
+
+import pytest
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+from selenium.webdriver.support import expected_conditions
+from selenium.webdriver.support.ui import WebDriverWait
+
+
+pytestmark = [pytest.mark.django_db, pytest.mark.selenium]
+
+
+def _press_space(driver):
+    driver.find_element(By.TAG_NAME, "body").send_keys(Keys.SPACE)
+
+
+def _iterate_windows(driver):
+    for handle in driver.window_handles:
+        driver.switch_to.window(handle)
+        yield
+
+
+def test_warning_shows_and_session_expires(selenium_browser, activity_window):
+    start = datetime.datetime.now()
+
+    for _ in _iterate_windows(selenium_browser):
+        warning = WebDriverWait(selenium_browser, activity_window.max_warn_after).until(
+            expected_conditions.visibility_of_element_located((By.ID, "session_security_warning"))
+        )
+        assert warning.is_displayed()
+
+    delta = datetime.datetime.now() - start
+    assert delta.seconds >= activity_window.min_warn_after
+    assert delta.seconds <= activity_window.max_warn_after
+
+    for _ in _iterate_windows(selenium_browser):
+        password_field = WebDriverWait(selenium_browser, activity_window.max_expire_after).until(
+            expected_conditions.visibility_of_element_located((By.ID, "id_password"))
+        )
+        assert password_field.is_displayed()
+        delta = datetime.datetime.now() - start
+        assert delta.seconds >= activity_window.min_expire_after
+        assert delta.seconds <= activity_window.max_expire_after
+
+
+def test_activity_hides_warning(selenium_browser, activity_window):
+    time.sleep(activity_window.min_warn_after * 0.7)
+    WebDriverWait(selenium_browser, activity_window.max_warn_after).until(
+        expected_conditions.visibility_of_element_located((By.ID, "session_security_warning"))
+    )
+
+    _press_space(selenium_browser)
+
+    for _ in _iterate_windows(selenium_browser):
+        pass
+
+    assert WebDriverWait(selenium_browser, 20).until(
+        expected_conditions.invisibility_of_element_located((By.ID, "session_security_warning"))
+    )
+
+
+def test_activity_prevents_warning(selenium_browser, activity_window):
+    time.sleep(activity_window.min_warn_after * 0.7)
+    _press_space(selenium_browser)
+    start = datetime.datetime.now()
+
+    warning = WebDriverWait(selenium_browser, activity_window.max_warn_after).until(
+        expected_conditions.visibility_of_element_located((By.ID, "session_security_warning"))
+    )
+    assert warning.is_displayed()
+
+    for _ in _iterate_windows(selenium_browser):
+        pass
+
+    delta = datetime.datetime.now() - start
+    assert delta.seconds >= activity_window.min_warn_after

session_security/tests/test_templates.py

@@ -0,0 +1,17 @@
+import pytest
+
+
+pytestmark = pytest.mark.django_db
+
+
+def test_default_template_has_no_return_to_url(client, user):
+    client.force_login(user)
+    response = client.get("/template/")
+    assert b"returnToUrl" not in response.content
+
+
+def test_setting_enables_return_to_url(client, user, settings):
+    client.force_login(user)
+    settings.SESSION_SECURITY_REDIRECT_TO_LOGOUT = True
+    response = client.get("/template/")
+    assert b"returnToUrl" in response.content

session_security/tests/test_views.py

@@ -0,0 +1,43 @@
+from datetime import datetime
+from datetime import timedelta
+
+import pytest
+
+from session_security.utils import set_last_activity
+
+
+pytestmark = pytest.mark.django_db
+
+
+PING_CASES = (
+    (1, 4, "1", True),
+    (3, 2, "2", True),
+    (5, 5, "5", True),
+    (12, 14, '"logout"', False),
+)
+
+
+def test_anonymous_ping(client):
+    client.logout()
+    client.get("/admin/")
+    response = client.get("/session_security/ping/?idleFor=81")
+    assert response.content == b'"logout"'
+
+
+@pytest.mark.parametrize("server_idle, client_idle, expected, authenticated", PING_CASES)
+def test_ping(client, admin_user, settings, server_idle, client_idle, expected, authenticated):
+    settings.SESSION_SECURITY_WARN_AFTER = 5
+    settings.SESSION_SECURITY_EXPIRE_AFTER = 10
+
+    assert client.login(username="test", password="test")
+    client.get("/admin/")
+
+    now = datetime.now()
+    session = client.session
+    set_last_activity(session, now - timedelta(seconds=server_idle))
+    session.save()
+
+    response = client.get(f"/session_security/ping/?idleFor={client_idle}")
+
+    assert response.content == expected.encode("utf-8")
+    assert ("_auth_user_id" in client.session) is authenticated

session_security/urls.py

@@ -0,0 +1,29 @@
+"""
+One url meant to be used by JavaScript.
+
+session_security_ping
+    Connects the PingView.
+
+To install this url, include it in ``urlpatterns`` definition in ``urls.py``,
+ie::
+
+    urlpatterns = [
+        # ....
+        path("session_security/", include("session_security.urls")),
+        # ....
+    ]
+
+"""
+
+from django.urls import re_path
+
+from session_security.views import PingView
+
+
+urlpatterns = [
+    re_path(
+        "ping/$",
+        PingView.as_view(),
+        name="session_security_ping",
+    )
+]

session_security/utils.py

@@ -0,0 +1,14 @@
+"""Helpers to support json encoding of session data"""
+
+from datetime import datetime
+
+
+def set_last_activity(session, dt):
+    """Set the last activity datetime as a string in the session."""
+    session["_session_security"] = dt.strftime("%Y-%m-%dT%H:%M:%S.%f")
+
+
+def get_last_activity(session):
+    """Return the stored last-activity timestamp as a datetime."""
+    value = session["_session_security"]
+    return datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%f")

session_security/views.py

@@ -0,0 +1,29 @@
+"""One view method for AJAX requests by SessionSecurity objects."""
+
+from datetime import datetime
+
+from django import http
+from django.views import generic
+
+from session_security.utils import get_last_activity
+
+
+__all__ = [
+    "PingView",
+]
+
+
+class PingView(generic.View):
+    """
+    This view is just in charge of returning the number of seconds since the
+    'real last activity' that is maintained in the session by the middleware.
+    """
+
+    def get(self, request, *args, **kwargs):
+        if "_session_security" not in request.session:
+            # It probably has expired already
+            return http.HttpResponse('"logout"', content_type="application/json")
+
+        last_activity = get_last_activity(request.session)
+        inactive_for = (datetime.now() - last_activity).seconds
+        return http.HttpResponse(inactive_for, content_type="application/json")