velocity-python 0.2.1__tar.gz → 0.2.2__tar.gz

{velocity_python-0.2.1/src/velocity_python.egg-info → velocity_python-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.2.1
+Version: 0.2.2
 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.1 → velocity_python-0.2.2}/pyproject.toml

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

{velocity_python-0.2.1 → velocity_python-0.2.2}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.1"
+__version__ = version = "0.2.2"
 
 import importlib as _importlib
 

velocity_python-0.2.2/src/velocity/aws/authz.py

@@ -0,0 +1,428 @@
+"""Who may do what, decided in one place.
+
+One pure function answers every authorization question::
+
+    can(principal, action, resource, context) -> Decision
+
+* **Deny by default.** Nothing is allowed unless a rule permits it.
+* **A forbid beats any permit.**
+* **An error can only take access away.** A permit rule whose condition
+  raises is skipped; a forbid rule whose condition raises forbids. Either
+  way the rule is named in ``Decision.errors`` and logged.
+* **No I/O.** A decision is id comparisons and set lookups. Whoever already
+  loaded the row passes its owner in; this module never loads data.
+
+Rules are data, declared beside the feature they govern and registered once
+at import::
+
+    from velocity.aws import authz
+
+    RULES = (
+        authz.permit("notes.own", {"notes.read", "notes.write"}, when=authz.owner),
+        authz.permit("notes.read_any", "notes.read",
+                     when=authz.holds("notes.read_any"), audit=True),
+        authz.forbid("notes.masquerade_write", "notes.write",
+                     when=authz.masquerading),
+    )
+    authz.register(*RULES)
+
+Permissions are plain names a principal holds. Code never checks a role:
+a role is a bundle of permissions, and which bundle a user gets is the
+site's decision (``principal_permissions`` on the handler).
+
+**On a handler.** :func:`principal_for` builds the principal from the user
+row the handler already loaded; :func:`decide` asks; :func:`require` asks,
+refuses with a 403, and records the use of any rule marked ``audit`` in
+``sys_security_events`` *before* the access happens (no audit row, no
+access). The handler attributes they read:
+
+==========================  ================================================
+``authz_mode``              ``"off"`` (default), ``"log"`` or ``"enforce"``:
+                            how the *existing* generic surfaces (the
+                            DataService table gate) use the decision. New
+                            actions written against :func:`require` are
+                            always enforced.
+``authz_rules``             a handler's own rules, beside the registered ones
+``principal_permissions``   ``(current_user) -> iterable of names``; the
+                            default grants none
+==========================  ================================================
+
+The request shape and the decision rule are those of AWS's Cedar policy
+language, on purpose: the rules can move there without changing a caller.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from fnmatch import fnmatchcase
+from typing import Any, Callable, Optional
+
+from velocity.aws import ssm_config
+from velocity.aws.handlers.exceptions import AccessError
+
+logger = logging.getLogger(__name__)
+
+PERMIT = "permit"
+FORBID = "forbid"
+
+OFF = "off"
+LOG = "log"
+ENFORCE = "enforce"
+MODES = (OFF, LOG, ENFORCE)
+
+# The action the DataService table gate asks about, and its resource type.
+DATA_ACCESS = "data.access"
+TABLE = "table"
+SYSTEM_PREFIX = "sys_"
+
+# The audit sink's ``guard`` value for a use of an ``audit`` rule.
+PRIVILEGED_ACCESS = "privileged_access"
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Who is asking. ``user_sys_id`` is the row id in the site's user table
+    (never an email). ``real_user`` is set in a masquerade session: the
+    administrator who is acting as this user."""
+
+    user_sys_id: Optional[int] = None
+    permissions: frozenset = frozenset()
+    tenant: Any = None
+    real_user: Any = None
+
+    def holds(self, permission):
+        return permission in self.permissions
+
+
+@dataclass(frozen=True)
+class Resource:
+    """The specific object: its type, id, owner (a user row id) and tenant."""
+
+    type: str
+    id: Any = None
+    owner: Optional[int] = None
+    tenant: Any = None
+
+
+@dataclass(frozen=True)
+class Rule:
+    name: str
+    effect: str
+    actions: frozenset
+    when: Optional[Callable] = None
+    audit: bool = False
+
+    def covers(self, action):
+        return any(
+            action == pattern or ("*" in pattern and fnmatchcase(action, pattern))
+            for pattern in self.actions
+        )
+
+
+@dataclass(frozen=True)
+class Decision:
+    """The answer. ``rule`` is the rule that decided (``None`` when nothing
+    permitted); ``audit`` is true when that rule's use must be recorded."""
+
+    allowed: bool
+    action: str
+    rule: Optional[str] = None
+    audit: bool = False
+    errors: tuple = field(default_factory=tuple)
+
+    def __bool__(self):
+        return self.allowed
+
+
+def _rule(effect, name, actions, when, audit):
+    if not isinstance(name, str) or not name:
+        raise ValueError("A rule needs a name.")
+    if isinstance(actions, str):
+        actions = (actions,)
+    actions = frozenset(actions or ())
+    if not actions or not all(isinstance(a, str) and a for a in actions):
+        raise ValueError(f"Rule '{name}' names no action.")
+    if when is not None and not callable(when):
+        raise ValueError(f"Rule '{name}': 'when' must be callable.")
+    return Rule(name, effect, actions, when, bool(audit))
+
+
+def permit(name, actions, *, when=None, audit=False):
+    """Allow ``actions`` (a name, or names; ``*`` is a wildcard) when
+    ``when(principal, action, resource, context)`` is true. ``audit=True``
+    marks a privileged rule: each use is recorded."""
+    return _rule(PERMIT, name, actions, when, audit)
+
+
+def forbid(name, actions, *, when=None):
+    """Refuse ``actions`` when ``when(...)`` is true, whatever permits."""
+    return _rule(FORBID, name, actions, when, False)
+
+
+# ── conditions ─────────────────────────────────────────────────────────────
+
+
+def owner(principal, action, resource, context):
+    """The resource belongs to the principal."""
+    return (
+        principal.user_sys_id is not None
+        and resource is not None
+        and resource.owner is not None
+        and resource.owner == principal.user_sys_id
+    )
+
+
+def masquerading(principal, action, resource, context):
+    """An administrator is acting as this user."""
+    return principal.real_user is not None or bool((context or {}).get("masquerade"))
+
+
+def signed_in(principal, action, resource, context):
+    return principal.user_sys_id is not None
+
+
+def holds(permission):
+    """The principal holds the named permission."""
+
+    def condition(principal, action, resource, context):
+        return principal.holds(permission)
+
+    return condition
+
+
+def table(*names):
+    """The resource is one of these tables."""
+    wanted = frozenset(names)
+
+    def condition(principal, action, resource, context):
+        return resource is not None and resource.type == TABLE and resource.id in wanted
+
+    return condition
+
+
+def all_of(*conditions):
+    def condition(principal, action, resource, context):
+        return all(c(principal, action, resource, context) for c in conditions)
+
+    return condition
+
+
+def any_of(*conditions):
+    def condition(principal, action, resource, context):
+        return any(c(principal, action, resource, context) for c in conditions)
+
+    return condition
+
+
+def _ordinary_table(principal, action, resource, context):
+    return (
+        resource is not None
+        and resource.type == TABLE
+        and isinstance(resource.id, str)
+        and not resource.id.startswith(SYSTEM_PREFIX)
+    )
+
+
+# ── the registry ───────────────────────────────────────────────────────────
+
+# Until each site declares rules per table, an ordinary table stays reachable
+# through the generic Data actions exactly as the table gate, the rwx hooks
+# and the tenant scope already allow. System tables (``sys_…``) get no such
+# rule: they are refused unless the handler declares one.
+BUILTIN_RULES = (permit("data.ordinary_tables", DATA_ACCESS, when=_ordinary_table),)
+
+_REGISTERED = {}
+
+
+def register(*rules):
+    """Add rules to the ones every handler evaluates. Registering the same
+    rule again is a no-op; a different rule under a taken name is an error."""
+    for rule in rules:
+        if not isinstance(rule, Rule):
+            raise ValueError("register() takes rules made by permit() or forbid().")
+        known = _REGISTERED.get(rule.name)
+        if known is not None and known != rule:
+            raise ValueError(f"An authorization rule named '{rule.name}' exists.")
+        _REGISTERED[rule.name] = rule
+
+
+def registered():
+    """Every rule a handler evaluates before its own."""
+    return BUILTIN_RULES + tuple(_REGISTERED.values())
+
+
+# ── the decision ───────────────────────────────────────────────────────────
+
+
+def can(principal, action, resource=None, context=None, *, rules=None):
+    """Decide. See the module docstring for the rule."""
+    rules = registered() if rules is None else tuple(rules)
+    context = context or {}
+    permitted = None
+    errors = []
+    if not isinstance(principal, Principal) or not isinstance(action, str):
+        return Decision(False, str(action))
+    for rule in rules:
+        if not rule.covers(action):
+            continue
+        try:
+            matched = rule.when is None or bool(
+                rule.when(principal, action, resource, context)
+            )
+        except Exception:
+            logger.warning(
+                "authorization rule %s failed on %s", rule.name, action, exc_info=True
+            )
+            errors.append(rule.name)
+            # an error can only take access away
+            matched = rule.effect == FORBID
+        if not matched:
+            continue
+        if rule.effect == FORBID:
+            return Decision(False, action, rule.name, False, tuple(errors))
+        if permitted is None:
+            permitted = rule
+    if permitted is None:
+        return Decision(False, action, None, False, tuple(errors))
+    return Decision(True, action, permitted.name, permitted.audit, tuple(errors))
+
+
+# ── on a handler ───────────────────────────────────────────────────────────
+
+
+def mode_of(handler):
+    """``AuthzMode`` config first, then the handler's ``authz_mode``. Blank
+    is ``off``; a value that is not a mode is ``enforce`` (fail closed)."""
+    raw = None
+    try:
+        raw = ssm_config.getenv("AuthzMode", None)
+    except Exception:
+        raw = None
+    raw = str(raw or getattr(handler, "authz_mode", None) or OFF).strip().lower()
+    return raw if raw in MODES else ENFORCE
+
+
+def _session(context):
+    try:
+        return context.session() or {}
+    except Exception:
+        return {}
+
+
+def principal_for(handler, context=None):
+    """The principal for the request ``handler`` is serving, from the user
+    row it already loaded. No query."""
+    user = getattr(handler, "current_user", None) or {}
+    try:
+        user_sys_id = int(user.get("sys_id"))
+    except (TypeError, ValueError, AttributeError):
+        user_sys_id = None
+    if user_sys_id is not None and user_sys_id <= 0:
+        user_sys_id = None
+    permissions = ()
+    hook = getattr(handler, "principal_permissions", None)
+    if callable(hook) and user_sys_id is not None:
+        try:
+            permissions = hook(user) or ()
+        except Exception:
+            # no permissions is the safe answer
+            logger.warning("principal_permissions failed", exc_info=True)
+            permissions = ()
+    context = context if context is not None else getattr(handler, "context", None)
+    masquerade = _session(context).get("masquerade") if context is not None else None
+    real_user = None
+    if masquerade:
+        real_user = (
+            masquerade.get("real_user") if isinstance(masquerade, dict) else None
+        ) or True
+    return Principal(
+        user_sys_id=user_sys_id,
+        permissions=frozenset(p for p in permissions if isinstance(p, str)),
+        tenant=user.get("tenant") if isinstance(user, dict) else None,
+        real_user=real_user,
+    )
+
+
+def rules_for(handler):
+    return registered() + tuple(getattr(handler, "authz_rules", None) or ())
+
+
+def decide(handler, action, resource=None, context=None):
+    """The decision for the request ``handler`` is serving."""
+    principal = principal_for(handler, context)
+    facts = {"masquerade": principal.real_user is not None}
+    return can(principal, action, resource, facts, rules=rules_for(handler))
+
+
+def require(handler, tx, context, action, resource=None):
+    """Decide and enforce, whatever ``authz_mode`` says: for actions written
+    against the policy. A denial raises :class:`AccessError` (403). A use of
+    an ``audit`` rule is recorded first, and refused when it cannot be."""
+    decision = decide(handler, action, resource, context)
+    if not decision.allowed:
+        logger.warning(
+            "authorization refused %s on %s (%s)",
+            action,
+            _describe(resource),
+            decision.rule or "no rule permits it",
+        )
+        raise AccessError("You do not have access to that.")
+    if decision.audit and not _record(handler, tx, context, decision, resource):
+        raise AccessError("That access could not be recorded, so it was refused.")
+    return decision
+
+
+_WOULD_REFUSE = set()
+
+
+def gate(handler, action, resource=None):
+    """The decision for an EXISTING generic surface, under ``authz_mode``:
+    ``off`` allows without asking, ``log`` asks and logs what it would
+    refuse (once per container per action and resource) and allows,
+    ``enforce`` returns the decision's answer."""
+    mode = mode_of(handler)
+    if mode == OFF:
+        return True
+    decision = decide(handler, action, resource)
+    if decision.allowed:
+        return True
+    if mode == LOG:
+        key = (action, getattr(resource, "type", None), getattr(resource, "id", None))
+        if key not in _WOULD_REFUSE:
+            _WOULD_REFUSE.add(key)
+            logger.warning(
+                "authz (log only) would refuse %s on %s (%s)",
+                action,
+                _describe(resource),
+                decision.rule or "no rule permits it",
+            )
+        return True
+    return False
+
+
+def _describe(resource):
+    if resource is None:
+        return "-"
+    return f"{resource.type}:{resource.id}"
+
+
+def _record(handler, tx, context, decision, resource):
+    # imported here: the capabilities package pulls in more than a pure
+    # decision module should load at import
+    from velocity.aws.capabilities.security import record_event
+
+    session = _session(context)
+    actor = (
+        (session.get("masquerade") or {}).get("real_user")
+        if isinstance(session.get("masquerade"), dict)
+        else None
+    ) or session.get("email_address")
+    return record_event(
+        tx,
+        PRIVILEGED_ACCESS,
+        f"{decision.action} on {_describe(resource)} by rule {decision.rule}",
+        aws_event=getattr(handler, "aws_event", None),
+        context=context,
+        user_email=actor,
+    )

