feat: SameAs generator

[mesemus]

Warning

This is a backward-incompatible change, as users might, in rare cases, rely on the static binding inside the base permission policy.
Please consider merging #120 for the same release as that would need major bump as well

Note

This PR has an accompanying one in invenio-rdm-records - inveniosoftware/invenio-rdm-records#2267
This PR has an accompanying one in invenio-requests - inveniosoftware/invenio-requests#582
This PR has an accompanying one in invenio-communities - inveniosoftware/invenio-communities#1355

Description

A permission policy can be a complicated thing - look for example at the RDM permission policy:

class RDMPermissionPolicy:
    can_manage = [
        RecordOwners(),
        RecordCommunitiesAction("curate"),
        AccessGrant("manage"),
        SystemProcess(),
    ]
    can_curate = can_manage + [AccessGrant("edit"), SecretLinks("edit")]

If we inherit from the policy and modify the can_manage to include another group of users:

class MyPP(RDMPermissionPolicy):
    can_manage = [
        UsersWithRole("myrole"),
        RecordOwners(),
        RecordCommunitiesAction("curate"),
        AccessGrant("manage"),
        SystemProcess(),
    ]

can_curate is not updated as a user might expect. When evaluating permissions, can_curate will not contain the UsersWithRole generator because it was created statically inside the RDMPermissionPolicy class.

The SameAs generator addresses this issue by introducing dynamic binding — the delegation/inclusion happens at permission evaluation time. If the RDM policy were defined as follows:

class RDMPermissionPolicy:
    can_manage = [
        RecordOwners(),
        RecordCommunitiesAction("curate"),
        AccessGrant("manage"),
        SystemProcess(),
    ]
    can_curate = [SameAs("can_manage"), AccessGrant("edit"), SecretLinks("edit")]

the example above would work as the user would intuitively expect.

Note: SameAs is a permission generator, so that it can be included anywhere permission generator might go. To simplify permissions, SameAs can also be used outside lists and combined with other lists:

class RDMPermissionPolicy:
    can_manage = [
        RecordOwners(),
        RecordCommunitiesAction("curate"),
        AccessGrant("manage"),
        SystemProcess(),
    ]
    can_curate = SameAs("can_manage") + [AccessGrant("edit"), SecretLinks("edit")]
    can_delete = SameAs("can_curate")

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

• I'm aware of the code of conduct.
• I've created logical separate commits and followed the commit message format.
• I've added relevant test cases.
• I've added relevant documentation.
• I've marked translation strings.
• I've identified the copyright holder(s) and updated copyright headers for touched files (>15 lines contributions).
• I've NOT included third-party code (copy/pasted source code or new dependencies).
  • If you have added third-party code (copy/pasted or new dependencies), please reach out to an architect on Discord.

Frontend

• I've followed the CSS/JS and React guidelines.
• I've followed the web accessibility guidelines.
• I've followed the user interface guidelines.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

1. You license your contribution under the same terms as the current repository’s license.
2. You agree that you have the right to license your contribution under the current repository’s license.

[max-moser]

this looks amazing, and has the potential to massively simplify permission policy definitions!
thanks a lot for this 😃

i'll take it for a test ride and approve after 🙂

[max-moser]

FYI, I'm currently in the process of reshaping our own custom permission policy with this new generator, and preliminary results are very promising: https://gitlab.tuwien.ac.at/crdm/invenio-config-tuw/-/merge_requests/110

[max-moser]

With this new permission generator, I was able to cut down our custom TUWRecordPermissionPolicy from 131 lines of code down to 38 (and half of those are comments).
Now we only have 4 explicit action permission definitions left, instead of overriding almost every single one like before.

Massive work, thanks a ton!

[zzacharo]

Thanks a lot for this!!!!