@malloy-publisher/server 0.0.218 → 0.0.220

package/src/service/materialization_service.ts

@@ -34,7 +34,7 @@ import { errMessage } from "../utils";
 import {
    CompiledBuildPlan,
    compilePackageBuildPlan,
-   computeBuildId,
+   computeSourceEntityId,
    deriveAnnotationFields,
    iterGraphSources,
 } from "./build_plan";
@@ -43,16 +43,17 @@ import { bareTableName, quoteIdentifier, quoteTablePath } from "./quoting";
 import { resolveEnvironmentId } from "./resolve_environment";
 
 /**
- * Length of the buildId prefix used when synthesizing staging table names.
- * buildId is a 64-char SHA-256 hex string; 12 hex chars is 48 bits of
- * entropy, well inside every dialect's identifier limit (Postgres is the
- * tightest at 63).
+ * Length of the sourceEntityId prefix used when synthesizing staging table
+ * names. 12 hex chars is 48 bits of entropy, well inside every dialect's
+ * identifier limit (Postgres is the tightest at 63).
  */
-const STAGING_BUILD_ID_LEN = 12;
+const STAGING_ID_LEN = 12;
 
 /** Staging suffix appended to a table name while it is being built. */
-export function stagingSuffix(buildId: string): string {
-   return `_${buildId.substring(0, STAGING_BUILD_ID_LEN)}`;
+export function stagingSuffix(sourceEntityId: string): string {
+   // Drop hyphens so the suffix stays a bare identifier fragment when the id
+   // becomes a UUID5 (a no-op for the current hex ids).
+   return `_${sourceEntityId.replace(/-/g, "").substring(0, STAGING_ID_LEN)}`;
 }
 
 /**
@@ -334,7 +335,7 @@ export class MaterializationService {
             carried = {};
          } else {
             // Skip-if-unchanged: reuse tables from the most recent successful
-            // manifest for sources whose buildId is unchanged, unless
+            // manifest for sources whose sourceEntityId is unchanged, unless
             // forceRefresh.
             const priorEntries = opts.forceRefresh
                ? {}
@@ -396,7 +397,7 @@ export class MaterializationService {
    /**
     * Derive the publisher's own build instructions for auto-run. Each persist
     * source (respecting the optional sourceNames filter) gets a self-assigned
-    * physical table name and COPY realization, unless its buildId is unchanged
+    * physical table name and COPY realization, unless its sourceEntityId is unchanged
     * since `priorEntries` — those are carried forward (reused) instead of
     * rebuilt.
     */
@@ -420,24 +421,24 @@ export class MaterializationService {
          )) {
             if (include && !include.has(persistSource.name)) continue;
 
-            const buildId = computeBuildId(
+            const sourceEntityId = computeSourceEntityId(
                persistSource,
                compiled.connectionDigests,
             );
-            if (seen.has(buildId)) continue;
-            seen.add(buildId);
+            if (seen.has(sourceEntityId)) continue;
+            seen.add(sourceEntityId);
 
-            const prior = priorEntries[buildId];
+            const prior = priorEntries[sourceEntityId];
             if (prior && prior.physicalTableName) {
-               carried[buildId] = prior;
+               carried[sourceEntityId] = prior;
                continue;
             }
 
             instructions.push({
-               buildId,
-               materializedTableId: `local-${buildId.substring(
+               sourceEntityId,
+               materializedTableId: `local-${sourceEntityId.substring(
                   0,
-                  STAGING_BUILD_ID_LEN,
+                  STAGING_ID_LEN,
                )}`,
                physicalTableName: selfAssignTableName(persistSource),
                realization: "COPY",
@@ -486,9 +487,11 @@ export class MaterializationService {
       entries: Record<string, ManifestEntry>,
    ): Promise<void> {
       const manifestEntries: BuildManifest["entries"] = {};
-      for (const [buildId, entry] of Object.entries(entries)) {
+      for (const [sourceEntityId, entry] of Object.entries(entries)) {
          if (entry.physicalTableName) {
-            manifestEntries[buildId] = { tableName: entry.physicalTableName };
+            manifestEntries[sourceEntityId] = {
+               tableName: entry.physicalTableName,
+            };
          }
       }
       try {
@@ -512,7 +515,7 @@ export class MaterializationService {
 
    /**
     * Validate caller-supplied build instructions against the package's compiled
-    * build plan: every instructed buildId must be a planned source, and only
+    * build plan: every instructed sourceEntityId must be a planned source, and only
     * COPY realization is supported. Throws when the package declares no persist
     * source (no plan to build against).
     */
@@ -525,15 +528,15 @@ export class MaterializationService {
             "Package has no persist sources; buildInstructions cannot be applied",
          );
       }
-      const plannedBuildIds = new Set<string>();
+      const plannedSourceEntityIds = new Set<string>();
       for (const source of Object.values(plan.sources)) {
-         plannedBuildIds.add(source.buildId);
+         plannedSourceEntityIds.add(source.sourceEntityId);
       }
 
       for (const instruction of instructions) {
-         if (!plannedBuildIds.has(instruction.buildId)) {
+         if (!plannedSourceEntityIds.has(instruction.sourceEntityId)) {
             throw new BadRequestError(
-               `Instruction references unknown buildId '${instruction.buildId}'`,
+               `Instruction references unknown sourceEntityId '${instruction.sourceEntityId}'`,
             );
          }
          // COPY-only for now; SNAPSHOT lands once clone semantics are defined.
@@ -561,20 +564,20 @@ export class MaterializationService {
       const { graphs, sources, connectionDigests, connections } = compiled;
 
       // Index instructions by sourceID (the stable per-source handle) so the
-      // build no longer recomputes the buildId to find an instruction.
-      // Recomputing it here forced a caller's buildId to equal the publisher's
-      // content hash, so a caller that derives buildIds by any other scheme
-      // would have its sources silently skipped (the recomputed buildId would
-      // not match the instruction). buildId is treated as opaque, caller-assigned
-      // identity. A buildId index is kept as a fallback for instructions without
+      // build no longer recomputes the sourceEntityId to find an instruction.
+      // Recomputing it here forced a caller's sourceEntityId to equal the publisher's
+      // content hash, so a caller that derives sourceEntityIds by any other scheme
+      // would have its sources silently skipped (the recomputed sourceEntityId would
+      // not match the instruction). sourceEntityId is treated as opaque, caller-assigned
+      // identity. A sourceEntityId index is kept as a fallback for instructions without
       // a sourceID (e.g. standalone auto-run).
       const bySourceID = new Map<string, BuildInstruction>();
-      const byBuildId = new Map<string, BuildInstruction>();
+      const bySourceEntityId = new Map<string, BuildInstruction>();
       for (const instruction of instructions) {
          if (instruction.sourceID) {
             bySourceID.set(instruction.sourceID, instruction);
          }
-         byBuildId.set(instruction.buildId, instruction);
+         bySourceEntityId.set(instruction.sourceEntityId, instruction);
       }
 
       // Accumulates physical names as sources are built so downstream sources
@@ -582,11 +585,13 @@ export class MaterializationService {
       // it with carried-forward entries so reused upstreams resolve too.
       const manifest = new Manifest();
       const entries: Record<string, ManifestEntry> = {};
-      for (const [buildId, entry] of Object.entries(seedEntries)) {
+      for (const [sourceEntityId, entry] of Object.entries(seedEntries)) {
          if (entry.physicalTableName) {
-            manifest.update(buildId, { tableName: entry.physicalTableName });
+            manifest.update(sourceEntityId, {
+               tableName: entry.physicalTableName,
+            });
          }
-         entries[buildId] = entry;
+         entries[sourceEntityId] = entry;
       }
 
       for (const graph of graphs) {
@@ -599,15 +604,19 @@ export class MaterializationService {
          for (const persistSource of iterGraphSources(graph, sources)) {
             if (signal.aborted) throw new Error("Build cancelled");
 
-            // The manifest is keyed by the content buildId — what Malloy
+            // The manifest is keyed by the content sourceEntityId — what Malloy
             // recomputes to resolve upstream persist references during SQL
-            // generation — independent of the instruction's identity buildId.
-            const buildId = computeBuildId(persistSource, connectionDigests);
-            // Prefer sourceID matching (so the caller's buildId scheme stays
-            // opaque to the build); fall back to buildId for instructions
+            // generation — independent of the instruction's identity sourceEntityId.
+            const sourceEntityId = computeSourceEntityId(
+               persistSource,
+               connectionDigests,
+            );
+            // Prefer sourceID matching (so the caller's sourceEntityId scheme stays
+            // opaque to the build); fall back to sourceEntityId for instructions
             // without a sourceID (auto-run).
             const instruction =
-               bySourceID.get(persistSource.sourceID) ?? byBuildId.get(buildId);
+               bySourceID.get(persistSource.sourceID) ??
+               bySourceEntityId.get(sourceEntityId);
             if (!instruction) continue;
 
             const entry = await this.buildOneSource(
@@ -617,7 +626,7 @@ export class MaterializationService {
                connectionDigests,
                manifest,
             );
-            entries[buildId] = entry;
+            entries[sourceEntityId] = entry;
          }
       }
 
@@ -627,7 +636,7 @@ export class MaterializationService {
    /**
     * Build a single instructed source into its assigned physical table.
     * COPY uses a staging table + atomic rename for crash-safety; the staging
-    * name derives from the buildId. Records and returns the manifest entry.
+    * name derives from the sourceEntityId. Records and returns the manifest entry.
     */
    private async buildOneSource(
       persistSource: PersistSource,
@@ -636,7 +645,7 @@ export class MaterializationService {
       connectionDigests: Record<string, string>,
       manifest: Manifest,
    ): Promise<ManifestEntry> {
-      const buildId = instruction.buildId;
+      const sourceEntityId = instruction.sourceEntityId;
       const physicalTableName = instruction.physicalTableName;
       const buildSQL = persistSource.getSQL({
          buildManifest: manifest.buildManifest,
@@ -644,7 +653,7 @@ export class MaterializationService {
       });
 
       const bareName = bareTableName(physicalTableName);
-      const stagingTableName = `${physicalTableName}${stagingSuffix(buildId)}`;
+      const stagingTableName = `${physicalTableName}${stagingSuffix(sourceEntityId)}`;
       // The control plane sends the logical (unquoted) physical name; dialect-
       // quote each identifier here so a container path or quote-requiring name
       // (e.g. a hyphenated BigQuery project id) produces valid DDL. The manifest
@@ -681,7 +690,7 @@ export class MaterializationService {
       }
 
       // Make this table visible to downstream sources built later in this run.
-      manifest.update(buildId, { tableName: physicalTableName });
+      manifest.update(sourceEntityId, { tableName: physicalTableName });
 
       const durationMs = Math.round(performance.now() - startTime);
       recordSourceBuildDuration(durationMs);
@@ -691,7 +700,7 @@ export class MaterializationService {
       });
 
       return {
-         buildId,
+         sourceEntityId,
          sourceName: persistSource.name,
          materializedTableId: instruction.materializedTableId,
          physicalTableName,
@@ -799,7 +808,7 @@ export class MaterializationService {
          if (!connectionName || !physicalTableName) {
             logger.warn("Skipping manifest entry with no connection/table", {
                materializationId: m.id,
-               buildId: entry.buildId,
+               sourceEntityId: entry.sourceEntityId,
             });
             continue;
          }
@@ -825,7 +834,7 @@ export class MaterializationService {
             // table behind; clean it up too while we hold the connection.
             await connection.runSQL(
                `DROP TABLE IF EXISTS ${quoteTablePath(
-                  `${physicalTableName}${stagingSuffix(entry.buildId)}`,
+                  `${physicalTableName}${stagingSuffix(entry.sourceEntityId)}`,
                   dialect,
                )}`,
             );

package/src/service/materialization_test_fixtures.ts

@@ -48,7 +48,7 @@ export function makeBuildPlan(overrides: Partial<BuildPlan> = {}): BuildPlan {
             sourceID: "orders@m.malloy",
             connectionName: "duckdb",
             dialect: "duckdb",
-            buildId: "build-orders",
+            sourceEntityId: "build-orders",
             sql: "SELECT 1",
             columns: [],
          },
@@ -62,7 +62,7 @@ export function makeInstruction(
    overrides: Partial<BuildInstruction> = {},
 ): BuildInstruction {
    return {
-      buildId: "build-orders",
+      sourceEntityId: "build-orders",
       materializedTableId: "mt-1",
       physicalTableName: '"orders_v1"',
       realization: "COPY",
@@ -72,12 +72,12 @@ export function makeInstruction(
 
 /**
  * A minimal stand-in for a Malloy {@link PersistSource} exposing only what the
- * build internals touch (name/id, deterministic buildId, SQL, and the
+ * build internals touch (name/id, deterministic sourceEntityId, SQL, and the
  * `#@ persist name=` annotation reader, defaulted to "unset").
  */
 export function fakeSource(opts: {
    name: string;
-   buildId: string;
+   sourceEntityId: string;
    sql?: string;
    connectionName?: string;
    dialectName?: string;
@@ -87,7 +87,7 @@ export function fakeSource(opts: {
       sourceID: opts.name,
       connectionName: opts.connectionName ?? "duckdb",
       dialectName: opts.dialectName ?? "duckdb",
-      makeBuildId: () => opts.buildId,
+      makeBuildId: () => opts.sourceEntityId,
       getSQL: () => opts.sql ?? "SELECT 1",
       annotations: {
          parseAsTag: () => ({ tag: { text: () => undefined } }),

package/src/service/model.ts

@@ -1931,7 +1931,7 @@ function makeHydrationRuntime(
    // (getSQL) time, gated on `prepareResultOptions.buildManifest`; without this
    // the hydrated model always recomputes from the base tables even though the
    // manifest was bound at load. `strict: false` keeps serving live for any
-   // source whose buildId is absent from the manifest.
+   // source whose sourceEntityId is absent from the manifest.
    return new Runtime({
       urlReader,
       config,

package/src/service/package.ts

@@ -61,7 +61,7 @@ export class Package {
    private packagePath: string;
    private malloyConfig: MalloyConfig;
    // Build-manifest binding state (Malloy Persistence v0). When bound, these
-   // entries (buildId -> { tableName }) are what served queries use to route
+   // entries (sourceEntityId -> { tableName }) are what served queries use to route
    // persist sources to their materialized physical tables; they are also reused
    // by the /compile preview so previewed SQL matches executed SQL. Surfaced on
    // /status (via getPackageMetadata) so the control plane can confirm a worker
@@ -72,7 +72,7 @@ export class Package {
    private manifestEntryCount = 0;
    private boundManifestUri: string | null = null;
    // The package's persist build plan: a deterministic property of the compiled
-   // package (per-source buildId, columns, build SQL, dependency graphs),
+   // package (per-source sourceEntityId, columns, build SQL, dependency graphs),
    // computed once at load from the live (unbound) models so it is stable for a
    // given (package version, connection config). Null when the package declares
    // no persist source. Surfaced read-only on getPackageMetadata() so a caller
@@ -460,7 +460,7 @@ export class Package {
    }
 
    /**
-    * The package's persist build plan (per-source buildId, columns, build SQL,
+    * The package's persist build plan (per-source sourceEntityId, columns, build SQL,
     * dependency graphs), or null when the package declares no persist source.
     * A deterministic property of the compiled package; callers derive build
     * instructions from it for an orchestrated materialization.
@@ -503,7 +503,7 @@ export class Package {
    }
 
    /**
-    * The currently-bound build-manifest entries (buildId -> { tableName }), or
+    * The currently-bound build-manifest entries (sourceEntityId -> { tableName }), or
     * undefined when the package is serving live. Reused by the /compile preview
     * so previewed SQL gets the same persist-source -> physical-table routing as
     * execution.

package/src/service/proxy.spec.ts

@@ -300,39 +300,69 @@ describe("openProxy — SSH tunnel", () => {
             },
             { host: "127.0.0.1", port: echoServer.port },
          ),
-      ).rejects.toThrow(/host-key mismatch/i);
+      ).rejects.toThrow(/host-key verification failed/i);
    });
 
-   it("rejects when hostKey is absent and opt-out env is not set", async () => {
-      const orig = process.env.PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY;
-      delete process.env.PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY;
-
+   it("connects when hostKey is absent — unpinned self-service default", async () => {
+      // No hostKey → connect without host-key verification (the SSH transport is
+      // still encrypted). Matches mainstream BI tools' SSH-tunnel default.
+      const ep = await openProxy(
+         {
+            type: "ssh",
+            ssh: {
+               host: "127.0.0.1",
+               port: sshServer.port,
+               username: "testuser",
+               privateKey: clientPrivatePem,
+            },
+         },
+         { host: "127.0.0.1", port: echoServer.port },
+      );
       try {
-         await expect(
-            openProxy(
-               {
-                  type: "ssh",
-                  ssh: {
-                     host: "127.0.0.1",
-                     port: sshServer.port,
-                     username: "testuser",
-                     privateKey: clientPrivatePem,
-                  },
-               },
-               { host: "127.0.0.1", port: echoServer.port },
-            ),
-         ).rejects.toThrow(/no hostKey provided/i);
+         const reply = await connectAndSend(ep.port, "unpinned");
+         expect(reply).toContain("unpinned");
       } finally {
-         if (orig !== undefined) {
-            process.env.PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY = orig;
-         }
+         await closeQuietly(() => ep.close());
       }
    });
 
-   it("connects when hostKey is absent and opt-out env is set", async () => {
-      process.env.PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY = "true";
+   it("accepts a multi-line hostKey listing several keys — matches any (LB bastion)", async () => {
+      // A load-balanced bastion presents a different host key per backend, so the
+      // pin lists every backend's key and any match is accepted.
+      const decoy = Buffer.alloc(32, 0xff).toString("base64");
+      const multiKey = [
+         `bastion.example.com ssh-ed25519 ${decoy}`,
+         `bastion.example.com ssh-rsa ${sshServer.hostKeyBase64}`,
+      ].join("\n");
+      const ep = await openProxy(
+         {
+            type: "ssh",
+            ssh: {
+               host: "127.0.0.1",
+               port: sshServer.port,
+               username: "testuser",
+               privateKey: clientPrivatePem,
+               hostKey: multiKey,
+            },
+         },
+         { host: "127.0.0.1", port: echoServer.port },
+      );
       try {
-         const ep = await openProxy(
+         const reply = await connectAndSend(ep.port, "multi-key");
+         expect(reply).toContain("multi-key");
+      } finally {
+         await closeQuietly(() => ep.close());
+      }
+   });
+
+   it("fails closed when hostKey is set but parses to zero keys (comment/blank only)", async () => {
+      // A set-but-degenerate pin must NOT fall through to the unpinned branch —
+      // the security boundary is gated on hostKey being configured, not on it
+      // parsing to >=1 key. (Config load rejects this earlier; this guards the
+      // boundary itself.)
+      const commentOnly = "# ssh-keyscan bastion.example.com timed out\n   \n";
+      await expect(
+         openProxy(
             {
                type: "ssh",
                ssh: {
@@ -340,19 +370,36 @@ describe("openProxy — SSH tunnel", () => {
                   port: sshServer.port,
                   username: "testuser",
                   privateKey: clientPrivatePem,
+                  hostKey: commentOnly,
                },
             },
             { host: "127.0.0.1", port: echoServer.port },
-         );
-         try {
-            const reply = await connectAndSend(ep.port, "allow-unknown");
-            expect(reply).toContain("allow-unknown");
-         } finally {
-            await closeQuietly(() => ep.close());
-         }
-      } finally {
-         delete process.env.PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY;
-      }
+         ),
+      ).rejects.toThrow(/host-key verification failed/i);
+   });
+
+   it("rejects a multi-line hostKey when none of the listed keys match", async () => {
+      const decoy1 = Buffer.alloc(32, 0xff).toString("base64");
+      const decoy2 = Buffer.alloc(32, 0xaa).toString("base64");
+      const multiKey = [
+         `bastion.example.com ssh-ed25519 ${decoy1}`,
+         `bastion.example.com ssh-rsa ${decoy2}`,
+      ].join("\n");
+      await expect(
+         openProxy(
+            {
+               type: "ssh",
+               ssh: {
+                  host: "127.0.0.1",
+                  port: sshServer.port,
+                  username: "testuser",
+                  privateKey: clientPrivatePem,
+                  hostKey: multiKey,
+               },
+            },
+            { host: "127.0.0.1", port: echoServer.port },
+         ),
+      ).rejects.toThrow(/host-key verification failed/i);
    });
 
    it("rejects for unsupported proxy type", async () => {

package/src/service/proxy.ts

@@ -8,24 +8,26 @@
  * A connection proxy is a normal connection capability (authorized by whoever
  * configures the connection); it is intentionally NOT behind an env-flag gate,
  * and is kept separate from the `publisher` HTTP multi-hop type's
- * PUBLISHER_ALLOW_PROXY_CONNECTIONS gate. The trust boundary is host-key pinning
- * (below), which is fail-closed.
+ * PUBLISHER_ALLOW_PROXY_CONNECTIONS gate. When host-key pinning is configured it
+ * is fail-closed (below).
  *
  * # Host-key policy
  *
- * Publisher is fail-closed by default: if `ssh.hostKey` is absent the tunnel
- * is refused at connect time to prevent MITM.  Set the environment variable
- *
- *   PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY=true
- *
- * to disable this check for development/testing.  Never set this in
- * production.
+ * `ssh.hostKey` is optional. When set, it pins the bastion's host key(s) and the
+ * tunnel is fail-closed on mismatch; it may list multiple known_hosts lines (a
+ * load-balanced/HA bastion presents a different key per backend), and any listed
+ * key is accepted. When absent, the tunnel connects without host-key
+ * verification — the self-service default, matching mainstream BI tools' SSH
+ * tunnels. The SSH transport is still encrypted; unpinned, a MITM on the
+ * publisher→bastion hop is possible, mitigated by the customer allowlisting our
+ * egress on the bastion.
  */
 
 import net from "net";
 import { Client as SshClient } from "ssh2";
 import type { ConnectConfig, SyncHostVerifier } from "ssh2";
 import { components } from "../api";
+import { logger } from "../logger";
 
 type ConnectionProxy = components["schemas"]["ConnectionProxy"];
 
@@ -39,17 +41,27 @@ const SSH_CONNECT_TIMEOUT_MS = 15_000;
 const SSH_KEEPALIVE_INTERVAL_MS = 15_000;
 
 /**
- * Extract the base64 wire-format key from a stored hostKey, accepting any of:
- * a full known_hosts line (`[markers] host keytype AAAA…`), a `keytype AAAA…`
- * pair, or the bare base64 blob. SSH public-key blobs always base64-encode to a
- * string starting with "AAAA" (the 4-byte length prefix of the key-type name),
- * so we pick that token; otherwise fall back to the last whitespace-delimited
- * token. This matches what ssh2's hostVerifier hands us (`key.toString("base64")`).
+ * Parse a stored hostKey into the set of base64 wire-format key blobs to accept.
+ * The value may hold one or more OpenSSH known_hosts entries (one per line) — a
+ * load-balanced bastion presents a different host key per backend, so pinning
+ * such a bastion means listing every backend's key. Blank lines and `#` comments
+ * are skipped. Each entry may be a full known_hosts line (`[markers] host keytype
+ * AAAA…`), a `keytype AAAA…` pair, or a bare base64 blob; SSH key blobs
+ * base64-encode to a string starting with "AAAA" (the length prefix of the
+ * key-type name), so we pick that token, else the last whitespace-delimited
+ * token. Compared against what ssh2 hands us (`key.toString("base64")`).
  */
-function extractHostKeyBase64(raw: string): string {
-   const tokens = raw.trim().split(/\s+/);
-   const blob = tokens.find((t) => /^AAAA[A-Za-z0-9+/]+={0,2}$/.test(t));
-   return blob ?? tokens[tokens.length - 1] ?? "";
+export function parseHostKeys(raw: string): Set<string> {
+   const keys = new Set<string>();
+   for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const tokens = trimmed.split(/\s+/);
+      const blob = tokens.find((t) => /^AAAA[A-Za-z0-9+/]+={0,2}$/.test(t));
+      const key = blob ?? tokens[tokens.length - 1];
+      if (key) keys.add(key);
+   }
+   return keys;
 }
 
 /**
@@ -112,31 +124,34 @@ function openSshProxy(
          hostVerifier: ((key: Buffer): boolean => {
             // `key` is the raw Buffer of the host's public key.
             const presented = key.toString("base64");
+            // "Pinned" is gated on hostKey being a non-empty value, not on it
+            // parsing to ≥1 key: a set-but-degenerate hostKey (only whitespace,
+            // blanks, or comments) must fail closed, never fall through to the
+            // unpinned branch. Config load (validateConnectionShape) already
+            // rejects that case; this is the security-boundary backstop for any
+            // path that reaches here directly. ("" is the unpinned signal.)
             if (ssh.hostKey) {
-               const expected = extractHostKeyBase64(ssh.hostKey);
-               if (presented !== expected) {
-                  fail(
-                     new Error(
-                        `SSH host-key mismatch for ${ssh.host}: expected ${expected.slice(0, 24)}… but got ${presented.slice(0, 24)}….`,
-                     ),
-                  );
-                  return false;
+               // Fail-closed, accepting any listed key — an LB/HA bastion presents
+               // a different host key per backend.
+               const pinned = parseHostKeys(ssh.hostKey);
+               if (pinned.has(presented)) {
+                  return true;
                }
-               return true;
-            }
-            // No hostKey provided.
-            if (process.env.PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY === "true") {
-               return true;
+               fail(
+                  new Error(
+                     `SSH host-key verification failed for ${ssh.host}: the presented key ` +
+                        `(${presented.slice(0, 24)}…) is not among the ${pinned.size} pinned ` +
+                        `host key(s).`,
+                  ),
+               );
+               return false;
             }
-            fail(
-               new Error(
-                  `SSH connection to ${ssh.host} refused: no hostKey provided and ` +
-                     `PUBLISHER_SSH_ALLOW_UNKNOWN_HOSTKEY is not 'true'.  ` +
-                     `Set hostKey to the bastion's host public key (an OpenSSH ` +
-                     `known_hosts line or its base64 blob, e.g. from ssh-keyscan).`,
-               ),
+            // Unpinned (no hostKey): connect without host-key verification — the
+            // self-service default (see file header).
+            logger.warn(
+               `Connecting to SSH bastion ${ssh.host} without host-key verification (no hostKey pinned).`,
             );
-            return false;
+            return true;
          }) as SyncHostVerifier,
       };