Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
// The env loader MUST be the first import: it populates process.env from .env / data/.env.generated
// before any other module is evaluated, so modules that read process.env at import time (e.g. the
// webhook Worker's @Processor connection) see the configured values rather than pre-dotenv defaults.
import './config/load-env';
import { NestFactory } from '@nestjs/core';
import { INestApplication, ShutdownSignal } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { SwaggerModule } from '@nestjs/swagger';
import { AppModule, DASHBOARD_DIST, dashboardServingEnabled, dashboardBuildPresent } from './app.module';
import { ShutdownService } from './common/services/shutdown.service';
import { LoggerService, LogLevel, createLogger } from './common/services/logger.service';
import {
createSwaggerConfig,
documentErrorResponses,
dropUnexpressibleOperations,
exemptPublicOperations,
} from './config/swagger.config';
import { registerUncaughtExceptionMonitor, registerUnhandledRejectionHandler } from './config/process-error-monitor';
import { runBootstrapOrExit } from './config/bootstrap-fatal';
import { s3EndpointError, validateEnv } from './config/env.validation';
import { warnUnusableAllowedHosts } from './common/security/ssrf-guard';
import { resolveStorageRoot } from './config/storage-root';
import { applyHttpTimeouts, HttpTimeoutConfig, HttpTimeoutSink } from './config/http-timeouts';
import { applyGlobalValidation } from './config/app-validation';
import { configureApp } from './configure-app';
import {
isSwaggerEnabled,
isDashboardCspUpgradeTrapLikely,
assertNoDefaultSecretsInProduction,
isApiKeyPepperMissingInProduction,
isMainDbSynchronizeInProduction,
isNodeEnvUnset,
rewrittenCorsOrigins,
} from './config/bootstrap-security';
import { BullBoardAuthMiddleware } from './common/security/bull-board-auth.middleware';
import { invalidTrustedProxies } from './common/utils/ip';
import { AuthService } from './modules/auth/auth.service';
import { AuditService } from './modules/audit/audit.service';
import { Request, Response, NextFunction } from 'express';
import { RedisIoAdapter } from './modules/events/redis-io.adapter';
import { prestartBuiltinDatabase } from './modules/docker/docker.service';
// The created app, exposed at module scope so the fatal handler below can run a best-effort teardown
// (engine sessions, Redis/pg) when bootstrap fails AFTER NestFactory.create succeeded — notably a
// listen() bind failure (EADDRINUSE), where full init already ran.
let appInstance: INestApplication | undefined;
async function bootstrap() {
// Apply the operator-configured log verbosity (LOG_LEVEL) before anything logs. Unset means INFO.
// A misspelling is skipped here; validateEnv below rejects it before the boot has any side effect.
const requestedLevel = process.env.LOG_LEVEL?.trim().toLowerCase();
if (requestedLevel && (Object.values(LogLevel) as string[]).includes(requestedLevel)) {
LoggerService.setLogLevel(requestedLevel as LogLevel);
}
// Backstop for promise rejections that escaped a local handler (e.g. a fire-and-forget engine-event
// dispatch), including the expected engine-teardown case it downgrades to a warning (see the helper).
const bootstrapLogger = createLogger('Bootstrap');
registerUnhandledRejectionHandler(bootstrapLogger);
// A synchronous throw from a non-promise context (e.g. a sync timer callback) is fatal — Node prints a
// raw stack to stderr, bypassing the structured log pipeline, and exits(1). Route the stack through the
// logger WITHOUT swallowing the exception, so the crash-and-restart posture is unchanged (see the helper).
registerUncaughtExceptionMonitor(bootstrapLogger);
// Validate the environment before anything acts on it. ConfigModule.forRoot runs the same check, but
// only once NestFactory.create awaits it, which is after the storage root is created and a built-in
// PostgreSQL container is started; an invalid config would do both and then be reported twice.
validateEnv(process.env);
// Reported, not refused: with S3 selected and an endpoint the client cannot use, the instance runs today on its
// local fallback directory, so an upgrade must not turn that into a crash loop. The Infrastructure save refuses it.
const s3EndpointProblem = s3EndpointError(process.env);
if (s3EndpointProblem) {
bootstrapLogger.error(
`${s3EndpointProblem}. Until then S3 is unavailable and media is written to the local directory.`,
);
}
// Reported at boot, where the operator reads the log, rather than at the first outbound request.
warnUnusableAllowedHosts();
// Advisory (not enforced): an unset/blank NODE_ENV is the deliberate local-dev default, but it
// silently degrades four controls to their dev posture (the default-secret guard, wildcard CORS,
// Swagger UI, validation error detail) — warn so a production deployment that simply forgot the
// variable can tell. The defaults themselves stay unchanged.
if (isNodeEnvUnset(process.env.NODE_ENV)) {
bootstrapLogger.warn(
'NODE_ENV is not set: running with development defaults — the default-secret guard is skipped, ' +
'wildcard CORS is allowed, Swagger UI is served, and validation error detail is exposed. ' +
'Set NODE_ENV=production for a production deployment.',
);
}
// Fail fast: never start production with default/placeholder secrets.
assertNoDefaultSecretsInProduction({
nodeEnv: process.env.NODE_ENV,
databaseType: process.env.DATABASE_TYPE,
databasePassword: process.env.DATABASE_PASSWORD,
postgresBuiltIn: process.env.POSTGRES_BUILTIN,
databaseHost: process.env.DATABASE_HOST,
storageType: process.env.STORAGE_TYPE,
minioBuiltIn: process.env.MINIO_BUILTIN,
s3Endpoint: process.env.S3_ENDPOINT,
// Mirror storage.service's canonical-with-legacy fallback so the guard inspects the var the app
// actually uses (it reads S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY first).
s3AccessKey: process.env.S3_ACCESS_KEY_ID || process.env.S3_ACCESS_KEY,
s3SecretKey: process.env.S3_SECRET_ACCESS_KEY || process.env.S3_SECRET_KEY,
apiMasterKey: process.env.API_MASTER_KEY,
allowDevApiKey: process.env.ALLOW_DEV_API_KEY,
redisPassword: process.env.REDIS_PASSWORD,
metricsToken: process.env.METRICS_TOKEN,
});
// Advisory (not enforced): without API_KEY_PEPPER, stored API-key hashes use plain SHA-256. Enabling
// a pepper on an install with keys locks every key out (see api-key-hash.ts), so we only nudge the operator.
if (isApiKeyPepperMissingInProduction(process.env.NODE_ENV, process.env.API_KEY_PEPPER)) {
bootstrapLogger.warn(
'API_KEY_PEPPER is not set in production: stored API-key hashes use plain SHA-256. ' +
'Set API_KEY_PEPPER before the first boot to enable HMAC hashing; on an install with keys it locks out ' +
'every key until the previous pepper is restored, or api_keys is cleared and the instance restarted to ' +
'seed a new admin key.',
);
}
// Advisory (not enforced): the main DB normally runs its migration chain; synchronize is an opt-in.
if (isMainDbSynchronizeInProduction(process.env.NODE_ENV, process.env.MAIN_DATABASE_SYNCHRONIZE)) {
bootstrapLogger.warn(
'MAIN_DATABASE_SYNCHRONIZE=true in production: after its migrations the auth/audit schema is also ' +
"synchronized to this release's entities, and those changes are not recorded in the migration ledger. " +
'Unset it to use the main migrations alone.',
);
}
// Advisory (not enforced): a TRUSTED_PROXIES entry that is not an IP or CIDR never matches, so the
// proxy it meant to name is treated as a client. Failing the boot would break configs that run today.
const badTrustedProxies = invalidTrustedProxies(process.env.TRUSTED_PROXIES);
if (badTrustedProxies.length > 0) {
bootstrapLogger.warn(
`TRUSTED_PROXIES entries that are not an IP address or CIDR range are ignored: ${badTrustedProxies.join(', ')}`,
);
}
// Advisory: an origin copied from the address bar carries a path or a trailing slash that a browser never
// sends in `Origin`. It is used without them, which is what the operator meant.
const rewrittenOrigins = rewrittenCorsOrigins(process.env.CORS_ORIGINS);
if (rewrittenOrigins.length > 0) {
bootstrapLogger.warn(
`CORS_ORIGINS entries are used as an origin, without their path or trailing slash: ${rewrittenOrigins.join(', ')}`,
);
}
// Fail fast on a media storage root the app cannot write to, BEFORE Nest builds the module graph:
// StorageService only checks that the root EXISTS, so a root owned by another user passes boot and
// fails later on the first media write instead (#1065). Runs ahead of NestFactory.create so
// configuration.ts reads the resolved value.
process.env.STORAGE_LOCAL_PATH = resolveStorageRoot({
configured: process.env.STORAGE_LOCAL_PATH,
logger: bootstrapLogger,
});
// The data connection dials PostgreSQL inside NestFactory.create, so a stopped built-in container
// must be started before it, not from DockerService.onModuleInit (see the helper).
await prestartBuiltinDatabase();
// Disable Nest's default body parser so we can set an explicit size cap below. Framework lines
// (route mapping, unhandled-exception stacks) go through the app logger so LOG_LEVEL, LOG_FORMAT and
// the request id apply to them too.
// forceCloseConnections: the HTTP close runs after every destroy hook, and a request still in flight
// would hold it until the force-exit; destroying the open sockets there keeps it at 0 s in the
// shutdown budget (shutdown-budget.ts). It also cuts in-flight requests and WebSocket clients at that
// point (the socket.io server is not closed first), after the destroy hooks have run.
const app = await NestFactory.create(AppModule, {
bodyParser: false,
logger: createLogger('Nest'),
forceCloseConnections: true,
});
appInstance = app;
// Cross-replica WebSocket fan-out: when Redis is enabled, broadcasts reach clients on every
// replica, not just this process. Set before the gateway's namespace is created so it inherits
// the adapter. Inert (plain in-memory adapter) without REDIS_ENABLED, so single-node pays nothing.
app.useWebSocketAdapter(new RedisIoAdapter(app));
// The production HTTP surface: request context, the CSP nonce, helmet, the SPA document handler,
// CORS, the encoded-NUL refusal, in-flight body budget, body parsers and the trailing-slash DELETE
// refusal. Extracted so the e2e lane runs the SAME stack instead of a copy of it (src/configure-app.ts).
const { bodyLimit, inflightBudgetBytes } = configureApp(app);
bootstrapLogger.log(`Request body caps: ${bodyLimit} per request, ${inflightBudgetBytes} bytes aggregate in flight`);
// Let Nest own every shutdown signal EXCEPT SIGTERM/SIGINT — those we route through the bounded
// drain below, so a load balancer / orchestrator observes readiness=503 and stops routing BEFORE
// teardown begins. (enableShutdownHooks with an EMPTY array registers ALL signals; this filtered
// list is non-empty, so the exclusion is honoured.)
app.enableShutdownHooks(
Object.values(ShutdownSignal).filter(s => s !== ShutdownSignal.SIGTERM && s !== ShutdownSignal.SIGINT),
);
// Wire up graceful shutdown service
const shutdownService = app.get(ShutdownService);
shutdownService.setShutdownCallback(async () => {
await app.close();
});
// On SIGTERM/SIGINT: drain gracefully. shutdown() flips readiness to 503 immediately (the LB stops
// routing), keeps serving in-flight requests for a bounded grace, then runs app.close() (the SAME
// Nest lifecycle hooks Nest's own handler would run) and exits deterministically. A SECOND signal
// forces an immediate exit — a dev double-Ctrl+C, or an operator not willing to wait out a wedged
// teardown. The gate is a dedicated "a signal already arrived" flag, NOT isShuttingDown() (which an
// admin restart also sets) — so a first real signal during an admin-restart grace still drains
// gracefully instead of hard-exiting.
let signalReceived = false;
for (const signal of ['SIGTERM', 'SIGINT'] as const) {
process.on(signal, () => {
if (signalReceived) {
process.exit(130);
}
signalReceived = true;
shutdownService.shutdown();
});
}
// Shared production/e2e prefix and DTO validation contract.
applyGlobalValidation(app);
// Swagger documentation. ENABLE_SWAGGER wins; otherwise default on outside production, off in
// production (the API schema is reconnaissance surface — production opts in with ENABLE_SWAGGER=true).
const swaggerEnabled = isSwaggerEnabled(process.env.ENABLE_SWAGGER, process.env.NODE_ENV);
if (swaggerEnabled) {
const config = createSwaggerConfig();
const document = SwaggerModule.createDocument(app, config);
// Same passes, in the same order, as scripts/export-openapi.ts. The document is produced in
// TWO places — here for the live /api/docs and there for the committed snapshot — and fixing only
// the snapshot leaves a running gateway serving a document that fails schema validation.
dropUnexpressibleOperations(document);
exemptPublicOperations(document);
documentErrorResponses(document);
SwaggerModule.setup('api/docs', app, document);
}
// Protect the Bull Board queue UI (/api/admin/queues). It is mounted by
// @bull-board/nestjs as raw Express middleware that the global ApiKeyGuard
// does not cover; registering this before app.listen() ensures it runs ahead
// of the Bull Board router. Requires a valid ADMIN API key. The middleware also
// writes the audit trail for this mount (auth failures + queue mutations).
const bullBoardAuth = new BullBoardAuthMiddleware(
app.get(AuthService),
app.get(ConfigService),
app.get(AuditService),
);
app.use('/api/admin/queues', (req: Request, res: Response, next: NextFunction) => {
void bullBoardAuth.use(req, res, next);
});
// Apply explicit HTTP server timeouts so they are operator-tunable (REQUEST_TIMEOUT_MS /
// HEADERS_TIMEOUT_MS / KEEPALIVE_TIMEOUT_MS) and observable at boot, instead of Node's implicit
// defaults. Done after the adapter exists and before listen(). Target MUST be the http.Server
// (app.getHttpServer()) — NOT getHttpAdapter().getInstance(), which is the Express APPLICATION
// (a function with no requestTimeout/headersTimeout/keepAliveTimeout props); writing onto it is
// inert. The timeouts only take effect on the real server.
const appliedHttpTimeouts = applyHttpTimeouts(
app.getHttpServer() as HttpTimeoutSink,
app.get(ConfigService).get<HttpTimeoutConfig>('http')!,
);
bootstrapLogger.log(
`HTTP server timeouts applied: requestTimeout=${appliedHttpTimeouts.requestTimeoutMs}ms ` +
`headersTimeout=${appliedHttpTimeouts.headersTimeoutMs}ms keepAliveTimeout=${appliedHttpTimeouts.keepAliveTimeoutMs}ms`,
);
const port = process.env.PORT || 2785;
await app.listen(port);
// Advertise the configured public URL, matching the AuthService banner (auth.service.ts). A bare
// `localhost` literal here contradicted that banner and read as "the UI is pinned to localhost",
// sending #731 chasing BASE_URL/BIND_HOST/API_PORT instead of the real cause.
const publicUrl = process.env.BASE_URL || `http://localhost:${port}`;
bootstrapLogger.log(`OpenWA is running on: ${publicUrl}`);
if (swaggerEnabled) {
bootstrapLogger.log(`Swagger docs: ${publicUrl}/api/docs`);
}
// Make the dashboard-serving outcome explicit so a missing build (no UI on `/`)
// is obvious instead of a silent 404.
if (!dashboardServingEnabled) {
bootstrapLogger.log('Dashboard: serving disabled (SERVE_DASHBOARD=false); API only');
} else if (dashboardBuildPresent) {
bootstrapLogger.log(`Dashboard: serving bundled UI at ${publicUrl}`);
} else {
bootstrapLogger.warn(
`Dashboard: no build at ${DASHBOARD_DIST} - UI disabled (API still serves /api). ` +
'Run `npm run build:all` to bundle it, or use the Vite dev server (`npm run dev`).',
);
}
// The upgrade-insecure-requests trap (#731): the browser upgrades the UI's own script fetches to
// https and a non-TLS server can't answer them, so the dashboard renders blank with nothing in the
// server log. We can't tell a TLS proxy from direct HTTP at boot (`trust proxy` is off), so this
// fires for both and the text says who should ignore it.
if (
isDashboardCspUpgradeTrapLikely({
nodeEnv: process.env.NODE_ENV,
cspEnv: process.env.CSP_UPGRADE_INSECURE_REQUESTS,
dashboardServed: dashboardServingEnabled && dashboardBuildPresent,
})
) {
bootstrapLogger.warn(
'Dashboard: CSP upgrade-insecure-requests is ON (production default). If this instance is ' +
"reached over plain HTTP, the browser will upgrade the UI's scripts to https:// and the " +
'dashboard will render blank. Behind a TLS proxy? Ignore this. Serving direct HTTP? Set ' +
'CSP_UPGRADE_INSECURE_REQUESTS=false.',
);
}
}
// A failed bootstrap MUST terminate the process with a non-zero code, not just set `process.exitCode`:
// listen() runs the full module init (database, Redis, plugin registration) before binding the port, and
// the detached session auto-start (SessionService.onApplicationBootstrap) is already launching engines by
// then, so a bind failure (EADDRINUSE) would otherwise leave a zombie process: no HTTP port, yet still
// holding the event loop open and running WhatsApp sessions, invisible to Docker's restart policy.
// runBootstrapOrExit logs the failure, runs a bounded best-effort app.close() teardown, then exits(1); a
// successful boot returns without touching exit. Puppeteer's own `exit` handlers kill any browser
// children still up.
void runBootstrapOrExit(bootstrap, {
logger: createLogger('Bootstrap'),
closeApp: () => (appInstance ? appInstance.close() : Promise.resolve()),
});