velocity-python 0.4.0__tar.gz → 0.4.1__tar.gz

{velocity_python-0.4.0 → velocity_python-0.4.1}/PKG-INFO

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

{velocity_python-0.4.0 → velocity_python-0.4.1}/pyproject.toml

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

{velocity_python-0.4.0 → velocity_python-0.4.1}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.4.0"
+__version__ = version = "0.4.1"
 
 import importlib as _importlib
 

{velocity_python-0.4.0 → velocity_python-0.4.1}/src/velocity/workflow/access.py

@@ -288,8 +288,15 @@ def act_relations(
         if kind == "hold":
             hold = tx.table(engine.HOLD).find({"sys_id": ident})
             if hold is not None and hold["docket_id"] == docket["sys_id"]:
+                # the relation only; the engine decides the hold's own
+                # release_permission with the actor's bound authz
                 if engine.hold_owner_of(
-                    actor, route, dict(hold.to_dict()), docket.get("entity")
+                    actor,
+                    route,
+                    dict(hold.to_dict()),
+                    docket.get("entity"),
+                    docket=docket,
+                    check_permission=False,
                 ):
                     out.add(HOLD_OWNER)
             return frozenset(out)

{velocity_python-0.4.0 → velocity_python-0.4.1}/src/velocity/workflow/engine.py

@@ -891,10 +891,15 @@ def may_release(actor: Actor, route: Route, hold, docket, effect) -> bool:
         return False
     if actor.kind != "person" or not in_scope(actor, docket.get("entity")):
         return False
+    held = hold.get("release_permission")
+    if held and not actor.may(HOLD_RELEASE, held, docket):
+        return False  # the hold's own permission binds every way out
     permission = effect.get("release_permission")
     if permission:
         return actor.may(HOLD_RELEASE, permission, docket)
-    return hold_owner_of(actor, route, hold, docket.get("entity"))
+    return hold_owner_of(
+        actor, route, hold, docket.get("entity"), docket=docket, direct=False
+    )
 
 
 def _release_effects(item: Pass):
@@ -1659,16 +1664,43 @@ def problem_owner_of(actor: Actor, route: Route, position) -> bool:
     )
 
 
-def hold_owner_of(actor: Actor, route: Route, hold, entity) -> bool:
+RELEASE_ANY, RELEASE_VIA_EFFECT = "any", "effect"
+
+
+def hold_owner_of(
+    actor: Actor,
+    route: Route,
+    hold,
+    entity,
+    *,
+    docket=None,
+    direct=True,
+    check_permission=True,
+) -> bool:
     """Who may release a manual hold on a docket of ``entity``: its owner
-    role, its placer, a route owner — inside their entities."""
+    role, its placer, a route owner, an authorized override — inside their
+    entities, and subject to the hold's own release controls:
+
+    * ``release_via="effect"``: never released directly (the
+      ``hold:<id>:release`` action, ``direct=True``), only by a pass effect;
+    * ``release_permission``: whoever releases it must also be allowed that
+      permission through authz (:data:`HOLD_RELEASE`, with the docket's
+      entity scope) — a route owner or an override included. Needs
+      ``docket``; ``check_permission=False`` is only for computing an authz
+      relation, the engine then decides with the actor's own ``allows``."""
     if actor.kind != "person" or str(hold.get("release_rule") or "") not in (
         "",
         "manual",
     ):
         return False
+    if direct and (hold.get("release_via") or RELEASE_ANY) == RELEASE_VIA_EFFECT:
+        return False
     if not in_scope(actor, entity):
         return False
+    permission = hold.get("release_permission")
+    if permission and check_permission:
+        if docket is None or not actor.may(HOLD_RELEASE, permission, docket):
+            return False
     if actor.override:
         return True
     return (
@@ -1777,7 +1809,7 @@ def actions_for(tx, docket, route: Route, actor: Actor, *, positions=None, now=N
                 }
             )
     for hold in holds_of(tx, docket["sys_id"]):
