Skip to content
BranchesTags

Repository files navigation

ruby_template

TOTP Authenticator PWA

A futuristic, Apple-styled Progressive Web App for TOTP (Time-based One-Time Password) authentication, compatible with Google Authenticator and the Ruby totp.rb script.

Bare minimum PWA code ...

The Pages branch, 'docs' directory is where GitHub Pages content is located

The 'app' directory contains the same minimal code.

GitHub Pages hosts the PWA at TOTP PWA

Features

✅ All Phases Complete!

Phase 1-3: Core Engine, Storage & UI ✅

  • Core TOTP Engine: RFC 6238 compliant implementation
    • Custom Base32 encoding/decoding (matching Ruby implementation)
    • HOTP (HMAC-based OTP) algorithm
    • TOTP (Time-based OTP) with 30-second intervals
    • Real-time countdown timers with progress visualization
  • Storage: IndexedDB for accounts, LocalStorage for settings
  • UI: Futuristic Apple-style glass morphism design
    • Dark/Light/Auto theme modes
    • Bootstrap 5.3 components
    • Smooth animations and transitions
    • Responsive mobile-first layout
  • PWA: Offline-capable with service worker
    • Installable on iOS and Android
    • Works without internet connection
    • App manifest with icons

Phase 4: Account Management ✅

  • Add, edit, delete accounts
  • Show/hide secrets
  • Account menu with all operations
  • Full CRUD functionality

Phase 5: QR Code Features ✅

  • Camera QR code scanning
  • QR code generation for accounts
  • File upload for QR images
  • otpauth:// URI parsing

Phase 6: Advanced Import/Export ✅

  • JSON export/import (full details)
  • Base64 compact format
  • otpauth:// URI export
  • File upload and download
  • Clipboard operations
  • Batch export all accounts

Phase 7: Customization System ✅

  • Theme presets (Classic Apple, Dark, High Contrast)
  • Color customization (primary, accent)
  • Size controls (fonts, spacing, radius)
  • Effect controls (glass opacity, blur, shadow)
  • Animation speed and toggle
  • Reset to defaults

Phase 8: PWA Polish & Optimization ✅

  • Search/filter accounts
  • Keyboard shortcuts (/, N, E, S, T, ?)
  • Install prompt handling
  • Update notifications
  • Haptic feedback
  • Auto-update checks

Phase 9: Testing & Documentation ✅

  • RFC 4226 test vectors validation
  • Ruby script compatibility testing
  • Comprehensive documentation
  • Git integration

Installation

Option 1: Web Server

cd ~/src/morganism/totp/app
python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

Option 2: File Server (VS Code Live Server)

  1. Open the app/ folder in VS Code
  2. Right-click index.html → "Open with Live Server"

Option 3: Deploy

Deploy to any static hosting (GitHub Pages, Netlify, Vercel, etc.)

Usage

Add an Account

  1. Click "Add Account" button
  2. Choose "Manual" tab
  3. Enter:
    • Account name (e.g., user@example.com)
    • Issuer (e.g., GitHub)
    • Secret key (Base32 format, e.g., JBSWY3DPEHPK3PXP)
    • Digits (6 or 8)
    • Interval (30 or 60 seconds)
  4. Click "Add Account"

Copy TOTP Code

  • Click on any displayed code to copy it to clipboard
  • Codes auto-refresh every 30 seconds
  • Progress bar shows remaining time

Change Theme

  • Click the moon/sun icon in the navbar
  • Cycles through: Light → Dark → Auto (system preference)
  • Or press T keyboard shortcut

Keyboard Shortcuts

  • / - Focus search bar
  • N - Add new account
  • E - Export all accounts
  • S - Open settings
  • T - Toggle theme
  • ? - Show keyboard shortcuts help
  • Esc - Close modals or blur inputs
  • Space - Copy code (when account is focused)

Testing Against Ruby Implementation

To verify the JavaScript implementation matches the Ruby script:

# Terminal 1: Generate code with Ruby
cd ~/src/morganism/totp
ruby totp.rb --current --secret JBSWY3DPEHPK3PXP

# Terminal 2: Start web server
cd ~/src/morganism/totp/app
python3 -m http.server 8000

# Browser: Add account with secret JBSWY3DPEHPK3PXP
# Compare codes - they should match!

Test with RFC 4226 Vectors

The Ruby script includes test vectors. To verify:

cd ~/src/morganism/totp
ruby totp_test.rb

Expected output:

PASS  Base32 round-trip
PASS  HOTP counter=0 => 755224
PASS  HOTP counter=1 => 287082
PASS  HOTP counter=2 => 359152
PASS  HOTP counter=3 => 969429
PASS  HOTP counter=4 => 338314
...

Architecture

Technology Stack

  • Frontend: Vanilla JavaScript (ES6+), Bootstrap 5.3
  • Storage: IndexedDB API, LocalStorage API
  • Crypto: Web Crypto API (HMAC-SHA1)
  • PWA: Service Worker API, Web App Manifest
  • Styling: CSS Custom Properties, Glass Morphism

File Structure

app/
├── index.html              # Single-page app (~50KB)
├── manifest.json           # PWA manifest
├── service-worker.js       # Offline caching
├── icons/
│   ├── icon-192.png       # App icons
│   ├── icon-512.png
│   └── icon-maskable-512.png
└── lib/
    ├── qrcode.min.js      # QR generation (Phase 5)
    └── html5-qrcode.min.js # QR scanning (Phase 5)

Core Components

TOTP Engine (TOTP object)

  • encodeBase32(bytes) - Base32 encoding
  • decodeBase32(str) - Base32 decoding
  • hotp(secret, counter, digits) - HMAC-based OTP
  • totp(secret, time, digits, interval) - Time-based OTP
  • validate(secret, code, ...) - Code validation
  • parseOtpauthURI(uri) - Parse otpauth:// URIs
  • generateOtpauthURI(account) - Generate URIs
  • generateSecret(length) - Random secret generation

