Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.yml
index 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-strict
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 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 dependencies
run: cd dashboard && npm ci
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.yml
diff --git a/docs/16-risk-management.md b/docs/16-risk-management.md
index 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.yml
diff --git a/sdk/javascript/README.md b/sdk/javascript/README.md
index 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 app
version 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.
## License
diff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.ts
index 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 }>;