velocity-python 0.1.103__tar.gz → 0.1.104__tar.gz

{velocity_python-0.1.103 → velocity_python-0.1.104}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.103
+Version: 0.1.104
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.103 → velocity_python-0.1.104}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.103"
+version = "0.1.104"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.103 → velocity_python-0.1.104}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.103"
+__version__ = version = "0.1.104"
 
 import importlib as _importlib
 

{velocity_python-0.1.103 → velocity_python-0.1.104}/src/velocity/aws/handlers/mixins/__init__.py

@@ -6,15 +6,19 @@ This package provides mixins for common Lambda handler patterns:
 - ButtonHandler: Dynamic button action handler loading
 - DataServiceMixin: Generic CRUD operations for database-backed APIs
 - JobHandler: get-job-status / download-job-result / cancel-job for async jobs
+- SessionControlMixin: opt-in single-active-login enforcement (register /
+  check / end session actions; pairs with velocity-react's SessionGate)
 """
 
 from .web_handler import WebHandler, ButtonHandler
 from .data_service import DataServiceMixin
 from .job_handler import JobHandler
+from .session_control import SessionControlMixin
 
 __all__ = [
     "WebHandler",
     "ButtonHandler",
     "DataServiceMixin",
     "JobHandler",
+    "SessionControlMixin",
 ]

velocity_python-0.1.104/src/velocity/aws/handlers/mixins/session_control.py

@@ -0,0 +1,277 @@
+"""Single-active-session enforcement for handler-backed apps.
+
+One live login per user: at sign-in the client registers a per-browser
+session key; if another live session exists (and the user row's
+``allow_multiple_sessions`` switch is off) the register answers
+``conflict`` with the other session's ip / browser / times so the UI can
+offer the choice — take over (ends the other session; its next heartbeat
+signs it out) or back out of this sign-in. A periodic client heartbeat
+keeps ``last_seen_at`` fresh and learns when it has been superseded;
+sessions quiet past ``session_stale_minutes`` are expired server-side so a
+crashed browser can't hold the account hostage.
+
+Feature switch — OFF by default (opt-in per app):
+  - class attribute ``single_session_enforcement = True`` turns it on;
+  - the ``SingleSessionEnforcement`` config key overrides per environment
+    (same precedence pattern as ``QueryMaxRows``).
+When off, every action answers as if the session were fine, so a deployed
+frontend gate (velocity-react ``SessionGate``) becomes a no-op without a
+frontend change.
+
+Everything is scoped by the AUTHENTICATED session's email — the payload
+only supplies the caller's own session key, so no action can read or end
+another user's sessions. Sessions live in ``session_table`` (default
+``app_session``; auto-created on first write under unlocked auto-schema —
+locked-schema apps declare it in their ensure_schema). The per-user
+switch column is read from the handler's ``user_table``.
+
+Usage::
+
+    class HttpEventHandler(SessionControlMixin, WebHandler, LambdaHandler):
+        user_table = "app_user"
+        single_session_enforcement = True
+
+Promoted 2026-09-07 from dance.10sp.us (same lifecycle as tenspace's
+app_auth: proven in the app, then centralized).
+"""
+
+import datetime
+
+from velocity.aws import ssm_config
+
+_TRUE = {"1", "true", "yes", "on"}
+_FALSE = {"0", "false", "no", "off"}
+
+
+def _now():
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+def _iso(value):
+    return value.isoformat() if hasattr(value, "isoformat") else (value or None)
+
+
+def describe_browser(user_agent):
+    """Friendly 'Chrome on Windows' from a raw UA (best-effort, no deps)."""
+    ua = user_agent or ""
+    if "Edg/" in ua:
+        browser = "Edge"
+    elif "OPR/" in ua or "Opera" in ua:
+        browser = "Opera"
+    elif "Chrome/" in ua:
+        browser = "Chrome"
+    elif "Firefox/" in ua:
+        browser = "Firefox"
+    elif "Safari/" in ua:
+        browser = "Safari"
+    else:
+        browser = "Unknown browser"
+    # order matters: Android UAs contain "Linux", iPads report "Mac OS X"
+    if "Windows" in ua:
+        os_name = "Windows"
+    elif "Android" in ua:
+        os_name = "Android"
+    elif "iPhone" in ua or "iPad" in ua:
+        os_name = "iPhone/iPad"
+    elif "Mac OS X" in ua:
+        os_name = "Mac"
+    elif "Linux" in ua:
+        os_name = "Linux"
+    else:
+        os_name = ""
+    return f"{browser} on {os_name}" if os_name else browser
+
+
+def client_info(aws_event):
+    """(ip, user_agent) from the API Gateway event — server-derived, never
+    trusted from the payload."""
+    identity = (aws_event or {}).get("requestContext", {}).get("identity", {})
+    headers = (aws_event or {}).get("headers") or {}
+    ip = identity.get("sourceIp") or ""
+    user_agent = headers.get("User-Agent") or headers.get("user-agent") or ""
+    return ip, user_agent
+
+
+def _describe(row):
+    return {
+        "ip": row.get("ip") or "",
+        "browser": row.get("browser") or row.get("user_agent") or "",
+        "started_at": _iso(row.get("started_at")),
+        "last_seen_at": _iso(row.get("last_seen_at")),
+    }
+
+
+class SessionControlMixin:
+    """register-session / check-session / end-session for the handler.
+
+    Add the three action names to any non-staff/authenticated-only allowlist
+    the handler enforces — every signed-in user needs them.
+    """
+
+    # The app-level switch (see module docstring). The
+    # ``SingleSessionEnforcement`` config key overrides per environment.
+    single_session_enforcement = False
+
+    session_table = "app_session"
+    session_stale_minutes = 10
+    # user-table column holding the per-user opt-out of the single limit
+    session_multi_column = "allow_multiple_sessions"
+
+    # ── switch resolution ────────────────────────────────────────────────
+    def _session_enforcement_enabled(self):
+        raw = None
+        try:
+            raw = ssm_config.getenv("SingleSessionEnforcement", None)
+        except Exception:
+            raw = None
+        if raw is not None:
+            lowered = str(raw).strip().lower()
+            if lowered in _TRUE:
+                return True
+            if lowered in _FALSE:
+                return False
+        return bool(self.single_session_enforcement)
+
+    def _session_user_table(self):
+        return getattr(self, "user_table", None) or "app_user"
+
+    # ── shared internals ─────────────────────────────────────────────────
+    def _session_email(self, context):
+        return ((context.session() or {}).get("email_address") or "").strip().lower()
+
+    def _live_sessions(self, tx, email, now):
+        """Live sessions for the user, expiring quiet ones on the way."""
+        sessions = tx.table(self.session_table)
+        stale_after = datetime.timedelta(minutes=self.session_stale_minutes)
+        live = []
+        for row in sessions.select(where={"email_address": email, "ended_at": None}):
+            seen = row.get("last_seen_at") or row.get("started_at")
+            if seen and (now - seen) > stale_after:
+                sessions.update(
+                    {"ended_at": now, "ended_by": "expired (no heartbeat)"},
+                    where={"sys_id": row["sys_id"]},
+                )
+                continue
+            live.append(row)
+        return live
+
+    def _allow_multiple(self, tx, email):
+        row = next(
+            iter(
+                tx.table(self._session_user_table()).select(
+                    where={"email_address": email}, qty=1
+                )
+            ),
+            None,
+        )
+        return bool(row and row.get(self.session_multi_column))
+
+    # ── actions ──────────────────────────────────────────────────────────
+    def OnActionRegisterSession(self, tx, context):
+        """Claim (or refresh) the caller's session; 'conflict' when someone
+        else is signed in, the user's multi-session switch is off, and this
+        isn't a takeover."""
+        payload = context.payload() or {}
+        email = self._session_email(context)
+        session_key = payload.get("session_key")
+        if not (email and session_key) or not self._session_enforcement_enabled():
+            context.response().set_body({"status": "active"})
+            return
+        ip, user_agent = client_info(self.aws_event)
+        now = _now()
+        sessions = tx.table(self.session_table)
+
+        mine = next(
+            iter(sessions.select(where={"session_key": session_key}, qty=1)), None
+        )
+        others = [
+            r
+            for r in self._live_sessions(tx, email, now)
+            if r.get("session_key") != session_key
+        ]
+        takeover = bool(payload.get("takeover"))
+
+        if others and not takeover and not self._allow_multiple(tx, email):
+            # my previously-live row (a page refresh) doesn't excuse the
+            # conflict: only an ACTIVE claim survives, and mine may have
+            # been superseded
+            if not (mine and mine.get("ended_at") is None):
+                context.response().set_body(
+                    {"status": "conflict", "sessions": [_describe(r) for r in others]}
+                )
+                return
+
+        if takeover:
+            for row in others:
+                sessions.update(
+                    {
+                        "ended_at": now,
+                        "ended_by": (
+                            f"signed out by a new sign-in from {ip or 'unknown ip'}"
+                        ),
+                    },
+                    where={"sys_id": row["sys_id"]},
+                )
+
+        fields = {
+            "email_address": email,
+            "ip": ip,
+            "user_agent": user_agent,
+            "browser": describe_browser(user_agent),
+            "last_seen_at": now,
+        }
+        if mine and mine.get("ended_at") is None:
+            # same login continuing (page refresh) — keep started_at
+            sessions.update(fields, where={"sys_id": mine["sys_id"]})
+        else:
+            # brand-new sign-in, or reclaiming a key that was previously ended
+            fields.update({"started_at": now, "ended_at": None, "ended_by": None})
+            sessions.upsert(fields, {"session_key": session_key})
+        context.response().set_body({"status": "active"})
+
+    def OnActionCheckSession(self, tx, context):
+        """Heartbeat: refresh last_seen_at, or report who superseded us."""
+        payload = context.payload() or {}
+        email = self._session_email(context)
+        session_key = payload.get("session_key")
+        if not (email and session_key) or not self._session_enforcement_enabled():
+            context.response().set_body({"status": "active"})
+            return
+        now = _now()
+        sessions = tx.table(self.session_table)
+        mine = next(
+            iter(
+                sessions.select(
+                    where={"session_key": session_key, "email_address": email}, qty=1
+                )
+            ),
+            None,
+        )
+        if mine and mine.get("ended_at") is None:
+            sessions.update({"last_seen_at": now}, where={"sys_id": mine["sys_id"]})
+            context.response().set_body({"status": "active"})
+            return
+        live = self._live_sessions(tx, email, now)
+        context.response().set_body(
+            {
+                "status": "superseded",
+                "reason": (mine or {}).get("ended_by") or "session ended",
+                "by": _describe(live[0]) if live else None,
+            }
+        )
+
+    def OnActionEndSession(self, tx, context):
+        """Clean sign-out: release the caller's own session claim."""
+        payload = context.payload() or {}
+        email = self._session_email(context)
+        session_key = payload.get("session_key")
+        if email and session_key and self._session_enforcement_enabled():
+            tx.table(self.session_table).update(
+                {"ended_at": _now(), "ended_by": "signed out"},
+                where={
+                    "session_key": session_key,
+                    "email_address": email,
+                    "ended_at": None,
+                },
+            )
+        context.response().set_body({"status": "ended"})

