Middleware

Introduction#

EnsureAuthenticated blocks a signed-out visitor from a protected route, and RedirectIfAuthenticated blocks a signed-in visitor from a guest-only page such as the login form. Both extend MagicMiddleware and override redirectTarget, so the redirect resolves inside the router's redirect callback before any page builds; the destination view mounts exactly once instead of building the gated page and then remounting.

Registering the Aliases#

Register them once in your app's Kernel, using the exact alias names 'auth' and 'guest' that the starter's own route groups reference:

import 'package:magic/magic.dart';
import 'package:magic_starter/magic_starter.dart';

void registerMiddleware() {
  Kernel.registerAll({
    'auth': () => EnsureAuthenticated(),
    'guest': () => RedirectIfAuthenticated(),
  });
}

Call registerMiddleware() once from your bootstrap, before the router builds its routes. starter:install does this for you in lib/app/kernel.dart, with copies of the two classes it scaffolds into lib/app/middleware/ (see Gotchas).

EnsureAuthenticated#

Redirects an unauthenticated visitor to MagicStarterConfig.loginRoute(). It leaves the login route itself alone so the redirect can never loop: go_router raises past five successive redirects.

Before it redirects, it records the location it bounced as the router's intended url (MagicRouter.setIntendedUrl), so a successful sign-in lands there through navigateHome(). Nothing is recorded for the login route or for the guest-only auth pages (register, forgot and reset password, two-factor challenge, OTP). The location carries no query string, so a recorded intent loses a ?token=... the original link had.

MagicRoute.group(
  middleware: ['auth'],
  routes: () {
    // protected routes
  },
);

RedirectIfAuthenticated#

Redirects an already authenticated visitor to MagicStarterConfig.homeRoute(). It leaves the home route itself alone for the same reason: a signed-in visitor landing back on home must not be redirected to home again.

A guest session (is_guest: true) is exempt and stays on the auth pages, because login and registration are where a guest becomes an account.

MagicRoute.group(
  middleware: ['guest'],
  routes: () {
    // auth pages: login, register, forgot/reset password
  },
);

Which Routes Expect Which Alias#

The starter's own route groups assume these aliases are registered:

The email verification and sign-in handoff routes sit outside both groups on purpose: a visitor may open those links signed in or signed out (see Authentication).

If a route names an alias that was never registered, the router throws a StateError naming the route and the alias when it builds, which surfaces from Magic.init.

Gotchas#

Related Documentation#

• Authentication: Auth.check(), login, logout and the routes these guards protect.
• Session Scope: what resets when Auth.stateNotifier changes identity.
• CLI Commands: what starter:install scaffolds and registers.