Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
ci(sdk): audit the SDK lockfile before an npm publish (#1845)
Yudhi Armyndharis22e060c11d05
diff --git a/.github/workflows/js-sdk-release.yml b/.github/workflows/js-sdk-release.ymlindex c7ce93823..937918155 100644--- a/.github/workflows/js-sdk-release.yml+++ b/.github/workflows/js-sdk-release.yml@@ -84,6 +84,13 @@ jobs:npm install -g [email protected]npm --version+ # The audit ci.yml runs over this tree, so a tag cannot publish what main would refuse. The+ # package has no runtime dependencies, but its build and test toolchain runs here, in a job that+ # can mint a publish credential, and builds the dist/ that ships. `npm audit` reads the lockfile+ # alone, so it runs before the install executes any of that toolchain. It has no skip path: an+ # npm audit outage fails the publish, and a re-run clears it.+ - run: npm audit --audit-level=high+# --engine-strict: the tests below must not run on a Node the locked toolchain does not support.- run: npm ci --engine-strictdiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 7345107e8..31e846758 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -64,20 +64,21 @@ jobs:echo "Tag $TAG matches package.json $PKG_VERSION"- name: Security audit- # Matches ci.yml's advisory rules exactly, including its per-advisory allowlist. The release- # gate must not be laxer than the PR gate, or a HIGH advisory blocked on every PR would still- # sail through at tag time, and it must not excuse fewer advisories either, or a tag fails on- # something main has already accepted. The one difference is an audit that could not run:- # PR CI skips it with a warning, while a release refuses to publish with no advisory checked.- # A re-run clears a transient npm outage.+ # Matches ci.yml's advisory rules exactly, including its per-advisory allowlist. For the trees+ # the image ships, the release gate must not be laxer than the PR gate, or a HIGH advisory+ # blocked on every PR would still sail through at tag time, and it must not excuse fewer+ # advisories either, or a tag fails on something main has already accepted. The one+ # difference is an audit that could not run: PR CI skips it with a warning, while a release+ # refuses to publish with no advisory checked. A re-run clears a transient npm outage.env:CHECK_AUDIT_REQUIRED: '1'run: npm run check:audit- # Second tree, same rule. The dashboard's runtime deps are bundled into dashboard/dist and the+ # The dashboard tree, same rule. Its runtime deps are bundled into dashboard/dist and the# published image serves them to every operator's browser, so the tag path must scan them for- # the same reason ci.yml's audit job now does — otherwise this gate is laxer than the PR gate- # for exactly the dependencies that reach a user.+ # the same reason ci.yml's audit job does, or this gate is laxer than the PR gate for exactly+ # the dependencies that reach a user. The third tree, sdk/javascript, is not audited here: the+ # image does not ship it, and js-sdk-release.yml audits it before publishing the SDK.- name: Install dashboard dependenciesrun: cd dashboard && npm cidiff --git a/CHANGELOG.md b/CHANGELOG.mdindex f855f5b78..a63683801 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Changed+- The JavaScript SDK release job runs `npm audit` over the SDK tree before it installs, tests and publishes.- The JavaScript SDK CommonJS build no longer sets `moduleResolution` node10, which TypeScript 7 removed; the built output is unchanged.- JavaScript SDK CI and release jobs install with `--engine-strict` wherever they run the tests, so an unsupported Node fails at install.- The JavaScript SDK smoke check sends requests through both built clients, so the Node 18 CI lane covers the request path.diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 96a2317e3..c81def4b1 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -805,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/` 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`.+> **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`: none of the trees carries a HIGH advisory today (the root reaches that through the `overrides` in `package.json`), 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`; 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/16-risk-management.md b/docs/16-risk-management.mdindex f826a6bf9..c76646f41 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. `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`.+> **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`.```yaml# .github/workflows/security.ymldiff --git a/sdk/javascript/README.md b/sdk/javascript/README.mdindex 463a8ec49..97ba90039 100644--- a/sdk/javascript/README.md+++ b/sdk/javascript/README.md@@ -120,10 +120,11 @@ Cutting a release:2. Tag that commit `js-sdk-v<version>` (e.g. `js-sdk-v0.5.1`) and push the tag.The SDK has its own version line — the monorepo's `v*` tags are the appversion and never trigger an SDK publish.-3. The workflow re-runs the SDK's tests, typecheck, build and dual CJS/ESM- smoke check (packaging plus requests through each build's client), then- publishes. The published tarball is the one those gates passed, not a- later rebuild.+3. The workflow audits the SDK lockfile (`npm audit --audit-level=high`),+ re-runs the SDK's tests, typecheck, build and dual CJS/ESM smoke check+ (packaging plus requests through each build's client), then publishes.+ The published tarball is the one those gates passed, not a later+ rebuild.## Licensediff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.tsindex 96ceeab1e..27c6628fb 100644--- a/src/common/release-gate-parity.spec.ts+++ b/src/common/release-gate-parity.spec.ts@@ -9,10 +9,10 @@ import { executableLines } from './workflow-lines';* The release workflow publishes the image and the GitHub Release from a tag push. A tag starts* release.yml ALONE (ci.yml triggers on branches), so whatever gate the tag path skips is a gate a* release never ran; the workflow's own header states the invariant ("a tag can never publish- * something the branch gate would have refused"; "the release gate must not be laxer than the PR- * gate"). Both sides drifted before: check:contract-shapes and test:docs ran only on branches, so- * an SDK wire-shape regression or a repo-file drift could ride a tag to publication while the same- * commit would have failed CI.+ * something the branch gate would have refused"; "for the trees the image ships, the release gate+ * must not be laxer than the PR gate"). Both sides drifted before: check:contract-shapes and+ * test:docs ran only on branches, so an SDK wire-shape regression or a repo-file drift could ride a+ * tag to publication while the same commit would have failed CI.** This locks the invariant structurally: every gate command (npm/npx lines) in ci.yml's lint and* test jobs must also run in release.yml's lint and test jobs (the workflow header and the check:audit step comment both state@@ -169,6 +169,48 @@ describe('every npm tree is audited and kept current', () => {expect(trees().filter(tree => !runs.includes(auditCommand(tree)))).toEqual([]);});+ type ReleaseStep = { run?: string; 'continue-on-error'?: unknown; 'working-directory'?: string };+ const releaseAudits = (file: string, job: string) => {+ const workflow = yaml.load(fs.readFileSync(path.join(workflowDir, file), 'utf8')) as {+ jobs: Record<string, { defaults?: { run?: { 'working-directory'?: string } }; steps: ReleaseStep[] }>;+ };+ const cwd = workflow.jobs[job].defaults?.run?.['working-directory'] ?? '';+ return workflow.jobs[job].steps.flatMap((step, index) =>+ executableLines(step.run ?? '')+ .split('\n')+ .map(line => /^(?:cd (\S+) && )?npm (?:run check:audit|audit --audit-level=high)$/.exec(line.trim()))+ .flatMap(match =>+ match ? [{ index, step, tree: path.posix.join(cwd, match[1] ?? '').replace(/^\.$/, '') }] : [],+ ),+ );+ };++ // A tag starts only its own release workflow, so each one audits the trees it publishes: the image+ // carries the root and the dashboard, the npm package is built from the SDK. Exact, so moving a+ // tree from one path to the other is a deliberate edit here.+ it.each([+ ['release.yml', 'lint', ['', 'dashboard']],+ ['js-sdk-release.yml', 'publish', ['sdk/javascript']],+ ])('%s %s audits exactly the trees it publishes', (file, job, published) => {+ const audits = releaseAudits(file, job);+ expect(audits.map(audit => audit.tree)).toEqual(published);+ // An audit allowed to fail gates nothing, and a step-level working-directory audits another tree.+ expect(+ audits.filter(({ step }) => step['continue-on-error'] !== undefined || step['working-directory'] !== undefined),+ ).toEqual([]);+ });++ // `npm audit` reads the lockfile alone, so a high advisory stops the publish job before `npm ci`+ // runs any of the toolchain while the job can mint a publish credential.+ it('js-sdk-release.yml audits the SDK before it installs it', () => {+ const [audit] = releaseAudits('js-sdk-release.yml', 'publish');+ const install = jobSteps('js-sdk-release.yml', 'publish').findIndex(step =>+ /^npm ci\b/.test(executableLines(step.run ?? '').trim()),+ );+ expect(install).toBeGreaterThan(-1);+ expect(audit.index).toBeLessThan(install);+ });+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 }>;