feat: add local GeoIP firewall and free session manager

Remove premium gating from the admin/server flow, add regression tests for session lifecycle fixes, and wire a local MaxMind GeoLite2 provider for geofencing.

Add admin UI controls and backend routes for storing MaxMind credentials and downloading/updating the local MMDB database from inside the plugin.

Verification: npm test; npm run build; npm run verify; npm run verify:runtime; npm pack --dry-run --json.

Author: Schero94

.gitignore

@@ -10,6 +10,9 @@ test-*.ts
 *.test.ts
 *.spec.js
 *.spec.ts
+!tests/
+!tests/*.test.js
+!tests/*.test.mjs
 TEST_*.md
 TEST_RESULTS.md
 RELEASE_CHECKLIST.md
@@ -63,4 +66,7 @@ tmp/
 
 # Build artifacts
 *.map
-.cache/
+.cache/
+
+# Local agent archive
+.archive/

.planning/HANDOFF.json

@@ -0,0 +1,146 @@
+{
+  "version": "1.0",
+  "timestamp": "2026-06-20T22:04:41.326Z",
+  "source": "auto-postool",
+  "partial": false,
+  "phase": null,
+  "phase_name": null,
+  "phase_dir": null,
+  "plan": null,
+  "task": null,
+  "total_tasks": null,
+  "status": "auto-checkpoint",
+  "completed_tasks": [],
+  "remaining_tasks": [],
+  "blockers": [],
+  "human_actions_pending": [],
+  "decisions": [],
+  "uncommitted_files": [
+    {
+      "status": "M",
+      "path": "README.md"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/components/LicenseGuard.jsx"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/components/SessionDetailModal.jsx"
+    },
+    {
+      "status": "D",
+      "path": "admin/src/hooks/useLicense.js"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/index.js"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/pages/Analytics.jsx"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/pages/HomePage.jsx"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/pages/License.jsx"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/pages/Settings.jsx"
+    },
+    {
+      "status": "D",
+      "path": "admin/src/pages/UpgradePage.jsx"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/translations/de.json"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/translations/en.json"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/translations/es.json"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/translations/fr.json"
+    },
+    {
+      "status": "M",
+      "path": "admin/src/translations/pt.json"
+    },
+    {
+      "status": "M",
+      "path": "package-lock.json"
+    },
+    {
+      "status": "M",
+      "path": "package.json"
+    },
+    {
+      "status": "M",
+      "path": "server/src/bootstrap.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/controllers/license.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/controllers/session.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/controllers/settings.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/destroy.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/routes/admin.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/services/license-guard.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/services/session.js"
+    },
+    {
+      "status": "M",
+      "path": "server/src/utils/settings-loader.js"
+    },
+    {
+      "status": "M",
+      "path": "strapi-admin.js"
+    },
+    {
+      "status": "M",
+      "path": "strapi-server.js"
+    },
+    {
+      "status": "??",
+      "path": ".planning/"
+    },
+    {
+      "status": "??",
+      "path": "scripts/build-server-bundle.mjs"
+    },
+    {
+      "status": "??",
+      "path": "scripts/verify-server-bundle.mjs"
+    }
+  ],
+  "next_action": null,
+  "context_notes": "Recent commits:\n1402eef fix(build): use non-destructured require for @strapi/utils\n2100783 chore(release): 4.5.12 [skip ci]\n729e794 fix(build): declare @strapi/utils as peerDependency — preventive zod/v4 fix\nb165368 chore(release): 4.5.11 [skip ci]\n21779d8 fix(rbac): make plugin::magic-sessionmanager.access visible in role editor"
+}

README.md

@@ -4,6 +4,8 @@
 
 Track logins, monitor active users, and secure your app with one simple plugin. No complicated setup required.
 
+Free and open under the MIT license. All features are available without a paid license or activation key.
+
 [![NPM](https://img.shields.io/npm/v/strapi-plugin-magic-sessionmanager.svg)](https://www.npmjs.com/package/strapi-plugin-magic-sessionmanager)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
@@ -45,8 +47,8 @@ Track logins, monitor active users, and secure your app with one simple plugin.
 - Full device information
 - Browser and operating system
 - Complete session history
-- IP geolocation (Premium)
-- Security risk score (Premium)
+- IP geolocation
+- Security risk score
 
 ---
 
@@ -199,7 +201,7 @@ SESSION_ENCRYPTION_KEY=your-key-here
 - Last time they did something
 - What browser/device they use
 - Their IP address
-- Location (if Premium)
+- Location
 
 ### 4. Multiple Devices
 
@@ -269,7 +271,7 @@ Add to `config/plugins.ts`:
 
 ---
 
-## 🌍 Premium Features (Optional License)
+## 🌍 Security Features
 
 ### IP Geolocation
 
@@ -279,6 +281,77 @@ Add to `config/plugins.ts`:
 - ISP Provider
 - Coordinates (for map)
 
+### Local GeoIP Firewall (Recommended)
+
+For login blocking, use a local MaxMind GeoLite2 Country database. This avoids
+remote API timeouts and rate limits in the login path.
+
+1. Create a free MaxMind account and download `GeoLite2-Country.mmdb`:
+   https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/
+2. Store the file on your Strapi server, for example:
+   `/var/lib/strapi/GeoLite2-Country.mmdb`
+3. Configure the plugin:
+
+```bash
+MAGIC_SESSIONMANAGER_GEOIP_DATABASE=/var/lib/strapi/GeoLite2-Country.mmdb
+MAXMIND_ACCOUNT_ID=your-account-id
+MAXMIND_LICENSE_KEY=your-license-key
+```
+
+You can also manage this from the Strapi admin UI. Open
+**Magic Session Manager -> Settings -> Geofencing**, choose `local-mmdb`,
+enter the MaxMind account ID and license key, then use **Download / Update DB**.
+The plugin stores the credentials in the Strapi plugin store and never returns
+the license key to the browser after saving it.
+
+Download or update the database:
+
+```bash
+npm run geoip:update
+```
+
+When installed as a package in a Strapi project, run the packaged binary:
+
+```bash
+npx strapi-magic-sessionmanager-geoip
+```
+
+The updater checks MaxMind's `Last-Modified` header first and skips the download
+when the local metadata is current. Use `npm run geoip:update -- --force` in the
+plugin repo or `npx strapi-magic-sessionmanager-geoip --force` in an installed
+Strapi project to force a refresh. Schedule it weekly or twice weekly with
+cron/systemd. MaxMind requires GeoLite databases to stay up to date and
+currently limits GeoLite users to 30 database downloads per day.
+
+```typescript
+// config/plugins.ts
+export default () => ({
+  'magic-sessionmanager': {
+    enabled: true,
+    config: {
+      geoIpProvider: 'local-mmdb',
+      geoIpDatabasePath: process.env.MAGIC_SESSIONMANAGER_GEOIP_DATABASE,
+      // "auto": fail closed for suspicious-session blocking, fail open for plain geofencing
+      // "block": fail closed whenever GEOIP lookup is unavailable
+      // "allow": fail open whenever GEOIP lookup is unavailable
+      geoLookupFailureMode: 'block',
+      enableGeofencing: true,
+      allowedCountries: ['DE', 'AT', 'CH'],
+    },
+  },
+});
+```
+
+Provider options:
+- `local-mmdb`: local MaxMind-compatible database only
+- `auto`: use local database when configured, otherwise use the legacy remote provider
+- `ipapi`: legacy remote provider
+- `disabled`: no GEOIP lookup
+
+Country firewall rules use the local database. VPN/proxy/threat detection still
+requires a provider that supplies those risk signals; a free country database
+does not reliably identify VPNs or proxies.
+
 ### Threat Detection
 
 **Automatically check if IP is:**
@@ -305,7 +378,7 @@ Add to `config/plugins.ts`:
 
 ---
 
-## 📧 Email Alerts Setup (Premium)
+## 📧 Email Alerts Setup
 
 The Session Manager uses **Strapi's Email Plugin** to send notifications. You need to configure an email provider first.
 
@@ -713,11 +786,11 @@ When you install this plugin, you get:
 - ✅ Encryption (secure)
 - ✅ Multi-device support
 
-**Premium features require a license (free to generate):**
-- 🔒 IP Geolocation
-- 🔒 Threat detection
-- 🔒 Auto-blocking
-- 🔒 Email/webhook alerts
+**All features are included for free:**
+- ✅ IP Geolocation
+- ✅ Threat detection
+- ✅ Auto-blocking
+- ✅ Email/webhook alerts
 
 ---
 
@@ -757,32 +830,11 @@ A: Not yet, but it's planned for future versions!
 
 **Copyright © 2025 Schero D.**
 
-### Important License Restriction
-
-This plugin is **free and open source**, BUT:
-
-⚠️ **You CANNOT modify the license validation system**
-
-This means:
-- ❌ Cannot remove `license-guard.js`
-- ❌ Cannot bypass license activation
-- ❌ Cannot disable license checks
-- ❌ Cannot modify license-related endpoints
-
-**Why?** The license system ensures:
-- Quality and ongoing support
-- Spam prevention
-- Usage analytics for improvements
-- Fair use tracking
+### Optional license-key activation
 
-**What you CAN do:**
-- ✅ Use freely (personal & commercial)
-- ✅ View and study source code
-- ✅ Report issues and contribute
-- ✅ Deploy in production without fees
-- ✅ Integrate in your projects
+The admin panel includes a License page where you can register an optional key. This is only used for install tracking and support context; it does not unlock or restrict any plugin feature.
 
-See [LICENSE](./LICENSE) and [COPYRIGHT_NOTICE.txt](./COPYRIGHT_NOTICE.txt) for full terms.
+See [LICENSE](./LICENSE) for full terms.
 
 ---