@malloy-publisher/server 0.0.218 → 0.0.220

package/src/server.ts

@@ -20,6 +20,7 @@ import {
    BadRequestError,
    internalErrorToHttpError,
    NotImplementedError,
+   ServiceUnavailableError,
 } from "./errors";
 import {
    drainingGuard,
@@ -38,6 +39,7 @@ import { setFilterDeprecationHeaders } from "./filter_deprecation";
 import { checkHeapConfiguration } from "./heap_check";
 import { queryConcurrency } from "./query_concurrency";
 import { MaterializationController } from "./controller/materialization.controller";
+import { ThemeController } from "./controller/theme.controller";
 import { initializeMcpServer } from "./mcp/server";
 import { startAgentMcpServer } from "./mcp/agent_server";
 import { registerLegacyRoutes } from "./server-old";
@@ -45,6 +47,7 @@ import { EnvironmentStore } from "./service/environment_store";
 import { MaterializationService } from "./service/materialization_service";
 import { normalizeQueryArray } from "./query_param_utils";
 import { PackageMemoryGovernor } from "./service/package_memory_governor";
+import { ThemeStore } from "./service/theme_store";
 import { assertSafePackageName, safeJoinUnderRoot } from "./path_safety";
 
 export { normalizeQueryArray } from "./query_param_utils";
@@ -207,6 +210,8 @@ const materializationService = new MaterializationService(environmentStore);
 const materializationController = new MaterializationController(
    materializationService,
 );
+const themeStore = new ThemeStore(environmentStore.storageManager, SERVER_ROOT);
+const themeController = new ThemeController(themeStore, SERVER_ROOT);
 
 export const mcpApp = express();
 
@@ -722,7 +727,20 @@ app.get(
 app.get(`${API_PREFIX}/status`, async (_req, res) => {
    try {
       const status = await environmentStore.getStatus();
-      res.status(200).json(status);
+      // Compose theme onto the status response so the SDK can read both
+      // in one round trip on app boot. ThemeStore is the source of truth;
+      // publisher.config.json is only a boot seed (see ThemeStore). The
+      // field is always present (an empty object means "no overrides
+      // yet"), so the OpenAPI shape and the runtime payload agree.
+      // The theme here is cosmetic, so during the brief window before storage
+      // initializes report no overrides rather than 500 an endpoint the
+      // control plane polls for serving state (themeStore.get() throws until
+      // storage is ready). GET /theme, the editor's authoritative load, is
+      // answered with 503 during that window instead.
+      const theme = environmentStore.storageManager.isInitialized()
+         ? await themeStore.get()
+         : undefined;
+      res.status(200).json({ ...status, theme: theme ?? {} });
    } catch (error) {
       logger.error("Error getting status", { error });
       const { json, status } = internalErrorToHttpError(error as Error);
@@ -730,6 +748,45 @@ app.get(`${API_PREFIX}/status`, async (_req, res) => {
    }
 });
 
+app.get(`${API_PREFIX}/theme`, async (_req, res) => {
+   try {
+      if (!environmentStore.storageManager.isInitialized()) {
+         // Storage is still initializing. Answer 503 (not 200 with an empty
+         // theme) so the Theme Editor's load stays in an error state and
+         // never adopts {} as the authoritative saved baseline, which would
+         // let a subsequent edit auto-save {} over the real persisted theme.
+         throw new ServiceUnavailableError(
+            "Theme storage is still initializing. Retry shortly.",
+         );
+      }
+      res.status(200).json(await themeController.getTheme());
+   } catch (error) {
+      logger.error("Error getting theme", { error });
+      const { json, status } = internalErrorToHttpError(error as Error);
+      res.status(status).json(json);
+   }
+});
+
+app.put(`${API_PREFIX}/theme`, async (req, res) => {
+   try {
+      res.status(200).json(await themeController.putTheme(req.body));
+   } catch (error) {
+      logger.error("Error saving theme", { error });
+      const { json, status } = internalErrorToHttpError(error as Error);
+      res.status(status).json(json);
+   }
+});
+
+app.delete(`${API_PREFIX}/theme`, async (_req, res) => {
+   try {
+      res.status(200).json(await themeController.resetTheme());
+   } catch (error) {
+      logger.error("Error resetting theme", { error });
+      const { json, status } = internalErrorToHttpError(error as Error);
+      res.status(status).json(json);
+   }
+});
+
 app.get(`${API_PREFIX}/watch-mode/status`, watchModeController.getWatchStatus);
 app.post(`${API_PREFIX}/watch-mode/start`, watchModeController.startWatching);
 app.post(`${API_PREFIX}/watch-mode/stop`, watchModeController.stopWatchMode);

package/src/service/build_plan.spec.ts

@@ -4,7 +4,7 @@ import * as sinon from "sinon";
 import type { BuildGraph as MalloyBuildGraph } from "@malloydata/malloy";
 import {
    compilePackageBuildPlan,
-   computeBuildId,
+   computeSourceEntityId,
    computePackageBuildPlan,
    deriveAnnotationFields,
    deriveBuildPlan,
@@ -27,8 +27,8 @@ describe("flattenDependsOn", () => {
 
 describe("iterGraphSources", () => {
    it("yields resolvable sources in dependency order, skipping missing ones", () => {
-      const a = fakeSource({ name: "a", buildId: "ba" });
-      const b = fakeSource({ name: "b", buildId: "bb" });
+      const a = fakeSource({ name: "a", sourceEntityId: "ba" });
+      const b = fakeSource({ name: "b", sourceEntityId: "bb" });
       const graph = {
          connectionName: "duckdb",
          nodes: [
@@ -52,9 +52,9 @@ describe("iterGraphSources", () => {
       // and every transitive persist dependency is nested in dependsOn. All
       // three must be yielded (so all get built), leaf-first so a downstream
       // build reads its upstream's freshly materialized table.
-      const root = fakeSource({ name: "root", buildId: "br" });
-      const mid = fakeSource({ name: "mid", buildId: "bm" });
-      const leaf = fakeSource({ name: "leaf", buildId: "bl" });
+      const root = fakeSource({ name: "root", sourceEntityId: "br" });
+      const mid = fakeSource({ name: "mid", sourceEntityId: "bm" });
+      const leaf = fakeSource({ name: "leaf", sourceEntityId: "bl" });
       const graph = {
          connectionName: "duckdb",
          nodes: [
@@ -85,9 +85,9 @@ describe("iterGraphSources", () => {
    it("deduplicates a shared (diamond) dependency across roots", () => {
       // r1 and r2 both depend on `shared`; it must be yielded exactly once and
       // before both dependents.
-      const r1 = fakeSource({ name: "r1", buildId: "b1" });
-      const r2 = fakeSource({ name: "r2", buildId: "b2" });
-      const shared = fakeSource({ name: "shared", buildId: "bs" });
+      const r1 = fakeSource({ name: "r1", sourceEntityId: "b1" });
+      const r2 = fakeSource({ name: "r2", sourceEntityId: "b2" });
+      const shared = fakeSource({ name: "shared", sourceEntityId: "bs" });
       const graph = {
          connectionName: "duckdb",
          nodes: [
@@ -149,7 +149,7 @@ describe("deriveAnnotationFields", () => {
    });
 });
 
-describe("computeBuildId", () => {
+describe("computeSourceEntityId", () => {
    it("delegates to PersistSource.makeBuildId with the connection digest and SQL", () => {
       const makeBuildId = sinon.stub().returns("computed-id");
       const source = {
@@ -158,7 +158,7 @@ describe("computeBuildId", () => {
          getSQL: () => "SELECT 7",
       } as unknown as PersistSource;
 
-      const id = computeBuildId(source, { duckdb: "dig-1" });
+      const id = computeSourceEntityId(source, { duckdb: "dig-1" });
 
       expect(id).toBe("computed-id");
       expect(makeBuildId.calledOnceWithExactly("dig-1", "SELECT 7")).toBe(true);
@@ -188,7 +188,7 @@ describe("deriveBuildPlan", () => {
    it("projects graphs and sources into the wire build plan", () => {
       const orders = fakeSource({
          name: "orders",
-         buildId: "bid-orders",
+         sourceEntityId: "bid-orders",
          sql: "SELECT 1",
       });
       const plan = deriveBuildPlan(
@@ -206,15 +206,15 @@ describe("deriveBuildPlan", () => {
       expect(plan.sources["orders@m"]).toMatchObject({
          name: "orders",
          connectionName: "duckdb",
-         buildId: "bid-orders",
+         sourceEntityId: "bid-orders",
          sql: "SELECT 1",
          columns: [],
       });
    });
 
    it("honors the sourceNames filter", () => {
-      const a = fakeSource({ name: "a", buildId: "bid-a" });
-      const b = fakeSource({ name: "b", buildId: "bid-b" });
+      const a = fakeSource({ name: "a", sourceEntityId: "bid-a" });
+      const b = fakeSource({ name: "b", sourceEntityId: "bid-b" });
       const plan = deriveBuildPlan(
          [
             {
@@ -231,8 +231,8 @@ describe("deriveBuildPlan", () => {
    });
 
    it("carries the per-source package-relative modelPath", () => {
-      const a = fakeSource({ name: "a", buildId: "bid-a" });
-      const b = fakeSource({ name: "b", buildId: "bid-b" });
+      const a = fakeSource({ name: "a", sourceEntityId: "bid-a" });
+      const b = fakeSource({ name: "b", sourceEntityId: "bid-b" });
       const plan = deriveBuildPlan(
          [
             {

package/src/service/build_plan.ts

@@ -112,8 +112,8 @@ export function flattenDependsOn(node: {
  * persist dependency is nested under a root in its recursive {@code dependsOn}
  * tree (and present in {@code sources}). Walking only {@code graph.nodes}
  * silently skips every intermediate persist source, so it never gets
- * materialized (it only gets a table by coincidence when it shares a buildId
- * with a root). We post-order DFS the {@code dependsOn} tree
+ * materialized (it only gets a table by coincidence when it shares a
+ * sourceEntityId with a root). We post-order DFS the {@code dependsOn} tree
  * so dependencies are built first (a downstream build can then read its upstream
  * source's freshly materialized table), deduplicating shared (diamond)
  * dependencies by sourceID so each is yielded once. This mirrors the canonical
@@ -147,11 +147,23 @@ export function* iterGraphSources(
 }
 
 /**
- * The buildId for a persist source: a stable digest of its connection identity
- * and canonical SQL. Centralizes the (source, connectionDigests) call shape so
- * planning, self-instruction, and build all agree on the same id.
+ * The sourceEntityId for a persist source: a stable content address of its
+ * connection identity and canonical SQL. Centralizes the
+ * (source, connectionDigests) call shape so planning, self-instruction, build,
+ * and serve-time manifest resolution all agree on the same id.
+ *
+ * <p>This is the single seam between the publisher and the Malloy compiler's
+ * source-identity recipe. Today it delegates to
+ * {@code PersistSource.makeBuildId(connectionDigest, sql)} — the compiler's
+ * current hex content hash. The connection's contribution is already
+ * fingerprint-aware: when a connection carries an API `fingerprint`, its
+ * digest IS that fingerprint verbatim (see applyConnectionFingerprint in
+ * connection.ts), so ids stay stable across credential rotation. When the
+ * compiler ships the scoped UUID5 sourceEntityId recipe (scope + connection
+ * fingerprint + canonical SQL), swap the delegation below to the new compiler
+ * API — this function is the only place the publisher derives the id.
  */
-export function computeBuildId(
+export function computeSourceEntityId(
    source: PersistSource,
    connectionDigests: Record<string, string>,
 ): string {
@@ -246,9 +258,9 @@ export async function compilePackageBuildPlan(
       const conn = connections.get(graph.connectionName);
       if (!conn) {
          // The connection failed to resolve (already warned in
-         // resolvePackageConnections). Its buildIds will be computed without a
-         // digest, so surface it as a discrete correctness signal rather than
-         // skipping silently.
+         // resolvePackageConnections). Its sourceEntityIds will be computed
+         // without a digest, so surface it as a discrete correctness signal
+         // rather than skipping silently.
          recordConnectionDigestSkipped();
          logger.warn("Skipping connection digest; connection did not resolve", {
             connectionName: graph.connectionName,
@@ -256,6 +268,9 @@ export async function compilePackageBuildPlan(
          continue;
       }
       if (!connectionDigests[graph.connectionName]) {
+         // getDigest() is fingerprint-aware: a connection configured with an
+         // API `fingerprint` returns it verbatim (applyConnectionFingerprint),
+         // so a credential rotation does not re-address its sources.
          connectionDigests[graph.connectionName] = await conn.getDigest();
       }
    }
@@ -297,7 +312,7 @@ export function deriveBuildPlan(
          sourceID: source.sourceID,
          connectionName: source.connectionName,
          dialect: source.dialectName,
-         buildId: computeBuildId(source, connectionDigests),
+         sourceEntityId: computeSourceEntityId(source, connectionDigests),
          sql: source.getSQL(),
          columns: deriveColumns(source),
          annotationFields: deriveAnnotationFields(source),

package/src/service/connection.spec.ts

@@ -1,10 +1,12 @@
 import { DuckDBConnection } from "@malloydata/db-duckdb";
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import fs from "fs/promises";
+import os from "os";
 import path from "path";
 import sinon from "sinon";
 import { components } from "../api";
 import {
+   buildProxiedSslQuery,
    createEnvironmentConnections,
    testConnectionConfig,
 } from "./connection";
@@ -1846,3 +1848,71 @@ describe("connection integration tests", () => {
       );
    });
 });
+
+describe("buildProxiedSslQuery", () => {
+   const ORIG_CA = process.env.NODE_EXTRA_CA_CERTS;
+   afterEach(() => {
+      if (ORIG_CA === undefined) delete process.env.NODE_EXTRA_CA_CERTS;
+      else process.env.NODE_EXTRA_CA_CERTS = ORIG_CA;
+   });
+
+   it("defaults to no-verify when sslmode is unset (force-SSL target isn't rejected for plaintext)", () => {
+      expect(buildProxiedSslQuery("conn")).toBe("?sslmode=no-verify");
+   });
+
+   it("returns no-verify for explicit no-verify", () => {
+      expect(buildProxiedSslQuery("conn", "no-verify")).toBe(
+         "?sslmode=no-verify",
+      );
+   });
+
+   it("emits an explicit sslmode=disable, never an empty query", () => {
+      // Regression: an empty query lets pg fall back to the deployment's PGSSLMODE
+      // env, which would verify and fail the 127.0.0.1 hostname check.
+      expect(buildProxiedSslQuery("conn", "disable")).toBe("?sslmode=disable");
+   });
+
+   it("builds a chain-verifying, hostname-skipped query for verify-ca", () => {
+      process.env.NODE_EXTRA_CA_CERTS = "/etc/ssl/certs/rds bundle.pem";
+      const q = buildProxiedSslQuery("conn", "verify-ca");
+      expect(q).toContain("uselibpqcompat=true");
+      expect(q).toContain("sslmode=verify-ca");
+      expect(q).toContain(
+         `sslrootcert=${encodeURIComponent("/etc/ssl/certs/rds bundle.pem")}`,
+      );
+   });
+
+   it("throws for verify-ca when no CA bundle is available", () => {
+      delete process.env.NODE_EXTRA_CA_CERTS;
+      expect(() => buildProxiedSslQuery("conn", "verify-ca")).toThrow(
+         /no trusted CA bundle/i,
+      );
+   });
+
+   it("throws for an unsupported sslmode", () => {
+      expect(() => buildProxiedSslQuery("conn", "require")).toThrow(
+         /unsupported sslmode/i,
+      );
+   });
+
+   it("verify-ca connectionString parses to an ssl config (pg-connection-string version guard)", async () => {
+      // uselibpqcompat=true (pg-connection-string >= 2.7) is what turns verify-ca
+      // into "verify chain, skip hostname". If pg is ever downgraded below that
+      // floor, sslmode would be ignored — this guard fails loudly instead.
+      const caPath = path.join(os.tmpdir(), `proxy-ca-${process.pid}.pem`);
+      await fs.writeFile(
+         caPath,
+         "-----BEGIN CERTIFICATE-----\nMIIB\n-----END CERTIFICATE-----\n",
+      );
+      process.env.NODE_EXTRA_CA_CERTS = caPath;
+      try {
+         const q = buildProxiedSslQuery("conn", "verify-ca");
+         const { parse } = await import("pg-connection-string");
+         const parsed = parse(`postgresql://127.0.0.1:5432/db${q}`);
+         expect(parsed.ssl).toBeTruthy();
+         expect(typeof parsed.ssl).toBe("object");
+      } finally {
+         await fs.rm(caPath, { force: true });
+      }
+   });
+});

package/src/service/connection.ts

@@ -925,6 +925,44 @@ 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
+// 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).
+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)
+   // isn't rejected for plaintext. Operators opt up to verify-ca when the
+   // target's CA is in the trust bundle, or down to disable for non-TLS DBs.
+   const mode = sslmode ?? "no-verify";
+   switch (mode) {
+      case "disable":
+         // Explicit: with no sslmode in the connectionString, pg falls back to
+         // the PGSSLMODE env (set on the non-proxied path), which would verify
+         // and fail the 127.0.0.1 hostname check. Force plaintext explicitly.
+         return "?sslmode=disable";
+      case "no-verify":
+         return "?sslmode=no-verify";
+      case "verify-ca":
+         // Env-set backstop; validateConnectionShape does the readable-file check
+         // at config load (so a bad bundle fails fast instead of at connect time).
+         if (!caBundle) {
+            throw new Error(
+               `Connection proxy on '${name}' uses sslmode 'verify-ca' but no trusted CA bundle is available (NODE_EXTRA_CA_CERTS is unset). Add the CA bundle to the image or use sslmode 'no-verify'.`,
+            );
+         }
+         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).`,
+         );
+   }
+}
+
 function buildProxiedPostgresConnection(
    metadata: EnvironmentConnectionMetadata,
    endpoint: ProxyEndpoint,
@@ -936,13 +974,20 @@ function buildProxiedPostgresConnection(
          `Proxied connection '${name}' has type 'postgres' but no postgresConnection config.`,
       );
    }
+   // Build a connectionString to the LOCAL tunnel endpoint carrying the TLS mode.
+   // This is NOT the tenant's connectionString (rejected in validateConnectionShape
+   // because it can't be tunneled) — we construct it ourselves and it targets
+   // 127.0.0.1:<localport>, so there's no ambiguity about where it connects.
+   const enc = encodeURIComponent;
+   const auth = pg.userName
+      ? `${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}`;
    return new PooledPostgresConnection({
       name,
-      host: endpoint.host,
-      port: endpoint.port,
-      username: pg.userName,
-      password: pg.password,
-      databaseName: pg.databaseName,
+      connectionString,
       // Pool sizing mirrors buildSnowflakePrivateKeyConnection.
       poolMin: 1,
       poolMax: 20,
@@ -983,6 +1028,38 @@ function getMetadataForLookup(
    return name ? metadata.get(name) : undefined;
 }
 
+/**
+ * Make a connection's digest the caller-supplied API `fingerprint`, verbatim.
+ *
+ * The fingerprint is the connection's data identity as declared by the caller
+ * (secret-free, stable across credential rotation). When set, it replaces the
+ * locally derived `getDigest()` so it becomes the connection's contribution to
+ * content-addressed source ids everywhere a digest is read:
+ *
+ *  - build planning (`compilePackageBuildPlan` -> `conn.getDigest()`),
+ *  - the package-load worker's connection-metadata RPC, and
+ *  - Malloy's own serve-time manifest resolution (the runtime calls
+ *    `conn.getDigest()` internally when a build manifest is bound).
+ *
+ * Overriding the method on the resolved instance — inside the one
+ * `lookupConnection` wrapper every resolution passes through — is what keeps
+ * build-time and serve-time ids identical; applying it per call site would
+ * invite divergence and a silent live-serving fallback. The value is used
+ * verbatim (never re-hashed or combined with local details) and treated as an
+ * opaque token: it is not a secret, but it is never logged or parsed.
+ * Without a fingerprint the connection keeps its locally derived digest.
+ */
+function applyConnectionFingerprint(
+   connection: Connection,
+   metadata: EnvironmentConnectionMetadata | undefined,
+): Connection {
+   const fingerprint = metadata?.apiConnection.fingerprint;
+   if (fingerprint) {
+      connection.getDigest = () => fingerprint;
+   }
+   return connection;
+}
+
 function isDuckDBConnection(
    connection: Connection,
 ): connection is DuckDBConnection {
@@ -1050,10 +1127,11 @@ export function buildEnvironmentMalloyConfig(
    }
 
    malloyConfig.wrapConnections(
-      (base: LookupConnection<Connection>): LookupConnection<Connection> => ({
-         lookupConnection: async (name?: string): Promise<Connection> => {
-            const metadata = getMetadataForLookup(assembled.metadata, name);
-
+      (base: LookupConnection<Connection>): LookupConnection<Connection> => {
+         const resolveConnection = async (
+            name: string | undefined,
+            metadata: EnvironmentConnectionMetadata | undefined,
+         ): Promise<Connection> => {
             if (metadata?.isDuckLake) {
                let connectionPromise = duckLakeCache.get(name!);
                if (!connectionPromise) {
@@ -1165,8 +1243,21 @@ export function buildEnvironmentMalloyConfig(
                await attachOnce(connection, metadata);
             }
             return connection;
-         },
-      }),
+         };
+
+         return {
+            lookupConnection: async (name?: string): Promise<Connection> => {
+               const metadata = getMetadataForLookup(assembled.metadata, name);
+               // 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 {

package/src/service/connection_config.spec.ts

@@ -464,4 +464,142 @@ describe("SSH proxy validation", () => {
          "requires explicit host and port",
       );
    });
+
+   it("accepts a multi-line hostKey and sslmode=no-verify", () => {
+      const conn: ApiConnection = {
+         ...validSshProxy,
+         postgresConnection: {
+            ...validSshProxy.postgresConnection!,
+            sslmode: "no-verify",
+         },
+         proxy: {
+            type: "ssh",
+            ssh: {
+               ...validSshProxy.proxy!.ssh!,
+               hostKey:
+                  "bastion ssh-ed25519 AAAAdecoy\nbastion ssh-rsa AAAAreal",
+            },
+         },
+      };
+      expect(() => assembleEnvironmentConnections([conn])).not.toThrow();
+   });
+
+   it("rejects a hostKey that parses to zero keys (comment/blank only) — fail-closed at config load", () => {
+      const conn: ApiConnection = {
+         ...validSshProxy,
+         proxy: {
+            type: "ssh",
+            ssh: {
+               ...validSshProxy.proxy!.ssh!,
+               hostKey: "# ssh-keyscan bastion timed out\n   \n",
+            },
+         },
+      };
+      expect(() => assembleEnvironmentConnections([conn])).toThrow(
+         "no usable host-key line",
+      );
+   });
+
+   it("rejects a whitespace-only hostKey (must not silently connect unpinned)", () => {
+      const conn: ApiConnection = {
+         ...validSshProxy,
+         proxy: {
+            type: "ssh",
+            ssh: {
+               ...validSshProxy.proxy!.ssh!,
+               hostKey: "   ",
+            },
+         },
+      };
+      expect(() => assembleEnvironmentConnections([conn])).toThrow(
+         "no usable host-key line",
+      );
+   });
+
+   it("treats an empty-string hostKey as unpinned (omission-equivalent)", () => {
+      const conn: ApiConnection = {
+         ...validSshProxy,
+         proxy: {
+            type: "ssh",
+            ssh: { ...validSshProxy.proxy!.ssh!, hostKey: "" },
+         },
+      };
+      expect(() => assembleEnvironmentConnections([conn])).not.toThrow();
+   });
+
+   it("rejects an unsupported sslmode", () => {
+      const conn = {
+         ...validSshProxy,
+         postgresConnection: {
+            ...validSshProxy.postgresConnection!,
+            sslmode: "require",
+         },
+      } as unknown as ApiConnection;
+      expect(() => assembleEnvironmentConnections([conn])).toThrow(
+         "unsupported sslmode 'require'",
+      );
+   });
+
+   it("rejects an empty-string sslmode at config load (not deferred to connect)", () => {
+      const conn = {
+         ...validSshProxy,
+         postgresConnection: {
+            ...validSshProxy.postgresConnection!,
+            sslmode: "",
+         },
+      } as unknown as ApiConnection;
+      expect(() => assembleEnvironmentConnections([conn])).toThrow(
+         "unsupported sslmode",
+      );
+   });
+
+   it("rejects sslmode=verify-ca when no CA bundle is available", () => {
+      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-ca",
+            },
+         };
+         expect(() => assembleEnvironmentConnections([conn])).toThrow(
+            "verify-ca",
+         );
+      } 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",
+         type: "postgres",
+         postgresConnection: {
+            host: "db.example.com",
+            port: 5432,
+            databaseName: "mydb",
+            userName: "user",
+            password: "pass",
+            sslmode: "verify-ca",
+         },
+      };
+      expect(() => assembleEnvironmentConnections([conn])).toThrow(
+         "only supported for proxied connections",
+      );
+   });
+
+   it("rejects a proxied database name with URI-reserved characters", () => {
+      const conn: ApiConnection = {
+         ...validSshProxy,
+         postgresConnection: {
+            ...validSshProxy.postgresConnection!,
+            databaseName: "sales@prod",
+         },
+      };
+      expect(() => assembleEnvironmentConnections([conn])).toThrow(
+         "URI-reserved characters",
+      );
+   });
 });