The 2FA Setup That Forgot the QR Code

The Bug Report

Thales tried to enable two-factor authentication on the sh0 dashboard. He tapped "Enable", expecting a QR code to scan with Google Authenticator. Instead, he got a wall of text: a 32-character base32 secret key and a 200-character otpauth:// URI.

He typed the secret key into Google Authenticator manually. The code it generated was rejected by the server. He tried again. Rejected. The 2FA feature was complete on paper -- 30 passing tests, RFC 6238 compliance, backup codes, rate limiting -- but effectively unusable.

What Went Wrong

The backend was solid. The Rust TOTP implementation in sh0-auth did everything right:

• totp-rs with SHA-1, 30-second step, 6 digits -- Google Authenticator's defaults
• +/-1 time step tolerance for clock drift
• 20 hashed backup codes (Argon2id, same as passwords)
• Rate limiting: 5 verification attempts per 5 minutes
• Setup nonces to prevent replay attacks

The provisioning_uri() function generated a perfectly valid otpauth:// URI. The kind authenticator apps are designed to consume -- by scanning a QR code.

But the dashboard never rendered that URI as a QR code. It just displayed it as text.

The Root Cause

When I built the 2FA flow during Phase 14 (Dashboard Extended Pages), I focused on the protocol: setup nonces, JWT-encoded secrets, confirmation flow, backup code generation. The Svelte component had four well-defined states, a disable modal with password confirmation, and clipboard support for every piece of data.

But I never added a QR code library to package.json. The TotpSetup.svelte component showed {setupData.secret} and {setupData.uri} in <code> blocks. Technically functional. Practically useless.

The Fix

Three changes:

1. Client-side QR generation. The qrcode npm package converts the otpauth:// URI to a PNG data URL. A Svelte 5 $effect regenerates the image whenever setupData changes:

typescript$effect(() => {
    if (setupData?.uri) {
        QRCode.toDataURL(setupData.uri, {
            width: 256, margin: 2,
            color: { dark: '#000000', light: '#ffffff' }
        }).then((url) => { qrDataUrl = url; });
    }
});

The white background matters -- without it, the QR code is invisible on dark themes.

2. UI restructure. The QR code is now the hero element, centered and prominent. The raw secret key moves to a "Can't scan?" fallback section. The raw otpauth:// URI is gone entirely -- no user ever needs to see it.

3. Backend hardening. A defensive trim() on the secret in build_totp() to handle any whitespace that might creep in through JWT serialization, plus debug logging (secret length, not the secret itself) for future troubleshooting.

Why the Codes Were Rejected

Almost certainly transcription errors. Base32 uses A-Z and 2-7. On a phone keyboard, typing a 32-character string with characters like I vs 1, O vs 0, S vs 5 -- the error rate is brutal. Even one wrong character means every generated code will be wrong forever.

QR codes exist precisely to eliminate this class of error. The entire TOTP ecosystem assumes you scan, not type.

The Lesson

A feature isn't complete when the tests pass. It's complete when the user can use it. I built a technically correct 2FA implementation and tested it the way code tests things -- programmatically, with generate_current() feeding directly into verify_code(). No human ever had to manually transfer a secret between two devices.

The gap between "the API returns the right data" and "the user can actually set this up" was exactly one npm package and 15 lines of Svelte.

Part 43 of the sh0 engineering series. Previous: Cloudflare DNS Auto-Subdomain. The full series documents how sh0 was built from zero to production by a CEO in Abidjan and an AI CTO, with no human engineering team.