Click to login: Login
\",\n \"message_text\": \"Your login link: <%= URL %>?loginToken=<%= CODE %>\"\n}\n```\n\n**Template Variables:**\n- `<%= URL %>` - Your confirmation URL\n- `<%= CODE %>` - The generated token\n- `<%= USER %>` - User email/username\n- `<%= EXPIRES_AT %>` - Token expiration time\n\n### π JWT Settings\n\n```javascript\n{\n \"use_jwt_token\": true, // Use JWT for authentication\n \"jwt_token_expires_in\": \"30d\", // JWT validity (e.g., '7d', '30d', '365d')\n \"store_login_info\": true // Track IP and user agent\n}\n```\n\n### π‘οΈ Security & Rate Limiting\n\n```javascript\n{\n \"rate_limit_enabled\": true, // Enable rate limiting\n \"rate_limit_max_attempts\": 5, // Max requests per window\n \"rate_limit_window_minutes\": 15 // Time window in minutes\n}\n```\n\n**How it works:**\n- Limits token requests per IP address\n- Limits token requests per email address\n- Returns `429 Too Many Requests` when exceeded\n- Automatic cleanup every 30 minutes\n- Protects against brute-force and spam attacks\n\n**Example:** With default settings (5 attempts per 15 minutes):\n- User can request max 5 magic links in 15 minutes\n- After 5 attempts, they must wait up to 15 minutes\n- View statistics in Settings β Security & Rate Limiting\n- Manually cleanup expired entries or reset all limits\n\n---\n\n## π Required Environment Variables\n\nThe plugin stores secrets that must be protected across restarts and should\nnot be rotated with the rest of your Strapi key material. Two env vars are\n**mandatory in production** (the plugin refuses to boot without them):\n\n```bash\n# 32+ random bytes β used as AES-256 key for TOTP secrets.\n# DO NOT ROTATE: existing TOTP secrets would become undecryptable.\nMAGIC_LINK_ENCRYPTION_KEY=Click to login:
\n?loginToken=<%= CODE %>\">\n Login to Your Account\n\n```\n\n**Available Variables:**\n- `<%= URL %>` - Your confirmation URL\n- `<%= CODE %>` - The generated token\n\n---\n\n## π Security Features\n\n- **Token Expiration** - Configurable expiration periods\n- **One-time Tokens** - Optional single-use tokens\n- **IP Tracking** - Monitor login locations\n- **IP Banning** - Block suspicious addresses\n- **JWT Blacklist** - Revoke compromised sessions\n- **Login Attempt Limiting** - Prevent brute force\n- **User Agent Tracking** - Device fingerprinting\n\n---\n\n## π― Use Cases\n\n- **SaaS Applications** - Simplify user onboarding\n- **Customer Portals** - Secure, password-free access\n- **Multi-tenant Systems** - Easy user management\n- **Mobile Apps** - Seamless authentication flow\n- **Content Platforms** - Reduce password fatigue\n\n---\n\n## π Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| **Emails not sending** | Check Strapi email provider configuration in `config/plugins.js` |\n| **Token invalid errors** | Verify token hasn't expired. Check `expire_period` setting |\n| **User not found** | Enable `createUserIfNotExists` setting in admin panel |\n| **License activation fails** | Check network connectivity. Try manual activation with license key |\n| **npm install fails** | Use `npm install --legacy-peer-deps` or update to latest npm |\n| **OTP settings not visible** | Check license tier. Email OTP requires Premium license |\n| **TOTP not working** | Verify Advanced license is active. Check authenticator app time sync |\n| **\"Current License: Free\" but Premium activated** | Refresh browser cache. License info loads from `/magic-link/license/status` |\n| **Lock icons not centered** | Update to v4.16.1+. Mobile UI fixes are included |\n| **Email OTP shown without license** | Update to v4.16.3+. License validation is fixed |\n\n### Debug Mode\n\nEnable debug logging in your Strapi instance:\n\n```bash\n# In development\nNODE_ENV=development npm run develop\n\n# Check logs in terminal for Magic Link debug output\n```\n\n### Reset Plugin\n\nIf you need to reset the plugin:\n\n```bash\n# 1. Stop Strapi\n# 2. Clear plugin database entries\n# 3. Restart Strapi\nnpm run develop\n```\n\n### Get Support\n\n- π [GitHub Issues](https://github.com/Schero94/strapi-plugin-magic-link-v5/issues)\n- π Check the README for updated examples\n\n---\n\n## π€ Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n**Commit Convention:** Follow [Conventional Commits](https://www.conventionalcommits.org/)\n- `feat:` - New features\n- `fix:` - Bug fixes\n- `docs:` - Documentation changes\n- `chore:` - Maintenance tasks\n\n---\n\n## Changelog\n\n### v5.2.7 (2025-12-16) - Latest\n\n**WhatsApp Integration**\n- **WhatsApp Magic Links** - Send authentication links via WhatsApp messenger (FREE!)\n- **Customizable Templates** - Configure WhatsApp message text with variables\n- **Frontend URL Setting** - Set custom frontend login URLs for magic links\n- **Magic-Mail Integration** - Automatic delegation when both plugins installed\n- **QR Code Setup** - Easy WhatsApp connection via QR code scan\n- **Debug Mode** - Optional verbose logging for WhatsApp connections\n\n**New Settings:**\n- `frontend_login_url` - Custom frontend URL for magic links\n- `whatsapp_message_text` - WhatsApp message template\n- `whatsapp_app_name` - App name displayed in WhatsApp messages\n- `whatsapp_debug` - Enable/disable verbose WhatsApp logging\n\n### v5.1.10 (2025-12-15)\n\n**Plugin Compatibility Mode**\n- **Passwordless Plugin Compatibility** - Migration support for `strapi-plugin-passwordless`\n - Added `/api/passwordless/send-link` and `/api/passwordless/login` routes\n - Identical request/response format - no frontend changes needed!\n - Disabled by default for security (returns 404 when off)\n- **Email Designer 5 Integration** - Enhanced template support\n- New \"Compatibility\" settings section in admin UI\n- Full i18n support for compatibility settings (DE, EN, ES, FR, PT)\n- `compatibility-check` policy for secure route access\n\n### v4.16.3 (2025-11-22)\n\n**License Validation Fix**\n- β Fixed license tier detection from backend features\n- β Correctly extracts `premium`, `advanced`, `enterprise` from license response\n- β Enriched license info with `tier` field for UI compatibility\n- π Fixed \"Current License: Free\" display bug when Premium is active\n\n### v4.16.2 (2025-11-22)\n\n**Active State & Auto-Disable Fix**\n- β \"Magic Link Only\" now always shows ACTIVE with FREE license\n- β Email OTP settings only visible with Premium+ license\n- β Auto-disable premium features when license doesn't support them\n- β Added useEffect hook for automatic license enforcement\n\n### v4.16.1 (2025-11-22)\n\n**Lock Icons & License Checks**\n- β Perfectly centered lock/lightning icons in locked mode cards\n- β Fixed license validation in active state detection\n- β Locked features now show proper disabled state\n- π¨ Improved locked overlay with flexbox centering\n\n### v4.16.0 (2025-11-22)\n\n**Major UX Improvements**\n- π¨ Complete MFA settings redesign with modern UI\n- π License tier status display with visual indicators\n- π Locked feature cards with clear premium/advanced badges\n- π©πͺ Full German translations for all MFA settings\n- β Improved explanations and help texts\n- π§ Better Email OTP configuration section\n- π Added step-by-step \"How it works\" guides\n\n### v4.15.6 (2025-11-22)\n\n**Email OTP Configuration**\n- β Added Email OTP configuration section\n- βοΈ Code length, expiry time, max attempts settings\n- π Resend cooldown configuration\n- π§ OTP delivery method selection\n- βΉοΈ Improved help text and info boxes\n\n### v4.15.5 (2025-11-22)\n\n**Mobile & Settings UI Fixes**\n- π± Fixed mobile button icon centering issues\n- ποΈ Removed duplicate OTP accordion\n- π¨ Improved badge colors for better readability\n- β¨ Better contrast for Premium/Advanced badges\n\nFor full version history, see [GitHub Releases](https://github.com/Schero94/strapi-plugin-magic-link-v5/releases).\n\n---\n\n## π License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n**Important:** While the code is open source, the license validation system must remain intact. This ensures quality, security, and continued development of the plugin.\n\n---\n\n## π¬ Support & Community\n\n### Need Help?\n\n- π **Bug Reports**: [GitHub Issues](https://github.com/Schero94/strapi-plugin-magic-link-v5/issues)\n- π‘ **Feature Requests**: [GitHub Discussions](https://github.com/Schero94/strapi-plugin-magic-link-v5/discussions)\n- π¦ **npm Package**: [strapi-plugin-magic-link-v5](https://www.npmjs.com/package/strapi-plugin-magic-link-v5)\n\n### Resources\n\n- π **Documentation**: This README + [Strapi Docs](https://docs.strapi.io)\n- π» **Source Code**: [GitHub Repository](https://github.com/Schero94/strapi-plugin-magic-link-v5)\n- π― **Live Example**: Coming soon\n- πΉ **Video Tutorial**: Coming soon\n\n### Sponsoring\n\nIf this plugin saves you time and you'd like to support development:\n\n- β Star the repository on GitHub\n- π Report bugs and suggest features\n- π‘ Contribute code improvements\n- π’ Share with the Strapi community\n\n---\n\n## Security Advisories & Dependency Overrides\n\nThis plugin ships with a first-party dependency tree audited on every\nrelease, but two transitive paths are governed by upstream packages we\ndo not control. If your own `npm audit` flags any of the following,\nadd the matching entry to your **Strapi project's** `package.json`\n(not this plugin's β npm `overrides` only take effect on the\nroot project):\n\n```jsonc\n{\n \"overrides\": {\n // GHSA-xq3m-2v4x-88gg β protobufjs <7.5.5 arbitrary code execution.\n // Reaches us via @whiskeysockets/baileys β libsignal β protobufjs.\n // We already ship this override for local development; apply it in\n // your Strapi project so the fix propagates to the installed tree.\n \"protobufjs\": \"^7.5.5\",\n\n // Optional: if you do not use the WhatsApp delivery feature, you\n // can also skip installing @whiskeysockets/baileys altogether:\n // npm install --omit=optional\n // (The Magic-Link code path detects the missing module and\n // disables the WhatsApp controller at runtime β the rest of the\n // plugin keeps working.)\n }\n}\n```\n\nAfter editing `package.json`, run:\n\n```bash\nrm -rf node_modules package-lock.json\nnpm install\nnpm audit\n```\n\nThe critical `protobufjs` advisory disappears once the override is in\nplace. The remaining `@strapi/design-system β lodash` advisory is a\nStrapi-core issue and will clear up automatically when you upgrade\n`@strapi/strapi` to the latest patch release.\n\n---\n\n