OpenWA - Moses Yebei

The Problem

Self-hosted WhatsApp integrations typically mean either paying for a managed API or wiring together unofficial libraries with hand-rolled auth, webhooks, and dashboards. OpenWA packages that into a single deployable gateway with an API-key auth layer, multi-session support, and a React admin UI.

What This Does

OpenWA is a NestJS-based WhatsApp API gateway. The backend in src/ exposes REST endpoints for messaging, groups, contacts, and labels, with pluggable storage (SQLite/PostgreSQL), cache (Memory/Redis), and object storage (Local/S3). The dashboard/ folder is a React/Vite admin panel for managing sessions, API keys, and webhooks. A small SDK in sdk/javascript and sdk/python wraps the REST API.

The architecture is adapter-based: src/engine/adapters/whatsapp-web-js.adapter.ts is the default WhatsApp engine, and src/engine/engine.factory.ts selects the active one. Plugins load from a directory at runtime via src/core/plugins/plugin-loader.service.ts.

How It Is Wired

Execution starts in src/main.ts (bootstrap), which initializes the NestJS app and reaches 21 functions. The critical path is short: bootstrap -> create -> createApiKey performs a randomBytes(32) call, and dispatch -> generateSignature does an HMAC digest for webhook verification. So a fresh deployment generates API keys and signs webhooks within two hops of boot.

The call graph shows three heavily reused functions: ensureReady (49 call sites), getEngine (48), and request (31). src/modules/session/session.service.ts is the integration point for the WhatsApp engine — 12 modules import it. The logger.service is a hub with 15 dependents but zero outgoing edges; changing its signature ripples across a third of the codebase. The module graph has no circular dependencies, which keeps refactoring tractable.

File-by-file: whatsapp-web-js.adapter.ts owns engine lifecycle (65 functions); src/modules/auth/auth.service.ts handles API key creation and HMAC signing; src/modules/infra/infra.controller.ts manages engine selection and config persistence; dashboard/src/services/api.ts is the frontend's typed client.

How To Use It

Setup: Requires Node 22 and npm. Docker Compose is the fastest path — docker-compose.yml exists with a mounted socket for containerized WhatsApp sessions.

Configuration: Copy .env.example to .env and set database, cache, and storage backends. There's also a committed .env.minimal — see the health section.

Running it:

npm install
npm run start:dev
# or
docker-compose up -d

The dashboard runs separately from dashboard/ via Vite. The SDK is published from sdk/javascript and sdk/python.

Real-World Use

A support team runs OpenWA on a single VPS with SQLite and local storage. The React dashboard lets them scan QR codes for multiple WhatsApp numbers, assign API keys per internal tool, and verify webhook delivery via HMAC signatures. The n8n integration (docs/22-n8n-integration.md) lets them trigger WhatsApp sends from workflow automation without writing custom HTTP calls.

Code Health & Issues

Static analysis found 15 findings (2 high, 13 medium). High: duplicated 6-line blocks across 17 dashboard files (e.g., ApiKeys.tsx, Webhooks.tsx), and deep nesting (max depth 8) in Plugins.tsx and ApiKeys.tsx. Medium: whatsapp-web-js.adapter.ts is 774 lines; api-key.guard.ts has 15 branch points over 53 lines. The dependency graph is clean — no cycles, and most modules have low instability.

The SDLC audit flagged three high-severity issues: GitHub Actions pinned to mutable tags (@v5, @v3) instead of commit SHAs; docker-compose.yml uses privileged mode with host networking; and .env.minimal is committed to the repo — rotate anything in it and git rm --cached it.

The Bottom Line

OpenWA is a credible, well-structured WhatsApp gateway with a real dashboard and SDKs. The codebase is organized and the module graph is clean. The security posture needs hardening before production — fix the pinned actions, the privileged container, and the committed .env first. It's a solid choice for teams that want full control over WhatsApp messaging without vendor lock-in.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

242 files

TypeScript130
Markdown28
TSX17
CSS15
JSON14
YAML7

ReactExpressNestJSDockerTransformers

Module dependencies

The 10 most depended-upon modules of 149, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_mmon_services_logger_service["logger.service"] n1_auth_entities_api_key_entity["api-key.entity"] n2_ules_session_session_service["session.service"] n3_src_core_hooks_index["index"] n4_sion_entities_session_entity["session.entity"] n5_dules_session_session_module["session.module"] n6_h_decorators_auth_decorators["auth.decorators"] n7_rd_src_components_PageHeader["PageHeader"] n8_d_src_hooks_useDocumentTitle["useDocumentTitle"] n9_dashboard_src_services_api["api"] n6_h_decorators_auth_decorators --> n1_auth_entities_api_key_entity n5_dules_session_session_module --> n4_sion_entities_session_entity n5_dules_session_session_module --> n2_ules_session_session_service n2_ules_session_session_service --> n4_sion_entities_session_entity n2_ules_session_session_service --> n0_mmon_services_logger_service n2_ules_session_session_service --> n3_src_core_hooks_index

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh6 occurrences

.github/workflows

codecov/codecov-action@v5, docker/setup-buildx-action@v3, docker/login-action@v3, docker/metadata-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Drop privileged mode and host networkinghigh

docker-compose.yml

the docker socket mounted

privileged hands the container every capability including direct device access, which makes escaping to the host a documented one-liner, and host networking removes the network boundary so every port the container opens is open on the host.

Fix: Grant the specific capability the workload needs with cap_add, and publish ports explicitly.

Remove the committed .env and rotate what it holdshigh

.env.minimal

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Pin the container base image by digestmedium2 occurrences

Dockerfile

node:22-slim, node:22-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Review the install lifecycle script and disable scripts in CImedium

package.json

postinstall

Install scripts are the execution vector for every npm compromise from event-stream onward, and a postinstall that fetches a binary makes the build depend on a URL nobody reviews.

Fix: Move the work into an explicit build step, or set ignore-scripts in CI and run it by name.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.