Forem: Divyam Gupta

A Practical Guide to Secure 2FA with TOTP

Divyam Gupta — Mon, 23 Feb 2026 15:31:29 +0000

Why Your Password Isn't Enough Anymore?

Passwords get reused, phished, and leaked. It's not a matter of if, it's when. And when it happens, your app pays the price even if you did everything right on your end.

The fix? Add a second layer. Something that lives on the user's phone, changes every 30 seconds, and works even without internet. That's TOTP-based 2FA, and by the end of this guide you'll have it fully wired up in your TypeScript app.

Let's build it.

Disclaimer: This article consists of pieces and excerpts from an educational conversation with Claude Sonnet 4.6

What Even Is TOTP?

TOTP stands for Time-based One-Time Password.

When a user enables 2FA on your app, your server generates a shared secret. It's basically a random string that both your server and the user's authenticator app know about. Using that secret and the current time, both sides independently calculate the same 6-digit code. The user types it in, you verify it, done.

The code refreshes every 30 seconds and is only valid for that window. So even if someone intercepts it, it's already useless by the time they try to use it.

You've probably seen this in action. That little 6-digit code ticking down in Google Authenticator or Authy? That's TOTP.

Why TOTP over SMS OTP?

SMS OTP is convenient but has real problems. SIM swap attacks are a thing, carriers can be socially engineered, and SMS simply doesn't work when you have no signal. TOTP has none of these issues. The code is generated entirely on the device, no network required.

It's also an open standard (RFC 6238), which means it works with any authenticator app including Google Authenticator, Authy, 1Password, and Bitwarden. You're not locking anyone into anything.

How It Actually Works Under the Hood

You don't need to understand cryptography to implement TOTP, but knowing the flow will save you a lot of confusion later.

Here's what happens, step by step.

1. Secret Generation
When a user enables 2FA, your server generates a random secret key. It's a short unique string tied to that user. Think of it as a shared password between your server and their authenticator app. This secret is stored on your server and never shown to the user directly.

2. QR Code
Instead of asking the user to type the secret manually, you encode it into a QR code using a standard format called otpauth URL. The user scans it with their authenticator app, and now the app has the secret stored locally on their phone.

3. Code Generation
Every 30 seconds, the authenticator app combines the secret + current timestamp and runs it through a hashing algorithm (HMAC-SHA1) to produce a 6-digit code. Your server does the exact same calculation independently.

4. Verification
When the user submits a code, your server runs the same calculation and checks if both results match. If yes, access granted. No network calls, no third-party service, just math on both ends arriving at the same answer.

💡 The key insight: Neither side is sending the code to the other. Both sides are independently calculating the same value because they share the same secret and trust the same clock.

Setting Up TOTP in a TypeScript Project

We'll be using two packages: otplib for everything TOTP-related and qrcode to generate the QR code image.

npm install otplib qrcode
npm install -D @types/qrcode

otplib ships with its own TypeScript types so no extra install needed there.

Generating a Secret

When a user wants to enable 2FA, the first thing you do is generate a secret for them on the server.

import { authenticator } from "otplib";

export const generateSecret = (userEmail: string) => {
  const secret = authenticator.generateSecret();
  const otpauthUrl = authenticator.keyuri(userEmail, "YourAppName", secret);

  return { secret, otpauthUrl };
};

generateSecret() gives you a random Base32 string. keyuri() packages it into a standard otpauth:// URL that any authenticator app understands.

Turning That URL Into a QR Code

The otpauthUrl alone isn't useful to the user. We need to render it as a scannable QR code.

import QRCode from "qrcode";

export const generateQRCode = async (otpauthUrl: string): Promise<string> => {
  return await QRCode.toDataURL(otpauthUrl);
};

This returns a base64 image string that you can drop directly into an <img> tag on the frontend. No file storage needed.

const { secret, otpauthUrl } = generateSecret(user.email);
const qrCodeImage = await generateQRCode(otpauthUrl);

// Send qrCodeImage to the frontend
// Store secret temporarily until the user verifies setup

⚠️ Don't save the secret to your database yet. Wait until the user successfully scans the QR and verifies with a valid code. Otherwise you might store secrets for setups that were never completed.

The Registration Flow

This is where everything comes together for the first time. The goal is simple: let the user enable 2FA and confirm they've set it up correctly before you commit anything to the database.

Here's the full picture of what we're building.

User clicks "Enable 2FA" → Backend generates secret + QR → Frontend shows QR → User scans with authenticator app → User submits a verification code → Backend verifies it → Secret saved to DB