{velocity_python-0.2.1 → velocity_python-0.2.2}/src/velocity/aws/handlers/mixins/data_service.py

@@ -13,7 +13,7 @@ import re
 from io import BytesIO
 from types import MappingProxyType
 
-from velocity.aws import dirty_pipeline, ssm_config
+from velocity.aws import authz, dirty_pipeline, ssm_config
 from velocity.aws import facets
 from velocity.aws.handlers.exceptions import AccessError, AlertError, BadRequestError
 from velocity.aws.handlers.mixins.client_input import MODES, STRICT, ClientInputGuard
@@ -72,6 +72,9 @@ def _fk_blocked_delete_message(table, exc):
 
 
 _IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+# Owner-scoped tables already warned about under the legacy client SQL mode
+# (once per container, not once per request).
+_OWNER_SCOPE_WARNED = set()
 
 
 TEXT_TYPES = frozenset(
@@ -695,6 +698,44 @@ class DataServiceMixin:
     client_denied_tables = frozenset()
     client_allowed_tables = None
 
+    # The authorization decision point (velocity.aws.authz) at the client
+    # table gate. ``"off"`` (default): the gate is as above. ``"log"``: every
+    # table is also put to the rules and what they would refuse is logged,
+    # nothing is refused. ``"enforce"``: a table no rule permits is refused.
+    # The ``AuthzMode`` config key overrides this per environment. Out of the
+    # box the rules permit every ordinary table and NO system table
+    # (``sys_…``): a handler that serves one in a grid declares it, e.g.
+    #   authz_rules = (authz.permit("flags.admin", authz.DATA_ACCESS,
+    #       when=authz.all_of(authz.table("sys_feature_flags"),
+    #                         authz.holds("site.admin"))),)
+    # ``principal_permissions(current_user)`` says which permissions the
+    # signed-in user holds; the default is none.
+    authz_mode = authz.OFF
+    authz_rules = ()
+
+    def principal_permissions(self, current_user):
+        return ()
+
+    # Tables whose every row belongs to ONE signed-in user: ``{table: owner
+    # column}``. The owner column holds the user's sign-in email as the
+    # session carries it. Each hooked action (query, find, read, write,
+    # delete) confines the caller to their own rows, and the direct actions
+    # refuse the table — the rule ``tenant_scope`` gives a site, applied by
+    # the framework itself and resolved BEFORE the site's ``tenant_scope``,
+    # so an override that forgets ``super()`` cannot switch it off.
+    #
+    # ``user_data`` is here because the framework owns it: per-user settings
+    # written by ``store-user-data`` and read back by the browser through the
+    # generic ``query``, which until this rule let any signed-in user read or
+    # overwrite another user's rows by naming their ``userid``.
+    #
+    # Enforced under the strict client SQL mode. Under legacy mode the
+    # browser can send raw SQL around any row predicate, so nothing here can
+    # be a boundary: the rule is skipped and a warning is logged, leaving
+    # legacy behaviour exactly as it was. Set the attribute to ``{}`` to opt
+    # a handler out.
+    owner_scoped_tables = MappingProxyType({"user_data": "userid"})
+
     # How much SQL-shaped input the boundary accepts from the browser
     # (velocity.aws.handlers.mixins.client_input): "strict" (Contract C — dict
     # filters, plain columns, structured @@search) or "legacy" (string
@@ -795,7 +836,9 @@ class DataServiceMixin:
         if table in self.client_denied_tables:
             return False
         allowed = self.client_allowed_tables
-        return allowed is None or table in allowed
+        if allowed is not None and table not in allowed:
+            return False
+        return authz.gate(self, authz.DATA_ACCESS, authz.Resource(authz.TABLE, table))
 
     def _assert_client_table(self, table, label="table"):
         """The table gate every client action passes (SEC 4.2)."""
@@ -914,9 +957,12 @@ class DataServiceMixin:
             )
 
     def _assert_direct_unscoped(self, table, context):
