cherrypy-foundation 1.0.0__py3-none-any.whl

cherrypy_foundation/tools/ratelimit.py

@@ -0,0 +1,265 @@
+# Ratelimit tools for cherrypy
+# Copyright (C) 2022-2026 IKUS Software
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+import hashlib
+import os
+import tempfile
+import threading
+import time
+from collections import namedtuple
+
+import cherrypy
+
+from cherrypy_foundation.sessions import session_lock
+
+Tracker = namedtuple('Tracker', ['token', 'hits', 'timeout'])
+
+
+class _DataStore:
+    """
+    Base class for rate limit data store
+    """
+
+    def __init__(self, **kwargs):
+        self._locks = {}
+
+    def get_and_increment(self, token, delay, hit=1):
+        lock = self._locks.setdefault(token, threading.RLock())
+        with lock:
+            tracker = self._load(token)
+            if tracker is None or tracker.timeout < time.time():
+                tracker = Tracker(token=token, hits=0, timeout=int(time.time() + delay))
+            tracker = tracker._replace(hits=tracker.hits + hit)
+            self._save(tracker)
+        return tracker.hits, tracker.timeout
+
+    def _save(self, tracker):
+        raise NotImplementedError
+
+    def _load(self, token):
+        raise NotImplementedError
+
+
+class RamRateLimit(_DataStore):
+    """
+    Store rate limit information in memory.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._data = {}
+
+    def _load(self, token):
+        return self._data.get(token)
+
+    def _save(self, tracker):
+        self._data[tracker.token] = tracker
+
+    def reset(self):
+        self._data = {}
+
+
+class FileRateLimit(_DataStore):
+    PREFIX = 'ratelimit-'
+
+    def __init__(self, storage_path, **kwargs):
+        super().__init__(**kwargs)
+        assert storage_path, 'FileRateLimit requires storage_path'
+        self.storage_path = os.path.abspath(storage_path)
+        os.makedirs(self.storage_path, exist_ok=True)
+
+    def _path(self, token):
+        # Hash the token to avoid max path limit and invalid chars.
+        digest = hashlib.sha256(token.encode('utf-8')).hexdigest()
+        return os.path.join(self.storage_path, self.PREFIX + digest + '.txt')
+
+    def _load(self, token):
+        path = self._path(token)
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                line = f.readline().strip()
+        except FileNotFoundError:
+            return None
+        except OSError:
+            return None
+
+        if not line:
+            return None
+
+        parts = line.split()
+        if len(parts) != 2:
+            return None
+
+        try:
+            hits = int(parts[0])
+            timeout = int(parts[1])
+            if hits < 0 or timeout < 0:
+                return None
+        except ValueError:
+            return None
+
+        return Tracker(token=token, hits=hits, timeout=timeout)
+
+    def _save(self, tracker):
+        path = self._path(tracker.token)
+        # Atomic write: temp file in same directory
+        fd, tmp = tempfile.mkstemp(dir=self.storage_path)
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                f.write(f"{tracker.hits} {int(tracker.timeout)}\n")
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp, path)
+            # On POSIX, chmod on first write
+            try:
+                os.chmod(path, 0o600)
+            except OSError:
+                pass
+        finally:
+            try:
+                if os.path.exists(tmp):
+                    os.remove(tmp)
+            except Exception:
+                pass
+
+    def reset(self):
+        for item in os.listdir(self.storage_path):
+            if not item.startswith(self.PREFIX):
+                continue
+            fn = os.path.join(self.storage_path, item)
+            if not os.path.isfile(fn):
+                continue
+            try:
+                os.remove(fn)
+            except OSError:
+                pass
+
+
+class Ratelimit(cherrypy.Tool):
+    CONTEXT = 'TOOLS.RATELIMIT'
+
+    _datastores = {}
+
+    def __init__(self, priority=60):
+        super().__init__('before_handler', self.check_ratelimit, 'ratelimit', priority)
+
+    def _get_datastore(self, storage_class, **kwargs):
+        """
+        Create new datastore or return existing datastore.
+        """
+        # Default to RAM if storage class is not defined.
+        if storage_class is None:
+            kwargs = {}
+            storage_class = RamRateLimit
+        # Lookup for matching storage.
+        key = (storage_class, str(kwargs))
+        datastore = self._datastores.get(key)
+        if datastore is None:
+            # Create new storage if not found.
+            self._datastores[key] = datastore = storage_class(**kwargs)
+        return datastore
+
+    def check_ratelimit(
+        self,
+        delay=3600,
+        limit=25,
+        return_status=429,
+        logout=False,
+        scope=None,
+        methods=None,
+        debug=False,
+        hit=1,
+        storage_class=None,
+        **storage_kwargs,
+    ):
+        """
+        Verify the ratelimit. By default return a 429 HTTP error code (Too Many Request). After 25 request within the same hour.
+
+        Arguments:
+            delay:         Time window for analysis in seconds
+            limit:         Number of request allowed for an entry point
+            return_status: HTTP Error code to return.
+            logout:        True to logout user when limit is reached
+            scope:         if specify, define the scope of rate limit. Default to path_info.
+            methods:       if specify, only the methods in the list will be rate limited.
+        """
+        if delay <= 0:
+            raise ValueError('Invalid delay: %s' % delay)
+        if limit <= 0:
+            return
+
+        # Check if this 'method' should be rate limited
+        request = cherrypy.request
+        if methods is not None and request.method not in methods:
+            if debug:
+                cherrypy.log(f'skip rate limit for HTTP method {request.method}', context=self.CONTEXT)
+            return
+
+        # Create storage using storage class
+        datastore = self._get_datastore(storage_class, **storage_kwargs)
+
+        # Identifier: prefer authenticated user; else client IP
+        identifier = getattr(cherrypy.serving.request, 'login', None) or cherrypy.request.remote.ip
+
+        # Include method unless methods is explicitly a single method
+        method_part = request.method
+        if methods and len(methods) == 1:
+            method_part = next(iter(methods))
+
+        # Scope: allow explicit; else normalized path (e.g., strip trailing slash)
+        path = request.path_info.rstrip('/') or '/'
+        scope_value = scope or path
+
+        token = f"{identifier}|{method_part}|{scope_value}"
+
+        # Get hits count using datastore.
+        hits, timeout = datastore.get_and_increment(token, delay, hit)
+        if debug:
+            cherrypy.log(f'check and increase limit token={token} limit={limit} hits={hits}', context=self.CONTEXT)
+
+        # Verify user has not exceeded rate limit
+        remaining = max(0, limit - hits)
+
+        # Define headers
+        cherrypy.response.headers['X-RateLimit-Limit'] = str(limit)
+        cherrypy.response.headers['X-RateLimit-Remaining'] = str(remaining)
+        cherrypy.response.headers['X-RateLimit-Reset'] = str(timeout)
+
+        if limit < hits:  # block only after 'limit' successful requests
+            cherrypy.log(f'block access to path_info={request.path_info}', context=self.CONTEXT)
+            if logout:
+                if hasattr(cherrypy.serving, 'session'):
+                    with session_lock() as session:
+                        session.clear()
+                raise cherrypy.HTTPRedirect("/")
+            raise cherrypy.HTTPError(return_status)
+
+    def increase_hit(self, hit=1):
+        """
+        May be called directly by handlers to add a hit for the given request.
+        """
+        conf = cherrypy.tools.ratelimit._merged_args()
+        conf['hit'] = hit
+        cherrypy.tools.ratelimit.callable(**conf)
+
+    def reset(self):
+        """
+        Used to reset the ratelimit. (for unit test)
+        """
+        for datastore in self._datastores.values():
+            datastore.reset()
+
+
+cherrypy.tools.ratelimit = Ratelimit()

cherrypy_foundation/tools/secure_headers.py

@@ -0,0 +1,119 @@
+# Secure Headers tool for cherrypy
+# Copyright (C) 2012-2026 IKUS Software
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import http.cookies
+
+import cherrypy
+
+DEFAULT_CSP = {
+    'default-src': 'self',
+    'style-src': ('self', 'unsafe-inline'),
+    'script-src': ('self', 'unsafe-inline'),
+}
+
+#
+# Patch Morsel prior to 3.8
+# Allow SameSite attribute to be define on the cookie.
+#
+if not http.cookies.Morsel().isReservedKey("samesite"):
+    http.cookies.Morsel._reserved['samesite'] = 'SameSite'
+
+
+def _build_csp(csp):
+    if isinstance(csp, dict):
+        return "; ".join(
+            f"{directive} {' '.join(sources) if isinstance(sources, (list, tuple)) else str(sources)}"
+            for directive, sources in csp.items()
+        )
+    return str(csp)
+
+
+def set_headers(
+    xfo='DENY',
+    no_cache=True,
+    referrer='same-origin',
+    nosniff=True,
+    xxp='1; mode=block',
+    csp=DEFAULT_CSP,
+):
+    """
+    This tool provide CSRF mitigation.
+
+    * Define X-Frame-Options = DENY
+    * Define Cookies SameSite=Lax
+    * Define Cookies Secure when https is detected
+    * Validate `Origin` and `Referer` on POST, PUT, PATCH, DELETE
+    * Define Cache-Control by default
+    * Define Referrer-Policy to 'same-origin'
+
+    Ref.:
+    https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
+    https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html
+    """
+    request = cherrypy.request
+    response = cherrypy.serving.response
+
+    # Check if Origin matches our target.
+    if request.method in ['POST', 'PUT', 'PATCH', 'DELETE']:
+        origin = request.headers.get('Origin', None)
+        if origin and origin != request.base:
+            raise cherrypy.HTTPError(403, 'Unexpected Origin header')
+
+    # Check if https is enabled
+    https = request.base.startswith('https')
+
+    # Define X-Frame-Options to avoid Clickjacking
+    if xfo:
+        response.headers['X-Frame-Options'] = xfo
+
+    # Enforce security on cookies
+    cookie = response.cookie.get('session_id', None)
+    if cookie:
+        # Awaiting bug fix in cherrypy
+        # https://github.com/cherrypy/cherrypy/issues/1767
+        # Force SameSite to Lax
+        cookie['samesite'] = 'Lax'
+        if https:
+            cookie['secure'] = 1
+
+    # Add Cache-Control to avoid storing sensible information in Browser cache.
+    if no_cache:
+        response.headers['Cache-control'] = 'no-cache, no-store, must-revalidate, max-age=0'
+        response.headers['Pragma'] = 'no-cache'
+        response.headers['Expires'] = '0'
+
+    # Add Referrer-Policy
+    if referrer:
+        response.headers['Referrer-Policy'] = referrer
+
+    # Add X-Content-Type-Options to avoid browser to "sniff" to content-type
+    if nosniff:
+        response.headers['X-Content-Type-Options'] = 'nosniff'
+
+    # Add X-XSS-Protection to enabled XSS protection
+    if xxp:
+        response.headers['X-XSS-Protection'] = xxp
+
+    # Add Content-Security-Policy
+    if csp:
+        response.headers['Content-Security-Policy'] = _build_csp(csp)
+
+    # Add Strict-Transport-Security to force https use.
+    if https:
+        response.headers['Strict-Transport-Security'] = "max-age=31536000; includeSubDomains"
+
+
+cherrypy.tools.secure_headers = cherrypy.Tool('before_request_body', set_headers, priority=71)

cherrypy_foundation/tools/sessions_timeout.py

@@ -0,0 +1,167 @@
+# Session timeout tool for cherrypy
+# Copyright (C) 2012-2026 IKUS Software
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+import datetime
+import math
+import time
+
+import cherrypy
+from cherrypy.lib import httputil
+
+from cherrypy_foundation.sessions import session_lock
+
+SESSION_PERSISTENT = '_session_persistent'
+SESSION_START_TIME = '_session_start_time'
+
+SESSION_DEFAULT_ABSOLUTE_TIMEOUT = 43200  # 30 days
+SESSION_DEFAULT_PERSISTENT_TIMEOUT = 10080  # 7 days
+SESSION_DEFAULT_TIMEOUT = 60  # 60 minutes (from cherrypy default)
+
+
+class SessionsTimeout(cherrypy.Tool):
+    """
+    Fine-grained control over session timeouts.
+
+    Config keys:
+      - tools.sessions.timeout (int, minutes)  -> base idle timeout (CherryPy built-in, used for non-persistent)
+      - tools.sessions_timeout.absolute_timeout (int, minutes)  -> hard cap for all sessions (default=43200 = 30d)
+      - tools.sessions_timeout.persistent_timeout (int, minutes) -> sliding window for persistent sessions (default=10080 = 7d)
+      - tools.sessions.name (str) -> session cookie name (default: 'session_id')
+    """
+
+    def __init__(self, priority: int = 75):
+        super().__init__(point='before_handler', callable=self.run, priority=priority)
+
+    @staticmethod
+    def _cookie_name() -> str:
+        return cherrypy.request.config.get('tools.sessions.name', 'session_id')
+
+    @staticmethod
+    def _get_config_timeouts() -> tuple[int, int, int]:
+        cfg = cherrypy.request.config
+        idle_timeout = int(cfg.get('tools.sessions.timeout', SESSION_DEFAULT_TIMEOUT))
+        persistent_timeout = int(
+            cfg.get('tools.sessions_timeout.persistent_timeout', SESSION_DEFAULT_PERSISTENT_TIMEOUT)
+        )
+        absolute_timeout = int(cfg.get('tools.sessions_timeout.absolute_timeout', SESSION_DEFAULT_ABSOLUTE_TIMEOUT))
+        return idle_timeout, persistent_timeout, absolute_timeout
+
+    def _set_cookie_max_age(self, session, max_age: int) -> None:
+        """Adjust only Max-Age and Expires for the session cookie, keep other flags intact."""
+        cookie_name = self._cookie_name()
+        cookie = cherrypy.serving.response.cookie
+        # Ensure the cookie key exists (CherryPy sets it when session id is issued/regenerated).
+        if cookie_name not in cookie:
+            cookie[cookie_name] = session.id
+        cookie[cookie_name]['max-age'] = str(max(0, max_age))
+        cookie[cookie_name]['expires'] = httputil.HTTPDate(time.time() + max(0, max_age))
+
+    @staticmethod
+    def _ceil_minutes(seconds: int) -> int:
+        if seconds <= 0:
+            return 0
+        return int(math.ceil(seconds / 60.0))
+
+    def _ensure_start_time(self, session) -> None:
+        """Ensure the session has a stable start time anchor for absolute timeout."""
+        if SESSION_START_TIME not in session or not isinstance(session.get(SESSION_START_TIME), datetime.datetime):
+            session[SESSION_START_TIME] = session.now()
+
+    def _expire_and_restart(self, session, make_persistent: bool | None = None) -> None:
+        """Expire current session and start a fresh one. Optionally set persistent flag."""
+        session.clear()
+        session.regenerate()
+        session[SESSION_START_TIME] = session.now()
+        if make_persistent is not None:
+            session[SESSION_PERSISTENT] = bool(make_persistent)
+
+    def _update_session_timeout(self, session) -> None:
+        self._ensure_start_time(session)
+
+        now: datetime.datetime = session.now()
+        start: datetime.datetime = session[SESSION_START_TIME]
+
+        idle_timeout_min, persistent_timeout_min, absolute_timeout_min = self._get_config_timeouts()
+
+        is_persistent = bool(session.get(SESSION_PERSISTENT, False))
+
+        # Compute absolute remaining (hard cap from start, never slides)
+        abs_expiration = start + datetime.timedelta(minutes=absolute_timeout_min)
+        abs_remaining_sec = int((abs_expiration - now).total_seconds())
+
+        if is_persistent:
+            # Sliding window for persistent sessions
+            sliding_exp = now + datetime.timedelta(minutes=persistent_timeout_min)
+        else:
+            # Sliding window for non-persistent sessions (idle timeout)
+            sliding_exp = now + datetime.timedelta(minutes=idle_timeout_min)
+
+        sliding_remaining_sec = int((sliding_exp - now).total_seconds())
+
+        # Effective remaining is the minimum of the sliding window and absolute cap
+        remaining_sec = min(abs_remaining_sec, sliding_remaining_sec)
+        remaining_min = self._ceil_minutes(remaining_sec)
+
+        if remaining_min <= 0:
+            # Expired due to either sliding window or absolute cap
+            # Start a fresh session; do NOT automatically re-mark persistent here.
+            # Authentication/Remember me logic elsewhere can call set_persistent(True) again after login.
+            self._expire_and_restart(session)
+            # After regeneration, set a sensible session.timeout baseline:
+            session.timeout = idle_timeout_min
+            return
+
+        # Apply per-request remaining minutes to CherryPy's session timeout
+        session.timeout = remaining_min
+
+        if is_persistent:
+            # Keep cookie lifetime aligned with remaining time so it can survive browser restarts.
+            self._set_cookie_max_age(session, remaining_sec)
+        else:
+            # For non-persistent, let CherryPy manage the session cookie (session or transient cookie).
+            # If you want strict enforcement client-side too, uncomment the next line:
+            # self._set_cookie_max_age(remaining_sec)
+            pass
+
+    def run(self, persistent_timeout: int = 10080, absolute_timeout: int = 43200) -> None:
+        # Skip if sessions are not enabled
+        if not hasattr(cherrypy.serving, 'session'):
+            return
+
+        # Ensure configured values are honored (method signature kept for CherryPy Tool interface)
+        with session_lock() as session:
+            self._update_session_timeout(session)
+
+    def set_persistent(self, value: bool = True) -> None:
+        """Mark current session as persistent (or not) and reset the start window."""
+        with session_lock() as session:
+            session[SESSION_PERSISTENT] = bool(value)
+            # Reset absolute window anchor when the persistence policy changes
+            session[SESSION_START_TIME] = session.now()
+            self._update_session_timeout(session)
+
+    def is_persistent(self) -> bool:
+        """Return True if the session is marked persistent."""
+        with session_lock() as session:
+            return bool(session.get(SESSION_PERSISTENT, False))
+
+    def get_session_start_time(self) -> datetime.datetime | None:
+        """Return the session start time if any."""
+        with session_lock() as session:
+            return session.get(SESSION_START_TIME, None)
+
+
+cherrypy.tools.sessions_timeout = SessionsTimeout()

cherrypy_foundation/tools/tests/components/Button.jinja

@@ -0,0 +1,2 @@
+{# def label, link #}
+<a {{ attrs.render(class='btn btn-primary', href=link) }}>{{ label }}</a>

cherrypy_foundation/tools/tests/locales/de/LC_MESSAGES/messages.po

@@ -0,0 +1,15 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: \n"
+"POT-Creation-Date: \n"
+"PO-Revision-Date: \n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"Language: de\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: Poedit 3.6\n"
+
+msgid "Some text to translate"
+msgstr "Einige zu übersetzende Texte"

cherrypy_foundation/tools/tests/locales/fr/LC_MESSAGES/messages.po

@@ -0,0 +1,15 @@
+msgid ""
+msgstr ""
+"Project-Id-Version: \n"
+"POT-Creation-Date: \n"
+"PO-Revision-Date: \n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"Language: fr\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"X-Generator: Poedit 3.6\n"
+
+msgid "Some text to translate"
+msgstr "Du texte à traduire"

cherrypy_foundation/tools/tests/locales/messages.pot

@@ -0,0 +1,2 @@
+msgid "Some text to translate"
+msgstr ""

cherrypy_foundation/tools/tests/templates/test_jinja2.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <title>test-jinja2</title>
+    </head>
+    <body>
+        var1: {{ var1 }}<br/>
+        var2: {{ var2 }}<br/>
+        const1: {{ const1 }}<br/>
+    </body>
+</html>

cherrypy_foundation/tools/tests/templates/test_jinjax.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <title>test-jinjax</title>
+    </head>
+    <body>
+        <Button link="http://example.com" label="foo" />
+    </body>
+</html>

cherrypy_foundation/tools/tests/templates/test_jinjax_i18n.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="{{ get_translation().locale }}">
+    <head>
+        <title>test-jinja2</title>
+        {{ catalog.render_assets() }}
+    </head>
+    <body>
+        <!-- Selector -->
+        <div class="dropdown">
+            <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">
+                Dropdown button
+            </button>
+            <ul class="dropdown-menu">
+                <LocaleSelection />
+            </ul>
+        </div>
+        {{ get_language_name(get_translation().locale) }}<br/>
+        {% trans %}Some text to translate{% endtrans %}<br/>
+        {{ my_datetime | format_datetime(format='full') }}<br/>
+        {{ my_date | format_date(format='full') }}
+    </body>
+</html>