@malloy-publisher/server 0.0.198-dev → 0.0.198-dev2

package/src/health.spec.ts

@@ -0,0 +1,90 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { Server } from "http";
+import { performGracefulShutdownAfterDrain } from "./health";
+import { logger } from "./logger";
+
+// Regression test for the graceful-shutdown ordering bug that caused
+//   [winston] Attempt to write logs with no transports: {"message":"Waiting 50 seconds..."}
+// to appear in production logs. logger.close() must run after every
+// logger.* call, including the "Waiting ... seconds after server close
+// before exit..." message.
+//
+// Tests call performGracefulShutdownAfterDrain directly rather than
+// emitting SIGTERM, so module-level operationalState is not mutated
+// and the spec stays isolated from sibling tests in the same process.
+describe("performGracefulShutdownAfterDrain: shutdown ordering", () => {
+   const originalExit = process.exit;
+   let callOrder: string[];
+
+   beforeEach(() => {
+      callOrder = [];
+
+      spyOn(logger, "info").mockImplementation(((msg: string) => {
+         callOrder.push(`info:${msg}`);
+         return logger;
+      }) as never);
+      spyOn(logger, "close").mockImplementation((() => {
+         callOrder.push("close");
+         return logger;
+      }) as never);
+      // Silence warn/error calls so spec output stays clean. They are
+      // not load-bearing for these assertions.
+      spyOn(logger, "warn").mockImplementation((() => logger) as never);
+      spyOn(logger, "error").mockImplementation((() => logger) as never);
+
+      process.exit = ((_code?: number) => {
+         callOrder.push("exit");
+      }) as never;
+   });
+
+   afterEach(() => {
+      process.exit = originalExit;
+   });
+
+   const fakeServer = (): Server => ({ listening: false }) as unknown as Server;
+
+   it("logs the 'Waiting ...' message before closing the logger", async () => {
+      await performGracefulShutdownAfterDrain(fakeServer(), fakeServer(), 0.05);
+
+      const waitingIdx = callOrder.findIndex((entry) =>
+         entry.startsWith("info:Waiting"),
+      );
+      const closeIdx = callOrder.indexOf("close");
+      const exitIdx = callOrder.indexOf("exit");
+
+      expect(waitingIdx).toBeGreaterThanOrEqual(0);
+      expect(closeIdx).toBeGreaterThanOrEqual(0);
+      expect(exitIdx).toBeGreaterThanOrEqual(0);
+      expect(waitingIdx).toBeLessThan(closeIdx);
+      expect(closeIdx).toBeLessThan(exitIdx);
+   });
+
+   it("emits no logger.info calls after logger.close", async () => {
+      await performGracefulShutdownAfterDrain(fakeServer(), fakeServer(), 0.05);
+
+      const closeIdx = callOrder.indexOf("close");
+      const lateInfoIdx = callOrder.findIndex(
+         (entry, idx) => idx > closeIdx && entry.startsWith("info:"),
+      );
+      expect(closeIdx).toBeGreaterThanOrEqual(0);
+      expect(lateInfoIdx).toBe(-1);
+   });
+
+   it("closes the logger exactly once", async () => {
+      await performGracefulShutdownAfterDrain(fakeServer(), fakeServer(), 0.05);
+
+      const closes = callOrder.filter((entry) => entry === "close").length;
+      expect(closes).toBe(1);
+   });
+
+   it("skips the 'Waiting ...' message when gracefulCloseTimeoutSeconds is 0", async () => {
+      await performGracefulShutdownAfterDrain(fakeServer(), fakeServer(), 0);
+
+      const waitingCalls = callOrder.filter((entry) =>
+         entry.startsWith("info:Waiting"),
+      );
+      expect(waitingCalls.length).toBe(0);
+      expect(callOrder.indexOf("close")).toBeGreaterThanOrEqual(0);
+      expect(callOrder.indexOf("exit")).toBeGreaterThanOrEqual(0);
+   });
+});

package/src/health.ts

