@malloydata/db-postgres 0.0.422 → 0.0.424

package/README.md

@@ -5,3 +5,32 @@ Malloy is a modern open source language for describing data relationships and tr
 ## This package
 
 This package facilitates using the `malloydata/malloy` library with Postgres - see [here](https://github.com/malloydata/malloy/blob/main/packages/malloy/README.md) for additional information.
+
+## Verified TLS through a tunnel
+
+`PostgresConnectionConfiguration.ssl` is forwarded verbatim to `pg`'s TLS options. To get servername-based certificate verification through a local tunnel (e.g. an SSH bastion forwarding to a remote Postgres), connect via the loopback IP rather than `localhost` — `pg` overwrites `servername` with `host` whenever `host` is a DNS name. If the certificate doesn't match the host `pg` connects to, `pg` throws a certificate error and the connector annotates it with this servername/host guidance.
+
+```ts
+import {PostgresConnection} from '@malloydata/db-postgres';
+
+const connection = new PostgresConnection({
+  name: 'tunneled_postgres',
+  host: '127.0.0.1', // must be an IP, not 'localhost', for servername to take effect
+  port: 5432,
+  ssl: {
+    servername: 'db.example.com',
+    ca: '<PEM-encoded CA certificate>',
+  },
+});
+```
+
+### Semantics (pg/Node `tls`, not libpq)
+
+- `ssl: true` — full verification against the system trust store, hostname included (verify-full). A self-signed or custom-CA server fails unless you supply `ca` (and/or set `servername` for a tunnel).
+- `ssl: { rejectUnauthorized: false }` — encrypt but do **not** verify (libpq's `sslmode=require`/`no-verify`). Use only when verification is impossible; it does not stop MITM.
+- `ssl: { ca }` — trust a specific CA (a PEM string, or an array of PEMs for rotation). This is the path for AWS RDS (or use `NODE_EXTRA_CA_CERTS`) and Cloud SQL.
+- **verify-ca** against a cert whose SAN/CN doesn't match any reachable name (e.g. Cloud SQL *legacy* per-instance certs) needs a `checkServerIdentity` override. That is a function, so it is **not** expressible in a saved `json` config — construct the connection programmatically and pass the full `pg` `ssl` (`tls.ConnectionOptions`) directly.
+
+Do **not** put TLS parameters in both `ssl` and the `connectionString`: `pg` merges URL ssl params (`sslmode`, `sslrootcert`, …) *over* the `ssl` object, silently dropping it. Set TLS in one place.
+
+`ssl` is passed through literally — `json` config is never reference-resolved (a malloy security invariant), so `key`/`passphrase` cannot be pulled from an `{env:...}`/overlay reference. Inject secret material programmatically at construction time; never persist it in a shared connection config.

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { PostgresConnection, PooledPostgresConnection, } from './postgres_connection';
+export type { PostgresSSLConfig } from './postgres_connection';

package/dist/index.js

@@ -46,6 +46,14 @@ const postgres_connection_2 = require("./postgres_connection");
             advanced: true,
             description: 'SQL statements to run when the connection is established',
         },
+        {
+            name: 'ssl',
+            displayName: 'SSL',
+            type: 'json',
+            optional: true,
+            advanced: true,
+            description: 'TLS/SSL options forwarded to pg, e.g. {"servername":"db.example.com","ca":"<PEM>"}. Passed through literally (json config is never reference-resolved), so do not place secret key/passphrase material in shared config.',
+        },
     ],
 });
 //# sourceMappingURL=index.js.map

package/dist/postgres_connection.d.ts

@@ -1,6 +1,48 @@
 import type { Connection, ConnectionConfig, MalloyQueryData, PersistSQLResults, PooledConnection, QueryRecord, QueryOptionsReader, QueryRunStats, RunSQLOptions, SQLSourceDef, TableSourceDef, StreamingConnection, SQLSourceRequest } from '@malloydata/malloy';
 import { BaseConnection } from '@malloydata/malloy/connection';
 import { Client, Pool } from 'pg';
