release: 2.4.0 - license activation required

Polishes the licensing rollout for public release:

- Better error UX: HTTP 503 now carries instance_id, docs_url and an
  actionable message instructing the operator to open the manager UI
  or set AUTHENTICATION_API_KEY in .env.
- Better boot banner: lists the activation paths (manager UI, env var)
  with the docs URL and the instance_id.
- Auto-detect missing migration: if the RuntimeConfig table is absent,
  the server prints a clear banner asking the operator to run
  npm run db:deploy and exits 1, instead of throwing a Prisma stack
  trace from inside the bootstrap.
- Version bump 2.3.7 -> 2.4.0.
- CHANGELOG entry with BREAKING CHANGE notice and migration guide.
- README section 'License Activation' linking to
  docs.evolutionfoundation.com.br/licensing.

Author: DavidsonGomes

CHANGELOG.md

@@ -1,3 +1,109 @@
+# 2.4.0 (2026-05-06)
+
+### ⚠️ BREAKING CHANGE — License activation is now required
+
+Starting with v2.4.0, every Evolution API instance must be activated against the
+Evolution Foundation licensing server before serving API traffic. Until activation,
+all business endpoints return:
+
+```
+HTTP 503 Service Unavailable
+{
+  "error": "service not activated",
+  "code": "LICENSE_REQUIRED",
+  "register_url": "https://<your-host>/manager/login",
+  "instance_id": "<uuid>",
+  "docs_url": "https://docs.evolutionfoundation.com.br/licensing",
+  "message": "..."
+}
+```
+
+The following routes always remain public so the operator can recover:
+`/license/status`, `/license/register`, `/license/activate`, `/manager/**`,
+`/health`, `/server/ok`, `/ws`, static assets.
+
+### Migration guide
+
+1. Pull the new version and install dependencies:
+   ```bash
+   git pull
+   npm install
+   ```
+
+2. Apply the new migration (creates the `RuntimeConfig` table). Required:
+   ```bash
+   npm run db:deploy
+   ```
+   If you skip this step, the server now fails fast with a clear error
+   asking you to run `db:deploy`.
+
+3. Start the service. There are three activation paths:
+
+   - **Already have a valid licensing key?** Set it as `AUTHENTICATION_API_KEY`
+     in your `.env` and restart. The bootstrap step will validate the key with
+     the licensing server, persist it, and activate the instance automatically.
+
+   - **First-time activation via the manager UI?** Open
+     `https://<your-host>/manager/login`. The manager detects that the
+     instance is unlicensed and redirects you to the registration page on
+     the licensing server. After you complete the form, you are sent back
+     to `/manager/license/callback?code=...`, the manager exchanges the code,
+     and the dashboard becomes accessible.
+
+   - **Calling the API from code (n8n, Make, custom scripts) without a valid
+     license?** Every request will receive `503 LICENSE_REQUIRED` with the
+     `register_url` field pointing to the manager. Open it in a browser to
+     activate.
+
+### Added
+
+- **Licensing module** under `src/licensing/` — RuntimeContext, gate middleware,
+  signed/unsigned HTTP transport, hardware-based instance ID, fire-and-forget
+  heartbeat (every 30 min), graceful shutdown deactivation.
+- **Public license endpoints**:
+  - `GET /license/status` — current activation state and (masked) api_key
+  - `GET /license/register?redirect_uri=` — initiates registration on the
+    licensing server, returns `register_url`
+  - `GET /license/activate?code=` — exchanges the authorization code received
+    on the callback for a real api_key, persists it, marks the runtime active.
+- **New Prisma model** `RuntimeConfig` (key/value rows in `RuntimeConfig` table)
+  for both PostgreSQL and MySQL schemas.
+- **Auto-detect missing migration**: if the `RuntimeConfig` table is absent,
+  the server prints a clear banner explaining `npm run db:deploy` and exits 1
+  instead of throwing a stack trace from the Prisma client.
+- **Manager v2** ships with the new license-aware login flow that recognises
+  HTTP 503 / `LICENSE_REQUIRED`, calls `/license/register`, and redirects to
+  the registration server. After the callback, it lands on
+  `/manager/license/callback?code=...` and finalises activation. The new
+  manager bundle is included under `manager/dist/`.
+
+### Notes
+
+- `AUTHENTICATION_API_KEY` keeps its original meaning (global API key for
+  business endpoints) **and** gains a second use as the bootstrap license
+  key. If the value you have is a real licensing key, activation is silent.
+  If it is not, the service starts unlicensed and waits for activation via
+  the manager.
+- Activation is a one-time operation. The `api_key` is stored in the database
+  and reused across restarts. The licensing server is only consulted again
+  for periodic heartbeats (telemetry — non-blocking) and on graceful shutdown
+  (`/v1/deactivate`).
+- If the licensing server is unreachable but the instance has been activated
+  before, the service continues to serve traffic normally — local DB is the
+  source of truth for activation state after the first successful call.
+
+### Troubleshooting
+
+- **`HTTP 503 LICENSE_REQUIRED`** — expected before activation. Follow the
+  migration guide.
+- **`The table evolution_api.RuntimeConfig does not exist`** (legacy stack
+  trace if you somehow bypass the new auto-detect) — run `npm run db:deploy`.
+- **`Global API key not accepted by licensing server: invalid signature`** —
+  your existing `AUTHENTICATION_API_KEY` is not a valid licensing key. Use
+  the manager UI flow to obtain a new one.
+
+---
+
 # 2.3.7 (2025-12-05)
 
 ### Features

