feat(functions): add remoteSource utility and path resolution helper

src/deploy/functions/remoteSource.spec.ts

@@ -0,0 +1,128 @@
+import { expect } from "chai";
+import * as sinon from "sinon";
+import * as fs from "fs";
+
+import * as remoteSourceModule from "./remoteSource";
+import { cloneRemoteSource, GitClient } from "./remoteSource";
+import { FirebaseError } from "../../error";
+
+describe("remoteSource", () => {
+  describe("cloneRemoteSource", () => {
+    let existsSyncStub: sinon.SinonStub;
+    let isGitAvailableStub: sinon.SinonStub;
+    let cloneStub: sinon.SinonStub;
+    let fetchStub: sinon.SinonStub;
+    let checkoutStub: sinon.SinonStub;
+    let mockGitClient: GitClient;
+
+    beforeEach(() => {
+      existsSyncStub = sinon.stub(fs, "existsSync");
+      isGitAvailableStub = sinon.stub(remoteSourceModule, "isGitAvailable");
+
+      cloneStub = sinon.stub().returns({ status: 0 });
+      fetchStub = sinon.stub().returns({ status: 0 });
+      checkoutStub = sinon.stub().returns({ status: 0 });
+      mockGitClient = {
+        clone: cloneStub,
+        fetch: fetchStub,
+        checkout: checkoutStub,
+      } as unknown as GitClient;
+    });
+
+    afterEach(() => {
+      existsSyncStub.restore();
+      isGitAvailableStub.restore();
+    });
+
+    it("should handle clone failures with meaningful errors", async () => {
+      isGitAvailableStub.returns(true);
+      cloneStub.returns({
+        status: 1,
+        stderr: "fatal: unable to access 'https://github.com/org/repo': Could not resolve host",
+      });
+
+      await expect(
+        cloneRemoteSource("https://github.com/org/repo", "main", undefined, mockGitClient),
+      ).to.be.rejectedWith(FirebaseError, /Unable to access repository/);
+    });
+
+    it("should handle fetch failures for invalid refs", async () => {
+      isGitAvailableStub.returns(true);
+      fetchStub.returns({
+        status: 1,
+        stderr: "error: pathspec 'bad-ref' did not match any file(s) known to git",
+      });
+
+      await expect(
+        cloneRemoteSource("https://github.com/org/repo", "bad-ref", undefined, mockGitClient),
+      ).to.be.rejectedWith(FirebaseError, /Git ref 'bad-ref' not found/);
+    });
+
+    it("should validate subdirectory exists after clone", async () => {
+      isGitAvailableStub.returns(true);
+      // Simulate that the subdirectory does not exist
+      existsSyncStub.callsFake((p: fs.PathLike) => {
+        const s = String(p);
+        if (/[/\\]subdir$/.test(s)) return false; // dir missing
+        if (s.endsWith("functions.yaml")) return true; // avoid manifest error masking
+        return true;
+      });
+      await expect(
+        cloneRemoteSource("https://github.com/org/repo", "main", "subdir", mockGitClient),
+      ).to.be.rejectedWith(FirebaseError, /Directory 'subdir' not found/);
+    });
+
+    it("should validate functions.yaml exists", async () => {
+      isGitAvailableStub.returns(true);
+      // Everything exists except the manifest file
+      existsSyncStub.callsFake((p: fs.PathLike) => !String(p).endsWith("functions.yaml"));
+
+      await expect(
+        cloneRemoteSource("https://github.com/org/repo", "main", undefined, mockGitClient),
+      ).to.be.rejectedWith(FirebaseError, /missing a required deployment manifest/);
+    });
+
+    it("should successfully clone a repository without a subdirectory", async () => {
+      isGitAvailableStub.returns(true);
+      // Pass manifest check by returning true for any path ending with functions.yaml
+      existsSyncStub.callsFake((p: fs.PathLike) => String(p).endsWith("functions.yaml"));
+
+      const sourceDir = await cloneRemoteSource(
+        "https://github.com/org/repo",
+        "main",
+        undefined,
+        mockGitClient,
+      );
+
+      expect(cloneStub.calledOnceWith("https://github.com/org/repo", sinon.match.string)).to.be
+        .true;
+      expect(fetchStub.calledOnceWith("main", sinon.match.string)).to.be.true;
+      expect(checkoutStub.calledOnceWith("FETCH_HEAD", sinon.match.string)).to.be.true;
+      // No sparse-checkout in MVP path
+      expect(sourceDir).to.be.a("string");
+    });
+
+    it("should successfully clone a repository with a subdirectory", async () => {
+      isGitAvailableStub.returns(true);
+      existsSyncStub.callsFake((p: fs.PathLike) => {
+        const s = String(p);
+        if (/[/\\]functions$/.test(s)) return true; // subdir exists
+        if (s.endsWith("functions.yaml")) return true; // manifest exists
+        return false;
+      });
+
+      const dir = "functions";
+      const sourceDir = await cloneRemoteSource(
+        "https://github.com/org/repo",
+        "main",
+        dir,
+        mockGitClient,
+      );
+
+      expect(fetchStub.calledOnceWith("main", sinon.match.string)).to.be.true;
+      expect(checkoutStub.calledOnceWith("FETCH_HEAD", sinon.match.string)).to.be.true;
+      expect(sourceDir).to.be.a("string");
+      expect(/[/\\]functions$/.test(sourceDir)).to.be.true;
+    });
+  });
+});

