{ "componentChunkName": "component---src-templates-blog-template-js", "path": "/implementing-2fa-totp-with-remix", "result": {"data":{"site":{"siteMetadata":{"title":"Edwards Moses - Web, Mobile - React & React Native Software Developer"}},"markdownRemark":{"html":"\n

Introduction

\n

I've always wondered how 2FA actually worked.You open Google Authenticator, scan a QR code, and suddenly the app starts generating a 6-digit code that keeps changing every few seconds; it felt like magic. From the user's side, the whole thing feels simple. From the app side, though, I wanted to understand the moving pieces properly.

\n

So I decided to build a small demo app, totp-demo to see the whole flow end-to-end: login with email and password, turn on 2FA from settings, scan a QR code, verify the first code, and then enforce that TOTP step on the next login.

\n

Hopefully, by the end, if we don't get lost, we'd have a working 2FA system!

\n

We'll keep the auth system super simple, back it with SQLite, and wire the up TOTP flow.

\n

Getting started

\n

I'm using the current React Router / Remix tooling here, so the project starts with create-react-router:

\n\n
\n
\n Copy\n
\n
\n \n
npx create-react-router@latest totp-demo\ncd totp-demo
\n

I use Remix on a daily, so the route/action flow feels very familiar, but using the latest version to see what's new as well.

\n

I also used this as an excuse to finally try Jujutsu. I've heard enough good things about it for a while now, so I figured I might as well let this demo be the project where I stop procrastinating.

\n

I'm on a Mac, so I installed it with:

\n\n
\n
\n Copy\n
\n
\n \n
brew install jj
\n

Then initialized the repo:

\n\n
\n
\n Copy\n
\n
\n \n
jj git init
\n

That gave me the first clean snapshot of the project:

\n

\"Jujutsu

\n

And jj st gives the status view of the working tree:

\n

\"Jujutsu

\n

Before the first describe, I configured identity:

\n\n
\n
\n Copy\n
\n
\n \n
jj config set --user user.name \"Edwards Moses\"\njj config set --user user.email \"edwardsmoses3@gmail.com\"
\n

And then:

\n\n
\n
\n Copy\n
\n
\n \n
jj describe -m \"chore: start of totp demo\"
\n

\"Jujutsu

\n

Installing the packages

\n

For this demo, I wanted the smallest set of dependencies: .

\n\n

To install them:

\n\n
\n
\n Copy\n
\n
\n \n
npm install speakeasy qrcode better-sqlite3 bcryptjs
\n

We also need a session secret for the cookie session storage. I added this to a .env file at the project root:

\n\n
\n
\n Copy\n
\n
\n \n
SESSION_SECRET=super-secret-but-not-for-production
\n

Setting up the demo database

\n

Since I wanted this rooted in an 'actual' project, I didn't want to wave the data layer away with \"assume auth already exists\".

\n

I'm keeping the demo database intentionally small. We only need a single users table with the normal login bits and the two fields that matter for 2FA:

\n\n

Create app/utils/db.server.ts:

\n\n
\n
\n Copy\n
\n
\n \n
import Database from \"better-sqlite3\";\nimport { hashSync } from \"bcryptjs\";\n\ntype User = {\n  id: number;\n  email: string;\n  password_hash: string;\n  two_factor_enabled: boolean;\n  two_factor_secret?: string;\n  two_factor_temp_secret?: string;\n}\n\nconst db = new Database(\"totp-demo.sqlite\");\n\ndb.exec(`\n  CREATE TABLE IF NOT EXISTS users (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    email TEXT NOT NULL UNIQUE,\n    password_hash TEXT NOT NULL,\n    two_factor_enabled INTEGER NOT NULL DEFAULT 0,\n    two_factor_secret TEXT,\n    two_factor_temp_secret TEXT\n  )\n`);\n\nconst existingUser = db\n  .prepare(\"SELECT id FROM users WHERE email = ?\")\n  .get(\"demo@example.com\");\n\nif (!existingUser) {\n  db.prepare(\n    `\n      INSERT INTO users (\n        email,\n        password_hash,\n        two_factor_enabled\n      ) VALUES (?, ?, 0)\n    `\n  ).run(\"demo@example.com\", hashSync(\"password123\", 10));\n}\n\nexport function findUserByEmail(email: string): User | undefined {\n  return db.prepare(\"SELECT * FROM users WHERE email = ?\").get(email) as User | undefined;\n}\n\nexport function findUserById(id: number): User | undefined {\n  return db.prepare(\"SELECT * FROM users WHERE id = ?\").get(id) as User | undefined;\n}\n\nexport function setTemporaryTwoFactorSecret(userId: number, secret: string) {\n  db.prepare(\n    `\n      UPDATE users\n      SET two_factor_temp_secret = ?\n      WHERE id = ?\n    `\n  ).run(secret, userId);\n}\n\nexport function enableTwoFactor(userId: number) {\n  db.prepare(\n    `\n      UPDATE users\n      SET\n        two_factor_enabled = 1,\n        two_factor_secret = two_factor_temp_secret,\n        two_factor_temp_secret = NULL\n      WHERE id = ?\n    `\n  ).run(userId);\n}\n\nexport function clearTwoFactor(userId: number) {\n  db.prepare(\n    `\n      UPDATE users\n      SET\n        two_factor_enabled = 0,\n        two_factor_secret = NULL,\n        two_factor_temp_secret = NULL\n      WHERE id = ?\n    `\n  ).run(userId);\n}
\n

If you wanna get rid of the red-lines, you can install the types:

\n\n
\n
\n Copy\n
\n
\n \n
npm i --save-dev @types/better-sqlite3
\n

For the demo, I'm seeding a single user directly from the DB helper, so I don't have to build registration too. That gives us a stable account to test against:

\n\n

At this point, the app shape I cared about looked like this:

\n\n
\n
\n Copy\n
\n
\n \n
app/\n  routes/\n    login.tsx\n    settings.2fa.tsx\n    verify-2fa.tsx\n  utils/\n    db.server.ts\n    session.server.ts
\n

Session helpers

\n

We need two session states in this app:

\n\n

That second state is the important part. After the password is correct, we still don't want to treat the user as fully signed in until the TOTP code checks out.

\n

Create app/utils/session.server.ts:

\n\n
\n
\n Copy\n
\n
\n \n
import { createCookieSessionStorage, redirect } from \"react-router\";\n\nconst sessionStorage = createCookieSessionStorage({\n  cookie: {\n    name: \"__session\",\n    httpOnly: true,\n    sameSite: \"lax\",\n    path: \"/\",\n    secure: false,\n    secrets: [process.env.SESSION_SECRET || \"\"],\n  },\n});\n\nexport async function getSession(cookieHeader: string | null) {\n  return sessionStorage.getSession(cookieHeader);\n}\n\nexport async function commitSession(session: any) {\n  return sessionStorage.commitSession(session);\n}\n\nexport async function destroySession(session: any) {\n  return sessionStorage.destroySession(session);\n}\n\nexport async function requireUserId(request: Request) {\n  const session = await getSession(request.headers.get(\"Cookie\"));\n  const userId = session.get(\"userId\");\n\n  if (!userId) {\n    throw redirect(\"/login\");\n  }\n\n  return userId;\n}
\n

I'm using the same cookie for both states; the only thing that changes is which key is present in the session.

\n

Building the login route

\n

We making some progress, nothing visible yet, let's move to the actual auth flow.

\n

The login route checks the email and password. If the user doesn't have 2FA turned on, we set userId in session and redirect home. If they do have 2FA enabled, we set pending2faUserId instead and redirect to /verify-2fa.

\n

Create app/routes/login.tsx:

\n\n
\n
\n Copy\n
\n
\n \n
import { compareSync } from \"bcryptjs\";\nimport { Form, redirect, useActionData, useNavigation } from \"react-router\";\nimport { findUserByEmail } from \"~/utils/db.server\";\nimport { getSession, commitSession } from \"~/utils/session.server\";\n\nexport async function action({ request }: { request: Request }) {\n  const formData = await request.formData();\n  const email = formData.get(\"email\")?.toString().trim() || \"\";\n  const password = formData.get(\"password\")?.toString() || \"\";\n\n  const user = findUserByEmail(email);\n\n  if (!user || !compareSync(password, user.password_hash)) {\n    return { error: \"Invalid email or password.\" };\n  }\n\n  const session = await getSession(request.headers.get(\"Cookie\"));\n\n  if (user.two_factor_enabled) {\n    session.set(\"pending2faUserId\", user.id);\n\n    return redirect(\"/verify-2fa\", {\n      headers: {\n        \"Set-Cookie\": await commitSession(session),\n      },\n    });\n  }\n\n  session.set(\"userId\", user.id);\n\n  return redirect(\"/\", {\n    headers: {\n      \"Set-Cookie\": await commitSession(session),\n    },\n  });\n}\n\nexport default function Login() {\n  const actionData = useActionData();\n  const navigation = useNavigation();\n\n  return (\n    <div>\n      <h1>Login</h1>\n\n      <Form method=\"post\">\n        <input type=\"email\" name=\"email\" placeholder=\"demo@example.com\" required />\n        <input\n          type=\"password\"\n          name=\"password\"\n          placeholder=\"password123\"\n          required\n        />\n        <button type=\"submit\">\n          {navigation.state === \"submitting\" ? \"Signing in...\" : \"Sign in\"}\n        </button>\n      </Form>\n\n      {actionData?.error ? <p>{actionData.error}</p> : null}\n    </div>\n  );\n}
\n

I like this split because the password step stays boring. The only extra branch is whether we stop there or send the user to the second factor page.

\n

So, the below bit was something new, I'm used to the previous filesystem always routing for Remix, but in the new React Router flow, that needs to be explicitly configured.

\n

First, we want to install:

\n\n
\n
\n Copy\n
\n
\n \n
npm i @react-router/fs-routes
\n

Then, we want to replace app/routes.ts with:

\n\n
\n
\n Copy\n
\n
\n \n
import { type RouteConfig, index } from \"@react-router/dev/routes\";\nimport { flatRoutes } from \"@react-router/fs-routes\";\n\nexport default [...(await flatRoutes())] satisfies RouteConfig;
\n

I'm definitely not winning any design awards for this login page:

\n

\"our

\n

Generating the QR code and turning on 2FA

\n

Once the user is logged in, we can give them a page to enable 2FA.

\n

The first job on /settings/2fa is to generate a new secret and store it in two_factor_temp_secret. I only move it into two_factor_secret after the user proves the setup worked by entering a valid code from their authenticator app.

\n

Create app/routes/settings.2fa.tsx:

\n\n
\n
\n Copy\n
\n
\n \n
import QRCode from \"qrcode\";\nimport speakeasy from \"speakeasy\";\nimport { Form, useActionData, useLoaderData } from \"react-router\";\nimport {\n  findUserById,\n  setTemporaryTwoFactorSecret,\n  enableTwoFactor,\n} from \"~/utils/db.server\";\nimport { requireUserId } from \"~/utils/session.server\";\n\nasync function qrCodeForSecret(userEmail: string, secret: string) {\n  const otpAuthUrl = speakeasy.otpauthURL({\n    secret,\n    label: `totp-demo:${userEmail}`,\n    issuer: \"totp-demo\",\n    encoding: \"base32\",\n  });\n\n  return QRCode.toDataURL(otpAuthUrl);\n}\n\nexport async function loader({ request }: { request: Request }) {\n  const userId = await requireUserId(request);\n  const user = findUserById(userId);\n\n  if (!user) {\n    throw new Response(\"User not found\", { status: 404 });\n  }\n\n  return {\n    twoFactorEnabled: Boolean(user.two_factor_enabled),\n  };\n}\n\nexport async function action({ request }: { request: Request }) {\n  const userId = await requireUserId(request);\n  const user = findUserById(userId);\n  const formData = await request.formData();\n  const intent = formData.get(\"intent\");\n\n  if (!user) {\n    throw new Response(\"User not found\", { status: 404 });\n  }\n\n  if (intent === \"generate\") {\n    const secret = speakeasy.generateSecret({\n      name: user.email,\n      issuer: \"totp-demo\",\n    });\n\n    setTemporaryTwoFactorSecret(userId, secret.base32);\n\n    return {\n      qrCodeDataUrl: await QRCode.toDataURL(secret.otpauth_url || \"\"),\n      success: false,\n    };\n  }\n\n  if (intent === \"verify\") {\n    const token = formData.get(\"token\")?.toString() || \"\";\n\n    if (!user.two_factor_temp_secret) {\n      return { error: \"Start setup again so we can generate a new secret.\" };\n    }\n\n    const verified = speakeasy.totp.verify({\n      secret: user.two_factor_temp_secret,\n      encoding: \"base32\",\n      token,\n      window: 1,\n    });\n\n    if (!verified) {\n      return {\n        error:\n          \"That code didn't match. Try the current code from your authenticator app.\",\n        qrCodeDataUrl: await qrCodeForSecret(\n          user.email,\n          user.two_factor_temp_secret,\n        ),\n      };\n    }\n\n    enableTwoFactor(userId);\n\n    return {\n      success: true,\n    };\n  }\n\n  return { error: \"Unknown action.\" };\n}\n\nexport default function TwoFactorSettings() {\n  const actionData = useActionData();\n  const loaderData = useLoaderData();\n\n  return (\n    <div>\n      <h1>Two-Factor Authentication</h1>\n\n      {loaderData.twoFactorEnabled ? (\n        <p>2FA is already enabled on this account.</p>\n      ) : null}\n\n      {!actionData?.qrCodeDataUrl && !actionData?.success ? (\n        <Form method=\"post\">\n          <input type=\"hidden\" name=\"intent\" value=\"generate\" />\n          <button type=\"submit\">Generate QR code</button>\n        </Form>\n      ) : null}\n\n      {actionData?.qrCodeDataUrl ? (\n        <div>\n          <p>\n            Scan this with Google Authenticator, Microsoft Authenticator, or\n            Authy.\n          </p>\n          <img src={actionData.qrCodeDataUrl} alt=\"TOTP QR code\" />\n\n          <Form method=\"post\">\n            <input type=\"hidden\" name=\"intent\" value=\"verify\" />\n            <input\n              type=\"text\"\n              name=\"token\"\n              placeholder=\"123456\"\n              maxLength={6}\n              required\n            />\n            <button type=\"submit\">Verify and enable 2FA</button>\n          </Form>\n        </div>\n      ) : null}\n\n      {actionData?.error ? <p>{actionData.error}</p> : null}\n      {actionData?.success ? <p>2FA is now enabled for this account.</p> : null}\n    </div>\n  );\n}
\n

A couple of useful things are happening here:

\n\n

That temporary secret field is doing a real job for us. If the user abandons setup halfway through, we haven't fully enabled 2FA yet, and we haven't accidentally made the account harder to access.

\n

If you haven't already, let's also install the types for the packages we're using in this route:

\n\n
\n
\n Copy\n
\n
\n \n
npm i --save-dev @types/qrcode\nnpm i --save-dev @types/speakeasy
\n

Okay, now we have the QR code displayed, yay progress!!

\n

\"yay,

\n

Verifying the TOTP code during login

\n

Now for the enforcing part.

\n

When a user with 2FA enabled logs in, we redirect them to /verify-2fa. On this route, we read pending2faUserId from session, look up the stored secret, and verify the submitted token.

\n

If the token is correct, we promote the session from \"pending 2FA\" to \"fully logged in\".

\n

Create app/routes/verify-2fa.tsx:

\n\n
\n
\n Copy\n
\n
\n \n
import speakeasy from \"speakeasy\";\nimport { Form, redirect, useActionData, useNavigation } from \"react-router\";\nimport { findUserById } from \"~/utils/db.server\";\nimport { getSession, commitSession } from \"~/utils/session.server\";\n\nexport async function loader({ request }: { request: Request }) {\n  const session = await getSession(request.headers.get(\"Cookie\"));\n\n  if (!session.get(\"pending2faUserId\")) {\n    throw redirect(\"/login\");\n  }\n\n  return null;\n}\n\nexport async function action({ request }: { request: Request }) {\n  const session = await getSession(request.headers.get(\"Cookie\"));\n  const pendingUserId = session.get(\"pending2faUserId\");\n  const token = (await request.formData()).get(\"token\")?.toString() || \"\";\n\n  if (!pendingUserId) {\n    throw redirect(\"/login\");\n  }\n\n  const user = findUserById(pendingUserId);\n\n  if (!user || !user.two_factor_secret) {\n    return { error: \"This account doesn't have 2FA enabled.\" };\n  }\n\n  const verified = speakeasy.totp.verify({\n    secret: user.two_factor_secret,\n    encoding: \"base32\",\n    token,\n    window: 1,\n  });\n\n  if (!verified) {\n    return { error: \"Invalid code. Try the latest code from your authenticator app.\" };\n  }\n\n  session.unset(\"pending2faUserId\");\n  session.set(\"userId\", user.id);\n\n  return redirect(\"/\", {\n    headers: {\n      \"Set-Cookie\": await commitSession(session),\n    },\n  });\n}\n\nexport default function VerifyTwoFactor() {\n  const actionData = useActionData();\n  const navigation = useNavigation();\n\n  return (\n    <div>\n      <h1>Verify 2FA</h1>\n      <p>Enter the 6-digit code from your authenticator app.</p>\n\n      <Form method=\"post\">\n        <input\n          type=\"text\"\n          name=\"token\"\n          placeholder=\"123456\"\n          maxLength={6}\n          required\n        />\n        <button type=\"submit\">\n          {navigation.state === \"submitting\" ? \"Checking...\" : \"Verify code\"}\n        </button>\n      </Form>\n\n      {actionData?.error ? <p>{actionData.error}</p> : null}\n    </div>\n  );\n}
\n

And, we have a winner on our hands! With this, the loop is completed.

\n

At this point, the app behaves the way I wanted from the start:

\n\n

A quick note

\n

For this demo, I'm storing the TOTP secret directly in SQLite so the flow is easy to follow.

\n

In a real application, I'd treat that secret much more carefully:

\n\n

I'm intentionally leaving recovery codes and more complex logic / edge-cases out of this walkthrough so the core TOTP flow stays easy to follow.

\n

Testing the flow

\n

Once everything was wired up, I ran through the whole thing with the seeded user.

\n

The test path is pretty simple:

\n
    \n
  1. Sign in with demo@example.com and password123.
    2. \n
  2. Visit /settings/2fa and generate a QR code.
    3. \n
  3. Scan the QR code with an authenticator app.
    4. \n
  4. Enter the current 6-digit token to finish setup.
    5. \n
  5. Sign out and log back in.
    6. \n
  6. Confirm the app now pauses at /verify-2fa before finishing login.
    7. \n
\n

A few useful failure cases to test too:

\n\n

If you can get through those cases cleanly, the implementation is in a pretty solid place.

\n

Wrapping up

\n

This was a really fun one.

\n

TOTP feels a lot less magical once I got hands-on. At the end of the day, the flow is just:

\n\n

The nice part is how well this fits the Remix model.

\n

If you're adding this to an existing app, the main pieces to lift from the demo are the same ones that made this one work: temporary secret during setup, permanent secret after verification, and a separate login state for users who are halfway through authentication.

\n

Here's the repo, if you wanna grab and run the project: Totp Remix demo

\n

I'd like to chat with anyone who has implemented this in a production system, any weird edge-cases you have encountered ?

\n

Drop a comment below, I'd love to know.

\n

Until next time, folks!!

\n

PS: Not any closer to figuring out Jujutsu, yet, the mental model still feels foreign..

\n","frontmatter":{"date":"April 12, 2026","path":"/implementing-2fa-totp-with-remix","title":"Implementing Two-Factor Authentication (2FA) with TOTP in a Remix app","thumbnail":"/assets/totp/edwardsmoses.com_pexels-zulfugarkarimov-33440144.jpg","metaDescription":null}}},"pageContext":{}}, "staticQueryHashes": ["3604841143"]}