@@ -57,8 +57,8 @@ export function markNotReady(): void {
  * 2. Waits shutdownDrainDurationSeconds to allow in-flight requests to complete
  * 3. Sets preGracefulShutdownCompleted flag (enables drainingGuard middleware to reject new requests)
  * 4. Closes main server and MCP server (stops accepting new connections)
- * 5. Closes logger
- * 6. Waits shutdownGracefulCloseTimeoutSeconds (if > 0) for final cleanup
+ * 5. Waits shutdownGracefulCloseTimeoutSeconds (if > 0) for final cleanup
+ * 6. Closes logger (last, so any logs emitted during cleanup are flushed)
  * 7. Exits process
  *
  * Note: drainingGuard only rejects requests after step 3 completes. During step 2,
@@ -92,51 +92,79 @@ export function registerSignalHandlers(
          }, shutdownDrainDurationSeconds * 1000),
       );
 
-      const closeServer = (server: Server, name: string) =>
-         new Promise<void>((resolve) => {
-            if (server && server.listening) {
-               server.close((err) => {
-                  if (err) {
-                     logger.error(`${name} close error:`, err);
-                  } else {
-                     logger.info(`${name} closed`);
-                  }
-                  resolve();
-               });
-            } else {
-               resolve();
-            }
-         });
-
-      await Promise.all([
-         closeServer(server, "Main server"),
-         closeServer(mcpServer, "MCP server"),
-      ]);
-
-      try {
-         await shutdownSDK();
-         logger.info("OpenTelemetry SDK shut down");
-      } catch (_error) {
-         /* do nothing */
-      }
-
-      try {
-         logger.close();
-      } catch (_error) {
-         /* do nothing */
-      }
-
-      if (shutdownGracefulCloseTimeoutSeconds > 0) {
-         logger.info(
-            `Waiting ${shutdownGracefulCloseTimeoutSeconds} seconds after server close before exit...`,
-         );
-         await new Promise((resolve) =>
-            setTimeout(resolve, shutdownGracefulCloseTimeoutSeconds * 1000),
-         );
-      }
-      process.exit(0);
+      await performGracefulShutdownAfterDrain(
+         server,
+         mcpServer,
+         shutdownGracefulCloseTimeoutSeconds,
+      );
    });
 }
