Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
ci(gates): fail closed when a release gate cannot run
Yudhi Armyndharis2e22e48ec9db
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 32ea123ca..260757cfc 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -186,8 +186,9 @@ jobs:- name: Run e2e smoke testsrun: npm run test:e2e- # Point the queue-on suite at the service container (it self-skips without one). Every other- # suite keeps QUEUE_ENABLED=false via setup-e2e.ts and never touches Redis.+ # Point the queue-on suite at the service container (under GitHub Actions the suite fails+ # without one; a local run without Redis skips). Every other suite keeps QUEUE_ENABLED=false+ # via setup-e2e.ts and never touches Redis.env:REDIS_HOST: localhostREDIS_PORT: '6379'diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 34c9c9052..1acf18bbe 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -64,10 +64,14 @@ jobs:echo "Tag $TAG matches package.json $PKG_VERSION"- name: Security audit- # Matches ci.yml 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 be STRICTER either, or a tag fails on something main has already- # accepted, which is how a release stalls with nothing actionable to fix.+ # 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.+ 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@@ -128,9 +132,9 @@ jobs:name: Testruns-on: ubuntu-latesttimeout-minutes: 20- # Mirrors ci.yml's test job. Without this service the queue-on e2e suite self-skips and the- # release path reports green on a suite it never actually ran — the tag is the one place that- # must not be verified less than the branch it came from.+ # Mirrors ci.yml's test job. The queue-on e2e suite needs this service: under GitHub Actions it+ # fails rather than skipping when Redis is unreachable, so the tag is never verified less than the+ # branch it came from.services:redis:image: redis:7-alpinediff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.ymlindex 0c2600b0e..195ddef4b 100644--- a/.github/workflows/security-scan.yml+++ b/.github/workflows/security-scan.yml@@ -29,8 +29,9 @@ concurrency:cancel-in-progress: falsejobs:- # Mirrors the ci.yml `audit` job step for step, so a scheduled failure means exactly what a- # merge-gate failure means — no stricter, no looser.+ # Mirrors the ci.yml `audit` job step for step, with one difference: an audit npm cannot answer+ # fails here (CHECK_AUDIT_REQUIRED=1) instead of skipping, because this job exists to detect+ # advisories.audit:name: Security auditruns-on: ubuntu-latest@@ -54,7 +55,10 @@ jobs:- name: Security audit# check:audit, not bare `npm audit`: the per-advisory allowlist in scripts/check-audit.mjs# applies, so an advisory already excused by id (with its recorded reason and drop- # condition) does not fire a false weekly alarm.+ # condition) does not fire a false weekly alarm. Required here: this job exists to detect+ # advisories, and a skipped audit would report the whole week clean.+ env:+ CHECK_AUDIT_REQUIRED: '1'run: npm run check:audit# The dashboard is a second dependency tree and the one that reaches a browser; samediff --git a/docs/09-testing-strategy.md b/docs/09-testing-strategy.mdindex 9d07bd023..937dc790b 100644--- a/docs/09-testing-strategy.md+++ b/docs/09-testing-strategy.md@@ -262,7 +262,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/`) |+| `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 release gate and the weekly scan fail (`CHECK_AUDIT_REQUIRED=1`) || `test` | backend coverage run, script unit tests (node:test), e2e smoke tests || `test-postgres` | real PostgreSQL 16 service, backend build, migration smoke, and PostgreSQL FTS provider spec || `dashboard` | dashboard install, lint, formatting, type-check, i18n parity, build, unit tests |@@ -361,7 +361,8 @@ Live WhatsApp checks require an operator-owned account and should not be part of- The default `test` job uses SQLite; PostgreSQL 16 is only exercised by the dedicated `test-postgres` job.- No default CI job exercises S3/MinIO or Docker socket proxy integration. (Redis is no longer a gap: the`test` job starts a `redis:7-alpine` service container so the queue-on e2e suite has a broker. That suite- skips itself when no Redis is reachable, so it stays green on a machine without one.)+ skips itself when no Redis is reachable, so it stays green on a machine without one; under GitHub Actions+ it fails instead, so a workflow that loses its Redis service cannot report the suite green.)- Performance testing is not automated.- Dashboard browser/visual UI tests are not currently automated; dashboard pure utility tests run via `npm --prefix dashboard run test:unit`.diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex b5db74732..977dc7e0b 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -270,8 +270,9 @@ Rollout is left to the operator — the repo has no SSH deploy step, no staging/environments and no auto-deploy on merge.`.github/workflows/security-scan.yml` (`name: Scheduled Security Scan`) complements the merge-time-gates with a weekly run (Wednesdays 03:00 UTC, plus `workflow_dispatch`): it re-runs the exact-`audit` job against the current dependency trees and the release workflow's `image-scan` against+gates with a weekly run (Wednesdays 03:00 UTC, plus `workflow_dispatch`): it re-runs the `audit`+job's checks against the current dependency trees, failing rather than skipping when npm's audit+endpoint cannot answer (`CHECK_AUDIT_REQUIRED=1`), and the release workflow's `image-scan` againstthe published `latest` image on both architectures. A newly published advisory therefore turnssomething red within days instead of waiting for the next push or release. A third job,`base-image-drift`, fails when the two `node:22-slim` FROM lines in the `Dockerfile` pin differentdiff --git a/scripts/check-audit.mjs b/scripts/check-audit.mjsindex 8d6ac26e8..6fbe82926 100644--- a/scripts/check-audit.mjs+++ b/scripts/check-audit.mjs@@ -70,7 +70,8 @@ function runAuditOnce() {/*** Runs the audit, retrying once when the endpoint does not answer. A transient blip clears on the* retry; a retired or persistently-down endpoint returns the last error report, which the caller- * turns into a loud skip rather than a false "stale allowlist" failure.+ * turns into a loud skip (or, on a required path, a failure) rather than a false "stale allowlist"+ * failure.*/function runAudit() {const ATTEMPTS = 2;@@ -107,6 +108,34 @@ export function collectAdvisories(report) {return found;}+/**+ * What to do when npm audit could not answer at all. PR and push CI skip, so an npm outage does not+ * block every merge, but the skip is raised as a warning annotation on GitHub Actions rather than a+ * log line inside a green job. A path that sets CHECK_AUDIT_REQUIRED=1 (the release gate and the+ * weekly scan) fails instead: publishing, or reporting a week clean, with no advisory checked is not+ * a skip those paths may take. A re-run clears a transient outage.+ */+export function unavailableOutcome(summary, env = process.env) {+ const required = env.CHECK_AUDIT_REQUIRED === '1';+ const text = `npm audit endpoint is unavailable after a retry (${summary}); advisories were not checked this run.`;+ const lines = [];+ if (env.GITHUB_ACTIONS === 'true') {+ // A workflow command ends at the first newline, and npm's summary can span several lines.+ const message = text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');+ lines.push(+ required+ ? `::error title=check:audit could not run::${message}`+ : `::warning title=check:audit skipped::${message}`,+ );+ }+ lines.push(+ required+ ? `check:audit FAILED: ${text} The audit is required on this path (CHECK_AUDIT_REQUIRED=1).`+ : `check:audit SKIPPED: ${text}`,+ );+ return { exitCode: required ? 1 : 0, lines };+}+/** The gate's verdict, split out so a spec can drive it without shelling out to npm. */export function evaluate(report, allowlist = ALLOWLIST) {const advisories = collectAdvisories(report);@@ -147,16 +176,14 @@ export function evaluate(report, allowlist = ALLOWLIST) {if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {const report = runAudit();- // A registry that cannot answer the audit request must not be read as a clean tree, and blocking- // every merge while npm's audit endpoint is down (or being retired) is worse than the risk of a- // missed advisory for the duration. Skip loudly instead: the gate resumes the moment the endpoint- // answers, and a working audit still fails on any unexcused high or critical.+ // A registry that cannot answer the audit request must not be read as a clean tree. On a merge+ // path, blocking every merge while npm's audit endpoint is down (or being retired) is worse than+ // the risk of a missed advisory for the duration, so it skips loudly; a required path fails. See+ // unavailableOutcome.if (auditUnavailable(report)) {- console.warn(- `check:audit SKIPPED: npm audit endpoint is unavailable after a retry (${report?.error?.summary ?? 'no report'}). ` +- 'Advisories were not checked this run.',- );- process.exit(0);+ const outcome = unavailableOutcome(report?.error?.summary ?? 'no report');+ for (const line of outcome.lines) console.log(line);+ process.exit(outcome.exitCode);}const errors = evaluate(report);diff --git a/scripts/check-audit.spec.mjs b/scripts/check-audit.spec.mjsindex 68db0378b..ff8a4f3c2 100644--- a/scripts/check-audit.spec.mjs+++ b/scripts/check-audit.spec.mjs@@ -1,6 +1,11 @@import test from 'node:test';import assert from 'node:assert/strict';-import { auditUnavailable, collectAdvisories, evaluate } from './check-audit.mjs';+import { spawnSync } from 'node:child_process';+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { delimiter, join } from 'node:path';+import { fileURLToPath } from 'node:url';+import { auditUnavailable, collectAdvisories, evaluate, unavailableOutcome } from './check-audit.mjs';/*** The report shape is taken from a real `npm audit --json` run, not invented: one advisory@@ -126,3 +131,66 @@ test('a clean or vulnerable report is not audit-unavailable', () => {assert.equal(auditUnavailable({ vulnerabilities: {} }), false);assert.equal(auditUnavailable(puppeteerReport), false);});++// PR CI keeps the skip so an npm outage does not block every merge, but it must show on the run as a+// warning annotation rather than a plain log line inside a green job.+test('an unavailable audit skips with exit 0 outside a required path', () => {+ const plain = unavailableOutcome('down', {});+ assert.equal(plain.exitCode, 0);+ assert.equal(+ plain.lines.some(line => line.startsWith('::warning')),+ false,+ );+ const actions = unavailableOutcome('down', { GITHUB_ACTIONS: 'true' });+ assert.equal(actions.exitCode, 0);+ assert.match(actions.lines[0], /^::warning title=check:audit skipped::.*down/);+});++// The release and the weekly scan set CHECK_AUDIT_REQUIRED=1: publishing, or reporting a week clean,+// with no advisory checked at all is not a skip they may take.+test('an unavailable audit fails when the path requires it', () => {+ const required = unavailableOutcome('down', { CHECK_AUDIT_REQUIRED: '1', GITHUB_ACTIONS: 'true' });+ assert.equal(required.exitCode, 1);+ assert.match(required.lines.join('\n'), /required on this path/);+ assert.match(required.lines[0], /^::error title=check:audit could not run::/);+ assert.equal(unavailableOutcome('down', { CHECK_AUDIT_REQUIRED: '0' }).exitCode, 0);+});++test('the annotation stays on one line when npm reports a multi-line summary', () => {+ const [annotation] = unavailableOutcome('100% down\nretry later', { GITHUB_ACTIONS: 'true' }).lines;+ assert.equal(annotation.includes('\n'), false);+ assert.match(annotation, /100%25 down%0Aretry later/);+});++// End to end through the real entrypoint, with `npm` replaced by a shim that answers like a down+// audit endpoint, so the exit code the workflow sees is the one asserted.+test(+ 'the script exits by CHECK_AUDIT_REQUIRED when npm audit cannot answer',+ { skip: process.platform === 'win32' },+ () => {+ const bin = mkdtempSync(join(tmpdir(), 'check-audit-'));+ try {+ writeFileSync(join(bin, 'npm'), '#!/bin/sh\necho \'{"error":{"summary":"endpoint down"}}\'\nexit 1\n');+ chmodSync(join(bin, 'npm'), 0o755);+ const script = fileURLToPath(new URL('./check-audit.mjs', import.meta.url));+ const run = extra =>+ spawnSync(process.execPath, [script], {+ encoding: 'utf8',+ env: {+ ...process.env,+ GITHUB_ACTIONS: '',+ CHECK_AUDIT_REQUIRED: '',+ ...extra,+ PATH: `${bin}${delimiter}${process.env.PATH}`,+ },+ });+ const skipped = run({});+ assert.equal(skipped.status, 0, skipped.stderr);+ assert.match(skipped.stdout, /check:audit SKIPPED/);+ const required = run({ CHECK_AUDIT_REQUIRED: '1' });+ assert.equal(required.status, 1);+ } finally {+ rmSync(bin, { recursive: true, force: true });+ }+ },+);diff --git a/src/common/release-gate-parity.spec.ts b/src/common/release-gate-parity.spec.tsindex fccbd04c2..caddb1395 100644--- a/src/common/release-gate-parity.spec.ts+++ b/src/common/release-gate-parity.spec.ts@@ -89,3 +89,39 @@ describe('one prerelease rule across the GitHub Release and the image channels',expect(steps().some(step => /\[\[ "\$REF_NAME" == \*-\* \]\]/.test(step.run ?? ''))).toBe(true);});});++/**+ * check:audit skips when npm's audit endpoint cannot answer, so an npm outage does not block every+ * merge. The release and the weekly scan must not take that skip: one would publish, the other would+ * report the week clean, with no advisory checked. CHECK_AUDIT_REQUIRED=1 turns the skip into a failure.+ */+describe('the release and weekly audits fail when the audit cannot run', () => {+ type AuditStep = { run?: string; env?: Record<string, unknown> };+ const auditSteps = (file: string): AuditStep[] => {+ const workflow = yaml.load(fs.readFileSync(path.join(workflowDir, file), 'utf8')) as {+ jobs?: Record<string, { steps?: AuditStep[] }>;+ };+ return Object.values(workflow.jobs ?? {})+ .flatMap(job => job.steps ?? [])+ .filter(step => executableLines(step.run ?? '').includes('npm run check:audit'));+ };++ it.each(['release.yml', 'security-scan.yml'])('%s requires the audit', file => {+ const steps = auditSteps(file);+ expect(steps.length).toBeGreaterThan(0);+ expect(steps.filter(step => step.env?.CHECK_AUDIT_REQUIRED !== '1')).toEqual([]);+ });++ it('docs/10 describes the weekly audit as required, not as the merge job', () => {+ const doc = fs.readFileSync(path.join(__dirname, '..', '..', 'docs', '10-devops-infrastructure.md'), 'utf8');+ const paragraph = doc.split(/\n\s*\n/).find(block => block.includes('security-scan.yml'));+ expect(paragraph).toContain('`CHECK_AUDIT_REQUIRED=1`');+ expect(paragraph).not.toMatch(/exact\s+`audit`/);+ });++ it('ci.yml keeps the skip for merges', () => {+ const steps = auditSteps('ci.yml');+ expect(steps.length).toBeGreaterThan(0);+ expect(steps.some(step => step.env?.CHECK_AUDIT_REQUIRED !== undefined)).toBe(false);+ });+});diff --git a/test/queue-on.e2e-spec.ts b/test/queue-on.e2e-spec.tsindex 11851eb30..707d4c585 100644--- a/test/queue-on.e2e-spec.ts+++ b/test/queue-on.e2e-spec.ts@@ -21,7 +21,10 @@ process.env.REDIS_PORT = String(REDIS_PORT);// Jest registers suites synchronously at file load and has no runtime skip, so the Redis// availability probe has to settle synchronously too: spawn a throwaway node one-liner that// TCP-connects with a hard deadline (spawnSync kills it past the timeout margin). Unreachable →-// describe.skip below: an explicit green skip instead of a red boot.+// describe.skip below on a developer box: an explicit green skip instead of a red boot. On GitHub+// Actions every workflow that runs this suite provides Redis, so an unreachable one is drift (a+// removed service, a renamed env var) and fails the suite instead of reporting green on tests it+// never ran. Keyed on GITHUB_ACTIONS rather than CI, which a local shell may export without Redis.const probeRedis = (host: string, port: number, timeoutMs: number): boolean => {const script =`const s = require('net').connect(${port}, ${JSON.stringify(host)});` +@@ -32,6 +35,12 @@ const probeRedis = (host: string, port: number, timeoutMs: number): boolean => {};const REDIS_AVAILABLE = probeRedis(REDIS_HOST, REDIS_PORT, 1000);+if (!REDIS_AVAILABLE && process.env.GITHUB_ACTIONS === 'true') {+ throw new Error(+ `queue-on e2e: no Redis at ${REDIS_HOST}:${REDIS_PORT} under GitHub Actions (set REDIS_HOST/REDIS_PORT or ` ++ 'QUEUE_TEST_REDIS_HOST/QUEUE_TEST_REDIS_PORT); refusing to skip',+ );+}const describeQueueOn = REDIS_AVAILABLE ? describe : describe.skip;import { createHmac, randomBytes } from 'node:crypto';@@ -82,7 +91,7 @@ import { WebhookService } from '../src/modules/webhook/webhook.service';* (or `docker compose --profile redis up -d redis`); point elsewhere with* QUEUE_TEST_REDIS_HOST/QUEUE_TEST_REDIS_PORT. CI runs it against the redis service of the Test job.* With no Redis reachable the whole suite self-skips (see REDIS_AVAILABLE above), so a bare- * `npm run test:e2e` on a Redis-less box stays green.+ * `npm run test:e2e` on a Redis-less box stays green; on GitHub Actions it fails instead.*/describeQueueOn('Queued dispatch paths (e2e, QUEUE_ENABLED=true)', () => {let app: INestApplication<App>;