current_auth API

[jace]

Coaster received an auth framework in #154 and #155 with a proxy named current_auth. The proxy expects a login manager attached to the app that implements a _load_user method. However, as demonstrated in hasgeek/lastuser#229 (the first login manager to attempt a full switch to current_auth), the login manager has two distinct phases during a request:

1. Before request, when cookies are processed and a user is loaded.
2. After request, when a cookie is returned and activity logs are written.

Using current_auth in its current form replaces the first. It triggers a check for a user only when first required, so requests that don't require auth don't run the code. It also allows other before_request handlers to require a user without risk of being called before the user is loaded.

We now need a protocol for the second phase. Previously, we assumed the first phase runs on every request, so post-processing is required for every request. Now we need a flag somewhere to indicate current_auth was invoked during the request.

Perhaps:

1. A CurrentAuth object is constructed every time current_auth is invoked. It should be constructed once and stored on the request context stack as current_auth.
2. CurrentAuth copies the user and auth attributes on the request stack. Is this still necessary? Why not mutate the CurrentAuth object itself? (Using the existing add_auth_attribute helper, as the primary interface is better off read-only.)
3. A new helper function request_had_auth can indicate if the CurrentAuth instance exists.
4. Login managers continue to implement after_request handlers that do tear down, but only if request_had_auth().

[jace]

current_auth needs to work even when there is no request, since current_auth.is_authenticated is the recommended way to test for a user regardless of the situation. This is tricky if current_auth is a request-persistent object living on the stack.

[jace]

In Lastuser, the requires_client decorator provides a g.client instead of a g.user. hasgeek/lastuser#229 replaces g.client with current_auth.client. Since current_auth.user does not exist, current_auth.is_authenticated will return False even though a client has been authenticated.

The is_authenticated call needs to be distinct from is_anonymous, and needs to recognise principals other than users.

[jace]

Clarified in hasgeek/lastuser#91 (comment): principals with agency may be explicitly recognised as "actor" or "agent". add_auth_attribute should accept actor and agent flags to indicate if the attribute is an actor or agent.

[jace]

We've dropped agent for now pending further clarity.