velocity-python 0.1.62__tar.gz → 0.1.66__tar.gz

{velocity_python-0.1.62 → velocity_python-0.1.66}/PKG-INFO

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

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

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.62"
+__version__ = version = "0.1.66"
 
 import importlib as _importlib
 

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/aws/handlers/context.py

@@ -167,6 +167,43 @@ class Context:
         self.perf.set_enabled(enabled)
         return enabled
 
+    # Header (case-insensitive) carrying a signed masquerade grant minted by an
+    # authorized administrative service. See velocity.aws.handlers.masquerade.
+    MASQUERADE_HEADER = "x-cc-masquerade"
+
+    def get_masquerade_grant(self):
+        """Return the verified masquerade grant payload for this request, or None.
+
+        The grant is read from the ``x-cc-masquerade`` header and verified
+        against the ``MasqueradeSigningKey`` config value. Returns ``None`` when
+        the feature is off (no key), no header is present, or the grant is
+        invalid/expired — callers then fall back to normal identity. A present
+        but invalid grant is logged and treated as absent (fail closed).
+        """
+        headers = self.__aws_event.get("headers") or {}
+        token = None
+        for name, value in headers.items():
+            if isinstance(name, str) and name.lower() == self.MASQUERADE_HEADER:
+                token = value
+                break
+        if not token:
+            return None
+
+        secret = config_getenv("MasqueradeSigningKey", "") or ""
+        if not secret:
+            logger.warning(
+                "Masquerade grant header present but MasqueradeSigningKey is not configured"
+            )
+            return None
+
+        from velocity.aws.handlers.masquerade import MasqueradeError, verify_grant
+
+        try:
+            return verify_grant(secret, token)
+        except MasqueradeError as exc:
+            logger.warning("Rejected masquerade grant: %s", exc)
+            return None
+
     def _build_session(self, aws_event):
         request_context = aws_event.get("requestContext") or {}
         identity = request_context.get("identity") or {}

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/aws/handlers/lambda_handler.py

@@ -69,7 +69,40 @@ class LambdaHandler(BaseHandler):
             auth_mode = "none"
             require_db_user = False
 
-        if auth_mode == "none":
+        # Masquerade: a signed grant lets an authorized admin act as another
+        # user. When a valid grant scoped to this app's user_table is present,
+        # the request identity resolves to the target (effective_user) exactly
+        # as if they had signed in, while the real admin is retained for audit.
+        # The grant signature is verified in context.get_masquerade_grant().
+        masquerade = None
+        if (
+            auth_mode != "none"
+            and getattr(self, "allow_masquerade", True)
+            and getattr(self, "user_table", None)
+        ):
+            grant = context.get_masquerade_grant()
+            if grant and grant.get("pool") == self.user_table:
+                masquerade = grant
+                session["real_user"] = grant["real_user"]
+                session["email_address"] = grant["effective_user"]
+                session["masquerade"] = {
+                    "real_user": grant["real_user"],
+                    "effective_user": grant["effective_user"],
+                    "pool": grant["pool"],
+                    "jti": grant.get("jti"),
+                    "exp": grant.get("exp"),
+                }
+                logger.info(
+                    "Masquerade active: %s acting as %s on %s",
+                    grant["real_user"],
+                    grant["effective_user"],
+                    grant["pool"],
+                )
+
+        if masquerade or auth_mode == "none":
+            # In masquerade mode the caller's own Cognito token is for a
+            # different pool (e.g. the admin pool), so skip the pool-scoped
+            # Cognito lookup; identity comes from the verified grant instead.
             self.cognito_user = None
         else:
             context.perf.start("get_cognito_user")

velocity_python-0.1.66/src/velocity/aws/handlers/masquerade.py

