velocity-python 0.2.8__tar.gz → 0.2.9__tar.gz

{velocity_python-0.2.8/src/velocity_python.egg-info → velocity_python-0.2.9}/PKG-INFO

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

{velocity_python-0.2.8 → velocity_python-0.2.9}/pyproject.toml

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

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.8"
+__version__ = version = "0.2.9"
 
 import importlib as _importlib
 

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity/aws/authz.py

@@ -935,6 +935,33 @@ def is_protected(table_name):
     return table_name in _PROTECTED
 
 
+# Tables whose rows are confidential (the security audit: everyone's sign-ins,
+# addresses, refusals). The generic Data actions READ them only on a handler
+# that lists the table in ``confidential_reads`` (an explicit opt-in, e.g. an
+# operators-only console), in every mode: ``gate`` records nothing, so even a
+# permitted read there would be unaudited.
+_CONFIDENTIAL = set()
+
+
+def confidential_tables(*names):
+    """Mark tables generic Data reads refuse unless the handler opts in (see
+    ``DataServiceMixin.confidential_reads``), whatever ``authz_mode`` says.
+    Combine with :func:`protect_tables` to refuse writes as well."""
+    _CONFIDENTIAL.update(name for name in names if isinstance(name, str) and name)
+
+
+def is_confidential(table_name):
+    return table_name in _CONFIDENTIAL
+
+
+# velocity's own audit sink (capabilities.security.EVENTS_TABLE): append-only
+# and confidential on every site, registered here so the rule never depends on
+# which modules a handler happened to import (VelocityAudit SEC-12 follow-up).
+SECURITY_EVENTS_TABLE = "sys_security_events"
+protect_tables(SECURITY_EVENTS_TABLE)
+confidential_tables(SECURITY_EVENTS_TABLE)
+
+
 # ── the action index ───────────────────────────────────────────────────────
 
 # id(rules tuple) -> (the tuple, {key: its rules in order}), where key is the
@@ -1319,6 +1346,15 @@ def _describe(resource):
     return f"{resource.type}:{resource.id}"
 
 
+def record_confidential_read(handler, tx, context, table):
+    """Record one generic read of a confidential table by a handler that opted
+    in (``confidential_reads``) as ``privileged_access``; False when it could
+    not be recorded (the caller refuses the read). The opt-in serves an
+    operators-only console; every use of it is still on the record."""
+    decision = Decision(True, rule="confidential_reads", audit=True, action=DATA_READ)
+    return bool(_record(handler, tx, context, decision, Resource(TABLE, table)))
+
+
 def _record(handler, tx, context, decision, resource):
     # imported here: the capabilities package pulls in more than a pure
     # decision module should load at import
@@ -1330,6 +1366,16 @@ def _record(handler, tx, context, decision, resource):
         if isinstance(session.get("masquerade"), dict)
         else None
     ) or session.get("email_address")
+    # the subject API Gateway's authorizer verified (the real caller, also
+    # under masquerade), and its issuer, so the record names an identity and
+    # not only an email
+    sub = session.get("sub") or None
+    provider = session.get("authentication_provider")
+    issuer = session.get("iss") or (
+        "https://" + provider.split(",", 1)[0].strip()
+        if isinstance(provider, str) and provider.strip()
+        else None
+    )
     return record_event(
         tx,
         PRIVILEGED_ACCESS,
@@ -1337,4 +1383,6 @@ def _record(handler, tx, context, decision, resource):
         aws_event=getattr(handler, "aws_event", None),
         context=context,
         user_email=actor,
+        user_sub=sub,
+        detail={"iss": issuer} if issuer else None,
     )

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity/aws/capabilities/security.py

