Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(audit): list what the log records and that error is reserved
Yudhi Armyndhariscdac70111ab4
diff --git a/README.md b/README.mdindex ac6a47815..b9f36082f 100644--- a/README.md+++ b/README.md@@ -157,7 +157,7 @@ For any deployment where ethical, legal, or regulatory compliance matters (healt| Rate Limiting | ✅ | Configurable request limits || CIDR Whitelisting | ✅ | IP-based access control || Chat Scoping | ✅ | Per-key `allowedChats` allowlist (groups and contacts): a key reaches only those chats, and routes not marked safe for it refuse it |-| Audit Logging | ✅ | Audit trail for API-key, session, integration-instance, and infra admin operations (message sends and webhook deliveries are tracked in their own tables, not the audit log) |+| Audit Logging | ✅ | Audit trail for API-key, session, integration-instance, plugin and infra admin operations (message sends and webhook deliveries have tables of their own, not the audit log) |### Infrastructurediff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex 4c2d10bf8..a4ab1b5ee 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -607,7 +607,7 @@ CREATE UNIQUE INDEX "IDX_api_keys_keyHash" ON api_keys("keyHash");### 5.3.6 audit_logs-Consolidated audit trail for API-key, session, send-pacing, rate-limit, queue-dashboard, integration-instance and infrastructure events. This is the **only** audit table — there are no separate `session_logs`, `webhook_logs`, or `api_key_logs` tables. Lives on the **main** (always-SQLite) connection.+Consolidated audit trail for API-key, session, send-pacing, rate-limit, queue-dashboard, integration-instance, plugin-management and infrastructure events. This is the **only** audit table — there are no separate `session_logs`, `webhook_logs`, or `api_key_logs` tables. Lives on the **main** (always-SQLite) connection.```sqlCREATE TABLE audit_logs (@@ -667,7 +667,7 @@ id, version, the host of the requested download URL and config field names, neveEight of these are reserved and never emitted, so no row ever carries them: `api_key_used`,`session_connected`, `message_sent`, `message_failed`, `webhook_created`, `webhook_deleted`,`webhook_triggered` and `webhook_failed`. `src/modules/audit/intentionally-unemitted-actions.ts` is the-authoritative list, with the reason for each.+authoritative list, with the reason for each. The `error` severity is reserved too: nothing writes it, so every row carries `info` or `warn`, and `GET /api/audit?severity=error` returns zero rows.> [!NOTE]> Audit-log retention is automatic: see [§5.7 Data Retention](#57-data-retention). Other event types (session logs, API access logs) are surfaced via structured application logging, not dedicated database tables. The one exception is a webhook delivery that exhausts every retry — that lands in the `webhook_delivery_failures` table (§5.3.8), not just the log stream.diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 434272db3..1ff2aad74 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -5424,7 +5424,7 @@ Notes: raw return of an in-memory `Settings` object built once in the controller#### GET /api/audit-List audit-log entries, newest first. API-key lifecycle changes, session lifecycle events and ADMIN infra operations land here. **The eight actions below are never emitted**, so filtering for any of them returns zero rows by design: `message_sent` and `message_failed` (every send and its outcome is in the `messages` table), `webhook_triggered` and `webhook_failed` (tracked in `webhook_delivery_failures` and the `openwa_webhook_delivery_failures_total` counter), `webhook_created` and `webhook_deleted` (not wired yet), `api_key_used` (it would fire on every authenticated request; failed authentication is audited as `api_key_auth_failed`), and `session_connected` (an engine-level transition already reflected in `sessions.status`; the user-initiated `session_started` and `session_stopped` are audited).+List audit-log entries, newest first. API-key lifecycle changes, session lifecycle events, send-pacing and rate-limit enforcement, queue-dashboard mutations, webhook delivery redrives, integration-instance changes, plugin management (install, update, uninstall, enable, disable, configuration, session activation) and ADMIN infra operations land here. **The eight actions below are never emitted**, so filtering for any of them returns zero rows by design: `message_sent` and `message_failed` (every send and its outcome is in the `messages` table), `webhook_triggered` and `webhook_failed` (tracked in `webhook_delivery_failures` and the `openwa_webhook_delivery_failures_total` counter), `webhook_created` and `webhook_deleted` (not wired yet), `api_key_used` (it would fire on every authenticated request; failed authentication is audited as `api_key_auth_failed`), and `session_connected` (an engine-level transition already reflected in `sessions.status`; the user-initiated `session_started` and `session_stopped` are audited).**Auth:** API key (ADMIN) · **Scope:** rows are confined to the calling key's `allowedSessions` — the `sessionId` query may only narrow within that list, never widen it@@ -5433,11 +5433,11 @@ List audit-log entries, newest first. API-key lifecycle changes, session lifecyc| Name | Type | Required | Default | Description || ----------- | ----------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `action` | string | No | — | Filter by `AuditAction` (e.g. `api_key_created`, `session_started`, `infra_data_imported`). Message, webhook, `api_key_used` and `session_connected` actions are never emitted (see above). |-| `severity` | `'info' \| 'warn' \| 'error'` | No | — | Filter by `AuditSeverity`. |+| `severity` | `'info' \| 'warn' \| 'error'` | No | — | Filter by `AuditSeverity`. `error` is reserved and nothing writes it (rows are `info` or `warn`), so that filter returns zero rows. || `sessionId` | string | No | — | Narrow to one session. A value outside the key's `allowedSessions` returns `{ "data": [], "total": 0 }`. || `apiKeyId` | string | No | — | Filter by the acting key's id. || `limit` | integer | No | `50` | Page size, clamped to a maximum of `200`. |-| `offset` | integer | No | `0` | Rows to skip; a negative value resolves to `0`. |+| `offset` | integer | No | `0` | Rows to skip; a negative value resolves to `0`, and a value above `9007199254740991` is capped at it, which returns an empty page. |**Response** `200`diff --git a/openapi.json b/openapi.jsonindex 367fec9e9..71e4baeae 100644--- a/openapi.json+++ b/openapi.json@@ -41,6 +41,7 @@"name": "severity","required": false,"in": "query",+ "description": "`error` is reserved: nothing writes it, so that filter returns no rows.","schema": {"enum": ["info",diff --git a/src/modules/audit/audit.controller.ts b/src/modules/audit/audit.controller.tsindex 635b2e55f..40b1719b1 100644--- a/src/modules/audit/audit.controller.ts+++ b/src/modules/audit/audit.controller.ts@@ -15,7 +15,12 @@ export class AuditController {@RequireRole(ApiKeyRole.ADMIN)@ApiOperation({ summary: 'List audit logs with optional filters' })@ApiQuery({ name: 'action', required: false, enum: AuditAction })- @ApiQuery({ name: 'severity', required: false, enum: AuditSeverity })+ @ApiQuery({+ name: 'severity',+ required: false,+ enum: AuditSeverity,+ description: '`error` is reserved: nothing writes it, so that filter returns no rows.',+ })@ApiQuery({ name: 'sessionId', required: false })@ApiQuery({ name: 'apiKeyId', required: false })@ApiQuery({ name: 'limit', required: false, type: Number })