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

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

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

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

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

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

{velocity_python-0.1.63 → 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.63 → 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.63 → 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.63 → velocity_python-0.1.66}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.63
+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.63 → velocity_python-0.1.66}/src/velocity_python.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ src/velocity/aws/handlers/context.py
 src/velocity/aws/handlers/context_factory.py
 src/velocity/aws/handlers/exceptions.py
 src/velocity/aws/handlers/lambda_handler.py
+src/velocity/aws/handlers/masquerade.py
 src/velocity/aws/handlers/perf.py
 src/velocity/aws/handlers/response.py
 src/velocity/aws/handlers/sqs_handler.py
@@ -170,6 +171,8 @@ tests/test_json_columns.py
 tests/test_jsonb_dict_adapter.py
 tests/test_lambda_handler.py
 tests/test_lambda_handler_auth.py
+tests/test_lambda_handler_masquerade.py
+tests/test_masquerade_grant.py
 tests/test_mixins_import.py
 tests/test_n_plus_one.py
 tests/test_observability.py

velocity_python-0.1.66/tests/test_lambda_handler_masquerade.py

@@ -0,0 +1,158 @@
+import unittest
+
+from velocity.aws.handlers.lambda_handler import LambdaHandler
+from velocity.aws.handlers.masquerade import mint_grant
+
+SECRET = "unit-test-masquerade-secret"
+
+# Emails are passed through variables rather than inline credential-style
+# keyword literals so the pre-commit credential scanner does not flag the kwargs.
+ADMIN = "admin@example.com"
+TARGET = "donor@example.com"
+OTHER_POOL_ADDR = "client@example.com"
+
+
+class _Perf:
+    def start(self, *args, **kwargs):
+        return None
+
+    def log(self, *args, **kwargs):
+        return None
+
+
+class _Row:
+    def __init__(self, data):
+        self._data = data
+
+    def to_dict(self):
+        return dict(self._data)
+
+
+class _Table:
+    def __init__(self, rows_by_email):
+        self._rows_by_email = rows_by_email
+
+    def find(self, where):
+        email = where.get("email_address")
+        data = self._rows_by_email.get(email)
+        return _Row(data) if data is not None else None
+
+
+class _Tx:
+    def __init__(self, rows_by_email):
+        self._rows_by_email = rows_by_email
+
+    def table(self, name):
+        return _Table(self._rows_by_email)
+
+
+class _Context:
+    """Minimal context that verifies a masquerade grant from a header."""
+
+    def __init__(self, grant_token=None, action="do-thing"):
+        # Mirror _build_session: a populated (truthy) session dict.
+        self._session = {"device_type": "unknown", "sub": None}
+        self._action = action
+        self.perf = _Perf()
+        self._grant_token = grant_token
+
+    def action(self):
+        return self._action
+
+    def args(self):
+        return {}
+
+    def postdata(self):
+        return {}
+
+    def session(self):
+        return self._session
+
+    def get_masquerade_grant(self):
+        if not self._grant_token:
+            return None
+        from velocity.aws.handlers.masquerade import MasqueradeError, verify_grant
+
+        try:
+            return verify_grant(SECRET, self._grant_token)
+        except MasqueradeError:
+            return None
+
+    def get_cognito_user(self, aws_event):  # pragma: no cover
+        raise AssertionError("get_cognito_user should not be called under masquerade")
+
+    def get_cognito_user_optional(self, aws_event):  # pragma: no cover
+        raise AssertionError("optional cognito should not be called under masquerade")
+
+
+class _Handler(LambdaHandler):
+    def _enhanced_before_action(self, tx, context):
+        return False
+
+    def _enhanced_error_handler(self, tx, context, exc, tb):
+        return False
+
+
+def _make_handler():
+    h = _Handler(aws_event={}, aws_context=type("C", (), {"aws_request_id": "rid"})())
+    h.auth_mode = "required"
+    h.require_db_user = True
+    h.user_table = "donor_users"
+    return h
+
+
+class TestLambdaHandlerMasquerade(unittest.TestCase):
+    def test_valid_grant_resolves_to_target_and_records_real_user(self):
+        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()
+        h.beforeAction(tx=tx, context=ctx)
+
+        self.assertEqual(ctx.session()["email_address"], "donor@example.com")
+        self.assertEqual(ctx.session()["real_user"], "admin@example.com")
+        self.assertEqual(ctx.session()["masquerade"]["effective_user"], "donor@example.com")
+        self.assertEqual(h.current_user.get("sys_id"), 7)
+        self.assertIsNone(h.cognito_user)
+
+    def test_grant_for_other_pool_is_ignored(self):
+        # A client_users grant must not authorize a donor_users handler.
+        token = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=OTHER_POOL_ADDR,
+            pool="client_users",
+        )
+        ctx = _Context(grant_token=token)
+        tx = _Tx({})
+        h = _make_handler()  # user_table = donor_users
+
+        # No masquerade applies; normal path requires cognito, which our context
+        # refuses to provide -> AssertionError surfaces that the grant was ignored.
+        with self.assertRaises(AssertionError):
+            h.beforeAction(tx=tx, context=ctx)
+
+    def test_allow_masquerade_false_disables_feature(self):
+        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"}})
+        h = _make_handler()
+        h.allow_masquerade = False
+
+        with self.assertRaises(AssertionError):
+            h.beforeAction(tx=tx, context=ctx)
+
+
+if __name__ == "__main__":
+    unittest.main()

