Merge pull request #1591 from dcoric/feat/postgres-rds-iam-auth

feat: AWS RDS/Aurora IAM authentication for the PostgreSQL sink

Author: dcoric

config.schema.json

@@ -621,6 +621,21 @@
                   "description": "Milliseconds to wait for a connection before timing out."
                 }
               }
+            },
+            "awsIamAuth": {
+              "type": "object",
+              "description": "Authenticate to Amazon RDS/Aurora with an IAM auth token instead of a static password. When enabled, a short-lived token is generated for each new connection from the AWS SDK default credential chain, so no password is stored. Requires the discrete `host`/`port`/`user` fields (or the `PGHOST`/`PGPORT`/`PGUSER` environment variables) rather than a `connectionString`, requires TLS (`ssl` defaults to `true` when omitted), and needs the optional `@aws-sdk/rds-signer` dependency to be installed.",
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "description": "Enable IAM token authentication for the PostgreSQL connection."
+                },
+                "region": {
+                  "type": "string",
+                  "description": "AWS region of the RDS/Aurora instance. Falls back to the `AWS_REGION` / `AWS_DEFAULT_REGION` environment variables, then the AWS SDK's default region resolution."
+                }
+              },
+              "required": ["enabled"]
             }
           },
           "required": ["type", "enabled"]

package-lock.json

