Authlama

This is a concept project. It has worked well in personal use, but if it does not work for you, there is no liability -- it is a concept.

A serverless, zero-database encrypted TOTP code manager. Save your 2FA codes as a single encrypted file. Nothing is stored anywhere.

authlama.pages.dev

---

Why does Authlama exist?

2FA codes are sensitive. Saving them in the cloud means trusting a third party. Saving them on your device means losing them if the device breaks.

Authlama gives you one encrypted file -- secret.txt. That file is your vault. It contains all your codes encrypted with AES-256-GCM. No server. No database. No account. You manage the file yourself.

The encryption is real -- AES-256-GCM via the browser's native Web Crypto API, with PBKDF2 key derivation (600,000 SHA-256 iterations). The password never leaves your browser. The encrypted blob never touches a server.

---

Features

• TOTP code generation -- scan QR codes or enter secrets manually (Google Authenticator compatible)
• Session mode -- codes work immediately but disappear when you close the tab
• AES-256-GCM encryption -- codes are encrypted into a single self-contained string
• Password protection -- unlock with your password and the encrypted key file
• Download as secret.txt -- save the encrypted key as a file anywhere
• File upload to unlock -- upload your secret.txt and enter your password to decrypt
• Re-encrypt on edit -- every time you save changes, you get a new key (old one stops working)
• Dark / Light mode -- toggle with the moon/sun icon, persisted in localStorage
• Auto-cleanup on exit -- all session data is wiped when you close the tab
• Zero accounts, zero servers, zero tracking -- everything happens in your browser

---

How it works

Authlama is a 100% static website -- React, TypeScript, Tailwind CSS. No backend. No API. No database. No server-side code of any kind.

Encryption flow

1. You add TOTP codes in the browser (QR scan or manual entry)
2. Click Save Key, enter a key name and password
3. The browser uses PBKDF2 (600,000 iterations) to derive an AES-256-GCM key from your password
4. Your codes and key name are encrypted into a single base64 string
5. This string is packed as [version][salt][IV][ciphertext] -- self-contained, no external data needed
6. You download this string as secret.txt or copy it

Decryption flow

1. Click Load Key, paste the encrypted string or upload secret.txt
2. Enter your password
3. PBKDF2 derives the same AES key from password and embedded salt
4. AES-GCM decrypts and authenticates -- wrong password fails immediately
5. Your codes appear with live countdown timers

Why this is secure

• The encrypted blob contains everything needed to decrypt (salt, IV, ciphertext) except the password
• Without the password, the blob is cryptographically useless
• AES-GCM provides authenticated encryption -- tampering is detected
• The password is never stored or transmitted -- only the derived key exists briefly in memory

---

File structure

authlama/
├── index.html              # Entry point
├── src/
│   ├── App.tsx             # Main application
│   ├── main.tsx            # React root + exit cleanup
│   ├── index.css           # Tailwind + light/dark theme
│   ├── components/
│   │   ├── ui/             # Button, Input, Modal
│   │   ├── totp/           # TOTP code display, QR scanner, add form
│   │   └── vault/          # Save/Load modals, secret key display
│   ├── hooks/              # useSessionCodes, useVaults, useTheme
│   └── lib/
│       ├── crypto/         # AES-256-GCM, PBKDF2
│       ├── totp/           # TOTP/HOTP algorithm, Base32, otpauth URI parser
│       ├── storage/        # Session storage + vault encryption
│       └── types/          # TypeScript type definitions
├── package.json
├── vite.config.ts
├── tailwind.config.js
└── LICENSE                 # MIT

---

Tech stack

Layer	Technology
Framework	React 18 + TypeScript (strict mode)
Build	Vite 5
Styling	Tailwind CSS 3 (class-based dark mode)
Cryptography	Web Crypto API (AES-256-GCM, PBKDF2, HMAC)
QR scanning	html5-qrcode
Dependencies	Zero external crypto libraries -- all native browser APIs

---

Self-hosting / Deployment

Authlama is entirely static. Host it anywhere with zero configuration.

Cloudflare Pages

1. Push the repo to GitHub
2. In Cloudflare Pages dashboard, select Vite (framework preset)
3. Build command: npm run build (default)
4. Build output: dist (default)
5. Cloudflare auto-runs npm install before every build

Vercel

1. Import the GitHub repo in Vercel
2. Framework preset auto-detects Vite
3. Everything defaults to npm run build then dist
4. Vercel auto-runs npm install before every build

Netlify

1. Connect the GitHub repo in Netlify
2. Build command: npm run build
3. Publish directory: dist
4. Netlify auto-runs npm install before every build

Any static host

Build locally and upload the dist/ folder:

npm install
npm run build
# upload dist/ to any static server

Run locally

Prerequisites: Node.js 18+ and npm (download)

git clone https://github.com/sahinguclu/Authlama.git
cd Authlama
npm install
npm run dev

Open http://localhost:3000/ in your browser. The app must be served over localhost or HTTPS for the Web Crypto API to work.

To create a production build:

npm run build     # outputs to dist/
npm run preview   # preview the production build

---

Security

• AES-256-GCM via browser Web Crypto API
• PBKDF2 with SHA-256, 600,000 iterations for key derivation
• The password never leaves your browser
• The encrypted blob contains salt, IV, and ciphertext -- no external data needed
• All session data is wiped on tab close -- only your theme preference persists
• The app works fully offline after first load

---

License

MIT License -- see LICENSE

Free to use, copy, modify, distribute, sublicense, and sell. Attribution appreciated but not required.

---

Credits

Made by Sahin Guclu

Source Code