feat(dart_frog_auth): add custom unauthenticated responses to all aut…

[mtwichel]

Status

READY

Description

Closes #1631. Adds an optional unauthenticatedResponse to all auth middleware which enables users to customize the response returned when a user is unauthenticated.

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 🛠️ Bug fix (non-breaking change which fixes an issue)
• ❌ Breaking change (fix or feature that would cause existing functionality to change)
• 🧹 Code refactor
• ✅ Build configuration change
• 📝 Documentation
• 🗑️ Chore

[alestiago]

I am yet not sure if there could be a better API that the one suggested in the PR.

I think the main issue is that the existence of unauthenticatedResponse makes the programmer feel there should exist an authenticatedResponse counterpart. Then, having both exist makes me question if we could merge them into a single parameter and allow the user to dictate the logic.

I've been thinking about how would it look like if instead we had an responseOverride parameter where the programmer gets a user and decide how to handle the authorization; but it didn't convince me. Mainly because if you would only like to override the unauthenticated behavior the programmer would be forced to define the current default handler(context.provide(() => user)); for authenticated cases redundantly. In addition I feel that something similar could be achieved by chaining a middleware.

I have this other idea, where I think we should make a clear distinction between authentication and authorization. As of right now, the bearerAuthentication is doing both, authentication and authorization (despite its name being solely bearerAuthentication). The authorization logic is quite basic, if the authentication is a null user then deny access by returning an HttpStatus.unauthorized response. What we could do is introduce an authorizer parameter (that defaults to the current behavior user != null and returns an HttpStatus.unauthorized response). Yet, I'm not sure if we could provide a better API by leveraging the existing Dart Frog structure, for example by defining an Authorizer middleware.

---

Regarding the suggest API in this PR , a change I'm sure about is that if we end up going forward with it is renaming the parameter to remove the "Response" suffix, since it it not of type Response but Handler, here are some name alternatives:

• onUnauthenticated
• unauthenticatedHandler
• onAuthenticationFailure

I tend to prefer onUnauthenticated.

[mtwichel]

we should make a clear distinction between authentication and authorization

This makes a ton of sense to me and is possibly the root of why I felt this change was needed. But this could also be solved with #1652 (or something similar) by moving the authorization logic to the handler itself. For example

Response onRequest(RequestContext context) {
  final user = context.tryRead<User>();
  if (user == null) {
    // Unauthenticated
    return UnauthenticatedResponse();
  }
  if (!hasPermission(user)) {
    // Unauthorized
    return UnauthorizedResponse();
  }

  return RealResponse();
}

Overall I think this is a very transparent solution and is the most flexible. But currently this won't work because if you are unauthenticated, the middleware will just return a 401 response and your handler will never actually happen.

That would be a pretty big breaking change for the auth handlers, so maybe it could be opt-in with a parameter?

bearerAuthentication<User>(
  guarded: false // when true, a default 401 response will be returned. Otherwise, no user will be provided.
)

Or maybe it could be a separate middleware for that behavior?