Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(auth): document allowedChats on API keys
Yudhi Armyndharis63485da2bbb7
diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex f8934b3d9..353ec81a3 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -72,7 +72,7 @@ fixed `dev-admin-key`; with neither set, the seed key is generated in the format### Permission ModelAPI keys carry **no permission strings**. Authorization is a role hierarchy on the key itself, plus-two scoping dimensions enforced by `ApiKeyGuard`.+three scoping dimensions enforced by `ApiKeyGuard`.| Role | Rank | Meaning || ---------- | ---- | -------------------------------------------------------------------- |@@ -83,10 +83,11 @@ two scoping dimensions enforced by `ApiKeyGuard`.A route declares its minimum level with `@RequireRole(...)`; a key passes when its role ranks at orabove that level (`AuthService.hasPermission`). A key below it is rejected with `403 Forbidden`.-| Scope | Field | Effect |-| --------- | ----------------- | -------------------------------------------------------------------------------------------------------- |-| Source IP | `allowedIps` | Empty/absent = unrestricted; non-empty = fail-closed IP whitelist (see §4.3) |-| Sessions | `allowedSessions` | Empty/absent = every session; non-empty = a request carrying any other session id is rejected with `401` |+| Scope | Field | Effect |+| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| Source IP | `allowedIps` | Empty/absent = unrestricted; non-empty = fail-closed IP whitelist (see §4.3) |+| Sessions | `allowedSessions` | Empty/absent = every session; non-empty = a request carrying any other session id is rejected with `401` |+| Chats | `allowedChats` | Empty/absent = every chat; non-empty = default-deny: only chat-scoped routes, and only for a listed chat, else `403`; `/events`, MCP and Bull Board refuse the key |The key-lifecycle routes (`/api/auth/api-keys`) are additionally fenced with `@RequireUnscopedKey()`:a session-scoped key is refused there whatever its role, so it cannot mint or widen credentialsdiff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex d17f05632..642dcc3bb 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -253,6 +253,7 @@ erDiagramvarchar rolesimple_array allowedIpssimple_array allowedSessions+ simple_array allowedChatsboolean isActivetimestamp expiresAttimestamp lastUsedAt@@ -542,6 +543,7 @@ CREATE TABLE api_keys (role VARCHAR(20) NOT NULL DEFAULT 'operator', -- admin | operator | viewer"allowedIps" TEXT, -- simple-array (comma-joined), null = any IP"allowedSessions" TEXT, -- simple-array, null = all sessions+ "allowedChats" TEXT, -- simple-array, null = all chats"isActive" BOOLEAN NOT NULL DEFAULT 1,"expiresAt" DATETIME,"lastUsedAt" DATETIME,@@ -554,7 +556,7 @@ CREATE UNIQUE INDEX "IDX_df3b25181df0b4b59bd93f16e1" ON api_keys("keyHash");```> [!NOTE]-> Access control is **role-based** (`admin` / `operator` / `viewer`), optionally scoped by `allowedIps` and `allowedSessions`. There is no granular `permissions` string array — see [04 - Security Design](./04-security-design.md) for what each role can do.+> Access control is **role-based** (`admin` / `operator` / `viewer`), optionally scoped by `allowedIps`, `allowedSessions` and `allowedChats`. There is no granular `permissions` string array — see [04 - Security Design](./04-security-design.md) for what each role can do.---diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex e3efb7542..d96eb7720 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -47,6 +47,8 @@ API keys carry one of three roles, ordered by privilege:A key may additionally be scoped to specific sessions (`allowedSessions`) and/or source IPs (`allowedIps`). The scope/IP check runs in the guard **before** any role check, so a request outside that scope is rejected with `401` (not `403`) even if the role would otherwise allow it.+A key may also be restricted to selected chats (`allowedChats`: group `<id>@g.us`, contact `<phone>@c.us` or `<lid>@lid`, or a bare phone number, which is stored as `<phone>@c.us`). An empty or absent list leaves the key unrestricted. A chat-restricted key is **denied by default**: it may call only routes marked as chat-scoped, and every other route (webhooks, automation, status, channels, key management, and any route added later) answers `403 "API key is restricted to selected chats"` after the role check. On a chat-scoped route, every chat id the request names (a `:chatId` / `:groupId` / `:contactId` path param, `?chatId=`, a body `chatId` / `fromChatId` / `toChatId`, and each `messages[].chatId` of a bulk send) must be inside the allowlist, or the request answers `403 "API key not authorized for this chat"`; a contact entry also matches its mapped `@lid` form, and the reverse. Chat list routes return only the allowed chats. A `quotedMessageId` is refused with `403` everywhere except the reply route, which binds the quote to the chat it sends into. The surfaces outside the REST guard refuse a chat-restricted key outright: the `/events` WebSocket at the handshake and on every subscribe, every MCP tool call (`403`), and the Bull Board queue dashboard (`403`).+### API-Key LifecycleOpenWA seeds an initial admin key on first run (printed to the startup log and written to `data/.api-key`, or `/app/data/.api-key` in Docker). Use it to mint scoped, lower-privilege keys for integrations. Full key creation, listing, rotation, and revocation are documented under the auth resource in **§6.4.9 (API Keys)**.@@ -4813,13 +4815,14 @@ Create a new API key; returns the full plaintext key exactly once.**Request body** — `CreateApiKeyDto`-| Field | Type | Required | Constraints | Description |-| ----------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------- | ------------------------------------ |-| `name` | string | yes | length 3–100 | Friendly name for the key. |-| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Defaults to `operator` when omitted. |-| `allowedIps` | string[] | no | each entry a valid **IPv4** address or IPv4 CIDR `/0-32`; IPv6 rejected | IP whitelist (IPv4-only by design). |-| `allowedSessions` | string[] | no | each `@IsString` | Session IDs this key may access. |-| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Stored as a `Date`. |+| Field | Type | Required | Constraints | Description |+| ----------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |+| `name` | string | yes | length 3–100 | Friendly name for the key. |+| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Defaults to `operator` when omitted. |+| `allowedIps` | string[] | no | each entry a valid **IPv4** address or IPv4 CIDR `/0-32`; IPv6 rejected | IP whitelist (IPv4-only by design). |+| `allowedSessions` | string[] | no | each `@IsString` | Session IDs this key may access. |+| `allowedChats` | string[] | no | unique entries, each a group `<id>@g.us`, a contact `<phone>@c.us` / `<lid>@lid`, or a bare phone number | Chat IDs this key may reach (see [Roles & Authorization](#roles--authorization)). |+| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Stored as a `Date`. |```json{@@ -4867,13 +4870,14 @@ Update mutable fields of an API key. `isActive` is **not** updatable here — us**Request body** — `UpdateApiKeyDto`-| Field | Type | Required | Constraints | Description |-| ----------------- | -------------------------------------- | -------- | ------------------------ | --------------------------------------------------------- |-| `name` | string | no | length 3–100 | Applied only if truthy. |-| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Applied only if truthy. |-| `allowedIps` | string[] | no | IPv4 address / CIDR only | Applied if not `undefined` (can be set to `[]` to clear). |-| `allowedSessions` | string[] | no | each `@IsString` | Applied if not `undefined`. |-| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Applied if not `undefined`; empty/falsy clears to `null`. |+| Field | Type | Required | Constraints | Description |+| ----------------- | -------------------------------------- | -------- | ------------------------ | ------------------------------------------------------------------------- |+| `name` | string | no | length 3–100 | Applied only if truthy. |+| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Applied only if truthy. |+| `allowedIps` | string[] | no | IPv4 address / CIDR only | Applied if not `undefined` (can be set to `[]` to clear). |+| `allowedSessions` | string[] | no | each `@IsString` | Applied if not `undefined`. |+| `allowedChats` | string[] | no | same as create | Applied if not `undefined` (`[]` clears it, making the key unrestricted). |+| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Applied if not `undefined`; empty/falsy clears to `null`. |```json{