velocity-python 0.2.3__tar.gz → 0.2.5__tar.gz

{velocity_python-0.2.3/src/velocity_python.egg-info → velocity_python-0.2.5}/PKG-INFO

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

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

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.3"
+__version__ = version = "0.2.5"
 
 import importlib as _importlib
 

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/authz.py

@@ -80,6 +80,7 @@ from __future__ import annotations
 
 import logging
 import re
+import sys
 from dataclasses import dataclass, field, replace
 from fnmatch import fnmatchcase
 from typing import Any, Callable, Optional
@@ -379,22 +380,42 @@ BUILTIN_RULES = (permit("data.ordinary_tables", DATA_ACCESS, when=_ordinary_tabl
 
 _REGISTERED = {}
 _REGISTERED_TUPLE = None
+# name -> the globals of the module that registered it. A module imported a
+# second time (importlib.reload, a test that patches sys.modules) runs with
+# new globals under the same __name__ and builds new condition closures, so
+# its rules never compare equal to the first import's.
+_OWNERS = {}
 
 
 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."""
+    rule again is a no-op, and so is a module re-registering its own rules
+    when it is imported again (the new rules replace the old). A different
+    rule under a taken name is otherwise an error."""
     global _REGISTERED_TUPLE
+    caller = sys._getframe(1).f_globals
     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:
+        if known is not None and known != rule and not _reimported(rule.name, caller):
             raise ValueError(f"An authorization rule named '{rule.name}' exists.")
         _REGISTERED[rule.name] = rule
+        _OWNERS[rule.name] = caller
     _REGISTERED_TUPLE = None
 
 
+def _reimported(name, caller):
+    """True when ``caller`` is a fresh import of the module that registered
+    ``name``: same module name, different globals."""
+    owner = _OWNERS.get(name)
+    return (
+        owner is not None
+        and owner is not caller
+        and owner.get("__name__") == caller.get("__name__")
+    )
+
+
 def registered():
     """Every rule a handler evaluates before its own. The same tuple object
     until a rule is registered, so its action index is built once."""

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/context.py

@@ -1093,6 +1093,9 @@ class Context:
                 "enabled": response.get("Enabled"),
                 "user_status": response.get("UserStatus"),
                 "sub": attributes.get("sub", user_sub),
+                # the token issuer for this pool: with "sub", the identity
+                # the provider never reassigns (velocity.aws.identity)
+                "issuer": f"https://{user_pool_segment}",
             }
 
             return user

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/lambda_handler.py

@@ -177,10 +177,15 @@ class LambdaHandler(BaseHandler):
                 )
 
             context.perf.start("user lookup")
-            user = self._cached_user(tx, session.get("email_address"))
+            user = self._find_current_user(tx, session, masquerade)
             context.perf.log("user lookup")
             if not user and not masquerade and _stage_allows_provisioning():
-                user = self._provision_and_reload(tx, session)
+                if self._by_subject(masquerade):
+                    # the hook's new row is bound on this, its first, sign-in
+                    self.provision_missing_user(tx, session)
+                    user = self._find_current_user(tx, session, masquerade)
+                else:
+                    user = self._provision_and_reload(tx, session)
             if not user:
                 raise UserNotProvisionedError(
                     "A valid user with permission is required to access this function [DB]"
@@ -245,6 +250,59 @@ class LambdaHandler(BaseHandler):
             )
         return user
 
