fespalier-guards
Guarding and redirecting routes in fespalier — guard.dart (a function over a Riverpod Ref that returns a location or null, for a folder and everything below it, in page-less groups too, and that runs
SKILL.mdskills/fespalier-guards/SKILL.md
GitHubfespalier-guards
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
A guard
// (members)/guard.dart: guards /inbox, /admin and everything in the group
import 'package:fespalier/fespalier.dart';
import 'package:my_app/app.g.dart';
import 'package:my_app/auth.dart';
GuardResult guard(Ref ref, {required Uri uri}) =>
ref.watch(session) ? null : LoginRoute(from: uri.toString()).location;
GuardResult is FutureOr<String?>: a location to redirect to, or null to
let the navigation through; it may be async, but return synchronously when you
can (any Future, even Future.value(...), costs a frame and a blank first frame on a
cold deep link). A guard covers every route at and
below its folder, and the folder needs no page.dart: put the guard in a
(group) (or at the root) to cover a whole section.
- Parameters. First the
Ref ref(positional; the olderProviderContainer cis still accepted), then named:uri(the requested location, query included),extra, the segments of its own folder and above ({required String shop}), and optional nullable query parameters. A guard above$idcannot ask forid. - Order. Outermost first; the first guard to return a location wins; a folder's own guard runs after the ones above it, so an inner guard may assume what an outer one checked. The location a guard returns is navigated to and its guards run in turn.
- No double runs. Each page's
GoRoutegets theredirect; nested pages go through their parent's, and shells get none (go_router runs a matched route's redirect for deep links and for navigation inside shells, tabs included). - It takes a
Ref, not aWidgetRef(a guard has no widget:a guard runs outside the widget tree: take `Ref`).ref.watcha provider and the guard runs again when it changes (since 0.5.0): if the new answer differs from the one the navigation used, the router runs the redirects again. Signing out on/inboxmoves you to login by itself. See "Signing out moves you" below. - Stay sync when you can. A guard that answers synchronously adds no frame and
boots with no blank first frame; any
Future, even a completed one, costs a frame. Return aFutureonly when you await something. - A
guard.dartwith no route at or below its folder is a warning. - To redirect, use a guard, not an
onEnter(since 0.8.1): anobserve.darthook runs after the navigation committed and cannot veto it. Seefespalier-observability. - A guard is not access control: the server must still authorise the data.
Keep the login page outside the guard
A guard covers everything below it, so a login/ folder inside the guarded group is
redirected to itself (/login?from=/login?from=...); go_router gives up at its
redirect limit and the router's error builder shows your not_found.dart:
"Nothing at /login", location stuck where it was. Put login/ beside the
guarded group, never inside it.
Sending people back
LoginRoute(from: uri.toString()).location // /login?from=%2Finbox%3Ffolder%3Dsent
// login/page.dart, when sign-in succeeds:
context.go(returnTo(from)); // from if it is an absolute in-app path, else '/'
context.go(returnTo(from, fallback: '/home'));
returnTo lets only an absolute in-app path through; https://..., //host,
/\host and javascript: all fall back, so a crafted ?from= cannot send people
off your app.
redirect.dart
// old-inbox/redirect.dart: /old-inbox?folder=sent -> /inbox?folder=sent
import 'package:my_app/app.g.dart';
String redirect({String? folder}) => InboxRoute(folder: folder).location;
A folder has a redirect.dart instead of a page.dart. It takes a guard's
parameters (the first one, Ref ref, is optional since 0.5.0, as is the older
ProviderContainer c), inherits the guards above it, gets a typed route named after its
path (OldInboxRoute), and its target's guards run in turn. A tab layout's own folder
cannot hold one. It runs once per navigation and does not watch: a redirect route
never stays on screen.
Two behaviours that surprise
An unparsable segment skips only the guards that read segments or query parameters.
/vault/abc(anint id) skips aguard(..., {required int id})and shows not-found, but a guard that asks for neither (for instance the(members)one above, which takes onlyuri) still runs, so/items/abcunder it redirects to login first. (The 0.3.0 README said all guards are skipped.)Signing out moves you, if the guard watches (since 0.5.0). A guard that
ref.watches the session runs again when it changes, withAppRoutes.router()and with a router of your own built fromAppRoutes.mount(), with norefreshListenable. Three limits: a guard under a pushed page does not react until you pop back to it (the push dropped its subscription, popping runs the guard again); a guard that takesProviderContainer c(or onlyref.reads) never runs again by itself, as on 0.4.1 and earlier, where no guard did; and a sign-out runs the guard twice (Riverpod recomputes it, then the router asks), without fetching the providers it watches twice. Don'tref.keepAlive()in a guard: it leaks a provider per navigation. A guard that throws never moves the router: on a navigation its failure shows the route's error.dart (or the not-found view), reported once in every build mode throughFlutterError.onError, on every go_router (since 0.21.0). Details and a compiled sample:references/auth-patterns.md.DevTools shows each decision (since 0.7.0). Its Guards tab lists every guard and
redirect.dartthat answered, withpass,redirect(and where to),pendingorerrorfor an async guard, orskippedwhen a segment did not parse; a redirect chain is one history entry. The generatedredirect:wraps each call intraceGuard, which returns the guard's own result, so a sync guard stays sync (fespalier-troubleshooting, its DevTools page); since 0.21.0 that sits insiderunRedirect, which returns a sync answer as it is (the very object, still sync) and, for an async guard, a newFuturewith the same value, or with the failure as aGuardFailure.A menu runs your guards too (since 0.8.1).
AppMenu.watch(ref)(generated fromnav.dartfiles) asks the guards that run for each guarded entry, with the entry's own location, to list, switch off or hide it. It follows aRefguard'sref.watches, shows an entry pending while an async guard is out, and reads aProviderContainer cguard once. Keep guards cheap and free of side effects (fespalier-layouts, its page on menus and breadcrumbs).
fespalier_auth (since 0.9.0)
fespalier's core has no auth feature; the fespalier_auth package (a git dependency next to fespalier, same
url, same ref) packages the pattern below: a session provider (authSession), restoreAuth for startup(),
token storage, lazy single-flight refresh with no timer, guard helpers and an HTTP client that attaches the
session to your API. It changes no generated code, adds no file kind, key or command.
// app/(signed-in)/guard.dart: the group needs a session; sign-in/ sits BESIDE it
GuardResult guard(Ref ref, {required Uri uri}) =>
requireSignedIn(ref, uri, signIn: (from) => SignInRoute(from: from));
// app/sign-in/guard.dart: the trap. Without it, signing in changes the session and nothing moves
GuardResult guard(Ref ref, {String? from}) => redirectIfSignedIn(ref, from: from);
// app/startup.dart
FutureOr<List<Override>> startup() => restoreAuth(authSetup());
redirectIfSignedInis what sends the user back. It watches the session, so signing in on the sign-in page navigates tofromby itself; the page has nocontext.go.returnTorefuses//hostandhttps://….No
refreshingstate. A refresh keepsSignedIn;isSignedInandauthUserdo not notify on a token swap, so no guard runs again. A refused refresh token isSignedOut(reason: SignOutReason.expired); a network error keeps the session (AuthUnavailable).Guards stay synchronous once
startup()returnsrestoreAuth(...)(no network, ever: an expired access token is refreshed by the first request). Without it the guards answer aFuturewhile the session restores.authHttpClientsends the session only toAuthConfig.apiOrigins, refreshes once when the token has expired (shared by every request that finds it so: refresh-token rotation needs one refresh), and sends a request again after a 401, at most three sends. WatchauthUserIdin adata.dart: a user change reloads it, a refresh does not.Tests:
fakeAuth(signedInAs: ...)frompackage:fespalier_auth/testing.dartis theoverridesofpumpRouter; seefespalier-testing.Never log or put a token, an id or an e-mail in an error or a telemetry attribute: the package's own
toStrings hide them.With
fespalier_cratestack(since 0.10.0):crateStackScope.overrideWith((ref) => ref.watch(authUserId)), and a sign-out callsref.read(crateStackAccount).clear()beforesignOut(), whose state flips synchronously (orclear(scope: id)after). A401keeps a queued intent's key (fespalier-offline).OpenID Connect and Keycloak are in the package (
package:fespalier_auth/oidc.dart,OidcBackend: code flow with PKCE for a public client, Keycloak's endpoints and roles, refresh-token rotation). Firebase and Supabase are recipes, not packages.references/auth-backends.mdhas the code and what was read from a live Keycloak 26.8.0.A replay after a 401 is marked (
isAuthReplay(request),options.extra[authReplayKey]) and keeps anAbortableRequest's abort trigger. Never putRetryClientunder the session client: it re-sends the same DPoP proof and the server refuses it. WrapauthHttpClientin it instead.Device-bound tokens are the
fespalier_sign_keypairpackage (a third git dependency with the sameurlandref):OidcBackend(proof: DpopProof.device())signs every token call and API request with a key in the Secure Enclave or the AndroidKeyStore (DPoP, RFC 9449), and the server binds the tokens to it.DpopProof.device()throwsDpopUnavailableon the web, Windows and Linux unlessfallback: DpopFallback.software(a key in memory) orDpopFallback.bearer(no DPoP) is given. Sign-out deletes the key. Keycloak sends no nonce and noDate, so a wrong device clock isDPoP proof is not active: set the clock.references/auth-dpop.md.
references/auth-package.md has the pieces, a compiled starter (a backend over
a JSON API, the guards, the sign-in form, an API call and its tests) and every behaviour above in detail;
examples/auth is the running version (guards, form, refresh, restore, Keycloak realm). Its messages are in
fespalier-troubleshooting (its diagnostics-auth.md page).
Feature flags (fespalier_flags, since 0.9.0)
fespalier's core has no flag feature; the fespalier_flags package (a git dependency next to fespalier, same url,
same ref) is a guard with a source of values. It adds no dependency beyond fespalier, no timer and no polling, and
changes no generated code.
// flags.dart
const labs = BoolFlag('labs');
// app/labs/guard.dart: /labs is there while the flag is on; a nav.dart beside it is hidden while it is off
GuardResult guard(Ref ref) => flagGuard(ref, labs, orElse: const HomeRoute().location);
// app/startup.dart
Future<List<Override>> startup() async => [
flagSource.overrideWithValue(const ConstFlags({'labs': bool.fromEnvironment('LABS')})),
];
- A flag is synchronous:
ref.watch(flag(labs))is abool, never anAsyncValueor aFuture, and a flag that is not known yet is its fallback. So the guard stays sync, the first frame is not blank, and menus (which run guards) hide the entry for free. - One
guard.dartper folder: compose with??(flagGuard(...) ?? requireSignedIn(...)). - Never call a vendor's async API in a guard (PostHog's
isFeatureEnabledis aFuture: the entry turns pending and the first frame is blank). Put the value behind aFlagSource. follow: falsefor a flow: with the default, turning the flag off on the page takes the user off it.- A guard that redirected stays subscribed until the next navigation, so a flag's subscription outlives the page it gated by one navigation (a test pins it). A guarded page under a pushed page reacts only when uncovered.
- A cold deep link before the source is ready sees the fallback: await the vendor's local load in
startup(), or wrap a network-first vendor inAsyncFlags(the app's own.timeout()is the only timer). - Without an override every flag is its fallback. A flag that is "always off" is no override in
startup(), or a key typo (FakeFlags.strictin tests). - Not built: a
route.dartconstant for a flag, vendor packages, a DevTools flag panel.
references/feature-flags.md has the package in full and a compiled starter (the route, the
guard, the menu entry, startup() and the tests); references/flag-sources.md has the vendor
bridges as compiled recipes (Firebase Remote Config, LaunchDarkly, PostHog, GrowthBook, an OpenFeature sketch). examples/features has /labs behind a flag. The tests use
FakeFlags from package:fespalier_flags/testing.dart (fespalier-testing); the run-time
messages are in fespalier-troubleshooting (its
diagnostics-flags-storage-network.md page).
Biometric unlock (since 0.13.0)
package:fespalier_biometrics puts a route behind a fingerprint or a face. A guard never prompts: a guard runs again
whenever something it watches changes, and one that showed the platform's sheet would show it again each time.
requireUnlocked(ref, uri, unlock: (from) => UnlockRoute(from: from), maxAge:) reads the unlock state and redirects,
synchronously; the unlock page beside the guarded folder calls ref.read(biometricUnlock.notifier).unlock(reason)
(single-flight, never throws) and goes to returnTo(from); withBiometrics(ref, reason, action, maxAge:) makes an
action ask again and throws BiometricDeclined. The app gives a BiometricPrompt in startup()
(biometricPrompt.overrideWithValue(...)); local_auth is a recipe, not a dependency, because its 2.x and 3.x cannot
share one source. The state relocks when the app comes back from the background (core's appShowSignal, not a notification shade or
the platform's sheet) at least BiometricPolicy.resumeGrace after the unlock, with no timer and no listener; the
default 10 s grace is a security trade-off the reference states; maxAge is checked at the next navigation, never by
itself. Since 0.19.0 BiometricPolicy(idleTimeout:) locks after that long without a touch: BiometricActivity in
MaterialApp.router(builder:) records touches and keys and absorbs (and locks on) the first touch after the limit, and the
app fires biometricIdleTicker from its own Timer.periodic (at most idleTimeout / 4, paused while hidden; the package
has no timer). requireUnlocked and isFresh treat an idle unlock as locked at the next navigation. Telemetry is fespalier.biometrics.prompt with fespalier.biometrics.result. Since 0.19.0 a secret can be kept behind the biometric: the app gives a BiometricSecrets (biometricSecrets.overrideWithValue(...); flutter_secure_storage is a compiled recipe, not a dependency) and ref.read(biometricUnlock.notifier).readSecret(key, reason) answers SecretFound, SecretMissing or SecretRefused(outcome); the keystore gates the item (a value hidden behind unlock() in Dart is readable by code that skips the guard), the read is one sheet at a time (it waits for an unlock() sheet; two reads of one key share one), a read does not unlock the app, and the value goes to the caller only (fespalier.biometrics.secret telemetry: constants, never the key, value or reason). Since 0.19.0 BiometricLockScreen (package:fespalier_biometrics/material.dart, the one Material library) is
the unlock page's body: its button prompts on a tap and never otherwise, it shows the failed and lockedOut words, and
an unavailable: builder replaces the button on a device that cannot ask. To ask as the page opens, use the unlock
folder's observe.dart onEnter (after the frame), never build. Never call unlock()
from build or a guard; never put requireUnlocked on the unlock page.
references/biometrics.md has the package in full and a compiled starter;
references/biometric-lock-screen.md the lock screen with the onEnter auto-prompt;
references/biometric-secrets.md the flutter_secure_storage recipe for secrets;
references/biometric-prompts.md (local_auth 3.x) and
references/biometric-prompts-local-auth-2.md (2.x, with
useErrorDialogs: false) are the prompt recipes. The tests use FakeBiometricPrompt and FakeBiometricSecrets from
package:fespalier_biometrics/testing.dart (fespalier-testing).
Where to read more
| Need | Reference |
|---|---|
Every guard and redirect rule, compiled samples, returnTo details |
references/guards-and-redirects.md |
| Session provider, sign-in/out, guards that re-run, async guards | references/auth-patterns.md |
fespalier_auth (since 0.9.0): restore, guards, refresh, HTTP, tests |
references/auth-package.md |
| OpenID Connect, Keycloak, Firebase, Supabase, your own API, dio | references/auth-backends.md |
Device-bound tokens: DPoP, fespalier_sign_keypair, proofs in tests |
references/auth-dpop.md |
Feature flags (since 0.9.0): flagGuard, flag providers, FakeFlags |
references/feature-flags.md |
| Flag sources (since 0.9.0): Remote Config, LaunchDarkly, PostHog, GrowthBook | references/flag-sources.md |
Biometric unlock (since 0.13.0): requireUnlocked, unlock(), withBiometrics, relock, idle lock, BiometricLockScreen (since 0.19.0) |
references/biometrics.md |
BiometricLockScreen with an onEnter auto-prompt (since 0.19.0) |
references/biometric-lock-screen.md |
local_auth as a BiometricPrompt (3.x, and 2.x for Flutter before 3.38) |
references/biometric-prompts.md, references/biometric-prompts-local-auth-2.md |
flutter_secure_storage as BiometricSecrets: a secret behind the biometric (since 0.19.0) |
references/biometric-secrets.md |
| Testing a guarded route | fespalier-testing |
An fsp error on a guard or redirect |
fespalier-troubleshooting |