Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

4.5 KB
Raw Blame
import * as path from 'path';
import * as os from 'os';
import { AppError } from './AppError';

/**
 * Sanitizes and formats a storage path based on the storage type and operating system.
 * @param storagePath The user-provided storage path string.
 * @param storageType The type of storage (e.g., 'local', 's3', 'b2').
 * @param targetOS Optional OS of the target device (e.g., 'linux', 'windows', 'darwin').
 *   When provided, path operations use the target OS conventions instead of the server's OS.
 *   This prevents cross-platform issues such as a Windows server prepending a drive letter
 *   to a Linux absolute path like `/var/home/xxx` → `F:/var/home/xxx`.
 * @returns A sanitized, correctly formatted path string.
 * @throws {AppError} Throws a 400 Bad Request error if the path is invalid or contains malicious sequences.
 */
export function sanitizeStoragePath(
	storagePath: string,
	storageType: string,
	targetOS?: string
): string {
	if (typeof storagePath !== 'string') {
		// Handle cases where the input might not be a string
		return '';
	}

	const trimmedPath = storagePath.trim();

	// Determine path module based on target OS when provided,
	// otherwise fall back to the server's native path module.
	const isTargetWindows = targetOS
		? targetOS === 'windows' || targetOS === 'win32'
		: os.platform() === 'win32';
	const pathModule = isTargetWindows ? path.win32 : path.posix;

	// Normalize the path to resolve segments like '.', '..', and multiple slashes.
	const normalizedPath = pathModule.normalize(trimmedPath);

	// **Security Check:** After normalization, if ".." still exists, it's a sign of a
	if (normalizedPath.includes('..')) {
		throw new AppError(
			400,
			'Invalid Storage Destination path: Directory traversal sequences ("..") are not allowed.'
		);
	}

	if (storageType === 'local') {
		if (isTargetWindows) {
			// Refuse UNC paths. Test the RAW input, because
			// path.win32.normalize('\\\\host') collapses to '\host' and destroys the
			// UNC signature (the silent F:\host defect). The raw test finds
			// '\\host\share', '\\host', and '//host/share'.
			const parsedRoot = path.win32.parse(normalizedPath).root;
			if (/^[\\/]{2}/.test(trimmedPath) || parsedRoot.startsWith('\\\\')) {
				throw new AppError(
					400,
					'Invalid Storage Destination path: Network (UNC) destinations are not supported. Map the share to a drive letter on the Pluton host, or add the share as an SMB storage.'
				);
			}
			// Refuse a rootless path (no drive letter). Also fixes '/mnt/data' -> 'F:\mnt\data' defect.
			if (parsedRoot === '\\' || parsedRoot === '/') {
				throw new AppError(
					400,
					'Invalid Storage Destination path: Include a drive letter (e.g., "C:\\backups").'
				);
			}
		}

		// For local storage, we need a fully qualified absolute path.
		// Check *before* resolve() because resolve() always returns an absolute path
		// by prepending the server's CWD, which mangles paths for remote devices
		// (e.g., a Linux path "home/user" resolved on a Windows server becomes
		// "/JS/apps/.../backend/home/user" instead of "/home/user").
		if (!pathModule.isAbsolute(normalizedPath)) {
			throw new AppError(
				400,
				`Invalid Storage Destination path: An absolute path is required for local storage (e.g., "${isTargetWindows ? 'C:\\' : '/'}home/user/backups").`
			);
		}

		// When targeting a remote OS, use the target path module to avoid
		// the server's OS mangling the path (e.g., adding a Windows drive letter to a Linux path).
		const resolvedPath = pathModule.resolve(normalizedPath);
		return resolvedPath;
	} else {
		// For all remote/cloud storage types (s3, b2, etc.), the path must be relative
		// to the bucket root. A leading slash is invalid for an object key.
		// return normalizedPath.startsWith(path.sep) ? normalizedPath.substring(1) : normalizedPath;

		// For all remote storage types, we want a clean, relative, forward-slash path.
		// 1. Replace all backslashes with forward slashes
		let remotePath = trimmedPath.replace(/\\/g, '/');

		// 2. Remove any leading slashes
		if (remotePath.startsWith('/')) {
			remotePath = remotePath.substring(1);
		}

		// 3. Remove any trailing slashes
		if (remotePath.endsWith('/') && remotePath.length > 1) {
			remotePath = remotePath.slice(0, -1);
		}

		// 4. disallow any remaining ".." segments to prevent directory traversal in remote storage contexts
		if (remotePath.startsWith('..') || remotePath.includes('/../') || remotePath.endsWith('/..')) {
			throw new AppError(400, 'Invalid path: Directory traversal not allowed.');
		}

		return remotePath;
	}
}