@@ -218,6 +218,7 @@
     "underscore": "^1.13.8"
   },
   "optionalDependencies": {
+    "@aws-sdk/rds-signer": "^3.980.0",
     "@esbuild/darwin-arm64": "^0.27.2",
     "@esbuild/darwin-x64": "^0.27.2",
     "@esbuild/linux-x64": "0.27.2",

package.json

@@ -566,6 +566,15 @@ export interface Database {
    */
   options?: Options;
   type: DatabaseType;
+  /**
+   * Authenticate to Amazon RDS/Aurora with an IAM auth token instead of a static password.
+   * When enabled, a short-lived token is generated for each new connection from the AWS SDK
+   * default credential chain, so no password is stored. Requires the discrete
+   * `host`/`port`/`user` fields (or the `PGHOST`/`PGPORT`/`PGUSER` environment variables)
+   * rather than a `connectionString`, requires TLS (`ssl` defaults to `true` when omitted),
+   * and needs the optional `@aws-sdk/rds-signer` dependency to be installed.
+   */
+  awsIamAuth?: AwsIamAuth;
   /**
    * Database name. Used when `connectionString` is not set. Falls back to the `PGDATABASE`
    * environment variable.
@@ -604,6 +613,27 @@ export interface Database {
   [property: string]: any;
 }
 
+/**
+ * Authenticate to Amazon RDS/Aurora with an IAM auth token instead of a static password.
+ * When enabled, a short-lived token is generated for each new connection from the AWS SDK
+ * default credential chain, so no password is stored. Requires the discrete
+ * `host`/`port`/`user` fields (or the `PGHOST`/`PGPORT`/`PGUSER` environment variables)
+ * rather than a `connectionString`, requires TLS (`ssl` defaults to `true` when omitted),
+ * and needs the optional `@aws-sdk/rds-signer` dependency to be installed.
+ */
+export interface AwsIamAuth {
+  /**
+   * Enable IAM token authentication for the PostgreSQL connection.
+   */
+  enabled: boolean;
+  /**
+   * AWS region of the RDS/Aurora instance. Falls back to the `AWS_REGION` /
+   * `AWS_DEFAULT_REGION` environment variables, then the AWS SDK's default region resolution.
+   */
+  region?: string;
+  [property: string]: any;
+}
+
 /**
  * mongoDB Client connection options. Please note that only custom options are described
  * here, see
@@ -1178,6 +1208,7 @@ const typeMap: any = {
       { json: 'enabled', js: 'enabled', typ: true },
       { json: 'options', js: 'options', typ: u(undefined, r('Options')) },
       { json: 'type', js: 'type', typ: r('DatabaseType') },
+      { json: 'awsIamAuth', js: 'awsIamAuth', typ: u(undefined, r('AwsIamAuth')) },
       { json: 'database', js: 'database', typ: u(undefined, '') },
       { json: 'host', js: 'host', typ: u(undefined, '') },
       { json: 'password', js: 'password', typ: u(undefined, '') },
@@ -1188,6 +1219,13 @@ const typeMap: any = {
     ],
     'any',
   ),
+  AwsIamAuth: o(
+    [
+      { json: 'enabled', js: 'enabled', typ: true },
+      { json: 'region', js: 'region', typ: u(undefined, '') },
+    ],
+    'any',
+  ),
   Options: o(
     [
       {

src/config/generated/config.ts

@@ -43,15 +43,80 @@ const hasConnectionConfig = (db: DatabaseConfig): boolean =>
     process.env.PGDATABASE,
   );
 
+/**
+ * Minimal shape of the optional `@aws-sdk/rds-signer` module, declared locally
+ * so the project type-checks whether or not the optional dependency is present.
+ */
+interface RdsSignerModule {
+  Signer: new (config: { hostname: string; port: number; username: string; region?: string }) => {
+    getAuthToken: () => Promise<string>;
+  };
+}
+
+/**
+ * Load the optional RDS signer, raising a clear error if it is not installed.
+ * Kept optional so installs that do not use IAM auth stay lean.
+ */
+const loadRdsSigner = async (): Promise<RdsSignerModule> => {
+  try {
+    return (await import('@aws-sdk/rds-signer')) as unknown as RdsSignerModule;
+  } catch {
+    throw new Error(
+      'AWS RDS IAM authentication requires the optional `@aws-sdk/rds-signer` dependency. Install it with `npm install @aws-sdk/rds-signer`.',
+    );
+  }
+};
+
+/**
+ * Build the per-connection password provider for RDS/Aurora IAM auth. `pg`
+ * invokes it for every new connection, so each one receives a fresh (~15 min)
+ * token and refresh is automatic — no static password is ever stored.
+ */
+const buildIamTokenProvider = (db: DatabaseConfig): (() => Promise<string>) => {
+  const host = db.host ?? process.env.PGHOST;
+  const port = db.port ?? (process.env.PGPORT ? Number(process.env.PGPORT) : 5432);
+  const user = db.user ?? process.env.PGUSER;
+  const region = db.awsIamAuth?.region ?? process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+
+  if (!host || !user) {
+    throw new Error(
+      'AWS RDS IAM authentication requires `host` and `user` (or the PGHOST/PGUSER environment variables) to generate an auth token.',
+    );
+  }
+
+  return async () => {
+    const { Signer } = await loadRdsSigner();
+    const signer = new Signer({ hostname: host, port, username: user, region });
+    return signer.getAuthToken();
+  };
+};
+
 /**
  * Build a `pg` PoolConfig from the resolved database config. A connection
  * string (already env-resolved by `getDatabase`) takes precedence; otherwise
  * the discrete fields are used. When neither is set, `pg` reads the `PG*`
- * environment variables itself.
+ * environment variables itself. When `awsIamAuth` is enabled, the static
+ * password is replaced by a generated IAM token and the discrete fields drive
+ * the connection.
  */
 const buildPoolConfig = (db: DatabaseConfig): PoolConfig => {
   const config: PoolConfig = {};
-  if (db.connectionString) {
+  const iamAuthEnabled = Boolean(db.awsIamAuth?.enabled);
+
+  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;
+    if (db.database !== undefined) config.database = db.database;
+    config.password = buildIamTokenProvider(db);
+  } else if (db.connectionString) {
     if (
       db.host !== undefined ||
       db.port !== undefined ||
@@ -71,8 +136,32 @@ const buildPoolConfig = (db: DatabaseConfig): PoolConfig => {
     if (db.password !== undefined) config.password = db.password;
     if (db.database !== undefined) config.database = db.database;
   }
-  // TLS applies regardless of how the connection itself was configured.
-  if (db.ssl !== undefined) config.ssl = db.ssl as PoolConfig['ssl'];
+
+  // TLS applies regardless of how the connection itself was configured. RDS IAM
+  // 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.
   if (db.pool) {