nodewarden/README_EN.md

NodeWarden

An alternative implementation of the Bitwarden server API running on Cloudflare Workers, designed for personal use.

English | 中文

---

⚠️ Important Notice

Disclaimer
This project is for educational purposes only. We are not responsible for any data loss. Regular backups are strongly recommended.
This project is not associated with Bitwarden. Do not report issues to Bitwarden's official support channels.

---

Features

• ✅ Full password, note, card, and identity management
• ✅ Folders and favorites
• ✅ File attachments (R2 storage, 100MB limit)
• ✅ Import/Export functionality
• ✅ Website icons
• ✅ Login rate limiting (lockout after 5 failed attempts for 15 minutes)
• ✅ API rate limiting (60 requests/minute)
• ✅ End-to-end encryption (server cannot access plaintext)
• ✅ Compatible with all official Bitwarden clients

---

Quick Start

One-Click Deploy

Click the button below to deploy to Cloudflare Workers:

Deployment Steps:

1. Sign in with GitHub and authorize
2. Log in to your Cloudflare account
3. Important: Set JWT_SECRET to a strong random string (use openssl rand -hex 32)
4. KV storage and R2 bucket will be auto-provisioned
5. Click Deploy and wait for completion

⚠️ Reminder: Always use a strong random JWT_SECRET. Never use example values or simple strings!

Client Setup

After deployment, open any Bitwarden client:

1. Click Settings (⚙️)
2. Select "Self-hosted environment"
3. Enter Server URL: https://your-project.workers.dev
4. Save and return to login page

First-time registration: Visit your Workers URL directly to register an account.

---

Manual Deployment

# Clone
git clone https://github.com/shuaiplus/nodewarden.git
cd nodewarden

# Install
npm install

# Login to Cloudflare
npx wrangler login

# Create KV storage
npx wrangler kv namespace create VAULT
# Copy the id to wrangler.toml [[kv_namespaces]]

# Create R2 bucket (for file attachments)
npx wrangler r2 bucket create nodewarden-attachments

# Set JWT secret (use a strong random string)
npx wrangler secret put JWT_SECRET
# Recommended: openssl rand -hex 32

# Deploy
npm run deploy

---

NodeWarden vs Vaultwarden

NodeWarden focuses on personal users with core features, keeping the codebase minimal. Here's a comparison with Vaultwarden:

Feature	NodeWarden	Vaultwarden	Notes
Passwords/Notes/Cards/Identity	✅	✅	Full support
Folders & Favorites	✅	✅	Full support
File Attachments	✅	✅	R2 storage, 100MB limit
Import/Export	✅	✅	Full support
Website Icons	✅	✅	Proxy fetch
Login Rate Limiting	✅	✅	Brute-force protection
Single User Mode	✅	✅	Personal use
Bitwarden Send	❌	✅	Secure sharing
Two-Factor Auth (2FA)	❌	✅	TOTP/WebAuthn etc
Emergency Access	❌	✅	Emergency contacts
Organizations/Teams	❌	✅	Multi-user collaboration
Real-time Sync (WebSocket)	❌	✅	Instant multi-device push
Email Notifications	❌	✅	Requires SMTP
Change Master Password	❌	✅	Re-encrypt vault
Admin Panel	❌	✅	Backend management

💡 Recommendation
If you only need personal password management, NodeWarden is sufficient and easier to deploy.
For team features or advanced capabilities, consider Vaultwarden.

---

Update Guide

If you deployed via the one-click button, the code is forked to your GitHub account. To get the latest updates:

Method 1: Manual Sync (Recommended)

# In your forked repository
git remote add upstream https://github.com/shuaiplus/nodewarden.git
git fetch upstream
git merge upstream/main
git push origin main

Method 2: GitHub Actions Auto-Sync

The project includes built-in auto-sync configuration. In your forked repository:

1. Go to the Actions tab
2. If you see "Workflows aren't being run on this forked repository", click I understand my workflows, go ahead and enable them
3. Auto-sync will run daily at 2:00 AM UTC
4. You can also manually trigger by clicking Sync Fork with Upstream → Run workflow

⚠️ Note: If you've modified the code, auto-sync may cause merge conflicts that require manual resolution.

---

Limitations

• Single user only (personal use)
• No two-factor authentication
• No organization/team support
• Cannot change master password
• File attachment size limit: 100MB

---

Tech Stack

• Runtime: Cloudflare Workers
• Data Storage: Cloudflare KV
• File Storage: Cloudflare R2
• Language: TypeScript
• Encryption: Client-side AES-256-CBC, JWT with HS256

---

Security Recommendations

1. Strong JWT_SECRET: Generate with openssl rand -hex 32
2. Regular Backups: Export your vault and store securely
3. HTTPS Access: Cloudflare Workers provides HTTPS by default
4. Access Control: Use Cloudflare WAF rules or IP whitelist

---

FAQ

Q: How to backup data?
A: In the client, select "Export Vault" and save the JSON file.

Q: Forgot master password?
A: Cannot be recovered due to end-to-end encryption. Keep your master password safe.

Q: Can multiple people use it?
A: Not recommended. This project is designed for single user. Use Vaultwarden for multi-user scenarios.

---

License

MIT License

---

Acknowledgments

• Bitwarden - Original design and clients
• Vaultwarden - Server implementation reference
• Cloudflare Workers - Serverless platform