Add passkey sign-in to React Router Framework Mode

React Router Framework Mode can start a hosted passkey login from a server action and receive the result in a server loader. Sudomimus runs the WebAuthn challenge. The official @sudomimus/react-router adapter handles the Connect exchange and server session; your application decides what the signed-in user may do.

Start with a Node.js Framework Mode project. Install @sudomimus/react-router, @sudomimus/web, @sudomimus/connect, and @sudomimus/session. This guide uses Connect; see OIDC or Connect if you need to choose a protocol. The application sign-in page shows the hosted experience.

The example uses a single process and in-memory storage for development. Production requires a shared durable store. A browser-only SPA cannot run these server handlers.

1. Configure passkeys and the Connect callback

In the With portal, create an organization and application. Save its immutable applicationAnchor. Register the application’s RS256 client-auth public key and keep the paired private key in your backend’s secret store. This key signs Connect requests; it is separate from a user’s passkey.

Configure all three rule layers:

Use https://app.example.com/auth/callback in production, replacing the host with yours. For local development, Connect also permits a loopback HTTP callback such as http://localhost:5173/auth/callback. Permit its host in the application’s CALLBACK rule. Keep the callback on the same origin as the page that submits login and logout. Do not add exposure-key or confirmation-key to the configured URL; Connect appends those query parameters.

Activate the application after configuring its rules. Register a passkey in your Sudomimus account before testing. Enabling a passkey rule does not enroll a credential for the user. See the passkey rule guide and Connect setup.

2. Configure the server module

Set the application anchor, callback URL, and private-key file path in the server environment. For example, a local callback can use http://localhost:5173/auth/callback. Keep the private PEM outside your public assets and source repository. Do not expose it through browser environment variables.

Create one server-only module. The explicit production check prevents deployment with local in-memory storage.

1
import { readFileSync } from "node:fs";
2
import { ConnectClient } from "@sudomimus/connect";
3
import { createReactRouterHandlers } from "@sudomimus/react-router";
4
import { SessionClient } from "@sudomimus/session";
5
import { MemoryWebAuthStore } from "@sudomimus/web";
6

7
function requiredEnvironment(name: string): string {
8
    const value = process.env[name];
9
    if (!value) {
10
        throw new Error(`Missing server environment variable: ${name}`);
11
    }
12
    return value;
13
}
14

15
if (process.env.NODE_ENV === "production") {
16
    throw new Error("Configure a shared WebAuthStore before production");
17
}
18

19
const applicationAnchor = requiredEnvironment("SUDOMIMUS_APPLICATION_ANCHOR");
20
const connect = new ConnectClient({
21
    clientAuth: {
22
        applicationAnchor,
23
        privateKeyPem: readFileSync(
24
            requiredEnvironment("SUDOMIMUS_CLIENT_AUTH_PRIVATE_KEY_FILE"),
25
            "utf8",
26
        ),
27
    },
28
});
29

30
export const sudomimus = createReactRouterHandlers({
31
    applicationAnchor,
32
    callbackUrl: requiredEnvironment("SUDOMIMUS_CALLBACK_URL"),
33
    afterLoginUrl: "/dashboard",
34
    afterLogoutUrl: "/",
35
    connect,
36
    session: new SessionClient(),
37
    store: new MemoryWebAuthStore(),
38
    pendingTtlSeconds: 600,
39
    sessionTtlSeconds: 86_400,
40
});

The adapter signs /establish, stores the pending Inquiry keys, redirects to the hosted login, redeems the callback once, and verifies the returned access token. hiddenKey, access tokens, and refresh tokens stay in the server store. The browser receives an opaque session cookie.

current() refreshes access tokens near expiry and persists the rotated refresh token. Login creates a fresh local session identifier. Logout revokes the Session API session and clears cookies. The configured local session lasts at most one day; restarting this development server loses pending logins and sessions. Production HTTPS callbacks enable Secure cookies; HttpOnly and SameSite=Lax apply to both environments.

3. Register actions, the callback loader, and page routes

Declare the routes in app/routes.ts. React Router’s route configuration maps each path to a route module.

1
import { type RouteConfig, index, route } from "@react-router/dev/routes";
2

3
export default [
4
    index("routes/home.tsx"),
5
    route("login", "routes/login.tsx"),
6
    route("auth/callback", "routes/auth.callback.tsx"),
7
    route("logout", "routes/logout.tsx"),
8
    route("dashboard", "routes/dashboard.tsx"),
9
] satisfies RouteConfig;

Use actions for login start and logout. Use a loader for the GET callback. Return the handler responses directly so their redirects and Set-Cookie headers reach the browser.

1
import { sudomimus } from "../sudomimus.server";
2

3
export const action = sudomimus.startAction;

1
import { sudomimus } from "../sudomimus.server";
2

3
export const loader = sudomimus.callbackLoader;

1
import { sudomimus } from "../sudomimus.server";
2

3
export const action = sudomimus.logoutAction;

The home page submits a POST. A GET link to /login does not start this flow.

1
import { Form } from "react-router";
2

3
export default function Home() {
4
    return (
5
        <Form method="post" action="/login">
6
            <button type="submit">Sign in with Sudomimus</button>
7
        </Form>
8
    );
9
}

4. Return only the fields the page needs

Read the current session in the dashboard’s server loader. Return only its subject; keep the token pair and pending-login state on the server.

1
import { Form, type LoaderFunctionArgs, redirect, useLoaderData } from "react-router";
2
import { sudomimus } from "../sudomimus.server";
3

4
export async function loader({ request }: LoaderFunctionArgs) {
5
    const session = await sudomimus.current({ request });
6
    if (!session) {
7
        throw redirect("/");
8
    }
9
    return { subject: session.subject };
10
}
11

12
export default function Dashboard() {
13
    const { subject } = useLoaderData<typeof loader>();
14
    return (
15
        <main>
16
            <h1>Signed in</h1>
17
            <p>User: {subject}</p>
18
            <Form method="post" action="/logout">
19
                <button type="submit">Sign out</button>
20
            </Form>
21
        </main>
22
    );
23
}

subject is an application-visible sector-pairwise identifier. Map it to your own user record instead of treating it as an email address. Your application still enforces its own permissions for protected data and operations. The subject comes from a verified token; offline verification does not observe later platform revocation immediately.

5. Test login, refresh, and logout

Open the application, sign in with a registered passkey, and confirm that the browser reaches /dashboard. Sign out, then revisit /dashboard: the loader should redirect to /. To check refresh, remain signed in until the access token approaches expiry and load the dashboard again. The server should rotate the token pair without returning either token to the page.

Before production, replace MemoryWebAuthStore with a shared durable WebAuthStore, then remove the local-only guard. takePending() must consume a matching transaction atomically. withSession() must lock across reading, refreshing, and persisting a session, so concurrent requests do not reuse the same refresh token. Match storage expiry to the configured TTL and protect stored tokens and keys.

Deploy behind HTTPS. Keep the adapter’s POST origin checks, cookie protections, callback checks, and token verification. Avoid logging callback query parameters, cookies, private keys, or tokens. When an operation needs current platform session authority, use live Session introspection; offline token verification cannot observe revocation immediately.

See the React Router integration reference and Session lifecycle guide for the storage and verification contracts. Connect profile data uses Session UserInfo; an OIDC application uses a separate endpoint and scopes, as explained in the email troubleshooting guide.