@btatum5/codex-bridge 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btatum5/codex-bridge",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Local bridge between Codex and the Codex mobile app. Run `codex-bridge up` to start.",
   "main": "src/index.js",
   "bin": {
@@ -32,6 +32,7 @@
   "license": "ISC",
   "type": "commonjs",
   "dependencies": {
+    "bonjour-service": "^1.3.0",
     "qrcode-terminal": "^0.12.0",
     "ws": "^8.19.0"
   }

package/src/bridge.js

@@ -13,8 +13,9 @@ const {
 } = require("./codex-desktop-refresher");
 const { createCodexTransport } = require("./codex-transport");
 const { createThreadRolloutActivityWatcher } = require("./rollout-watch");
-const { printQR } = require("./qr");
-const { rememberActiveThread } = require("./session-state");
+const { printQR } = require("./qr");
+const { startPairingDiscoveryAdvertisement } = require("./local-pairing-discovery");
+const { rememberActiveThread } = require("./session-state");
 const { handleDesktopRequest } = require("./desktop-handler");
 const { handleGitRequest } = require("./git-handler");
 const { handleThreadContextRequest } = require("./thread-context-handler");
@@ -81,10 +82,11 @@ function startBridge({
   // Keep the local Codex runtime alive across transient relay disconnects.
   let socket = null;
   let isShuttingDown = false;
-  let reconnectAttempt = 0;
-  let reconnectTimer = null;
-  let lastConnectionStatus = null;
-  let codexHandshakeState = config.codexEndpoint ? "warm" : "cold";
+  let reconnectAttempt = 0;
+  let reconnectTimer = null;
+  let lastConnectionStatus = null;
+  let localPairingDiscovery = null;
+  let codexHandshakeState = config.codexEndpoint ? "warm" : "cold";
   const forwardedInitializeRequestIds = new Set();
   const secureTransport = createBridgeSecureTransport({
     sessionId,
@@ -254,13 +256,20 @@ function startBridge({
     });
   }
 
-  const pairingPayload = secureTransport.createPairingPayload();
-  onPairingPayload?.(pairingPayload);
-  if (printPairingQr) {
-    printQR(pairingPayload);
-  }
-  pushServiceClient.logUnavailable();
-  connectRelay();
+  const pairingPayload = secureTransport.createPairingPayload();
+  onPairingPayload?.(pairingPayload);
+  if (printPairingQr) {
+    printQR(pairingPayload);
+  }
+  try {
+    localPairingDiscovery = startPairingDiscoveryAdvertisement(pairingPayload);
+  } catch (error) {
+    console.warn(
+      `[codex-bridge] Local pairing discovery is unavailable: ${(error && error.message) || "unknown error"}`
+    );
+  }
+  pushServiceClient.logUnavailable();
+  connectRelay();
 
   codex.onMessage((message) => {
     trackCodexHandshakeState(message);
@@ -280,22 +289,28 @@ function startBridge({
     });
     isShuttingDown = true;
     clearReconnectTimer();
-    stopContextUsageWatcher();
-    rolloutLiveMirror?.stopAll();
-    desktopRefresher.handleTransportReset();
-    if (socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) {
-      socket.close();
-    }
-  });
-
-  process.on("SIGINT", () => shutdown(codex, () => socket, () => {
-    isShuttingDown = true;
-    clearReconnectTimer();
-  }));
-  process.on("SIGTERM", () => shutdown(codex, () => socket, () => {
-    isShuttingDown = true;
-    clearReconnectTimer();
-  }));
+    stopContextUsageWatcher();
+    rolloutLiveMirror?.stopAll();
+    desktopRefresher.handleTransportReset();
+    localPairingDiscovery?.stop();
+    localPairingDiscovery = null;
+    if (socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) {
+      socket.close();
+    }
+  });
+
+  process.on("SIGINT", () => shutdown(codex, () => socket, () => {
+    isShuttingDown = true;
+    clearReconnectTimer();
+    localPairingDiscovery?.stop();
+    localPairingDiscovery = null;
+  }));
+  process.on("SIGTERM", () => shutdown(codex, () => socket, () => {
+    isShuttingDown = true;
+    clearReconnectTimer();
+    localPairingDiscovery?.stop();
+    localPairingDiscovery = null;
+  }));
 
   // Routes decrypted app payloads through the same bridge handlers as before.
   function handleApplicationMessage(rawMessage) {

package/src/local-pairing-discovery.js

@@ -0,0 +1,87 @@
+// FILE: local-pairing-discovery.js
+// Purpose: Advertises the current pairing payload on the local network so iPhone clients can discover it without scanning.
+// Layer: CLI helper
+// Exports: startPairingDiscoveryAdvertisement
+// Depends on: bonjour-service
+
+const { Bonjour } = require("bonjour-service");
+
+const PAIRING_SERVICE_TYPE = "codex-pairing";
+
+function startPairingDiscoveryAdvertisement(pairingPayload, { logger = console } = {}) {
+  const bonjour = new Bonjour();
+  const serviceName = buildServiceName(pairingPayload);
+  const publishedService = bonjour.publish({
+    name: serviceName,
+    type: PAIRING_SERVICE_TYPE,
+    protocol: "tcp",
+    port: advertisedPort(pairingPayload.relay),
+    txt: buildTxtRecord(pairingPayload),
+  });
+
+  publishedService.on("up", () => {
+    logger.log?.(`[codex-bridge] Nearby pairing is available on local Wi-Fi as “${serviceName}”.`);
+  });
+  publishedService.on("error", (error) => {
+    logger.warn?.(
+      `[codex-bridge] Local pairing advertisement failed: ${(error && error.message) || "unknown error"}`
+    );
+  });
+
+  let didStop = false;
+
+  return {
+    stop() {
+      if (didStop) {
+        return;
+      }
+
+      didStop = true;
+      try {
+        publishedService.stop(() => {
+          bonjour.destroy();
+        });
+      } catch {
+        bonjour.destroy();
+      }
+    },
+  };
+}
+
+function buildServiceName(pairingPayload) {
+  const suffix = String(pairingPayload.macDeviceId || "")
+    .replace(/[^a-zA-Z0-9]/g, "")
+    .slice(0, 6)
+    .toUpperCase();
+  return suffix ? `Codex ${suffix}` : "Codex";
+}
+
+function buildTxtRecord(pairingPayload) {
+  return {
+    v: String(pairingPayload.v || ""),
+    relay: String(pairingPayload.relay || ""),
+    sid: String(pairingPayload.sessionId || ""),
+    mid: String(pairingPayload.macDeviceId || ""),
+    mpk: String(pairingPayload.macIdentityPublicKey || ""),
+    exp: String(pairingPayload.expiresAt || ""),
+  };
+}
+
+function advertisedPort(relayUrl) {
+  try {
+    const parsed = new URL(relayUrl);
+    if (parsed.port) {
+      return Number(parsed.port);
+    }
+    return parsed.protocol === "wss:" || parsed.protocol === "https:" ? 443 : 80;
+  } catch {
+    return 9;
+  }
+}
+
+module.exports = {
+  PAIRING_SERVICE_TYPE,
+  advertisedPort,
+  buildTxtRecord,
+  startPairingDiscoveryAdvertisement,
+};

package/src/workspace-handler.js

@@ -4,23 +4,28 @@
 // Exports: handleWorkspaceRequest
 // Depends on: child_process, fs, os, path, ./git-handler
 
-const { execFile } = require("child_process");
-const fs = require("fs");
-const os = require("os");
-const path = require("path");
-const { promisify } = require("util");
-const { gitStatus } = require("./git-handler");
-
-const execFileAsync = promisify(execFile);
-const GIT_TIMEOUT_MS = 30_000;
-const repoMutationLocks = new Map();
-
-function handleWorkspaceRequest(rawMessage, sendResponse) {
-  let parsed;
-  try {
-    parsed = JSON.parse(rawMessage);
-  } catch {
-    return false;
+const { execFile } = require("child_process");
+const { randomUUID } = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { promisify } = require("util");
+const { gitStatus } = require("./git-handler");
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 30_000;
+const MOBILE_FILE_IMPORT_MAX_BYTES = 1024 * 1024 * 1024;
+const MOBILE_FILE_IMPORT_MAX_CHUNK_BYTES = 1024 * 1024;
+const MOBILE_FILE_IMPORT_SINGLE_REQUEST_MAX_BYTES = MOBILE_FILE_IMPORT_MAX_CHUNK_BYTES;
+const activeMobileFileImports = new Map();
+const repoMutationLocks = new Map();
+
+function handleWorkspaceRequest(rawMessage, sendResponse, options = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(rawMessage);
+  } catch {
+    return false;
   }
 
   const method = typeof parsed?.method === "string" ? parsed.method.trim() : "";
@@ -30,12 +35,12 @@ function handleWorkspaceRequest(rawMessage, sendResponse) {
 
   const id = parsed.id;
   const params = parsed.params || {};
-
-  handleWorkspaceMethod(method, params)
-    .then((result) => {
-      sendResponse(JSON.stringify({ id, result }));
-    })
-    .catch((err) => {
+
+  handleWorkspaceMethod(method, params, options)
+    .then((result) => {
+      sendResponse(JSON.stringify({ id, result }));
+    })
+    .catch((err) => {
       const errorCode = err.errorCode || "workspace_error";
       const message = err.userMessage || err.message || "Unknown workspace error";
       sendResponse(
@@ -50,22 +55,281 @@ function handleWorkspaceRequest(rawMessage, sendResponse) {
       );
     });
 
-  return true;
-}
-
-async function handleWorkspaceMethod(method, params) {
-  const cwd = await resolveWorkspaceCwd(params);
-  const repoRoot = await resolveRepoRoot(cwd);
-
-  switch (method) {
-    case "workspace/revertPatchPreview":
-      return workspaceRevertPatchPreview(repoRoot, params);
-    case "workspace/revertPatchApply":
-      return withRepoMutationLock(repoRoot, () => workspaceRevertPatchApply(repoRoot, params));
-    default:
-      throw workspaceError("unknown_method", `Unknown workspace method: ${method}`);
-  }
-}
+  return true;
+}
+
+async function handleWorkspaceMethod(method, params, options = {}) {
+  switch (method) {
+    case "workspace/importMobileFile":
+      return workspaceImportMobileFile(params, options);
+    case "workspace/beginMobileFileImport":
+      return workspaceBeginMobileFileImport(params, options);
+    case "workspace/appendMobileFileImportChunk":
+      return workspaceAppendMobileFileImportChunk(params);
+    case "workspace/finishMobileFileImport":
+      return workspaceFinishMobileFileImport(params);
+    case "workspace/cancelMobileFileImport":
+      return workspaceCancelMobileFileImport(params);
+    case "workspace/revertPatchPreview":
+    case "workspace/revertPatchApply": {
+      const cwd = await resolveWorkspaceCwd(params);
+      const repoRoot = await resolveRepoRoot(cwd);
+      if (method === "workspace/revertPatchPreview") {
+        return workspaceRevertPatchPreview(repoRoot, params);
+      }
+      return withRepoMutationLock(repoRoot, () => workspaceRevertPatchApply(repoRoot, params));
+    }
+    default:
+      throw workspaceError("unknown_method", `Unknown workspace method: ${method}`);
+  }
+}
+
+async function workspaceImportMobileFile(
+  params,
+  {
+    fsModule = fs,
+    osModule = os,
+    pathModule = path,
+    env = process.env,
+  } = {}
+) {
+  const base64Data = normalizeBase64Payload(params.base64Data);
+  if (!base64Data) {
+    throw workspaceError("missing_file_data", "The selected file could not be uploaded.");
+  }
+
+  const fileBuffer = decodeBase64File(base64Data);
+  if (!fileBuffer.length) {
+    throw workspaceError("empty_file", "The selected file is empty.");
+  }
+  if (fileBuffer.length > MOBILE_FILE_IMPORT_SINGLE_REQUEST_MAX_BYTES) {
+    throw workspaceError(
+      "file_too_large",
+      "This file is too large for single-request uploads. Update the app and retry."
+    );
+  }
+
+  const requestedFileName = firstNonEmptyString([params.fileName, params.name]);
+  const sanitizedFileName = sanitizeImportFileName(requestedFileName, pathModule);
+  const importRoot = resolveMobileImportRoot({
+    requestedCwd: firstNonEmptyString([params.cwd, params.currentWorkingDirectory]),
+    fsImpl: fsModule,
+    osImpl: osModule,
+    pathImpl: pathModule,
+    env,
+  });
+  fsModule.mkdirSync(importRoot, { recursive: true });
+
+  const destinationPath = reserveUniqueImportPath(importRoot, sanitizedFileName, {
+    fsImpl: fsModule,
+    pathImpl: pathModule,
+  });
+  await fsModule.promises.writeFile(destinationPath, fileBuffer, { mode: 0o600 });
+  try {
+    fsModule.chmodSync(destinationPath, 0o600);
+  } catch {
+    // Best-effort only on filesystems without POSIX mode support.
+  }
+
+  const normalizedMimeType = firstNonEmptyString([params.mimeType, params.contentType]);
+  return {
+    fileName: pathModule.basename(destinationPath),
+    path: destinationPath,
+    sizeBytes: fileBuffer.length,
+    mimeType: normalizedMimeType || null,
+    importRoot,
+  };
+}
+
+async function workspaceBeginMobileFileImport(
+  params,
+  {
+    fsModule = fs,
+    osModule = os,
+    pathModule = path,
+    env = process.env,
+  } = {}
+) {
+  const requestedFileName = firstNonEmptyString([params.fileName, params.name]);
+  const sanitizedFileName = sanitizeImportFileName(requestedFileName, pathModule);
+  const totalBytes = readOptionalNonNegativeInteger(params.totalBytes, "totalBytes");
+
+  if (totalBytes === 0) {
+    throw workspaceError("empty_file", "The selected file is empty.");
+  }
+  if (totalBytes != null && totalBytes > MOBILE_FILE_IMPORT_MAX_BYTES) {
+    throw workspaceError(
+      "file_too_large",
+      "This file is larger than 1 GB. Pick a smaller file and retry."
+    );
+  }
+
+  const importRoot = resolveMobileImportRoot({
+    requestedCwd: firstNonEmptyString([params.cwd, params.currentWorkingDirectory]),
+    fsImpl: fsModule,
+    osImpl: osModule,
+    pathImpl: pathModule,
+    env,
+  });
+  fsModule.mkdirSync(importRoot, { recursive: true });
+
+  const destinationPath = reserveUniqueImportPath(importRoot, sanitizedFileName, {
+    fsImpl: fsModule,
+    pathImpl: pathModule,
+  });
+  const uploadId = randomUUID();
+  const tempPath = reserveTempImportPath(importRoot, sanitizedFileName, uploadId, {
+    fsImpl: fsModule,
+    pathImpl: pathModule,
+  });
+
+  await fsModule.promises.writeFile(tempPath, Buffer.alloc(0), {
+    flag: "wx",
+    mode: 0o600,
+  });
+  try {
+    fsModule.chmodSync(tempPath, 0o600);
+  } catch {
+    // Best-effort only on filesystems without POSIX mode support.
+  }
+
+  const normalizedMimeType = firstNonEmptyString([params.mimeType, params.contentType]);
+  activeMobileFileImports.set(uploadId, {
+    uploadId,
+    tempPath,
+    destinationPath,
+    fileName: pathModule.basename(destinationPath),
+    requestedFileName: sanitizedFileName,
+    mimeType: normalizedMimeType || null,
+    importRoot,
+    bytesWritten: 0,
+    totalBytes,
+    fsModule,
+    pathModule,
+  });
+
+  return {
+    uploadId,
+    fileName: pathModule.basename(destinationPath),
+    path: destinationPath,
+    importRoot,
+    maxChunkBytes: MOBILE_FILE_IMPORT_MAX_CHUNK_BYTES,
+    maxUploadBytes: MOBILE_FILE_IMPORT_MAX_BYTES,
+  };
+}
+
+async function workspaceAppendMobileFileImportChunk(params) {
+  const uploadId = requireUploadId(params.uploadId);
+  const session = requireActiveMobileImport(uploadId);
+  const base64Data = normalizeBase64Payload(params.base64Data);
+  if (!base64Data) {
+    throw workspaceError("missing_file_data", "The selected file could not be uploaded.");
+  }
+
+  const fileBuffer = decodeBase64File(base64Data);
+  if (!fileBuffer.length) {
+    throw workspaceError("empty_chunk", "The uploaded chunk was empty.");
+  }
+  if (fileBuffer.length > MOBILE_FILE_IMPORT_MAX_CHUNK_BYTES) {
+    throw workspaceError(
+      "chunk_too_large",
+      "The upload chunk is too large. Retry the upload."
+    );
+  }
+
+  const nextByteCount = session.bytesWritten + fileBuffer.length;
+  if (nextByteCount > MOBILE_FILE_IMPORT_MAX_BYTES) {
+    await destroyMobileImportSession(uploadId, session);
+    throw workspaceError(
+      "file_too_large",
+      "This file is larger than 1 GB. Pick a smaller file and retry."
+    );
+  }
+  if (session.totalBytes != null && nextByteCount > session.totalBytes) {
+    await destroyMobileImportSession(uploadId, session);
+    throw workspaceError(
+      "upload_size_mismatch",
+      "The uploaded file exceeded its declared size. Retry the upload."
+    );
+  }
+
+  await session.fsModule.promises.appendFile(session.tempPath, fileBuffer, { mode: 0o600 });
+  session.bytesWritten = nextByteCount;
+
+  return {
+    uploadId,
+    bytesWritten: session.bytesWritten,
+    remainingBytes: session.totalBytes == null
+      ? null
+      : Math.max(session.totalBytes - session.bytesWritten, 0),
+  };
+}
+
+async function workspaceFinishMobileFileImport(params) {
+  const uploadId = requireUploadId(params.uploadId);
+  const session = requireActiveMobileImport(uploadId);
+
+  if (session.bytesWritten <= 0) {
+    await destroyMobileImportSession(uploadId, session);
+    throw workspaceError("empty_file", "The selected file is empty.");
+  }
+  if (session.totalBytes != null && session.bytesWritten !== session.totalBytes) {
+    await destroyMobileImportSession(uploadId, session);
+    throw workspaceError(
+      "upload_incomplete",
+      "The selected file did not finish uploading. Retry the upload."
+    );
+  }
+
+  let finalPath = session.destinationPath;
+  if (session.fsModule.existsSync(finalPath)) {
+    finalPath = reserveUniqueImportPath(session.importRoot, session.requestedFileName, {
+      fsImpl: session.fsModule,
+      pathImpl: session.pathModule,
+    });
+  }
+
+  try {
+    await session.fsModule.promises.rename(session.tempPath, finalPath);
+  } catch (err) {
+    await destroyMobileImportSession(uploadId, session);
+    throw workspaceError(
+      "file_write_failed",
+      err?.message || "The uploaded file could not be finalized."
+    );
+  }
+
+  try {
+    session.fsModule.chmodSync(finalPath, 0o600);
+  } catch {
+    // Best-effort only on filesystems without POSIX mode support.
+  }
+
+  activeMobileFileImports.delete(uploadId);
+
+  return {
+    fileName: session.pathModule.basename(finalPath),
+    path: finalPath,
+    sizeBytes: session.bytesWritten,
+    mimeType: session.mimeType,
+    importRoot: session.importRoot,
+  };
+}
+
+async function workspaceCancelMobileFileImport(params) {
+  const uploadId = firstNonEmptyString([params.uploadId]);
+  if (!uploadId) {
+    return { cancelled: false };
+  }
+
+  const session = activeMobileFileImports.get(uploadId);
+  if (!session) {
+    return { cancelled: false };
+  }
+
+  await destroyMobileImportSession(uploadId, session);
+  return { cancelled: true };
+}
 
 // Validates the reverse patch against the current tree without writing repo files.
 async function workspaceRevertPatchPreview(repoRoot, params) {
@@ -272,10 +536,10 @@ function extractPatchPath(lines) {
   return "";
 }
 
-function normalizeDiffPath(rawPath) {
-  if (!rawPath) {
-    return "";
-  }
+function normalizeDiffPath(rawPath) {
+  if (!rawPath) {
+    return "";
+  }
 
   if (rawPath.startsWith("a/") || rawPath.startsWith("b/")) {
     return rawPath.slice(2);
@@ -422,7 +686,7 @@ async function resolveRepoRoot(cwd) {
   );
 }
 
-function firstNonEmptyString(candidates) {
+function firstNonEmptyString(candidates) {
   for (const candidate of candidates) {
     if (typeof candidate !== "string") {
       continue;
@@ -434,16 +698,155 @@ function firstNonEmptyString(candidates) {
     }
   }
 
-  return null;
-}
-
-function isExistingDirectory(candidatePath) {
-  try {
-    return fs.statSync(candidatePath).isDirectory();
-  } catch {
-    return false;
-  }
-}
+  return null;
+}
+
+function normalizeBase64Payload(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+
+  const commaIndex = trimmed.indexOf(",");
+  const payload = trimmed.startsWith("data:") && commaIndex >= 0
+    ? trimmed.slice(commaIndex + 1)
+    : trimmed;
+  return payload.replace(/\s+/g, "");
+}
+
+function decodeBase64File(base64Data) {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64Data) || base64Data.length % 4 === 1) {
+    throw workspaceError("invalid_file_data", "The selected file could not be decoded.");
+  }
+
+  const fileBuffer = Buffer.from(base64Data, "base64");
+  if (!fileBuffer.length) {
+    return Buffer.alloc(0);
+  }
+
+  const normalizedInput = base64Data.replace(/=+$/, "");
+  const normalizedDecoded = fileBuffer.toString("base64").replace(/=+$/, "");
+  if (normalizedDecoded !== normalizedInput) {
+    throw workspaceError("invalid_file_data", "The selected file could not be decoded.");
+  }
+
+  return fileBuffer;
+}
+
+function sanitizeImportFileName(fileName, pathImpl = path) {
+  const rawName = typeof fileName === "string" ? fileName.trim() : "";
+  const baseName = rawName ? pathImpl.basename(rawName) : "upload.bin";
+  const sanitized = baseName.replace(/[<>:"/\\|?*\u0000-\u001F]/g, "_");
+  return sanitized || "upload.bin";
+}
+
+function resolveMobileImportRoot({
+  requestedCwd,
+  fsImpl = fs,
+  osImpl = os,
+  pathImpl = path,
+  env = process.env,
+} = {}) {
+  if (requestedCwd && isExistingDirectory(requestedCwd, fsImpl)) {
+    return pathImpl.join(requestedCwd, ".codex-mobile-uploads");
+  }
+
+  const codexHome = firstNonEmptyString([env.CODEX_HOME])
+    || pathImpl.join(osImpl.homedir(), ".codex");
+  return pathImpl.join(codexHome, "mobile-uploads");
+}
+
+function reserveUniqueImportPath(importRoot, fileName, { fsImpl = fs, pathImpl = path } = {}) {
+  const parsed = pathImpl.parse(fileName);
+  const safeBaseName = parsed.name || "upload";
+  const extension = parsed.ext || "";
+  let attempt = 0;
+
+  while (true) {
+    const candidateName = attempt === 0
+      ? `${safeBaseName}${extension}`
+      : `${safeBaseName}-${attempt + 1}${extension}`;
+    const candidatePath = pathImpl.join(importRoot, candidateName);
+    if (!fsImpl.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+    attempt += 1;
+  }
+}
+
+function reserveTempImportPath(importRoot, fileName, uploadId, { fsImpl = fs, pathImpl = path } = {}) {
+  const parsed = pathImpl.parse(fileName);
+  const safeBaseName = parsed.name || "upload";
+  const extension = parsed.ext || "";
+  let attempt = 0;
+
+  while (true) {
+    const candidateName = attempt === 0
+      ? `.${safeBaseName}-${uploadId}${extension}.partial`
+      : `.${safeBaseName}-${uploadId}-${attempt + 1}${extension}.partial`;
+    const candidatePath = pathImpl.join(importRoot, candidateName);
+    if (!fsImpl.existsSync(candidatePath)) {
+      return candidatePath;
+    }
+    attempt += 1;
+  }
+}
+
+function requireUploadId(value) {
+  const uploadId = firstNonEmptyString([value]);
+  if (!uploadId) {
+    throw workspaceError("missing_upload_id", "The upload session is missing. Retry the upload.");
+  }
+  return uploadId;
+}
+
+function requireActiveMobileImport(uploadId) {
+  const session = activeMobileFileImports.get(uploadId);
+  if (!session) {
+    throw workspaceError("unknown_upload", "The upload session expired. Retry the upload.");
+  }
+  return session;
+}
+
+async function destroyMobileImportSession(uploadId, session) {
+  activeMobileFileImports.delete(uploadId);
+  try {
+    await session.fsModule.promises.unlink(session.tempPath);
+  } catch {
+    // Ignore temp cleanup failures.
+  }
+}
+
+function readOptionalNonNegativeInteger(value, fieldName) {
+  if (value == null) {
+    return null;
+  }
+
+  const numericValue = typeof value === "number"
+    ? value
+    : (typeof value === "string" && value.trim() ? Number(value) : NaN);
+
+  if (!Number.isInteger(numericValue) || numericValue < 0) {
+    throw workspaceError(
+      "invalid_upload_size",
+      `${fieldName} must be a non-negative integer.`
+    );
+  }
+
+  return numericValue;
+}
+
+function isExistingDirectory(candidatePath, fsImpl = fs) {
+  try {
+    return fsImpl.statSync(candidatePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
 
 function workspaceError(errorCode, userMessage) {
   const err = new Error(userMessage);