+    # How a request finds its user row (velocity.aws.identity): "email" (the
+    # default) or "subject" — the identity provider's issuer + subject, the
+    # row bound once by verified email on the first sign-in after the switch.
+    # The IdentityMode config key (per environment) overrides this.
+    identity_mode = "email"
+
+    def _by_subject(self, masquerade):
+        from velocity.aws import identity
+
+        # a masquerade identity is the grant's user, not a provider subject;
+        # the mode is the IdentityMode config key, else identity_mode
+        return not masquerade and identity.mode_of(self) == identity.IDENTITY_SUBJECT
+
+    def _find_current_user(self, tx, session, masquerade=False):
+        """The signed-in caller's user row (dict) or None, by email or — in
+        ``identity_mode = "subject"`` — by issuer + subject."""
+        if not self._by_subject(masquerade):
+            return self._cached_user(tx, session.get("email_address"))
+        from velocity.aws import identity
+
+        issuer, subject, email, verified = identity.claims_of(self.cognito_user)
+        session["iss"], session["sub"] = issuer, subject
+        if not (issuer and subject):
+            return None
+        return self._cached_subject_user(tx, issuer, subject, email, verified)
+
+    def _cached_subject_user(self, tx, issuer, subject, email, verified):
+        """``_cached_user`` by issuer + subject. A first sign-in binds its row
+        inside the load; a miss is never cached."""
+        from velocity.cache import memo
+
+        from velocity.aws import identity
+        from velocity.aws.handlers.context import user_cache_seconds
+
+        def load():
+            return identity.find_user(
+                tx, self.user_table, issuer, subject, email, verified
+            )
+
+        key = ("user-subject", self.user_table, issuer, subject)
+        if getattr(self, "permission_source", None) == "tables":
+            from velocity.aws import permissions as _grants
+
+            key = (*key, _grants.cached_version(tx))
+        user = memo(
+            key,
+            load,
+            user_cache_seconds(),
+            tables=(self.user_table,),
+            cache_none=False,
+        )
+        return dict(user) if user else None
+
     def _cached_user(self, tx, email_address):
         """The user-table row for the signed-in user as a dict, through the
         process read cache (velocity.cache) for ``UserCacheSeconds``: one

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/mixins/__init__.py

@@ -23,8 +23,9 @@ from .row_scoped import RowScopedDataService
 from .audit_trail import AuditTrailMixin
 from .job_handler import JobHandler
 from .session_control import SessionControlMixin
-from .permissions_actions import PermissionsMixin
-from .tiles_actions import TilesMixin
+from .action_names import action_names
+from .permissions_actions import PERMISSION_ACTIONS, PermissionsMixin
+from .tiles_actions import TILE_ACTIONS, TilesMixin
 from .client_errors import ClientErrorReporting, AnonymousClientErrorReporting
 
 __all__ = [
@@ -37,7 +38,10 @@ __all__ = [
     "JobHandler",
     "SessionControlMixin",
     "PermissionsMixin",
+    "PERMISSION_ACTIONS",
     "TilesMixin",
+    "TILE_ACTIONS",
+    "action_names",
     "ClientErrorReporting",
     "AnonymousClientErrorReporting",
 ]

velocity_python-0.2.5/src/velocity/aws/handlers/mixins/action_names.py

@@ -0,0 +1,30 @@
+"""The client action names a handler class serves, from its methods.
+
+``BaseHandler.format_action_name`` turns ``"tiles-load"`` into
+``"OnActionTilesLoad"``; this is the inverse, for a site's ``client_actions``
+allow-list: ``client_actions = MINE | TILE_ACTIONS | PERMISSION_ACTIONS``
+picks up every action a mixin gains with a release, instead of a list each
+site copies by hand (and forgets to extend: admin refused every tile action
+until its list was edited, 2026-10-14).
+"""
+
+from __future__ import annotations
+
+import re
+
+_PREFIX = "OnAction"
+_WORD = re.compile(r"[A-Z][a-z0-9]*")
+
+
+def action_names(cls) -> frozenset:
+    """The kebab-case action of every ``OnAction<Name>`` method ``cls``
+    itself defines (not inherited ones; not ``OnActionDefault``)."""
+    names = set()
+    for attr, value in vars(cls).items():
+        if not attr.startswith(_PREFIX) or not callable(value):
+            continue
+        rest = attr[len(_PREFIX) :]
+        if not rest or rest == "Default":
+            continue
+        names.add("-".join(word.lower() for word in _WORD.findall(rest)))
+    return frozenset(names)

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/mixins/data_service.py

@@ -426,6 +426,19 @@ def plan_row_number(params):
 
 # result_formats query answers with a file download (velocity.misc.export).
 FILE_EXPORT_FORMATS = frozenset(export.EXPORT_FORMATS)
+# Formats written as XLSX cells, which carry no time zone: aware values are
+# converted to the handler's display_timezone() first.
+XLSX_EXPORT_FORMATS = frozenset({"excel", "xlsx"})
+
+
+def _export_zone(handler, result_format, context):
+    """The display zone for an export: the handler's ``display_timezone``
+    for the XLSX formats, ``None`` for the text formats (which write values
+    as given and need no SSM read)."""
+    if result_format not in XLSX_EXPORT_FORMATS:
+        return None
+    zone_for = getattr(handler, "display_timezone", None)
+    return zone_for(context) if zone_for is not None else None
 
 
 def _positive_int(value):
@@ -679,7 +692,11 @@ class ExportStream:
         """The whole export as one file: :func:`velocity.misc.export.build_buffer`
         over :meth:`rows` (line formats are written as the batches arrive)."""
         built = export.build_buffer(
-            result_format, self.headers, self.rows(), filename_base
+            result_format,
+            self.headers,
+            self.rows(),
+            filename_base,
+            display_timezone=_export_zone(self.handler, result_format, self.context),
         )
         if built is None:
             raise BadRequestError(f"Unsupported export format: {result_format!r}")
@@ -838,6 +855,24 @@ class DataServiceMixin:
         "timestamp": "string",
     }
 
+    def display_timezone(self, context=None):
+        """The zone XLSX exports show times in: Excel cells carry no zone,
+        so an aware value (every ``timestamptz``) is written as its wall time
+        here. Default: the site's ``SiteTimezone`` config key (an IANA name
+        such as ``America/Denver``, read through ``ssm_config.getenv``, which
+        caches it per process); UTC, with a warning, when it is unset or not
+        a zone. Override to choose per request (``context`` is the request
+        context) or per handler. Returns a ``tzinfo``."""
+        try:
+            name = ssm_config.getenv("SiteTimezone", None)
+        except Exception:
+            logger.warning("SiteTimezone could not be read; exports use UTC")
+            name = None
+        if not name:
+            logger.warning("SiteTimezone is not set; exports show times in UTC")
+            return datetime.timezone.utc
+        return export.resolve_display_timezone(name)
+
     def _resolve_query_max_rows(self):
         """Effective query row ceiling: `QueryMaxRows` config key first, then
         the class attribute. Returns a positive int or None (no cap)."""
@@ -2231,6 +2266,7 @@ class DataServiceMixin:
                 data.get("headers", []),
                 data.get("rows", []),
                 filename_base,
+                display_timezone=_export_zone(self, result_format, context),
             )
             if result_format == "excel":
                 # the legacy excel download keeps its caller-chosen filename
@@ -2412,7 +2448,12 @@ class DataServiceMixin:
             )
             rows = result.as_list().all()
             filebuffer = BytesIO()
-            export.create_spreadsheet(headers, rows, filebuffer)
+            export.create_spreadsheet(
+                headers,
+                rows,
+                filebuffer,
+                display_timezone=self.display_timezone(context),
+            )
             context.response().file_download(
                 {
                     "filename": payload.get("filename", "temp_file.xls"),

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/mixins/permissions_actions.py

@@ -63,6 +63,7 @@ from types import SimpleNamespace
 
 from velocity.aws import authz, permissions
 from velocity.aws.handlers.exceptions import AlertError
+from .action_names import action_names
 
 READ = "permissions.read"
 READ_ACTION = "permissions.read"
@@ -804,3 +805,8 @@ class PermissionsMixin:
             )
         )
         context.response().set_body(self._inbox_body(tx, actor))
+
+
+# every action PermissionsMixin serves, for a site's ``client_actions``:
+# ``client_actions = MINE | PERMISSION_ACTIONS``
+PERMISSION_ACTIONS = action_names(PermissionsMixin)

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/mixins/tiles_actions.py

@@ -39,6 +39,7 @@ from velocity.aws import authz, facets, permissions, tiles
 from velocity.aws.handlers.exceptions import AccessError, AlertError
 from velocity.db.fragments import Expr
 from velocity.db.servers.tablehelper import TableHelper
+from .action_names import action_names
 
 logger = logging.getLogger(__name__)
 
@@ -659,3 +660,8 @@ class TilesMixin:
             )
         )
         context.response().set_body(self._manage_body(tx, actor))
+
+
+# every action TilesMixin serves, for a site's ``client_actions``:
+# ``client_actions = MINE | TILE_ACTIONS``
+TILE_ACTIONS = action_names(TilesMixin)

{velocity_python-0.2.3 → velocity_python-0.2.5}/src/velocity/aws/handlers/mixins/web_handler.py

@@ -621,6 +621,14 @@ Request Details:
             return
         session = context.session() or {}
         email = session.get("email_address")
+        if not email:
+            # Nobody is signed in (a public page that saves its layout as it
+            # goes): there is no owner, so nothing is saved. Rows mode used to
+            # upsert under a blank userid — one shared junk row per key that
+            # every anonymous visitor overwrote. Not an error, so a public
+            # page does not report a failure on every change.
+            context.response().set_body({"saved": False, "reason": "signed_out"})
+            return
         if self.user_data_mode == USER_DATA_DOCUMENT:
             owner = (getattr(self, "current_user", None) or {}).get("sys_id")
             decision = authz.decide(

velocity_python-0.2.5/src/velocity/aws/identity.py

@@ -0,0 +1,138 @@
+"""Who is signed in: the user row bound to the identity provider's issuer and
+subject, never found by email.
+
+An email address can change, be reused, or be claimed by an external identity
+provider; the provider's issuer plus subject (``iss`` + ``sub``) is the one
+pair it guarantees never to reassign (OpenID Connect Core 1.0, section 5.7).
+So a user row carries the pair it is bound to, and each request finds its
+user by that pair.
+
+The mode is the ``IdentityMode`` config key (SSM ``/{Project}/{env}/`` then
+``/Global/{env}/``) when set, else the handler's ``identity_mode``
+(see ``LambdaHandler.beforeAction``), else ``"email"`` — so a site switches
+one environment at a time, demo first, with no code change:
+
+* ``"email"`` — the default and the behaviour before this module: the user
+  row is found by ``email_address``.
+* ``"subject"`` — the user row is found by :data:`ISSUER_COLUMN` +
+  :data:`SUBJECT_COLUMN`. The first sign-in after a site switches binds its
+  existing row ONCE, by the caller's *verified* email, and only a row not
+  yet bound to anyone; from then on email is never used to find that user.
+  A row already bound to another identity is never re-bound by email (the
+  address moved to a different account), and an unverified email binds
+  nothing.
+
+Both columns are TEXT on the site's user table. Declare them in the site's
+schema lane before switching a locked environment
+(``SCHEMA_COLUMNS``); in an unlocked one the first binding creates them.
+
+A masquerade session keeps the email path: its identity is the verified
+grant's user, not a provider subject.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from velocity.aws import ssm_config
+
+logger = logging.getLogger(__name__)
+
+IDENTITY_EMAIL = "email"
+IDENTITY_SUBJECT = "subject"
+IDENTITY_MODES = (IDENTITY_EMAIL, IDENTITY_SUBJECT)
+
+ISSUER_COLUMN = "identity_issuer"
+SUBJECT_COLUMN = "identity_subject"
+# for a site's schema lane: ensure_columns(tx, user_table, SCHEMA_COLUMNS)
+SCHEMA_COLUMNS = {ISSUER_COLUMN: "TEXT", SUBJECT_COLUMN: "TEXT"}
+
+
+def mode_of(handler):
+    """``IdentityMode`` config first, then the handler's ``identity_mode``,
+    then ``"email"``. A value that is not a mode is ``"email"`` (logged):
+    unlike authorization, the safe fallback is the established lookup, so a
+    typo never locks every user out."""
+    raw = None
+    try:
+        raw = ssm_config.getenv("IdentityMode", None)
+    except Exception:
+        raw = None
+    raw = str(raw or getattr(handler, "identity_mode", None) or IDENTITY_EMAIL)
+    mode = raw.strip().lower()
+    if mode not in IDENTITY_MODES:
+        logger.warning("identity: unknown IdentityMode %r; using email", raw)
+        return IDENTITY_EMAIL
+    return mode
+
+
+def claims_of(cognito_user):
+    """``(issuer, subject, email, email_verified)`` from a resolved Cognito
+    user (``Context.get_cognito_user``); ``None`` parts when absent."""
+    user = cognito_user if isinstance(cognito_user, dict) else {}
+    attributes = user.get("attributes") or {}
+    email = (attributes.get("email") or user.get("email") or "").strip().lower() or None
+    verified = str(attributes.get("email_verified", "")).strip().lower() == "true"
+    return user.get("issuer") or None, user.get("sub") or None, email, verified
+
+
+def _row(found):
+    if not found:
+        return None
+    return found.to_dict() if hasattr(found, "to_dict") else dict(found)
+
+
+def find_bound(tx, user_table, issuer, subject):
+    """The user row bound to ``issuer`` + ``subject``, or None."""
+    if not (issuer and subject):
+        return None
+    return _row(
+        tx.table(user_table).find({ISSUER_COLUMN: issuer, SUBJECT_COLUMN: subject})
+    )
+
+
+def bind_by_verified_email(tx, user_table, issuer, subject, email, verified):
+    """Bind the unbound row with this verified email to ``issuer`` +
+    ``subject`` and return it; None when there is nothing it may bind.
+
+    Refuses (returns None, logs why) when the email is not verified, when no
+    row has it, or when that row is already bound to a different identity —
+    the address now belongs to another account, and following it would hand
+    that account someone else's row.
+    """
+    if not (issuer and subject and email):
+        return None
+    if not verified:
+        logger.warning("identity: not binding %s — email not verified", email)
+        return None
+    row = _row(tx.table(user_table).find({"email_address": email}))
+    if not row:
+        return None
+    bound = (row.get(ISSUER_COLUMN), row.get(SUBJECT_COLUMN))
+    if any(bound):
+        if bound != (issuer, subject):
+            logger.warning(
+                "identity: %s row %s is bound to another identity; not re-binding by email",
+                user_table,
+                row.get("sys_id"),
+            )
+            return None
+        return row
+    tx.table(user_table).update(
+        {ISSUER_COLUMN: issuer, SUBJECT_COLUMN: subject}, {"sys_id": row["sys_id"]}
+    )
+    logger.info(
+        "identity: bound %s row %s to its sign-in (first sign-in by subject)",
+        user_table,
+        row.get("sys_id"),
+    )
+    row.update({ISSUER_COLUMN: issuer, SUBJECT_COLUMN: subject})
+    return row
+
+
+def find_user(tx, user_table, issuer, subject, email=None, verified=False):
+    """The signed-in caller's user row: by ``issuer`` + ``subject``, else (on
+    the first sign-in after the switch) the row its verified email binds."""
+    return find_bound(tx, user_table, issuer, subject) or bind_by_verified_email(
+        tx, user_table, issuer, subject, email, verified
+    )