🎉 Vaultwarden API v1.0.0 - Production-ready with IP whitelisting

First stable release - Production-ready Vaultwarden API proxy with IP whitelisting and CLI authentication

📦 Download

Docker (Recommended):

docker pull turboot/vaultwarden-api:latest

Build from source:

git clone https://github.com/thijsherman/vaultwarden-api.git
cd vaultwarden-api
git checkout v1.0.0
make build

✨ What's New

🔒 Security Enhancements

IP Whitelisting - Restrict API access by IP address or CIDR range
- Support for single IPs, multiple IPs, and CIDR notation
- Automatic validation of IP/CIDR entries
- GitHub Actions IP range support (auto-updates every 24h)
- Duplicate IP detection and removal
Trusted Proxy Configuration - Proper client IP detection behind reverse proxies
- Validates proxy IPs to prevent misconfiguration
- Supports Cloudflare, Nginx Proxy Manager, Traefik
- Extracts real client IP from X-Forwarded-For header
Input Validation - Secure validation of secret names to prevent injection attacks

🔑 Authentication Improvements

Bitwarden CLI Integration - More reliable authentication
- API key authentication (recommended) - never expires
- Automatic login and unlock on startup
- Bypasses 2FA for API access
- Fallback to session tokens for compatibility
- Exponential backoff retry logic with proper error handling

🐛 Bug Fixes

Fixed double cleanup of IP update goroutines
Fixed IP detection showing Docker gateway IPs instead of real client IPs
Fixed health check being blocked by IP whitelist
Removed unused code (279 lines) for better maintainability
Fixed error message capitalization to follow Go conventions

📝 Documentation

Comprehensive IP whitelisting guide
Detailed authentication setup instructions
Enhanced troubleshooting section
Updated configuration table with all environment variables
Security best practices reorganized by priority

🧹 Code Quality

Added package-level documentation comments
Removed 366 lines of dead code (auth.go, unused functions)
Added 87 lines of improvements
Better code organization and structure
Go conventions properly followed

🚀 Key Features

✅ Secure - API key authentication, IP whitelisting, constant-time comparison
✅ Lightweight - ~15MB Docker image, minimal resource usage
✅ Fast - Built-in caching with configurable TTL (default 5 minutes)
✅ Production-ready - Rate limiting (30 req/min), health checks, graceful shutdown
✅ Easy to deploy - Docker support with multi-arch builds (amd64, arm64)

📋 Requirements

Vaultwarden instance (self-hosted Bitwarden)
Docker (recommended) or Go 1.25+
Reverse proxy (recommended for HTTPS)

🔧 Quick Start

1. Pull the Docker image

docker pull turboot/vaultwarden-api:1.0.0

2. Create environment file

# Generate a strong API key (32+ characters)
openssl rand -base64 32

# Create .env file
cat > .env << 'EOF'
API_KEY=<your-generated-api-key>
VAULTWARDEN_URL=https://vault.yourdomain.com
VAULTWARDEN_CLIENT_ID=user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
VAULTWARDEN_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
VAULTWARDEN_PASSWORD=your-master-password
ALLOWED_IPS=<your-ip-address>
TRUSTED_PROXY_IP=172.16.0.0/12
EOF

3. Run the container

docker run -d \
  --name vaultwarden-api \
  --env-file .env \
  -p 8080:8080 \
  turboot/vaultwarden-api:1.0.0

4. Test the API

# Health check (public endpoint)
curl http://localhost:8080/health

# Get a secret (requires API key and whitelisted IP)
curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://localhost:8080/secret/DATABASE_URL

📊 Configuration

Required Environment Variables

Variable	Description
`API_KEY`	API key for authentication (min 32 chars)
`VAULTWARDEN_URL`	Your Vaultwarden instance URL
`VAULTWARDEN_CLIENT_ID`	API client ID from Vaultwarden
`VAULTWARDEN_CLIENT_SECRET`	API client secret from Vaultwarden
`VAULTWARDEN_PASSWORD`	Your Vaultwarden master password

Optional Security Variables

Variable	Default	Description
`ALLOWED_IPS`	(empty)	Comma-separated IPs/CIDRs to whitelist
`ENABLE_GITHUB_IP_RANGES`	`false`	Allow GitHub Actions IPs
`TRUSTED_PROXY_IP`	`localhost`	Trusted reverse proxy IPs/CIDRs

Other Variables

Variable	Default	Description
`API_PORT`	`8080`	Port to listen on
`ENVIRONMENT`	`development`	Environment (production/development)
`CACHE_TTL`	`5m`	Cache duration
`CORS_ALLOWED_ORIGINS`	`localhost:3000`	CORS origins
`DEBUG`	`false`	Enable debug logging

See .env.example for full configuration.

🔒 Security Recommendations

Production Deployment Checklist

Use HTTPS via reverse proxy (Nginx, Traefik, Cloudflare)
Enable IP whitelisting (ALLOWED_IPS)
Configure trusted proxies (TRUSTED_PROXY_IP)
Set ENVIRONMENT=production
Use strong API keys (32+ characters)
Use API key authentication (not session tokens)
Restrict CORS to specific domains
Monitor logs for blocked IP attempts
Regular security updates (rebuild monthly)

📖 Full Documentation

README: https://github.com/thijsherman/vaultwarden-api
Setup Guide: docs/SETUP_GUIDE.md
Docker Hub: https://hub.docker.com/r/turboot/vaultwarden-api

🔄 Upgrading from Pre-1.0 Versions

Breaking Changes

⚠️ Authentication method changed - Session tokens are now optional, CLI authentication is recommended.

Before (v0.x):

VAULTWARDEN_ACCESS_TOKEN=your-session-token

After (v1.0):

VAULTWARDEN_CLIENT_ID=user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
VAULTWARDEN_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxx
VAULTWARDEN_PASSWORD=your-master-password

Migration Steps

Stop the current container
```
docker stop vaultwarden-api
```
Update your .env file with new authentication variables

Pull the new image

docker pull turboot/vaultwarden-api:1.0.0

Update environment variables in Portainer or docker-compose
Start the container
```
docker start vaultwarden-api
```
Verify logs for successful authentication
```
docker logs -f vaultwarden-api
```

Note: Session tokens (VAULTWARDEN_ACCESS_TOKEN) still work but are deprecated and will be removed in v2.0.

🐛 Known Issues

None at this time

📝 Changelog

Added

IP whitelisting with CIDR support
GitHub Actions IP range auto-update
Trusted proxy configuration with validation
Bitwarden CLI authentication
Input validation for secret names
Debug logging mode
Comprehensive documentation
Package-level comments for all modules

Changed

Authentication now uses Bitwarden CLI (more reliable)
Health check endpoint is now public (no IP whitelist)
Improved error messages for configuration issues
Security best practices reorganized by priority

Fixed

Double cleanup of IP update goroutines
IP detection showing proxy IPs instead of client IPs
Health check blocked by IP whitelist
Error message capitalization (Go conventions)

Removed

Unused AuthManager and OAuth code (142 lines)
Unused NewClientWithAuth function
Unused logger sanitization functions
Unused config fields (VaultwardenClientID, VaultwardenSecret)
Dead code and imports

Security

Invalid proxy IPs are now validated and logged
IP/CIDR validation prevents misconfiguration
Proper X-Forwarded-For parsing for reverse proxy setups
Constant-time API key comparison
No sensitive data in logs

🙏 Acknowledgments

Built with Go and Fiber
Uses Bitwarden CLI
Inspired by the Vaultwarden project

📄 License

MIT License - See LICENSE file for details

v1.0.0