Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { LogLevel } from '../common/services/logger.service';
import { s3EndpointError, validateEnv } from './env.validation';
/** Regression locks for boot-time env validation (no silent coercion). */
describe('validateEnv', () => {
it('passes the zero-config default (sqlite, no pg vars)', () => {
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite' })).not.toThrow();
expect(() => validateEnv({})).not.toThrow();
});
it('rejects a DATABASE_TYPE typo instead of silently falling back to SQLite', () => {
expect(() => validateEnv({ DATABASE_TYPE: 'postgre' })).toThrow(/DATABASE_TYPE/);
});
it('requires host/username/password when DATABASE_TYPE=postgres', () => {
expect(() => validateEnv({ DATABASE_TYPE: 'postgres' })).toThrow(/DATABASE_PASSWORD/);
expect(() =>
validateEnv({ DATABASE_TYPE: 'postgres', DATABASE_HOST: 'db', DATABASE_USERNAME: 'u', DATABASE_PASSWORD: 'p' }),
).not.toThrow();
});
it('validates POSTGRES_SCHEMA as a legal, non-reserved Postgres identifier when set', () => {
const pg = { DATABASE_TYPE: 'postgres', DATABASE_HOST: 'db', DATABASE_USERNAME: 'u', DATABASE_PASSWORD: 'p' };
// unset / 'public' (default) and ordinary identifiers are fine
expect(() => validateEnv({ ...pg })).not.toThrow();
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'public' })).not.toThrow();
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'openwa' })).not.toThrow();
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'my_app_2' })).not.toThrow();
// invalid identifier characters (would reach CREATE TABLE "<schema>"."..." or a search_path SET)
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'openwa; DROP' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: '1bad' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'has space' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'a.b' })).toThrow(/POSTGRES_SCHEMA/);
// upper case rejected: the unquoted search_path folds it, TypeORM's quoted schema does not
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'OpenWA' })).toThrow(/lower-case/);
// reserved pg_ prefix rejected
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'pg_catalog' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'Pg_temp' })).toThrow(/POSTGRES_SCHEMA/);
// surrounding whitespace rejected, not trimmed: the app and the migration CLI use the raw value
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: ' openwa' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: 'openwa ' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: ' ' })).toThrow(/POSTGRES_SCHEMA/);
expect(() => validateEnv({ ...pg, POSTGRES_SCHEMA: '' })).not.toThrow();
// ignored for sqlite: a bogus value must NOT trip when not on postgres
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', POSTGRES_SCHEMA: '1bad' })).not.toThrow();
});
/**
* The media knobs take RAW numbers while `BODY_SIZE_LIMIT` beside them in .env.example takes a
* unit string. Their read sites use `Number.parseInt`, which takes the leading digits and drops
* the unit, so `50mb` was accepted as 50: a 50-byte cap, and `30s` a 30 ms timeout. Both are
* positive integers, so the "garbage falls back to the default" those helpers promise never
* fired. Boot has to be the place this stops.
*/
it('rejects a unit-suffixed media knob instead of reading its leading digits', () => {
expect(() => validateEnv({ MEDIA_DOWNLOAD_MAX_BYTES: '50mb' })).toThrow(/MEDIA_DOWNLOAD_MAX_BYTES/);
expect(() => validateEnv({ MEDIA_DOWNLOAD_TIMEOUT_MS: '30s' })).toThrow(/MEDIA_DOWNLOAD_TIMEOUT_MS/);
expect(() => validateEnv({ CHAT_HISTORY_MEDIA_BUDGET_BYTES: '25mb' })).toThrow(/CHAT_HISTORY_MEDIA_BUDGET_BYTES/);
expect(() => validateEnv({ INBOUND_MEDIA_CONCURRENCY: '4x' })).toThrow(/INBOUND_MEDIA_CONCURRENCY/);
});
it('rejects a non-positive media knob and accepts a plain byte count', () => {
expect(() => validateEnv({ MEDIA_DOWNLOAD_MAX_BYTES: '0' })).toThrow(/MEDIA_DOWNLOAD_MAX_BYTES/);
expect(() => validateEnv({ MEDIA_DOWNLOAD_MAX_BYTES: '-1' })).toThrow(/MEDIA_DOWNLOAD_MAX_BYTES/);
expect(() => validateEnv({ INBOUND_MEDIA_CONCURRENCY: 'abc' })).toThrow(/INBOUND_MEDIA_CONCURRENCY/);
expect(() => validateEnv({ MEDIA_DOWNLOAD_MAX_BYTES: '52428800' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_TIMEOUT_MS: '30000' })).not.toThrow();
});
it('accepts 0 for INBOUND_MEDIA_GLOBAL_CONCURRENCY (off) and rejects a negative or suffixed value', () => {
expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '0' })).not.toThrow();
expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '16' })).not.toThrow();
expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '-1' })).toThrow(/INBOUND_MEDIA_GLOBAL_CONCURRENCY/);
expect(() => validateEnv({ INBOUND_MEDIA_GLOBAL_CONCURRENCY: '4x' })).toThrow(/INBOUND_MEDIA_GLOBAL_CONCURRENCY/);
});
// Unset and empty stay the operator's way of taking the default; compose forwards a blank.
it('leaves an unset or blank media knob alone', () => {
expect(() => validateEnv({})).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_MAX_BYTES: '', MEDIA_DOWNLOAD_TIMEOUT_MS: ' ' })).not.toThrow();
});
it('rejects a non-integer / out-of-range port', () => {
expect(() => validateEnv({ DATABASE_PORT: 'abc' })).toThrow(/DATABASE_PORT/);
expect(() => validateEnv({ PORT: '70000' })).toThrow(/PORT/);
expect(() => validateEnv({ PORT: '2785' })).not.toThrow();
});
// main.ts listens on the raw PORT and the image healthcheck puts it in a URL verbatim, so a padded
// value would boot on 2785 while every probe of `http://localhost:2785 /...` fails as malformed.
it('rejects a PORT with surrounding whitespace and takes only an empty one as unset', () => {
expect(() => validateEnv({ PORT: '2785 ' })).toThrow(/PORT/);
expect(() => validateEnv({ PORT: ' 8080' })).toThrow(/PORT/);
expect(() => validateEnv({ PORT: ' ' })).toThrow(/PORT/);
expect(() => validateEnv({ PORT: '' })).not.toThrow();
});
it('rejects a non-numeric database timeout knob (a typo would become NaN and break the pg pool)', () => {
expect(() => validateEnv({ DATABASE_STATEMENT_TIMEOUT_MS: 'abc' })).toThrow(/DATABASE_STATEMENT_TIMEOUT_MS/);
expect(() => validateEnv({ DATABASE_IDLE_TIMEOUT_MS: '30s' })).toThrow(/DATABASE_IDLE_TIMEOUT_MS/);
expect(() => validateEnv({ DATABASE_CONNECTION_TIMEOUT_MS: '10000' })).not.toThrow();
});
it('rejects an ENGINE_TYPE typo instead of silently falling back to whatsapp-web.js', () => {
expect(() => validateEnv({ ENGINE_TYPE: 'bailys' })).toThrow(/ENGINE_TYPE/);
expect(() => validateEnv({ ENGINE_TYPE: 'whatsapp-web.js' })).not.toThrow();
expect(() => validateEnv({ ENGINE_TYPE: 'baileys' })).not.toThrow();
});
it('rejects a STORAGE_TYPE typo instead of silently falling back to local', () => {
expect(() => validateEnv({ STORAGE_TYPE: 'ss' })).toThrow(/STORAGE_TYPE/);
expect(() => validateEnv({ STORAGE_TYPE: 'local' })).not.toThrow();
expect(() => validateEnv({ STORAGE_TYPE: 's3' })).not.toThrow();
});
it('accepts MESSAGE_INLINE_MEDIA inline or archive, and refuses a typo', () => {
expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'inline' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive', CHAT_MEDIA_ARCHIVE_ENABLED: 'true' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archived' })).toThrow(/MESSAGE_INLINE_MEDIA must be one of/);
});
it('refuses MESSAGE_INLINE_MEDIA=archive without the archiver, which would silently do nothing', () => {
expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive' })).toThrow(
/MESSAGE_INLINE_MEDIA=archive needs CHAT_MEDIA_ARCHIVE_ENABLED=true/,
);
expect(() => validateEnv({ MESSAGE_INLINE_MEDIA: 'archive', CHAT_MEDIA_ARCHIVE_ENABLED: 'false' })).toThrow(
/needs CHAT_MEDIA_ARCHIVE_ENABLED=true/,
);
});
// The runtime compares these raw (`=== 'postgres'`, the engine plugin lookup, `=== 's3'`), so a
// padded value that only matches after trimming would validate here and then take the default branch.
it.each([
['DATABASE_TYPE', 'postgres '],
['DATABASE_TYPE', 'sqlite\r'],
['ENGINE_TYPE', 'baileys '],
['STORAGE_TYPE', ' s3'],
])('rejects a padded %s %j instead of validating the trimmed value', (key, value) => {
const pg = { DATABASE_HOST: 'db', DATABASE_USERNAME: 'u', DATABASE_PASSWORD: 'p' };
expect(() => validateEnv({ ...pg, [key]: value })).toThrow(new RegExp(`${key} must be`));
});
it('still treats a whitespace-only enum (a blank compose forward) as unset', () => {
expect(() => validateEnv({ DATABASE_TYPE: ' ', ENGINE_TYPE: '', STORAGE_TYPE: ' ' })).not.toThrow();
});
// Every production hardening in the repo compares NODE_ENV against the exact string 'production',
// so an unrecognised value silently selects the permissive branch of each one — including the
// ALLOW_DEV_API_KEY rejection that stops the public `dev-admin-key` being seeded as an ADMIN
// credential. A typo must fail the boot, not downgrade it.
// The knob that raises the message-list media budget parses with parseInt, so `8MiB` silently
// means 8 BYTES — every payload omitted — exactly the trap its sibling
// EXPORT_INLINE_MEDIA_BUDGET_BYTES is boot-checked for.
it('rejects a non-integer message-list media budget', () => {
expect(() => validateEnv({ MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES: '8MiB' })).toThrow(
/MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES/,
);
expect(() => validateEnv({ MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES: '8388608' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES: '0' })).not.toThrow();
});
it('rejects a NODE_ENV typo instead of silently selecting the permissive branch', () => {
expect(() => validateEnv({ NODE_ENV: 'prod' })).toThrow(/NODE_ENV/);
expect(() => validateEnv({ NODE_ENV: 'staging' })).toThrow(/NODE_ENV/);
expect(() => validateEnv({ NODE_ENV: 'Production' })).toThrow(/NODE_ENV/);
// Padded values must fail too: every reader compares the RAW `process.env.NODE_ENV` against
// 'production', so a value that only matches after trimming validates clean and then selects the
// permissive branch anyway — the exact silent downgrade this check exists to stop.
expect(() => validateEnv({ NODE_ENV: ' production ' })).toThrow(/NODE_ENV/);
expect(() => validateEnv({ NODE_ENV: 'production' })).not.toThrow();
expect(() => validateEnv({ NODE_ENV: 'development' })).not.toThrow();
expect(() => validateEnv({ NODE_ENV: 'test' })).not.toThrow();
// Unset stays legal: it is the standard Node default and every shipped deployment sets it
// explicitly (Dockerfile, both compose files, the Helm chart, .env.example).
expect(() => validateEnv({})).not.toThrow();
});
it('rejects a non-integer rate-limit / webhook / pool-size / redis-timeout / session-cap value', () => {
expect(() => validateEnv({ RATE_LIMIT_SHORT_LIMIT: 'abc' })).toThrow(/RATE_LIMIT_SHORT_LIMIT/);
expect(() => validateEnv({ WEBHOOK_TIMEOUT: '10s' })).toThrow(/WEBHOOK_TIMEOUT/);
expect(() => validateEnv({ DATABASE_POOL_SIZE: '1.5' })).toThrow(/DATABASE_POOL_SIZE/);
expect(() => validateEnv({ REDIS_CONNECT_TIMEOUT_MS: 'soon' })).toThrow(/REDIS_CONNECT_TIMEOUT_MS/);
expect(() => validateEnv({ MAX_CONCURRENT_SESSIONS: 'many' })).toThrow(/MAX_CONCURRENT_SESSIONS/);
expect(() => validateEnv({ RATE_LIMIT_LONG_TTL: '-5' })).toThrow(/RATE_LIMIT_LONG_TTL/);
// valid integers (and unset) still pass
expect(() =>
validateEnv({
RATE_LIMIT_SHORT_LIMIT: '10',
WEBHOOK_TIMEOUT: '10000',
DATABASE_POOL_SIZE: '10',
REDIS_CONNECT_TIMEOUT_MS: '5000',
MAX_CONCURRENT_SESSIONS: '0',
}),
).not.toThrow();
expect(() => validateEnv({})).not.toThrow();
});
it('rejects 0 for a rate-limit limit or window or the webhook timeout (self-DoS), but allows 0 where it is meaningful', () => {
expect(() => validateEnv({ RATE_LIMIT_SHORT_LIMIT: '0' })).toThrow(/RATE_LIMIT_SHORT_LIMIT/);
expect(() => validateEnv({ RATE_LIMIT_MEDIUM_LIMIT: '0' })).toThrow(/RATE_LIMIT_MEDIUM_LIMIT/);
expect(() => validateEnv({ RATE_LIMIT_LONG_LIMIT: '0' })).toThrow(/RATE_LIMIT_LONG_LIMIT/);
expect(() => validateEnv({ WEBHOOK_TIMEOUT: '0' })).toThrow(/WEBHOOK_TIMEOUT/);
// A 0 window expires every hit as it lands, which switches that tier off just as a 0 limit would.
for (const key of [
'RATE_LIMIT_SHORT_TTL',
'RATE_LIMIT_MEDIUM_TTL',
'RATE_LIMIT_LONG_TTL',
'INGRESS_INSTANCE_TTL',
]) {
expect(() => validateEnv({ [key]: '0' })).toThrow(new RegExp(`${key} must be a positive integer`));
}
// 0 stays valid where it has a real meaning: unlimited sessions, no webhook retry backoff.
expect(() => validateEnv({ MAX_CONCURRENT_SESSIONS: '0', WEBHOOK_RETRY_DELAY: '0' })).not.toThrow();
// a positive value still passes
expect(() => validateEnv({ RATE_LIMIT_SHORT_LIMIT: '10', WEBHOOK_TIMEOUT: '10000' })).not.toThrow();
});
it('rejects a non-positive / non-integer in-flight body budget (0 would refuse every body)', () => {
expect(() => validateEnv({ INFLIGHT_BODY_BUDGET_BYTES: '0' })).toThrow(/INFLIGHT_BODY_BUDGET_BYTES/);
expect(() => validateEnv({ INFLIGHT_BODY_BUDGET_BYTES: '100mb' })).toThrow(/INFLIGHT_BODY_BUDGET_BYTES/);
expect(() => validateEnv({ INFLIGHT_BODY_BUDGET_BYTES: '-5' })).toThrow(/INFLIGHT_BODY_BUDGET_BYTES/);
expect(() => validateEnv({ INFLIGHT_BODY_BUDGET_BYTES: '104857600' })).not.toThrow();
});
it('rejects a BODY_SIZE_LIMIT that refuses every body or would silently fall back to the default', () => {
for (const value of ['0', '0kb', '0.5', '50M', '50MiB', '50 MiB', 'abc']) {
expect(() => validateEnv({ BODY_SIZE_LIMIT: value })).toThrow(/BODY_SIZE_LIMIT must be a positive size/);
}
for (const value of ['25mb', '1.5gb', '1048576', '50 MB']) {
expect(() => validateEnv({ BODY_SIZE_LIMIT: value })).not.toThrow();
}
});
it('rejects a negative/non-integer webhook fan-out knob (0 is a documented escape hatch)', () => {
expect(() => validateEnv({ WEBHOOK_MAX_PER_SESSION: '-1' })).toThrow(/WEBHOOK_MAX_PER_SESSION/);
expect(() => validateEnv({ WEBHOOK_MAX_PER_SESSION: '1.5' })).toThrow(/WEBHOOK_MAX_PER_SESSION/);
expect(() => validateEnv({ WEBHOOK_MEDIA_INLINE_MAX_BYTES: 'abc' })).toThrow(/WEBHOOK_MEDIA_INLINE_MAX_BYTES/);
// 0 is meaningful for both: unlimited registrations / never inline media.
expect(() => validateEnv({ WEBHOOK_MAX_PER_SESSION: '0', WEBHOOK_MEDIA_INLINE_MAX_BYTES: '0' })).not.toThrow();
});
it('rejects a non-integer audit retention but accepts every value documented as "disable"', () => {
expect(() => validateEnv({ AUDIT_RETENTION_DAYS: 'ninety' })).toThrow(/AUDIT_RETENTION_DAYS/);
expect(() => validateEnv({ AUDIT_RETENTION_DAYS: '90.5' })).toThrow(/AUDIT_RETENTION_DAYS/);
expect(() => validateEnv({ AUDIT_RETENTION_DAYS: '30d' })).toThrow(/AUDIT_RETENTION_DAYS/);
// audit.service.ts and docs/05 both document `<= 0` as the off switch, so BOTH spellings must
// boot. Requiring non-negative here would refuse to start on a configuration the docs advertise.
expect(() => validateEnv({ AUDIT_RETENTION_DAYS: '0' })).not.toThrow();
expect(() => validateEnv({ AUDIT_RETENTION_DAYS: '-1' })).not.toThrow();
expect(() => validateEnv({ AUDIT_RETENTION_DAYS: '90' })).not.toThrow();
});
it('rejects a non-integer message retention and accepts 0 and negatives as "keep forever"', () => {
expect(() => validateEnv({ MESSAGE_RETENTION_DAYS: '30d' })).toThrow(/MESSAGE_RETENTION_DAYS/);
expect(() => validateEnv({ MESSAGE_RETENTION_DAYS: '0' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_RETENTION_DAYS: '-1' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_RETENTION_DAYS: '30' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_RETENTION_DAYS: '36500' })).not.toThrow();
expect(() => validateEnv({ MESSAGE_RETENTION_DAYS: '36501' })).toThrow(/MESSAGE_RETENTION_DAYS.*36500/);
});
// A "keep forever" row of nines binds on SQLite as a truncated year that sorts after today, so the
// prune would delete every row. Each retention window shares the message-retention cap.
it.each([
'AUDIT_RETENTION_DAYS',
'CHAT_MEDIA_ARCHIVE_TTL_DAYS',
'WEBHOOK_FAILURE_RETENTION_DAYS',
'WEBHOOK_OUTBOX_RETENTION_DAYS',
'INGRESS_RETENTION_DAYS',
'INGRESS_DEDUP_RETENTION_DAYS',
])('rejects a %s above 36500 days', key => {
expect(() => validateEnv({ [key]: '9999999' })).toThrow(new RegExp(`${key} must be at most 36500`));
expect(() => validateEnv({ [key]: '36501' })).toThrow(new RegExp(`${key} must be at most 36500`));
expect(() => validateEnv({ [key]: '36500' })).not.toThrow();
});
// The same 36500-day cutoff bound, in hours. A malformed value fell back to 0 downstream, which keeps no
// payload on a failure row and leaves the redrive endpoint nothing to replay, with no boot error.
it('rejects a malformed or oversized WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS and keeps 0 (no payload kept)', () => {
const key = 'WEBHOOK_FAILURE_PAYLOAD_RETENTION_HOURS';
for (const bad of ['24h', '-1', '1.5']) {
expect(() => validateEnv({ [key]: bad })).toThrow(new RegExp(`${key} must be a non-negative integer`));
}
expect(() => validateEnv({ [key]: '876001' })).toThrow(new RegExp(`${key} must be at most 876000`));
for (const ok of ['0', '24', '876000']) {
expect(() => validateEnv({ [key]: ok })).not.toThrow();
}
});
it('rejects a non-positive / non-integer WEBHOOK_MAX_PAYLOAD_BYTES (0 would reject every dispatch)', () => {
expect(() => validateEnv({ WEBHOOK_MAX_PAYLOAD_BYTES: '0' })).toThrow(/WEBHOOK_MAX_PAYLOAD_BYTES/);
expect(() => validateEnv({ WEBHOOK_MAX_PAYLOAD_BYTES: 'abc' })).toThrow(/WEBHOOK_MAX_PAYLOAD_BYTES/);
expect(() => validateEnv({ WEBHOOK_MAX_PAYLOAD_BYTES: '-5' })).toThrow(/WEBHOOK_MAX_PAYLOAD_BYTES/);
expect(() => validateEnv({ WEBHOOK_MAX_PAYLOAD_BYTES: '1048576' })).not.toThrow();
});
it('rejects non-decimal integer spellings that parseInt would silently truncate', () => {
// Number('1e6') is a valid integer, but the config readers use parseInt(raw, 10) — which reads
// `1e6` as 1 and `0x100` as 0. Validation must reject these so the validated value and the
// parsed value can never disagree.
expect(() => validateEnv({ WEBHOOK_MEDIA_INLINE_MAX_BYTES: '1e6' })).toThrow(/WEBHOOK_MEDIA_INLINE_MAX_BYTES/);
expect(() => validateEnv({ WEBHOOK_MEDIA_INLINE_MAX_BYTES: '0x100' })).toThrow(/WEBHOOK_MEDIA_INLINE_MAX_BYTES/);
expect(() => validateEnv({ PORT: '0x50' })).toThrow(/PORT/);
expect(() => validateEnv({ RATE_LIMIT_SHORT_TTL: '1e3' })).toThrow(/RATE_LIMIT_SHORT_TTL/);
// Plain decimal integers still pass.
expect(() => validateEnv({ WEBHOOK_MEDIA_INLINE_MAX_BYTES: '1048576', PORT: '2785' })).not.toThrow();
});
it('rejects a non-canonical boolean feature flag instead of silently disabling the feature', () => {
// QUEUE_ENABLED / MCP_ENABLED / SERVE_DASHBOARD are read at module-eval with `=== 'true'` /
// `!== 'false'`, so a typo silently (dis)ables the feature with zero diagnostics. Boot must reject it.
expect(() => validateEnv({ QUEUE_ENABLED: 'True' })).toThrow(/QUEUE_ENABLED/);
expect(() => validateEnv({ QUEUE_ENABLED: '1' })).toThrow(/QUEUE_ENABLED/);
expect(() => validateEnv({ MCP_ENABLED: 'yes' })).toThrow(/MCP_ENABLED/);
expect(() => validateEnv({ SERVE_DASHBOARD: 'no' })).toThrow(/SERVE_DASHBOARD/);
expect(() => validateEnv({ STATUS_SEED_ON_READY: 'yes' })).toThrow(/STATUS_SEED_ON_READY/);
// The raw value is checked, NOT a trimmed one: a trailing space / CR (Windows-edited env file
// forwarded verbatim by `docker run --env-file`) must still be rejected — otherwise the flag reads
// false at every `=== 'true'` site while validation passes, giving false assurance.
expect(() => validateEnv({ QUEUE_ENABLED: 'true ' })).toThrow(/QUEUE_ENABLED/);
expect(() => validateEnv({ MCP_ENABLED: 'true\r' })).toThrow(/MCP_ENABLED/);
// Canonical values, unset, and blank (a compose `${KEY:-}` forward renders '') all pass.
expect(() =>
validateEnv({
QUEUE_ENABLED: 'true',
MCP_ENABLED: 'false',
SERVE_DASHBOARD: 'true',
STATUS_SEED_ON_READY: 'false',
}),
).not.toThrow();
expect(() => validateEnv({ QUEUE_ENABLED: '', SERVE_DASHBOARD: '' })).not.toThrow();
expect(() => validateEnv({})).not.toThrow();
});
it('rejects a mistyped value for the datastore, webhook and engine booleans too', () => {
// Read with the same bare `=== 'true'` / `!== 'false'` comparison but absent from the strict list,
// so a typo configured the opposite of what the operator asked for, in silence. DATABASE_SSL is
// the one that fails OPEN: `require` is the natural Postgres spelling and reads as OFF, so a
// connection the operator believed was TLS-protected runs in plaintext.
expect(() => validateEnv({ DATABASE_SSL: 'require' })).toThrow(/DATABASE_SSL/);
expect(() => validateEnv({ DATABASE_SSL_REJECT_UNAUTHORIZED: '0' })).toThrow(/DATABASE_SSL_REJECT_UNAUTHORIZED/);
expect(() => validateEnv({ MAIN_DATABASE_SYNCHRONIZE: 'False' })).toThrow(/MAIN_DATABASE_SYNCHRONIZE/);
expect(() => validateEnv({ ALLOW_UNSIGNED_INGRESS: 'yes' })).toThrow(/ALLOW_UNSIGNED_INGRESS/);
expect(() => validateEnv({ ALLOW_DEV_API_KEY: '1' })).toThrow(/ALLOW_DEV_API_KEY/);
expect(() => validateEnv({ WEBHOOK_SSRF_PROTECT: 'off' })).toThrow(/WEBHOOK_SSRF_PROTECT/);
expect(() => validateEnv({ WEBHOOK_CONTACT_DETAILS: 'on' })).toThrow(/WEBHOOK_CONTACT_DETAILS/);
expect(() => validateEnv({ BAILEYS_SYNC_FULL_HISTORY: 'True' })).toThrow(/BAILEYS_SYNC_FULL_HISTORY/);
expect(() => validateEnv({ BAILEYS_WA_VERSION: '2.3000' })).toThrow(/BAILEYS_WA_VERSION/);
expect(() => validateEnv({ BAILEYS_WA_VERSION: '1.2.3' })).toThrow(/BAILEYS_WA_VERSION/);
expect(() => validateEnv({ BAILEYS_WA_VERSION: 'abc' })).toThrow(/BAILEYS_WA_VERSION/);
expect(() => validateEnv({ BAILEYS_WA_VERSION: '2.3000.1045340097' })).not.toThrow();
expect(() => validateEnv({ BAILEYS_WA_VERSION: '2,3000,1045340097' })).not.toThrow();
expect(() => validateEnv({ BAILEYS_MARK_ONLINE_ON_CONNECT: 'ture' })).toThrow(/BAILEYS_MARK_ONLINE_ON_CONNECT/);
expect(() => validateEnv({ POSTGRES_BUILTIN: 'yes' })).toThrow(/POSTGRES_BUILTIN/);
expect(() => validateEnv({ REDIS_BUILTIN: 'yes' })).toThrow(/REDIS_BUILTIN/);
expect(() => validateEnv({ MINIO_BUILTIN: 'yes' })).toThrow(/MINIO_BUILTIN/);
expect(() => validateEnv({ CACHE_ENABLED: '1' })).toThrow(/CACHE_ENABLED/);
expect(() => validateEnv({ DATABASE_LOGGING: '1' })).toThrow(/DATABASE_LOGGING/);
// Canonical values, and the blank a compose `${KEY:-}` forward renders, both stay legal.
expect(() => validateEnv({ DATABASE_SSL: 'true', MAIN_DATABASE_SYNCHRONIZE: 'false' })).not.toThrow();
expect(() => validateEnv({ DATABASE_SSL: '', WEBHOOK_SSRF_PROTECT: '' })).not.toThrow();
// Deliberately still tolerant, because both fail toward the SAFE state and the repo tests that
// tolerance: mcp.server.spec.ts asserts MCP_READONLY='yes' stays read-only, and
// PUPPETEER_HEADLESS='new' is a real Puppeteer value that works today.
expect(() => validateEnv({ MCP_READONLY: 'yes' })).not.toThrow();
expect(() => validateEnv({ PUPPETEER_HEADLESS: 'new' })).not.toThrow();
});
it('rejects a REDIS_ENABLED typo instead of silently downgrading throttler+cache to in-memory', () => {
// REDIS_ENABLED is read at boot with `=== 'true'` (throttler storage in app.module.ts,
// CacheService), so a typo flips rate limiting + caching to per-process in-memory with zero
// diagnostics — a silent behavior/security downgrade on a multi-replica deployment.
expect(() => validateEnv({ REDIS_ENABLED: 'ture' })).toThrow(/REDIS_ENABLED/);
expect(() => validateEnv({ REDIS_ENABLED: 'True' })).toThrow(/REDIS_ENABLED/);
expect(() => validateEnv({ REDIS_ENABLED: '1' })).toThrow(/REDIS_ENABLED/);
// Canonical values, blank (compose `${KEY:-}` forward), and unset all pass.
expect(() => validateEnv({ REDIS_ENABLED: 'true' })).not.toThrow();
expect(() => validateEnv({ REDIS_ENABLED: 'false' })).not.toThrow();
expect(() => validateEnv({ REDIS_ENABLED: '' })).not.toThrow();
expect(() => validateEnv({})).not.toThrow();
});
it.each(['MEDIA_CONVERSION_ENABLED', 'CHAT_MEDIA_ARCHIVE_ENABLED', 'CHAT_MEDIA_ARCHIVE_OUTBOUND'])(
'rejects a %s typo instead of silently leaving the feature off',
key => {
// Both are read at boot with `=== 'true'`, so a typo silently disables the feature and the
// endpoints answer as if it was never configured — the same silent-off class as SEND_PACING.
expect(() => validateEnv({ [key]: 'ture' })).toThrow(new RegExp(key));
expect(() => validateEnv({ [key]: 'True' })).toThrow(new RegExp(key));
expect(() => validateEnv({ [key]: 'true' })).not.toThrow();
expect(() => validateEnv({ [key]: 'false' })).not.toThrow();
expect(() => validateEnv({ [key]: '' })).not.toThrow();
},
);
it('rejects a MEDIA_DOWNLOAD_ENABLED typo instead of silently keeping the expensive default on', () => {
// The odd one out of the boolean family: it is read with `!== 'false' && !== '0' && !== 'no'`
// (inbound-media-cap.ts), so a typo does not disable a feature — it leaves inbound media being
// decrypted and base64-inlined into every message row, up to MEDIA_DOWNLOAD_MAX_BYTES apiece.
// An operator who typed it to turn that OFF gets the most expensive behaviour the gateway has,
// with no diagnostics anywhere.
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: 'fasle' })).toThrow(/MEDIA_DOWNLOAD_ENABLED/);
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: 'ture' })).toThrow(/MEDIA_DOWNLOAD_ENABLED/);
// Unlike the strict family this flag is read through a NORMALISING parser — inbound-media-cap.ts
// trims and lowercases, and inbound-media-cap.spec.ts asserts 'FALSE' / ' false ' disable. Those
// spellings demonstrably work, so validation must not reject them; only a value the read site
// cannot recognise at all is a mistake worth failing the boot for.
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: 'False' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: ' false ' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: '0' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: 'no' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: 'true' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: 'false' })).not.toThrow();
expect(() => validateEnv({ MEDIA_DOWNLOAD_ENABLED: '' })).not.toThrow();
});
it('rejects a SEARCH_PROVIDER typo instead of silently falling back to auto', () => {
// A bogus / typo value must fail fast at boot rather than silently selecting the default provider.
expect(() => validateEnv({ SEARCH_PROVIDER: 'bogus' })).toThrow(/SEARCH_PROVIDER/);
// The three documented values are accepted.
expect(() => validateEnv({ SEARCH_PROVIDER: 'auto' })).not.toThrow();
expect(() => validateEnv({ SEARCH_PROVIDER: 'builtin-fts' })).not.toThrow();
expect(() => validateEnv({ SEARCH_PROVIDER: 'none' })).not.toThrow();
// Unset is accepted (the configuration default of 'auto' applies downstream).
expect(() => validateEnv({})).not.toThrow();
});
it('rejects a SEARCH_CONTAINS_ENABLED typo instead of silently leaving contains search off', () => {
expect(() => validateEnv({ SEARCH_CONTAINS_ENABLED: 'yes' })).toThrow(/SEARCH_CONTAINS_ENABLED/);
expect(() => validateEnv({ SEARCH_CONTAINS_ENABLED: 'true' })).not.toThrow();
expect(() => validateEnv({ SEARCH_CONTAINS_ENABLED: '' })).not.toThrow();
});
it('rejects a LOG_LEVEL misspelling instead of silently logging at info', () => {
// Plausible spellings from neighbouring vocabularies that this repo's LogLevel does not carry;
// every one of them silently meant INFO before this check existed.
expect(() => validateEnv({ LOG_LEVEL: 'warning' })).toThrow(/LOG_LEVEL/);
expect(() => validateEnv({ LOG_LEVEL: 'log' })).toThrow(/LOG_LEVEL/); // Nest's spelling
expect(() => validateEnv({ LOG_LEVEL: 'trace' })).toThrow(/LOG_LEVEL/); // Baileys' vocabulary
// The reader (main.ts) trims and lowercases before matching, so these keep booting.
expect(() => validateEnv({ LOG_LEVEL: 'DEBUG' })).not.toThrow();
expect(() => validateEnv({ LOG_LEVEL: ' warn ' })).not.toThrow();
// Unset means INFO and passes.
expect(() => validateEnv({})).not.toThrow();
});
it('accepts exactly the LogLevel values main.ts applies, no more and no fewer', () => {
// env.validation.ts keeps its own copy of the level list while main.ts matches against the enum.
// The rejection message prints that copy, so comparing it with the enum catches drift either way.
const levels: string[] = Object.values(LogLevel);
for (const level of levels) {
expect(() => validateEnv({ LOG_LEVEL: level })).not.toThrow();
}
expect(() => validateEnv({ LOG_LEVEL: 'nope' })).toThrow(
`LOG_LEVEL must be one of ${levels.map(v => `"${v}"`).join(', ')} (got "nope")`,
);
});
it('rejects a sqlite data DB path that collides with the internal main database file', () => {
// The 'main' (auth/audit) and 'data' connections must be separate SQLite files; sharing one
// file means two migration ledgers + synchronize policies on the same tables.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: './data/main.sqlite' })).toThrow(
/DATABASE_NAME/,
);
// Relative spellings of the same file are caught (path normalization).
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: './data/../data/main.sqlite' })).toThrow(
/DATABASE_NAME/,
);
// The default data path is fine.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: './data/openwa.sqlite' })).not.toThrow();
// Postgres uses a bare DB name, never a file path — must not false-positive.
expect(() =>
validateEnv({
DATABASE_TYPE: 'postgres',
DATABASE_HOST: 'db',
DATABASE_USERNAME: 'u',
DATABASE_PASSWORD: 'p',
DATABASE_NAME: 'main.sqlite',
}),
).not.toThrow();
});
it('resolves the main DB path from MAIN_DATABASE_NAME like the runtime (no false-negative/-positive)', () => {
// The runtime main path is MAIN_DATABASE_NAME || ./data/main.sqlite (configuration.ts). When it
// is overridden, a DATABASE_NAME following it to the same file must still be caught — comparing
// against the hardcoded default alone would miss this.
expect(() =>
validateEnv({
DATABASE_TYPE: 'sqlite',
MAIN_DATABASE_NAME: '/srv/openwa/main.sqlite',
DATABASE_NAME: '/srv/openwa/main.sqlite',
}),
).toThrow(/DATABASE_NAME/);
// Same collision via a non-normalized spelling (relative/absolute forms of one file).
expect(() =>
validateEnv({
DATABASE_TYPE: 'sqlite',
MAIN_DATABASE_NAME: './custom/main.sqlite',
DATABASE_NAME: './custom/../custom/main.sqlite',
}),
).toThrow(/DATABASE_NAME/);
// And the reverse: when MAIN_DATABASE_NAME moves the main DB elsewhere, the DEFAULT main file
// is no longer the runtime main DB, so using it for data must NOT be rejected.
expect(() =>
validateEnv({
DATABASE_TYPE: 'sqlite',
MAIN_DATABASE_NAME: '/srv/openwa/main.sqlite',
DATABASE_NAME: './data/main.sqlite',
}),
).not.toThrow();
// Distinct overridden paths pass.
expect(() =>
validateEnv({
DATABASE_TYPE: 'sqlite',
MAIN_DATABASE_NAME: './data/auth.sqlite',
DATABASE_NAME: './data/openwa.sqlite',
}),
).not.toThrow();
});
it("catches MAIN_DATABASE_NAME pointing at the data connection's default file", () => {
// DATABASE_NAME unset resolves to ./data/openwa.sqlite at runtime, so the guard must compare that.
expect(() => validateEnv({ MAIN_DATABASE_NAME: './data/openwa.sqlite' })).toThrow(/\.\/data\/openwa\.sqlite/);
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', MAIN_DATABASE_NAME: './data/../data/openwa.sqlite' })).toThrow(
/main database file/,
);
});
// The bundled PostgreSQL container runs without TLS: a built-in database with DATABASE_SSL=true would retry its
// connection until the boot gives up, so the boot refuses it at once and names the key.
describe('DATABASE_SSL with the built-in PostgreSQL container', () => {
const builtIn = {
DATABASE_TYPE: 'postgres',
POSTGRES_BUILTIN: 'true',
DATABASE_HOST: 'postgres',
DATABASE_USERNAME: 'openwa',
DATABASE_PASSWORD: 'openwa',
};
it.each(['postgres', 'Postgres', 'postgres.', 'openwa-postgres'])('refuses it beside the host %j', host => {
expect(() => validateEnv({ ...builtIn, DATABASE_HOST: host, DATABASE_SSL: 'true' })).toThrow(
/DATABASE_SSL=true .*built-in PostgreSQL container/,
);
});
it('accepts it off, and on for another host or without the built-in flag', () => {
expect(() => validateEnv({ ...builtIn, DATABASE_SSL: 'false' })).not.toThrow();
expect(() => validateEnv({ ...builtIn, DATABASE_HOST: 'db.ext.example', DATABASE_SSL: 'true' })).not.toThrow();
// A server of its own named postgres (a Kubernetes Service, a compose service with TLS set up) may serve TLS.
expect(() => validateEnv({ ...builtIn, POSTGRES_BUILTIN: 'false', DATABASE_SSL: 'true' })).not.toThrow();
});
});
it('rejects DATABASE_SYNCHRONIZE=true with DATABASE_TYPE=postgres (drops body_ts → /search 501)', () => {
// The Postgres data connection hardcodes migrationsRun=true; an opted-in synchronize=true makes
// TypeORM re-sync from entities on every boot, dropping the migration-created `body_ts` generated
// tsvector column (not declared on the Message entity) → /search 501 every restart. The breaking
// combo must fail fast at boot.
expect(() =>
validateEnv({
DATABASE_TYPE: 'postgres',
DATABASE_HOST: 'db',
DATABASE_USERNAME: 'u',
DATABASE_PASSWORD: 'p',
DATABASE_SYNCHRONIZE: 'true',
}),
).toThrow(/DATABASE_SYNCHRONIZE.*postgres|migrations/);
// The production default (synchronize=false / unset) is fine on Postgres.
expect(() =>
validateEnv({
DATABASE_TYPE: 'postgres',
DATABASE_HOST: 'db',
DATABASE_USERNAME: 'u',
DATABASE_PASSWORD: 'p',
DATABASE_SYNCHRONIZE: 'false',
}),
).not.toThrow();
expect(() =>
validateEnv({
DATABASE_TYPE: 'postgres',
DATABASE_HOST: 'db',
DATABASE_USERNAME: 'u',
DATABASE_PASSWORD: 'p',
}),
).not.toThrow();
// SQLite is migration-managed only when synchronize is unset/false, but the combo is NOT breaking
// there (SQLite has no generated-column migration to drop), so it stays allowed.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_SYNCHRONIZE: 'true' })).not.toThrow();
});
it('rejects a bare SQLite DATABASE_NAME (PG-name leak) that has no path separator or file extension', () => {
// Regression for #677: .env.example shipped `DATABASE_NAME=openwa` (a PostgreSQL db name).
// In a SQLite run that bare name becomes the file PATH → SQLite opens a file named 'openwa'
// under the read-only app rootfs → SQLITE_CANTOPEN boot-loop. The guard catches the leak at boot.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: 'openwa' })).toThrow(/file path/);
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: 'prod_db' })).toThrow(/file path/);
// A bare name WITH a .sqlite/.db suffix is a legitimate file in the cwd — let it pass.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: 'openwa.sqlite' })).not.toThrow();
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: 'cache.db' })).not.toThrow();
// A path (with a separator) is always honored, explicit host paths included.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: '/app/data/openwa.sqlite' })).not.toThrow();
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite', DATABASE_NAME: './data/openwa.sqlite' })).not.toThrow();
// Unset falls through to the default path (configuration.ts) — the boot-loop fix.
expect(() => validateEnv({ DATABASE_TYPE: 'sqlite' })).not.toThrow();
});
// A renewal that does not fit inside the lease renews too late to matter: the claim lapses between
// ticks and peers adopt sessions from a healthy node, with nothing in the logs saying why.
it('rejects a lease heartbeat that does not comfortably fit inside the TTL', () => {
expect(() => validateEnv({ SESSION_LEASE_TTL_MS: '60000', SESSION_LEASE_HEARTBEAT_MS: '50000' })).toThrow(
/less than half/,
);
// The defaults stand in for whatever is unset, so a lone oversized heartbeat cannot slip past.
expect(() => validateEnv({ SESSION_LEASE_HEARTBEAT_MS: '45000' })).toThrow(/less than half/);
expect(() => validateEnv({ SESSION_LEASE_TTL_MS: '20000' })).toThrow(/less than half/);
expect(() => validateEnv({ SESSION_LEASE_TTL_MS: '120000', SESSION_LEASE_HEARTBEAT_MS: '30000' })).not.toThrow();
// Exactly half is rejected too: a single missed renewal then lands on the expiry instant.
expect(() => validateEnv({ SESSION_LEASE_TTL_MS: '60000', SESSION_LEASE_HEARTBEAT_MS: '30000' })).toThrow(
/less than half/,
);
expect(() => validateEnv({})).not.toThrow();
});
// The forwarder builds an absolute URL from NODE_URL; a scheme-less value only fails at the first
// forward, as a 500 on a request that had nothing wrong with it.
it('rejects a NODE_URL that is not an absolute http(s) URL', () => {
expect(() => validateEnv({ NODE_URL: 'localhost:2785' })).toThrow(/absolute http/);
expect(() => validateEnv({ NODE_URL: '10.0.0.5:2785' })).toThrow(/absolute http/);
expect(() => validateEnv({ NODE_URL: 'ftp://10.0.0.5' })).toThrow(/absolute http/);
// Embedded credentials parse as a valid URL but undici's fetch refuses them, so reject at boot.
expect(() => validateEnv({ NODE_URL: 'http://user:[email protected]:2785' })).toThrow(/must not embed credentials/);
expect(() => validateEnv({ NODE_URL: 'http://10.0.0.5:2785' })).not.toThrow();
expect(() => validateEnv({ NODE_URL: 'https://node-a.internal' })).not.toThrow();
});
// Without a scheme the S3 client throws "Invalid URL" on every call and media quietly lands on local disk. That
// deployment runs today, so the boot reports the endpoint instead of refusing it (validateEnv never throws for
// it); the Infrastructure save is what refuses.
describe('S3_ENDPOINT', () => {
const s3 = (S3_ENDPOINT: string | undefined, STORAGE_TYPE = 's3') => ({ STORAGE_TYPE, S3_ENDPOINT });
it.each(['minio:9000', '127.0.0.1:9000', 'localhost:9000', 'minio', 'ftp://minio:9000'])(
'reports %s while S3 is the selected storage, and still lets validateEnv pass',
endpoint => {
expect(s3EndpointError(s3(endpoint))).toMatch(/^S3_ENDPOINT must be an absolute http\(s\) URL/);
expect(() => validateEnv(s3(endpoint))).not.toThrow();
},
);
it('says where to fix it', () => {
expect(s3EndpointError(s3('minio:9000'))).toMatch(
/environment, \.\/\.env or data\/\.env\.generated, or on the Infrastructure page/,
);
});
it('does not echo the value, which may carry credentials', () => {
const message = s3EndpointError(s3('AKIAKEY:hunter2@s3host:9000'));
expect(message).toMatch(/S3_ENDPOINT/);
expect(message).not.toMatch(/hunter2|AKIAKEY|s3host/);
});
it.each([
'http://minio:9000',
'https://s3.example.com',
'https://gateway.example.com/s3/',
' http://minio:9000 ',
'HTTP://minio:9000',
])('accepts %s', endpoint => {
expect(s3EndpointError(s3(endpoint))).toBeNull();
});
it('leaves an unset or blank endpoint alone, and a stale one while storage is local', () => {
expect(s3EndpointError(s3(undefined))).toBeNull();
expect(s3EndpointError(s3(' '))).toBeNull();
expect(s3EndpointError(s3('minio:9000', 'local'))).toBeNull();
expect(s3EndpointError({ S3_ENDPOINT: 'minio:9000' })).toBeNull();
});
});
it('rejects a non-positive media-conversion knob instead of silently using the default', () => {
expect(() => validateEnv({ MEDIA_CONVERSION_CONCURRENCY: '0' })).toThrow(/positive integer/);
expect(() => validateEnv({ MEDIA_CONVERSION_TIMEOUT_MS: 'abc' })).toThrow(/positive integer/);
expect(() => validateEnv({ MEDIA_CONVERSION_MAX_OUTPUT_BYTES: '52428800' })).not.toThrow();
});
// Read with parseInt and a `> 0` guard, so `1h` became a 1 ms sweep interval rather than the default.
it.each([
'CHAT_MEDIA_ARCHIVE_MAX_BYTES',
'CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS',
'CHAT_MEDIA_ORPHAN_GRACE_MS',
'STATUS_MEDIA_MAX_BYTES',
'STATUS_ORPHAN_SWEEP_INTERVAL_MS',
'STATUS_ORPHAN_GRACE_MS',
'S3_REPROBE_INTERVAL_MS',
'STORAGE_EXPORT_TTL_MS',
'STORAGE_EXPORT_SWEEP_MAX_AGE_MS',
'WEBHOOK_DEGRADED_SESSION_CONCURRENCY',
])('rejects a unit-suffixed or non-positive %s and accepts a plain count', key => {
expect(() => validateEnv({ [key]: '1h' })).toThrow(new RegExp(`${key} must be a positive integer`));
expect(() => validateEnv({ [key]: '0' })).toThrow(new RegExp(`${key} must be a positive integer`));
expect(() => validateEnv({ [key]: '3600000' })).not.toThrow();
});
// Each read fell back to the default on 0 or garbage, or passed a negative or fractional value on.
it.each(['SEARCH_LIMIT_MAX', 'INGRESS_MAX_ATTEMPTS', 'WEBHOOK_WORKER_CONCURRENCY', 'INGRESS_WORKER_CONCURRENCY'])(
'rejects a non-positive or non-integer %s and accepts a plain count',
key => {
for (const bad of ['0', '-5', '2.5', 'abc', '5x']) {
expect(() => validateEnv({ [key]: bad })).toThrow(new RegExp(`${key} must be a positive integer`));
}
expect(() => validateEnv({ [key]: '7' })).not.toThrow();
expect(() => validateEnv({ [key]: '' })).not.toThrow();
expect(() => validateEnv({ [key]: ' ' })).not.toThrow();
},
);
// The prefix is joined to the queue name with a colon in every Redis key.
it('accepts a plain QUEUE_PREFIX, or none, and rejects one that would build ambiguous keys', () => {
for (const ok of ['bull', 'openwa-staging', 'prod_2.eu', 'a', '0', '', ' ']) {
expect(() => validateEnv({ QUEUE_PREFIX: ok })).not.toThrow();
}
for (const bad of ['a:b', 'has space', '-lead', '.lead', 'a/b', 'x'.repeat(65)]) {
expect(() => validateEnv({ QUEUE_PREFIX: bad })).toThrow(/QUEUE_PREFIX must be 1 to 64/);
}
expect(() => validateEnv({ QUEUE_PREFIX: 'x'.repeat(64) })).not.toThrow();
});
// Read as an exact 'true'/'false' override; anything else falls back to the NODE_ENV default, so
// CSP_UPGRADE_INSECURE_REQUESTS=False kept the blank-dashboard trap on in production.
it.each([
'CSP_UPGRADE_INSECURE_REQUESTS',
'ENABLE_SWAGGER',
'VALIDATION_ERROR_DETAIL',
'PLUGIN_INSTALL_REQUIRE_PIN',
'WEBHOOK_SSRF_REDIRECTS',
])('accepts only an exact true or false for %s', key => {
for (const bad of ['False', 'TRUE', '0', 'false\r']) {
expect(() => validateEnv({ [key]: bad })).toThrow(new RegExp(`${key} must be "true" or "false"`));
}
for (const ok of ['true', 'false', '']) {
expect(() => validateEnv({ [key]: ok })).not.toThrow();
}
});
it('accepts only an exact true or false for REDIS_TLS', () => {
expect(() => validateEnv({ REDIS_TLS: 'yes' })).toThrow(/REDIS_TLS must be "true" or "false"/);
expect(() => validateEnv({ REDIS_TLS: 'true ' })).toThrow(/REDIS_TLS/);
expect(() => validateEnv({ REDIS_TLS: 'true' })).not.toThrow();
expect(() => validateEnv({ REDIS_TLS: '' })).not.toThrow();
});
// BAILEYS_GROUP_METADATA_CACHE_TTL_MS: 0 switches the cache off, and the reader falls back to five minutes
// on `5m`, so only boot validation tells the operator the value was refused.
it.each(['INGRESS_RETRY_DELAY_MS', 'REDIS_CACHE_DB', 'BAILEYS_GROUP_METADATA_CACHE_TTL_MS'])(
'rejects a negative or non-integer %s and keeps 0',
key => {
for (const bad of ['-1', '1.5', 'abc', '5m']) {
expect(() => validateEnv({ [key]: bad })).toThrow(new RegExp(`${key} must be a non-negative integer`));
}
expect(() => validateEnv({ [key]: '0' })).not.toThrow();
expect(() => validateEnv({ [key]: '300000' })).not.toThrow();
expect(() => validateEnv({ [key]: '' })).not.toThrow();
},
);
it('rejects a unit-suffixed CHAT_MEDIA_ARCHIVE_TTL_DAYS but keeps 0 (keep forever)', () => {
expect(() => validateEnv({ CHAT_MEDIA_ARCHIVE_TTL_DAYS: '30d' })).toThrow(/CHAT_MEDIA_ARCHIVE_TTL_DAYS/);
expect(() => validateEnv({ CHAT_MEDIA_ARCHIVE_TTL_DAYS: '0' })).not.toThrow();
});
// parseInt reads a unit-suffixed value as its leading digits: `5mb` became a 5-byte plugin download cap.
it.each([
['PLUGIN_DOWNLOAD_MAX_BYTES', '5mb'],
['PLUGIN_STORAGE_MAX_BYTES', '50mb'],
['PLUGIN_CAP_TIMEOUT_MS', '30s'],
['TEMPLATE_RENDER_MAX_CHARS', '64k'],
['STORAGE_IMPORT_MAX_BYTES', '200mb'],
['STORAGE_IMPORT_MAX_ENTRIES', '1e5'],
['STORAGE_IMPORT_MAX_TOTAL_BYTES', '10gb'],
['BAILEYS_MESSAGE_STORE_LIMIT', '5k'],
])('rejects a unit-suffixed or zero %s', (key, bad) => {
expect(() => validateEnv({ [key]: bad })).toThrow(new RegExp(`${key} must be a positive integer`));
expect(() => validateEnv({ [key]: '0' })).toThrow(new RegExp(`${key} must be a positive integer`));
expect(() => validateEnv({ [key]: '1000' })).not.toThrow();
});
it('rejects a unit-suffixed SHUTDOWN_DELAY_MS but keeps 0 (no drain)', () => {
expect(() => validateEnv({ SHUTDOWN_DELAY_MS: '3s' })).toThrow(/SHUTDOWN_DELAY_MS must be a non-negative integer/);
expect(() => validateEnv({ SHUTDOWN_DELAY_MS: '0' })).not.toThrow();
});
it('rejects a malformed WEBHOOK_SHUTDOWN_DRAIN_MS but keeps 0 (no wait), like the other shutdown knobs', () => {
// A malformed value was silently replaced by 5000, which also sets the force-exit budget, so a typo
// such as `30s` quietly cut the drain the operator asked for.
for (const bad of ['30s', '-5', 'abc', '1.5']) {
expect(() => validateEnv({ WEBHOOK_SHUTDOWN_DRAIN_MS: bad })).toThrow(
/WEBHOOK_SHUTDOWN_DRAIN_MS must be a non-negative integer/,
);
}
expect(() => validateEnv({ WEBHOOK_SHUTDOWN_DRAIN_MS: '0' })).not.toThrow();
expect(() => validateEnv({ WEBHOOK_SHUTDOWN_DRAIN_MS: '12000' })).not.toThrow();
});
it.each([
'WEBHOOK_FAILURE_RETENTION_DAYS',
'WEBHOOK_OUTBOX_RETENTION_DAYS',
'INGRESS_RETENTION_DAYS',
'INGRESS_DEDUP_RETENTION_DAYS',
])('rejects a non-integer %s and keeps 0 and negatives', key => {
expect(() => validateEnv({ [key]: 'ninety' })).toThrow(new RegExp(`${key} must be an integer`));
expect(() => validateEnv({ [key]: '30d' })).toThrow(new RegExp(`${key} must be an integer`));
expect(() => validateEnv({ [key]: '0' })).not.toThrow();
expect(() => validateEnv({ [key]: '-1' })).not.toThrow();
});
// Node fires a timer delay above 2^31-1 ms after 1 ms, so these would spin instead of waiting.
it.each([
'MEDIA_CONVERSION_TIMEOUT_MS',
'CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS',
'STATUS_ORPHAN_SWEEP_INTERVAL_MS',
'S3_REPROBE_INTERVAL_MS',
'STORAGE_EXPORT_TTL_MS',
'MESSAGE_REAPER_INTERVAL_MS',
'WEBHOOK_RECONCILE_INTERVAL_MS',
'INGRESS_RECONCILE_INTERVAL_MS',
'SESSION_TAKEOVER_SWEEP_MS',
'SESSION_PROXY_TIMEOUT_MS',
'MEDIA_DOWNLOAD_TIMEOUT_MS',
'WEBHOOK_TIMEOUT',
'RATE_LIMIT_SHORT_TTL',
'RATE_LIMIT_MEDIUM_TTL',
'RATE_LIMIT_LONG_TTL',
'INGRESS_INSTANCE_TTL',
])('rejects a %s above the Node timer ceiling', key => {
expect(() => validateEnv({ [key]: '2147483648' })).toThrow(new RegExp(`${key} must not exceed 2147483647 ms`));
expect(() => validateEnv({ [key]: '2147483647' })).not.toThrow();
});
// 0 disables each sweep; a negative value used to boot clean and keep the sweep running.
it.each(['MESSAGE_REAPER_INTERVAL_MS', 'WEBHOOK_RECONCILE_INTERVAL_MS', 'INGRESS_RECONCILE_INTERVAL_MS'])(
'rejects a negative %s and keeps 0 as the off switch',
key => {
expect(() => validateEnv({ [key]: '-1' })).toThrow(new RegExp(`${key} must be a non-negative integer`));
expect(() => validateEnv({ [key]: '0' })).not.toThrow();
},
);
// A huge grace builds a cutoff whose year SQLite binds in wrapped form, matching fresh rows.
it.each(['MESSAGE_REAPER_GRACE_MS', 'WEBHOOK_RECONCILE_GRACE_MS', 'INGRESS_RECONCILE_GRACE_MS'])(
'rejects a malformed or oversized %s',
key => {
expect(() => validateEnv({ [key]: '1h' })).toThrow(new RegExp(`${key} must be a non-negative integer`));
expect(() => validateEnv({ [key]: '-1' })).toThrow(new RegExp(`${key} must be a non-negative integer`));
expect(() => validateEnv({ [key]: '999999999999999' })).toThrow(
new RegExp(`${key} must be at most 3153600000000`),
);
expect(() => validateEnv({ [key]: '3153600000000' })).not.toThrow();
expect(() => validateEnv({ [key]: '0' })).not.toThrow();
},
);
it('rejects a non-positive or overflowing SSRF_DNS_TIMEOUT_MS', () => {
expect(() => validateEnv({ SSRF_DNS_TIMEOUT_MS: '0' })).toThrow(/SSRF_DNS_TIMEOUT_MS must be a positive integer/);
expect(() => validateEnv({ SSRF_DNS_TIMEOUT_MS: '10s' })).toThrow(/SSRF_DNS_TIMEOUT_MS must be a positive integer/);
expect(() => validateEnv({ SSRF_DNS_TIMEOUT_MS: '2147483648' })).toThrow(
/SSRF_DNS_TIMEOUT_MS must not exceed 2147483647 ms/,
);
expect(() => validateEnv({ SSRF_DNS_TIMEOUT_MS: '2147483647' })).not.toThrow();
});
// pg arms these with setTimeout and sends statement_timeout to a server capped at INT_MAX; 0 still disables.
it.each(['DATABASE_CONNECTION_TIMEOUT_MS', 'DATABASE_IDLE_TIMEOUT_MS', 'DATABASE_STATEMENT_TIMEOUT_MS'])(
'rejects a %s above 2147483647 ms and keeps 0',
key => {
expect(() => validateEnv({ [key]: '99999999999' })).toThrow(new RegExp(`${key} must not exceed 2147483647 ms`));
expect(() => validateEnv({ [key]: '2147483647' })).not.toThrow();
expect(() => validateEnv({ [key]: '0' })).not.toThrow();
},
);
it('rejects a SESSION_LEASE_HEARTBEAT_MS above the Node timer ceiling even inside a longer lease', () => {
const lease = { SESSION_LEASE_TTL_MS: '5000000000' };
expect(() => validateEnv({ ...lease, SESSION_LEASE_HEARTBEAT_MS: '2147483648' })).toThrow(
/SESSION_LEASE_HEARTBEAT_MS must not exceed 2147483647 ms/,
);
expect(() => validateEnv({ ...lease, SESSION_LEASE_HEARTBEAT_MS: '2147483647' })).not.toThrow();
});
// Send verbs arm four times this budget, so its ceiling is a quarter of the timer ceiling.
it('rejects a PLUGIN_CAP_TIMEOUT_MS whose send-verb budget overflows the Node timer ceiling', () => {
expect(() => validateEnv({ PLUGIN_CAP_TIMEOUT_MS: '536870912' })).toThrow(
/PLUGIN_CAP_TIMEOUT_MS must not exceed 536870911 ms/,
);
expect(() => validateEnv({ PLUGIN_CAP_TIMEOUT_MS: '536870911' })).not.toThrow();
});
// A direct (queue-off) delivery doubles the delay on each retry, up to 2^3 for the maximum retryCount of 5.
it('rejects a WEBHOOK_RETRY_DELAY whose last direct-delivery backoff overflows the Node timer ceiling', () => {
expect(() => validateEnv({ WEBHOOK_RETRY_DELAY: '268435456' })).toThrow(
/WEBHOOK_RETRY_DELAY must not exceed 268435455 ms/,
);
expect(() => validateEnv({ WEBHOOK_RETRY_DELAY: '268435455' })).not.toThrow();
});
});
// The bundled Redis container runs a plaintext listener with only its default user. A connection that
// asks for TLS, or authenticates as a named user, fails on every attempt, as the bundled PostgreSQL does
// with DATABASE_SSL=true.
describe('validateEnv built-in Redis connection settings', () => {
const builtin = { REDIS_ENABLED: 'true', REDIS_BUILTIN: 'true', REDIS_HOST: 'redis' };
describe('REDIS_TLS', () => {
it.each(['redis', 'REDIS.', 'openwa-redis'])('rejects TLS against the bundled host %s', host => {
expect(() => validateEnv({ ...builtin, REDIS_HOST: host, REDIS_TLS: 'true' })).toThrow(/REDIS_TLS/);
});
it.each(['QUEUE_ENABLED', 'CACHE_ENABLED'])('rejects it when only %s uses Redis', consumer => {
expect(() => validateEnv({ ...builtin, REDIS_ENABLED: 'false', [consumer]: 'true', REDIS_TLS: 'true' })).toThrow(
/REDIS_TLS/,
);
});
it('says where to fix it and names the external Redis way out', () => {
const message = () => {
try {
validateEnv({ ...builtin, REDIS_TLS: 'true' });
} catch (error) {
return (error as Error).message;
}
return '';
};
expect(message()).toMatch(/set REDIS_TLS=false in the environment, \.\/\.env or data\/\.env\.generated/);
expect(message()).toMatch(
/use an external Redis \(REDIS_BUILTIN=false with its REDIS_HOST, also on the Infrastructure page\)/,
);
});
it('keeps TLS to an external host, and accepts plaintext or a Redis nothing uses', () => {
expect(() => validateEnv({ ...builtin, REDIS_HOST: 'cache.example.com', REDIS_TLS: 'true' })).not.toThrow();
expect(() => validateEnv({ ...builtin, REDIS_TLS: 'false' })).not.toThrow();
expect(() => validateEnv({ ...builtin, REDIS_ENABLED: 'false', REDIS_TLS: 'true' })).not.toThrow();
expect(() => validateEnv({ ...builtin, REDIS_BUILTIN: 'false', REDIS_TLS: 'true' })).not.toThrow();
});
});
describe('REDIS_USERNAME', () => {
it.each(['REDIS_ENABLED', 'QUEUE_ENABLED', 'CACHE_ENABLED'])('rejects a named user for %s', consumer => {
expect(() =>
validateEnv({ ...builtin, REDIS_ENABLED: 'false', [consumer]: 'true', REDIS_USERNAME: 'worker' }),
).toThrow(/REDIS_USERNAME/);
});
// The username is passed to the server as written, so only the exact word `default` names the default user.
it.each(['DEFAULT', 'default ', ' '])('does not normalize the user name %j', username => {
expect(() => validateEnv({ ...builtin, REDIS_USERNAME: username })).toThrow(/REDIS_USERNAME/);
});
it.each([undefined, '', 'default'])('accepts the default user as %j', username => {
expect(() => validateEnv({ ...builtin, REDIS_USERNAME: username })).not.toThrow();
});
it('says where to fix it and names the external Redis way out', () => {
expect(() => validateEnv({ ...builtin, REDIS_USERNAME: 'worker' })).toThrow(
/remove the named username in the environment, \.\/\.env or data\/\.env\.generated, or use an external Redis \(REDIS_BUILTIN=false with its REDIS_HOST, also on the Infrastructure page\)/,
);
});
it('keeps a named user for an external host, and accepts one when Redis is not the bundled one in use', () => {
expect(() =>
validateEnv({ ...builtin, REDIS_HOST: 'cache.example.com', REDIS_USERNAME: 'worker' }),
).not.toThrow();
expect(() => validateEnv({ ...builtin, REDIS_BUILTIN: 'false', REDIS_USERNAME: 'worker' })).not.toThrow();
expect(() => validateEnv({ ...builtin, REDIS_ENABLED: 'false', REDIS_USERNAME: 'worker' })).not.toThrow();
});
});
});