Reject sslrootcert and unknown sslmode values in PostgreSQL DSNs (#442)

On the DSN-only path (--dsn / DSN env), which bypasses TOML validation,
the PostgreSQL parser silently dropped sslrootcert unless sslmode was
verify-ca or verify-full. libpq treats require + a root CA as verify-ca,
so a connection string copied from psql connected with no server
verification and no warning. The same DSN inside a TOML source was
already rejected.

- sslrootcert with sslmode=require, disable or unset now fails with a
  message pointing at sslmode=verify-ca, matching TOML validation.
- Unrecognised sslmode values (libpq's allow/prefer, typos) no longer
  fall through to `ssl: true`, which verified against the system CA store
  and never fell back to plaintext. They are rejected with the list of
  valid modes, as TOML already does.

Replaces the two tests that asserted the silent-ignore behaviour and
documents the difference from libpq in docs/config/command-line.mdx.


Claude-Session: https://claude.ai/code/session_012UzToxWXzC7oQ9xMnhM192

Co-authored-by: Claude <noreply@anthropic.com>

Author: tianzhou

docs/config/command-line.mdx

@@ -253,7 +253,7 @@ This page covers command-line flags and environment variables. For TOML configur
   | Parameter | Databases | Description | Example |
   |-----------|-----------|-------------|---------|
   | `sslmode` | PostgreSQL, MySQL, MariaDB, SQL Server, Oracle | SSL mode: `disable`, `require`, `verify-ca`, `verify-full` | `?sslmode=require` |
-  | `sslrootcert` | PostgreSQL | CA certificate path (requires `verify-ca` or `verify-full`) | `?sslrootcert=~/.ssl/ca.pem` |
+  | `sslrootcert` | PostgreSQL | CA certificate path (requires `verify-ca` or `verify-full`; rejected with `require`, `disable` or no `sslmode`) | `?sslrootcert=~/.ssl/ca.pem` |
   | `sslcert` | PostgreSQL | PEM client certificate for client certificate authentication (set with `sslkey`; requires `require`, `verify-ca` or `verify-full`) | `?sslcert=~/.ssl/client.crt` |
   | `sslkey` | PostgreSQL | Unencrypted PEM private key for `sslcert` | `?sslkey=~/.ssl/client.key` |
   | `instanceName` | SQL Server | Named instance | `?instanceName=SQLEXPRESS` |
@@ -277,6 +277,10 @@ This page covers command-line flags and environment variables. For TOML configur
   - `sslmode=verify-ca`: SSL with CA certificate verification, but no hostname check. **PostgreSQL only.** Use `sslrootcert` to specify the CA certificate path.
   - `sslmode=verify-full`: SSL with CA certificate and hostname verification. **PostgreSQL and Oracle.** On PostgreSQL use `sslrootcert` to specify the CA certificate path; on Oracle the server certificate is validated against the system trust store.
 
+  <Note>
+  Unlike libpq, DBHub does not upgrade `sslmode=require` to `verify-ca` when `sslrootcert` is present: that combination is rejected at startup, so set `sslmode=verify-ca` explicitly. libpq's `allow` and `prefer` modes are not supported for PostgreSQL either; use `require` (or a verify mode) instead.
+  </Note>
+
   ```bash
   # Examples
   postgres://user:password@localhost:5432/dbname?sslmode=disable

src/connectors/__tests__/dsn-parser.test.ts

@@ -87,17 +87,35 @@ describe('DSN Parser - PostgreSQL SSL Modes', () => {
     await expect(parser.parse(dsn)).rejects.toThrow("Failed to read SSL root certificate at '/nonexistent/ca.pem'");
   });
 
-  it('should ignore sslrootcert when sslmode=require', async () => {
-    const dsn = `postgres://user:pass@localhost:5432/db?sslmode=require&sslrootcert=${encodeURIComponent(certPath)}`;
-    const config = await parser.parse(dsn);
-    expect(config.ssl).toEqual({ rejectUnauthorized: false });
+  it.each(['require', 'disable'])('should reject sslrootcert when sslmode=%s', async (sslmode) => {
+    const dsn = `postgres://user:pass@localhost:5432/db?sslmode=${sslmode}&sslrootcert=${encodeURIComponent(certPath)}`;
+    await expect(parser.parse(dsn)).rejects.toThrow(
+      `sslrootcert requires sslmode 'verify-ca' or 'verify-full' (got '${sslmode}')`
+    );
   });
 
-  it('should ignore sslrootcert when sslmode=disable', async () => {
-    const dsn = `postgres://user:pass@localhost:5432/db?sslmode=disable&sslrootcert=${encodeURIComponent(certPath)}`;
-    const config = await parser.parse(dsn);
-    expect(config.ssl).toBe(false);
+  it('should reject sslrootcert when sslmode is not set', async () => {
+    const dsn = `postgres://user:pass@localhost:5432/db?sslrootcert=${encodeURIComponent(certPath)}`;
+    await expect(parser.parse(dsn)).rejects.toThrow(
+      "sslrootcert requires sslmode 'verify-ca' or 'verify-full' (got 'not set')"
+    );
   });
+
+  it('should leave ssl unset when sslmode is not set', async () => {
+    const config = await parser.parse('postgres://user:pass@localhost:5432/db');
+    expect(config.ssl).toBeUndefined();
+  });
+
+  it.each(['prefer', 'allow', 'verify_full', 'true'])(
+    'should reject unsupported sslmode=%s',
+    async (sslmode) => {
+      await expect(
+        parser.parse(`postgres://user:pass@localhost:5432/db?sslmode=${sslmode}`)
+      ).rejects.toThrow(
+        `Unsupported sslmode '${sslmode}'. Valid values: disable, require, verify-ca, verify-full`
+      );
+    }
+  );
 });
 
 describe('DSN Parser - PostgreSQL client certificate (sslcert/sslkey)', () => {

src/connectors/postgres/index.ts

@@ -32,6 +32,9 @@ const POSTGRES_CLIENT_QUERY_TIMEOUT_GRACE_MS = 5_000;
 /** SSL modes in which a client certificate is presented to the server. */
 const CLIENT_CERT_SSL_MODES = ["require", "verify-ca", "verify-full"];
 
+/** SSL modes this parser maps to a node-postgres `ssl` setting. */
+const SUPPORTED_SSL_MODES = ["disable", ...CLIENT_CERT_SSL_MODES];
+
 /**
  * Read a PEM file referenced by an SSL DSN parameter, expanding a leading `~/`.
  * Wraps any read failure in FailedToReadCertificate so callers can tell a
@@ -67,10 +70,11 @@ function isEncryptedPemKey(pem: string): boolean {
  * - sslmode=require: SSL connection without certificate verification
  * - sslmode=verify-ca: SSL with CA certificate verification, no hostname check
  * - sslmode=verify-full: SSL with CA certificate and hostname verification
- * - Any other value: SSL with default Node.js TLS settings
+ * - Any other value is rejected (libpq's allow/prefer have no node-postgres equivalent)
  *
  * Optional parameter for verify-ca/verify-full:
- * - sslrootcert=/path/to/ca.pem: Path to CA certificate bundle (supports ~/ expansion)
+ * - sslrootcert=/path/to/ca.pem: Path to CA certificate bundle (supports ~/ expansion).
+ *   Rejected with any other sslmode rather than silently ignored.
  *
  * Optional parameters for client certificate authentication (require/verify-ca/verify-full):
  * - sslcert=/path/to/client.crt: PEM client certificate (supports ~/ expansion)
@@ -123,6 +127,27 @@ class PostgresDSNParser implements DSNParser {
         // Add other parameters as needed
       });
 
+      // An unrecognised mode (libpq's allow/prefer, or a typo) used to fall
+      // through to `ssl: true`, which verifies against the system CA store and
+      // never falls back to plaintext — the opposite of what allow/prefer ask
+      // for. Reject it instead of guessing.
+      if (sslmode !== undefined && !SUPPORTED_SSL_MODES.includes(sslmode)) {
+        throw new Error(
+          `Unsupported sslmode '${sslmode}'. Valid values: ${SUPPORTED_SSL_MODES.join(", ")}`
+        );
+      }
+
+      // sslrootcert is only read for verify-ca/verify-full. libpq treats
+      // require + a root CA as verify-ca, so a DSN copied from psql would
+      // otherwise connect unverified without any warning. Fail fast and let
+      // the user pick the mode explicitly (matches TOML validation).
+      if (sslrootcert !== undefined && sslmode !== "verify-ca" && sslmode !== "verify-full") {
+        throw new FailedToReadCertificate(
+          `sslrootcert requires sslmode 'verify-ca' or 'verify-full' (got '${sslmode ?? "not set"}'). ` +
+            `Use sslmode=verify-ca to verify the server certificate against it, or remove sslrootcert.`
+        );
+      }
+
       // Client certificate authentication: both halves are needed for a TLS
       // handshake, and node-postgres only speaks TLS in the modes below, so a
       // cert on a plaintext connection would be silently dropped. Fail fast.
@@ -154,8 +179,6 @@ class PostgresDSNParser implements DSNParser {
           sslConfig.ca = await readPemFile(sslrootcert, "SSL root certificate");
         }
         poolConfig.ssl = sslConfig;
-      } else if (sslmode !== undefined) {
-        poolConfig.ssl = true;
       }
 
       if (sslcert !== undefined && sslkey !== undefined) {