{velocity_python-0.1.103 → velocity_python-0.1.104}/src/velocity/misc/pdf.py

@@ -161,12 +161,23 @@ def _prepend_env_path(name: str, *paths: str) -> None:
     os.environ[name] = os.pathsep.join(merged)
 
 
+def _configure_layer_fonts() -> None:
+    """Point fontconfig at a Lambda layer's /opt/fonts when nothing else has.
+
+    Must run BEFORE the first render in the process: with no usable
+    fontconfig config Pango gets a NULL font and the whole runtime dies with
+    a segmentation fault, not a Python error (found live 2026-09-07 on an
+    AL2023/python3.12 stack whose functions did not set FONTCONFIG_PATH).
+    Harmless off-Lambda — the directory simply doesn't exist."""
+    if os.path.isdir("/opt/fonts") and not os.environ.get("FONTCONFIG_PATH"):
+        os.environ["FONTCONFIG_PATH"] = "/opt/fonts"
+
+
 def _configure_wkhtml_runtime() -> None:
     # Lambda layers put the binary in /opt/bin and its shared libs in /opt/lib.
     _prepend_env_path("PATH", "/opt/bin")
     _prepend_env_path("LD_LIBRARY_PATH", "/opt/lib")
-    if os.path.isdir("/opt/fonts") and not os.environ.get("FONTCONFIG_PATH"):
-        os.environ["FONTCONFIG_PATH"] = "/opt/fonts"
+    _configure_layer_fonts()
 
 
 def _find_wkhtmltopdf() -> str | None:
