@malloy-publisher/server 0.0.199 → 0.0.200

package/src/service/environment.ts

@@ -1,5 +1,6 @@
 import type { GivenValue, LogMessage } from "@malloydata/malloy";
 import { MalloyError, Runtime } from "@malloydata/malloy";
+import { metrics } from "@opentelemetry/api";
 import { Mutex } from "async-mutex";
 import crypto from "crypto";
 import * as fs from "fs";
@@ -69,6 +70,49 @@ type RetiredConnectionGeneration = {
 
 const RETIRED_CONNECTION_DRAIN_MS = 30_000;
 
+/**
+ * Module-scoped admission-rejection counters. Lazy-initialized so
+ * the OTel JS `ProxyMeter` cannot strand them on a NoOp instrument
+ * created before the SDK MeterProvider was registered (a real risk
+ * in unit tests; see comment in `query_timeout.ts`). Environment
+ * name is attached as a label so dashboards can identify hot
+ * environments without grepping logs.
+ */
+import { type Counter } from "@opentelemetry/api";
+let queryAdmissionRejectionsCounter: Counter | null = null;
+let packageAdmissionRejectionsCounter: Counter | null = null;
+function getQueryAdmissionRejectionsCounter(): Counter {
+   if (queryAdmissionRejectionsCounter) return queryAdmissionRejectionsCounter;
+   queryAdmissionRejectionsCounter = metrics
+      .getMeter("publisher")
+      .createCounter("publisher_query_admission_rejections_total", {
+         description:
+            "Queries rejected with 503 because Environment.assertCanAdmitQuery() observed memory back-pressure",
+      });
+   return queryAdmissionRejectionsCounter;
+}
+function getPackageAdmissionRejectionsCounter(): Counter {
+   if (packageAdmissionRejectionsCounter) {
+      return packageAdmissionRejectionsCounter;
+   }
+   packageAdmissionRejectionsCounter = metrics
+      .getMeter("publisher")
+      .createCounter("publisher_package_admission_rejections_total", {
+         description:
+            "Package loads rejected with 503 because Environment.assertCanAdmitNewPackage() observed memory back-pressure",
+      });
+   return packageAdmissionRejectionsCounter;
+}
+
+/**
+ * Visible for tests; production code never calls this. Resets the
+ * lazy caches so a fresh MeterProvider can capture future writes.
+ */
+export function resetAdmissionTelemetryForTesting(): void {
+   queryAdmissionRejectionsCounter = null;
+   packageAdmissionRejectionsCounter = null;
+}
+
 export class Environment {
    private packages: Map<string, Package> = new Map();
    // Lock ordering: connectionMutex (environment) MUST be acquired before any
@@ -176,6 +220,7 @@ export class Environment {
       environmentPath: string,
       connections: ApiConnection[],
    ): Promise<Environment> {
+      assertSafeEnvironmentPath(environmentPath);
       if (!(await fs.promises.stat(environmentPath))?.isDirectory()) {
          throw new EnvironmentNotFoundError(
             `Environment path ${environmentPath} not found`,
@@ -218,7 +263,7 @@ export class Environment {
       try {
          readme = (
             await fs.promises.readFile(
-               path.join(this.environmentPath, README_NAME),
+               safeJoinUnderRoot(this.environmentPath, README_NAME),
             )
          ).toString();
       } catch {
@@ -579,8 +624,43 @@ export class Environment {
    ): void {
       if (allowAdmission) return;
       if (!this.memoryGovernor?.isBackpressured()) return;
+      // Increment *before* throwing so the metric ticks even on
+      // the not-uncommon "caught and swallowed" path. The label
+      // shape mirrors `assertCanAdmitQuery` so a dashboard panel
+      // can sum both rejection kinds by environment.
+      getPackageAdmissionRejectionsCounter().add(1, {
+         environment: this.environmentName,
+         reason,
+      });
+      throw new ServiceUnavailableError(
+         `Publisher is under memory pressure and cannot ${reason} (package "${packageName}", environment "${this.environmentName}"). Retry after the server's memory usage drops below the low-water mark (PUBLISHER_MEMORY_LOW_WATER_FRACTION of PUBLISHER_MAX_MEMORY_BYTES), or raise PUBLISHER_MAX_MEMORY_BYTES if you have headroom.`,
+      );
+   }
+
+   /**
+    * Reject incoming queries with HTTP 503 when the memory governor
+    * has tripped its high-water mark. Used by every query controller
+    * (connection SQL, model query, notebook cell, MCP `execute_query`)
+    * to shed load before the query runs — complementing
+    * {@link assertCanAdmitNewPackage}, which only fires on cache-miss
+    * package loads and so leaves already-loaded packages fully
+    * queryable under pressure. With this in place, "back-pressured"
+    * means "no new work of any kind" until the governor's low-water
+    * mark is crossed.
+    *
+    * Cheap O(1) boolean read; no allocation when happy.
+    */
+   public assertCanAdmitQuery(): void {
+      if (!this.memoryGovernor?.isBackpressured()) return;
+      // Tick first so the counter reflects every rejection even
+      // when the controller's catch block swallows the error (e.g.
+      // an MCP tool surfaces it as a content payload rather than
+      // letting it bubble to the HTTP error mapper).
+      getQueryAdmissionRejectionsCounter().add(1, {
+         environment: this.environmentName,
+      });
       throw new ServiceUnavailableError(
-         `Publisher is under memory pressure and cannot ${reason} (package "${packageName}", environment "${this.environmentName}"). Retry after the server's memory usage drops below the configured low-water mark.`,
+         `Publisher is under memory pressure and cannot accept new queries (environment "${this.environmentName}"). Retry after the server's memory usage drops below the low-water mark (PUBLISHER_MEMORY_LOW_WATER_FRACTION of PUBLISHER_MAX_MEMORY_BYTES), or raise PUBLISHER_MAX_MEMORY_BYTES if you have headroom.`,
       );
    }
 

package/src/service/environment_admission.spec.ts

@@ -4,8 +4,12 @@ import * as os from "os";
 import * as path from "path";
 
 import { ServiceUnavailableError } from "../errors";
+import {
+   startMetricsHarness,
+   type MetricsHarness,
+} from "../test_helpers/metrics_harness";
 import { buildEnvironmentMalloyConfig } from "./connection";
-import { Environment } from "./environment";
+import { Environment, resetAdmissionTelemetryForTesting } from "./environment";
 import type { PackageMemoryGovernor } from "./package_memory_governor";
 
 /**
@@ -178,3 +182,163 @@ describe("Environment admission gate (memory governor choke point)", () => {
       expect(caught).not.toBeInstanceOf(ServiceUnavailableError);
    });
 });
+
+describe("Environment.assertCanAdmitQuery (query-path back-pressure)", () => {
+   let envDir: string;
+
+   beforeEach(() => {
+      envDir = fs.mkdtempSync(
+         path.join(os.tmpdir(), "publisher-env-query-admission-"),
+      );
+   });
+
+   afterEach(() => {
+      fs.rmSync(envDir, { recursive: true, force: true });
+   });
+
+   it("is a no-op when no governor is attached", () => {
+      const env = makeEnvironment(envDir);
+      // No governor — must not throw. Equivalent of an OSS / non-Docker
+      // deployment that never opted into PUBLISHER_MAX_MEMORY_BYTES.
+      expect(() => env.assertCanAdmitQuery()).not.toThrow();
+   });
+
+   it("is a no-op when the governor is happy (under high-water mark)", () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      governor.backpressured = false;
+
+      expect(() => env.assertCanAdmitQuery()).not.toThrow();
+   });
+
+   it("throws ServiceUnavailableError (→503) when back-pressured", () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      governor.backpressured = true;
+
+      expect(() => env.assertCanAdmitQuery()).toThrow(ServiceUnavailableError);
+   });
+
+   it("error message names the environment so operators can pinpoint the hot pod's load", () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      governor.backpressured = true;
+
+      let caught: unknown;
+      try {
+         env.assertCanAdmitQuery();
+      } catch (err) {
+         caught = err;
+      }
+      expect(caught).toBeInstanceOf(ServiceUnavailableError);
+      expect((caught as Error).message).toContain('environment "test-env"');
+      expect((caught as Error).message).toContain("memory pressure");
+   });
+
+   it("clearing back-pressure immediately re-admits queries (matches governor hysteresis)", () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+
+      governor.backpressured = true;
+      expect(() => env.assertCanAdmitQuery()).toThrow(ServiceUnavailableError);
+
+      governor.backpressured = false;
+      expect(() => env.assertCanAdmitQuery()).not.toThrow();
+   });
+
+   it("detaching the governor reverts to legacy admit-everything", () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      governor.backpressured = true;
+
+      env.setMemoryGovernor(null);
+      // Even with the stub still claiming back-pressure, a detached
+      // governor leaves nothing to consult. Mirrors the package-admission
+      // detach behavior.
+      expect(() => env.assertCanAdmitQuery()).not.toThrow();
+   });
+});
+
+describe("Environment admission telemetry", () => {
+   let envDir: string;
+   let harness: MetricsHarness;
+
+   beforeEach(async () => {
+      envDir = fs.mkdtempSync(
+         path.join(os.tmpdir(), "publisher-env-admission-telemetry-"),
+      );
+      harness = await startMetricsHarness();
+      resetAdmissionTelemetryForTesting();
+   });
+
+   afterEach(async () => {
+      fs.rmSync(envDir, { recursive: true, force: true });
+      resetAdmissionTelemetryForTesting();
+      await harness.shutdown();
+   });
+
+   it("publisher_query_admission_rejections_total ticks per query rejection, labeled by environment", async () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      governor.backpressured = true;
+
+      // Drive three rejections so the counter is unambiguous (a
+      // single-tick assertion can pass against a leaked counter
+      // from a different test; three is harder to fake).
+      for (let i = 0; i < 3; i++) {
+         expect(() => env.assertCanAdmitQuery()).toThrow(
+            ServiceUnavailableError,
+         );
+      }
+      expect(
+         await harness.collectCounter(
+            "publisher_query_admission_rejections_total",
+            { environment: "test-env" },
+         ),
+      ).toBe(3);
+   });
+
+   it("counter stays at zero when the governor is happy (no spurious ticks)", async () => {
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      // Not back-pressured.
+      env.assertCanAdmitQuery();
+      env.assertCanAdmitQuery();
+      // No rejection should have been recorded; verifies that the
+      // counter doesn't tick on the happy-path admission either.
+      expect(
+         await harness.collectCounter(
+            "publisher_query_admission_rejections_total",
+         ),
+      ).toBe(0);
+   });
+
+   it("publisher_package_admission_rejections_total ticks per package-load rejection", async () => {
+      // Ensure the package directory exists so the 404 doesn't
+      // short-circuit ahead of the back-pressure gate.
+      const pkgName = "real-pkg";
+      fs.mkdirSync(path.join(envDir, pkgName));
+
+      const env = makeEnvironment(envDir);
+      const governor = new StubGovernor();
+      env.setMemoryGovernor(governor as unknown as PackageMemoryGovernor);
+      governor.backpressured = true;
+
+      await expect(env.addPackage(pkgName)).rejects.toBeInstanceOf(
+         ServiceUnavailableError,
+      );
+      expect(
+         await harness.collectCounter(
+            "publisher_package_admission_rejections_total",
+            { environment: "test-env", reason: "add a new package" },
+         ),
+      ).toBe(1);
+   });
+});

package/src/service/environment_store.spec.ts

@@ -5,6 +5,7 @@ import * as sinon from "sinon";
 import { components } from "../api";
 import { isPublisherConfigFrozen } from "../config";
 import { TEMP_DIR_PATH } from "../constants";
+import { BadRequestError } from "../errors";
 import { Environment } from "./environment";
 import { EnvironmentStore } from "./environment_store";
 
@@ -1020,3 +1021,105 @@ describe("Project Service Error Recovery", () => {
       );
    });
 });
+
+const TRAVERSAL_NAMES: ReadonlyArray<readonly [string, string]> = [
+   ["leading traversal", "../etc"],
+   ["embedded traversal", "foo/../../bar"],
+   ["slash in name", "foo/bar"],
+   ["backslash in name", "foo\\bar"],
+   ["leading dot", ".staging"],
+   ["bare dot-dot", ".."],
+   ["bare dot", "."],
+   ["empty", ""],
+   ["NUL byte", "foo\0bar"],
+   ["oversized", "a".repeat(256)],
+   ["absolute", "/etc/passwd"],
+] as const;
+
+describe("EnvironmentStore path-injection guards", () => {
+   let environmentStore: EnvironmentStore;
+
+   beforeEach(async () => {
+      if (existsSync(serverRootPath)) {
+         rmSync(serverRootPath, { recursive: true, force: true });
+      }
+      mkdirSync(serverRootPath);
+      mock(isPublisherConfigFrozen).mockReturnValue(false);
+      mock.module("../config", () => ({
+         isPublisherConfigFrozen: () => false,
+      }));
+      environmentStore = new EnvironmentStore(serverRootPath);
+      await environmentStore.finishedInitialization;
+   });
+
+   afterEach(() => {
+      if (existsSync(serverRootPath)) {
+         rmSync(serverRootPath, { recursive: true, force: true });
+      }
+      mkdirSync(serverRootPath);
+   });
+
+   describe("addEnvironment", () => {
+      it.each(TRAVERSAL_NAMES)(
+         "rejects %s as environment.name (%p)",
+         async (_label, name) => {
+            await expect(
+               environmentStore.addEnvironment({ name } as never, true),
+            ).rejects.toBeInstanceOf(BadRequestError);
+         },
+      );
+
+      it.each(TRAVERSAL_NAMES)(
+         "rejects %s as packages[].name (%p)",
+         async (_label, packageName) => {
+            await expect(
+               environmentStore.addEnvironment(
+                  {
+                     name: "ok-env",
+                     packages: [
+                        {
+                           name: packageName,
+                           location: "https://github.com/example/repo",
+                        },
+                     ],
+                  } as never,
+                  true,
+               ),
+            ).rejects.toBeInstanceOf(BadRequestError);
+         },
+      );
+   });
+
+   describe("updateEnvironment", () => {
+      it.each(TRAVERSAL_NAMES)(
+         "rejects %s as environment.name (%p)",
+         async (_label, name) => {
+            await expect(
+               environmentStore.updateEnvironment({ name } as never),
+            ).rejects.toBeInstanceOf(BadRequestError);
+         },
+      );
+   });
+
+   describe("deleteEnvironment", () => {
+      it.each(TRAVERSAL_NAMES)(
+         "rejects %s as environmentName (%p)",
+         async (_label, name) => {
+            await expect(
+               environmentStore.deleteEnvironment(name),
+            ).rejects.toBeInstanceOf(BadRequestError);
+         },
+      );
+   });
+
+   describe("getEnvironment", () => {
+      it.each(TRAVERSAL_NAMES)(
+         "rejects %s as environmentName (%p)",
+         async (_label, name) => {
+            await expect(
+               environmentStore.getEnvironment(name),
+            ).rejects.toBeInstanceOf(BadRequestError);
+         },
+      );
+   });
+});

package/src/service/environment_store.ts

@@ -27,6 +27,11 @@ import {
 } from "../errors";
 import { getOperationalState, markNotReady, markReady } from "../health";
 import { formatDuration, logger } from "../logger";
+import {
+   assertSafeEnvironmentPath,
+   assertSafePackageName,
+   safeJoinUnderRoot,
+} from "../path_safety";
 import { Connection } from "../storage/DatabaseInterface";
 import { StorageConfig, StorageManager } from "../storage/StorageManager";
 import { Environment, PackageStatus } from "./environment";
@@ -756,6 +761,7 @@ export class EnvironmentStore {
       reload: boolean = false,
    ): Promise<Environment> {
       await this.finishedInitialization;
+      assertSafePackageName(environmentName);
 
       // Check if environment is already loaded first
       const environment = this.environments.get(environmentName);
@@ -816,9 +822,10 @@ export class EnvironmentStore {
       if (!skipInitialization && this.publisherConfigIsFrozen) {
          throw new FrozenConfigError();
       }
+      assertSafePackageName(environment.name);
       const environmentName = environment.name;
-      if (!environmentName) {
-         throw new Error("Environment name is required");
+      for (const _package of environment.packages || []) {
+         assertSafePackageName(_package.name);
       }
       // Check if environment already exists and update it instead of creating a new one
       const existingEnvironment = this.environments.get(environmentName);
@@ -884,6 +891,7 @@ export class EnvironmentStore {
    }
 
    public async unzipEnvironment(absoluteEnvironmentPath: string) {
+      assertSafeEnvironmentPath(absoluteEnvironmentPath);
       const startedAt = Date.now();
       logger.info(
          `Detected zip file at "${absoluteEnvironmentPath}". Unzipping...`,
@@ -930,9 +938,10 @@ export class EnvironmentStore {
          throw new FrozenConfigError();
       }
       validateEnvironmentAzureUrls(environment);
+      assertSafePackageName(environment.name);
       const environmentName = environment.name;
-      if (!environmentName) {
-         throw new Error("Environment name is required");
+      for (const _package of environment.packages || []) {
+         assertSafePackageName(_package.name);
       }
       const existingEnvironment = this.environments.get(environmentName);
       if (!existingEnvironment) {
@@ -953,6 +962,7 @@ export class EnvironmentStore {
       if (this.publisherConfigIsFrozen) {
          throw new FrozenConfigError();
       }
+      assertSafePackageName(environmentName);
       const environment = this.environments.get(environmentName);
       if (!environment) {
          return;
@@ -1027,15 +1037,17 @@ export class EnvironmentStore {
    }
 
    private async scaffoldEnvironment(environment: ApiEnvironment) {
+      assertSafePackageName(environment.name);
       const environmentName = environment.name;
-      if (!environmentName) {
-         throw new Error("Environment name is required");
-      }
-      const absoluteEnvironmentPath = `${this.serverRootPath}/${PUBLISHER_DATA_DIR}/${environmentName}`;
+      const absoluteEnvironmentPath = safeJoinUnderRoot(
+         this.serverRootPath,
+         PUBLISHER_DATA_DIR,
+         environmentName,
+      );
       await fs.promises.mkdir(absoluteEnvironmentPath, { recursive: true });
       if (environment.readme) {
          await fs.promises.writeFile(
-            path.join(absoluteEnvironmentPath, "README.md"),
+            safeJoinUnderRoot(absoluteEnvironmentPath, "README.md"),
             environment.readme,
          );
       }
@@ -1071,7 +1083,12 @@ export class EnvironmentStore {
       environmentName: string,
       packages: ApiEnvironment["packages"],
    ) {
-      const absoluteTargetPath = `${this.serverRootPath}/${PUBLISHER_DATA_DIR}/${environmentName}`;
+      assertSafePackageName(environmentName);
+      const absoluteTargetPath = safeJoinUnderRoot(
+         this.serverRootPath,
+         PUBLISHER_DATA_DIR,
+         environmentName,
+      );
 
       await fs.promises.mkdir(absoluteTargetPath, { recursive: true });
 
@@ -1126,7 +1143,10 @@ export class EnvironmentStore {
             .update(groupedLocation)
             .digest("hex")
             .substring(0, 16); // Use first 16 chars for shorter paths
-         const tempDownloadPath = `${absoluteTargetPath}/.temp_${locationHash}`;
+         const tempDownloadPath = safeJoinUnderRoot(
+            absoluteTargetPath,
+            `.temp_${locationHash}`,
+         );
          await fs.promises.mkdir(tempDownloadPath, { recursive: true });
          logger.info(`Created temporary directory: ${tempDownloadPath}`);
          try {
@@ -1140,7 +1160,11 @@ export class EnvironmentStore {
             // Extract each package from the downloaded content
             for (const _package of packagesForLocation) {
                const packageDir = _package.name;
-               const absolutePackagePath = `${absoluteTargetPath}/${packageDir}`;
+               assertSafePackageName(packageDir);
+               const absolutePackagePath = safeJoinUnderRoot(
+                  absoluteTargetPath,
+                  packageDir,
+               );
                // For GitHub URLs, extract the subdirectory path from the original location
                let sourcePath: string;
                if (this.isGitHubURL(_package.location)) {
@@ -1151,7 +1175,7 @@ export class EnvironmentStore {
                      const subPathMatch =
                         _package.location.match(/\/tree\/[^/]+\/(.+)$/);
                      if (subPathMatch) {
-                        sourcePath = path.join(
+                        sourcePath = safeJoinUnderRoot(
                            tempDownloadPath,
                            subPathMatch[1],
                         );
@@ -1168,7 +1192,10 @@ export class EnvironmentStore {
                   if (this.isLocalPath(_package.location)) {
                      sourcePath = _package.location;
                   } else {
-                     sourcePath = path.join(tempDownloadPath, groupedLocation);
+                     sourcePath = safeJoinUnderRoot(
+                        tempDownloadPath,
+                        groupedLocation,
+                     );
                   }
                }
 
@@ -1347,6 +1374,10 @@ export class EnvironmentStore {
       environmentName: string,
       packageName: string,
    ) {
+      // `environmentPath` is the operator-supplied mount source and may
+      // legitimately be a relative path that resolves outside the
+      // server root; only the target is asserted.
+      assertSafeEnvironmentPath(absoluteTargetPath);
       if (environmentPath.endsWith(".zip")) {
          environmentPath = await this.unzipEnvironment(environmentPath);
       }
@@ -1374,6 +1405,7 @@ export class EnvironmentStore {
       absoluteDirPath: string,
       isCompressedFile: boolean,
    ) {
+      assertSafeEnvironmentPath(absoluteDirPath);
       const trimmedPath = gcsPath.slice(5);
       const [bucketName, ...prefixParts] = trimmedPath.split("/");
       const prefix = prefixParts.join("/");
@@ -1396,10 +1428,15 @@ export class EnvironmentStore {
       }
       await Promise.all(
          files.map(async (file) => {
-            const relativeFilePath = file.name.replace(prefix, "");
+            // Strip leading `/` left over from prefix removal when the
+            // GCS prefix lacked a trailing slash — otherwise
+            // `safeJoinUnderRoot` treats it as absolute and rejects.
+            const relativeFilePath = file.name
+               .replace(prefix, "")
+               .replace(/^\/+/, "");
             const absoluteFilePath = isCompressedFile
                ? absoluteDirPath
-               : path.join(absoluteDirPath, relativeFilePath);
+               : safeJoinUnderRoot(absoluteDirPath, relativeFilePath);
             if (file.name.endsWith("/")) {
                return;
             }
@@ -1424,6 +1461,7 @@ export class EnvironmentStore {
       absoluteDirPath: string,
       isCompressedFile: boolean = false,
    ) {
+      assertSafeEnvironmentPath(absoluteDirPath);
       const trimmedPath = s3Path.slice(5);
       const [bucketName, ...prefixParts] = trimmedPath.split("/");
       const prefix = prefixParts.join("/");
@@ -1477,11 +1515,16 @@ export class EnvironmentStore {
             if (!key) {
                return;
             }
-            const relativeFilePath = key.replace(prefix, "");
+            // Strip leading `/` left over from prefix removal when the
+            // S3 prefix lacked a trailing slash — otherwise
+            // `safeJoinUnderRoot` treats it as absolute and rejects.
+            const relativeFilePath = key
+               .replace(prefix, "")
+               .replace(/^\/+/, "");
             if (!relativeFilePath || relativeFilePath.endsWith("/")) {
                return;
             }
-            const absoluteFilePath = path.join(
+            const absoluteFilePath = safeJoinUnderRoot(
                absoluteDirPath,
                relativeFilePath,
             );
@@ -1532,6 +1575,7 @@ export class EnvironmentStore {
    }
 
    async downloadGitHubDirectory(githubUrl: string, absoluteDirPath: string) {
+      assertSafeEnvironmentPath(absoluteDirPath);
       // First we'll clone the repo without the additional path
       // E.g. we're removing `/tree/main/imdb` from https://github.com/credibledata/malloy-samples/tree/main/imdb
       const githubInfo = this.parseGitHubUrl(githubUrl);
@@ -1539,7 +1583,11 @@ export class EnvironmentStore {
          throw new Error(`Invalid GitHub URL: ${githubUrl}`);
       }
       const { owner, repoName, packagePath } = githubInfo;
-      const cleanPackagePath = packagePath?.replace("/tree/main", "") || "";
+      // `packagePath` is captured with a leading `/`; strip it so the
+      // value is a relative segment usable with `safeJoinUnderRoot`.
+      const cleanPackagePath = (
+         packagePath?.replace("/tree/main", "") || ""
+      ).replace(/^\/+/, "");
 
       // We'll make sure whatever was in absoluteDirPath is removed,
       // so we have a nice a clean directory where we can clone the repo
@@ -1579,7 +1627,10 @@ export class EnvironmentStore {
 
       // Remove all contents of absoluteDirPath (/var/publisher/asd123)
       // except for the cleanPackagePath directory (/var/publisher/asd123/imdb)
-      const packageFullPath = path.join(absoluteDirPath, cleanPackagePath);
+      const packageFullPath = safeJoinUnderRoot(
+         absoluteDirPath,
+         cleanPackagePath,
+      );
 
       // Check if the cleanPackagePath (/var/publisher/asd123/imdb) exists
       const packageExists = await fs.promises
@@ -1598,7 +1649,7 @@ export class EnvironmentStore {
       for (const entry of dirContents) {
          // Don't remove the cleanPackagePath directory itself (/var/publisher/asd123/imdb)
          if (entry !== cleanPackagePath.replace(/^\/+/, "").split("/")[0]) {
-            await fs.promises.rm(path.join(absoluteDirPath, entry), {
+            await fs.promises.rm(safeJoinUnderRoot(absoluteDirPath, entry), {
                recursive: true,
                force: true,
             });
@@ -1609,8 +1660,8 @@ export class EnvironmentStore {
       const packageContents = await fs.promises.readdir(packageFullPath);
       for (const entry of packageContents) {
          await fs.promises.rename(
-            path.join(packageFullPath, entry),
-            path.join(absoluteDirPath, entry),
+            safeJoinUnderRoot(packageFullPath, entry),
+            safeJoinUnderRoot(absoluteDirPath, entry),
          );
       }