-        """A tenant-scoped table is never reachable through a direct action
-        (they cannot apply the scope)."""
-        if self.tenant_scope(context, table) is not None:
+        """A tenant-scoped or owner-scoped table is never reachable through a
+        direct action (they cannot apply the scope)."""
+        if (
+            self._owner_scope(context, table) is not None
+            or self.tenant_scope(context, table) is not None
+        ):
             raise AlertError(
                 f"Direct access to '{table}' is not permitted; "
                 "use the standard data actions."
@@ -995,11 +1041,47 @@ class DataServiceMixin:
         """
         return None
 
+    def _owner_scope(self, context, table):
+        """``(column, values)`` confining ``table`` to the signed-in user, or
+        ``None`` when the table is not in :attr:`owner_scoped_tables` — or
+        when this handler runs the legacy client SQL mode, where no row
+        predicate is a boundary (see the attribute's comment).
+
+        The values are the session's email as it stands and lowercased: rows
+        written before emails were normalized keep matching. The first value
+        is the one stamped on a new row. A session without an email is
+        refused."""
+        column = (self.owner_scoped_tables or {}).get(table)
+        if not column:
+            return None
+        if self.client_sql_mode_effective != STRICT:
+            if table not in _OWNER_SCOPE_WARNED:
+                _OWNER_SCOPE_WARNED.add(table)
+                logger.warning(
+                    "%s rows are not confined to their owner: this handler "
+                    "runs the legacy client SQL mode, under which no row rule "
+                    "can be enforced. Move it to strict mode.",
+                    table,
+                )
+            return None
+        session = context.session() if hasattr(context, "session") else None
+        email = (session or {}).get("email_address")
+        if not isinstance(email, str) or not email.strip():
+            raise AlertError("Access denied: no signed-in user for this session.")
+        email = email.strip()
+        return column, tuple(dict.fromkeys((email, email.lower())))
+
     def _resolve_tenant_scope(self, tx, table, context):
         """``(column, values)`` for ``table``, or ``None`` (unscoped). Fails
         closed: a scope under any client SQL mode but strict, a malformed
-        scope, an empty value, or a table without the column is refused."""
-        scope = self.tenant_scope(context, table)
+        scope, an empty value, or a table without the column is refused.
+
+        A table in :attr:`owner_scoped_tables` takes the framework's owner
+        scope; the site's :meth:`tenant_scope` is not consulted for it."""
+        scope = self._owner_scope(context, table)
+        owned = scope is not None
+        if scope is None:
+            scope = self.tenant_scope(context, table)
         if scope is None:
             return None
         # The predicate is only a boundary when the client cannot send raw
@@ -1030,7 +1112,12 @@ class DataServiceMixin:
         except Exception:  # noqa: BLE001 — unknown schema is not scoped schema
             available = set()
         if column.lower() not in available:
-            raise AlertError(f"Access denied: {table} is not tenant-scoped.")
+            # An owner-scoped table that does not exist yet (user_data on a
+            # fresh site, before anyone has saved a setting) has no rows to
+            # confine: keep the scope and let the read come back empty, as it
+            # did before. A table that exists WITHOUT the column is refused.
+            if not (owned and not available):
+                raise AlertError(f"Access denied: {table} is not tenant-scoped.")
         return column, values
 
     @staticmethod
@@ -1066,10 +1153,12 @@ class DataServiceMixin:
                     f"Access denied: {column} must be one of your own values."
                 )
         if not keys and creating:
-            if len(values) != 1:
+            if len(values) != 1 and table not in (self.owner_scoped_tables or {}):
                 raise AlertError(
                     f"Access denied: choose the {column} for this {table} record."
                 )
+            # an owner scope's values are one person's email in two spellings:
+            # the first is the session's own
             incoming[column] = values[0]
 
     def _check_tenant_row(self, table, scope, row):