Add new endpoint checkpermissions

[hu-ahmed]

fixes #1137

This PR introduces the implementation of the /checkPermissions endpoint in Ditto’s API, enhancing the authorization model by allowing permission checks on thing, message, and policy resources without modifying them. This endpoint validates whether specified entities have the required permissions for resources, returning authorization statuses in the response. This feature is particularly beneficial for UI-driven applications that rely on dynamic permission-based display logic, where interface elements can be enabled or disabled based on user access rights. Documentation includes usage examples, request structure, and response details.

Example Request
A POST request to /checkPermissions to verify permissions for multiple entities:

{
  "lamp_reader": {
    "resource": "thing:/features/lamp/properties/on",
    "entityId": "org.eclipse.ditto:some-thing-1",
    "hasPermissions": ["READ"]
  },
  "lamp_toggler": {
    "resource": "message:/features/lamp/inbox/messages/toggle",
    "entityId": "org.eclipse.ditto:some-thing-1",
    "hasPermissions": ["WRITE"]
  },
  "policy_admin": {
    "resource": "policy:/",
    "entityId": "org.eclipse.ditto:some-policy-1",
    "hasPermissions": ["READ", "WRITE"]
  }
}

Example Response

{
  "lamp_reader": true,
  "lamp_toggler": false,
  "policy_admin": true
}

[thjaeckle]

Thanks a lot @hu-ahmed for the PR.
Functionality already looks good, I had a first look and did some inline comments.

We should definitely add some unit tests as well for this feature (model classes + for the actor + for the HTTP route).
Javadoc has to be added for every public class/method, etc. .. so choose wisely what to make "public" and what not ;)

[thjaeckle]

Great progress, @hu-ahmed - thanks a lot. 👍
I did another round of review and provided feedback inline, please have a look :)

[thjaeckle]

Added some remarks for the added documentation.

[thjaeckle]

Some few minor fixes needed ..

[thjaeckle]

@hu-ahmed changes look good to me 👍 Thanks a lot for your patience.

Looking forward to a system test: https://github.com/eclipse-ditto/ditto-testing

[thjaeckle]

System tests passed: https://github.com/eclipse-ditto/ditto/actions/runs/11667112664/job/32584674693
See PR for those: eclipse-ditto/ditto-testing/pull/11