GO-2FA

GO-2FA is a minimal Go web application for storing TOTP secrets and generating time-based one-time passwords in real time. Secrets are encrypted on disk using a password provided at login. This project is designed for personal use as a lightweight self-hosted alternative to mobile authenticator apps.

Features

• Password-based encrypted storage using AES-GCM
• Single-user login session
• Real-time TOTP code generation without page reload
• Automatic 30-second refresh aligned with TOTP intervals
• Countdown timer for current code validity
• Minimal web interface

Requirements

• Go 1.25.8 or newer

Build and Run

Build the application:

go build

Run the binary:

./2fa

The server will start on:

http://localhost:4587

Alternatively, you can download a prebuilt binary and run it directly.

Usage

1. Open the web interface in your browser
2. Enter a master password to unlock or create your vault
3. Add entries by providing a label and a TOTP secret key
4. Codes will be generated automatically and updated in real time
5. Click on a code to copy it to your clipboard

Storage

All secrets are stored in a local file named store.json. The contents of this file are encrypted using a key derived from your password. If the password is lost, the stored data cannot be recovered.

Security Notes

• This application uses AES-GCM for encryption with a key derived from the provided password
• There is no password recovery mechanism
• Session handling is minimal and intended for single-user use only
• It should be deployed behind a reverse proxy providing HTTPS and additional authentication, it is not intended to be exposed directly to the internet

Systemd Service

To run Secure TOTP Vault as a systemd service without creating a separate user:

1. Place your binary somewhere accessible, for example /opt/2fa
2. Create the service file /etc/systemd/system/2fa.service:

[Unit]
Description=GO-2FA
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/2fa
ExecStart=/opt/2fa/2fa
Restart=on-failure

[Install]
WantedBy=multi-user.target

3. Reload systemd and start the service:

sudo systemctl daemon-reload
sudo systemctl enable totp-vault
sudo systemctl start totp-vault
sudo systemctl status totp-vault

License

This project is licensed under the GNU General Public License v3.0 (GPLv3).