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?

[felangel]

Since we closed #1652 do we feel this is still needed? I'm still playing catch up 😅

[mtwichel]

@felangel I still think there's a valid discussion here - basically right now, you can't use dart_frog_auth if you want routes that are optionally authenticated. Your only option if you want routes that might be authenticated is your own custom middleware.

That's fine, but imo it's a common enough task that it should be supported in the auth package.

[erickzanardo]

basically right now, you can't use dart_frog_auth if you want routes that are optionally authenticated.

@mtwichel I don't believe this is true! You can which routes are authenticated and which ones are not: https://dart-frog.dev/advanced/authentication/#filtering-routes

Or does this not work for you for some reason?

[felangel]

@mtwichel bump

[mtwichel]

@erickzanardo The use case I'm describing is a little different than the filtering available. If you filter a route as unauthenticated, it doesn't provide any object to the handler. So, an attempt to context.read (for example) will fail with a state error.

What I'm looking for is support for routes that are optionally authenticated, whereas the current system only allows routes that are authenticated, or not.

For example, a web page that returns a slightly different UI if the user is authenticated (say, their picture in the top right), than if they are unauthenticated (maybe there'd be a login button instead of the picture). Currently to do this, you have to make your own authentication middleware and it's not supported by the dart_frog_auth.

[mtwichel]

Another solution to this problem is something like #1651. The issue is that if you attempt to context.read something that hasn't been provided, it throws an error. Sure, you could write

final User? user;
try {
  user = context.read<User>();
} on StateError catch (_) {
  user = null;
}

But I think it's a bit clunky to do this every time. In practice you could (and I have) just wrapped this logic in an extension method, but it seems a common enough use case that imo dart_frog_auth should support routes that can be access by unauthenticated and authenticated routes alike.

[felangel]

@mtwichel wouldn't the following work:

final user = context.read<User?>();

[marcossevilla]

as @alestiago said here, I prefer renaming to onUnauthorized:

Suggested change

	Handler? unauthenticatedResponse,
	Handler? onUnauthorized,

since we're returning an unauthorized status by default, but I'm also good with onUnauthenticated