Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: correct the operations, security and contributor notes

Yudhi Armyndharis3f9032ca7b1f
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 81f8a7687..ff61f004d 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -159,7 +159,8 @@ updates:
# The other SDKs ship runtime dependencies to their consumers (httpx, guzzle, gson), and their
# published ranges admit whatever is current, so an advisory in one of them is a PR here, not a
# surprise in a user's lockfile. These PRs touch sdk/**, so SDK CI gates each one. The Go client
- # depends on the standard library alone; its entry watches the toolchain directive.
+ # depends on the standard library alone and its go.mod has no require, so its entry keeps the
+ # one-entry-per-SDK rule and starts proposing updates once a dependency is added.
- package-ecosystem: pip
directory: /sdk/python
schedule:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bb49da59c..baa622948 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -60,7 +60,11 @@ npm run i18n:check && npm run build && npm run test:unit
If you changed a DTO, a route, or an `@ApiResponse`, also run `npm run openapi:export` and
commit the snapshot, then `npm run openapi:check` and `npm run check:contract-shapes`. The
-hand-written SDK types are compared against the schemas and will fail CI by field name.
+hand-written SDK types are compared against the schemas and will fail CI by field name. A new
+route also needs a method in each of the five SDKs and a row in `docs/18-sdk-design.md`, or an
+entry in the unexposed list of `sdk/README.md`, which `npm run check:sdk-routes`,
+`check:sdk-coverage`, `check:sdk-events` and `check:sdk-docs` verify, as CI's lint job does
+with `npm run check:versions`.
- Add or update tests for behavior changes. Backend specs are colocated as `*.spec.ts`
and run under Jest; dashboard tests are colocated as `*.test.ts` and run under
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 716ddfe02..f7e88c9f8 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -83,15 +83,17 @@ three scoping dimensions enforced by `ApiKeyGuard`.
A route declares its minimum level with `@RequireRole(...)`; a key passes when its role ranks at or
above 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 `403` |
-| Chats | `allowedChats` | Empty/absent = every chat; non-empty = default-deny: only chat-scoped routes, MCP tools and events, only for a listed chat, else `403` (an event outside the list is never delivered); Bull Board refuses it |
+| 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 session named in the route path outside the list is rejected with `403`, and a `sessionId` filter in the query or body is narrowed to the list (an empty result, `200`) |
+| Chats | `allowedChats` | Empty/absent = every chat; non-empty = default-deny: only chat-scoped routes, MCP tools and events, only for a listed chat, else `403` (an event outside the list is never delivered); Bull Board refuses it |
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 credentials
-beyond its own confinement.
+beyond its own confinement. The same fence covers the other routes that act on the whole deployment:
+every `/api/infra` route, the plugin routes (except the per-session config override), `GET /api/settings`,
+`GET /api/stats/overview` and `/messages`, `POST /api/sessions` and the proxy setter. `SECURITY.md` lists them.
A session's egress proxy (`proxyUrl` on `POST /api/sessions`, `PATCH /api/sessions/:sessionId/proxy`)
is set only by an unscoped `admin` key; any other key gets `403`. The proxy is trusted egress chosen by
@@ -654,7 +656,7 @@ flowchart TB
| Plugin instance secrets (`plugin_instances.secret`, `verifyToken`, `config`) | Database: **plaintext**; `secret`, `verifyToken` and secret-marked config are masked on API reads, but `GET /api/infra/export-data` includes them verbatim | Per instance (regenerate-secret) |
| Session auth state | File system (data volume) — **not encrypted** | Never (tied to the WA session) |
-> `API_MASTER_KEY` only seeds the first ADMIN key, and is read only while the key table is empty. Changing it later has no effect: the new value never authenticates and the seeded key stays valid. Rotate by minting a new ADMIN key with `POST /api/auth/api-keys` and revoking the seeded `Default Admin Key`.
+> `API_MASTER_KEY` only seeds the first ADMIN key, and is read only while the key table is empty. Changing it later has no effect: the new value never authenticates and the seeded key stays valid. A value that is set must still be at least 32 characters and not a known default on every production boot, or the boot refuses to start; unset it after rotating. Rotate by minting a new ADMIN key with `POST /api/auth/api-keys` and revoking the seeded `Default Admin Key`.
> There is no application `ENCRYPTION_KEY` — OpenWA does not encrypt data at rest (see §4.4). The rotation cadences above are operational recommendations, not enforced by the app.
@@ -777,7 +779,7 @@ npm audit --json > audit-report.json
```yaml
# .github/dependabot.yml, root npm ecosystem only (the file also covers /dashboard,
-# /sdk/javascript, github-actions, docker and docker-compose). The comment above each
+# /sdk/javascript, /sdk/python, /sdk/java, /sdk/php, /sdk/go, github-actions, docker and docker-compose). The comment above each
# ignore is omitted here.
version: 2
updates:
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index 8dc66426a..d25f1f715 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -204,7 +204,7 @@ Every timestamp column on the PostgreSQL data connection is `timestamp without t
Three `@CreateDateColumn`/`@UpdateDateColumn` columns are filled by the app rather than by that default: `lid_mappings.updatedAt`, `chat_states.updatedAt` and `baileys_stored_messages.createdAt` reach the database through an `upsert` that passes the value, so the default behind them never fires and they follow the binding rule above instead of the session zone.
-`messages.createdAt` is a fourth, and split within itself: a live message takes the server default, while a row written by the Baileys history backfill carries the message's own time, stamped in `message-history-projector.ts` so the chat panel orders history correctly. Both conventions are UTC from this release on, and the two cannot be told apart row by row, which is why the upgrade notes exclude that column from any blanket conversion. A restore writes `createdAt`/`updatedAt` explicitly wherever the archive carries them, so a restored table follows the archive rather than either rule above; the upgrade notes cover that case separately.
+`messages.createdAt` is a fourth, and split within itself: a live message takes the server default, while a row written by the Baileys history backfill carries the message's own time, stamped in `message-history-projector.ts` so the chat panel orders history correctly. Both conventions are UTC since 0.23.6, and the two cannot be told apart row by row, which is why the 0.23.6 upgrade notes exclude that column from any blanket conversion. A restore writes `createdAt`/`updatedAt` explicitly wherever the archive carries them, so a restored table follows the archive rather than either rule above; the 0.23.6 upgrade notes cover that case separately.
Comparisons therefore mean the same thing on both dialects: a retention `LessThan(cutoff)`, a lease deadline written by another node, and a backup restored from any host all line up. SQLite is unaffected; it already stores ISO text in UTC.
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.md
index 8ae55592f..785f1a88a 100644
--- a/docs/10-devops-infrastructure.md
+++ b/docs/10-devops-infrastructure.md
@@ -381,7 +381,7 @@ LOG_FORMAT=json
# DATABASE_NAME=openwa
# DATABASE_USERNAME=user
# DATABASE_PASSWORD=pass
-# DATABASE_POOL_SIZE=20
+# DATABASE_POOL_SIZE=10
# DATABASE_SSL=false
# ===========================================
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index f23a5e95d..ff00c8a4a 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -434,7 +434,8 @@ docker stats --no-stream
# copied live; stop the sessions first if a restore must not need re-pairing, and start them
# again in step 10
docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh
-docker cp openwa-api:/app/data/backups/. ./backups/
+docker cp openwa-api:/app/data/backups/. ./backups/ \
+ && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz' # the copy off the volume is the backup
# Verify backup (backup.sh writes $BACKUP_DIR/openwa-backup-<timestamp>.tar.gz,
# BACKUP_DIR defaults to ./backups — it creates no dated subdirectories)
@@ -520,7 +521,8 @@ curl -H "X-API-Key: $API_KEY" \
export BACKUP_DIR="/backups/openwa"
mkdir -p "$BACKUP_DIR"
docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh
-docker cp openwa-api:/app/data/backups/. "$BACKUP_DIR"/
+docker cp openwa-api:/app/data/backups/. "$BACKUP_DIR"/ \
+ && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz' # the copy off the volume is the backup
# 3. Export the Data DB as JSON alongside the archive (admin key)
curl -H "X-API-Key: $ADMIN_API_KEY" \
@@ -781,9 +783,11 @@ OPENWA_DATA_DIR=/srv/openwa/data \
>
> ```bash
> docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh
-> docker cp openwa-api:/app/data/backups/. ./backups/
+> docker cp openwa-api:/app/data/backups/. ./backups/ \
+> && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz' # do not let archives pile up on the volume
> # Helm: kubectl exec <pod> -- env BACKUP_DIR=/app/data/backups ./scripts/backup.sh
> # kubectl cp <pod>:/app/data/backups ./backups
+> # kubectl exec <pod> -- sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz'
> ```
>
> The script stages a full copy of the data in `TMPDIR` before archiving it. The compose file mounts
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 53d398649..234e0c19c 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -1143,7 +1143,7 @@ flowchart TD
**Solutions:**
```bash
-# Show migration status (executed + pending)
+# From a source checkout: show migration status (executed + pending)
npm run migration:show
# Run all pending migrations
@@ -1152,13 +1152,17 @@ npm run migration:run
# Rollback last migration
npm run migration:revert
+# Inside the released image, which has no ts-node, use the :prod variants against dist/
+docker compose run --rm openwa-api npm run migration:show:prod
+docker compose run --rm openwa-api npm run migration:run:prod
+
# Schema is managed by migrations (there is no schema:sync)
# The auth/audit DB has parallel :main variants, e.g.:
npm run migration:run:main
npm run migration:run:main:prod # inside the released image
```
-**PostgreSQL crash-loop on boot after upgrade** — if logs show `column "id" is of type uuid but default expression is of type character varying` or `foreign key constraint ... cannot be implemented ... incompatible types: character varying and uuid`, the deployment was previously bootstrapped with `DATABASE_SYNCHRONIZE=true` (native `uuid` columns vs the migrations' `varchar`). A guard migration converts the columns automatically on the next boot; for large `messages` tables, run the migration against the stopped app (`npm run migration:run`) during a maintenance window. See [14.5 / 14.9 — PostgreSQL crash-loop after upgrading a `DATABASE_SYNCHRONIZE=true` deployment](./14-migration-guide.md). `DATABASE_SYNCHRONIZE=true` is unsupported on PostgreSQL for production.
+**PostgreSQL crash-loop on boot after upgrade** — if logs show `column "id" is of type uuid but default expression is of type character varying` or `foreign key constraint ... cannot be implemented ... incompatible types: character varying and uuid`, the deployment was previously bootstrapped with `DATABASE_SYNCHRONIZE=true` (native `uuid` columns vs the migrations' `varchar`). A guard migration converts the columns automatically on the next boot; for large `messages` tables, run the migration against the stopped app (`npm run migration:run` from a source checkout, `npm run migration:run:prod` in the image) during a maintenance window. See [14.5 / 14.9 — PostgreSQL crash-loop after upgrading a `DATABASE_SYNCHRONIZE=true` deployment](./14-migration-guide.md). `DATABASE_SYNCHRONIZE=true` is unsupported on PostgreSQL for production.
## 12.7 Docker Issues
@@ -1414,15 +1418,16 @@ Remember OpenWA is **single-port**: the Dashboard, REST API, and Socket.IO all s
```bash
# Production compose, whose data is the openwa-data volume: back up inside the container, then copy
# the archive off the volume. In crontab, for example every six hours:
-# 0 */6 * * * docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh && docker cp openwa-api:/app/data/backups/. /backups/openwa/
+# 0 */6 * * * docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh && docker cp openwa-api:/app/data/backups/. /backups/openwa/ && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz'
docker exec -e BACKUP_DIR=/app/data/backups -e TMPDIR=/app/data/backups openwa-api ./scripts/backup.sh
-docker cp openwa-api:/app/data/backups/. /backups/openwa/
+docker cp openwa-api:/app/data/backups/. /backups/openwa/ \
+ && docker exec openwa-api sh -c 'rm -f /app/data/backups/openwa-backup-*.tar.gz'
# Bare metal or docker-compose.dev.yml, whose data is ./data in the checkout:
# 0 */6 * * * cd /path/to/openwa && BACKUP_DIR=/backups/openwa ./scripts/backup.sh
```
-The archives stay in `/app/data/backups` on the volume as well, so prune them there too.
+Once an archive is copied off, the last command removes it from `/app/data/backups`, so archives do not pile up on the volume.
The shipped script also covers `main.sqlite`, the selected data store, whatsapp-web.js state,
`BAILEYS_AUTH_DIR` (default `./data/baileys`), media, plugin packages/state, and generated secrets. Apply
diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.md
index 91877ea3b..f25571ec0 100644
--- a/docs/13-horizontal-scaling.md
+++ b/docs/13-horizontal-scaling.md
@@ -571,6 +571,9 @@ metadata:
nginx.ingress.kubernetes.io/affinity: 'cookie'
nginx.ingress.kubernetes.io/session-cookie-name: 'openwa-session'
nginx.ingress.kubernetes.io/session-cookie-max-age: '172800'
+ # ingress-nginx refuses a request body over 1m by default, which base64 media sends exceed.
+ # Keep this at or above BODY_SIZE_LIMIT (25mb by default).
+ nginx.ingress.kubernetes.io/proxy-body-size: '25m'
spec:
ingressClassName: nginx
rules:
@@ -597,6 +600,9 @@ already encodes the `replicaCount: 1` constraint below; prefer it over hand-appl
raw manifests here stay for operators who do not use Helm.
```bash
+# Apply the namespace first: a directory is applied in file-name order, and the other files name it
+kubectl apply -f k8s/namespace.yaml
+
# Apply all manifests
kubectl apply -f k8s/
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 07b870a67..a660557f8 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -887,15 +887,16 @@ skips: check `pg_index.indisvalid` and drop the invalid index before building it
| Release | Change | Action |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0.25.0` | Once teardown begins (SIGTERM, SIGINT, `POST /api/infra/restart`) every request except `/api/health`, `/api/health/*`, the dashboard's HTML pages and CORS preflights answers `503` with `Connection: close`, `GET /api/infra/health` included | Probe `/api/health/live` for liveness that survives teardown, and retry a `503` once the instance is up again |
-| `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts |
+| `0.25.0` | `stop_grace_period` (Docker) and `terminationGracePeriodSeconds` (Kubernetes) go from 45 to 75 s, and a stop that runs 67 s past the shutdown delay exits with status 1 instead of 137 | Raise a pinned 45 s value to at least 75 s, plus the excess of `SHUTDOWN_DELAY_MS` over 3 s and of `WEBHOOK_SHUTDOWN_DRAIN_MS` over 5 s; a container that drops all capabilities and starts as root must add `KILL` to the capabilities 0.24.0 shipped, or a stop never reaches the app; update exit-code alerts |
| `0.25.0` | `400` instead of `201` or `200` for a phone number WhatsApp reports as unregistered (Baileys; `503` when the lookup gets no answer) and for `vote-poll` with no matching option text (whatsapp-web.js) | Handle `400` (`POLL_OPTION_NOT_FOUND` carries `validOptions`) and `503` on these routes; an empty `options` list still clears a vote |
-| `0.25.0` | `400` for an `allowedChats` list over 2000 entries, `GET /api/search` with `q` over 1000 characters or 32 words, an animated image over 500 frames, and an `image/svg+xml` sticker, profile picture or group picture | Shorten the list or the query, send an animated image as WebP, and convert SVG to PNG or WebP before sending |
-| `0.25.0` | `PUT /api/infra/config` answers `400` for a database or Redis port outside 1-65535 and a negative or fractional pool size | Fix the value in the request; it used to be stored and the next boot refused it |
+| `0.25.0` | `400` for an `allowedChats` list over 2000 entries and for `GET /api/search` with `q` over 1000 characters or 32 words; on Baileys also for a sticker it converts to WebP with over 500 frames, and for an `image/svg+xml` sticker, profile picture or group picture | Shorten the list or the query; on Baileys keep an animated sticker to 500 frames and convert SVG to PNG or WebP before sending |
+| `0.25.0` | On SQLite, `GET /api/search` leaves `score` out of the hits of a key restricted to sessions or chats, because it is computed over the whole index; the hits stay in relevance order | Read `hit.score` as optional |
+| `0.25.0` | `PUT /api/infra/config` answers `400` for a database or Redis port outside 1-65535, a negative or fractional pool size and a local storage path the app cannot create or write | Fix the value in the request; it used to be stored and the next boot refused it |
| `0.25.0` | Boot fails on a `PORT` with surrounding whitespace and on a `WEBHOOK_SHUTDOWN_DRAIN_MS` that is not a non-negative integer (for example `30s`) | Remove the padding or the unit |
| `0.25.0` | New Baileys pairings show `Ubuntu` as the linked-device name | Set `BAILEYS_BROWSER_NAME=OpenWA` to keep the old name; linked sessions are unaffected |
| `0.25.0` | `backup.sh` and `restore.sh` exit with status 2 on an unparsable or unreadable `./.env` or `.env.generated`, read the default SQLite paths under `OPENWA_DATA_DIR`, and with `DATABASE_SSL=true` verify the PostgreSQL certificate as the app does | Fix the line or the permissions, or pass the key in the environment; trust a private CA through `NODE_EXTRA_CA_CERTS` or `PGSSLROOTCERT` |
| `0.25.0` | With `DATABASE_SSL=true` the PostgreSQL certificate is verified against `DATABASE_HOST` even when it is an IP address | Use the certificate's DNS name as the host or add the IP to its subject alternative names; `DATABASE_SSL_REJECT_UNAUTHORIZED=false` remains the escape hatch |
-| `0.25.0` | The first boot builds three indexes on `messages` without `CONCURRENTLY` (about 240 MB per million messages; on PostgreSQL writes wait), and the Helm startup probe restarts a pod whose boot outlasts about 295 s | On a large table run the migrations first (section 14.5), or raise `startupProbe.failureThreshold` |
+| `0.25.0` | The first boot builds three indexes on `messages` without `CONCURRENTLY` (about 240 MB per million messages; on PostgreSQL writes wait), and the startup probe of the Helm chart or of the docs/13 StatefulSet restarts a pod whose boot outlasts about 295 s | On a large table run the migrations first (section 14.5), or raise `startupProbe.failureThreshold` |
| `0.25.0` | Rolling back to 0.24.0 strands webhook outbox rows in state `queued`, and the upgrade deletes duplicate terminal `webhook_delivery_failures` rows | Drain or accept the queued rows before a rollback; the deleted duplicates are not restored |
| `0.25.0` | A Baileys voice note goes out with flat waveform bars when no ffmpeg binary is found, and an `FFMPEG_PATH` wrapper script sees only `PATH`, the library paths, `HOME`, the temp directories, `LANG`, `LC_ALL` and `SystemRoot` of the gateway's environment | Use the official image, which ships ffmpeg, and export what a wrapper script needs inside the script |
| `0.24.0` | A live key refused by its `allowedIps` (including an undeterminable client IP) or its `allowedSessions` answers `403` instead of `401`; `401` now means only a missing, unknown, revoked or expired key | Handle `403` for these refusals: SDK callers catch the forbidden error (Go `ErrForbidden`) instead of the auth error |
diff --git a/docs/15-project-roadmap.md b/docs/15-project-roadmap.md
index b20887bee..2081dc98c 100644
--- a/docs/15-project-roadmap.md
+++ b/docs/15-project-roadmap.md
@@ -771,6 +771,12 @@ Re-using a version is safe precisely because nothing was published under it. A v
publish before a defect was found must not be re-tagged — never move or reuse an already-pushed tag;
supersede it with a new release instead (e.g. `v0.10.3` → `v0.10.4`).
+A gate that failed outside the image (a Trivy database download, a QEMU timeout) is recovered with
+**Re-run failed jobs**: the staging image of that run is kept when the build itself succeeded, and the
+re-run promotes it only after the gate passes. When a run is abandoned and the version re-tagged, its
+`smoke-<run_id>` tag stays in the registry; delete that package version once the new release is out,
+after confirming it carries no release tag.
+
Two failure classes are worth anticipating because they depend on the outside world rather than on
the change being released:
diff --git a/docs/16-risk-management.md b/docs/16-risk-management.md
index c76646f41..833a9e8ae 100644
--- a/docs/16-risk-management.md
+++ b/docs/16-risk-management.md
@@ -318,7 +318,7 @@ Dependencies (`whatsapp-web.js`, Puppeteer, NestJS, etc.) may have vulnerabiliti
**Mitigation Strategies:**
-> **Current state:** the real dependency check is a dedicated `audit` job in `ci.yml` running `npm run check:audit` over the root tree and `npm audit --audit-level=high` over `dashboard/` and `sdk/javascript/` (on push and PR); it is deliberately split out of the `Lint` job so a newly published advisory cannot abort the other quality gates. `check:audit` keeps the `high` threshold but applies it per advisory, so one with no patched version can be excused by id in `scripts/check-audit.mjs` (with its reason and removal condition recorded, and a stale entry failing the job) instead of lowering the bar for everything. `js-sdk-release.yml` audits `sdk/javascript/` before it publishes the SDK. `release.yml` repeats the root and dashboard audits, the two trees the image ships, and additionally runs a Trivy image scan (`CRITICAL,HIGH`, `ignore-unfixed`) against an explicit `.trivyignore` before the release tags are promoted. Dependabot PRs cover npm for `/`, `/dashboard` and `/sdk/javascript` (weekly), GitHub Actions (monthly), the Dockerfile base image and the `docker-compose.yml` images (weekly; PostgreSQL and Redis majors ignored, and a postgres, redis or pgsty/silo bump fails `compose-parity.spec.ts` until `src/modules/docker/docker.service.ts` carries the same image reference), with version-pinned ignores (seven in the root tree, two in `/dashboard`) whose reasons and lift conditions are recorded in `.github/dependabot.yml`. Between releases, `.github/workflows/security-scan.yml` (Scheduled Security Scan) runs every Wednesday at 03:00 UTC and on demand: it repeats the `audit` job and the release Trivy scan against the published `latest` image on amd64 and arm64, so an advisory those gates would block fails a run within a week of being published; the amd64 Chrome for Testing binary stays outside what Trivy can see (see `.trivyignore`). Its `base-image-drift` job fails when the Dockerfile's two `node:22-slim` FROM digests disagree, or when the pin differs from what the tag serves today and either the tag has served that image for 7 or more days, or for 3 or more days with the pin last changed 28 or more days ago; it backstops a Dependabot digest refresh that is late or left unmerged. There is **no** Snyk integration. The workflow below is a recommended enhancement to add Snyk; its scheduled `npm audit` is already covered by `security-scan.yml`.
+> **Current state:** the real dependency check is a dedicated `audit` job in `ci.yml` running `npm run check:audit` over the root tree and `npm audit --audit-level=high` over `dashboard/` and `sdk/javascript/` (on push and PR); it is deliberately split out of the `Lint` job so a newly published advisory cannot abort the other quality gates. `check:audit` keeps the `high` threshold but applies it per advisory, so one with no patched version can be excused by id in `scripts/check-audit.mjs` (with its reason and removal condition recorded, and a stale entry failing the job) instead of lowering the bar for everything. `js-sdk-release.yml` audits `sdk/javascript/` before it publishes the SDK. `release.yml` repeats the root and dashboard audits, the two trees the image ships, and additionally runs a Trivy image scan (`CRITICAL,HIGH`, `ignore-unfixed`) against an explicit `.trivyignore` before the release tags are promoted. Dependabot PRs cover npm for `/`, `/dashboard` and `/sdk/javascript`, and pip, maven, composer and gomod for the other four SDKs (weekly), GitHub Actions (monthly), the Dockerfile base image and the `docker-compose.yml` images (weekly; PostgreSQL and Redis majors ignored, and a postgres, redis or pgsty/silo bump fails `compose-parity.spec.ts` until `src/modules/docker/docker.service.ts` carries the same image reference), with version-pinned ignores (seven in the root tree, two in `/dashboard`) whose reasons and lift conditions are recorded in `.github/dependabot.yml`. Between releases, `.github/workflows/security-scan.yml` (Scheduled Security Scan) runs every Wednesday at 03:00 UTC and on demand: it repeats the `audit` job and the release Trivy scan against the published `latest` image on amd64 and arm64, so an advisory those gates would block fails a run within a week of being published; the amd64 Chrome for Testing binary stays outside what Trivy can see (see `.trivyignore`). Its `base-image-drift` job fails when the Dockerfile's two `node:22-slim` FROM digests disagree, or when the pin differs from what the tag serves today and either the tag has served that image for 7 or more days, or for 3 or more days with the pin last changed 28 or more days ago; it backstops a Dependabot digest refresh that is late or left unmerged. There is **no** Snyk integration. The workflow below is a recommended enhancement to add Snyk; its scheduled `npm audit` is already covered by `security-scan.yml`.
```yaml
# .github/workflows/security.yml
@@ -347,16 +347,16 @@ jobs:
**Dependency Management Policy:**
-| Action | Frequency |
-| ----------------------------------------------------------------------------------------- | ---------------------------- |
-| npm audit (`high`, per-advisory allowlist via `check:audit`; dedicated `audit` job in CI) | Every push / PR |
-| Trivy image scan (`CRITICAL,HIGH`, `.trivyignore`) | Every release |
-| Scheduled Security Scan (audit, Trivy on `latest` amd64 and arm64, base-image drift) | Weekly (Wednesday 03:00 UTC) |
-| Snyk scan | Not configured (planned) |
-| Dependabot PRs (npm: `/`, `/dashboard`, `/sdk/javascript`; docker; docker-compose) | Weekly |
-| Dependabot PRs (github-actions) | Monthly |
-| Major updates | Reviewed manually |
-| Security patches | Immediate |
+| Action | Frequency |
+| -------------------------------------------------------------------------------------------------- | ---------------------------- |
+| npm audit (`high`, per-advisory allowlist via `check:audit`; dedicated `audit` job in CI) | Every push / PR |
+| Trivy image scan (`CRITICAL,HIGH`, `.trivyignore`) | Every release |
+| Scheduled Security Scan (audit, Trivy on `latest` amd64 and arm64, base-image drift) | Weekly (Wednesday 03:00 UTC) |
+| Snyk scan | Not configured (planned) |
+| Dependabot PRs (npm: `/`, `/dashboard`, `/sdk/javascript`; the other SDKs; docker; docker-compose) | Weekly |
+| Dependabot PRs (github-actions) | Monthly |
+| Major updates | Reviewed manually |
+| Security patches | Immediate |
---
diff --git a/docs/17-dashboard-design.md b/docs/17-dashboard-design.md
index 5ab0c696d..fe8356a4a 100644
--- a/docs/17-dashboard-design.md
+++ b/docs/17-dashboard-design.md
@@ -562,9 +562,10 @@ export function useStopSessionMutation() {
}
```
-> **There is no `useSessionQr` polling hook.** QR codes are not fetched on a 30 s
-> `refetchInterval`. The Sessions page fetches the current QR imperatively via `sessionApi.getQR()`
-> and then receives fresh codes pushed over the WebSocket (`session.qr` events, see §17.6).
+> **There is no `useSessionQr` hook and no 30 s `refetchInterval`.** The Sessions page fetches the
+> current QR imperatively via `sessionApi.getQR()`, and `useSessionPairing` re-reads it with
+> `GET /sessions/:id/qr` every 5 s for as long as the QR modal is open; fresh codes are also pushed
+> over the WebSocket (`session.qr` events, see §17.6).
## 17.6 WebSocket Integration
diff --git a/docs/19-plugin-architecture.md b/docs/19-plugin-architecture.md
index 26c77f6c2..d9c2e2645 100644
--- a/docs/19-plugin-architecture.md
+++ b/docs/19-plugin-architecture.md
@@ -221,7 +221,7 @@ interface MyPluginConfig {
export default class MyAwesomePlugin implements IPlugin {
async onLoad(ctx: PluginContext): Promise<void> {
- ctx.logger.log('Plugin loaded', { version: ctx.manifest.version });
+ ctx.logger.log('Plugin loaded', { pluginId: ctx.pluginId });
// Register a hook handler. Handlers receive a HookContext and return a HookResult.
ctx.registerHook('message:received', async hookCtx => {
@@ -277,13 +277,13 @@ export interface IPlugin {
export interface PluginContext {
pluginId: string;
- manifest: PluginManifest;
+ manifest: PluginManifest; // in-process (built-in) context only; a sandboxed plugin has none
// Effective config for the firing session (per-session override merged over the base). A getter,
// so it reflects live config edits; outside a hook it returns the base config.
config: Record<string, unknown>;
- hookManager: HookManager;
+ hookManager: HookManager; // in-process (built-in) context only; a sandboxed plugin registers through registerHook
logger: PluginLogger; // log / debug / warn / error
storage: PluginStorage; // get / set / delete / list — requires 'storage:use', scoped to this plugin
@@ -675,7 +675,8 @@ data) would declare `engine:read` and call `ctx.engine.getGroupInfo(...)` / `ctx
## 19.8 Plugin Management API
`PluginsController` (`src/modules/plugins/plugins.controller.ts`) is mounted at `plugins` and **every
-route requires the `ADMIN` role** (`@RequireRole(ApiKeyRole.ADMIN)` — not a bare API-key guard). There
+route requires the `ADMIN` role** (`@RequireRole(ApiKeyRole.ADMIN)` — not a bare API-key guard) and an
+unscoped key (a session-scoped key is refused), except `PUT :id/config/:sessionId`. There
is **no** `POST :id/reload` and **no** `GET :id/config`. Install is a multipart `.zip` upload (or by
URL / catalog), not an npm/github source descriptor.
@@ -786,7 +787,8 @@ Two further checks apply on top of the permission:
security boundary; the manifest half is static (editing config can't widen it).
- **Network allowlist.** `ctx.net.fetch` additionally requires the target host to be on the plugin's
**effective** allowlist: `manifest.net.allow` plus the https origin of every `net.allowConfigHosts` config key
- that resolves to an https URL, taken across the base config **and** every per-session override. A host
+ that resolves to an https URL, taken across the base config, every per-session override **and** the config
+ of every enabled integration instance of the plugin. A host
admitted only through `allowConfigHosts` is therefore allowed while absent from `net.allow`. The request
always passes through the SSRF guard (which blocks internal IPs even for an allowlisted host).