@@ -0,0 +1,150 @@
+"""Signed masquerade (impersonation) grants.
+
+A masquerade grant is a compact, HMAC-SHA256 signed token that authorizes one
+identity (``real_user``) to act as another (``effective_user``) within a named
+scope (``pool``) for a short window. It is the trust vehicle for admin
+"masquerade as user" sessions: an administrative service mints a grant after
+authorizing the operation, and the target application verifies the grant's
+signature before resolving the request's identity to ``effective_user`` while
+retaining ``real_user`` for audit.
+
+The format is intentionally small and dependency-free (no JWT library):
+
+    base64url(payload_json) + "." + base64url(hmac_sha256(secret, body))
+
+Payload claims:
+
+    real_user        identity performing the masquerade (e.g. admin email)
+    effective_user   identity being acted as (e.g. donor/client email)
+    pool             scope the grant is valid for (e.g. "client_users")
+    iat              issued-at unix seconds
+    exp              expiry unix seconds
+    jti              unique id for one-time-use / revocation tracking
+
+This module is business-agnostic: it knows nothing about CaringCent pools,
+Cognito, or specific apps. Callers supply the secret and claim values.
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets as _secrets
+import time
+
+__all__ = [
+    "MasqueradeError",
+    "mint_grant",
+    "verify_grant",
+    "DEFAULT_TTL_SECONDS",
+]
+
+DEFAULT_TTL_SECONDS = 900  # 15 minutes
+
+
+class MasqueradeError(Exception):
+    """Raised when a masquerade grant is malformed, unsigned, or expired."""
+
+
+def _b64u_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _b64u_decode(value: str) -> bytes:
+    padding = "=" * (-len(value) % 4)
+    return base64.urlsafe_b64decode(value + padding)
+
+
+def _secret_bytes(secret) -> bytes:
+    if secret is None:
+        raise MasqueradeError("Masquerade signing secret is not configured")
+    if isinstance(secret, bytes):
+        secret_bytes = secret
+    else:
+        secret_bytes = str(secret).encode("utf-8")
+    if not secret_bytes:
+        raise MasqueradeError("Masquerade signing secret is empty")
+    return secret_bytes
+
+
+def _sign(secret_bytes: bytes, body: str) -> str:
+    digest = hmac.new(secret_bytes, body.encode("ascii"), hashlib.sha256).digest()
+    return _b64u_encode(digest)
+
+
+def mint_grant(
+    secret,
+    *,
+    real_user: str,
+    effective_user: str,
+    pool: str,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    jti: str = None,
+    now: int = None,
+) -> str:
+    """Create a signed masquerade grant string.
+
+    ``real_user``, ``effective_user`` and ``pool`` are required and must be
+    non-empty. ``ttl_seconds`` bounds validity; ``jti`` defaults to a random id.
+    """
+    real_user = (real_user or "").strip()
+    effective_user = (effective_user or "").strip()
+    pool = (pool or "").strip()
+    if not real_user or not effective_user or not pool:
+        raise MasqueradeError("real_user, effective_user and pool are required")
+    if ttl_seconds <= 0:
+        raise MasqueradeError("ttl_seconds must be positive")
+
+    issued = int(now if now is not None else time.time())
+    payload = {
+        "real_user": real_user,
+        "effective_user": effective_user,
+        "pool": pool,
+        "iat": issued,
+        "exp": issued + int(ttl_seconds),
+        "jti": jti or _secrets.token_urlsafe(16),
+    }
+    body = _b64u_encode(
+        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    )
+    signature = _sign(_secret_bytes(secret), body)
+    return f"{body}.{signature}"
+
+
+def verify_grant(secret, token, *, now: int = None) -> dict:
+    """Verify a grant's signature and expiry, returning its payload.
+
+    Raises :class:`MasqueradeError` if the token is malformed, the signature
+    does not match, the payload is structurally invalid, or it has expired.
+    """
+    if not token or not isinstance(token, str) or "." not in token:
+        raise MasqueradeError("Malformed masquerade grant")
+
+    body, _, signature = token.partition(".")
+    expected = _sign(_secret_bytes(secret), body)
+    # Constant-time comparison to avoid signature timing oracles.
+    if not hmac.compare_digest(signature, expected):
+        raise MasqueradeError("Masquerade grant signature mismatch")
+
+    try:
+        payload = json.loads(_b64u_decode(body).decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise MasqueradeError("Masquerade grant payload is not valid JSON") from exc
+
+    if not isinstance(payload, dict):
+        raise MasqueradeError("Masquerade grant payload is not an object")
+
+    for field in ("real_user", "effective_user", "pool", "exp"):
+        if not payload.get(field):
+            raise MasqueradeError(f"Masquerade grant missing '{field}'")
+
+    current = int(now if now is not None else time.time())
+    try:
+        expires = int(payload["exp"])
+    except (TypeError, ValueError) as exc:
+        raise MasqueradeError("Masquerade grant 'exp' is not an integer") from exc
+
+    if current >= expires:
+        raise MasqueradeError("Masquerade grant has expired")
+
+    return payload

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/aws/handlers/mixins/web_handler.py

@@ -461,12 +461,17 @@ Request Details:
         data = context.get_pass_through_vars(tx)
         current_user = getattr(self, "current_user", None) or {}
         context.response().load_object(current_user)
+        controls = {
+            **data.get("controls", {}),
+            "current_user": current_user,
+        }
+        # When the session is a masquerade, surface it so the UI can show the
+        # admin's real identity alongside the user they are acting as.
+        masquerade = (context.session() or {}).get("masquerade")
+        controls["masquerade"] = masquerade or None
         context.response().update_store(
             {
-                "controls": {
-                    **data.get("controls", {}),
-                    "current_user": current_user,
-                },
+                "controls": controls,
                 "repo": {
                     "current_user": current_user,
                 },

velocity_python-0.1.66/src/velocity/db/core/jsonproxy.py

@@ -0,0 +1,175 @@
+"""
+Live list/dict proxies for JSON column values.
+
+A ``list`` or ``dict`` stored in a row is just a JSON column (JSONB on
+PostgreSQL).  ``Row.__getitem__`` wraps such values in :class:`BoundList` /
+:class:`BoundDict` so in-place mutation writes the whole value back through
+the owning row::
+
+    row["tags"].append("vip")          # UPDATE ... SET tags = '["a","vip"]'
+    row["meta"]["verified"] = True     # whole "meta" value written back
+
+There are no relation declarations and no diffing: every mutation persists
+the complete top-level value.  Nested containers share the root's flush, so
+a deep mutation also writes the root value back.
+"""
+
+
+class _Controller:
+    """Shared link between a root proxy and all of its nested proxies."""
+
+    __slots__ = ("flush", "root")
+
+    def __init__(self, flush):
+        self.flush = flush
+        self.root = None
+
+    def notify(self):
+        self.flush(unwrap(self.root))
+
+
+def bind(value, flush):
+    """
+    Wrap ``value`` (a dict or list) in a bound proxy tree.
+
+    ``flush(plain_value)`` is called with the plain (unwrapped) top-level
+    value after every mutation anywhere in the tree.  Non-container values
+    are returned unchanged.
+    """
+    if not isinstance(value, (dict, list)):
+        return value
+    ctrl = _Controller(flush)
+    root = _wrap(value, ctrl)
+    ctrl.root = root
+    return root
+
+
+def unwrap(value):
+    """Return a plain dict/list copy of a (possibly bound) value tree."""
+    if isinstance(value, dict):
+        return {k: unwrap(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [unwrap(v) for v in value]
+    return value
+
+
+def _wrap(value, ctrl):
+    if isinstance(value, dict):
+        return BoundDict(value, ctrl)
+    if isinstance(value, list):
+        return BoundList(value, ctrl)
+    return value
+
+
+class BoundList(list):
+    """A list whose mutations flush the root value back to its column."""
+
+    def __init__(self, iterable, ctrl):
+        super().__init__(_wrap(v, ctrl) for v in iterable)
+        self._ctrl = ctrl
+
+    # -- mutators ------------------------------------------------------
+    def __setitem__(self, index, value):
+        if isinstance(index, slice):
+            value = [_wrap(v, self._ctrl) for v in value]
+        else:
+            value = _wrap(value, self._ctrl)
+        super().__setitem__(index, value)
+        self._ctrl.notify()
+
+    def __delitem__(self, index):
+        super().__delitem__(index)
+        self._ctrl.notify()
+
+    def __iadd__(self, other):
+        self.extend(other)
+        return self
+
+    def __imul__(self, n):
+        result = super().__imul__(n)
+        self._ctrl.notify()
+        return result
+
+    def append(self, value):
+        super().append(_wrap(value, self._ctrl))
+        self._ctrl.notify()
+
+    def extend(self, iterable):
+        super().extend(_wrap(v, self._ctrl) for v in iterable)
+        self._ctrl.notify()
+
+    def insert(self, index, value):
+        super().insert(index, _wrap(value, self._ctrl))
+        self._ctrl.notify()
+
+    def remove(self, value):
+        super().remove(value)
+        self._ctrl.notify()
+
+    def pop(self, index=-1):
+        result = super().pop(index)
+        self._ctrl.notify()
+        return result
+
+    def clear(self):
+        super().clear()
+        self._ctrl.notify()
+
+    def sort(self, **kwds):
+        super().sort(**kwds)
+        self._ctrl.notify()
+
+    def reverse(self):
+        super().reverse()
+        self._ctrl.notify()
+
+
+class BoundDict(dict):
+    """A dict whose mutations flush the root value back to its column."""
+
+    def __init__(self, mapping, ctrl):
+        super().__init__({k: _wrap(v, ctrl) for k, v in mapping.items()})
+        self._ctrl = ctrl
+
+    # -- mutators ------------------------------------------------------
+    def __setitem__(self, key, value):
+        super().__setitem__(key, _wrap(value, self._ctrl))
+        self._ctrl.notify()
+
+    def __delitem__(self, key):
+        super().__delitem__(key)
+        self._ctrl.notify()
+
+    def update(self, dict_=None, **kwds):
+        data = {}
+        if dict_:
+            data.update(dict_)
+        data.update(kwds)
+        for k, v in data.items():
+            super().__setitem__(k, _wrap(v, self._ctrl))
+        if data:
+            self._ctrl.notify()
+
+    def pop(self, key, *args):
+        existed = key in self
+        result = super().pop(key, *args)
+        if existed:
+            self._ctrl.notify()
+        return result
+
+    def popitem(self):
+        result = super().popitem()
+        self._ctrl.notify()
+        return result
+
+    def clear(self):
+        super().clear()
+        self._ctrl.notify()
+
+    def setdefault(self, key, default=None):
+        if key in self:
+            return self[key]
+        wrapped = _wrap(default, self._ctrl)
+        super().__setitem__(key, wrapped)
+        self._ctrl.notify()
+        return wrapped

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/db/core/row.py

@@ -2,6 +2,7 @@ import pprint
 import time as _time
 from collections.abc import MutableMapping
 from velocity.db.exceptions import DbColumnMissingError
+from velocity.db.core import jsonproxy
 
 
 # Attributes that live on the Row instance itself and must never be
@@ -133,9 +134,24 @@ class Row(MutableMapping):
             return self.pk[key]
         cache = self._ensure_cache()
         if key in cache:
-            return cache[key]
+            val = cache[key]
+            # JSON columns come back as plain dict/list — wrap them in live
+            # proxies so in-place mutation writes the whole value back.
+            if isinstance(val, (dict, list)) and not isinstance(
+                val, (jsonproxy.BoundDict, jsonproxy.BoundList)
+            ):
+                val = jsonproxy.bind(
+                    val, lambda plain, _k=key: self.__setitem__(_k, plain)
+                )
+                cache[key] = val
+            return val
         # Fall back to a direct DB fetch for columns not in the initial SELECT
-        return self.table.get_value(key, self.pk)
+        val = self.table.get_value(key, self.pk)
+        if isinstance(val, (dict, list)):
+            val = jsonproxy.bind(
+                val, lambda plain, _k=key: self.__setitem__(_k, plain)
+            )
+        return val
 
     def __setitem__(self, key, val):
         if key in self.pk:
@@ -327,7 +343,7 @@ class Row(MutableMapping):
         """
         Returns the row as a dictionary (from cache or via a SELECT on self.pk).
         """
-        return dict(self._ensure_cache())
+        return {k: jsonproxy.unwrap(v) for k, v in self._ensure_cache().items()}
 
     def extract(self, *args):
         """

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/db/core/table.py