@@ -351,6 +362,7 @@ class WeasyPrintRenderer(BasePdfRenderer):
                 "that carries its Pango/Cairo libraries and set LD_LIBRARY_PATH=/opt/lib, "
                 f"FONTCONFIG_PATH=/opt/fonts). Root cause: {_weasyprint_import_error!r}"
             )
+        _configure_layer_fonts()
         css_text = page_css(page)
         if extra_css:
             css_text += "\n" + extra_css

{velocity_python-0.1.103 → velocity_python-0.1.104}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.103
+Version: 0.1.104
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.103 → velocity_python-0.1.104}/src/velocity_python.egg-info/SOURCES.txt

@@ -38,6 +38,7 @@ src/velocity/aws/handlers/sqs_handler.py
 src/velocity/aws/handlers/mixins/__init__.py
 src/velocity/aws/handlers/mixins/data_service.py
 src/velocity/aws/handlers/mixins/job_handler.py
+src/velocity/aws/handlers/mixins/session_control.py
 src/velocity/aws/handlers/mixins/web_handler.py
 src/velocity/aws/tests/__init__.py
 src/velocity/aws/tests/test_amplify_build_policy_size.py
@@ -254,6 +255,7 @@ tests/test_row_cache_staleness.py
 tests/test_schema_migrations.py
 tests/test_security_hardening.py
 tests/test_server_cursor.py