Step 1: Generate and Return the QR Code

The user hits "Enable 2FA" in your UI. Your backend generates a secret, creates a QR code, and sends it back. The secret goes into a temporary store like a user session or a short-lived cache, not the database yet.

Step 2: Verify the Setup

After scanning the QR, the user submits the 6-digit code shown in their authenticator app. You grab the pending secret from the session, verify the code against it, and only then save the secret to the database.

💡 Why verify before saving? If you save the secret immediately and the user never completes the scan, their account now has a 2FA secret attached that they can't use. They'll be locked out on next login. Always confirm first.

The Login Flow

The login flow with TOTP is just your existing login with one extra step added at the end.

User submits email and password. You verify credentials as usual. If the user has 2FA enabled, you don't issue a token yet. Instead you return a signal to the frontend saying a second factor is needed.

The frontend then shows a code input screen. The user opens their authenticator app, types in the 6-digit code, and submits it. Your backend grabs their stored secret, runs authenticator.verify({ token: code, secret }) and if it passes, now you issue the token and let them in.

The key thing to get right here is the in-between state. After password verification but before TOTP verification, the user is neither fully authenticated nor a stranger. A clean way to handle this is a short-lived partial auth token or a server-side session flag that says "password passed, waiting for TOTP." This prevents anyone from skipping the second step by hitting your token endpoint directly.

⚠️ If the TOTP code is wrong, don't reveal whether the password was correct or not in your error message. A generic "Invalid credentials" keeps things safer.

Edge Cases and Things That'll Bite You

Getting the happy path working is the easy part. Here's what trips people up in production.

1. Clock Drift

TOTP codes are time-based, which means if your server's clock and the user's phone clock are even slightly out of sync, valid codes will get rejected.

otplib handles this with a tolerance window. By default it accepts the current code plus one code on either side, giving you a 90 second window. You can configure this via authenticator.options = { window: 1 }. Don't set it too high though. The wider the window, the longer a stolen code stays valid.

2. Encrypt Your Secrets

The TOTP secret stored in your database is the keys to the kingdom. If your database leaks and secrets are in plain text, attackers can generate valid codes for every user indefinitely.

Always encrypt the secret before storing it. AES-256-GCM via Node's built-in crypto module is a solid choice. Decrypt it only at the moment of verification, never log it, never expose it in API responses.

3. Replay Attacks

A valid TOTP code stays valid for 30 seconds. If someone intercepts it and uses it within that window, they're in. The fix is to mark each code as used the moment it's verified and reject any reuse within the same window. A simple cache entry with a 30 second TTL does the job.

4. Don't Skip Recovery Codes

What happens when a user loses their phone? Without a fallback, they're permanently locked out. Recovery codes are the safety net and we'll cover them properly in the next section.

💡 None of these are optional in a production app. Clock drift and encryption especially. They're quick to implement and the cost of skipping them is high.

Backup and Recovery Codes

Every 2FA implementation needs an answer to "what if I lose my phone?" Without one, your support inbox will fill up fast.

The idea is simple. When a user enables 2FA, generate a set of one-time recovery codes (typically 8-10 codes). The user saves them somewhere safe. If they ever lose access to their authenticator app, they can use one of these codes to get in instead of the TOTP code. Each code works exactly once and is gone after use.

Here's a clean way to generate them in TypeScript:

import crypto from "crypto";

export const generateRecoveryCodes = (): string[] => {
  return Array.from({ length: 10 }, () =>
    crypto.randomBytes(5).toString("hex").toUpperCase() // e.g. "A1B2C3D4E5"
  );
};

Before saving them to the database, hash each code using bcrypt or Node's crypto module, just like you'd hash a password. Store only the hashes, never the raw codes. When the user submits a recovery code at login, hash the input and compare it against your stored hashes.

Once a code is used, delete it from the database immediately. It's a one-time key, treat it that way.

⚠️ Show the codes only once — right after the user completes 2FA setup. Make it very clear that these should be saved somewhere safe. After that screen, they're gone even from your end.

What if the user loses their phone and their recovery codes both?

It happens. Here are two approaches you can take depending on your app's security requirements.

Option 1: Recovery codes as the only self-serve escape hatch

This is the stricter approach. Recovery codes are the only way in without a phone. Once all codes are used up or the user is fully locked out, they go through a manual account recovery process with identity verification on your end. No self-serve reset. This makes 2FA truly unbypassable with just a password.

Option 2: Email-based re-enrollment link

