Desktop TOTP Authenticator App

Two-factor authentication is only as convenient as the device that holds the codes, and most students keep their 2FA secrets on a phone app they cannot use while working on a laptop. This project builds a desktop TOTP authenticator: a native-feel app that implements the RFC 6238 time-based one-time password algorithm from first principles — base32 secret decoding, HMAC-SHA1, dynamic truncation and the 30-second time counter — so every code on screen is computed, not faked. Secrets are encrypted at rest with AES-256 under a vault password the user sets; the app supports adding accounts by scanning a service's 2FA QR or pasting the secret manually, searching across accounts, and exporting an encrypted backup file for migration. The accompanying web demo runs the same algorithm in JavaScript with six realistic accounts, so the viva can show live code generation, the countdown ring and the add/backup flows directly. The report documents the TOTP mathematics, the vault encryption design and the threat model honestly.

1. The user enrols an account by scanning the service's 2FA QR or pasting the base32 secret; the secret is encrypted into the vault immediately.
2. Every 30 seconds the app computes the Unix time counter (floor of epoch seconds divided by 30).
3. The counter is HMAC-SHA1 hashed with the account's secret key, dynamically truncated to 31 bits, and reduced modulo 1,000,000 to a 6-digit code.
4. The UI renders the code with a countdown ring showing seconds remaining in the current window.
5. Clicking copy places the code on the clipboard; it is cleared automatically after the configured interval.
6. Backup exports the encrypted vault as one file; restore decrypts it on the new machine after the vault password is verified.

Tech stack:

• Python 3 with Tkinter / PyQt (desktop shell)
• cryptography library (AES-256-GCM, PBKDF2)
• qrcode + OpenCV (QR enrolment flow)
• RFC 6238 TOTP core (implemented from spec)
• HTML/CSS/JS (working web demo of the algorithm)

• [Real RFC 6238 TOTP] Base32 decoding, HMAC-SHA1, dynamic truncation and 30-second counters implemented and documented — the report walks through the algorithm step by step.
• [AES-256 encrypted vault] All secrets encrypted at rest under a user-set vault password; the plaintext secret never touches the disk.
• [30-second countdown ring] Per-account visual countdown with automatic code rollover, matching the behaviour of standard authenticator apps.
• [One-click copy] Copies the current 6-digit code to the clipboard, with the copy expiring from the clipboard after a configurable interval.
• [Add via QR or manual entry] Scan the service's 2FA setup QR with the desktop camera flow, or paste the base32 secret for manual enrolment.
• [Encrypted backup & restore] Export a single .vkenc backup file and restore it on a new machine with the vault password.
• [Search across accounts] Instant filtering by service or username for users with dozens of enrolled accounts.

• Complete desktop app source code (Python) with TOTP core implemented from the RFC
• Working web demo generating real codes for 6 sample accounts
• Vault encryption module with documented key-derivation parameters
• QR enrolment flow documentation
• Project report PDF (TOTP mathematics, encryption design, threat model, testing)
• PPT presentation for final review
• Viva Q&A preparation document (HMAC, time counters, AES-GCM, PBKDF2, clipboard security)

• The vault password cannot be recovered — losing it means losing all secrets, which is stated upfront in the app and the report.
• Code correctness depends on the system clock; a machine with a badly skewed clock generates codes the server rejects (the plus/minus-one-step tolerance covers small skew only).
• The app stores TOTP secrets, not FIDO2/WebAuthn keys — hardware security keys are out of scope.
• QR enrolment needs a working camera; manual secret entry is the documented fallback.
• The demo web version keeps secrets in memory only and is not a password manager replacement.