Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: scope the audit, allowedIps and redrive statements precisely

Yudhi Armyndharisae3416a37ae1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9dc8f5528..08e924a48 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,8 +27,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Baileys: poll votes, in-chat pins, keep-in-chat toggles, album headers, encrypted reactions and event RSVPs no longer arrive as empty `unknown` messages on the live or history path ([#1568](https://github.com/rmyndharis/OpenWA/issues/1568)). Thanks @berodcdev for the report.
- Baileys: a message received through a sender's broadcast list carries the sender as `author`.
- Baileys: round video notes arrive as `video` messages with their media, quote and mentions instead of empty `unknown` messages.
-- Baileys: a connection that drops within 5 minutes of opening keeps backing off (1 s up to 60 s) and raises `session.reconnect_loop`, instead of redialing every 1 to 2 s.
-- A session that drops shortly after reaching READY keeps backing off and raises `session.reconnect_loop` on schedule, instead of retrying at the base delay forever; the downtime in the reconnect `lastError` counts from the last READY.
+- Baileys: a connection that keeps dropping soon after it opens keeps backing off (1 s up to 60 s) and raises `session.reconnect_loop`, instead of redialing every 1 to 2 s; the count restarts once 5 minutes pass between drops.
+- A session that drops shortly after reaching READY keeps backing off and raises `session.reconnect_loop` on schedule, instead of retrying at the base delay forever.
- A session that kept failing to reconnect for about 84 hours no longer falls from the 5-minute backoff cap to a retry every 5 seconds.
- A stop that answers `502` `SESSION_STOP_INCOMPLETE` releases the session claim, so another node's takeover no longer restarts the stopped session.
- A node that adopts a session no longer marks FAILED the bulk batches it started itself while the adopted engine was still initializing.
@@ -41,7 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- On PostgreSQL, boot no longer runs FTS schema DDL when the `body_ts` column and its index already exist, so a restart no longer queues every read and write on `messages` behind the open ones.
- Two plugins with the same instance id no longer serialize each other's ingress deliveries.
- Storage file count, export and import answer `503` when `STORAGE_TYPE=s3` and the bucket is unavailable, instead of silently using the local fallback directory.
-- `POST /api/infra/import-data` retires the plugin bindings of instances the restored backup drops or disables and re-applies the restored ones, so a dropped instance no longer keeps receiving message hooks with its old endpoint and credentials.
+- `POST /api/infra/import-data` retires the plugin bindings of instances the restored backup drops or disables and re-applies the restored ones, so a dropped session-scoped instance no longer keeps receiving message hooks with its old endpoint and credentials.
- `POST /api/infra/import-data` re-keys `chat_states` rows from a backup taken before 0.23.5, so their mute, archive and pin state is read again.
- Concurrent group creates and participant adds can no longer together exceed the send-pacing cold-reachout daily allowance.
- `GET /api/sessions/:sessionId/contacts/profile-pictures` answers `409` when the engine is not ready, instead of `200` with every picture null.
@@ -76,11 +76,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Webhooks already stored with a header value outside Latin-1 keep failing until their headers are updated.
- `docker-compose.dev.yml` no longer forwards `QUEUE_ENABLED` from the host `.env`, the same as `docker-compose.yml`; turn the queue on in Dashboard > Infrastructure.
- `TRUSTED_PROXIES` and `allowedIps` entries that are not a valid IP or CIDR (a leading-zero octet, an empty or padded prefix) are ignored, with a boot warning for `TRUSTED_PROXIES`.
+- An IPv6 address or range already stored in an API key's `allowedIps` (possible only for keys created before v0.4.3) is now matched as written; before, it never matched.
+- A restore that drops a session-wide (wildcard) plugin instance leaves that instance's settings in the plugin's base config; overwrite them with `PUT /api/plugins/:id/config`.
- Status media is served with its base type only (`audio/ogg; codecs=opus` becomes `audio/ogg`), and a stored type that is not one well-formed image, video or audio type is served as `application/octet-stream`.
### Security
-- A request with a missing or unknown API key writes at most 10 audit rows per client IP per minute, and audit rows cap the stored path and user agent at 500 characters; a rejected stored key and every `403` are still recorded each time.
+- A REST or queue-dashboard request with a missing or unknown API key writes at most 10 audit rows per client IP per minute, and every audit row caps the stored path and user agent at 500 characters; on those surfaces a rejected stored key and every `403` are still recorded each time.
- A `TRUSTED_PROXIES` entry with an empty prefix (`127.0.0.1/`) trusted every IPv4 peer and is now ignored. IPv6 addresses and CIDR ranges match, and a port on an `X-Forwarded-For` hop no longer changes the resolved client IP.
- Queued, retried, inline and redriven ingress deliveries are no longer dispatched to a plugin instance disabled or deleted after the delivery arrived; a deleted instance's delivery ran with the plugin's base configuration.
- The JavaScript, Python and PHP SDKs refuse an empty, `.` or `..` id before sending, instead of sending a request that resolved to the parent route.
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 3ed1f68ab..61e4f1184 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -159,7 +159,8 @@ sub-resource, no per-entry `active` flag. Enforcement lives in two places:
### IPv6 Support
`allowedIps` accepts IPv4 addresses and IPv4 CIDR ranges only; the API rejects an IPv6 entry. An
-IPv4-mapped client address (`::ffff:203.0.113.50`) is normalized to its bare IPv4 address before
+IPv6 address or range already stored on a key created before v0.4.3, when the API started rejecting
+them, is matched as written. An IPv4-mapped client address (`::ffff:203.0.113.50`) is normalized to its bare IPv4 address before
matching. `TRUSTED_PROXIES` accepts IPv4 and IPv6 addresses and CIDR ranges (for example `fd00::/8`);
an entry that is neither is ignored, with a warning at boot. A trusted proxy that appends a port to
an `X-Forwarded-For` hop (`203.0.113.7:51000`, `[2001:db8::1]:443`) resolves to the bare address.
@@ -494,7 +495,7 @@ flowchart TB
### Security Alerts
-> **Not implemented.** There is no alerting or automatic temp-block subsystem; the table below is a design target, not shipped behavior. The signals do get recorded: rejected authentication and WebSocket rate-limit violations write persisted audit rows, and an IP-restricted key used from a disallowed IP also emits a `logger.warn`; but nothing acts on them. A REST or queue-dashboard rejection that names no stored key (missing or unknown) is capped at 10 rows per client IP per minute; a rejection of a stored key (revoked, expired, IP or session refused, insufficient role) is recorded every time. Rate-limit violations are sampled. Forward the audit log / application log to your SIEM to build these alerts.
+> **Not implemented.** There is no alerting or automatic temp-block subsystem; the table below is a design target, not shipped behavior. The signals do get recorded: rejected authentication and WebSocket rate-limit violations write persisted audit rows, and an IP-restricted key used from a disallowed IP also emits a `logger.warn`; but nothing acts on them. A REST or queue-dashboard rejection that names no stored key (missing or unknown) is capped at 10 rows per client IP per minute; a rejection of a stored key (revoked, expired, IP or session refused, insufficient role) is recorded every time there. The public `/api/health` route bounds every auth-failure row it writes, stored key or not, at 10 per client IP per minute. Rate-limit violations are sampled. Forward the audit log / application log to your SIEM to build these alerts.
| Event | Severity | Intended action (roadmap) |
| -------------------- | -------- | ------------------------- |
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 279f5c584..b07b2c585 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -598,8 +598,9 @@ CREATE INDEX "IDX_c69efb19bf127c97e6740ad530" ON audit_logs("createdAt");
**Audit actions** are an enum (`AuditAction`) spanning API-key lifecycle (`api_key_created`,
`api_key_updated`, `api_key_used`, `api_key_revoked`, `api_key_deleted`, `api_key_auth_failed`, capped
-at 10 rows per client IP per minute for a REST or queue-dashboard rejection that names no stored key;
-a rejection of a stored key is never capped), session
+at 10 rows per client IP per minute for a REST or queue-dashboard rejection that names no stored key,
+where a rejection of a stored key is recorded every time, and at 10 per client IP per minute for any
+rejection on `/api/health`), session
lifecycle (`session_created`, `session_started`, `session_stopped`, `session_force_killed`,
`session_logged_out`, `session_deleted`, `session_qr_generated`, `session_connected`,
`session_disconnected`, `session_config_updated`), WhatsApp-imposed account restrictions (`session_restricted`,
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index c1cd6d42d..2d44aa958 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5769,7 +5769,7 @@ Because that pre-flight runs _before_ the transaction, its teardown is not cover
Inside the transaction every migration table is emptied. `webhooks` and `sessions` are DELETEd directly, so a missing table there fails the restore; 13 more go through a tolerant helper where a _genuinely missing_ table is skipped; and `automation_rules` is emptied by the `DELETE FROM sessions` cascade rather than by the helper. Any other DELETE failure propagates to the rollback. Rows are then re-inserted, sessions first. JSON object/array fields are auto-stringified before insert, and the Postgres-form `$N` placeholders are rewritten for SQLite. Two guards return `imported:false` after a rollback: any `warnings`, and a payload that restores **zero** rows in total (a wrong/empty backup would otherwise commit a silent wipe — the response then carries `Backup contained no rows to restore; refused to replace existing data. Check the file.`). On commit the lid→phone mirror is reloaded from the restored rows.
-On commit, plugin instance bindings are also re-applied: a session bound only by an instance the backup lacks, or restores disabled, is dropped from that plugin's active sessions and its per-session config is cleared, then every restored enabled instance is bound again. Sessions activated through `PUT /api/plugins/:id/sessions` with no instance behind them are left alone. If that re-sync fails the import still commits, with a notice and `restartRequired: true`.
+On commit, plugin instance bindings are also re-applied: a session bound only by an instance the backup lacks, or restores disabled, is dropped from that plugin's active sessions and its per-session config is cleared, then every restored enabled instance is bound again. Sessions activated through `PUT /api/plugins/:id/sessions` with no instance behind them are left alone. If that re-sync fails the import still commits, with a notice and `restartRequired: true`. A session-wide (wildcard) instance's config was merged into the plugin's base config when it was bound, and a restore does not remove it; overwrite those keys with `PUT /api/plugins/:id/config`.
**Errors:** `400` `tables` absent/not an object, a table whose value is not an array of rows, a row that is not an object (`null`, a bare string, a nested array), a flag spelled as anything but a boolean or exact `true`/`false`, or a property the route does not accept — nothing is written, and field-level detail is suppressed in production unless `VALIDATION_ERROR_DETAIL=true` · `401` · `403` · `409` refused, with the reason in `code` — `IMPORT_WOULD_ORPHAN_ENGINES` (live engines exist for sessions the backup does not contain; retry with `stopOrphans` or `force`), `IMPORT_ALREADY_RUNNING` (another import is running; wait for it), `IMPORT_NESTED_TRANSACTION` (another database transaction holds the connection; retry with nothing else in flight) · `500` unrecoverable DB error
@@ -6228,9 +6228,9 @@ still outstanding after this batch.
**Auth:** API key (ADMIN) · **Scope:** session-scoped (a key restricted to `allowedSessions` may only
redrive an instance whose current `sessionScope` is inside that allowlist; out of scope and missing
-instances both answer `404`, so redrive can't be used to probe other sessions). A deleted or disabled
-instance answers `409` for every caller: ingress dispatch refuses such an instance, so its rows could
-only fail again. Re-enable the instance to replay its backlog.
+instances both answer `404`, so redrive can't be used to probe other sessions). An instance that is
+disabled, or deleted when the key is not session-restricted, answers `409`: ingress dispatch refuses
+such an instance, so its rows could only fail again. Re-enable the instance to replay its backlog.
**Path parameters**