RoleMixin needs to accept principals and anchors

[jace]

RoleMixin currently accepts user and token parameters. While currently unused, token was supposed to represent a constraint on, or transfer of a user's roles.

We have since redefined a user as a "principal" that has the property of "agency" (shared with the "client" principal). This is defined in hasgeek/lastuser#91. The parameter name should change to indicate this.

We also have a new abstract concept, an "anchor" that allows us to infer a principal without explicitly requiring one. Inbound anchors, for example a browser session or a secret URL (as used in Boxoffice and previously in Hasjob) allow us to confer roles without needing a user or principal. Tokens are a form of inbound anchor.

RoleMixin should rename its parameters to principal and anchor, and Coaster should perhaps define base classes for the expected sorts of anchors.

[jace]

We have now introduced some ambiguity over what happens when there is more than one principal in a request. This can happen in two situations:

1. hasgeek/flask-lastuser@7f2e40d allows client apps to have "token or cookie" authentication. Cookies are normal browser sessions. Tokens, on the other hand, allow a client (say a native Android app) to access the website mimicking a user. In this case, there are two principals embedded in the access token: the user and the client.

2. Admin "sudo" framework lastuser#153 (Admin "sudo" framework) describes the need for one user to step into the account of another user.

3. We may have a use case where the user is logged in, but receives a special URL that grants them access to another user's data. For example, Boxofifice ticket assignment URLs.

There is only one active user principal in the first and second cases, and no conflicting principal in the third case, so there's no ambiguity over what happens when roles_for(principal=current_auth.principal) is called. However, the other principals must be stored somewhere (see #160), and any special privileges granted by them must manifest via roles_for. How does it receive this awareness of other principals? In the third case, both a principal and an anchor are provided to roles_for, but it currently accepts only one of them.

[jace]

Concern 3 (principal+anchor) can be addressed by accepting both and adding the roles, since roles are always additive.

[jace]

Clarified in hasgeek/lastuser#91 (comment): principals with agency may be explicitly recognised as "actor" or "agent".

[jace]

Actor+agent introduced in 8e6232d.

If we combine scenarios 1 and 2 above (user using a native app and sudoing into another user's account), we now have two agents: the commanding user, and the client app. Where is the scope for handling two agents? Should "agent" be explicitly classified into "client" and "sudoer" here?

[jace]

Since there is no foreseen use case for roles granted to agents, should we not bother with them in RoleMixin? They will still exist in current_auth (#160) and may be reintroduced to roles_for as anchors, should there be a future use case.

Also, given the availability of current_auth, does roles_for make sense anymore? Why not just a current_roles method? In what scenarios will we need to access roles for some other user/actor?