Rethink security model

[rafalkrupinski]

Currently security description is kinda sorta copied from openAPI, with security requirements declared in the function decorator or as __init__ parameter, and requesting authentication registers httpx.Auth instance with the client.

problems:

1. client instances are stateful/mutable

   client can only be either unauthenticated or authenticated with single credentials at a time.
   Instead it should support with_auth_* pattern, allowing to create authenticated clients from unathenticated one, and potentially sharing connections

2. no API to retrieve scopes from auth instances. Lapidary can't check scopes so declaring them doesn't really do anything

   the only way I can image to automatically use scope information is to require users to declare up-front which operations they intent to use. This would to automatically infer scopes, but I think is an overkill.

3. no way of choosing just-in-time vs eager authentication

   Basically httpx.Auth promotes just-in-time authentication (instances may make requests of their own to do their auth flow). At the same time httpx-auth eagerly refreshes tokens before they expire.
   There are two modes of operation: short- (e.g. CLI) and long-living clients (e.g. web apps). In case of short-living client, it makes sense to authenticate eagerly and execute auth flow as soon as the user makes call to auth function. For long living clients it probably makes sense to postpone authentication with asyncio and it makes sense to set up a timed token refresher.

[rafalkrupinski]

I'm not too fond of httpx auth model, that makes inline auth calls (the auth object may decide it needs to make an extra HTTP request to obtain credentials during httpx handling call to request).

httpx-auth implements the refresh before the token expires, still, it's only done when the user makes request with httpx Client, and httpx-auth implements only sync calls, blocking the event loop and the whole thread while user calls an async request. On one hand it's a problem with colored functions in async python (which httpx-auth avoids by simply not implementing the async interface), on the other, the auth interface in httpx encourages it.

If the program needs to get or refresh the token, it could be simply done at initialization.
In case of long-running programs, like servers or event handlers, if refreshing the token is necessary, a thread or async task could be set scheduled. The user knows their case and the library should facilitate that.