fix(db/postgres): surface RDS IAM transport pitfalls instead of failing quietly

Review feedback on IAM auth:

- When awsIamAuth is enabled a configured connectionString is ignored
  by design; that now logs a warning instead of happening silently.
- ssl: true verifies against Node's default trust store, which does not
  contain Amazon's RDS root CA, so the documented fallback would fail
  certificate verification against a real RDS endpoint. The default
  stays verify-on, but startup now warns (both when ssl is defaulted
  and when supplied ssl options lack a ca) that the RDS CA bundle must
  be provided via ssl.ca, and the architecture doc leads with the
  bundle requirement including the download location.

Author: dcoric

src/db/postgres/helper.ts

@@ -106,6 +106,11 @@ const buildPoolConfig = (db: DatabaseConfig): PoolConfig => {
   if (iamAuthEnabled) {
     // IAM auth supplies the password as a generated token, so the connection is
     // driven by the discrete fields (or PG* env), never a connection string.
+    if (db.connectionString) {
+      console.warn(
+        '[postgres] awsIamAuth is enabled; ignoring connectionString (IAM mode uses the discrete host/port/user/database fields)',
+      );
+    }
     if (db.host !== undefined) config.host = db.host;
     if (db.port !== undefined) config.port = db.port;
     if (db.user !== undefined) config.user = db.user;
@@ -136,8 +141,26 @@ const buildPoolConfig = (db: DatabaseConfig): PoolConfig => {
   // auth mandates TLS, so default it on when IAM is enabled and `ssl` is unset.
   if (db.ssl !== undefined) {
     config.ssl = db.ssl as PoolConfig['ssl'];
+    if (iamAuthEnabled && typeof db.ssl === 'object' && db.ssl !== null && !('ca' in db.ssl)) {
+      console.warn(
+        '[postgres] awsIamAuth: the ssl options carry no `ca`; RDS server certificates chain to ' +
+          "Amazon's RDS root CA, which is not in Node's default trust store, so verification " +
+          'will fail unless the RDS CA bundle is supplied via ssl.ca',
+      );
+    }
   } else if (iamAuthEnabled) {
+    // RDS requires TLS for IAM auth, so it defaults on. `ssl: true` verifies
+    // against Node's default trust store, which does NOT contain Amazon's RDS
+    // root CA; connecting to a real RDS endpoint therefore needs the RDS CA
+    // bundle supplied via `ssl.ca`. The default stays verify-on rather than
+    // silently downgrading transport security.
     config.ssl = true;
+    console.warn(
+      '[postgres] awsIamAuth: ssl defaulted to true, which verifies against ' +
+        "Node's default trust store; connections to RDS will fail certificate " +
+        'verification unless the RDS CA bundle is supplied via ssl.ca ' +
+        '(see the PostgreSQL section of the architecture doc)',
+    );
   }
 
   // Optional pool tuning.

test/db/postgres/helper.test.ts

@@ -354,6 +354,57 @@ describe('PostgreSQL - helper', async () => {
       expect(getOpts().ssl).toEqual(ssl);
     });
 
+    it('warns that the connection string is ignored when IAM auth is enabled', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      getDatabaseMock.mockReturnValue({
+        type: 'postgres',
+        enabled: true,
+        connectionString: 'postgresql://ignored/x',
+        host: 'rds.example.com',
+        user: 'gp',
+        awsIamAuth: { enabled: true, region: 'eu-west-2' },
+      });
+
+      await connect();
+
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('ignoring connectionString'));
+      warnSpy.mockRestore();
+    });
+
+    it('warns when ssl defaults to true in IAM mode (RDS CA is not in the default trust store)', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      getDatabaseMock.mockReturnValue({
+        type: 'postgres',
+        enabled: true,
+        host: 'rds.example.com',
+        user: 'gp',
+        awsIamAuth: { enabled: true, region: 'eu-west-2' },
+      });
+
+      await connect();
+
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('ssl.ca'));
+      warnSpy.mockRestore();
+    });
+
+    it('does not warn about ssl when a CA bundle is supplied', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      getDatabaseMock.mockReturnValue({
+        type: 'postgres',
+        enabled: true,
+        host: 'rds.example.com',
+        user: 'gp',
+        ssl: { rejectUnauthorized: true, ca: 'RDS_CA' },
+        awsIamAuth: { enabled: true, region: 'eu-west-2' },
+      });
+
+      await connect();
+
+      const sslWarnings = warnSpy.mock.calls.filter(([m]) => String(m).includes('ssl.ca'));
+      expect(sslWarnings).toEqual([]);
+      warnSpy.mockRestore();
+    });
+
     it('ignores a connection string when IAM auth is enabled', async () => {
       getDatabaseMock.mockReturnValue({
         type: 'postgres',

website/docs/architecture/architecture.md

@@ -552,7 +552,7 @@ For Amazon RDS or Aurora, GitProxy can authenticate with a short-lived IAM auth
 
 - A fresh token is generated for every new pool connection from the AWS SDK default credential chain (via `@aws-sdk/rds-signer`), so no password is stored and token refresh is automatic.
 - `region` falls back to the `AWS_REGION` / `AWS_DEFAULT_REGION` environment variables, then the SDK's default region resolution.
-- TLS is required by RDS for IAM auth, so `ssl` defaults to `true` when omitted. Supply an `ssl` object (for example `{ "rejectUnauthorized": true, "ca": "<RDS CA bundle>" }`) to verify against the RDS certificate authority.
+- TLS is required by RDS for IAM auth. Supply the RDS certificate authority bundle via `ssl` (for example `{ "rejectUnauthorized": true, "ca": "<contents of the RDS global-bundle.pem>" }`, downloadable from https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem): RDS server certificates chain to Amazon's own root CA, which is not in Node's default trust store, so the `ssl: true` fallback (used when `ssl` is omitted) fails certificate verification against a real RDS endpoint and logs a startup warning saying so. Do not work around a verification failure with `rejectUnauthorized: false`; that discards the transport security IAM auth depends on.
 - The database user must be granted the `rds_iam` role (`GRANT rds_iam TO gitproxy_iam;`).
 - IAM auth needs the optional `@aws-sdk/rds-signer` dependency, which installs by default. On a slim install (`npm install --omit=optional`) add it explicitly with `npm install @aws-sdk/rds-signer`.