Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: note the allowedChats refusal on key routes and in eviction
Yudhi Armyndharis6a14a5613843
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex c6ef8707a..5311f789f 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -4743,7 +4743,7 @@ No content (empty body; explicit `@HttpCode(204)`).### 6.4.9 API Keys-API keys are managed under `/api/auth/api-keys`. All management routes (create/list/get/update/delete/revoke) require an **ADMIN** key **with no session scope**: the controller is fenced with `@RequireUnscopedKey`, so a key whose `allowedSessions` is non-empty is rejected with `403` whatever its role — otherwise a confined admin key could mint an unrestricted one. The guard evaluates the role requirement _before_ that fence, so a scoped VIEWER/OPERATOR key is refused with `Insufficient permissions. Required: admin`; only a scoped ADMIN key reaches the fence and sees `Session-scoped API keys are not permitted on this route`. Both are `403`. The plaintext key string is returned **only once**, at creation. Validation of the caller's own key lives at `POST /api/auth/validate` (a separate controller, not fenced) and accepts any valid key.+API keys are managed under `/api/auth/api-keys`. All management routes (create/list/get/update/delete/revoke) require an **ADMIN** key **with no session scope**: the controller is fenced with `@RequireUnscopedKey`, so a key whose `allowedSessions` is non-empty is rejected with `403` whatever its role — otherwise a confined admin key could mint an unrestricted one. The guard evaluates the role requirement _before_ that fence, so a scoped VIEWER/OPERATOR key is refused with `Insufficient permissions. Required: admin`; only a scoped ADMIN key reaches the fence and sees `Session-scoped API keys are not permitted on this route`. Both are `403`. A key restricted with `allowedChats` that passes the role check is refused next, before the session fence, with `403 "API key is restricted to selected chats"`: no management route is open to a chat-scoped key. The plaintext key string is returned **only once**, at creation. Validation of the caller's own key lives at `POST /api/auth/validate` (a separate controller, not fenced) and accepts any valid key except one restricted with `allowedChats`, which it refuses with `403` like every route not open to a chat-scoped key.#### GET /api/auth/api-keys@@ -4773,7 +4773,7 @@ Bare JSON array (no envelope), ordered by `createdAt` DESC. Null array/date fiel]```-**Errors:** `401` missing/invalid `X-API-Key` · `403` key role below ADMIN, or the key is session-scoped+**Errors:** `401` missing/invalid `X-API-Key` · `403` key role below ADMIN, or the key is session-scoped or restricted with `allowedChats`#### GET /api/auth/api-keys/:id@@ -4805,7 +4805,7 @@ Get a single API key's details by id. No plaintext key.}```-**Errors:** `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped · `404` `"API key with id '<id>' not found"`+**Errors:** `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped or restricted with `allowedChats` · `404` `"API key with id '<id>' not found"`#### POST /api/auth/api-keys@@ -4854,7 +4854,7 @@ Same shape as the read DTO **plus** an `apiKey` field carrying the full plaintex}```-**Errors:** `400` validation (bad `name` length, invalid `role` enum, non-IPv4 `allowedIps` entry, bad `expiresAt`, or any non-whitelisted body field) · `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped+**Errors:** `400` validation (bad `name` length, invalid `role` enum, non-IPv4 `allowedIps` entry, bad `expiresAt`, or any non-whitelisted body field) · `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped or restricted with `allowedChats`#### PUT /api/auth/api-keys/:id@@ -4906,7 +4906,7 @@ Returns the updated key (no plaintext).}```-**Errors:** `400` validation (incl. `forbidNonWhitelisted` for unknown fields such as `isActive`) · `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped · `404` not found · `409` change would remove the last usable admin key+**Errors:** `400` validation (incl. `forbidNonWhitelisted` for unknown fields such as `isActive`) · `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped or restricted with `allowedChats` · `404` not found · `409` change would remove the last usable admin key#### POST /api/auth/api-keys/:id/revoke@@ -4936,7 +4936,7 @@ Sets `isActive` to `false` and returns the key with explicit HTTP `200`. After r}```-**Errors:** `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped · `404` not found · `409` target is the last usable admin key+**Errors:** `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped or restricted with `allowedChats` · `404` not found · `409` target is the last usable admin key#### DELETE /api/auth/api-keys/:id@@ -4954,7 +4954,7 @@ Permanently delete an API key (hard delete). Also drops any un-flushed usage acc`@HttpCode(204)` — no response body.-**Errors:** `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped · `404` `"API key with id '<id>' not found"` · `409` target is the last usable admin key+**Errors:** `401` missing/invalid key · `403` key role below ADMIN, or the key is session-scoped or restricted with `allowedChats` · `404` `"API key with id '<id>' not found"` · `409` target is the last usable admin key#### POST /api/auth/validate@@ -4962,7 +4962,7 @@ Validate the supplied `X-API-Key` and report its validity and role.**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.+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.**Response** `200`@@ -4970,7 +4970,7 @@ The key is read from the `X-API-Key` header, not the body; send an empty body. T{ "valid": true, "role": "operator" }```-**Errors:** `401` missing/invalid/revoked/expired key (raised by the global guard before the handler)+**Errors:** `401` missing/invalid/revoked/expired key (raised by the global guard before the handler); `403` a key restricted with `allowedChats`> Implemented by `AuthValidateController` (`@Controller('auth')`), sharing the same `/api/auth` base.@@ -6907,7 +6907,7 @@ A subscribe request whose `events` array contains no recognized name (after filt- **`sessionId: "*"`** subscribes to every session; **`events: ["*"]`** subscribes to every subscribable event. They combine (e.g. `"*"` + `["*"]` = every event of every session).- The API key is **re-validated on every `subscribe`** (not just at connect), so a key revoked or expired mid-connection is caught — the server replies `UNAUTHORIZED` and disconnects.- **Per-key session scope is enforced** against the fresh key: a key restricted via `allowedSessions` may NOT subscribe to `"*"` and may NOT subscribe to a session outside its allowlist — either is rejected with `FORBIDDEN_SESSION`. An unrestricted key (no `allowedSessions`) may subscribe to anything, including `"*"`.-- **Live sockets are re-validated against the database once a minute**, with no client activity required. A socket carries the key as it stood when it connected, and rooms joined earlier are never revisited, so that snapshot is what the sweep compares against the current row, along with any later `subscribe` whose key no longer matched it (what that `subscribe` granted outlives the change, so putting the row back does not spare the socket). It closes the key's sockets with an `UNAUTHORIZED` frame naming the cause: `API key has been deleted`, `API key has been revoked`, `API key has expired`, or `API key authorization changed; please reconnect` when `role`, `allowedIps`, `allowedSessions` or `expiresAt` moved. A change made through this API still evicts synchronously in the same request; the sweep is what catches a change made on another node, written straight to the database, or committed in the instant a socket was connecting. A rename, and the usage counters the gateway itself writes, evict nobody. Treat these frames as "reconnect and resubscribe", not as fatal.+- **Live sockets are re-validated against the database once a minute**, with no client activity required. A socket carries the key as it stood when it connected, and rooms joined earlier are never revisited, so that snapshot is what the sweep compares against the current row, along with any later `subscribe` whose key no longer matched it (what that `subscribe` granted outlives the change, so putting the row back does not spare the socket). It closes the key's sockets with an `UNAUTHORIZED` frame naming the cause: `API key has been deleted`, `API key has been revoked`, `API key has expired`, or `API key authorization changed; please reconnect` when `role`, `allowedIps`, `allowedSessions`, `allowedChats` or `expiresAt` moved. A change made through this API still evicts synchronously in the same request; the sweep is what catches a change made on another node, written straight to the database, or committed in the instant a socket was connecting. A rename, and the usage counters the gateway itself writes, evict nobody. Treat these frames as "reconnect and resubscribe", not as fatal.- **`session.qr` requires the OPERATOR role**, matching `GET /api/sessions/{sessionId}/qr`. A VIEWER key may still subscribe to it, by name or through a wildcard, but the QR is never delivered to its sockets; every other event is. The role is read from the key re-validated on each `subscribe`, so a key narrowed to VIEWER stops receiving the QR from its next `subscribe`. Between subscribes the QR gate rests on the same snapshot as every other event: a key demoted right after a `subscribe` keeps receiving the QR until its sockets are evicted, which is immediate on the node processing the change and within the sweep's minute anywhere else.### Example (socket.io-client)diff --git a/docs/07-api-collection.md b/docs/07-api-collection.mdindex e2a5fb886..260f38b92 100644--- a/docs/07-api-collection.md+++ b/docs/07-api-collection.md@@ -1205,7 +1205,7 @@ curl -X DELETE "$BASE/api/sessions/$SESSION_ID/webhooks/f1e2d3c4-b5a6-7890-1234-### 07.11 API Keys-All `/api/auth/api-keys` routes require an **ADMIN** key. `POST /api/auth/validate` accepts any valid key. The plaintext key is returned only by the create call.+All `/api/auth/api-keys` routes require an unscoped **ADMIN** key: one with `allowedSessions` or `allowedChats` set is refused with `403`. `POST /api/auth/validate` accepts any valid key except one restricted with `allowedChats`, which gets `403`. The plaintext key is returned only by the create call.#### GET /api/auth/api-keysdiff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.mdindex 55c597f94..4f2071194 100644--- a/docs/13-horizontal-scaling.md+++ b/docs/13-horizontal-scaling.md@@ -108,7 +108,7 @@> Nothing is published to peers; instead every node re-validates the keys behind its own live> sockets against the database once a minute (`EventsGateway.sweepApiKeyAuthorization`, one batched> read of the key ids currently holding sockets) and evicts on a row that is gone, inactive, expired,-> or whose role, `allowedIps`, `allowedSessions` or expiry no longer matches the snapshot the socket+> or whose role, `allowedIps`, `allowedSessions`, `allowedChats` or expiry no longer matches the snapshot the socket> authenticated with. So a peer node's sockets close within a minute of the change. Before, a revoke,> delete or expiry there waited for the client's next subscribe, and a narrowing was never caught at> all: it leaves the key valid, so only the new subscribe is rejected while every room joined earlierdiff --git a/src/modules/auth/auth.service.ts b/src/modules/auth/auth.service.tsindex a4d18ff0a..8af5e0784 100644--- a/src/modules/auth/auth.service.ts+++ b/src/modules/auth/auth.service.ts@@ -226,7 +226,7 @@ export class AuthService implements OnModuleInit, OnModuleDestroy {(normalizeChatAllowList(dto.allowedChats)?.length ?? 0) > 0;// Capture the authorization-relevant fields BEFORE applying the change. Only a change to role,- // allowedIps, allowedSessions, or expiry can widen or restrict what an already-connected WebSocket+ // allowedIps, allowedSessions, allowedChats, or expiry can widen or restrict what an already-connected WebSocket// socket may see, so only those trigger eviction of live /events sockets — a benign rename must// NOT disconnect clients. REST enforces the new state immediately; without eviction a live socket// keeps streaming events for sessions/IPs the key just lost until it resubscribes or drops.diff --git a/src/modules/events/events.gateway.ts b/src/modules/events/events.gateway.tsindex b145b9882..39938e7ad 100644--- a/src/modules/events/events.gateway.ts+++ b/src/modules/events/events.gateway.ts@@ -286,7 +286,7 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGate/*** Tear down every active socket authenticated with `keyId`. Called by AuthService when a key is- * revoked, deleted, or has its authorization (role/allowedSessions/allowedIps/expiry) narrowed, and+ * revoked, deleted, or has its authorization (role/allowedSessions/allowedChats/allowedIps/expiry) narrowed, and* by sweepApiKeyAuthorization for the same changes when they only reach this process through the* database, so the key's already-subscribed sockets stop receiving events immediately instead of* lingering until they disconnect on their own. Each socket gets a clean close (an `UNAUTHORIZED`