velocity-python 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

velocity/__init__.py

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

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/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