Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(audit): list all eight audit actions that are never emitted
Yudhi Armyndharis4c560414a295
diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex d2813f3b5..279f5c584 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -614,6 +614,11 @@ plugin instances (`integration_instance_created`, `integration_instance_updated``infra_restart_requested`, `infra_data_exported`, `infra_data_imported`, `infra_storage_exported`,`infra_storage_imported`).+Eight 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.+> [!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 f90b5274f..151d9c787 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -5237,20 +5237,20 @@ 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 six actions below are never emitted**: message sends and webhook deliveries are tracked in their own tables (`messages`, `webhook_delivery_failures`) — `webhook_created`/`webhook_deleted` are simply not wired yet — so filtering for `message_sent`, `message_failed`, `webhook_created`, `webhook_deleted`, `webhook_triggered` or `webhook_failed` returns zero rows by design.+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).**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**Query parameters**-| Name | Type | Required | Default | Description |-| ----------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |-| `action` | string | No | — | Filter by `AuditAction` (e.g. `api_key_created`, `session_started`, `infra_data_imported`). Message/webhook actions are never emitted (see above). |-| `severity` | `'info' \| 'warn' \| 'error'` | No | — | Filter by `AuditSeverity`. |-| `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`. |+| 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`. |+| `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`. |**Response** `200`diff --git a/src/modules/audit/audit-coverage.spec.ts b/src/modules/audit/audit-coverage.spec.tsindex c6cf9001e..177f3fbe8 100644--- a/src/modules/audit/audit-coverage.spec.ts+++ b/src/modules/audit/audit-coverage.spec.ts@@ -57,6 +57,16 @@ describe('audit action emit coverage', () => {expect(stale).toEqual([]);});+ // Filtering GET /api/audit for an unemitted action silently returns nothing, so the API docs must+ // name every one of them.+ it('docs/06 names every intentionally-unemitted action in the GET /api/audit description', () => {+ const docs = readFileSync(join(SRC_DIR, '..', 'docs', '06-api-specification.md'), 'utf8');+ const paragraph = docs.split('\n').find(line => line.startsWith('List audit-log entries, newest first.')) ?? '';+ const missing = Object.keys(INTENTIONALLY_UNEMITTED_ACTIONS).filter(value => !paragraph.includes(`\`${value}\``));+ expect(paragraph).not.toBe('');+ expect(missing).toEqual([]);+ });+it('intentionally-unemitted registry entries each carry a non-empty reason', () => {const empties = Object.entries(INTENTIONALLY_UNEMITTED_ACTIONS).filter(([, reason]) => typeof reason !== 'string' || reason.trim().length === 0)