Storage Manager (StorageManager object)

  • init() - Initialize IndexedDB
  • getAccounts() - Retrieve all accounts
  • addAccount(account) - Add new account
  • updateAccount(id, updates) - Update account
  • deleteAccount(id) - Delete account
  • exportJSON() - Export to JSON
  • importJSON(data) - Import from JSON
  • exportBase64() - Export to Base64
  • importBase64(base64) - Import from Base64

Settings Manager (SettingsManager object)

  • get(key, default) - Get setting
  • set(key, value) - Set setting
  • getAll() - Get all settings
  • reset() - Reset to defaults
  • applyTheme(theme) - Apply theme

UI Manager (UIManager object)

  • init() - Initialize application
  • renderAccounts() - Render account grid
  • updateCode(accountId) - Update TOTP code
  • startTimers() - Start countdown timers
  • updateAllTimers() - Update all timers
  • copyCode(accountId) - Copy code to clipboard
  • showToast(message, type) - Show notification
  • saveAccount() - Save new account

Design Language

Apple-Style Aesthetics

  • Glass Morphism: Frosted glass effect with backdrop-filter: blur(20px)
  • SF Pro Font: Apple system font stack
  • iOS Colors: Primary #007aff (iOS blue), Accent #5856d6 (iOS purple)
  • Smooth Animations: Cubic Bezier easing (0.4, 0, 0.2, 1)
  • Large Touch Targets: Minimum 44x44px per Apple HIG
  • Rounded Corners: 16px cards, 12px buttons
  • Generous Spacing: White space for clarity

CSS Custom Properties

All design tokens are CSS variables for easy customization:

--totp-primary: #007aff;
--totp-accent: #5856d6;
--totp-font-code: 48px;
--totp-border-radius: 16px;
--totp-glass-opacity: 0.85;
--totp-blur: 20px;

Browser Support

  • Chrome 90+ (Desktop & Android)
  • Firefox 88+ (Desktop)
  • Safari 14+ (macOS & iOS)
  • Edge 90+ (Desktop)

Required APIs

  • IndexedDB
  • LocalStorage
  • Service Workers
  • Web Crypto API (HMAC-SHA1)
  • Clipboard API
  • CSS backdrop-filter (for glass effect)

Security

Data Storage

  • IndexedDB: Origin-isolated, not accessible by other sites
  • No Encryption at Rest: Secrets stored in plain text
  • Recommendation: Protect device with PIN/password/biometric lock

Best Practices

  • Never log secrets to console (production mode)
  • Use HTTPS in production (required for Service Workers)
  • Regular backups via export functionality
  • Validate Base32 secrets before storage

Performance

  • First Contentful Paint: < 1.5s
  • Time to Interactive: < 2.5s
  • Lighthouse PWA Score: Target 100
  • Offline Support: 100% functional offline
  • Bundle Size: ~50KB HTML + ~60KB Bootstrap + ~19KB QR libs

Development

Local Development

# Start development server
cd ~/src/morganism/totp/app
python3 -m http.server 8000

# Or use VS Code Live Server extension

Testing Checklist

  • TOTP codes match Ruby script output
  • Codes refresh every 30 seconds
  • Countdown timer accurate
  • Copy to clipboard works
  • Works offline (disconnect WiFi)
  • Theme switching works
  • Responsive on mobile
  • Service worker caches assets
  • PWA installable

Known Limitations (Phase 1)

  • No QR code scanning/generation yet (Phase 5)
  • No import/export yet (Phase 6)
  • No account editing/deletion yet (Phase 4)
  • No search/filter yet (Phase 8)
  • No customization UI yet (Phase 7)

Roadmap

Phase 2-3: Storage & UI (✅ Complete)

Integrated in Phase 1.

Phase 4: Account Management

  • Edit account details
  • Delete with confirmation
  • Show/hide secret
  • Bulk operations

Phase 5: QR Code Features

  • Camera scanning
  • QR code generation
  • otpauth:// URI parsing
  • File upload support

Phase 6: Advanced Import/Export

  • JSON export/import
  • Base64 compact format
  • Google Authenticator compatibility
  • Drag-and-drop file upload

Phase 7: Customization System

  • Settings modal
  • Color pickers
  • Size controls
  • Effect controls (blur, shadow)
  • Theme presets
  • Animation toggles

Phase 8: PWA Polish

  • Search/filter accounts
  • Drag-to-reorder
  • Keyboard shortcuts (Space=copy, N=new, /=search)
  • Haptic feedback
  • Update notifications

Phase 9: Testing & Documentation

  • Cross-browser testing
  • Performance optimization
  • Security audit
  • Comprehensive documentation

Credits

  • TOTP Algorithm: RFC 6238 / RFC 4226
  • Design Inspiration: Apple iOS Human Interface Guidelines
  • Compatible with: Google Authenticator, Authy, Microsoft Authenticator
  • Ruby Reference: /Users/morgan/src/morganism/totp/totp.rb

License

Part of the TOTP project at /Users/morgan/src/morganism/totp/

Status: All Phases Complete ✅ - Production Ready Last Updated: 2026-03-10 Version: 1.0.0 Test: Open test.html to verify TOTP algorithm compatibility

About

A pure-Ruby RFC 6238 TOTP (Time-based One-Time Password) implementation compatible with Google Authenticator (issue: https://git.morganism.dev/totp/issues/18), usable both as a library module and a standalone CLI tool.

totp.morganism.dev/

Topics

qrtotp

Resources

Readme

Code of conduct

Code of conduct

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages

Generated from morganism/ruby_template