@malloy-publisher/server 0.0.229 → 0.0.230

package/src/service/connection.spec.ts

@@ -8,6 +8,7 @@ import { components } from "../api";
 import {
    buildProxiedSslQuery,
    createEnvironmentConnections,
+   resolveProxiedTls,
    testConnectionConfig,
 } from "./connection";
 import { assembleEnvironmentConnections } from "./connection_config";
@@ -1917,3 +1918,73 @@ describe("buildProxiedSslQuery", () => {
       }
    });
 });
+
+describe("resolveProxiedTls", () => {
+   it("routes verify-full to a raw ssl object with servername = the real host", () => {
+      // verify-full (chain + hostname) can't ride the connectionString through a
+      // tunnel — it needs ssl.servername set to the real DB host so pg checks the
+      // cert's SAN against it, not against the 127.0.0.1 socket address.
+      const { query, ssl } = resolveProxiedTls(
+         "conn",
+         "db.internal.example.com",
+         "verify-full",
+      );
+      expect(query).toBe("");
+      expect(ssl).toEqual({
+         servername: "db.internal.example.com",
+         rejectUnauthorized: true,
+      });
+   });
+
+   it("throws for verify-full with no host (servername would be undefined)", () => {
+      expect(() => resolveProxiedTls("conn", undefined, "verify-full")).toThrow(
+         /verify-full.*no host/i,
+      );
+   });
+
+   it("routes the connectionString-param modes through buildProxiedSslQuery with no ssl object", () => {
+      // verify-ca needs a CA bundle to build its query, so set one for the loop.
+      const prior = process.env.NODE_EXTRA_CA_CERTS;
+      process.env.NODE_EXTRA_CA_CERTS = "/etc/ssl/certs/bundle.pem";
+      try {
+         for (const mode of ["disable", "no-verify", "verify-ca", undefined]) {
+            const { query, ssl } = resolveProxiedTls("conn", "127.0.0.1", mode);
+            expect(query).toBe(buildProxiedSslQuery("conn", mode));
+            expect(ssl).toBeUndefined();
+         }
+      } finally {
+         if (prior === undefined) delete process.env.NODE_EXTRA_CA_CERTS;
+         else process.env.NODE_EXTRA_CA_CERTS = prior;
+      }
+   });
+
+   it("verify-full: a bare connectionString does not clobber the explicit ssl object (pg merge guard)", async () => {
+      // Load-bearing invariant: pg's ConnectionParameters does
+      // Object.assign({}, config, parse(connectionString)). A verify-full
+      // connectionString carries no sslmode, so pg-connection-string adds no
+      // `ssl` key and our explicit { servername, rejectUnauthorized } survives
+      // the merge. If a future pg bump changes this — or we accidentally emit an
+      // sslmode into the query — this guard fails loudly instead of silently
+      // downgrading verify-full.
+      const { query, ssl } = resolveProxiedTls(
+         "conn",
+         "db.internal.example.com",
+         "verify-full",
+      );
+      const { default: ConnectionParameters } = await import(
+         "pg/lib/connection-parameters.js"
+      );
+      const params = new (ConnectionParameters as unknown as new (
+         c: unknown,
+      ) => {
+         ssl: unknown;
+      })({
+         connectionString: `postgresql://u:p@127.0.0.1:5432/db${query}`,
+         ssl,
+      });
+      expect(params.ssl).toEqual({
+         servername: "db.internal.example.com",
+         rejectUnauthorized: true,
+      });
+   });
+});

package/src/service/connection.ts

@@ -9,6 +9,7 @@ import "@malloydata/db-postgres";
 import {
    PooledPostgresConnection,
    type PostgresConnection,
+   type PostgresSSLConfig,
 } from "@malloydata/db-postgres";
 // Registers the "publisher" connection type (proxies SQL to a remote Publisher
 // dataplane). No live-class branch is needed in lookupConnection — the default
