v15.0

# Notifuse v15.0 Release Notes

**Release Date:** November 1, 2025

## 🔒 Major Security Release: Enhanced Authentication & Authorization

Notifuse v15.0 represents a significant security milestone with the migration from PASETO to industry-standard JWT authentication, along with comprehensive improvements to authentication security.

---

## 🎯 What's New

### JWT Authentication (HS256)
We've migrated from PASETO to industry-standard JWT with HMAC-SHA256 signing, bringing:
- **Simplified setup**: Single `SECRET_KEY` environment variable instead of managing asymmetric key pairs
- **Comprehensive token validation**: Signature, expiration, and claims verification

### HMAC-Protected Magic Codes
Authentication codes are now stored securely:
- Magic codes stored as HMAC-SHA256 hashes (never in plain text)
- Database compromise cannot reveal authentication codes

### Server-Side Logout
Full session management with instant invalidation:
- New `/api/user.logout` endpoint for complete session termination
- Deletes ALL sessions for authenticated user from database

### Rate Limiting for Authentication Endpoints
Protection against brute force attacks and email bombing:
- **5 attempts per 5 minutes** per email address for sign-in
- **5 attempts per 5 minutes** per email address for code verification
- Sliding window algorithm with automatic cleanup
- Rate limiter resets on successful authentication
- Thread-safe concurrent access
- Prevents 99%+ of magic code brute force attempts

---

## ⚠️ BREAKING CHANGES & MIGRATION

### Before You Upgrade

#### 🚨 CRITICAL: About Your SECRET_KEY

**For Existing Deployments:**
- **DO NOT change your existing `SECRET_KEY`** 
- It encrypts all workspace integration secrets (API keys, SMTP passwords, email provider credentials)
- Changing it will permanently destroy all encrypted credentials
- Your email sending will break completely

**For New Installations:**
- Generate a new key: `export SECRET_KEY=$(openssl rand -base64 32)`

**If migrating from PASETO:**
- Use your existing PASETO key: `export SECRET_KEY="$PASETO_PRIVATE_KEY"`

### What Gets Invalidated During Migration

The following will be reset during the PASETO → JWT migration (this is a one-time event):

- ✗ **All user sessions** - Users must log in again (PASETO tokens → JWT tokens)
- ✗ **All API keys** - Must be regenerated (PASETO format → JWT format)
- ✗ **All pending workspace invitations** - Invitation tokens were PASETO-signed
- ✗ **All active magic codes** - Migrating from plain-text → HMAC-SHA256 hashes

**Why?** PASETO tokens are incompatible with JWT verification. Clean migration ensures no security gaps.

### Migration Steps

1. **Set SECRET_KEY environment variable** (if not already set)
   ```bash
   export SECRET_KEY="your-existing-secret-key"
   ```

2. **Start/Restart your Notifuse server**
   - Migration v15 runs automatically
   - Server will restart automatically after migration
   - Migration takes less than 1 second
   - Safe to run multiple times (idempotent)

3. **Post-Migration Actions:**
   - **Users**: Log in again with email/password or magic code
   - **API Key Holders**: Regenerate API keys in Settings → API Keys
   - **Integrations**: Update all API integrations with new keys
   - **Workspace Admins**: Resend pending invitations via Settings → Members → Invitations

## 📖 Full Changelog

For complete technical details, see [CHANGELOG.md](./CHANGELOG.md#150---2025-11-01).

---

## 🆘 Support

If you encounter any issues during migration:

1. Check that `SECRET_KEY` is set correctly
2. Review server logs for migration status
3. Open an issue on [GitHub](https://github.com/notifuse/notifuse/issues)

---

**Questions?** Check our [documentation](https://docs.notifuse.com) or open a GitHub issue.