Provide way list all actions a user can perform on a subject

[jpbochi]

as discussed on https://gitter.im/stalniy-casl/casl?at=6088455769231732f4c46b01

Is your feature request related to a problem? Please describe.

I'm building a RESTful API, and part of it is the HATEOAS thing. I'll include hyperlinks of actions that the authenticated user can do on each object. This is somewhat similar to what siren specifies.

A good RESTful API is one that doesn't even send a hyperlink to a user that can't execute it.

To give you a concrete example, my API is listing "documents". Each document can be downloaded and/or deleted. The thing is that not every user can download or delete a document. My API will communicate that to the UI by either including the hyperlink to download or delete the document. If the UI doesn't see the link, buttons will be disabled in the UI.

One nice advantage of all this is that the UI can prevent a user from clicking a button just to see a "forbidden" error. Another advantage is that the whole logic can live on the API. I could "pack" the abilities into a JWT or similar, but that would leak some logic I don't want to leak.

Describe the solution you'd like

Having a function like rulesFor that doesn't require an action param would allow me to solve this problem. The only filter would be the subject itself.

Alternatively, we could allow rulesFor to receive an array of actions. The output would be a merge (perhaps with a RuleIndex) of the results from actions.map((action) => ability.rulesFor(action, someSubject))`.

Describe alternatives you've considered (optional)

For now, personally, I'm iterating through all known actions, and doing actions.filter((action) => ability.can(action, someSubject)). The only issue with this is performance. I know that several actions are packed in a single rule, and we could evaluate those only once.

Additional context (optional)

One big caveat here are aliases. I think there are two main options. One, ignore all aliases. Two, include all the ones for which ability.can('some-aliased-action', someSubject) is true.

In my incomplete understanding of the library design, aliases seem to be useful for defining permissions, but not really when querying for them.

A list of actions returned by the HATEOAS-like API described above would only concern "querying" for allowed actions. Which means I'd probably would omit aliases in my case. However, there might be other similar cases where including them would make more sense. A good solution should be flexible to handle both, I think.

[stalniy]

implemented in @casl/[email protected]