@@ -1984,12 +1984,21 @@ class Table:
         _ddl_logger.warning("DDL ALTER COLUMN TYPE on %s column=%s", self.name, column)
         self.tx.execute(sql, vals, cursor=self.cursor())
 
+    def _adapt_data(self, data):
+        """
+        Apply the dialect's data-value adaptation (e.g. dict/list -> JSONB on
+        PostgreSQL, JSON text elsewhere) to a column->value mapping.  Used for
+        INSERT/UPDATE data only — WHERE values keep native driver adaptation.
+        """
+        adapt = self.sql.adapt_data_value
+        return {k: adapt(v) for k, v in data.items()}
+
     @create_missing
     def update(self, data, where=None, pk=None, **kwds):
         """
         Performs an UPDATE of rows matching `where` or `pk` with `data`.
         """
-        sql, vals = self.sql.update(self.tx, self.name, data, where, pk)
+        sql, vals = self.sql.update(self.tx, self.name, self._adapt_data(data), where, pk)
         if kwds.get("sql_only", False):
             return sql, vals
         self.tx.invalidate_cache(self.name)
@@ -2002,7 +2011,7 @@ class Table:
         """
         Performs an INSERT of the given data into this table. Resets sys_id on duplicate keys if needed.
         """
-        sql, vals = self.sql.insert(self.name, data)
+        sql, vals = self.sql.insert(self.name, self._adapt_data(data))
         if kwds.get("sql_only", False):
             return sql, vals
         self.tx.invalidate_cache(self.name)