src/deploy/functions/remoteSource.ts

@@ -0,0 +1,221 @@
+import * as fs from "fs";
+import * as path from "path";
+import { spawnSync, SpawnSyncReturns } from "child_process";
+
+import * as tmp from "tmp";
+
+import { FirebaseError, hasMessage } from "../../error";
+import { logger } from "../../logger";
+import { logLabeledBullet } from "../../utils";
+import { resolveWithin } from "../../pathUtils";
+
+export interface GitClient {
+  clone(repository: string, destination: string): SpawnSyncReturns<string>;
+  fetch(ref: string, cwd: string): SpawnSyncReturns<string>;
+  checkout(ref: string, cwd: string): SpawnSyncReturns<string>;
+}
+
+export class DefaultGitClient implements GitClient {
+  clone(repository: string, destination: string): SpawnSyncReturns<string> {
+    return spawnSync(
+      "git",
+      ["clone", "--filter=blob:none", "--no-checkout", "--depth=1", repository, destination],
+      { encoding: "utf8" },
+    );
+  }
+
+  fetch(ref: string, cwd: string): SpawnSyncReturns<string> {
+    return spawnSync("git", ["fetch", "--depth=1", "--filter=blob:none", "origin", ref], {
+      cwd,
+      encoding: "utf8",
+    });
+  }
+
+  checkout(ref: string, cwd: string): SpawnSyncReturns<string> {
+    return spawnSync("git", ["checkout", ref], { cwd, encoding: "utf8" });
+  }
+}
+
+export async function cloneRemoteSource(
+  repository: string,
+  ref: string,
+  dir?: string,
+  gitClient: GitClient = new DefaultGitClient(),
+): Promise<string> {
+  /**
+   * Clones a Git repo to a temporary directory and returns the absolute path
+   * to the source directory. Verifies that a `functions.yaml` manifest exists
+   * before returning.
+   *
+   * @param repository Remote Git URL (e.g. https://github.com/org/repo)
+   * @param ref Git ref to fetch (tag/branch/commit)
+   * @param dir Optional subdirectory within the repo to use
+   * @param gitClient Optional Git client for testing/injection
+   * @returns Absolute path to the checked‑out source directory
+   */
+  logger.debug(`Cloning remote source: ${repository}@${ref} (dir: ${dir || "."})`);
+
+  const tmpDir = tmp.dirSync({
+    prefix: "firebase-functions-remote-",
+    unsafeCleanup: true,
+  });
+
+  if (!isGitAvailable()) {
+    throw new FirebaseError(
+      "Git is required to deploy functions from a remote source. " +
+        "Please install Git from https://git-scm.com/downloads and try again.",
+    );
+  }
+
+  try {
+    logger.debug(`Fetching remote source for ${repository}@${ref}...`);
+
+    const cloneResult = await runGitWithRetry(() => gitClient.clone(repository, tmpDir.name));
+    if (cloneResult.error || cloneResult.status !== 0) {
+      throw (
+        cloneResult.error ||
+        new Error(
+          cloneResult.stderr ||
+            cloneResult.stdout ||
+            `Clone failed with status ${cloneResult.status}`,
+        )
+      );
+    }
+
+    const fetchResult = await runGitWithRetry(() => gitClient.fetch(ref, tmpDir.name));
+    if (fetchResult.error || fetchResult.status !== 0) {
+      throw (
+        fetchResult.error ||
+        new Error(
+          fetchResult.stderr ||
+            fetchResult.stdout ||
+            `Fetch failed with status ${fetchResult.status}`,
+        )
+      );
+    }
+
+    const checkoutResult = gitClient.checkout("FETCH_HEAD", tmpDir.name);
+    if (checkoutResult.error || checkoutResult.status !== 0) {
+      throw (
+        checkoutResult.error ||
+        new Error(
+          checkoutResult.stderr ||
+            checkoutResult.stdout ||
+            `Checkout failed with status ${checkoutResult.status}`,
+        )
+      );
+    }
+
+    const sourceDir = dir
+      ? resolveWithin(
+          tmpDir.name,
+          dir,
+          `Subdirectory '${dir}' in remote source must not escape the repository root.`,
+        )
+      : tmpDir.name;
+
+    if (dir && !fs.existsSync(sourceDir)) {
+      throw new FirebaseError(`Directory '${dir}' not found in repository ${repository}@${ref}`);
+    }
+
+    requireFunctionsYaml(sourceDir);
+    const origin = `${repository}@${ref}${dir ? `/${dir}` : ""}`;
+    logLabeledBullet("functions", `verified functions.yaml in remote source (${origin})`);
+    return sourceDir;
+  } catch (error: unknown) {
+    if (error instanceof FirebaseError) {
+      throw error;
+    }
+
+    const errorMessage = hasMessage(error) ? error.message : String(error);
+    if (
+      errorMessage.includes("Could not resolve host") ||
+      errorMessage.includes("unable to access")
+    ) {
+      throw new FirebaseError(
+        `Unable to access repository '${repository}'. ` +
+          `Please check the repository URL and your network connection.`,
+      );
+    }
+    if (errorMessage.includes("pathspec") || errorMessage.includes("did not match")) {
+      throw new FirebaseError(
+        `Git ref '${ref}' not found in repository '${repository}'. ` +
+          `Please check that the ref (tag, branch, or commit) exists.`,
+      );
+    }
+    if (
+      errorMessage.includes("Permission denied") ||
+      errorMessage.includes("Authentication failed")
+    ) {
+      throw new FirebaseError(
+        `Authentication failed for repository '${repository}'. ` +
+          `For private repositories, please ensure you have configured Git authentication.`,
+      );
+    }
+
+    throw new FirebaseError(`Failed to clone repository '${repository}@${ref}': ${errorMessage}`);
+  }
+}
+
+/**
+ * Checks whether the `git` binary is available in the current environment.
+ * @returns true if `git --version` runs successfully; false otherwise.
+ */
+export function isGitAvailable(): boolean {
+  const result = spawnSync("git", ["--version"], { encoding: "utf8" });
+  return !result.error && result.status === 0;
+}
+
+async function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isTransientGitError(message: string): boolean {
+  const m = message.toLowerCase();
+  return (
+    m.includes("could not resolve host") ||
+    m.includes("unable to access") ||
+    m.includes("connection reset") ||
+    m.includes("timed out") ||
+    m.includes("temporary failure in name resolution") ||
+    m.includes("ssl_read") ||
+    m.includes("network is unreachable")
+  );
+}
+
+async function runGitWithRetry(
+  cmd: () => SpawnSyncReturns<string>,
+  retries = 1,
+  backoffMs = 200,
+): Promise<SpawnSyncReturns<string>> {
+  let attempt = 0;
+  while (true) {
+    const res = cmd();
+    if (!res.error && res.status === 0) {
+      return res;
+    }
+    const stderr = (res.stderr || res.stdout || "").toString();
+    if (attempt < retries && isTransientGitError(stderr)) {
+      await delay(backoffMs * (attempt + 1));
+      attempt++;
+      continue;
+    }
+    return res;
+  }
+}
+
+/**
+ * Verifies that a `functions.yaml` manifest exists at the given directory.
+ * Throws a FirebaseError with guidance if it is missing.
+ */
+export function requireFunctionsYaml(codeDir: string): void {
+  const functionsYamlPath = path.join(codeDir, "functions.yaml");
+  if (!fs.existsSync(functionsYamlPath)) {
+    throw new FirebaseError(
+      `The remote repository is missing a required deployment manifest (functions.yaml).\n\n` +
+        `For your security, Firebase requires a static manifest to deploy functions from a remote source. ` +
+        `This prevents the execution of arbitrary code on your machine during the function discovery process.\n\n` +
+        `To resolve this, clone the repository locally, inspect the code for safety, and deploy it as a local source.`,
+    );
+  }
+}

