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)

   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.

🆘 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

Questions? Check our documentation or open a GitHub issue.