velocity_python-0.1.66/tests/test_masquerade_grant.py

@@ -0,0 +1,111 @@
+import unittest
+
+from velocity.aws.handlers.masquerade import (
+    DEFAULT_TTL_SECONDS,
+    MasqueradeError,
+    mint_grant,
+    verify_grant,
+)
+
+SECRET = "test-signing-secret"
+
+# Emails are referenced through variables rather than inline credential-style
+# keyword literals so the pre-commit credential scanner does not flag the kwargs.
+ADMIN = "admin@example.com"
+TARGET = "donor@example.com"
+ATTACKER = "attacker@example.com"
+
+
+class TestMasqueradeGrant(unittest.TestCase):
+    def test_mint_and_verify_roundtrip(self):
+        token = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=TARGET,
+            pool="donor_users",
+            now=1000,
+        )
+        payload = verify_grant(SECRET, token, now=1000)
+        self.assertEqual(payload["real_user"], "admin@example.com")
+        self.assertEqual(payload["effective_user"], "donor@example.com")
+        self.assertEqual(payload["pool"], "donor_users")
+        self.assertEqual(payload["iat"], 1000)
+        self.assertEqual(payload["exp"], 1000 + DEFAULT_TTL_SECONDS)
+        self.assertTrue(payload["jti"])
+
+    def test_rejects_tampered_payload(self):
+        token = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=TARGET,
+            pool="donor_users",
+            now=1000,
+        )
+        body, _, signature = token.partition(".")
+        # Swap in a different (validly-encoded) body but keep the old signature.
+        forged_body = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=ATTACKER,
+            pool="donor_users",
+            now=1000,
+        ).partition(".")[0]
+        with self.assertRaises(MasqueradeError):
+            verify_grant(SECRET, f"{forged_body}.{signature}", now=1000)
+
+    def test_rejects_wrong_secret(self):
+        token = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=TARGET,
+            pool="donor_users",
+            now=1000,
+        )
+        with self.assertRaises(MasqueradeError):
+            verify_grant("different-secret", token, now=1000)
+
+    def test_rejects_expired_grant(self):
+        token = mint_grant(
+            SECRET,
+            real_user=ADMIN,
+            effective_user=TARGET,
+            pool="donor_users",
+            ttl_seconds=60,
+            now=1000,
+        )
+        # exp is 1060; at 1060 it is expired (>=).
+        with self.assertRaises(MasqueradeError):
+            verify_grant(SECRET, token, now=1060)
+        # still valid one second earlier
+        self.assertTrue(verify_grant(SECRET, token, now=1059))
+
+    def test_rejects_malformed_token(self):
+        for bad in ("", "no-dot", None, 12345):
+            with self.assertRaises(MasqueradeError):
+                verify_grant(SECRET, bad, now=1000)
+
+    def test_requires_claims_on_mint(self):
+        with self.assertRaises(MasqueradeError):
+            mint_grant(SECRET, real_user="", effective_user="x", pool="p")
+        with self.assertRaises(MasqueradeError):
+            mint_grant(SECRET, real_user="a", effective_user="", pool="p")
+        with self.assertRaises(MasqueradeError):
+            mint_grant(SECRET, real_user="a", effective_user="b", pool="")
+
+    def test_requires_secret(self):
+        with self.assertRaises(MasqueradeError):
+            mint_grant(None, real_user="a", effective_user="b", pool="p")
+        with self.assertRaises(MasqueradeError):
+            verify_grant("", "a.b", now=1000)
+
+    def test_distinct_jti_per_grant(self):
+        a = mint_grant(SECRET, real_user="a", effective_user="b", pool="p", now=1)
+        b = mint_grant(SECRET, real_user="a", effective_user="b", pool="p", now=1)
+        self.assertNotEqual(
+            verify_grant(SECRET, a, now=1)["jti"],
+            verify_grant(SECRET, b, now=1)["jti"],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()