Could we have a bit more documentation for the parameters here? With the merge of the two rejections (which I agree to) I now find it a bit difficult to understand why this class has those parameters and what they mean. (This is not your fault btw, you just merged but we could now improve things)

Is there a better name for `authHeaderPresent`? Or maybe an enum instead to distinguish CredentialsMissing and CredentialsRejected more easily?

Also, it is hard to understand why `params` are included in this rejection and how the `params` in the rejection, in `HttpChallenge`, in `HttpCredentials`, and in `HttpAuthenticator` are related in detail. If I understand the RejectionHandler code correctly, the `HttpAuthenticator` is asked to extract (or generate?) `params` from the context at the time authentication fails and the rejection is generated. E.g. if one would implement digest authentication the `params` map would already contain the new nonce for the next request and not the one that failed the request.

So, now the rejection seems to carry two bits of information: 1) what failed and how (credentials missing or rejected) and 2) partial information on how to go on (i.e. by adding a `WWW-Authenticate` header appropriately parameterized). Couldn't we make the rejection a bit more general by changing it's definition to be the rejection for all kinds of authentication failures which would result in a 401 status code + some added headers (or even some arbitrary change of the response) ?

```scala
sealed trait AuthenticationFailureCause
case object CredentialsMissing extends AuthenticationFailureCause
case object CredentialsRejected extends AuthenticationFailureCause
case class AuthenticationFailedRejection(cause: AuthenticationFailureCause, addChallengeToResponse: HttpResponse => HttpResponse)
```
or maybe better:
```scala
case class AuthenticationFailedRejection(cause: AuthenticationFailureCause, authenticator: HttpAuthenticator)
```

and then use a new method in the authenticator to generate the next challenge.

WDYT?