@@ -30,6 +31,12 @@ import type { LookupConnection } from "@malloydata/malloy/connection";
 import { AxiosError } from "axios";
 import fs from "fs/promises";
 import { components } from "../api";
+import { getExtensionFetchPolicy } from "../config";
+import {
+   catalogFormatRangeForEngine,
+   isCatalogFormatInRange,
+} from "../ducklake_version";
+import { UnsupportedCatalogFormatError } from "../errors";
 import { logAxiosError, logger } from "../logger";
 import { redactPgSecrets } from "../pg_helpers";
 import {
@@ -71,26 +78,129 @@ export type InternalConnection = ApiConnection & {
 };
 
 // Shared utilities
+
+// Publisher-owned DuckDB sessions whose extension PRAGMAs have already been
+// pinned. The lookup funnel runs on every resolve, and the attach paths pin
+// too, so this WeakSet keeps the SETs to once per connection object. The
+// DuckLake tier pins with `alwaysDisableAutoinstall` inside its attach, which
+// runs before the funnel ever sees the connection, so the stronger always-off
+// setting is recorded first and never re-evaluated down to policy here.
+const extensionSessionPinned = new WeakSet<Connection>();
+
+/**
+ * Pin the extension-management PRAGMAs on a Publisher-owned DuckDB session.
+ * Publisher installs the extensions it needs explicitly (see
+ * {@link installAndLoadExtension}), so DuckDB's own IMPLICIT auto-install
+ * (fetching a known extension a query happens to reference) is never
+ * load-bearing.
+ *
+ * Auto-LOAD is left ON (DuckDB's default) so any locally-present extension
+ * still lazy-loads — the local-first UX every deployment relies on. Implicit
+ * auto-INSTALL is turned OFF when EITHER:
+ *   - `alwaysDisableAutoinstall` is set — the DuckLake tier's build/serve
+ *     sessions only ever need the curated extension set, so they never
+ *     implicitly fetch, regardless of the deployment policy; OR
+ *   - `EXTENSION_FETCH_POLICY=local-only` — the air-gapped / pinned-image
+ *     posture, where no session may reach the network.
+ *
+ * Under the default `on-demand` policy a generic session is left untouched
+ * (DuckDB's default), so existing standalone/OSS users see no behaviour change.
+ *
+ * Called for EVERY Publisher-owned DuckDB session — the environment lookup
+ * funnel, the per-package sandbox, and the attach entry points — so the pin has
+ * no gap regardless of whether a session has attached databases. On a failed
+ * SET: under `local-only` we FAIL CLOSED (throw), because the whole promise of
+ * that mode is that no session can reach the network; under the tier's
+ * on-demand always-off case the pin is defense-in-depth (the install path
+ * already avoids implicit fetches), so we log and continue rather than fail an
+ * otherwise-valid attach.
+ */
+export async function applyExtensionSessionSettings(
+   connection: DuckDBConnection,
+   {
+      alwaysDisableAutoinstall = false,
+   }: { alwaysDisableAutoinstall?: boolean } = {},
+): Promise<void> {
+   const policy = getExtensionFetchPolicy();
+   const disableAutoinstall =
+      alwaysDisableAutoinstall || policy === "local-only";
+   if (!disableAutoinstall || extensionSessionPinned.has(connection)) {
+      return;
+   }
+   try {
+      await connection.runSQL("SET autoinstall_known_extensions=false;");
+      // Keep autoload on: it is DuckDB's default, but set it explicitly next to
+      // an install lockdown so a locally-present/baked extension still loads.
+      await connection.runSQL("SET autoload_known_extensions=true;");
+      extensionSessionPinned.add(connection);
+   } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      if (policy === "local-only") {
+         throw new Error(
+            `Failed to disable DuckDB implicit extension auto-install under ` +
+               `EXTENSION_FETCH_POLICY=local-only; refusing to open a session that ` +
+               `could still fetch from the network. Underlying error: ${detail}`,
+         );
+      }
+      logger.warn("Failed to pin DuckDB extension session settings", {
+         error: detail,
+      });
+   }
+}
+
 async function installAndLoadExtension(
    connection: DuckDBConnection,
    extensionName: string,
    fromCommunity = false,
 ): Promise<void> {
+   const policy = getExtensionFetchPolicy();
+
+   // `local-only` never fetches: skip INSTALL entirely and rely on the
+   // extension already being present on disk (baked into the image). Auto-LOAD
+   // stays on (see applyExtensionSessionSettings), so a present extension still
+   // lazy-loads; a missing one fails the LOAD below and is reported loudly.
+   if (policy === "on-demand") {
+      try {
+         // Plain INSTALL is local-first: it no-ops when the extension is already
+         // present and only fetches when it is missing. We dropped FORCE, which
+         // re-fetched from the community CDN whenever the network was up — even
+         // for a baked extension — silently drifting the running binary past the
+         // offline-verified build.
+         const installCommand = fromCommunity
+            ? `INSTALL ${extensionName} FROM community;`
+            : `INSTALL ${extensionName};`;
+         await connection.runSQL(installCommand);
+         logger.info(`${extensionName} extension installed`);
+      } catch (error) {
+         logger.info(
+            `${extensionName} extension already installed or install skipped`,
+            { error },
+         );
+      }
+   }
+
    try {
-      const installCommand = fromCommunity
-         ? `FORCE INSTALL '${extensionName}' FROM community;`
-         : `INSTALL ${extensionName};`;
-      await connection.runSQL(installCommand);
-      logger.info(`${extensionName} extension installed`);
+      await connection.runSQL(`LOAD ${extensionName};`);
+      logger.info(`${extensionName} extension loaded`);
    } catch (error) {
-      logger.info(
-         `${extensionName} extension already installed or install skipped`,
-         { error },
-      );
+      if (policy === "local-only") {
+         const detail = error instanceof Error ? error.message : String(error);
+         logger.warn("DuckDB extension unavailable under local-only policy", {
+            extension: extensionName,
+            policy,
+            error: detail,
+         });
+         throw new Error(
+            `DuckDB extension '${extensionName}' is not available locally and ` +
+               `EXTENSION_FETCH_POLICY=local-only forbids fetching it. Bake the ` +
+               `'${extensionName}' extension into the image (or a pre-populated ` +
+               `~/.duckdb/extensions directory), or set ` +
+               `EXTENSION_FETCH_POLICY=on-demand to allow fetching missing ` +
+               `extensions on first use. Underlying LOAD error: ${detail}`,
+         );
+      }
+      throw error;
    }
-
-   await connection.runSQL(`LOAD ${extensionName};`);
-   logger.info(`${extensionName} extension loaded`);
 }
 
 async function isDatabaseAttached(
@@ -339,11 +449,141 @@ async function attachPostgres(
    logger.info(`Successfully attached PostgreSQL database: ${attachedDb.name}`);
 }
 
+/** Rows out of a DuckDBConnection.runSQL result, in either shape it returns. */
+function runSQLRows(result: unknown): Record<string, unknown>[] {
+   if (Array.isArray(result)) return result as Record<string, unknown>[];
+   const rows = (result as { rows?: unknown }).rows;
+   return Array.isArray(rows) ? (rows as Record<string, unknown>[]) : [];
+}
+
+/**
+ * Runtime range-preflight for a DuckLake ATTACH. Reads the catalog's recorded
+ * format version from its `ducklake_metadata` table via a plain postgres ATTACH
+ * (this does NOT invoke the DuckLake extension on the catalog), and checks it
+ * against the format range the running DuckDB engine supports (see
+ * `ducklake_version.ts`). On a mismatch it throws an
+ * {@link UnsupportedCatalogFormatError} (→ HTTP 422) naming the format found,
+ * the supported range, and where to migrate — instead of letting the real
+ * DuckLake ATTACH fail deep inside DuckDB as an opaque 500.
+ *
+ * Non-load-bearing on its own read: any failure of the preflight itself
+ * (missing `ducklake_metadata` table, non-postgres catalog, query timeout,
+ * connect failure, an engine with no matrix row) logs and returns so the real
+ * ATTACH below stays the source of truth for unrelated errors. Only a
+ * successfully-read, definitively-out-of-range format raises the clean 422.
+ *
+ * The temp attach uses a per-call unique name so a failed DETACH can't wedge
+ * the fixed name (which would make every later preflight for this connection
+ * fail its ATTACH with "already exists" and silently skip), and so two
+ * concurrent first-touch lookups can't cross-DETACH each other.
+ */
+let ducklakePreflightSeq = 0;
+async function preflightDuckLakeCatalogFormat(
+   connection: DuckDBConnection,
+   dbName: string,
+   pgConnString: string,
+): Promise<void> {
+   const tempDb = `${dbName}_fmt_preflight_${++ducklakePreflightSeq}`;
+   let catalogFormat: string | undefined;
+   try {
+      await connection.runSQL(
+         `ATTACH '${escapeSQL(pgConnString)}' AS ${tempDb} (TYPE postgres, READ_ONLY);`,
+      );
+      const result = await connection.runSQL(
+         `SELECT value FROM ${tempDb}.ducklake_metadata WHERE key = 'version' LIMIT 1;`,
+      );
+      const value = runSQLRows(result)[0]?.value;
+      catalogFormat = typeof value === "string" ? value : undefined;
+   } catch (error) {
+      logger.warn(
+         "DuckLake catalog-format preflight read failed; falling back to ATTACH",
+         {
+            dbName,
+            error: redactPgSecrets(
+               error instanceof Error ? error.message : String(error),
+            ),
+         },
+      );
+      return;
+   } finally {
+      try {
+         await connection.runSQL(`DETACH ${tempDb};`);
+      } catch {
+         // The ATTACH may have failed, so there may be nothing to detach.
+      }
+   }
+
+   if (!catalogFormat) {
+      // Table present but no version row, or unreadable value: let ATTACH decide.
+      return;
+   }
+
+   // Derive the supported range from the engine DuckDB actually reports. An
+   // unknown engine (no matrix row) yields null → skip (the CI version-contract
+   // check is what guarantees the pinned engine is always covered).
+   let engineVersion = "";
+   try {
+      const versionResult = await connection.runSQL("SELECT version() AS v;");
+      engineVersion = String(runSQLRows(versionResult)[0]?.v ?? "");
+   } catch (error) {
+      logger.warn(
+         "DuckLake catalog-format preflight: could not read engine version; skipping",
+         {
+            dbName,
+            error: error instanceof Error ? error.message : String(error),
+         },
+      );
+      return;
+   }
+
+   const range = catalogFormatRangeForEngine(engineVersion);
+   if (!range) {
+      logger.warn(
+         "DuckLake catalog-format preflight: engine not covered by the format matrix; skipping",
+         { dbName, engineVersion },
+      );
+      return;
+   }
+
+   if (!isCatalogFormatInRange(catalogFormat, range)) {
+      logger.warn(
+         "DuckLake catalog format outside supported range; rejecting",
+         {
+            dbName,
+            catalogFormat,
+            supportedMin: range.min,
+            supportedMax: range.max,
+            engineVersion: range.engineVersion,
+         },
+      );
+      throw new UnsupportedCatalogFormatError(
+         `DuckLake catalog '${dbName}' has format version ${catalogFormat}, ` +
+            `which is outside the range this Publisher supports ` +
+            `(${range.min} ≤ format ≤ ${range.max}). The DuckLake ` +
+            `extension bundled with DuckDB v${range.engineVersion} attaches only ` +
+            `catalogs in that range without migration. Migrate the catalog to a ` +
+            `supported format (see the DuckLake catalog-migration docs at ` +
+            `https://ducklake.select/docs), or run a Publisher built against a ` +
+            `DuckDB engine whose supported range includes ${catalogFormat}.`,
+      );
+   }
+
+   logger.info(
+      `DuckLake catalog '${dbName}' format ${catalogFormat} is within supported range ` +
+         `${range.min}..${range.max} (engine v${range.engineVersion})`,
+   );
+}
+
 async function attachDuckLake(
    connection: DuckDBConnection,
    dbName: string,
    ducklakeConfig: components["schemas"]["DucklakeConnection"],
 ): Promise<void> {
+   // Tier build/serve DuckLake sessions never implicitly auto-install (Publisher
+   // installs the DuckLake stack explicitly below) — regardless of the policy.
+   await applyExtensionSessionSettings(connection, {
+      alwaysDisableAutoinstall: true,
+   });
    await installAndLoadExtension(connection, "ducklake");
    await installAndLoadExtension(connection, "postgres");
    await installAndLoadExtension(connection, "aws");
@@ -387,6 +627,9 @@ async function attachDuckLake(
    );
    const escapedBucketUrl = escapeSQL(ducklakeConfig.storage.bucketUrl);
    logger.info(`escapedBucketUrl: ${escapedBucketUrl}`);
+   // Range-preflight the catalog's recorded format version so an unsupported
+   // catalog fails as a clean, actionable 422 rather than a deep DuckDB 500.
+   await preflightDuckLakeCatalogFormat(connection, dbName, pgConnString);
    const attachCommand = `ATTACH OR REPLACE 'ducklake:postgres:${escapedPgConnString}' AS ${dbName} (DATA_PATH '${escapedBucketUrl}', OVERRIDE_DATA_PATH true, READ_ONLY true);`;
    logger.info(
       `Attaching DuckLake database using command: ${redactPgSecrets(attachCommand)}`,
@@ -632,6 +875,12 @@ async function attachDatabasesToDuckDB(
       azure: attachAzureStorage,
    };
 
+   // Generic (non-tier) attach session: defer to the deployment policy — off
+   // under local-only, left at DuckDB's default under on-demand so existing
+   // users see no behaviour change. Publisher still installs each attached
+   // type's extension explicitly below.
+   await applyExtensionSessionSettings(duckdbConnection);
+
    // Pre-load extensions needed by any attached database type, once per connection
    const hasAzure = attachedDatabases.some((db) => db.type === "azure");
    if (hasAzure) {
@@ -926,13 +1175,14 @@ function buildSnowflakePrivateKeyConnection(
 }
 
 // TLS mode for a proxied postgres connection, as `pg` connectionString query
-// params. @malloydata/db-postgres exposes no ssl config, but it forwards a
-// connectionString straight to pg — which parses sslmode. The tunnel terminates
-// at 127.0.0.1, so pg's hostname check can't apply: `verify-ca` validates the
-// cert chain against the trusted CA bundle (NODE_EXTRA_CA_CERTS, e.g. the baked
+// params. @malloydata/db-postgres forwards a connectionString straight to pg —
+// which parses sslmode. The tunnel terminates at 127.0.0.1, so pg's hostname
+// check can't apply from the connectionString: `verify-ca` validates the cert
+// chain against the trusted CA bundle (NODE_EXTRA_CA_CERTS, e.g. the baked
 // Amazon RDS roots) WITHOUT the hostname; `no-verify` encrypts without checking;
-// `disable` uses no TLS. Full verify-full through a tunnel needs a servername
-// override (a raw ssl object) — awaits an upstream passthrough (malloydata/malloy#2960).
+// `disable` uses no TLS. `verify-full` (chain + hostname) can't be expressed as
+// a connectionString param through a tunnel — it needs a raw `ssl` object with
+// `servername` set to the real host; see resolveProxiedTls below.
 export function buildProxiedSslQuery(name: string, sslmode?: string): string {
    const caBundle = process.env.NODE_EXTRA_CA_CERTS;
    // Default: encrypt (no-verify) so a force-SSL target (the common RDS case)
@@ -958,11 +1208,39 @@ export function buildProxiedSslQuery(name: string, sslmode?: string): string {
          return `?uselibpqcompat=true&sslmode=verify-ca&sslrootcert=${encodeURIComponent(caBundle)}`;
       default:
          throw new Error(
-            `Connection proxy on '${name}' has unsupported sslmode '${mode}' (expected disable | no-verify | verify-ca).`,
+            `Connection proxy on '${name}' has unsupported sslmode '${mode}' (expected disable | no-verify | verify-ca; verify-full is applied via the ssl object in resolveProxiedTls, not this query).`,
          );
    }
 }
 
+// Resolve a proxied connection's TLS mode into either a connectionString query
+// suffix (disable/no-verify/verify-ca — parsed by pg from the connectionString)
+// or a raw `ssl` object. `verify-full` takes the ssl path: full verification
+// (chain + hostname) through a tunnel needs `servername` set to the real DB host,
+// which a connectionString sslmode param can't carry. The socket targets the
+// 127.0.0.1 IP literal, so pg preserves our `servername` (it only overwrites it
+// with `host` when host is a DNS name), verifying the cert's SAN against the real
+// host. Verification runs against Node's ambient trust anchors — its bundled
+// Mozilla CA roots plus NODE_EXTRA_CA_CERTS (e.g. the baked Amazon RDS roots) —
+// not the OS system store (unless Node is run with --use-system-ca).
+export function resolveProxiedTls(
+   name: string,
+   host: string | undefined,
+   sslmode?: string,
+): { query: string; ssl?: PostgresSSLConfig } {
+   if (sslmode === "verify-full") {
+      if (!host) {
+         // validateConnectionShape requires host on a proxied connection, so this
+         // is unreachable in practice — guard so servername is never undefined.
+         throw new Error(
+            `Connection proxy on '${name}' uses sslmode 'verify-full' but has no host to verify against.`,
+         );
+      }
+      return { query: "", ssl: { servername: host, rejectUnauthorized: true } };
+   }
+   return { query: buildProxiedSslQuery(name, sslmode) };
+}
+
 function buildProxiedPostgresConnection(
    metadata: EnvironmentConnectionMetadata,
    endpoint: ProxyEndpoint,
@@ -983,11 +1261,12 @@ function buildProxiedPostgresConnection(
       ? `${enc(pg.userName)}${pg.password ? `:${enc(pg.password)}` : ""}@`
       : "";
    const db = pg.databaseName ? `/${enc(pg.databaseName)}` : "";
-   const ssl = buildProxiedSslQuery(name, pg.sslmode);
-   const connectionString = `postgresql://${auth}${endpoint.host}:${endpoint.port}${db}${ssl}`;
+   const { query, ssl } = resolveProxiedTls(name, pg.host, pg.sslmode);
+   const connectionString = `postgresql://${auth}${endpoint.host}:${endpoint.port}${db}${query}`;
    return new PooledPostgresConnection({
       name,
       connectionString,
+      ...(ssl ? { ssl } : {}),
       // Pool sizing mirrors buildSnowflakePrivateKeyConnection.
       poolMin: 1,
       poolMax: 20,
@@ -1248,13 +1527,21 @@ export function buildEnvironmentMalloyConfig(
          return {
             lookupConnection: async (name?: string): Promise<Connection> => {
                const metadata = getMetadataForLookup(assembled.metadata, name);
+               const connection = await resolveConnection(name, metadata);
+               // Pin every environment-level DuckDB session against implicit
+               // auto-install (policy-driven) at this one exit — independent of
+               // the attach paths, so the guarantee holds even if a resolution
+               // branch is ever added that doesn't attach. The DuckLake tier
+               // already pinned always-off inside its attach; the WeakSet makes
+               // this a no-op there. (The per-package `:memory:` sandbox is a
+               // separate MalloyConfig and is pinned in package.ts.)
+               if (isDuckDBConnection(connection)) {
+                  await applyExtensionSessionSettings(connection);
+               }
                // Every resolution branch funnels through this one exit so a
                // configured fingerprint is applied no matter which wrapper
                // produced the connection (see applyConnectionFingerprint).
-               return applyConnectionFingerprint(
-                  await resolveConnection(name, metadata),
-                  metadata,
-               );
+               return applyConnectionFingerprint(connection, metadata);
             },
          };
       },

package/src/service/connection_config.spec.ts

@@ -572,6 +572,27 @@ describe("SSH proxy validation", () => {
       }
    });
 
+   it("accepts sslmode=verify-full on a proxied connection with no CA bundle (verifies against Node's bundled CA roots + NODE_EXTRA_CA_CERTS)", () => {
+      // Unlike verify-ca (which passes an explicit sslrootcert path and so
+      // fails fast without NODE_EXTRA_CA_CERTS), verify-full trusts Node's
+      // bundled Mozilla CA roots + NODE_EXTRA_CA_CERTS — so it must NOT require
+      // a bundle at load.
+      const prior = process.env.NODE_EXTRA_CA_CERTS;
+      delete process.env.NODE_EXTRA_CA_CERTS;
+      try {
+         const conn: ApiConnection = {
+            ...validSshProxy,
+            postgresConnection: {
+               ...validSshProxy.postgresConnection!,
+               sslmode: "verify-full",
+            },
+         };
+         expect(() => assembleEnvironmentConnections([conn])).not.toThrow();
+      } finally {
+         if (prior !== undefined) process.env.NODE_EXTRA_CA_CERTS = prior;
+      }
+   });
+
    it("rejects sslmode set on a non-proxied connection (silent-ignore footgun)", () => {
       const conn: ApiConnection = {
          name: "pg-direct",

package/src/service/connection_config.ts

@@ -11,7 +11,12 @@ type AttachedDatabase = components["schemas"]["AttachedDatabase"];
 // than in connection.ts, which imports this module) so both the config-load
 // validator and the connect-time builder derive from one list. Mirrors the
 // `sslmode` enum in api-doc.yaml.
-export const PROXIED_SSLMODES = ["disable", "no-verify", "verify-ca"] as const;
+export const PROXIED_SSLMODES = [
+   "disable",
+   "no-verify",
+   "verify-ca",
+   "verify-full",
+] as const;
 
 export type CoreConnectionEntry = {
    is: string;
@@ -356,6 +361,15 @@ function validateConnectionShape(connection: ApiConnection): void {
                );
             }
          }
+         // No precondition for `verify-full`: unlike `verify-ca` (which passes an
+         // explicit `sslrootcert` path), it verifies against Node's ambient trust
+         // anchors (its bundled Mozilla CA roots + NODE_EXTRA_CA_CERTS), so
+         // requiring a bundle here would wrongly reject targets with a
+         // publicly-trusted CA. An untrusted CA surfaces as a clear pg error at
+         // connect time instead. This means verify-full's CA trust is broader
+         // than verify-ca's pinned bundle — intentional (it adds the hostname
+         // check without narrowing trust), so unlike libpq, verify-full here is
+         // not a strict superset of verify-ca.
       }
 
       // The proxied path builds a connectionString to the local tunnel endpoint;

package/src/service/ducklake_lazy_attach.spec.ts

@@ -0,0 +1,110 @@
+import { DuckDBConnection } from "@malloydata/db-duckdb";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import fs from "fs/promises";
+import path from "path";
+import sinon from "sinon";
+import { components } from "../api";
+import { buildEnvironmentMalloyConfig } from "./connection";
+
+type ApiConnection = components["schemas"]["Connection"];
+
+// A DuckLake connection whose Postgres catalog points at an unroutable host.
+// If anything on the boot path tried to reach the catalog, these tests would
+// hang or fail — which is precisely the regression they guard against.
+const UNREACHABLE_DUCKLAKE: ApiConnection = {
+   name: "ducklake_lazy",
+   type: "ducklake",
+   ducklakeConnection: {
+      catalog: {
+         postgresConnection: {
+            host: "192.0.2.1", // TEST-NET-1: guaranteed non-routable
+            port: 5432,
+            userName: "nobody",
+            password: "nobody",
+            databaseName: "catalog",
+         },
+      },
+      storage: {
+         bucketUrl: "s3://test-bucket",
+         s3Connection: {
+            accessKeyId: "test",
+            secretAccessKey: "test",
+         },
+      },
+   },
+} as ApiConnection;
+
+describe("DuckLake lazy attach", () => {
+   const envPath = path.join(process.cwd(), "test-ducklake-lazy-attach");
+
+   beforeEach(async () => {
+      await fs.mkdir(envPath, { recursive: true });
+   });
+
+   afterEach(async () => {
+      sinon.restore();
+      await fs.rm(envPath, { recursive: true, force: true }).catch(() => {});
+   });
+
+   it("does not attach the catalog while building the environment config (boot path)", async () => {
+      // Stub the DuckDB session so no real database or network work happens; the
+      // stub also lets us observe whether ANY SQL ran during config build.
+      const runSQL = sinon
+         .stub(DuckDBConnection.prototype, "runSQL")
+         .resolves({ rows: [] } as never);
+
+      // Building the config is the worker boot path. It must be synchronous and
+      // must not open, construct, or touch the DuckLake session at all.
+      const config = buildEnvironmentMalloyConfig(
+         [UNREACHABLE_DUCKLAKE],
+         envPath,
+      );
+
+      expect(config.apiConnections.map((c) => c.name)).toContain(
+         "ducklake_lazy",
+      );
+      // The definitive assertion: zero SQL was issued building the config, so
+      // the (unreachable) catalog could not have been contacted on boot.
+      expect(runSQL.callCount).toBe(0);
+   });
+
+   it("cannot let an unavailable catalog block startup", async () => {
+      sinon
+         .stub(DuckDBConnection.prototype, "runSQL")
+         .resolves({ rows: [] } as never);
+
+      // Even with an unreachable catalog, constructing the environment config
+      // resolves promptly and never awaits the catalog. If attach were on the
+      // boot path, this would hang against 192.0.2.1 until a connect timeout.
+      const config = buildEnvironmentMalloyConfig(
+         [UNREACHABLE_DUCKLAKE],
+         envPath,
+      );
+      expect(config).toBeDefined();
+      expect(config.malloyConfig).toBeDefined();
+   });
+
+   it("attaches the catalog only on first connection lookup (serve path)", async () => {
+      const runSQL = sinon
+         .stub(DuckDBConnection.prototype, "runSQL")
+         .resolves({ rows: [] } as never);
+
+      const config = buildEnvironmentMalloyConfig(
+         [UNREACHABLE_DUCKLAKE],
+         envPath,
+      );
+      expect(runSQL.callCount).toBe(0);
+
+      // The lazy attach fires here, on the first lookup — not before.
+      await config.malloyConfig.connections.lookupConnection("ducklake_lazy");
+
+      const issued = runSQL.getCalls().map((c) => String(c.args[0]));
+      const attachedDuckLake = issued.some((sql) =>
+         sql.includes("ducklake:postgres:"),
+      );
+      expect(runSQL.callCount).toBeGreaterThan(0);
+      expect(attachedDuckLake).toBe(true);
+
+      await config.releaseConnections().catch(() => {});
+   });
+});