Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(config): reject a mixed-case or padded POSTGRES_SCHEMA
Yudhi Armyndharis7db588c4e07f
diff --git a/.env.example b/.env.exampleindex dd409f25c..f5191b272 100644--- a/.env.example+++ b/.env.example@@ -309,6 +309,7 @@ OPENWA_PIDS_LIMIT=2048# Postgres where you get a project schema, or to share one DB across apps). The schema must# already exist — the built-in container creates it; for external/managed Postgres create it# once (CREATE SCHEMA openwa;). A missing schema fails fast at migration time.+# Lower case only (letters, digits, underscores): boot rejects upper case.# POSTGRES_SCHEMA=public# DATABASE_USERNAME=openwa# MUST set a strong, unique value before using Postgres — no default is shipped.diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex aba3202a2..d17f05632 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -90,9 +90,9 @@ The container can still be coming up when the `data` connection first dials it,When using PostgreSQL, OpenWA can place its tables and migration ledger in a dedicated schema via the `POSTGRES_SCHEMA` environment variable:-| Setting | Default | Description |-| ----------------- | -------- | ---------------------------------------------------------------- |-| `POSTGRES_SCHEMA` | `public` | PostgreSQL schema for OpenWA tables and TypeORM migration ledger |+| Setting | Default | Description |+| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------- |+| `POSTGRES_SCHEMA` | `public` | PostgreSQL schema for OpenWA tables and TypeORM migration ledger (lower-case letters, digits and underscores) |**Use Cases:**diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 5960130df..91565e858 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -5444,7 +5444,7 @@ Merge-save infrastructure config to `data/.env.generated` (a `0600` secret file)| `database.type` | `'sqlite' \| 'postgres'` | If `database` is present | enum | `sqlite` drops stale postgres keys; `postgres` writes connection keys || `database.builtIn` | boolean | No | — | When `true`+postgres, forces the bundled `postgres` container creds + pushes `postgres` Docker profile || `database.host` / `.port` / `.username` / `.database` | string | No | `port` is a string | External postgres connection (defaults `localhost`/`5432`/`postgres`/`openwa`) |-| `database.schema` | string | No | — | Postgres schema, saved as `POSTGRES_SCHEMA`; an empty value writes `public` (also forced to `public` when switching to the built-in DB) |+| `database.schema` | string | No | lower-case, no `pg_` prefix (else 400) | Postgres schema, saved as `POSTGRES_SCHEMA`; an empty value writes `public` (also forced to `public` when switching to the built-in DB) || `database.password` | string | No | secret | Empty/omitted keeps the existing stored secret || `database.poolSize` | number | No | — | Default 10 || `database.sslEnabled` | boolean | No | — | Default false |diff --git a/scripts/postgres-init-schema.sh b/scripts/postgres-init-schema.shindex c957bb828..c8779ec05 100755--- a/scripts/postgres-init-schema.sh+++ b/scripts/postgres-init-schema.sh@@ -25,14 +25,15 @@ fi# The value is interpolated into the CREATE SCHEMA / SET search_path statements below, so apply# the same boot-time validation the app does (src/config/env.validation.ts): a plain, non-reserved-# Postgres identifier or nothing. Fail fast here rather than let a typo reach the SQL.-identifier_re='^[A-Za-z_][A-Za-z0-9_]{0,62}$'+# Postgres identifier or nothing. Fail fast here rather than let a typo reach the SQL. Lower case+# only: the app sets an unquoted search_path, which Postgres folds to lower case.+identifier_re='^[a-z_][a-z0-9_]{0,62}$'if ! [[ "$schema" =~ $identifier_re ]]; then- echo "postgres-init-schema: ERROR: POSTGRES_SCHEMA must be a valid Postgres identifier (a letter or underscore, then letters/digits/underscores, max 63 chars; got '${schema}')." >&2+ echo "postgres-init-schema: ERROR: POSTGRES_SCHEMA must be a valid lower-case Postgres identifier (a lower-case letter or underscore, then lower-case letters/digits/underscores, max 63 chars; got '${schema}')." >&2exit 1ficase "$schema" in- [pP][gG]_*)+ pg_*)echo "postgres-init-schema: ERROR: POSTGRES_SCHEMA must not use the reserved \"pg_\" prefix (got '${schema}')." >&2exit 1;;diff --git a/src/config/env.validation.spec.ts b/src/config/env.validation.spec.tsindex 2570db83c..298fb5f5a 100644--- a/src/config/env.validation.spec.ts+++ b/src/config/env.validation.spec.ts@@ -31,9 +31,16 @@ describe('validateEnv', () => {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/);- // reserved pg_ prefix rejected (case-insensitive)+ // 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 rejectedexpect(() => 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 postgresexpect(() => validateEnv({ DATABASE_TYPE: 'sqlite', POSTGRES_SCHEMA: '1bad' })).not.toThrow();});diff --git a/src/config/env.validation.ts b/src/config/env.validation.tsindex c2a2705b2..3c4758300 100644--- a/src/config/env.validation.ts+++ b/src/config/env.validation.ts@@ -41,6 +41,20 @@ export function sqliteDataMainPathCollision(config: EnvConfig): string | null {return null;}+/**+ * POSTGRES_SCHEMA rule shared by boot validation and the Infrastructure save path: a legal,+ * non-reserved, lower-case Postgres identifier. Returns the error message, or null when valid.+ */+export function postgresSchemaError(schema: string): string | null {+ if (!/^[a-z_][a-z0-9_]{0,62}$/.test(schema)) {+ return `POSTGRES_SCHEMA must be a valid lower-case Postgres identifier (a lower-case letter or underscore, then lower-case letters/digits/underscores, max 63 chars; got ${JSON.stringify(schema)})`;+ }+ if (schema.startsWith('pg_')) {+ return `POSTGRES_SCHEMA must not use the reserved "pg_" prefix (got ${JSON.stringify(schema)})`;+ }+ return null;+}+/*** Fail-fast environment validation. Wired as ConfigModule's `validate`* callback so a misconfigured deployment is rejected at BOOT instead of silently@@ -115,15 +129,14 @@ export function validateEnv(config: EnvConfig): EnvConfig {// POSTGRES_SCHEMA is optional (defaults to 'public' in configuration.ts). When set, validate it// is a legal, non-reserved Postgres identifier so a typo / injection-ish value fails fast at boot// rather than reaching CREATE TABLE "<schema>"."..." (or a search_path SET) at migration time.- const pgSchema = str('POSTGRES_SCHEMA');- if (pgSchema !== undefined) {- if (!/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(pgSchema)) {- errors.push(- `POSTGRES_SCHEMA must be a valid Postgres identifier (a letter or underscore, then letters/digits/underscores, max 63 chars; got ${JSON.stringify(pgSchema)})`,- );- } else if (pgSchema.toLowerCase().startsWith('pg_')) {- errors.push(`POSTGRES_SCHEMA must not use the reserved "pg_" prefix (got ${JSON.stringify(pgSchema)})`);- }+ // Lower case only: the search_path startup option is unquoted, so Postgres folds it to lower+ // case, while TypeORM quotes the schema. A mixed-case name would split DDL and queries across+ // two schemas. The raw value is checked, untrimmed: the app and the migration CLI both use it+ // as set, so a padded (or whitespace-only) value must fail here as it fails in the CLI.+ const pgSchema = config.POSTGRES_SCHEMA;+ const pgSchemaError = typeof pgSchema === 'string' && pgSchema !== '' ? postgresSchemaError(pgSchema) : null;+ if (pgSchemaError) {+ errors.push(pgSchemaError);}} else {// SQLite (explicit or default): DATABASE_NAME is a file path for the 'data' connection. It mustdiff --git a/src/database/data-source.spec.ts b/src/database/data-source.spec.tsindex 6f579a8f7..dbebfc049 100644--- a/src/database/data-source.spec.ts+++ b/src/database/data-source.spec.ts@@ -55,6 +55,28 @@ describe('data CLI DataSource', () => {jest.resetModules();}});++ it('refuses to load a postgres CLI connection with a mixed-case POSTGRES_SCHEMA', () => {+ // search_path is unquoted (folded to lower case) while TypeORM quotes the schema, so migration DDL+ // and the ledger would land in two different schemas.+ const prevType = process.env.DATABASE_TYPE;+ const prevSchema = process.env.POSTGRES_SCHEMA;+ process.env.DATABASE_TYPE = 'postgres';+ process.env.POSTGRES_SCHEMA = 'OpenWA';+ jest.resetModules();+ try {+ expect(() => {+ // eslint-disable-next-line @typescript-eslint/no-require-imports+ require('./data-source');+ }).toThrow(/POSTGRES_SCHEMA/);+ } finally {+ if (prevType !== undefined) process.env.DATABASE_TYPE = prevType;+ else delete process.env.DATABASE_TYPE;+ if (prevSchema !== undefined) process.env.POSTGRES_SCHEMA = prevSchema;+ else delete process.env.POSTGRES_SCHEMA;+ jest.resetModules();+ }+ });});// The migration CLI connection runs DDL (CREATE INDEX, unique backfills) that can legitimately takediff --git a/src/database/data-source.ts b/src/database/data-source.tsindex 5b6070814..3bd173b22 100644--- a/src/database/data-source.ts+++ b/src/database/data-source.ts@@ -2,7 +2,7 @@ import { DataSource, DataSourceOptions } from 'typeorm';import * as path from 'path';import { loadCliEnv } from './load-cli-env';import { postgresUtcExtra } from './postgres-utc';-import { sqliteDataMainPathCollision } from '../config/env.validation';+import { postgresSchemaError, sqliteDataMainPathCollision } from '../config/env.validation';// Load env with the same precedence as the app (process.env > .env > data/.env.generated), so the// migration CLI targets the SAME database the dashboard configured — not the default SQLite DB.@@ -20,6 +20,15 @@ if (sqlitePathCollision) {const dbType = process.env.DATABASE_TYPE || 'sqlite';+// Same POSTGRES_SCHEMA rule as boot: a mixed-case name is quoted by TypeORM (ledger) but folded to+// lower case in the unquoted search_path (raw migration DDL), splitting one migration run across two+// schemas.+const pgSchemaError =+ dbType === 'postgres' && process.env.POSTGRES_SCHEMA ? postgresSchemaError(process.env.POSTGRES_SCHEMA) : null;+if (pgSchemaError) {+ throw new Error(pgSchemaError);+}+const sourceGlob = (...segments: string[]): string => path.join(__dirname, ...segments).replace(/\\/g, '/');// Scoped to the DATA-owned modules only (session/webhook/message/template/engine/integration/status-store), mirroringdiff --git a/src/modules/infra/config-sections.ts b/src/modules/infra/config-sections.tsindex 6e7005067..3f7b9559f 100644--- a/src/modules/infra/config-sections.ts+++ b/src/modules/infra/config-sections.ts@@ -1,4 +1,5 @@import { BadRequestException } from '@nestjs/common';+import { postgresSchemaError } from '../../config/env.validation';import type { EngineFactory } from '../../engine/engine.factory';import { DatabaseConfigDto, EngineConfigDto, RedisConfigDto, StorageConfigDto } from './dto/save-config.dto';@@ -66,7 +67,12 @@ export function applyDatabaseSection(if (database.username !== undefined) updates.DATABASE_USERNAME = database.username || 'postgres';setSecret(updates, 'DATABASE_PASSWORD', database.password);if (database.database !== undefined) updates.DATABASE_NAME = database.database || 'openwa';- if (database.schema !== undefined) updates.POSTGRES_SCHEMA = database.schema || 'public';+ if (database.schema !== undefined) {+ // Refuse a schema the next boot would reject, or the saved file crash-loops the instance.+ const schemaError = database.schema ? postgresSchemaError(database.schema) : null;+ if (schemaError) throw new BadRequestException(schemaError);+ updates.POSTGRES_SCHEMA = database.schema || 'public';+ }}if (database.poolSize !== undefined) {updates.DATABASE_POOL_SIZE = String(database.poolSize || 10);diff --git a/src/modules/infra/infra-config.controller.spec.ts b/src/modules/infra/infra-config.controller.spec.tsindex 339e16b93..9744de16d 100644--- a/src/modules/infra/infra-config.controller.spec.ts+++ b/src/modules/infra/infra-config.controller.spec.ts@@ -92,6 +92,25 @@ describe('InfraConfigController PostgreSQL schema (POSTGRES_SCHEMA)', () => {expect(preserved).toContain('POSTGRES_SCHEMA=openwa');});+ it('refuses a schema the next boot would reject instead of writing it', () => {+ (fs.writeFileSync as jest.Mock).mockClear();+ for (const schema of ['OpenWA', 'pg_data', 'bad-name']) {+ expect(() =>+ newController().saveConfig({+ database: { type: 'postgres', builtIn: false, host: 'db', schema, password: 'unit-test-pw' },+ } as never),+ ).toThrow(BadRequestException);+ }+ expect(fs.writeFileSync).not.toHaveBeenCalled();+ });++ it('still writes the public default for an empty schema', () => {+ const env = written({+ database: { type: 'postgres', builtIn: false, host: 'db', schema: '', password: 'unit-test-pw' },+ });+ expect(env).toContain('POSTGRES_SCHEMA=public');+ });+it('pins POSTGRES_SCHEMA=public for the built-in Postgres container', () => {const env = written({ database: { type: 'postgres', builtIn: true } });expect(env).toContain('POSTGRES_SCHEMA=public');