The friendlier approach. Add a "Lost access to your authenticator?" link on the 2FA prompt. This sends a secure, time-limited link to the user's verified email address. Clicking it clears the existing TOTP secret and takes them straight into the 2FA setup flow to re-enroll with their new device.

This works safely because the email becomes the second factor in the recovery scenario. An attacker with only the password still can't do anything without inbox access. Just make sure to rate limit these recovery emails and flag repeated requests on the same account as suspicious activity.

💡 Most consumer apps go with Option 2 for the better user experience. If you're building something that handles sensitive data, Option 1 or a combination of both gives you stronger guarantees.

Wrapping Up

Here's what you've built. Your server generates a secret, shares it via QR code, the user's authenticator app takes it from there, and every login now requires a time-based code that only the user's device can produce. Clock drift is handled, secrets are encrypted, replay attacks are blocked, and recovery codes ensure nobody gets permanently locked out.

That's a production-grade TOTP setup.

What we haven't covered: WebAuthn and hardware security keys like YubiKey take this even further by eliminating shared secrets entirely. If you're building something that needs the highest level of security, those are worth exploring next.

But for the vast majority of apps, what you've built here is more than enough. 2FA isn't a feature only big companies ship. It's a few hours of work and it meaningfully raises the bar for anyone trying to get into your users' accounts.

Now go ship it.

CSS Is Smarter Than You Think. Stop Babysitting It with JS

Divyam Gupta — Thu, 05 Feb 2026 18:41:35 +0000

You know those tiny data- things in HTML that everyone ignores? They're actually way more powerful than you think. Keep reading to see what they can really do.

Disclaimer: This article consists of pieces and excerpts from an educational conversation with Claude Haiku 4.5

CSS has evolved. You now have :has() selectors that react to your HTML, if() functions that make decisions, and data attributes that bridge everything together. Instead of JavaScript managing styles, your state lives in HTML and CSS reacts to it.

THE OLD WAY: JavaScript Managing Everything

For years, this is how we've done it. You have some state in your app—maybe a form field that's valid or invalid, a button that's loading, a card that's active or inactive. JavaScript holds that state, and whenever it changes, JavaScript updates the DOM by adding or removing classes, or changing inline styles. The browser then reads those changes and updates how things look. It works, but there's a lot of back-and-forth happening between your JavaScript and the browser's rendering engine.

// Button loading state
button.addEventListener('click', () => {
  button.classList.add('loading');
  button.disabled = true;
  // Browser reflows and repaints
});

// Form validation
input.addEventListener('change', (e) => {
  if (e.target.value === '') {
    input.classList.add('error');
  } else {
    input.classList.remove('error');
  }
  // Browser reflows and repaints
});

// Toggle dark mode
toggleBtn.addEventListener('click', () => {
  document.body.classList.toggle('dark-mode');
  // Browser reflows and repaints everything
});

// Show/hide a modal
openBtn.addEventListener('click', () => {
  modal.style.display = 'block';
  modal.classList.add('visible');
  // Browser reflows and repaints
});

Why Should You Care?

Here's the thing: every time your JavaScript toggles a class or changes a style, your browser has to do work. It recalculates which styles apply, figures out new positions and sizes (reflow), and redraws pixels (repaint). This happens thousands of times per second in interactive apps. On a fast laptop, you might not notice. But on a phone? Your app feels sluggish.

The old approach triggers this expensive cycle repeatedly. The new approach? Your browser's CSS engine handles styling natively, which means your JavaScript thread stays free to do actual work. Less browser overhead, less lag, faster interactions.

Behavior	JavaScript Managing Styles	CSS Handling Natively
Reflow (recalculate layout)	Triggers on every class change	Only when necessary
Repaint (redraw pixels)	Follows each reflow	Batched with CSS engine
JavaScript thread	Blocked by DOM manipulation	Free for other logic
Per interaction cost	8-15ms (class toggling overhead)	2-4ms (attribute update only)
Mobile performance	Drops to 25-30fps	Stays at 60fps
10 rapid state changes	10 reflow cycles triggered	1 reflow cycle batched

When you toggle classes, you're asking JavaScript to talk to the DOM, which talks to the rendering engine, which reflows and repaints. When you update a data attribute, the browser's CSS engine takes over—it's optimized for this exact job.

THE NEW WAY: Let Data & CSS Do The Work

Here's where it changes. Instead of JavaScript juggling classes, you set a data attribute on your HTML element. That's it. CSS already knows what to do with it—it watches that attribute and applies the right styles automatically. Your JavaScript becomes simpler, your CSS becomes smarter, and your browser does way less work.