+tests/test_session_control.py
 tests/test_single_autocommit_safety.py
 tests/test_spreadsheet_functions.py
 tests/test_sqlite_backend.py

{velocity_python-0.1.103 → velocity_python-0.1.104}/tests/test_pdf.py

@@ -382,3 +382,28 @@ class TestWeasyPrintReal:
     def test_real_render_produces_a_pdf(self):
         out = html_to_pdf("<h1>hello</h1>", engine="weasyprint", margin="0in")
         assert out.startswith(b"%PDF-")
+
+
+class TestLayerFontConfiguration:
+    """_configure_layer_fonts: points fontconfig at /opt/fonts before a render
+    so Pango can never come up font-less on Lambda (a NULL font segfaults the
+    runtime — found live 2026-09-07)."""
+
+    def test_sets_fontconfig_path_when_layer_fonts_exist(self, monkeypatch):
+        monkeypatch.delenv("FONTCONFIG_PATH", raising=False)
+        monkeypatch.setattr(
+            pdfmod.os.path, "isdir", lambda p: p == "/opt/fonts"
+        )
+        pdfmod._configure_layer_fonts()
+        assert pdfmod.os.environ["FONTCONFIG_PATH"] == "/opt/fonts"
+
+    def test_never_overrides_an_explicit_setting_or_missing_dir(self, monkeypatch):
+        monkeypatch.setenv("FONTCONFIG_PATH", "/custom/fonts")
+        monkeypatch.setattr(pdfmod.os.path, "isdir", lambda p: True)
+        pdfmod._configure_layer_fonts()
+        assert pdfmod.os.environ["FONTCONFIG_PATH"] == "/custom/fonts"
+
+        monkeypatch.delenv("FONTCONFIG_PATH", raising=False)
+        monkeypatch.setattr(pdfmod.os.path, "isdir", lambda p: False)
+        pdfmod._configure_layer_fonts()
+        assert "FONTCONFIG_PATH" not in pdfmod.os.environ

velocity_python-0.1.104/tests/test_session_control.py

