The goal of the permissions system is to provide generic means to both programmers and site administrators to check, grant, or revoke permissions via a consistent interface. For example, an application developer might decide that viewing a certain set of pages within the application is an operation to be individually granted or revoked from a user. It's expected that the permissions system will be heavily used in production - almost every page will make at least one permissions API call, and some will make several.
The permissions systems deals with three kinds of objects: ACSObject, Party, Privilege. The system maintains a set of grants of the form Party p has Privilege priv on ACSObject obj. The privileges represent actions that are performed on objects.
There are generic privileges that are always defined: read, write, edit, admin, create, and delete. In addition, applications can define custom privileges, for example categorize.
The permissions system is used to answer questions such as:
What parties have a particular privilege on a particular object?
What privileges does a particular party have on a particular object?
On what objects does a particular party have a particular privilege?
Much of the power of the permissions system comes from the flexibility of the model. The assertions described above are not the only input. Each privilege can imply some set of privileges. In addition, each ACSObject can have a security context from which it inherits privilege grants. This security context is just another ACSObject. Groups provide a way of aggregating users and the permissions system pays attention to group membership.
The power of the permissions system comes from the interaction of these 3 hierarchies: group membership, security context, and privilege implication. Taking these 3 together, the assertion that p has privilege priv on object obj means that p is a party or a member of a party (at any depth) that was granted priv or a privilege implying privilege priv on object obj or any parent of obj in the security context hierarchy.