+
+/**
+ * Performs the post-drain shutdown work: closes both HTTP servers,
+ * shuts down the OpenTelemetry SDK, waits the optional graceful-close
+ * window so any in-flight cleanup can finish logging, closes the
+ * winston logger, and exits the process.
+ *
+ * Exported so unit tests can exercise the close + log + exit ordering
+ * without emitting SIGTERM (which would leave module-level
+ * operationalState stuck in "draining" and leak into sibling specs).
+ */
+export async function performGracefulShutdownAfterDrain(
+   server: Server,
+   mcpServer: Server,
+   shutdownGracefulCloseTimeoutSeconds: number,
+): Promise<void> {
+   const closeServer = (server: Server, name: string) =>
+      new Promise<void>((resolve) => {
+         if (server && server.listening) {
+            server.close((err) => {
+               if (err) {
+                  logger.error(`${name} close error:`, err);
+               } else {
+                  logger.info(`${name} closed`);
+               }
+               resolve();
+            });
+         } else {
+            resolve();
+         }
+      });
+
+   await Promise.all([
+      closeServer(server, "Main server"),
+      closeServer(mcpServer, "MCP server"),
+   ]);
+
+   try {
+      await shutdownSDK();
+      logger.info("OpenTelemetry SDK shut down");
+   } catch (_error) {
+      /* do nothing */
+   }
+
+   if (shutdownGracefulCloseTimeoutSeconds > 0) {
+      logger.info(
+         `Waiting ${shutdownGracefulCloseTimeoutSeconds} seconds after server close before exit...`,
+      );
+      await new Promise((resolve) =>
+         setTimeout(resolve, shutdownGracefulCloseTimeoutSeconds * 1000),
+      );
+   }
+
+   // Close the logger last so anything emitted during the wait window
+   // above (or by other shutdown paths still running) reaches its
+   // transports. Closing earlier triggers winston's
+   // "Attempt to write logs with no transports" warning on any
+   // subsequent logger call.
+   try {
+      logger.close();
+   } catch (_error) {
+      /* do nothing */
+   }
+
+   process.exit(0);
+}
 /**
  * Middleware that returns 503 for non-health and metrics requests when service is draining.
  * Must be registered before application routes.

package/src/instrumentation.ts

@@ -1,3 +1,4 @@
+import { monitorEventLoopDelay } from "node:perf_hooks";
 import { metrics } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
@@ -116,6 +117,55 @@ const httpRequestCount = meter.createCounter("http_server_requests_total", {
    description: "Total number of HTTP requests",
 });
 
+// Event-loop-delay metrics. A blocked event loop is the only way the
+// /health/liveness probe (a pure synchronous 200 handler) can fail under K8s,
+// so we surface p50/p99/max so an operator can correlate liveness restarts
+// with sustained event-loop pressure (large Malloy compiles, GC, etc.).
+const eventLoopHistogram = monitorEventLoopDelay({ resolution: 20 });
+eventLoopHistogram.enable();
+
+const eventLoopLagP50 = meter.createObservableGauge(
+   "publisher_event_loop_lag_p50_ms",
+   {
+      description:
+         "Event loop delay p50 since the last scrape, in milliseconds",
+      unit: "ms",
+   },
+);
+const eventLoopLagP99 = meter.createObservableGauge(
+   "publisher_event_loop_lag_p99_ms",
+   {
+      description:
+         "Event loop delay p99 since the last scrape, in milliseconds",
+      unit: "ms",
+   },
+);
+const eventLoopLagMax = meter.createObservableGauge(
+   "publisher_event_loop_lag_max_ms",
+   {
+      description:
+         "Event loop delay max since the last scrape, in milliseconds",
+      unit: "ms",
+   },
+);
+
+// Sample all three in one batch so the histogram reset can't race the reads.
+meter.addBatchObservableCallback(
+   (observableResult) => {
+      observableResult.observe(
+         eventLoopLagP50,
+         eventLoopHistogram.percentile(50) / 1e6,
+      );
+      observableResult.observe(
+         eventLoopLagP99,
+         eventLoopHistogram.percentile(99) / 1e6,
+      );
+      observableResult.observe(eventLoopLagMax, eventLoopHistogram.max / 1e6);
+      eventLoopHistogram.reset();
+   },
+   [eventLoopLagP50, eventLoopLagP99, eventLoopLagMax],
+);
+
 const IGNORED_PATHS = new Set([
    "/health",
    "/health/liveness",

package/src/logger.ts

@@ -28,9 +28,7 @@ export const logger = winston.createLogger({
       ? winston.format.combine(
            winston.format.uncolorize(),
            winston.format.timestamp(),
-           winston.format.metadata({
-              fillExcept: ["message", "level", "timestamp"],
-           }),
+           winston.format.errors({ stack: true }),
            winston.format.json(),
         )
       : winston.format.combine(

package/src/mcp/tools/discovery_tools.ts

@@ -222,8 +222,12 @@ export function registerTools(
                throw new Error(`Model not found: ${modelPath}`);
             }
 
-            // Use the new getModelFileText method
-            const fileText = await pkg.getModelFileText(modelPath);
+            // Route through the Environment so the disk read is serialized
+            // against installPackage / deletePackage.
+            const fileText = await environment.getModelFileText(
+               packageName,
+               modelPath,
+            );
 
             console.log(
                `[MCP LOG] Successfully retrieved model text for ${modelPath}`,

package/src/mcp/tools/execute_query_tool.ts

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+import type { GivenValue } from "@malloydata/malloy";
 import { logger } from "../../logger";
 import { EnvironmentStore } from "../../service/environment_store";
 import { getMalloyErrorDetails, type ErrorDetails } from "../error_messages";
@@ -30,6 +31,12 @@ const executeQueryShape = {
       .describe(
          "Filter parameter values keyed by filter name. Used with sources that declare #(filter) annotations.",
       ),
+   givens: z
+      .record(z.unknown())
+      .optional()
+      .describe(
+         "Per-query given values that override model defaults. Keys are given names declared in the model's given: block.",
+      ),
 };
 
 // Type inference is handled automatically by the MCP server based on the executeQueryShape
@@ -56,6 +63,7 @@ export function registerExecuteQueryTool(
             sourceName,
             queryName,
             filterParams,
+            givens,
          } = params;
 
          logger.info("[MCP Tool executeQuery] Received params:", { params });
@@ -128,6 +136,8 @@ export function registerExecuteQueryTool(
                   undefined,
                   query,
                   filterParams,
+                  undefined,
+                  givens as Record<string, GivenValue> | undefined,
                );
                const { validateRenderTags } = await import(
                   "@malloydata/render-validator"
@@ -174,6 +184,8 @@ export function registerExecuteQueryTool(
                   queryName,
                   undefined,
                   filterParams,
+                  undefined,
+                  givens as Record<string, GivenValue> | undefined,
                );
                const { validateRenderTags } = await import(
                   "@malloydata/render-validator"

package/src/path_safety.spec.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "bun:test";
+import * as path from "path";
+
+import { BadRequestError } from "./errors";
+import {
+   assertSafeEnvironmentPath,
+   assertSafePackageName,
+   assertSafeRelativeModelPath,
+   safeJoinUnderRoot,
+} from "./path_safety";
+
+describe("assertSafePackageName", () => {
+   it.each([
+      "pkg",
+      "test_package",
+      "test-package",
+      "TestPackage1",
+      "test.package.name",
+      "a",
+      "x".repeat(255),
+   ])("accepts %p", (name) => {
+      expect(() => assertSafePackageName(name)).not.toThrow();
+   });
+
+   it.each([
+      ["empty", ""],
+      ["dot", "."],
+      ["dot-dot", ".."],
+      ["leading dot", ".staging"],
+      ["forward slash", "foo/bar"],
+      ["backslash", "foo\\bar"],
+      ["null byte", "foo\0bar"],
+      ["traversal", "../etc/passwd"],
+      ["abs", "/etc/passwd"],
+      ["space", "my pkg"],
+      ["unicode", "pkg\u202E"],
+      ["too long", "x".repeat(256)],
+   ])("rejects %s (%p)", (_label, name) => {
+      expect(() => assertSafePackageName(name)).toThrow(BadRequestError);
+   });
+
+   it.each([
+      ["number", 42],
+      ["null", null],
+      ["undefined", undefined],
+      ["object", { name: "pkg" }],
+   ])("rejects non-string %s (%p)", (_label, value) => {
+      expect(() => assertSafePackageName(value)).toThrow(BadRequestError);
+   });
+});
+
+describe("assertSafeRelativeModelPath", () => {
+   it.each([
+      "model.malloy",
+      "models/foo.malloy",
+      "a/b/c/d.malloynb",
+      "deep/nested/file_name-1.malloy",
+   ])("accepts %p", (modelPath) => {
+      expect(() => assertSafeRelativeModelPath(modelPath)).not.toThrow();
+   });
+
+   it.each([
+      ["empty", ""],
+      ["leading slash (absolute)", "/etc/passwd"],
+      ["traversal", "../etc/passwd"],
+      ["embedded traversal", "models/../../../etc/passwd"],
+      ["embedded dot segment", "models/./foo.malloy"],
+      ["double slash", "models//foo.malloy"],
+      ["trailing slash", "models/foo/"],
+      ["backslash", "models\\foo.malloy"],
+      ["null byte", "models/foo\0.malloy"],
+      ["dotfile segment", ".staging/foo.malloy"],
+      ["dotfile leaf", "models/.hidden.malloy"],
+   ])("rejects %s (%p)", (_label, modelPath) => {
+      expect(() => assertSafeRelativeModelPath(modelPath)).toThrow(
+         BadRequestError,
+      );
+   });
+
+   it("rejects non-string inputs", () => {
+      expect(() => assertSafeRelativeModelPath(undefined)).toThrow(
+         BadRequestError,
+      );
+      expect(() => assertSafeRelativeModelPath(123)).toThrow(BadRequestError);
+   });
+});
+
+describe("assertSafeEnvironmentPath", () => {
+   it.each([
+      "/etc/publisher",
+      "/var/lib/publisher/env1",
+      "/Users/me/data",
+      "/a",
+      "C:\\Users\\me\\publisher",
+      "C:/Users/me/publisher",
+   ])("accepts %p", (p) => {
+      expect(() => assertSafeEnvironmentPath(p)).not.toThrow();
+   });
+
+   it.each([
+      ["empty", ""],
+      ["relative", "publisher/data"],
+      ["traversal in middle", "/var/lib/../../etc/passwd"],
+      ["traversal at end", "/var/lib/publisher/.."],
+      ["null byte", "/var/lib/publisher\0"],
+      ["bare dot-dot", ".."],
+      ["bare dot", "."],
+      ["too long", "/" + "a".repeat(5000)],
+   ])("rejects %s (%p)", (_label, p) => {
+      expect(() => assertSafeEnvironmentPath(p)).toThrow(BadRequestError);
+   });
+
+   it("rejects non-string inputs", () => {
+      expect(() => assertSafeEnvironmentPath(undefined)).toThrow(
+         BadRequestError,
+      );
+      expect(() => assertSafeEnvironmentPath(null)).toThrow(BadRequestError);
+      expect(() => assertSafeEnvironmentPath(42)).toThrow(BadRequestError);
+   });
+});
+
+describe("safeJoinUnderRoot", () => {
+   const root = "/tmp/test-root";
+
+   it("returns the resolved root when joined with no segments", () => {
+      expect(safeJoinUnderRoot(root)).toBe(path.resolve(root));
+   });
+
+   it("joins safe segments into a path under root", () => {
+      expect(safeJoinUnderRoot(root, "pkg", "model.malloy")).toBe(
+         path.resolve(root, "pkg", "model.malloy"),
+      );
+   });
+
+   it("throws when traversal escapes the root", () => {
+      expect(() => safeJoinUnderRoot(root, "..")).toThrow(BadRequestError);
+      expect(() => safeJoinUnderRoot(root, "..", "etc", "passwd")).toThrow(
+         BadRequestError,
+      );
+      expect(() => safeJoinUnderRoot(root, "pkg", "..", "..", "etc")).toThrow(
+         BadRequestError,
+      );
+   });
+
+   it("throws when an absolute segment overrides the root", () => {
+      expect(() => safeJoinUnderRoot(root, "/etc/passwd")).toThrow(
+         BadRequestError,
+      );
+   });
+
+   it("does NOT match a sibling directory with the same prefix", () => {
+      // path.resolve("/tmp/test-root", "../test-root-bad")  ->  "/tmp/test-root-bad"
+      // which starts with "/tmp/test-root" textually but is NOT a child.
+      expect(() => safeJoinUnderRoot(root, "..", "test-root-bad")).toThrow(
+         BadRequestError,
+      );
+   });
+});

package/src/path_safety.ts

@@ -0,0 +1,140 @@
+import * as path from "path";
+
+import { BadRequestError } from "./errors";
+
+/**
+ * Path-safety helpers used by `Environment` (and any other service that
+ * builds an on-disk path from request data) to defend against directory
+ * traversal. The intent is two-fold:
+ *
+ *  1. **Source-side allowlist**: `assertSafePackageName` /
+ *     `assertSafeRelativeModelPath` reject hostile inputs (`..`, leading
+ *     `/`, `\`, NUL, dotfiles) at the entry of every public service
+ *     method before any path-construction happens. These throw
+ *     `BadRequestError` so the controller layer's error mapper returns
+ *     HTTP 400.
+ *
+ *  2. **Sink-side containment**: `safeJoinUnderRoot` joins, resolves,
+ *     and verifies the result is strictly within the supplied root.
+ *     Even if a future caller forgets the source-side check, the sink
+ *     refuses to hand back an escaping path. This is the standard
+ *     "resolve-and-contain" pattern that CodeQL's `js/path-injection`
+ *     query recognises as a sanitizer.
+ */
+
+// Single path segment: ASCII letters, digits, `-`, `_`, `.`. No leading
+// `.` so internal sibling dirs (`.staging`, `.retired`) and editor /
+// VCS dirs can't be addressed by name from outside.
+const SAFE_NAME_RE = /^(?!\.\.?$)(?!\.)[A-Za-z0-9._-]{1,255}$/;
+
+const MAX_MODEL_PATH_LEN = 1024;
+
+// An environment path is server-controlled (config / disk-derived), but
+// CodeQL conservatively treats it as tainted because Express handlers on
+// the same class touch user input. The combined regex test +
+// `..` / NUL / length check at the constructor gate is the sanitizer
+// barrier the `js/path-injection` query recognises. Printable ASCII
+// only; absolute POSIX-or-Windows path; no `..`, no NUL.
+const SAFE_ENVIRONMENT_PATH_RE = /^(?:\/|[A-Za-z]:[\\/])[\x20-\x7E]*$/;
+const MAX_ENVIRONMENT_PATH_LEN = 4096;
+
+/**
+ * Reject anything that isn't a plausible single-segment package name.
+ * The allowlist is deliberately conservative — every existing test and
+ * production package name we've seen fits within it, and tightening
+ * here costs nothing.
+ */
+export function assertSafePackageName(packageName: unknown): void {
+   if (typeof packageName !== "string" || !SAFE_NAME_RE.test(packageName)) {
+      throw new BadRequestError(
+         `Invalid package name: must be 1-255 characters of letters, digits, "-", "_", or "." and must not start with "."`,
+      );
+   }
+}
+
+/**
+ * Reject anything that isn't a plausible *relative* path to a model
+ * file inside a package directory. Forward slashes are allowed (models
+ * live in subdirectories like `models/foo.malloy`); backslashes,
+ * absolute paths, NUL bytes, and `..` / `.` segments are not.
+ */
+export function assertSafeRelativeModelPath(modelPath: unknown): void {
+   if (
+      typeof modelPath !== "string" ||
+      modelPath.length === 0 ||
+      modelPath.length > MAX_MODEL_PATH_LEN ||
+      modelPath.includes("\0") ||
+      modelPath.includes("\\") ||
+      path.isAbsolute(modelPath) ||
+      modelPath.startsWith("/")
+   ) {
+      throw new BadRequestError(`Invalid model path`);
+   }
+
+   const segments = modelPath.split("/");
+   for (const segment of segments) {
+      if (segment === "" || segment === "." || segment === "..") {
+         throw new BadRequestError(`Invalid model path`);
+      }
+      if (segment.startsWith(".")) {
+         throw new BadRequestError(`Invalid model path`);
+      }
+   }
+}
+
+/**
+ * Reject anything that doesn't look like a server-controlled absolute
+ * filesystem path. Applied to `environmentPath` at the constructor
+ * gate so all downstream `path.join(this.environmentPath, …)` sites
+ * see a value that has cleared an allowlist check — the canonical
+ * sanitizer-barrier pattern CodeQL's `js/path-injection` query
+ * recognises.
+ */
+export function assertSafeEnvironmentPath(environmentPath: unknown): void {
+   if (typeof environmentPath !== "string") {
+      throw new BadRequestError(`Invalid environment path: must be a string`);
+   }
+   if (
+      environmentPath.length === 0 ||
+      environmentPath.length > MAX_ENVIRONMENT_PATH_LEN
+   ) {
+      throw new BadRequestError(`Invalid environment path: bad length`);
+   }
+   if (environmentPath.indexOf("\0") !== -1) {
+      throw new BadRequestError(`Invalid environment path: contains NUL byte`);
+   }
+   // Sanitizer barrier in the shape `x.indexOf("..") !== -1` that the
+   // CodeQL `js/path-injection` query recognises as a traversal guard.
+   if (environmentPath.indexOf("..") !== -1) {
+      throw new BadRequestError(
+         `Invalid environment path: contains ".." traversal segment`,
+      );
+   }
+   if (!SAFE_ENVIRONMENT_PATH_RE.test(environmentPath)) {
+      throw new BadRequestError(
+         `Invalid environment path: must be an absolute path of printable ASCII characters`,
+      );
+   }
+}
+
+/**
+ * Resolve `path.join(root, ...segments)` and verify the result lives
+ * strictly inside `root` (or is `root` itself). Throws
+ * `BadRequestError` if the resolved path escapes the root via `..`,
+ * absolute segments, or symlink-style trickery in the input.
+ *
+ * Callers should still run `assertSafePackageName` / similar on
+ * user-controlled segments first — this helper is the second line of
+ * defense, not the first.
+ */
+export function safeJoinUnderRoot(root: string, ...segments: string[]): string {
+   const resolvedRoot = path.resolve(root);
+   const joined = path.resolve(resolvedRoot, ...segments);
+   const rootWithSep = resolvedRoot.endsWith(path.sep)
+      ? resolvedRoot
+      : resolvedRoot + path.sep;
+   if (joined !== resolvedRoot && !joined.startsWith(rootWithSep)) {
+      throw new BadRequestError(`Resolved path is outside of root`);
+   }
+   return joined;
+}