-        if hold_owner_of(actor, route, hold, docket.get("entity")):
+        if hold_owner_of(actor, route, hold, docket.get("entity"), docket=docket):
             out.append(
                 _action(
                     f"hold:{hold['sys_id']}:release",
@@ -2217,11 +2249,28 @@ def place_hold(
     blocks=None,
     releases_when=None,
     label=None,
+    release_permission=None,
+    release_via=RELEASE_ANY,
     now=None,
 ) -> int:
     """Place a manual hold; returns its id. ``blocks``: the pass codes it
-    blocks (default every forward, branch and rejoin pass)."""
+    blocks (default every forward, branch and rejoin pass).
+
+    Release controls: ``release_permission`` — whoever releases it (owner,
+    route owner, override, or a pass effect) must be allowed that permission
+    through authz (``workflow.hold.release``); ``release_via="effect"`` —
+    only a pass's ``release_hold`` effect releases it, so its pass's guards
+    always apply: the direct ``hold:<id>:release`` action is never offered
+    and is refused if sent."""
     hooks.check_code(kind, "hold kind")
+    if release_via not in (RELEASE_ANY, RELEASE_VIA_EFFECT):
+        raise WorkflowError(
+            f"release_via must be {RELEASE_ANY!r} or {RELEASE_VIA_EFFECT!r}"
+        )
+    if release_permission is not None and (
+        not isinstance(release_permission, str) or not release_permission.strip()
+    ):
+        raise WorkflowError("release_permission must be a permission name")
     ctx = _Ctx(tx, now)
     docket = _docket(tx, docket_id, lock=True)
     row = tx.table(HOLD).new(
@@ -2236,6 +2285,8 @@ def place_hold(
             "release_rule": "manual",
             "releases_when": releases_when,
             "blocks": list(blocks) if blocks else None,
+            "release_permission": release_permission,
+            "release_via": release_via,
         }
     )
     _mark(ctx, docket, actor, "hold", outcome=kind, note=str(reason or kind))

{velocity_python-0.4.0 → velocity_python-0.4.1}/src/velocity/workflow/schema.py

@@ -317,6 +317,10 @@ SCHEMA = {
             "released_by": "TEXT",
             "released_at": TS,
             "blocks": "JSONB",
+            # release controls: a permission any release needs, and
+            # "effect" = only a pass effect may release it (no direct action)
+            "release_permission": "TEXT",
+            "release_via": "TEXT",
             "link_id": "BIGINT",
             "rule_pack": "TEXT",
             "rule_version": "INTEGER",

{velocity_python-0.4.0 → velocity_python-0.4.1}/src/velocity_python.egg-info/PKG-INFO

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

{velocity_python-0.4.0 → velocity_python-0.4.1}/tests/test_workflow_actions.py

@@ -722,7 +722,9 @@ def test_the_site_scope_hook_sets_the_resource_scopes():
 def test_a_denial_at_the_sites_scope_refuses_the_sheet_write_and_the_release():
     tx, docket = scoped_site()
     handler = Handler(7, permissions=(USE, ws.READ, ws.EDIT, OVERRIDE))
-    unheld = wf.open_docket(tx, "widget_flow", ws.subject("n2"), entity="north", now=NOW)
+    unheld = wf.open_docket(
+        tx, "widget_flow", ws.subject("n2"), entity="north", now=NOW
+    )
     with denied_at("school:north", ws.EDIT):
         context = call(tx, handler, "workflow-act", act_payload(tx, unheld))
     assert context.status == 403  # the sheet write
@@ -787,3 +789,20 @@ def test_hold_release_is_refused_through_authz():
     )
     assert context.status in (403, 409)
     assert [h["kind"] for h in engine.holds_of(tx, docket)] == ["paperwork"]
+
+
+def test_a_route_owner_cannot_release_an_effect_only_hold_through_the_handler(_clean):
+    tx, docket = site()
+    hold = wf.place_hold(
+        tx, docket, "credit", "Over limit", owner="owner", release_via="effect", now=NOW
+    )
+    context = call(
+        tx,
+        Handler(1),
+        "workflow-act",
+        {"docket": docket, "action": f"hold:{hold}:release", "request_key": "h1"},
+    )
+    assert context.status == 403
+    assert [h["kind"] for h in engine.holds_of(tx, docket)] == ["credit"]
+    body = call(tx, Handler(1), "workflow-docket", {"docket": docket}).body
+    assert "release_action" not in body["holds"][0]

{velocity_python-0.4.0 → velocity_python-0.4.1}/tests/test_workflow_features.py

@@ -797,3 +797,110 @@ def test_the_calendar_hook_may_take_the_transaction():
     wf.register_calendar(everything)
     wf.open_docket(tx, "widget_flow", ws.subject("2"), now=NOW)
     assert seen[-1] == ["entity", "station", "tx"]
+
+
+# ── 0.4.1: hold-level release controls ────────────────────────────────────
+
+CREDIT = "widgets.credit_release"
+
+
+def credit_route():
+    spec = ws.route_spec(tests=[])
+    spec["passes"].append(
+        {
+            "code": "release_credit",
+            "from_station": "review",
+            "to_station": "allocate",
+            "guard_rule": "approve_limit",
+            "effects": [{"type": "release_hold", "kind": "credit"}],
+        }
+    )
+    return spec
+
+
+def direct_ids(tx, route, docket, actor):
+    return [
+        a["id"]
+        for a in wf.actions_for(tx, engine.docket_row(tx, docket), route, actor)
+        if a["id"].startswith("hold:")
+    ]
+
+
+def test_a_release_via_effect_hold_is_never_released_directly():
+    tx, route = ws.site(**credit_route())
+    docket = wf.open_docket(tx, "widget_flow", ws.subject("1"), now=NOW)
+    hold = wf.place_hold(
+        tx, docket, "credit", "Over limit", owner="owner", release_via="effect", now=NOW
+    )
+    owner = ws.actor(ws.person(1, oversees=["widget_flow"]))
+    overriding = ws.actor(ws.person(1, oversees=["widget_flow"]), override=True)
+    for actor in (owner, overriding):
+        assert direct_ids(tx, route, docket, actor) == []
+        refused = wf.act(
+            tx, docket, f"hold:{hold}:release", None, actor, f"d{id(actor)}", now=NOW
+        )
+        assert refused.reasons == [engine.NOT_AVAILABLE]
+    assert [h["kind"] for h in engine.holds_of(tx, docket)] == ["credit"]
+    # the effect still works, for someone it lets release (the owner role)
+    lead = ws.actor(ws.person(11, roles=["reviewer", "owner"]))
+    position = the_open(tx, docket)
+    assert wf.act(
+        tx,
+        docket,
+        f"pass:{position['sys_id']}:release_credit",
+        None,
+        lead,
+        "e1",
+        now=NOW,
+    ).ok
+    assert engine.holds_of(tx, docket) == []
+
+
+def test_a_hold_release_permission_binds_route_owners_overrides_and_effects():
+    tx, route = ws.site(**credit_route())
+    docket = wf.open_docket(tx, "widget_flow", ws.subject("1"), now=NOW)
+    hold = wf.place_hold(
+        tx,
+        docket,
+        "credit",
+        "Over limit",
+        owner="owner",
+        release_permission=CREDIT,
+        now=NOW,
+    )
+    plain_owner = ws.actor(ws.person(1, oversees=["widget_flow"]))
+    overriding = ws.actor(ws.person(1, oversees=["widget_flow"]), override=True)
+    for actor in (plain_owner, overriding):
+        assert direct_ids(tx, route, docket, actor) == []
+        assert not wf.act(
+            tx, docket, f"hold:{hold}:release", None, actor, f"p{id(actor)}", now=NOW
+        ).ok
+    # the release pass is no way around it either: its effect needs CREDIT too
+    lead = ws.person(11, roles=["reviewer", "owner"])
+    position = the_open(tx, docket)
+    assert not wf.act(
+        tx,
+        docket,
+        f"pass:{position['sys_id']}:release_credit",
+        None,
+        ws.actor(lead),
+        "e1",
+        now=NOW,
+    ).ok
+    assert [h["kind"] for h in engine.holds_of(tx, docket)] == ["credit"]
+    # with the permission, the route owner may release it directly
+    allowed = ws.actor(
+        ws.person(1, oversees=["widget_flow"]), perms=(ws.READ, ws.EDIT, CREDIT)
+    )
+    assert direct_ids(tx, route, docket, allowed) == [f"hold:{hold}:release"]
+    assert wf.act(tx, docket, f"hold:{hold}:release", None, allowed, "ok", now=NOW).ok
+    assert engine.holds_of(tx, docket) == []
+
+
+def test_release_controls_are_validated():
+    tx, route = ws.site()
+    docket = wf.open_docket(tx, "widget_flow", ws.subject("1"), now=NOW)
+    with pytest.raises(wf.WorkflowError, match="release_via"):
+        wf.place_hold(tx, docket, "credit", "x", release_via="anyone", now=NOW)
+    with pytest.raises(wf.WorkflowError, match="release_permission"):
+        wf.place_hold(tx, docket, "credit", "x", release_permission=" ", now=NOW)

{velocity_python-0.4.0 → velocity_python-0.4.1}/tests/test_workflow_postgres.py

@@ -430,3 +430,28 @@ def test_a_failed_sweep_item_does_not_strip_the_audit_actor(eng):
             (good,),
         ).scalar()
     assert changed_by == "system:workflow"
+
+
+def test_hold_release_controls_on_postgres(eng):
+    docket, _sid = new_docket(eng)
+    owner = ws.actor(ws.person(1, oversees=["widget_flow"]), override=True)
+    with eng.transaction() as tx:
+        hold = wf.place_hold(
+            tx,
+            docket,
+            "credit",
+            "Over limit",
+            owner="owner",
+            release_via="effect",
+            release_permission="widgets.credit",
+            now=NOW,
+        )
+        row = engine.holds_of(tx, docket)[0]
+        assert (row["release_via"], row["release_permission"]) == (
+            "effect",
+            "widgets.credit",
+        )
+        refused = wf.act(
+            tx, docket, f"hold:{hold}:release", None, owner, "pg-h", now=NOW
+        )
+        assert refused.reasons == [engine.NOT_AVAILABLE]