useAuthFlow

Overview

Registers reauthentication routing behaviour, produces a submission error handler, and provides a form context.

By default the form's action needs a recent session. Whenever storeUser.authPendingFlow is a reauthentication flow, including when the form is set up, the user is sent to the reauthenticate route with the current path as redirect. Every who-is response for a signed-in user whose session is no longer recent sets that flow, including the refetch after a 401 response. The redirect therefore happens as soon as the store learns that the session is stale, not only after a refused request.

The storeUser actions that need a recent session, such as setupTOTPDevice and getRecoveryCodes, refetch the current user before they reject with an UnauthorizedError. The submission error handler reads that refetched state. A signed-out user goes to the sign-in route. A pending reauthentication flow sends the user to the reauthenticate route. An action that does not refetch leaves the state from before the request, so its UnauthorizedError goes to the fallback handler.

The fallback handler is the onSubmissionErrorHandler option when given, and defaultOnSubmissionError otherwise. It receives every error that the handler does not redirect for, and only those errors. A caller therefore controls ordinary errors without reimplementing reauthentication.

The watch and the handler share one redirect for each pending flow, so the user sees one toast and one navigation even when both react to the same refused request. When the router reports a failure for either navigation, the handler passes the error to the fallback handler. The next refused submission tries the redirect again.

With requireRecentAuth: false, a pending reauthentication flow does not redirect. A signed-out user still goes to the sign-in route.

Signature

useAuthFlow(options)

Parameters

Name	Type	Required	Description
options	AuthFlowOptions	yes

Returns

AuthFlowContext

Examples

// In a component that owns its own layout:
const formProps = reactive({ initialValues: { password: "" } });
const { formContext, onSubmissionErrorHandler, redirectTo } = useAuthFlow({ formProps });

Source

client/lib/use/useAuthFlow.js:80