Release: v0.1.0-alpha

2026-04-05 16:56:16 +02:00
parent 23ff731579
commit fd13e67aef
89 changed files with 18786 additions and 0 deletions
@@ -0,0 +1,110 @@
+# Email Configuration
+
+Keywarden supports SMTP-based email for login notifications and user invitations. Email is optional — all core functionality works without it.
+
+## Enabling Email
+
+Set the `KEYWARDEN_SMTP_HOST` environment variable to enable email:
+
+```env
+KEYWARDEN_SMTP_HOST=smtp.example.com
+KEYWARDEN_SMTP_PORT=587
+KEYWARDEN_SMTP_USER=keywarden@example.com
+KEYWARDEN_SMTP_PASSWORD=your-password
+KEYWARDEN_SMTP_FROM=keywarden@example.com
+KEYWARDEN_SMTP_TLS=true
+```
+
+If `KEYWARDEN_SMTP_HOST` is empty, email is completely disabled and all email-related features are hidden from the UI.
+
+## TLS Configuration
+
+| Port | Mode | Setting |
+|---|---|---|
+| `587` | STARTTLS | `KEYWARDEN_SMTP_TLS=true` (default) |
+| `465` | Implicit TLS | `KEYWARDEN_SMTP_TLS=true` + `KEYWARDEN_SMTP_PORT=465` |
+| `25` | Unencrypted | `KEYWARDEN_SMTP_TLS=false` (not recommended) |
+
+- Port **587** uses STARTTLS (upgrade from plaintext to TLS after connection)
+- Port **465** uses implicit TLS (TLS from the start)
+- Minimum TLS version: TLS 1.2
+
+## Email Features
+
+### Login Notifications
+
+Users can individually enable login notification emails in their account settings. When enabled, each successful login triggers an email containing:
+
+- Username
+- Client IP address
+- Timestamp
+- User agent (browser information)
+
+Emails are sent asynchronously in a background goroutine to avoid slowing down the login flow.
+
+### User Invitations
+
+When an admin creates a new user, they can choose to send an **invitation email** instead of setting a password manually. The invitation email contains:
+
+- The username
+- A secure one-time link (`/invite/{token}`)
+- Expiration time (48 hours)
+
+The invitation token is a 32-byte cryptographic random value, base32-encoded. Once used, the token is marked as consumed and cannot be reused.
+
+### Test Email
+
+The owner can send a test email from the Admin Settings page to verify that SMTP configuration is working correctly.
+
+## Email Templates
+
+All emails are sent as **multipart/alternative** (both plain text and HTML). The HTML versions use responsive, inline-styled templates.
+
+### Login Notification Email
+
+- **Subject**: `Keywarden: Login notification for {username}`
+- **Content**: IP address, timestamp, user agent
+- **Trigger**: Successful login when the user has notifications enabled
+
+### Invitation Email
+
+- **Subject**: `Keywarden: You have been invited – {username}`
+- **Content**: Username, registration link, expiration time
+- **Trigger**: Admin creates a user with "Send Invitation" enabled
+
+### Test Email
+
+- **Subject**: `Keywarden: SMTP Test Email`
+- **Content**: Confirmation that SMTP is working
+
+## Base URL Requirement
+
+For invitation emails to contain the correct link, set the `KEYWARDEN_BASE_URL` environment variable:
+
+```env
+KEYWARDEN_BASE_URL=https://keywarden.example.com
+```
+
+If not set, invitation links use relative paths which may not work in email clients.
+
+## Troubleshooting
+
+### Email Not Sent
+
+1. Check that `KEYWARDEN_SMTP_HOST` is set
+2. Verify SMTP credentials
+3. Check the application logs for SMTP errors (`KEYWARDEN_LOG_LEVEL=DEBUG` for details)
+4. Try sending a test email from Admin Settings
+5. Verify network connectivity from the container to the SMTP server
+
+### TLS Errors
+
+- Ensure the SMTP server supports TLS 1.2+
+- For self-signed certificates, the default TLS configuration may reject them
+- Try different port/TLS combinations
+
+### Authentication Failures
+
+- Verify username and password
+- Some providers require app-specific passwords (e.g., Gmail, Microsoft 365)
+- Check if the SMTP server requires a specific authentication mechanism