Overview • Downloads • Features • Installation • Usage • Architecture • Development • Security • Troubleshooting • Roadmap • Contributing • License • Acknowledgements
WickAuth is a professional-grade desktop authenticator application that provides secure two-factor authentication (2FA) using Time-Based One-Time Passwords (TOTP). Built with modern technologies like Electron, Next.js, and NextUI, it offers a sleek, intuitive interface while maintaining robust security standards.
Unlike browser-based authenticators, WickAuth operates as a standalone desktop application, offering enhanced security and offline accessibility. It's perfect for professionals, developers, and security-conscious users who require reliable authentication across multiple services.
- 📥 WickAuth-Portable-1.0.0.exe - Portable Windows Executable (No installation required)
- 📦 Source code (zip) - Source code archive (zip)
- 📦 Source code (tar.gz) - Source code archive (tar.gz)
View all releases: https://github.com/wickstudio/wickauth/releases
- TOTP Authentication: RFC 6238 compliant Time-Based One-Time Password implementation
- Secure Local Storage: Encrypted database for storing authentication tokens
- Offline Operation: No internet connection required after setup
- Custom Token Configuration: Control over algorithm (SHA-1, SHA-256, SHA-512), digits (6 or 8), and period (30s or 60s)
- Token Management: Easy addition, editing, and removal of authentication tokens
- Clipboard Integration: One-click copying of generated codes
- Countdown Timer: Visual indication of code validity period
- Modern UI: Clean, responsive interface built with NextUI and Tailwind CSS
- Custom Title Bar: Frameless window with custom controls for a native feel
- Dark Mode Support: Full dark mode implementation for comfortable usage
- Responsive Layout: Adapts to different window sizes
- Portable Mode: Use without installation as a portable application
- Auto-Starting Tokens: Automatic code generation upon launch
- Visual Feedback: Animations and transitions for a polished experience
- Electron Framework: Cross-platform compatibility (primarily Windows-focused)
- Next.js Frontend: React-based UI with modern development features
- TypeScript: Type-safe code for improved reliability
- IPC Communication: Secure communication between renderer and main processes
- Protocol Handling: Custom protocol handling for proper resource resolution
- Multiple Build Options: Both installed and portable versions available
- Node.js: Version 18.0.0 or higher
- npm or yarn: For package management
- Windows: Windows 10 or higher recommended
- Visit the Releases page
- Download the latest
WickAuth-Portable-x.x.x.exefile - Run the executable to start using WickAuth immediately
-
Clone the repository
git clone https://github.com/wickstudio/wickauth.git cd wickauth -
Install dependencies
npm install
-
Build the application
# For regular build (development) npm run build # For portable executable (production) npm run make
-
Launch the application
# For development version npm start # For production build ./dist/win-unpacked/WickAuth.exe
For convenience, several batch files are provided:
build.bat: Creates a regular buildbuild.ps1: Creates a portable EXE (requires PowerShell)start.bat: Launches the regular buildrun.bat: Smart launcher that automatically selects available builddev.bat: Starts the application in development mode
After launching WickAuth, you'll be presented with the main interface. If this is your first time using the application, the token list will be empty.
- Click the "+ Add Token" button in the main interface
- Enter the required information:
- Name: A descriptive name for the token (e.g., "GitHub")
- Secret Key: The base32-encoded secret key provided by the service
- Issuer (optional): The service provider name
- Advanced options (optional):
- Algorithm: Select from SHA-1, SHA-256, or SHA-512 (default: SHA-1)
- Digits: Number of digits in the generated code (6 or 8)
- Period: How often the code refreshes (30 or 60 seconds)
- Click "Add Token" to save
- When you need to authenticate, open WickAuth
- Find the desired token in your list
- Use the current code displayed next to the token name
- The progress bar indicates the remaining validity time of the code
- Edit: Click the edit icon (pencil) next to a token to modify its details
- Delete: In the edit screen, use the "Delete" button to remove a token
- Copy: Click the code to copy it to the clipboard automatically
The custom title bar provides familiar controls:
- Minimize: Reduce the window to the taskbar
- Maximize/Restore: Toggle between maximized and regular window size
- Close: Exit the application
- Ctrl+N: Add new token
- Esc: Cancel current operation
- Ctrl+C: Copy selected token code
- Alt+F4: Close application
WickAuth follows a modern architecture pattern combining Electron and Next.js:
┌────────────────────────────────┐
│ Electron Main Process │ ← Main application process
├────────────────────────────────┤
│ IPC Bridge Layer │ ← Inter-process communication
├────────────────────────────────┤
│ Next.js (React) UI Layer │ ← User interface components
├────────────────────────────────┤
│ Core Services & Utilities │ ← TOTP generation, encryption
└────────────────────────────────┘
- Main Process (
src/core/desktop/main.ts): Controls the application lifecycle, window management, and system integration - Preload Script (
src/core/desktop/preload.js): Exposes secure APIs to the renderer process - UI Components (
src/app/,src/components/): React components for the user interface - Core Services (
src/core/): Authentication and storage functionality - Data Types (
src/shared/types.ts): TypeScript interfaces for data structures - Route Handler (
public/route-handler.js): Client-side dynamic route handling for Electron
- User interacts with React components in the renderer process
- UI components call exposed IPC methods from the preload script
- IPC messages are transmitted to the main process
- Main process performs operations (database, system tasks)
- Results are returned to the renderer via IPC
- UI updates to reflect changes
Tokens are stored in a secure local database using electron-store with the following structure:
interface Token {
id: string; // Unique identifier
name: string; // Display name
secret: string; // TOTP secret key
issuer?: string; // Optional service provider
algorithm?: 'SHA-1' | 'SHA-256' | 'SHA-512'; // Hashing algorithm
digits?: number; // Code length (6 or 8)
period?: number; // Refresh period (30 or 60 seconds)
createdAt: number; // Timestamp of creation
}-
Fork and clone the repository
git clone https://github.com/wickstudio/wickauth.git cd wickauth -
Install dependencies
npm install
-
Start the development environment
npm run dev:electron
This will:
- Launch the Next.js development server
- Start Electron pointing to the dev server
- Enable hot reloading for faster development
/src/app: Next.js pages and routes/src/components: Reusable UI components/src/core: Core application functionality/desktop: Electron-specific code/auth: Authentication logic/storage: Data persistence layer
/src/shared: Shared utilities and types/public: Static assets and client-side scripts
The application uses several build configurations:
- Development Build: Uses Next.js development server with hot reloading
- Production Build: Creates optimized static export and Electron application
- Portable Build: Packages the application as a standalone executable
- Tailwind CSS: Used for styling components
- NextUI: Component library for consistent design
- Framer Motion: Animations and transitions
- Lucide Icons: SVG icon set
- Make your code changes
- Run the development environment to test
- Build a production version to verify functionality
npm run build npm start
- Main Process: Use console.log statements (visible in terminal)
- Renderer Process: Use DevTools console (available in development mode)
- Enable Debug Mode: Set
DEBUG=trueenvironment variable for additional logging
WickAuth prioritizes security through several key measures:
- Local Storage Only: Authentication secrets never leave your device
- Encrypted Storage: Data is stored in an encrypted format
- Process Isolation: Electron's contextIsolation prevents direct access to Node.js APIs
- Limited File Access: Application has restricted access to the filesystem
- No Network Requirement: Functions fully offline after initial setup
The application implements the Time-Based One-Time Password algorithm according to RFC 6238:
- Uses HMAC-SHA-1/SHA-256/SHA-512 cryptographic algorithms
- Time-synchronized with standard 30-second windows (configurable)
- Supports 6 or 8-digit output codes
- Secrets are never exposed in the UI after initial entry
- Database is protected using machine-specific encryption
- No analytics or telemetry data is collected
- Keep your operating system and application updated
- Use strong, unique passwords for each service
- Backup your authentication tokens securely
- Do not share your secret keys or QR codes
Symptom: Double-clicking the application does nothing or briefly shows a window before closing.
Solutions:
- Run the application as an administrator
- Ensure Node.js is properly installed (for dev mode)
- Check Windows Event Viewer for application errors
- Try running from the command line to see error output
Symptom: The application starts but has missing graphics or icons.
Solutions:
- Ensure the application was built correctly
- Try rebuilding with
npm run make - Verify the
publicfolder contains the required assets
Symptom: Generated codes aren't accepted by the service.
Solutions:
- Verify your computer's time is correctly synchronized
- Check if the service requires a specific algorithm or digits setting
- Ensure the secret key was entered correctly (no spaces, case-sensitive)
Symptom: The application window is empty or shows a blank screen.
Solutions:
- Delete the application data and restart
- Try launching with the
--ignore-gpu-blacklistflag - Check your graphics drivers are up to date
If you're experiencing issues not covered here:
- Check the GitHub Issues for similar problems
- Create a new issue with detailed information about your problem
- Include your system information, error messages, and steps to reproduce
- Cloud Backup: Optional encrypted backup to cloud storage
- Import/Export: Support for importing/exporting tokens
- QR Code Scanner: Scan QR codes directly from screen
- Multiple Profiles: Support for different token collections
- Automatic Updates: In-app update system
- Advanced Search: Filter and search functionality for many tokens
- Cross-Platform Support: macOS and Linux versions
- Mobile Companion App: Synchronized mobile application
- Enhanced security features
- UI/UX improvements
- Performance optimizations
- 1.0.0: Initial release with core functionality
- 1.1.0: (Planned) QR code scanning and improved UI
- 1.2.0: (Planned) Import/Export functionality
- 2.0.0: (Planned) Cloud backup and cross-platform support
Contributions are welcome and appreciated! Here's how you can contribute:
- Bug Reports: Create detailed issues for bugs you encounter
- Feature Requests: Suggest new features or improvements
- Documentation: Help improve or translate documentation
- Code Contributions: Submit pull requests with bug fixes or features
- Testing: Test the application on different setups and report issues
- Fork the repository
- Create a feature branch
git checkout -b feature/amazing-feature
- Commit your changes
git commit -m 'Add some amazing feature' - Push to the branch
git push origin feature/amazing-feature
- Open a Pull Request
- Follow the existing code style
- Write clear, documented code
- Include appropriate tests for new functionality
- Ensure all linting passes (
npm run lint) - Keep pull requests focused on a single feature/fix
- Select an issue to work on (or create one)
- Discuss approach in the issue thread
- Implement solution in your fork
- Test thoroughly
- Submit pull request
- Address review feedback
This project is licensed under the MIT License - see the LICENSE file for details.
- Electron - Desktop application framework
- Next.js - React framework
- React - UI library
- TypeScript - Type-safe JavaScript
- NextUI - UI component library
- Tailwind CSS - Utility-first CSS framework
- Framer Motion - Animation library
- Lucide Icons - SVG icon set
- Totpify - TOTP implementation
- All contributors and supporters
- The open-source community for their invaluable resources
- You, for using or contributing to WickAuth!