@@ -20,6 +20,15 @@ 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.
+
+``sys_security_events`` itself is a CORE table (``SCHEMA``, in
+``velocity.aws.schema``'s ``core`` group), not the capability's: it is
+velocity's one audit sink — refusals, masquerade grants, sign-ins — and every
+site keeps it whether or not the guards are on (VelocityAudit SEC-12: with the
+table capability-owned, a site without ``security`` silently dropped its
+masquerade audit). Pruning stays here (``security_events_days``, default 365 to
+match a one-year audit retention); a site without the capability lists the
+table in the ``retention`` capability instead.
 """
 
 from __future__ import annotations
@@ -46,6 +55,48 @@ log = logging.getLogger(__name__)
 
 EVENTS_TABLE = "sys_security_events"
 RATE_TABLE = "sys_rate_limit"
+EVENT_COLUMNS = {
+    "guard": "TEXT",
+    "reason": "TEXT",
+    "ip": "TEXT",
+    "country": "TEXT",
+    "path": "TEXT",
+    "action": "TEXT",
+    "user_email": "TEXT",
+    "user_agent": "TEXT",
+    "user_sub": "TEXT",
+    "detail": "JSONB",
+    # when it happened (a sign-in trigger fired), which a queue can write
+    # later than sys_created; defaults to the time of writing
+    "occurred_at": "TIMESTAMPTZ",
+}
+# Append-only and confidential on every site: authz registers the table as
+# protected (no generic write) and confidential (generic reads need an opt-in
+# or enforce) itself, so the rule holds whether or not this module is imported.
+# core infrastructure (velocity.aws.schema "core"): every site has the table
+SCHEMA = {
+    EVENTS_TABLE: {
+        "columns": dict(EVENT_COLUMNS),
+        "indexes": [
+            {
+                "columns": ["sys_created"],
+                "name": "idx__sys_security_events__sys_created",
+            },
+            {
+                "columns": ["guard", "sys_created"],
+                "name": "idx__sys_security_events__guard",
+            },
+            {
+                "columns": ["user_sub", "sys_created"],
+                "name": "idx__sys_security_events__user_sub",
+            },
+            {
+                "columns": ["user_sub", "occurred_at"],
+                "name": "idx__sys_security_events__user_sub_occurred",
+            },
+        ],
+    },
+}
 CACHE_TTL_SECONDS = 60  # per-container cache of the switches + site row
 
 SWITCHES = {
@@ -59,7 +110,7 @@ SWITCHES = {
 KNOBS = {
     "security_rate_limit_per_minute": "120",
     "security_payload_max_bytes": "1000000",
-    "security_events_days": "90",
+    "security_events_days": "365",
 }
 
 
@@ -275,30 +326,62 @@ def enforce(tx, aws_event, context, *, now=None):
     return config
 
 
-def record_event(tx, guard, reason, *, aws_event=None, context=None, user_email=None):
+def record_event(
+    tx,
+    guard,
+    reason,
+    *,
+    aws_event=None,
+    context=None,
+    user_email=None,
+    user_sub=None,
+    detail=None,
+    occurred_at=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, and
-    anything else security-relevant write here. 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."""
+    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.
+
+    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."""
     try:
         table = tx.table(EVENTS_TABLE)
         if not table.exists():
             return False
         facts = request_facts(aws_event)
-        table.insert(
-            {
-                "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],
-            }
-        )
+        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
     except Exception:
@@ -386,16 +469,9 @@ class Security(Capability):
         ),
     )
     schema = {
-        EVENTS_TABLE: {
-            "guard": "TEXT",
-            "reason": "TEXT",
-            "ip": "TEXT",
-            "country": "TEXT",
-            "path": "TEXT",
-            "action": "TEXT",
-            "user_email": "TEXT",
-            "user_agent": "TEXT",
-        },
+        # the events table is core (module SCHEMA); listed here too so turning
+        # the capability on in an older site still ensures it
+        EVENTS_TABLE: dict(EVENT_COLUMNS),
         RATE_TABLE: {"bucket": "TEXT", "window_start": "TIMESTAMPTZ", "hits": "BIGINT"},
     }
     schedules = (("prune", HOURLY),)
@@ -407,7 +483,7 @@ class Security(Capability):
         if action != "prune":
             raise ValueError(f"security: unknown action {action!r}")
         now = datetime.datetime.now(datetime.timezone.utc)
-        days = int(config.get("security_events_days") or 90)
+        days = int(config.get("security_events_days") or 365)
         return {
             "rate_buckets": tx.table(RATE_TABLE).purge(
                 {"<sys_created": now - datetime.timedelta(hours=1)}

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity/aws/handlers/mixins/data_service.py

@@ -588,6 +588,7 @@ class ExportStream:
     def __enter__(self):
         handler, payload = self.handler, self.payload
         handler._assert_client_table(self.table, "obj")
+        handler._audit_confidential_read(self.tx, self.table, self.context)
         # ``table`` is the only source: it is what passed the table gate and
         # whose hooks and scope run below, so a payload ``obj`` naming any
         # other table is refused rather than read.
@@ -915,6 +916,11 @@ class DataServiceMixin:
     # handler, not in the gate methods' signatures, so a site's override of
     # those keeps working.
     _table_operation = authz.DATA_READ
+    # Confidential tables (``authz.confidential_tables``) this handler serves
+    # to generic reads: an explicit opt-in for a console whose every user is
+    # an operator. Without it such a table is never read through generic Data
+    # (in any authz mode); it is read through its own audited action.
+    confidential_reads = frozenset()
 
     def _client_table_allowed(self, table):
         # lower case only: velocity lower-cases every Table name and
@@ -937,10 +943,30 @@ class DataServiceMixin:
         # ``authz_mode`` say.
         if self._table_operation != authz.DATA_READ and authz.is_protected(table):
             return False
+        # Confidential tables (``authz.confidential_tables``: the security
+        # audit) are read through generic Data only where the handler opted
+        # in. Never by default, and not under ``enforce`` either: ``gate``
+        # answers allow/deny but records nothing, so a super user's read would
+        # go unaudited; the table's own action (``authz.require``) records it.
+        if authz.is_confidential(table) and table not in self.confidential_reads:
+            return False
         return authz.gate(
             self, self._table_operation, authz.Resource(authz.TABLE, table)
         )
 
+    def _audit_confidential_read(self, tx, table, context):
+        """A generic read of a confidential table (only reachable on a handler
+        that lists it in ``confidential_reads``) is recorded as privileged
+        access first, and refused when it can't be: the opt-in keeps an
+        operators' grid working without making its reads invisible. Called by
+        the read ACTIONS right after their table gate (query, read-object,
+        find-object, query-direct, export), never from an overridable seam,
+        so a site's hook override can't skip it."""
+        if not authz.is_confidential(table):
+            return
+        if not authz.record_confidential_read(self, tx, context, table):
+            raise AccessError("That access could not be recorded, so it was refused.")
+
     def _assert_client_table(self, table, label="table"):
         """The table gate every client action passes (SEC 4.2)."""
         ClientInputGuard.table_name(table, label)
@@ -1022,7 +1048,11 @@ class DataServiceMixin:
             if not info:
                 continue
             foreign = info["referenced_table_name"]
-            if not self._client_table_allowed(foreign):
+            # never into a confidential table: its reads are audited by the
+            # actions that open it by name, and a join would skip that
+            if authz.is_confidential(foreign) or not self._client_table_allowed(
+                foreign
+            ):
                 raise AlertError(f"Access to '{table}.{local}>' is not permitted.")
             # A join reads the foreign table's rows without that table's row
             # filter. So someone who reaches only part of it cannot read it
@@ -2053,6 +2083,7 @@ class DataServiceMixin:
         if not obj:
             raise ValueError("Parameter 'object' cannot be empty")
         self._assert_client_table(table_name, "tableName")
+        self._audit_confidential_read(tx, table_name, context)
         if not isinstance(obj, dict):
             raise BadRequestError("Parameter 'object' must be an object")
         if obj.get("sys_id") != NEW_ROW:
@@ -2094,6 +2125,7 @@ class DataServiceMixin:
         if not query or "where" not in query:
             raise ValueError("Parameter 'query' must contain 'where' clause")
         self._assert_client_table(table_name, "tableName")
+        self._audit_confidential_read(tx, table_name, context)
         query["where"] = self._client_where(tx, table_name, query["where"])
 
         row = self.find_hook(
@@ -2254,6 +2286,7 @@ class DataServiceMixin:
         if not table:
             raise ValueError("Parameter 'obj' cannot be empty")
         self._assert_client_table(table, "obj")
+        self._audit_confidential_read(tx, table, context)
         payload["params"] = self._client_query_params(tx, table, payload.get("params"))
 
         result_format = payload.get("result_format")
@@ -2438,6 +2471,7 @@ class DataServiceMixin:
 
         self._assert_direct_access_allowed(table_name)
         self._assert_direct_unscoped(table_name, context)
+        self._audit_confidential_read(tx, table_name, context)
 
         params = self._client_query_params(tx, table_name, payload.get("params", {}))
 

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity/aws/handlers/mixins/tiles_actions.py

@@ -112,6 +112,10 @@ class TilesMixin:
         rule with the viewer filled in, and that where."""
         table = tile["target"]
         self._assert_client_table(table, "target")
+        # A confidential table (the security audit) is never a tile target:
+        # a saved, re-counted filter over it would be an unaudited oracle.
+        if authz.is_confidential(table):
+            raise AlertError(f"'{table}' can't be counted on a tile.")
         rule = tiles.fill_rule(
             tiles.clean_rule(_as_dict(tile.get("rule"))),
             principal,
@@ -218,7 +222,10 @@ class TilesMixin:
             return declared is not None and (
                 not declared.permission or principal.holds(declared.permission)
             )
-        return bool(self._client_table_allowed(str(tile.get("target") or "")))
+        target = str(tile.get("target") or "")
+        if authz.is_confidential(target):
+            return False
+        return bool(self._client_table_allowed(target))
 
     def _tile_public(self, tx, context, tile, principal, today, fresh=False, version=0):
         """One tile as the browser gets it, or None when it is not this

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity/aws/schema.py

@@ -21,7 +21,8 @@ renames or retypes an existing column.
 
 Groups:
 
-* ``core`` — the tables every velocity handler app writes.
+* ``core`` — the tables every velocity handler app writes, including the
+  ``sys_security_events`` audit sink (SEC-12).
 * ``assets`` — ``images`` + ``asset_usage_index`` (:mod:`velocity.aws.assets`).
 * ``payment`` — processor mirror tables (:mod:`velocity.payment.schema`).
 * ``permissions`` — roles, grants and requests (:mod:`velocity.aws.permissions`).
@@ -50,6 +51,7 @@ SCHEMA_SOURCES: Dict[str, Tuple[str, ...]] = {
         "velocity.aws.handlers.mixins.web_handler",
         "velocity.aws.handlers.mixins.session_control",
         "velocity.aws.user_data",
+        "velocity.aws.capabilities.security",
         "velocity.db.migrations",
     ),
     "assets": ("velocity.aws.assets",),

{velocity_python-0.2.8 → velocity_python-0.2.9/src/velocity_python.egg-info}/PKG-INFO

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

{velocity_python-0.2.8 → velocity_python-0.2.9}/src/velocity_python.egg-info/SOURCES.txt

@@ -377,6 +377,7 @@ tests/test_schema_lock_config_other_backends.py
 tests/test_schema_migrations.py
 tests/test_search_paging_export.py
 tests/test_security_capability.py
+tests/test_security_events_table_gate.py
 tests/test_security_hardening.py
 tests/test_server_cursor.py
 tests/test_session_control.py

{velocity_python-0.2.8 → velocity_python-0.2.9}/tests/test_ensure_infrastructure.py

@@ -74,6 +74,7 @@ def test_core_declares_every_velocity_owned_runtime_table():
         "lambda_metrics",
         "user_data",
         "sys_user_data",
+        "sys_security_events",
         "app_session",
         "sys_feature_flags",
         "sys_capabilities",

{velocity_python-0.2.8 → velocity_python-0.2.9}/tests/test_security_capability.py

@@ -41,10 +41,17 @@ class FakeTable:
         return 3
 
     exists_flag = True
+    # sys_columns() of the live table; None = every declared events column
+    columns = None
 
     def exists(self):
         return self.exists_flag
 
+    def sys_columns(self):
+        if self.columns is not None:
+            return list(self.columns)
+        return ["sys_id", "sys_created", *sec.EVENT_COLUMNS]
+
 
 class FakeTx:
     def __init__(self):
@@ -305,3 +312,73 @@ def test_capability_declares_schema_switches_and_prunes_with_purge():
     assert "<sys_created" in tx.table(sec.EVENTS_TABLE).purges[0]
     with pytest.raises(ValueError):
         cap.handle("nope", tx, None, {})
+
+
+# -- sys_security_events as velocity's core audit sink (SEC-12, Paul 2026-10-25)
+
+
+def test_record_event_stores_subject_and_detail():
+    tx = FakeTx()
+    ok = sec.record_event(
+        tx,
+        "auth.login",
+        "signed in",
+        user_email="staff@example.com",
+        user_sub="sub-123",
+        detail={"client_id": "abc", "new_device": True},
+    )
+    assert ok is True and tx.commits == 1
+    row = tx.table(sec.EVENTS_TABLE).rows[0]
+    assert row["guard"] == "auth.login" and row["user_sub"] == "sub-123"
+    assert row["detail"] == {"client_id": "abc", "new_device": True}
+
+
+def test_record_event_on_a_table_older_than_the_new_columns_still_records():
+    # a site whose schema lane has not added user_sub/detail yet: on a locked
+    # schema the unknown columns would lose the whole event, so they are left out
+    tx = FakeTx()
+    table = tx.table(sec.EVENTS_TABLE)
+    table.columns = ["sys_id", "guard", "reason", "ip", "user_email"]
+    assert sec.record_event(tx, "masquerade.start", "x", user_sub="s", detail={"a": 1})
+    row = table.rows[0]
+    assert row["guard"] == "masquerade.start"
+    assert "user_sub" not in row and "detail" not in row
+
+
+def test_every_event_says_when_it_occurred():
+    tx = FakeTx()
+    assert sec.record_event(tx, "ip_denylist", "listed")
+    row = tx.table(sec.EVENTS_TABLE).rows[0]
+    assert row["occurred_at"].tzinfo is not None
+    when = datetime.datetime(2026, 10, 25, 15, tzinfo=datetime.timezone.utc)
+    assert sec.record_event(tx, "auth.login", "signed in", occurred_at=when)
+    assert tx.table(sec.EVENTS_TABLE).rows[1]["occurred_at"] == when
+
+
+def test_events_table_is_core_and_retention_defaults_to_a_year():
+    from velocity.aws import schema as infra
+
+    core = infra.infrastructure_schema()
+    assert core[sec.EVENTS_TABLE]["columns"]["detail"] == "JSONB"
+    assert core[sec.EVENTS_TABLE]["columns"]["user_sub"] == "TEXT"
+    assert sec.KNOBS["security_events_days"] == "365"
+    # the capability still declares it, so enabling it on an older site ensures it
+    assert sec.Security_instance().schema[sec.EVENTS_TABLE] == sec.EVENT_COLUMNS
+    tx = FakeTx()
+    sec.Security_instance().handle("prune", tx, None, {})
+    cutoff = tx.table(sec.EVENTS_TABLE).purges[0]["<sys_created"]
+    age = datetime.datetime.now(datetime.timezone.utc) - cutoff
+    assert 364 < age.days <= 365
+
+
+def test_an_event_still_lands_when_the_columns_cannot_be_read():
+    tx = FakeTx()
+    table = tx.table(sec.EVENTS_TABLE)
+
+    def broken():
+        raise RuntimeError("catalog unavailable")
+
+    table.sys_columns = broken
+    assert sec.record_event(tx, "masquerade", "acting as x", user_sub="s")
+    row = table.rows[0]
+    assert row["guard"] == "masquerade" and "user_sub" not in row