src/pathUtils.spec.ts

@@ -0,0 +1,47 @@
+import { expect } from "chai";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { resolveWithin } from "./pathUtils";
+import { FirebaseError } from "./error";
+
+describe("resolveWithin", () => {
+  let baseDir: string;
+
+  beforeEach(() => {
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "fb-pathutils-"));
+  });
+
+  it("returns absolute path when subpath is inside base (relative)", () => {
+    const p = resolveWithin(baseDir, "sub/dir");
+    expect(p).to.equal(path.join(baseDir, "sub/dir"));
+  });
+
+  it("returns base when subpath normalizes to base (e.g., nested/..)", () => {
+    const p = resolveWithin(baseDir, "nested/..");
+    expect(p).to.equal(baseDir);
+  });
+
+  it("throws when subpath escapes base using ..", () => {
+    expect(() => resolveWithin(baseDir, "../outside")).to.throw(FirebaseError);
+  });
+
+  it("throws with custom message when provided", () => {
+    expect(() => resolveWithin(baseDir, "../outside", "Custom error"))
+      .to.throw(FirebaseError)
+      .with.property("message")
+      .that.matches(/Custom error/);
+  });
+
+  it("throws when absolute subpath is outside base", () => {
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), "fb-pathutils-out-"));
+    expect(() => resolveWithin(baseDir, outside)).to.throw(FirebaseError);
+  });
+
+  it("allows absolute subpath when inside base", () => {
+    const inside = path.join(baseDir, "child");
+    const p = resolveWithin(baseDir, inside);
+    expect(p).to.equal(inside);
+  });
+});