velocity-python 0.3.0__tar.gz → 0.3.1__tar.gz

{velocity_python-0.3.0 → velocity_python-0.3.1}/PKG-INFO

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

{velocity_python-0.3.0 → velocity_python-0.3.1}/pyproject.toml

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

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.3.0"
+__version__ = version = "0.3.1"
 
 import importlib as _importlib
 

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity/aws/capabilities/security.py

@@ -19,7 +19,8 @@ rate limits, payload caps, and an audit trail of what was refused and why.
 Attach :class:`SecurityMixin` FIRST in a handler's bases; it runs in
 ``beforeAction`` ahead of auth and every action, and is a no-op unless the
 site's ``sys_capabilities`` row for ``security`` is enabled. A refusal raises
-:class:`AccessError` (a 403) after committing a ``sys_security_events`` row.
+:class:`AccessError` (a 403) after recording a ``sys_security_events`` row
+(committed on its own transaction, so the 403's rollback keeps it).
 
 ``sys_security_events`` itself is a CORE table (``SCHEMA``, in
 ``velocity.aws.schema``'s ``core`` group), not the capability's: it is
@@ -39,6 +40,7 @@ import logging
 
 from velocity.aws import feature_flags
 from velocity.cache import memo, read_cache
+from velocity.db import _pgddl, audit
 
 from .base import (
     CIDR_LIST,
@@ -314,7 +316,13 @@ def enforce(tx, aws_event, context, *, now=None):
         guard, reason = refusal
         if truthy(config.get("security_block_logging_enabled")):
             record_event(
-                tx, guard, reason, aws_event=aws_event, context=context, user_email=user
+                tx,
+                guard,
+                reason,
+                aws_event=aws_event,
+                context=context,
+                user_email=user,
+                actor=GUARD_AUDIT_ACTOR,
             )
         log.warning("security guard %s refused %s: %s", guard, facts["ip"], reason)
         # imported here, not at module top: the capabilities package must not
@@ -326,6 +334,15 @@ def enforce(tx, aws_event, context, *, now=None):
     return config
 
 
+# A second connection waiting on a lock the caller's own transaction holds
+# would wait forever (the database can't see it as a deadlock): bound it, so
+# the event fails (and an audited decision is refused) instead of hanging.
+EVENT_LOCK_TIMEOUT = "5s"
+# The audit actor of a guard refusal: it is recorded in beforeAction, before
+# any request actor is set.
+GUARD_AUDIT_ACTOR = "system:security_guard"
+
+
 def record_event(
     tx,
     guard,
@@ -337,58 +354,116 @@ def record_event(
     user_sub=None,
     detail=None,
     occurred_at=None,
+    actor=None,
 ):
-    """Append one ``sys_security_events`` row and commit it — an audit row
-    must survive whatever the caller does next (typically raise). The one
-    audit sink for the framework: the request guards, masquerade grants,
-    sign-ins, and anything else security-relevant write here. ``user_sub`` is
-    the identity provider's subject; ``detail`` a JSON-able dict of facts that
-    have no column; ``occurred_at`` when it happened, if not now (an event
-    relayed through a queue). Silent when the table is not provisioned in this site, and
-    an audit failure never breaks the request. Returns True when a row was
-    written.
+    """Append one ``sys_security_events`` row on its own short transaction.
+    The one audit sink for the framework: the request guards, masquerade
+    grants, sign-ins, privileged decisions (``authz.require``), and anything
+    else security-relevant write here. ``user_sub`` is the identity provider's
+    subject; ``detail`` a JSON-able dict of facts that have no column;
+    ``occurred_at`` when it happened, if not now (an event relayed through a
+    queue). Silent when the table is not provisioned in this site, and an
+    audit failure never breaks the request. Returns True only once the row is
+    committed.
+
+    ``tx`` is the caller's transaction and is only used for its engine: the
+    row is written and committed through ``tx.engine.side_transaction()``
+    (another connection, which never waits for the pool), so it survives whatever the caller does next (raise,
+    roll back) and the caller's transaction is left exactly as it was: its
+    writes stay uncommitted, and its ``SET LOCAL`` settings (the audit actor),
+    row locks and transaction-level advisory locks are kept. A ``tx`` with no
+    engine (a test double) gets the row written on itself, uncommitted. On
+    PostgreSQL the event transaction's audit actor (``velocity.actor``, for a
+    ``sys_security_events`` under the audit trigger's ``require_actor``) is
+    ``actor`` when given, else the one the caller set with
+    :func:`velocity.db.audit.set_audit_actor`. Callers that record before any
+    actor is set (the request guards, the masquerade grant) pass their own.
 
     A table created before ``user_sub``/``detail`` existed (a site whose schema
     lane has not run since) still records the row without them: on a locked
     schema an unknown column would otherwise lose the whole event."""
+    facts = dict(
+        aws_event=aws_event,
+        context=context,
+        user_email=user_email,
+        user_sub=user_sub,
+        detail=detail,
+        occurred_at=occurred_at,
+    )
     try:
-        table = tx.table(EVENTS_TABLE)
-        if not table.exists():
-            return False
-        facts = request_facts(aws_event)
-        row = {
-            "guard": guard,
-            "reason": reason,
-            "ip": facts["ip"],
-            "country": facts["country"],
-            "path": facts["path"],
-            "action": _action(context) if context is not None else "",
-            "user_email": user_email,
-            "user_agent": facts["user_agent"][:512],
-        }
-        extra = {
-            "user_sub": user_sub,
-            "detail": detail,
-            "occurred_at": occurred_at or datetime.datetime.now(datetime.timezone.utc),
-        }
-        extra = {k: v for k, v in extra.items() if v is not None}
-        if extra:
-            try:
-                have = {c.lower() for c in table.sys_columns()}
-            except Exception:
-                # can't tell which newer columns exist: the event still lands
-                # with the columns every version of the table has
-                log.warning("security event %s: columns unknown", guard, exc_info=True)
-                have = set()
-            row.update({k: v for k, v in extra.items() if k in have})
-        table.insert(row)
-        tx.commit()
-        return True
+        open_transaction = getattr(
+            getattr(tx, "engine", None), "side_transaction", None
+        )
+        if not callable(open_transaction):
+            return _write_event(tx, guard, reason, **facts)
+        postgres = "postgres" in str(_pgddl.server_name(tx) or "").lower()
+        if postgres and not actor:
+            actor = _caller_actor(tx)
+        # the row is committed when the block exits; a commit failure raises
+        # out of it, so True is never returned for a row that isn't durable
+        with open_transaction() as event_tx:
+            if postgres:
+                # one round trip: the bounded lock wait, and the caller's audit
+                # actor (a sys_security_events under the audit trigger's
+                # require_actor still records)
+                event_tx.execute(
+                    "SELECT set_config('lock_timeout', %s, true), "
+                    "set_config(%s, %s, true)",
+                    (EVENT_LOCK_TIMEOUT, audit.ACTOR_SETTING, actor or ""),
+                )
+            return _write_event(event_tx, guard, reason, **facts)
     except Exception:
         log.warning("security event %s not recorded", guard, exc_info=True)
         return False
 
 
+def _caller_actor(tx):
+    """The audit actor :func:`velocity.db.audit.set_audit_actor` set on the
+    caller's transaction, or None. Read from the transaction object only:
+    running a statement on the caller's connection here could hit a dead
+    connection, and swallowing that error would lose the caller's
+    mid-transaction failure (R31) — its next write would land on a fresh
+    connection."""
+    value = getattr(tx, "_audit_actor", None)
+    return value if isinstance(value, str) and value else None
+
+
+def _write_event(
+    tx, guard, reason, *, aws_event, context, user_email, user_sub, detail, occurred_at
+):
+    table = tx.table(EVENTS_TABLE)
+    if not table.exists():
+        return False
+    facts = request_facts(aws_event)
+    row = {
+        "guard": guard,
+        "reason": reason,
+        "ip": facts["ip"],
+        "country": facts["country"],
+        "path": facts["path"],
+        "action": _action(context) if context is not None else "",
+        "user_email": user_email,
+        "user_agent": facts["user_agent"][:512],
+    }
+    extra = {
+        "user_sub": user_sub,
+        "detail": detail,
+        "occurred_at": occurred_at or datetime.datetime.now(datetime.timezone.utc),
+    }
+    extra = {k: v for k, v in extra.items() if v is not None}
+    if extra:
+        try:
+            have = {c.lower() for c in table.sys_columns()}
+        except Exception:
+            # can't tell which newer columns exist: the event still lands
+            # with the columns every version of the table has
+            log.warning("security event %s: columns unknown", guard, exc_info=True)
+            have = set()
+        row.update({k: v for k, v in extra.items() if k in have})
+    table.insert(row)
+    return True
+
+
 def _user_email(context):
     try:
         session = context.session() or {}

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity/aws/handlers/lambda_handler.py

@@ -8,7 +8,7 @@ from typing import Optional
 
 from velocity.aws import ssm_config
 from velocity.aws.handlers.base_handler import BaseHandler
-from velocity.aws.handlers.exceptions import UserNotProvisionedError
+from velocity.aws.handlers.exceptions import AccessError, UserNotProvisionedError
 from velocity.aws.handlers.context_factory import ContextFactory
 from velocity.aws.handlers.response import Response
 from velocity.logging import configure_logging
@@ -116,11 +116,12 @@ class LambdaHandler(BaseHandler):
                 )
                 # Persist the audit the docstring promises: who acted as whom,
                 # from where. Goes to the framework's one security audit sink
-                # (sys_security_events, the Security Events page); silent when
-                # that table is not provisioned here, never breaks the request.
+                # (sys_security_events, the Security Events page), on its own
+                # transaction: this request's tx stays open. Fail-closed, as
+                # authz.require is: no audit row, no masquerade.
                 from velocity.aws.capabilities.security import record_event
 
-                record_event(
+                recorded = record_event(
                     tx,
                     "masquerade",
                     f"{grant['real_user']} acting as {grant['effective_user']} "
@@ -128,7 +129,14 @@ class LambdaHandler(BaseHandler):
                     aws_event=self.aws_event,
                     context=context,
                     user_email=grant["real_user"],
+                    # recorded before any request actor is set; the actor
+                    # format AuditTrailMixin uses under masquerade
+                    actor=f"{grant['effective_user']} as {grant['real_user']}",
                 )
+                if not recorded:
+                    raise AccessError(
+                        "That masquerade could not be recorded, so it was refused."
+                    )
 
         if masquerade or auth_mode == "none":
             # In masquerade mode the caller's own Cognito token is for a

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity/db/audit.py

@@ -172,11 +172,20 @@ def set_audit_actor(tx, actor: Optional[str]) -> None:
     explicit ``tx.commit()``. ``None`` / ``""`` clears it (the trigger then
     records ``db:<session_user>``). A no-op off PostgreSQL, where there is no
     trigger to read it.
+
+    The value is also kept on the transaction (``tx._audit_actor``, cleared at
+    its commit, rollback or connection release; not undone by a savepoint
+    rollback) so a side transaction can carry it over without querying this
+    connection (:func:`velocity.aws.capabilities.security.record_event`).
     """
     if not _pgddl.is_postgres(tx):
         return
     value = "" if actor is None else str(actor)
     tx.execute("SELECT set_config(%s, %s, true)", (ACTOR_SETTING, value))
+    try:
+        tx._audit_actor = value or None
+    except AttributeError:  # a transaction double that refuses attributes
+        pass
 
 
 # ── trigger DDL ───────────────────────────────────────────────────────────

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity/db/core/engine.py

@@ -199,16 +199,27 @@ class ConnectionPool:
     # Public API
     # ------------------------------------------------------------------
 
-    def getconn(self):
-        """Borrow a connection from the pool (blocking if exhausted)."""
+    def getconn(self, *, wait=True):
+        """Borrow a connection from the pool (blocking if exhausted).
+
+        ``wait=False`` never waits: with no free slot it raises
+        ``DbConnectionError`` at once."""
         if self._closed:
             raise exceptions.DbConnectionError("Connection pool is closed")
 
         t0 = time.perf_counter()
-        # R24 — bounded wait for a free slot. Without a timeout an exhausted
-        # pool blocks until the surrounding Lambda/request itself times out,
-        # which masks the real problem and wastes the whole invocation window.
-        acquired = self._available.acquire(timeout=self._acquire_timeout)
+        if not wait:
+            if not self._available.acquire(blocking=False):
+                raise exceptions.DbConnectionError(
+                    f"Connection pool exhausted (maxconn={self._maxconn}); "
+                    f"not waiting for a slot."
+                )
+            acquired = True
+        else:
+            # R24 — bounded wait for a free slot. Without a timeout an exhausted
+            # pool blocks until the surrounding Lambda/request itself times out,
+            # which masks the real problem and wastes the whole invocation window.
+            acquired = self._available.acquire(timeout=self._acquire_timeout)
         if not acquired:
             raise exceptions.DbConnectionError(
                 f"Connection pool exhausted: no connection available within "
@@ -478,16 +489,19 @@ class Engine:
             self.__pool = None
             self.__pool_enabled = False
 
-    def connect(self):
+    def connect(self, *, wait=True):
         """
         Connects to the database and returns the connection object.
         If pooling is enabled, borrows from the pool.
         If the database is missing, tries to create it, then reconnect.
+
+        ``wait=False`` never waits for a pool slot: with none free right now
+        it opens a direct (unpooled) connection instead.
         """
         t0 = time.perf_counter()
         if self.__pool:
             try:
-                conn = self.__pool.getconn()
+                conn = self.__pool.getconn(wait=wait)
                 elapsed_ms = (time.perf_counter() - t0) * 1000
                 logger.debug(
                     "Engine.connect: obtained pooled connection (%.1f ms)", elapsed_ms
@@ -495,7 +509,7 @@ class Engine:
                 return conn
             except exceptions.DbDatabaseMissingError:
                 self.create_database()
-                return self.__pool.getconn()
+                return self.__pool.getconn(wait=wait)
             except Exception:
                 # Pool may have failed to connect — fall through to direct.
                 pass
@@ -596,6 +610,18 @@ class Engine:
             # Never let adapter registration break connection establishment.
             pass
 
+    def side_transaction(self):
+        """A new :class:`Transaction` for a short write taken while another
+        transaction of this thread is open (an audit row that must commit on
+        its own, whatever the request's transaction does next). Use it as
+        ``with engine.side_transaction() as tx:``.
+
+        It never waits for the pool: it leases a free slot if one is free right
+        now, else opens a direct connection. Waiting could only end when the
+        caller's own transaction, which holds a slot, finishes — a pool of one
+        would stall for the acquire timeout, or forever with none."""
+        return Transaction(self, wait_for_pool=False)
+
     def transaction(self, func_or_cls=None):
         """
         Decorator that provides a Transaction. If `tx` is passed in, uses it; otherwise, creates a new one.

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity/db/core/transaction.py

@@ -343,9 +343,17 @@ class Transaction:
     Encapsulates a single transaction in the database (connection + commit/rollback).
     """
 
-    def __init__(self, engine, connection=None):
+    def __init__(self, engine, connection=None, *, wait_for_pool=True):
         self.engine = engine
         self.connection = connection
+        # False (Engine.side_transaction): lease a pool slot only if one is
+        # free now, else connect directly — never wait on the pool.
+        self._wait_for_pool = wait_for_pool
+        # The audit actor velocity.db.audit.set_audit_actor set on this
+        # transaction (velocity.actor is transaction-local, so it is cleared
+        # at commit, rollback and connection release). Read by code that must
+        # carry it to another transaction without querying this connection.
+        self._audit_actor = None
         self.__pg_types = {}
         # Track whether this connection came from the pool and should be returned.
         self.__pooled = False  # set per leased connection (TX-7)
@@ -445,7 +453,10 @@ class Transaction:
                 "or Row used after the block must be consumed inside it."
             )
         try:
-            conn = self.engine.connect()
+            if getattr(self, "_wait_for_pool", True):
+                conn = self.engine.connect()
+            else:
+                conn = self.engine.connect(wait=False)
         except exceptions.DbException as e:
             if getattr(e, "tx", None) is None:
                 e.tx = self
@@ -472,6 +483,7 @@ class Transaction:
         self.connection = None
         self.__pooled = False
         self._in_progress = False
+        self._audit_actor = None
         if conn is None:
             return
         returned = False
@@ -844,6 +856,7 @@ class Transaction:
                 raise self._db_error(e)
             # Work is durably committed; the transaction is clean again.
             self._in_progress = False
+            self._audit_actor = None
             if self._query_count:
                 _logger.debug(
                     "Transaction commit: %d queries in %.1f ms",
@@ -934,6 +947,7 @@ class Transaction:
             self.connection.rollback()
             # Transaction is clean again — no uncommitted work pending.
             self._in_progress = False
+        self._audit_actor = None
 
     def is_aborted(self):
         """Return True if the connection is in a failed/aborted transaction.

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity_python.egg-info/PKG-INFO

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

{velocity_python-0.3.0 → velocity_python-0.3.1}/src/velocity_python.egg-info/SOURCES.txt

@@ -385,6 +385,8 @@ tests/test_query_missing_table_unlocked.py
 tests/test_raw_sql_prefix_policy.py
 tests/test_read_cache.py
 tests/test_readme_imports.py
+tests/test_record_event_postgres.py
+tests/test_record_event_transaction.py
 tests/test_response.py
 tests/test_restricted_direct_tables.py
 tests/test_result_returning.py

{velocity_python-0.3.0 → velocity_python-0.3.1}/tests/test_connection_pool.py

@@ -358,3 +358,78 @@ class TestAcquireTimeout:
         monkeypatch.setenv("VELOCITY_POOL_ACQUIRE_TIMEOUT", "7")
         eng = _make_engine()
         assert eng.pool._acquire_timeout == 7
+
+
+class TestNoWaitAcquire:
+    """``wait=False`` (Engine.side_transaction): never wait on the pool."""
+
+    def test_exhausted_pool_refuses_at_once_without_waiting(self):
+        pool = ConnectionPool(
+            _make_connect_fn(), minconn=0, maxconn=1, validate=False, acquire_timeout=0
+        )
+        held = pool.getconn()
+        t0 = time.time()
+        with pytest.raises(exceptions.DbConnectionError):
+            pool.getconn(wait=False)
+        assert time.time() - t0 < 0.5
+        pool.putconn(held)
+        assert pool.getconn(wait=False) is held  # a free slot is still used
+
+    def test_engine_connects_directly_when_no_slot_is_free(self):
+        eng = _make_engine(pool_enabled=True, pool_min=0, pool_max=1)
+        held = eng.connect()
+        direct = eng.connect(wait=False)
+        assert direct is not held and not eng.is_pooled_connection(direct)
+        eng.return_pooled_connection(held)
+
+    def test_side_transaction_does_not_wait_and_closes_its_direct_connection(self):
+        eng = _make_engine(pool_enabled=True, pool_min=0, pool_max=1)
+        with Transaction(eng) as outer:
+            outer.cursor()
+            t0 = time.time()
+            with eng.side_transaction() as side:
+                side.cursor()
+                conn = side.connection
+                assert not eng.is_pooled_connection(conn)
+            assert time.time() - t0 < 0.5
+            conn.close.assert_called()
+            assert eng.is_pooled_connection(outer.connection)
+
+    def test_concurrent_no_wait_acquires_keep_the_slot_count_balanced(self):
+        pool = ConnectionPool(
+            _make_connect_fn(), minconn=0, maxconn=2, validate=False, acquire_timeout=0
+        )
+        lock = threading.Lock()
+        state = {"held": 0, "peak": 0, "refused": 0, "leased": 0}
+
+        def worker():
+            for _ in range(200):
+                try:
+                    conn = pool.getconn(wait=False)
+                except exceptions.DbConnectionError:
+                    with lock:
+                        state["refused"] += 1
+                    continue
+                with lock:
+                    state["held"] += 1
+                    state["leased"] += 1
+                    state["peak"] = max(state["peak"], state["held"])
+                time.sleep(0)
+                with lock:
+                    state["held"] -= 1
+                pool.putconn(conn)
+
+        threads = [threading.Thread(target=worker) for _ in range(8)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+        assert not any(t.is_alive() for t in threads)
+        assert state["peak"] <= 2 and state["leased"] > 0
+        assert state["leased"] + state["refused"] == 8 * 200
+        # balanced: exactly maxconn slots are free again, no more
+        a, b = pool.getconn(wait=False), pool.getconn(wait=False)
+        with pytest.raises(exceptions.DbConnectionError):
+            pool.getconn(wait=False)
+        pool.putconn(a)
+        pool.putconn(b)

{velocity_python-0.3.0 → velocity_python-0.3.1}/tests/test_lambda_handler_masquerade.py

@@ -1,5 +1,8 @@
 import unittest
+from unittest.mock import patch
 
+from velocity.aws.capabilities import security
+from velocity.aws.handlers.exceptions import AccessError
 from velocity.aws.handlers.lambda_handler import LambdaHandler
 from velocity.aws.handlers.masquerade import mint_grant
 
@@ -188,7 +191,91 @@ class TestLambdaHandlerMasquerade(unittest.TestCase):
         self.assertEqual(event["user_email"], ADMIN)
         self.assertIn("acting as donor@example.com on donor_users", event["reason"])
         self.assertEqual(event["action"], "do-thing")
-        self.assertEqual(tx.commits, 1)  # the audit row is committed on its own
+        # the audit never commits the request's transaction (a real engine
+        # writes it on its own; see test_record_event_transaction)
+        self.assertEqual(tx.commits, 0)
+
+    def test_a_masquerade_that_cannot_be_recorded_is_refused(self):
+        # fail-closed like authz.require: no audit row, no masquerade (the
+        # table not provisioned, no connection, a write failure)
+        token = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=TARGET,
+            pool="donor_users",
+        )
+        ctx = _Context(grant_token=token)
+        tx = _Tx(
+            {"donor@example.com": {"email_address": "donor@example.com", "sys_id": 7}}
+        )
+        h = _make_handler()
+        with patch.object(security, "record_event", return_value=False) as rec:
+            with self.assertRaisesRegex(AccessError, "could not be recorded"):
+                h.beforeAction(tx=tx, context=ctx)
+        rec.assert_called_once()
+        self.assertEqual(h.current_user, {})
+        self.assertEqual(tx.events, [])
+
+    def test_the_masquerade_event_names_its_own_audit_actor(self):
+        # recorded before AuditTrailMixin sets the request's actor: under an
+        # events table with require_actor it would otherwise be refused
+        token = mint_grant(
+            SECRET, real_user=ADMIN, effective_user=TARGET, pool="donor_users"
+        )
+        ctx = _Context(grant_token=token)
+        tx = _Tx(
+            {"donor@example.com": {"email_address": "donor@example.com", "sys_id": 7}}
+        )
+        with patch.object(security, "record_event", return_value=True) as rec:
+            _make_handler().beforeAction(tx=tx, context=ctx)
+        self.assertEqual(rec.call_args.kwargs["actor"], f"{TARGET} as {ADMIN}")
+
+
+class TestRefusedMasqueradeThroughServe(unittest.TestCase):
+    """serve(): the refusal is a 403 with the reason, after a rollback."""
+
+    def test_a_masquerade_that_cannot_be_recorded_is_a_403(self):
+        import json
+        from unittest.mock import MagicMock
+
+        token = mint_grant(
+            SECRET, real_user=ADMIN, effective_user=TARGET, pool="donor_users"
+        )
+        aws_event = {
+            "headers": {"X-CC-Masquerade": token},
+            "queryStringParameters": {},
+            "body": json.dumps({"action": "do-thing", "payload": {}}),
+        }
+        h = _Handler(
+            aws_event=aws_event,
+            aws_context=type("C", (), {"aws_request_id": "rid"})(),
+        )
+        h.auth_mode = "required"
+        h.user_table = "donor_users"
+        ran = []
+        h.OnActionDoThing = lambda tx, context: ran.append(True)
+        tx = MagicMock()
+        with (
+            patch(
+                "velocity.aws.handlers.context.config_getenv",
+                side_effect=lambda name, default=None: (
+                    SECRET if name == "MasqueradeSigningKey" else default
+                ),
+            ),
+            patch.object(security, "record_event", return_value=False),
+        ):
+            rendered = h.serve(tx)
+        self.assertEqual(rendered["statusCode"], 403)
+        body = json.loads(rendered["body"])
+        self.assertEqual(
+            body,
+            {
+                "ok": False,
+                "message": "That masquerade could not be recorded, so it was refused.",
+            },
+        )
+        tx.rollback.assert_called_once()
+        self.assertEqual(ran, [])
 
 
 if __name__ == "__main__":