Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
feat(auth): report the running engine from POST /auth/validate
Yudhi Armyndharisde2d4a0332d9
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex d1b3aac46..eab0d88db 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -4968,16 +4968,16 @@ Permanently delete an API key (hard delete). Also drops any un-flushed usage acc#### POST /api/auth/validate-Validate the supplied `X-API-Key` and report its validity and role.+Validate the supplied `X-API-Key` and report its validity, its role, and the engine the gateway runs.**Auth:** API key (any valid role — VIEWER+)-The key is read from the `X-API-Key` header, not the body; send an empty body. This route sits behind the global guard (it is not `@Public`), so a missing/invalid/revoked/expired key is rejected with `401` at the guard before the handler runs. On success it returns the caller's role. A key restricted with `allowedChats` is refused with `403 "API key is restricted to selected chats"`: the route is not open to a chat-scoped key.+The key is read from the `X-API-Key` header, not the body; send an empty body. This route sits behind the global guard (it is not `@Public`), so a missing/invalid/revoked/expired key is rejected with `401` at the guard before the handler runs. On success it returns the caller's role and `engineType`, the engine the process resolved at boot (`whatsapp-web.js` or `baileys`). The engine is reported to every role because `GET /api/infra/engines/current` is ADMIN-only. A key restricted with `allowedChats` is refused with `403 "API key is restricted to selected chats"`: the route is not open to a chat-scoped key.**Response** `200````json-{ "valid": true, "role": "operator" }+{ "valid": true, "role": "operator", "engineType": "whatsapp-web.js" }```**Errors:** `401` missing/invalid/revoked/expired key (raised by the global guard before the handler); `403` a key restricted with `allowedChats`@@ -5352,7 +5352,7 @@ omitted per engine.#### GET /api/infra/engines/current-Get the currently active engine type.+Get the currently active engine type. A non-admin key reads the same value from `POST /api/auth/validate`.**Auth:** API key (ADMIN)diff --git a/docs/07-api-collection.md b/docs/07-api-collection.mdindex 3513c34bb..6f3feddcd 100644--- a/docs/07-api-collection.md+++ b/docs/07-api-collection.md@@ -1278,7 +1278,7 @@ curl -X DELETE "$BASE/api/auth/api-keys/3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33" \#### POST /api/auth/validate-Validate the supplied key and report its role (empty body; key read from the header).+Validate the supplied key and report its role and the running engine (`engineType`); empty body, key read from the header.```bashcurl -X POST "$BASE/api/auth/validate" \diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 1487dbf0d..afb9dc27e 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -119,10 +119,10 @@ All resources are accessed as properties on the client (`client.<resource>.<methThe top-level client also exposes:-| Method | Signature | Description |-| --------- | ---------------------------- | -------------------------------------------------------------------------- |-| `auth` | `client.auth()` | Validate the configured API key and resolve its role (`{ valid, role? }`). |-| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |+| Method | Signature | Description |+| --------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |+| `auth` | `client.auth()` | Validate the configured API key and resolve its role and the running engine (`{ valid, role?, engineType? }`). |+| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |#### `sessions`diff --git a/openapi.json b/openapi.jsonindex e5106dca9..2851ea1e9 100644--- a/openapi.json+++ b/openapi.json@@ -10309,6 +10309,11 @@"viewer"],"description": "The key's role; present only when valid."+ },+ "engineType": {+ "type": "string",+ "description": "Engine the process resolved at boot; present only when valid.",+ "example": "baileys"}},"required": [diff --git a/sdk/go/types_misc.go b/sdk/go/types_misc.goindex bc2953422..17e558211 100644--- a/sdk/go/types_misc.go+++ b/sdk/go/types_misc.go@@ -26,8 +26,9 @@ type HealthReadyResponse struct {// AuthValidateResponse reports whether the API key is valid and its role.type AuthValidateResponse struct {- Valid bool `json:"valid"`- Role string `json:"role,omitempty"`+ Valid bool `json:"valid"`+ Role string `json:"role,omitempty"`+ EngineType string `json:"engineType,omitempty"`}// ── Template ───────────────────────────────────────────diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.javaindex 8967584df..bd7041d9c 100644--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java@@ -1,4 +1,4 @@package com.rmyndharis.openwa.model;/** Result of validating the configured API key. */-public record AuthValidateResponse(boolean valid, String role) {}+public record AuthValidateResponse(boolean valid, String role, String engineType) {}diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.tsindex bfd8107b1..b051e6df9 100644--- a/sdk/javascript/src/types.ts+++ b/sdk/javascript/src/types.ts@@ -1189,6 +1189,7 @@ export interface HealthReadyResponse {export interface AuthValidateResponse {valid: boolean;role?: string;+ engineType?: string;}// ── Template ──────────────────────────────────────────────────────diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.pyindex 7a546f24e..ff6bdd35f 100644--- a/sdk/python/openwa/types.py+++ b/sdk/python/openwa/types.py@@ -1204,6 +1204,7 @@ class HealthReadyResponse(TypedDict, total=False):class AuthValidateResponse(TypedDict, total=False):valid: boolrole: str+ engineType: str# ── Template ──────────────────────────────────────────────────────diff --git a/src/modules/auth/auth-validate.controller.spec.ts b/src/modules/auth/auth-validate.controller.spec.tsindex f0e8b7d3e..87744f78f 100644--- a/src/modules/auth/auth-validate.controller.spec.ts+++ b/src/modules/auth/auth-validate.controller.spec.ts@@ -1,25 +1,33 @@import { AuthValidateController } from './auth-validate.controller';import { ApiKey, ApiKeyRole } from './entities/api-key.entity';+import { EngineFactory } from '../../engine/engine.factory';describe('AuthValidateController', () => {- const controller = new AuthValidateController();+ const engineFactory = { getCurrentEngine: () => 'baileys' } as unknown as EngineFactory;+ const controller = new AuthValidateController(engineFactory);const makeKey = (over: Partial<ApiKey> = {}): ApiKey =>({ id: 'k1', role: ApiKeyRole.OPERATOR, isActive: true, allowedIps: null, ...over }) as ApiKey;- it('reports the guard-validated key as valid, echoing its role', () => {+ it('reports the guard-validated key as valid, echoing its role and the running engine', () => {expect(controller.validate(makeKey({ role: ApiKeyRole.ADMIN }))).toEqual({valid: true,role: ApiKeyRole.ADMIN,+ engineType: 'baileys',});});+ it('reports the engine to an operator key, which cannot read the admin-only infra route', () => {+ // The dashboard needs the engine to gate status compose and the Channels tab for every writer.+ expect(controller.validate(makeKey({ role: ApiKeyRole.OPERATOR }))).toMatchObject({ engineType: 'baileys' });+ });+it('returns valid:true for an IP-restricted key (no IP-less re-validation false negative)', () => {// The global guard already validated this key against the real client IP and attached it.// The handler must NOT re-validate without an IP, which previously fail-closed and wrongly// reported valid:false for any key carrying an allowedIps restriction.const key = makeKey({ allowedIps: ['10.0.0.0/24'] });- expect(controller.validate(key)).toEqual({ valid: true, role: key.role });+ expect(controller.validate(key)).toEqual({ valid: true, role: key.role, engineType: 'baileys' });});it('returns valid:false when no key is attached (defense-in-depth)', () => {diff --git a/src/modules/auth/auth-validate.controller.ts b/src/modules/auth/auth-validate.controller.tsindex a8cac2139..2d355236e 100644--- a/src/modules/auth/auth-validate.controller.ts+++ b/src/modules/auth/auth-validate.controller.ts@@ -3,17 +3,20 @@ import { ApiTags, ApiOperation, ApiResponse, ApiHeader } from '@nestjs/swagger';import { CurrentApiKey } from './decorators/auth.decorators';import { ApiKey } from './entities/api-key.entity';import { ValidateApiKeyResponseDto } from './dto';+import { EngineFactory } from '../../engine/engine.factory';@ApiTags('auth')@Controller('auth')export class AuthValidateController {+ constructor(private readonly engineFactory: EngineFactory) {}+@Post('validate')@HttpCode(HttpStatus.OK)@ApiOperation({ summary: 'Validate an API key' })@ApiHeader({ name: 'X-API-Key', description: 'API key to validate' })@ApiResponse({ status: 200, description: 'API key is valid', type: ValidateApiKeyResponseDto })@ApiResponse({ status: 401, description: 'Invalid or missing API key' })- validate(@CurrentApiKey() apiKey?: ApiKey): { valid: boolean; role?: string } {+ validate(@CurrentApiKey() apiKey?: ApiKey): { valid: boolean; role?: string; engineType?: string } {// This route is behind the global API-key guard, so only a validated key reaches this handler// (a missing/invalid key 401s first). The guard has already verified the key — including its// client-IP and session-scope restrictions — and attached it to the request. Re-validating here@@ -24,6 +27,8 @@ export class AuthValidateController {if (!apiKey) {return { valid: false };}- return { valid: true, role: apiKey.role };+ // The engine rides along because GET /infra/engines/current is admin-only, and the dashboard needs+ // it for every role that can post a status or read channels.+ return { valid: true, role: apiKey.role, engineType: this.engineFactory.getCurrentEngine() };}}diff --git a/src/modules/auth/dto/api-key.dto.ts b/src/modules/auth/dto/api-key.dto.tsindex a1d0cd44d..d2266fd0e 100644--- a/src/modules/auth/dto/api-key.dto.ts+++ b/src/modules/auth/dto/api-key.dto.ts@@ -137,6 +137,12 @@ export class ValidateApiKeyResponseDto {@ApiPropertyOptional({ enum: ApiKeyRole, description: "The key's role; present only when valid." })role?: ApiKeyRole;++ @ApiPropertyOptional({+ description: 'Engine the process resolved at boot; present only when valid.',+ example: 'baileys',+ })+ engineType?: string;}export class UpdateApiKeyDto {