Example-1: Form Field Validation

Let's say you have a signup form. Users enter their email, and you need to show them if it's valid or invalid. The old way? JavaScript checks the input, adds an error class, changes the border color, shows an error message. All managed by JavaScript. The new way is simpler: you just set a data attribute, and CSS does everything else.

export default function EmailInput() {
  const [isInvalid, setIsInvalid] = useState(false);

  const handleBlur = (e) => {
    const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(e.target.value);
    setIsInvalid(!isValid);
  };

  return (
    <>
      <input
        className="input data-[invalid=true]:border-red-500 data-[invalid=false]:border-green-500"
        data-invalid={isInvalid}
        onBlur={handleBlur}
      />
      <span className="error-msg data-[invalid=false]:hidden">
        Please enter a valid email
      </span>
    </>
  );
}

Example-2: Interactive states for buttons

Buttons have multiple states—they can be disabled, pressed, or loading. Managing all of these with conditional classes gets messy fast. With data attributes, each state is explicit and CSS handles everything. Let's look at a real button that can be disabled or pressed.

export default function Button() {
  const [isPressed, setIsPressed] = useState(false);
  const [isDisabled, setIsDisabled] = useState(false);

  return (
    <button
      className="btn data-[pressed=true]:bg-blue-700 data-[pressed=false]:bg-blue-500 data-[disabled=true]:opacity-50 data-[disabled=true]:cursor-not-allowed"
      data-pressed={isPressed}
      data-disabled={isDisabled}
      disabled={isDisabled}
      onMouseDown={() => setIsPressed(true)}
      onMouseUp={() => setIsPressed(false)}
      onClick={() => setIsDisabled(!isDisabled)}
    >
      {isDisabled ? "Disabled" : "Click me"}
    </button>
  );
}

Two separate data attributes, two separate concerns. JavaScript only updates state. CSS handles all the visual feedback. No class juggling, no style conflicts.

Example-3: Conditional Styling with :has()

So far we've seen data attributes controlling a single element's styles. But what if you want a parent element to change based on what's inside it? That's where :has() comes in. It lets CSS check if a child with a specific data attribute exists, and then style the parent accordingly. For example, imagine a card that should remove bottom padding only when it has a footer slot inside it.

export default function Card({ hasFooter }) {
  return (
    <div className="card has-data-[slot=card-footer]:pb-0">
      <div className="card-header">Header Content</div>
      <div className="card-body">Body Content</div>
      {hasFooter && <div data-slot="card-footer" className="card-footer">Footer Content</div>}
    </div>
  );
}

The parent card checks if a child with data-slot="card-footer" exists—if it does, bottom padding is removed. You can also hide elements conditionally: use has-data-[slot=card-footer]:block to show content only when that slot exists. CSS reacts to what's inside without any JavaScript logic.

Example-4: Conditional Logic with CSS if()

Up until now, we've been using data attributes with Tailwind's conditional syntax. But CSS just got a new superpower: the if() function. It lets you write actual conditional logic directly in CSS. Instead of relying on pre-built Tailwind classes, you can now evaluate conditions and apply styles on the fly. For example, imagine a status badge that changes color, text, and icon based on an order status—all decided by a single if() statement in CSS.

.badge {
  --status: attr(data-status type(<custom-ident>));

  color: if(
    style(--status: shipped): #10b981;
    style(--status: pending): #f59e0b;
    else: #ef4444
  );

  background-color: if(
    style(--status: shipped): #d1fae5;
    style(--status: pending): #fef3c7;
    else: #fee2e2
  );
}

export default function OrderStatus({ status }) {
  return (
    <div 
      className="badge"
      data-status={status}
    >
      {status === 'shipped' && '✓ Shipped'}
      {status === 'pending' && '⏳ Pending'}
      {status === 'failed' && '✗ Failed'}
    </div>
  );
}

CSS if() evaluates the status value and applies colors conditionally—no JavaScript switch statements or ternary operators needed. The browser's CSS engine handles all the logic.

What's Next?

These examples are just the start. Once you think in data attributes and CSS conditionals, you'll spot opportunities everywhere—product filters, cart states, navigation menus, themes, wizards, notifications. The pattern stays the same: store state in HTML, let CSS react, keep JavaScript simple.

Pick one interactive component and try moving its styling from JavaScript to CSS. You'll feel the difference.

Simplest markdown component for your AI apps

Divyam Gupta — Wed, 01 Jan 2025 17:07:42 +0000