Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
ci: audit the JavaScript SDK dependencies (#1808)
Yudhi Armyndharis637c83c9b5d8
diff --git a/.github/dependabot.yml b/.github/dependabot.ymlindex 7c00ac253..1657b4822 100644--- a/.github/dependabot.yml+++ b/.github/dependabot.yml@@ -136,6 +136,26 @@ updates:- dependency-name: "@types/node"versions: [">=23.0.0"]+ # The JavaScript SDK publishes no runtime dependencies, so every update here moves the toolchain+ # that builds and tests it. These PRs touch sdk/**, so SDK CI gates each one.+ - package-ecosystem: npm+ directory: /sdk/javascript+ schedule:+ interval: weekly+ day: monday+ open-pull-requests-limit: 3+ groups:+ minor-and-patch:+ update-types:+ - minor+ - patch+ major:+ update-types:+ - major+ labels:+ - dependencies+ - javascript+# All workflow action refs are pinned to commit SHAs (with a `# vX.Y.Z` comment). Dependabot# understands that form: it proposes the new SHA and rewrites the version comment, so the pins# stay current without ever floating on a mutable major tag.diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 60ab4d62c..06d67a6a2 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -141,6 +141,12 @@ jobs:# `build` job that needs it does not run. A re-run clears a transient outage.run: cd dashboard && npm audit --audit-level=high+ # The JavaScript SDK is the third tree. Its published package has no runtime dependencies, so+ # what this catches is its build and test toolchain, which otherwise went unscanned. `npm audit`+ # reads the lockfile alone, so the tree is not installed here.+ - name: Security audit (JavaScript SDK)+ run: cd sdk/javascript && npm audit --audit-level=high+test:name: Testruns-on: ubuntu-latestdiff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.ymlindex 195ddef4b..eaa97316b 100644--- a/.github/workflows/security-scan.yml+++ b/.github/workflows/security-scan.yml@@ -69,6 +69,10 @@ jobs:- name: Security audit (dashboard)run: cd dashboard && npm audit --audit-level=high+ # Audited from its lockfile alone; same rationale as the ci.yml audit job.+ - name: Security audit (JavaScript SDK)+ run: cd sdk/javascript && npm audit --audit-level=high+# Dependabot proposes refreshed node:22-slim digests, yet the pin has trailed the tag for weeks# (a refresh that is late or left unmerged), and a stale base ages silently: Node patch releases# and Debian fixes that the image scan below does not flag (medium/low, or not yet fixed upstream)diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6e2612618..dce8f8629 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Add opt-in archive-only chat media with dashboard previews.+### Changed++- CI and the weekly security scan run `npm audit` over the JavaScript SDK, and Dependabot watches its lockfile.+### Fixed- Apply the Java SDK request timeout to the response body as well as the headers.diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 4b98a92bf..96a2317e3 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -760,7 +760,8 @@ npm audit --json > audit-report.json```yaml# .github/dependabot.yml, root npm ecosystem only (the file also covers /dashboard,-# github-actions, docker and docker-compose). The comment above each ignore is omitted here.+# /sdk/javascript, github-actions, docker and docker-compose). The comment above each+# ignore is omitted here.version: 2updates:- package-ecosystem: npm@@ -804,7 +805,7 @@ tar-stream from 3.2.1). Each ignore's reason and lift condition is the comment a### Security Scanning in CI-> **Aspirational template — not in the repo.** There is no Snyk and no CodeQL workflow today. The actual dependency check is a dedicated `audit` job ("Security audit") in `ci.yml`, on push/PR. It is deliberately its own job rather than a step inside Lint: an advisory published against an unrelated dependency would otherwise abort the job before ESLint, the type-check and the drift gates ever ran. It runs `npm run check:audit` over the root tree and `npm audit --audit-level=high` over `dashboard/`. Both fence `high` rather than `critical`, because the `overrides` in `package.json` clear the root tree's existing HIGH advisories, so the threshold fences regressions. `check:audit` applies that threshold per advisory instead of all-or-nothing: an advisory with no patched version can be excused by id in `scripts/check-audit.mjs`, with its reason and its removal condition recorded beside it, rather than dropping the whole job to `critical` — and an allowlist entry whose advisory has since gone fails the job too, so an exception cannot outlive its cause. The dashboard keeps the plain form: it has nothing to excuse and stays the stricter of the two. Between releases, `.github/workflows/security-scan.yml` (Scheduled Security Scan) repeats that job every Wednesday at 03:00 UTC and on demand, together with the release Trivy scan against the published `latest` image on amd64 and arm64, and a `base-image-drift` job that 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. The workflow below is a recommended setup to add if you want Snyk and SAST; its scheduled `npm audit` is already covered by `security-scan.yml`.+> **Aspirational template — not in the repo.** There is no Snyk and no CodeQL workflow today. The actual dependency check is a dedicated `audit` job ("Security audit") in `ci.yml`, on push/PR. It is deliberately its own job rather than a step inside Lint: an advisory published against an unrelated dependency would otherwise abort the job before ESLint, the type-check and the drift gates ever ran. It runs `npm run check:audit` over the root tree and `npm audit --audit-level=high` over `dashboard/` and `sdk/javascript/`. All three fence `high` rather than `critical`, because the `overrides` in `package.json` clear the root tree's existing HIGH advisories, so the threshold fences regressions. `check:audit` applies that threshold per advisory instead of all-or-nothing: an advisory with no patched version can be excused by id in `scripts/check-audit.mjs`, with its reason and its removal condition recorded beside it, rather than dropping the whole job to `critical` — and an allowlist entry whose advisory has since gone fails the job too, so an exception cannot outlive its cause. The dashboard and the SDK keep the plain form: they have nothing to excuse and stay stricter than the root. Between releases, `.github/workflows/security-scan.yml` (Scheduled Security Scan) repeats that job every Wednesday at 03:00 UTC and on demand, together with the release Trivy scan against the published `latest` image on amd64 and arm64, and a `base-image-drift` job that 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. The workflow below is a recommended setup to add if you want Snyk and SAST; its scheduled `npm audit` is already covered by `security-scan.yml`.```yaml# .github/workflows/security.ymldiff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.mdindex 4563b4184..02348004f 100644--- a/docs/09-testing-strategy.md+++ b/docs/09-testing-strategy.md@@ -257,7 +257,7 @@ request's superseded run; push runs on `main` are never cancelled or queued behi| Job | Checks || --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `lint` | backend ESLint, full-program TypeScript check, formatting, version consistency, .dockerignore context, OpenAPI snapshot, SDK routes and webhook events against the contract, contract coverage per SDK, SDK docs against the shipped client surface, client wire shapes (`check:contract-shapes` — the JavaScript SDK's, dashboard's, Python's, Go's and Java's hand-written types against the OpenAPI schemas; the PHP client returns untyped arrays and has no types layer to gate) |-| `audit` | dependency security audit of BOTH npm trees (root and `dashboard/`); when npm's audit endpoint cannot answer, the root audit skips with a warning annotation here while the dashboard audit, a plain `npm audit`, fails closed, so the job still goes red until a re-run; the release gate and the weekly scan fail (`CHECK_AUDIT_REQUIRED=1`) |+| `audit` | dependency security audit of all three npm trees (root, `dashboard/` and `sdk/javascript/`); when npm's audit endpoint cannot answer, the root audit skips with a warning annotation here while the dashboard and SDK audits, a plain `npm audit`, fail closed, so the job still goes red until a re-run; the release gate and the weekly scan fail (`CHECK_AUDIT_REQUIRED=1`) || `test` | backend coverage run, repo-file drift gates (`test:docs`), script unit tests (node:test), e2e smoke tests || `test-postgres` | real PostgreSQL 16 service, backend build, migration smoke, and the PostgreSQL specs (FTS provider, boot-migration lock, message list ordering, entity synchronize, UTC pin) || `dashboard` | dashboard install, lint, formatting, type-check, i18n parity, build, unit tests |diff --git a/docs/16-risk-management.md b/docs/16-risk-management.mdindex 4df8fc255..f826a6bf9 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/` (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. `release.yml` repeats both 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 `/` and `/dashboard` (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. `release.yml` repeats the root and dashboard audits 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`.```yaml# .github/workflows/security.yml@@ -353,7 +353,7 @@ jobs:| 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: `/` and `/dashboard`; docker; docker-compose) | Weekly |+| Dependabot PRs (npm: `/`, `/dashboard`, `/sdk/javascript`; docker; docker-compose) | Weekly || Dependabot PRs (github-actions) | Monthly || Major updates | Reviewed manually || Security patches | Immediate |diff --git a/docs/20-community-guidelines.md b/docs/20-community-guidelines.mdindex a087f5f8f..78f886d9b 100644--- a/docs/20-community-guidelines.md+++ b/docs/20-community-guidelines.md@@ -301,8 +301,8 @@ not supported on whatsapp-web.js, the default engine.| `github_actions` | Pull requests that update GitHub Actions code || `javascript` | Pull requests that update javascript code |-`.github/dependabot.yml` applies `dependencies`, `dashboard`, `ci` and `docker`; `github_actions` and-`javascript` are Dependabot defaults from before it set explicit labels.+`.github/dependabot.yml` applies `dependencies`, `dashboard`, `javascript` (the JavaScript SDK), `ci` and+`docker`; `github_actions` is a Dependabot default from before it set explicit labels.## 20.4 Community Channelsdiff --git a/scripts/check-audit.mjs b/scripts/check-audit.mjsindex ce504a0b5..13d2338ae 100644--- a/scripts/check-audit.mjs+++ b/scripts/check-audit.mjs@@ -16,8 +16,9 @@* 2. An allowlist entry whose advisory no longer appears ALSO FAILS. A carve-out that outlives* its cause is how a gate quietly narrows, so removing it is not left to anyone remembering.*- * Scope: the root tree only. `dashboard/` keeps a plain `npm audit --audit-level=high`, because it- * has nothing to excuse and should stay the stricter of the two.+ * Scope: the root tree only. `dashboard/` and `sdk/javascript/` keep a plain+ * `npm audit --audit-level=high`, because they have nothing to excuse and should stay stricter+ * than the root.** Run locally: `npm run check:audit`.*/diff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.tsindex 39767101f..6bc4077e3 100644--- a/src/common/release-gate-parity.spec.ts+++ b/src/common/release-gate-parity.spec.ts@@ -146,6 +146,38 @@ describe('the release and weekly audits fail when the audit cannot run', () => {});});+/**+ * Each npm tree has its own lockfile, and `npm audit` in one directory never sees another's. A tree+ * the merge and weekly audits skip, or that Dependabot does not watch, collects advisories unseen.+ */+describe('every npm tree is audited and kept current', () => {+ const root = path.join(__dirname, '..', '..');+ const trees = (): string[] =>+ spawnSync('git', ['ls-files', '--', '*package-lock.json'], { cwd: root, encoding: 'utf8' })+ .stdout.split('\n')+ .filter(Boolean)+ .map(file => path.posix.dirname(file).replace(/^\.$/, ''));+ const auditCommand = (tree: string): string =>+ tree === '' ? 'npm run check:audit' : `cd ${tree} && npm audit --audit-level=high`;++ it('finds every tree', () => {+ expect(trees()).toEqual(expect.arrayContaining(['', 'dashboard', 'sdk/javascript']));+ });++ it.each(['ci.yml', 'security-scan.yml'])('%s audits every tree', file => {+ const runs = runSteps(file, 'audit');+ expect(trees().filter(tree => !runs.includes(auditCommand(tree)))).toEqual([]);+ });++ it('Dependabot updates every tree', () => {+ const dependabot = yaml.load(fs.readFileSync(path.join(root, '.github', 'dependabot.yml'), 'utf8')) as {+ updates: Array<{ 'package-ecosystem': string; directory: string }>;+ };+ const watched = dependabot.updates.filter(u => u['package-ecosystem'] === 'npm').map(u => u.directory);+ expect(trees().filter(tree => !watched.includes(`/${tree}`))).toEqual([]);+ });+});+/*** BuildKit's provenance and SBOM travel inside the image index unsigned, so nothing a user could check* tied a published image to this workflow. promote now records a signed build-provenance attestation