@@ -2018,7 +2027,7 @@ class Table:
         sql, vals = self.sql.merge(
             self.tx,
             self.name,
-            data,
+            self._adapt_data(data),
             pk,
             on_conflict_do_nothing=False,
             on_conflict_update=True,
@@ -2047,7 +2056,9 @@ class Table:
         """
         if not rows:
             return 0
-        sql, args_list, template = self.sql.insert_many(self.name, rows)
+        sql, args_list, template = self.sql.insert_many(
+            self.name, [self._adapt_data(row) for row in rows]
+        )
         page_size = kwds.get("page_size", 1000)
         self.tx.invalidate_cache(self.name)
         return self.tx._execute_values(sql, args_list, template=template, page_size=page_size)
@@ -2068,7 +2079,9 @@ class Table:
         """
         if not rows:
             return 0
-        sql, args_list, template = self.sql.merge_many(self.tx, self.name, rows, pk=pk)
+        sql, args_list, template = self.sql.merge_many(
+            self.tx, self.name, [self._adapt_data(row) for row in rows], pk=pk
+        )
         page_size = kwds.get("page_size", 1000)
         self.tx.invalidate_cache(self.name)
         return self.tx._execute_values(sql, args_list, template=template, page_size=page_size)
@@ -2172,7 +2185,9 @@ class Table:
                 "Current SQL dialect does not support insert-if-not-exists operations."
             )
 