+import type { ClientConfig } from 'pg';
+/**
+ * Serializable TLS options for a Postgres connection, forwarded verbatim into
+ * pg's native `Object.assign(clientOptions, ssl)`. This is the subset that can
+ * live in a saved/registry connection config (all PEM strings + booleans).
+ *
+ * Semantics (these mirror pg / Node `tls`, NOT libpq):
+ * - `ssl: true` (or `rejectUnauthorized: true`, the default) → full
+ *   verification against the trust store, including hostname (verify-full).
+ * - `rejectUnauthorized: false` → encrypt but do NOT verify (libpq's
+ *   `sslmode=require` / `no-verify`); use only when you can't verify.
+ * - `ca` pins a trusted CA (PEM, or an array of PEMs).
+ *
+ * `servername` only takes effect when the connection `host` is an IP literal
+ * (e.g. `127.0.0.1`) — pg overwrites `servername` with `host` whenever `host`
+ * is a DNS name like `localhost`, so servername-based verification through a
+ * tunnel requires connecting via IP. When the certificate doesn't match the
+ * host pg connected to, pg throws; the connector annotates that error with
+ * this servername/host guidance.
+ *
+ * verify-ca against a cert with no matching SAN/CN (e.g. Cloud SQL legacy
+ * per-instance certs) needs `checkServerIdentity`, a function — not
+ * expressible here or in `type: 'json'` config. Pass the full pg `ssl`
+ * (`tls.ConnectionOptions`) via the config-reader constructor form
+ * (`new PostgresConnection(name, queryOptions, () => ({..., ssl}))`) for that
+ * case; the serializable options object is limited to this subset.
+ *
+ * `ssl` is passed through literally — `type: 'json'` config is never
+ * reference-resolved (a malloy security invariant), so secret `key`/
+ * `passphrase` material cannot be pulled from an `{env:...}`/overlay
+ * reference. Inject secrets programmatically at construction; never persist
+ * them in a shared connection config. Secrets are never logged.
+ */
+export type PostgresSSLConfig = {
+    ca?: string | string[];
+    cert?: string;
+    key?: string;
+    passphrase?: string;
+    crl?: string | string[];
+    servername?: string;
+    rejectUnauthorized?: boolean;
+};
 interface PostgresConnectionConfiguration {
     host?: string;
     port?: number;
@@ -9,9 +51,11 @@ interface PostgresConnectionConfiguration {
     databaseName?: string;
     connectionString?: string;
     setupSQL?: string;
+    ssl?: ClientConfig['ssl'];
 }
 type PostgresConnectionConfigurationReader = PostgresConnectionConfiguration | (() => Promise<PostgresConnectionConfiguration>);
-export interface PostgresConnectionOptions extends ConnectionConfig, PostgresConnectionConfiguration {
+export interface PostgresConnectionOptions extends ConnectionConfig, Omit<PostgresConnectionConfiguration, 'ssl'> {
+    ssl?: boolean | PostgresSSLConfig;
 }
 export declare class PostgresConnection extends BaseConnection implements Connection, StreamingConnection, PersistSQLResults {
     readonly name: string;
@@ -29,6 +73,8 @@ export declare class PostgresConnection extends BaseConnection implements Connec
     canStream(): this is StreamingConnection;
     getDigest(): string;
     get supportsNesting(): boolean;
+    protected buildClientConfig(cfg: PostgresConnectionConfiguration): ClientConfig;
+    protected withTlsHint<T>(op: () => Promise<T>): Promise<T>;
     protected getClient(): Promise<Client>;
     protected runPostgresQuery(sqlCommand: string, _pageSize: number, _rowIndex: number, deJSON: boolean, values?: unknown[]): Promise<MalloyQueryData>;
     fetchSelectSchema(sqlRef: SQLSourceRequest): Promise<SQLSourceDef | string>;

package/dist/postgres_connection.js

@@ -14,6 +14,24 @@ const pg_1 = require("pg");
 const pg_query_stream_1 = __importDefault(require("pg-query-stream"));
 const DEFAULT_PAGE_SIZE = 1000;
 const SCHEMA_PAGE_SIZE = 1000;
+// pg verifies the server certificate against the host it actually connects to,
+// not `ssl.servername` (which pg drops when the host is a DNS name). When that
+// check fails, pg throws a terse altname error; augment it with how to fix a
+// tunneled connection rather than trying to predict pg's host resolution up
+// front. Mutates and returns the original error so its type and stack survive.
+function addTlsHint(err) {
+    if (!(err instanceof Error))
+        return err;
+    const code = err.code;
+    const isCertHostMismatch = code === 'ERR_TLS_CERT_ALTNAME_INVALID' ||
+        (/certificate/i.test(err.message) &&
+            /altname|does not match/i.test(err.message));
+    if (isCertHostMismatch) {
+        err.message +=
+            "\n[malloy-db-postgres] The server certificate does not match the host pg connected to. pg verifies against the connection host, not ssl.servername, unless the host is an IP. For a tunnel, connect via the DB's IP (e.g. host '127.0.0.1') and set ssl.servername to the real hostname; or omit ssl.servername to verify against the host directly.";
+    }
+    return err;
+}
 /**
  * Decode a canonical Postgres dotted-table path into its underlying
  * identifier strings as they appear in `information_schema`. The schema
@@ -94,20 +112,33 @@ class PostgresConnection extends connection_1.BaseConnection {
     get supportsNesting() {
         return true;
     }
+    buildClientConfig(cfg) {
+        return {
+            user: cfg.username,
+            password: cfg.password,
+            database: cfg.databaseName,
+            port: cfg.port,
+            host: cfg.host,
+            connectionString: cfg.connectionString,
+            ssl: cfg.ssl,
+        };
+    }
+    // Runs a connect/query op, annotating pg's terse certificate-mismatch error
+    // with actionable TLS guidance (see addTlsHint).
+    async withTlsHint(op) {
+        try {
+            return await op();
+        }
+        catch (e) {
+            throw addTlsHint(e);
+        }
+    }
     async getClient() {
-        const { username: user, password, databaseName: database, port, host, connectionString, } = await this.readConfig();
-        return new pg_1.Client({
-            user,
-            password,
-            database,
-            port,
-            host,
-            connectionString,
-        });
+        return new pg_1.Client(this.buildClientConfig(await this.readConfig()));
     }
     async runPostgresQuery(sqlCommand, _pageSize, _rowIndex, deJSON, values) {
         const client = await this.getClient();
-        await client.connect();
+        await this.withTlsHint(() => client.connect());
         await this.connectionSetup(client);
         let result = await client.query(sqlCommand, values);
         if (Array.isArray(result)) {
@@ -133,7 +164,7 @@ class PostgresConnection extends connection_1.BaseConnection {
             name: (0, malloy_1.sqlKey)(sqlRef.connection, sqlRef.selectStr),
         };
         const client = await this.getClient();
-        await client.connect();
+        await this.withTlsHint(() => client.connect());
         await this.connectionSetup(client);
         // 1) Get row-descriptor without fetching data
         const res = await client.query({
@@ -296,7 +327,7 @@ class PostgresConnection extends connection_1.BaseConnection {
     async *runSQLStream(sqlCommand, { rowLimit, abortSignal } = {}) {
         const query = new pg_query_stream_1.default(sqlCommand);
         const client = await this.getClient();
-        await client.connect();
+        await this.withTlsHint(() => client.connect());
         await this.connectionSetup(client);
         const rowStream = client.query(query);
         let index = 0;
@@ -345,15 +376,7 @@ class PooledPostgresConnection extends PostgresConnection {
     }
     async getPool() {
         if (!this._pool) {
-            const { username: user, password, databaseName: database, port, host, connectionString, } = await this.readConfig();
-            this._pool = new pg_1.Pool({
-                user,
-                password,
-                database,
-                port,
-                host,
-                connectionString,
-            });
+            this._pool = new pg_1.Pool(this.buildClientConfig(await this.readConfig()));
             this._pool.on('acquire', client => {
                 client.query("SET TIME ZONE 'UTC'");
                 if (this.setupSQL) {
@@ -370,7 +393,7 @@ class PooledPostgresConnection extends PostgresConnection {
     }
     async runPostgresQuery(sqlCommand, _pageSize, _rowIndex, deJSON, values) {
         const pool = await this.getPool();
-        let result = await pool.query(sqlCommand, values);
+        let result = await this.withTlsHint(() => pool.query(sqlCommand, values));
         if (Array.isArray(result)) {
             result = result.pop();
         }
@@ -392,7 +415,7 @@ class PooledPostgresConnection extends PostgresConnection {
         // `QueryStream` as well, but it's not. So instead, we get a client and call
         // `client.query(query)`, which does what it's supposed to.
         const pool = await this.getPool();
-        const client = await pool.connect();
+        const client = await this.withTlsHint(() => pool.connect());
         const resultStream = client.query(query);
         for await (const row of resultStream) {
             yield row.row;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/db-postgres",
-  "version": "0.0.422",
+  "version": "0.0.424",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -23,7 +23,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@malloydata/malloy": "0.0.422",
+    "@malloydata/malloy": "0.0.424",
     "@types/pg": "^8.6.1",
     "pg": "8.7.3",
     "pg-query-stream": "4.2.3"