Planner: plan rights as a policy and a permission key¶
First bullet of the Sprint 2 code-review issue (#2043), on #1922 / PR #1930 ("allow unit members to edit shared plans"):
Rewrite so that we use proper permissions instead of 'field'
can_manage-> SHOULD NOT BE in the data, but be passed around as a policy (PART of a bigger rewrite of the 'permissions/policy' to simplify the number of layers).
Problem¶
PR #1930 made deletion creator-only and told the frontend about it by
stamping can_manage: bool onto every SimulatorPlanRead: five routes in
simulator_plan.py ran _with_can_delete(...), workspace_home.py did the
same inline, and anything that forgot the stamp silently returned false.
A per-caller decision lived in the data DTO, and the rule itself was spread
over five free functions in app/core/policy.py (plan_is_visible_to,
plan_can_manage, require_plan_access, require_plan_scope_for_report,
with require_unit_access as a precondition) plus the route helper
_require_plan_unit_access.
Decision (with the lead, 2026-08-20)¶
- Scope: plan policy + permission key. The wider engine rewrite
(
query_policy/_evaluate_*_policy/get_module_permission_decisionindirection in front ofhas_permission) is a follow-up, see below. - The frontend may compare
plan.created_by === user.idfor own-breadthdelete: own breadth is documented as "owner = current user" on both sides (as_scope_keyinapp/models/user.py,resolve_module_scope). - No migration and no product change: view/edit = creator, unit members of a shared plan, global; delete = creator or global.
Permission key planner.plans¶
Emitted by calculate_user_permissions next to the module.status
affordance:
| Role (scope) | Keys |
|---|---|
| CO2_USER_PRINCIPAL (unit) | planner.plans/<cf>: [view, edit], planner.plans/<cf>/own: [delete] |
| CO2_USER_STD (own) | planner.plans/<cf>/own: [view, edit, delete] |
| CO2_SUPERADMIN (global) | planner.plans: [view, edit, delete] |
The key is self-describing for resolve_module_scope: delete resolves to
global (any plan) or own (only created_by == user). Principals get
delete at own breadth on purpose so a principal still cannot delete a
colleague's plan. View/edit breadth is orthogonal to the share flag: below
global, the record rule (creator or is_viewable_by_unit_members) applies.
Nuance: the old helpers let any GlobalScope role through, the key is
emitted for CO2_SUPERADMIN only. Metier is always affiliation-scoped
(ACCRED never produces a global metier role), so nothing changes in practice.
PlanPolicy (app/core/plan_policy.py)¶
One frozen dataclass resolved once per request, in the spirit of
WriteScope (#2050 J4):
PlanPolicy.from_unit(current_user, unit)/await PlanPolicy.for_unit(db, current_user, unit_id): 404 when the unit is missing, 403 when the caller holds noplanner.plansbreadth for it (same codes and details asrequire_unit_access).breadth(action),can_view(plan),can_edit(plan),can_delete(plan),require(plan, action)(404 when invisible, 403 on denied delete),visible(plans).planis duck-typed oncreated_by/is_viewable_by_unit_members, so ORM rows andSimulatorPlanReadboth work.
Wiring:
simulator_plan.py:_require_plan_accessloads the plan, builds the policy fromplan.unit_idand callsrequire; list returnspolicy.visible(...); create only builds the policy (membership gate)._with_can_manageand the duplicaterequire_plan_accessinGET /{plan_id}are gone.workspace_home.py:PlanPolicy.from_unit(current_user, unit).visible(plans)on the unit the route already loaded.policy.require_plan_scope_for_reportkeeps its name, signature and return value (3 report-addressed callers untouched) and delegates toPlanPolicy.for_unit(db, current_user, report.unit_id)for plan reports. TheUnitget is an identity-map hit where the caller already loaded the unit; the write-path statement-budget tests still pass.
Deleted: plan_is_visible_to, plan_can_manage, require_plan_access,
_with_can_manage, SimulatorPlanRead.can_manage, SimulatorPlan.can_manage
(frontend store type).
Frontend¶
utils/permission.ts:PermissionAction.DELETE,PLANNER_PLANS_PERMISSION, purecanDeletePlan(permissions, institutionalId, userId, createdBy).stores/auth.ts:hasUserCanDeletePlan(plan)next tohasUserCanValidateModuleStatus.CO2ProjectPlanner.vue: the delete button and its tooltip gate onauthStore.hasUserCanDeletePlan(props.row).
Tests¶
tests/unit/utils/test_permissions.py: key expectations per role, domain isolation allowsplanner.plans, metier emits none.tests/unit/core/test_policy.py:TestPlanPolicy(creator delete; unshared 404; shared editable but 403 on delete for std and principal non-creators; global bypass; other unit / no roles 403; missing unit 404;visible),TestRequirePlanScopeForReporton real users.tests/unit/v1/test_workspace_home.py: home payload filtered by the policy and free ofcan_manage.frontend/tests/unit/planner-delete-permission.spec.ts:canDeletePlanfor global, unit, own (creator / non-creator), no key, no unit. Listed here but never committed with this plan — the file was added by #2607, which also fixed the unit-breadth branch it left untested.