-        sql, vals = ins_builder(self.tx, self.name, insert_payload, exists_where)
+        sql, vals = ins_builder(
+            self.tx, self.name, self._adapt_data(insert_payload), exists_where
+        )
         if sql_only:
             return {"update": update_stmt, "insert": (sql, vals)}
         result = self.tx.execute(sql, vals, cursor=self.cursor())
@@ -2200,7 +2215,9 @@ class Table:
                       must be present in `data`.
         :return: rowcount (0 or 1) or (sql, params) when sql_only=True
         """
-        sql, vals = self.sql.insert_if_not_exists(self.tx, self.name, data, where)
+        sql, vals = self.sql.insert_if_not_exists(
+            self.tx, self.name, self._adapt_data(data), where
+        )
         if kwds.get("sql_only", False):
             return sql, vals
         result = self.tx.execute(sql, vals, cursor=self.cursor())

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/db/servers/base/sql.py

@@ -2,6 +2,7 @@
 Abstract base class for SQL dialect implementations.
 """
 
+import json
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional, Tuple, Union
 
@@ -38,6 +39,21 @@ class BaseSQLDialect(ABC):
     DatabaseObjectExistsErrorCodes: List[str] = []
     DataIntegrityErrorCodes: List[str] = []
 
+    @classmethod
+    def adapt_data_value(cls, val: Any) -> Any:
+        """
+        Adapt a Python value being written to a column (INSERT/UPDATE data
+        values only — never WHERE parameters, which keep their native driver
+        adaptation, e.g. list -> ANY(...) on PostgreSQL).
+
+        Default: serialize dict/list to a JSON string for backends without a
+        native JSON parameter adapter (SQLite, SQL Server, MySQL).  PostgreSQL
+        overrides this to bind JSONB natively.
+        """
+        if isinstance(val, (dict, list)):
+            return json.dumps(val)
+        return val
+
     @classmethod
     def quote_identifier(cls, name: str) -> str:
         """Always-quote a single SQL identifier to prevent injection.

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/db/servers/mysql/types.py

@@ -23,6 +23,7 @@ class TYPES(BaseTypes):
     LONGTEXT = "LONGTEXT"
     MEDIUMTEXT = "MEDIUMTEXT"
     VARCHAR = "VARCHAR"
+    JSON = "JSON"
 
     @classmethod
     def get_type(cls, v):
@@ -51,6 +52,8 @@ class TYPES(BaseTypes):
             return cls.TIME
         if isinstance(v, bytes) or v is bytes:
             return cls.BINARY
+        if isinstance(v, (dict, list)) or v is dict or v is list:
+            return cls.JSON
         return cls.TEXT
 
     @classmethod
@@ -80,6 +83,8 @@ class TYPES(BaseTypes):
             return cls.TIME
         if isinstance(v, bytes) or v is bytes:
             return cls.BINARY
+        if isinstance(v, (dict, list)) or v is dict or v is list:
+            return cls.JSON
         return cls.TEXT
 
     @classmethod
@@ -108,4 +113,6 @@ class TYPES(BaseTypes):
             return datetime.datetime
         if v == cls.BINARY or "BLOB" in v:
             return bytes
+        if v == cls.JSON:
+            return dict
         raise Exception(f"Unmapped MySQL type {v}")

{velocity_python-0.1.62 → velocity_python-0.1.66}/src/velocity/db/servers/postgres/sql.py

@@ -71,6 +71,20 @@ class SQL(BaseSQLDialect):
     DatabaseObjectExistsErrorCodes = ["42710", "42P07", "42P04"]
     DataIntegrityErrorCodes = ["23503", "23502", "23514", "23P01", "22003"]
 
+    @classmethod
+    def adapt_data_value(cls, val):
+        """
+        Bind dict/list data values as JSONB.  Lists must be wrapped here
+        because psycopg's native list adaptation targets PostgreSQL arrays
+        (kept for WHERE params, e.g. ``= ANY(%s)``); bare dicts also work via
+        the engine-registered dumper, but wrapping both keeps it uniform.
+        """
+        if isinstance(val, (dict, list)):
+            from psycopg.types.json import Jsonb
+
+            return Jsonb(val)
+        return val
+
     @classmethod
     def get_error(cls, e):
         # psycopg v3 uses 'sqlstate'; psycopg2 used 'pgcode'.