Findings / Analysis

In ui-agreements package.json I added this view permission:

      {
        "permissionName": "ui-agreements.picklists.view",
        "displayName": "Settings (Agreements): View pick lists and values",
        "description": "Grants permission to view settings and pick lists and pick list values",
        "visible": true,
        "subPermissions": [
          "settings.agreements.enabled",
          "erm.refdata.view"
        ]
      },

The existing manage permission was updated to contain this new permission as a sub-permission:

      {
        "permissionName": "ui-agreements.picklists.manage",
        "displayName": "Settings (Agreements): Manage pick lists and values",
        "description": "Grants all permissions included in 'Settings (Agreements): Can view and edit general settings' plus the ability to manage pick lists and pick list values",
        "visible": true,
        "subPermissions": [
          "ui-agreements.picklists.view",
          "erm.refdata.manage"
        ]
      },

After I changed the permissions I stopped and started the application, logged an user (with the manage permission assigned before) several times out and in, did a stripes login to okapi and unassigned and assigned the manage permission to this user - with no success. The user didn't have the ui-agreements.picklists.view.

Then I started two slack conversations:

https://folio-project.slack.com/archives/C210UCHQ9/p1676294868572289

https://folio-project.slack.com/archives/C210RP0T1/p1676302569726109

I was told that

it's not possible to change a permission with the property mutable: false , and that I had to create a new permission with the replaces property. I followed the API and schema doku, but the attempt to create such a permission in my local backend ended with that error:

{
    "errors": [
        {
            "message": "Unrecognized field \"replaces\" (class org.folio.rest.jaxrs.model.PermissionUpload), not marked as ignorable (9 known properties: \"visible\", \"subPermissions\", \"mutable\", \"tags\", \"permissionName\", \"id\", \"description\", \"displayName\", \"metadata\"])\n at [Source: (String)\"{\n    \"id\": \"4a3c845e-db23-41aa-9ba2-8d4154b7e638\",\n    \"replaces\": [\n        \"settings.agreements.enabled\"\n    ]\n}\"; line: 3, column: 18] (through reference chain: org.folio.rest.jaxrs.model.PermissionUpload[\"replaces\"])",
            "type": "1",
            "code": "-1",
            "parameters": [
                {
                    "key": "",
                    "value": ""
                }
            ]
        }
    ]
}

The same POST to permissions endpoint without the replaces property was successfull.

then I was told to use /_/tenantpermissions, not /perms/permissions endpoint, but that gave me this error
No suitable module found for path /_/tenantpermissions for tenant diku
and it turned out that I can't use the /_/tenantpermissions interface
Last it was said that it should work how I tried: just change the package.json and it should work. But it didn't.
Additionally I was told that's not possible to change the settings.agreement.enabled permission which we defined wrongly and need to change also.
According to a comment in UIIN-2328 it should be sufficient to change the module version to test the new permission.

That's documentation that should be helpful:

https://dev.folio.org/faqs/explain-permissions-system/

https://github.com/folio-org/okapi/blob/00ff6e6b0902df2f3984d33355ad141191137922/doc/security.md

https://folio-org.atlassian.net/wiki/display/PLATFORM/FOLIO+permission+model

https://github.com/folio-org/mod-permissions/blob/master/NEWS.md#static-permission-migration

https://github.com/folio-org/okapi/blob/master/doc/guide.md#permissions-and-the-_tenantpermissions-interface

https://s3.amazonaws.com/foliodocs/api/mod-permissions/r/permissions.html

https://s3.amazonaws.com/foliodocs/api/mod-permissions/r/tenantPermissions.html