@@ -0,0 +1,255 @@
+"""SessionControlMixin: the on/off switch (attr + SingleSessionEnforcement
+config key), conflict/takeover/multi-allowed register paths, heartbeat,
+stale expiry, sign-out scoping, and browser description."""
+
+import datetime
+
+import pytest
+
+from velocity.aws.handlers.mixins import session_control
+from velocity.aws.handlers.mixins.session_control import SessionControlMixin
+
+NOW = datetime.datetime.now(datetime.timezone.utc)
+UA_CHROME = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
+)
+EVENT = {
+    "requestContext": {"identity": {"sourceIp": "203.0.113.7"}},
+    "headers": {"User-Agent": UA_CHROME},
+}
+
+
+def session_row(**overrides):
+    row = {
+        "sys_id": 41,
+        "email_address": "staff@example.com",
+        "session_key": "other-key",
+        "ip": "198.51.100.9",
+        "user_agent": "x",
+        "browser": "Firefox on Mac",
+        "started_at": NOW - datetime.timedelta(hours=1),
+        "last_seen_at": NOW - datetime.timedelta(seconds=30),
+        "ended_at": None,
+        "ended_by": None,
+    }
+    row.update(overrides)
+    return row
+
+
+class FakeTable:
+    def __init__(self, rows):
+        self.rows = rows
+        self.updates = []  # (fields, where)
+        self.upserts = []  # (fields, pk)
+
+    def select(self, where=None, qty=None, **_kw):
+        where = where or {}
+        rows = self.rows
+        for key in ("session_key", "email_address"):
+            if key in where:
+                rows = [r for r in rows if r.get(key) == where[key]]
+        if "ended_at" in where and where["ended_at"] is None:
+            rows = [r for r in rows if r.get("ended_at") is None]
+        return iter(rows[:qty] if qty else rows)
+
+    def update(self, fields, where=None):
+        self.updates.append((fields, where))
+
+    def upsert(self, fields, pk):
+        self.upserts.append((fields, pk))
+
+
+class FakeTx:
+    def __init__(self, session_rows, allow_multiple=False):
+        self.sessions = FakeTable(session_rows)
+        self.users = FakeTable(
+            [{"sys_id": 1, "email_address": "staff@example.com",
+              "allow_multiple_sessions": allow_multiple}]
+        )
+
+    def table(self, name):
+        return {"app_session": self.sessions, "app_user": self.users}[name]
+
+
+class FakeResponse:
+    def __init__(self):
+        self.body = None
+
+    def set_body(self, body):
+        self.body = body
+
+
+class FakeContext:
+    def __init__(self, email="Staff@Example.com ", payload=None):
+        self._email = email
+        self._payload = payload or {}
+        self._response = FakeResponse()
+
+    def session(self):
+        return {"email_address": self._email}
+
+    def payload(self):
+        return self._payload
+
+    def response(self):
+        return self._response
+
+
+class Handler(SessionControlMixin):
+    user_table = "app_user"
+    single_session_enforcement = True
+
+    def __init__(self, aws_event=EVENT):
+        self.aws_event = aws_event
+
+
+@pytest.fixture(autouse=True)
+def no_config_key(monkeypatch):
+    monkeypatch.setattr(
+        session_control.ssm_config, "getenv", lambda *_a, **_k: None
+    )
+
+
+def run(handler, method, tx, payload):
+    context = FakeContext(payload=payload)
+    getattr(handler, method)(tx, context)
+    return context._response.body
+
+
+# ── the switch ──────────────────────────────────────────────────────────
+
+
+def test_disabled_attribute_short_circuits_without_touching_the_db():
+    handler = Handler()
+    handler.single_session_enforcement = False
+    tx = FakeTx([session_row()])
+    body = run(handler, "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "active"}
+    assert tx.sessions.updates == [] and tx.sessions.upserts == []
+
+
+def test_config_key_overrides_the_attribute_both_ways(monkeypatch):
+    handler = Handler()
+    tx = FakeTx([session_row()])
+    monkeypatch.setattr(
+        session_control.ssm_config, "getenv", lambda *_a, **_k: "false"
+    )
+    body = run(handler, "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "active"}  # enforcement off despite attr True
+
+    handler.single_session_enforcement = False
+    monkeypatch.setattr(
+        session_control.ssm_config, "getenv", lambda *_a, **_k: "true"
+    )
+    body = run(handler, "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body["status"] == "conflict"  # enforcement on despite attr False
+
+
+# ── register ────────────────────────────────────────────────────────────
+
+
+def test_conflict_reports_the_other_session():
+    tx = FakeTx([session_row()])
+    body = run(Handler(), "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body["status"] == "conflict"
+    assert body["sessions"][0]["ip"] == "198.51.100.9"
+    assert body["sessions"][0]["browser"] == "Firefox on Mac"
+    assert tx.sessions.upserts == []
+
+
+def test_takeover_ends_the_other_session_and_activates_mine():
+    tx = FakeTx([session_row()])
+    body = run(
+        Handler(),
+        "OnActionRegisterSession",
+        tx,
+        {"session_key": "my-key", "takeover": True},
+    )
+    assert body == {"status": "active"}
+    ended_fields, _ = tx.sessions.updates[0]
+    assert "203.0.113.7" in ended_fields["ended_by"]
+    mine_fields, pk = tx.sessions.upserts[0]
+    assert mine_fields["browser"] == "Chrome on Windows"
+    assert mine_fields["ip"] == "203.0.113.7"
+    assert pk == {"session_key": "my-key"}
+
+
+def test_allow_multiple_admits_without_takeover():
+    tx = FakeTx([session_row()], allow_multiple=True)
+    body = run(Handler(), "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "active"}
+    assert len(tx.sessions.upserts) == 1
+
+
+def test_stale_other_session_expires_instead_of_conflicting():
+    stale = session_row(
+        last_seen_at=NOW
+        - datetime.timedelta(minutes=SessionControlMixin.session_stale_minutes + 5)
+    )
+    tx = FakeTx([stale])
+    body = run(Handler(), "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "active"}
+    expired_fields, _ = tx.sessions.updates[0]
+    assert "expired" in expired_fields["ended_by"]
+
+
+def test_refresh_of_my_live_session_keeps_started_at():
+    tx = FakeTx([session_row(sys_id=9, session_key="my-key")])
+    body = run(Handler(), "OnActionRegisterSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "active"}
+    assert tx.sessions.upserts == []
+    updated_fields, _ = tx.sessions.updates[0]
+    assert "started_at" not in updated_fields
+
+
+# ── heartbeat and sign-out ──────────────────────────────────────────────
+
+
+def test_heartbeat_refreshes_last_seen():
+    tx = FakeTx([session_row(sys_id=9, session_key="my-key")])
+    body = run(Handler(), "OnActionCheckSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "active"}
+    assert "last_seen_at" in tx.sessions.updates[0][0]
+
+
+def test_superseded_names_who_took_over():
+    mine = session_row(
+        sys_id=9,
+        session_key="my-key",
+        ended_at=NOW,
+        ended_by="signed out by a new sign-in from 203.0.113.7",
+    )
+    tx = FakeTx([mine, session_row()])
+    body = run(Handler(), "OnActionCheckSession", tx, {"session_key": "my-key"})
+    assert body["status"] == "superseded"
+    assert "203.0.113.7" in body["reason"]
+    assert body["by"]["ip"] == "198.51.100.9"
+
+
+def test_end_releases_only_my_live_claim():
+    tx = FakeTx([])
+    body = run(Handler(), "OnActionEndSession", tx, {"session_key": "my-key"})
+    assert body == {"status": "ended"}
+    fields, where = tx.sessions.updates[0]
+    assert fields["ended_by"] == "signed out"
+    assert where == {
+        "session_key": "my-key",
+        "email_address": "staff@example.com",
+        "ended_at": None,
+    }
+
+
+# ── helpers ─────────────────────────────────────────────────────────────
+
+
+def test_describe_browser_common_user_agents():
+    assert session_control.describe_browser(UA_CHROME) == "Chrome on Windows"
+    assert (
+        session_control.describe_browser(
+            "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) "
+            "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/604.1"
+        )
+        == "Safari on iPhone/iPad"
+    )
+    assert session_control.describe_browser("") == "Unknown browser"