README.md

@@ -124,6 +124,33 @@ docker run -p 8080:8080 --env-file .env evoapicloud/evolution-api:latest
 
 ---
 
+## License Activation
+
+Starting from **v2.4.0**, every Evolution API instance must be activated
+against the Evolution Foundation licensing server before serving API
+traffic. While unactivated, business endpoints return
+`HTTP 503 LICENSE_REQUIRED` with a `register_url` pointing to the manager
+UI.
+
+There are two ways to activate:
+
+1. **Set a known licensing key** as `AUTHENTICATION_API_KEY` in your
+   `.env`. The server validates it on boot, persists it locally and
+   activates the instance silently.
+2. **Activate via the manager UI** at `https://<your-host>/manager/login`.
+   On first login the manager detects an unlicensed backend and redirects
+   you to the registration server; once you complete the form you are
+   redirected back and the dashboard becomes accessible.
+
+Activation is a one-time operation — the key is persisted in the
+`RuntimeConfig` table and reused across restarts. The licensing server is
+only consulted again for fire-and-forget heartbeats (telemetry) and a
+best-effort `/v1/deactivate` notice on graceful shutdown.
+
+Full activation guide: <https://docs.evolutionfoundation.com.br/licensing>
+
+---
+
 ## Architecture
 
 Evolution API is built with a multi-provider, event-driven architecture:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolution-api",
-  "version": "2.3.7",
+  "version": "2.4.0",
   "description": "Rest api for communication with WhatsApp",
   "main": "./dist/main.js",
   "type": "commonjs",

src/licensing/runtime.ts

@@ -122,7 +122,23 @@ export async function initializeRuntime(opts: InitializeOptions = {}): Promise<R
   const rc = new RuntimeContext(globalApiKey, tier, version);
 
   // Step 1: Instance ID (hardware-based, persistent across restarts).
-  rc.instanceId = await loadOrCreateInstanceID();
+  try {
+    rc.instanceId = await loadOrCreateInstanceID();
+  } catch (err) {
+    if ((err as { code?: string })?.code === 'P2021') {
+      // Prisma error P2021 = "table does not exist" — almost always means
+      // the operator skipped `npm run db:deploy` after upgrading.
+      logger.error('╔══════════════════════════════════════════════════════════╗');
+      logger.error('║          Database is missing the licensing table          ║');
+      logger.error('╚══════════════════════════════════════════════════════════╝');
+      logger.error('The RuntimeConfig table was not found in the database.');
+      logger.error('Run the migration and restart:');
+      logger.error('  npm run db:deploy');
+      logger.error(`Docs: ${DOCS_URL}`);
+      process.exit(1);
+    }
+    throw err;
+  }
 
   // Step 2: Try loading existing license from DB.
   const stored = await loadRuntimeData();
@@ -160,21 +176,31 @@ export async function initializeRuntime(opts: InitializeOptions = {}): Promise<R
       logger.debug(`Global API key not accepted by licensing server: ${readErrorMessage(err)}`);
     }
   } else {
-    printRegistrationBanner();
+    printRegistrationBanner(rc);
     rc.setActive(false);
   }
 
   globalRC = rc;
   return rc;
 }
 
-function printRegistrationBanner(): void {
+const DOCS_URL = 'https://docs.evolutionfoundation.com.br/licensing';
+
+function printRegistrationBanner(rc?: RuntimeContext): void {
   logger.warn('╔══════════════════════════════════════════════════════════╗');
   logger.warn('║              License Registration Required               ║');
   logger.warn('╚══════════════════════════════════════════════════════════╝');
-  logger.warn('Server starting without license.');
-  logger.warn('API endpoints will return 503 until license is activated.');
-  logger.warn('Use GET /license/register to get the registration URL.');
+  logger.warn('This Evolution API instance is not activated yet.');
+  logger.warn('API endpoints will return HTTP 503 until activation.');
+  logger.warn('');
+  logger.warn('To activate:');
+  logger.warn('  1. Open the manager at /manager/login on this host');
+  logger.warn('  2. Or set AUTHENTICATION_API_KEY in your .env with a valid licensing key');
+  logger.warn(`  3. Docs: ${DOCS_URL}`);
+  if (rc?.instanceId) {
+    logger.warn('');
+    logger.warn(`Instance ID: ${rc.instanceId}`);
+  }
 }
 
 function maskKey(key: string): string {
@@ -229,7 +255,9 @@ export function gateMiddleware(rc: RuntimeContext) {
         error: 'service not activated',
         code: 'LICENSE_REQUIRED',
         register_url: managerUrl,
-        message: 'License required. Open the manager to activate your license.',
+        instance_id: rc.instanceId,
+        docs_url: DOCS_URL,
+        message: `This Evolution API instance is not activated. Open ${managerUrl} to activate, or set AUTHENTICATION_API_KEY in your .env with a valid licensing key. Docs: ${DOCS_URL}`,
       });
     }