botrun-horse 2.29.2 → 2.30.0

package/botrun-c/.claude/skills/GitHub/346/212/200/350/203/275/scripts/lib/path-validator.mjs

@@ -0,0 +1,167 @@
+/**
+ * GitHub 技能路徑驗證工具
+ *
+ * 安全設計：
+ * - 嚴格限制只能存取 /tmp/{userId}/github/ 目錄
+ * - 四層防護：userId 格式、owner/repo 格式、路徑正規化、路徑遍歷檢測
+ *
+ * 路徑格式：
+ * /tmp/{userId}/github/{owner}/{repo}/
+ */
+
+import { resolve, join, normalize } from 'node:path';
+
+/**
+ * 驗證 userId 格式
+ * 只允許英數字（Firebase User ID 格式）
+ */
+export function validateUserId(userId) {
+  if (!userId || typeof userId !== 'string') {
+    throw new Error('userId is required');
+  }
+
+  // Firebase User ID 只包含英數字
+  if (!/^[a-zA-Z0-9]+$/.test(userId)) {
+    throw new Error(`Invalid userId format: ${userId}`);
+  }
+
+  return userId;
+}
+
+/**
+ * 驗證 owner 格式
+ * GitHub owner 允許英數字、底線、連字號、點
+ */
+export function validateOwner(owner) {
+  if (!owner || typeof owner !== 'string') {
+    throw new Error('owner is required');
+  }
+
+  if (!/^[a-zA-Z0-9_.-]+$/.test(owner)) {
+    throw new Error(`Invalid owner format: ${owner}`);
+  }
+
+  return owner;
+}
+
+/**
+ * 驗證 repo 格式
+ * GitHub repo 允許英數字、底線、連字號、點
+ */
+export function validateRepo(repo) {
+  if (!repo || typeof repo !== 'string') {
+    throw new Error('repo is required');
+  }
+
+  if (!/^[a-zA-Z0-9_.-]+$/.test(repo)) {
+    throw new Error(`Invalid repo format: ${repo}`);
+  }
+
+  return repo;
+}
+
+/**
+ * 取得用戶的 GitHub 基礎路徑
+ * @returns /tmp/{userId}/github/
+ */
+export function getGitHubBasePath(userId) {
+  validateUserId(userId);
+  return `/tmp/${userId}/github`;
+}
+
+/**
+ * 取得 repo 的完整路徑
+ * @param repoFullName - 格式為 "owner/repo"
+ * @returns /tmp/{userId}/github/{owner}/{repo}
+ */
+export function getRepoPath(userId, repoFullName) {
+  validateUserId(userId);
+
+  if (!repoFullName || typeof repoFullName !== 'string') {
+    throw new Error('repoFullName is required');
+  }
+
+  const parts = repoFullName.split('/');
+  if (parts.length !== 2) {
+    throw new Error(`Invalid repo format. Expected: owner/repo, got: ${repoFullName}`);
+  }
+
+  const [owner, repo] = parts;
+  validateOwner(owner);
+  validateRepo(repo);
+
+  const basePath = getGitHubBasePath(userId);
+  return join(basePath, owner, repo);
+}
+
+/**
+ * 驗證路徑是否在允許範圍內
+ * 防止路徑遍歷攻擊
+ */
+export function validatePath(userId, requestedPath) {
+  validateUserId(userId);
+
+  const basePath = getGitHubBasePath(userId);
+
+  // 正規化路徑（處理 ../ 等）
+  const normalizedPath = resolve(requestedPath);
+
+  // 檢查是否在允許範圍內
+  if (!normalizedPath.startsWith(basePath)) {
+    throw new Error(`Access denied: ${requestedPath} is outside allowed path ${basePath}`);
+  }
+
+  // 額外檢查：原始路徑不應包含 ..
+  if (requestedPath.includes('..')) {
+    throw new Error(`Path traversal detected: ${requestedPath}`);
+  }
+
+  return normalizedPath;
+}
+
+/**
+ * 安全地解析 repo 內的檔案路徑
+ * @param repoFullName - 格式為 "owner/repo"
+ * @param filePath - repo 內的相對路徑
+ * @returns 完整的安全路徑
+ */
+export function resolveFilePath(userId, repoFullName, filePath) {
+  const repoPath = getRepoPath(userId, repoFullName);
+
+  // 正規化檔案路徑
+  const normalizedFile = normalize(filePath).replace(/^\//, '');
+
+  // 檢查路徑遍歷
+  if (normalizedFile.includes('..') || normalizedFile.startsWith('/')) {
+    throw new Error(`Path traversal detected: ${filePath}`);
+  }
+
+  const fullPath = join(repoPath, normalizedFile);
+
+  // 再次驗證最終路徑在 repo 範圍內
+  if (!fullPath.startsWith(repoPath)) {
+    throw new Error(`Path traversal detected: ${filePath}`);
+  }
+
+  return { repoPath, fullPath, relativePath: normalizedFile };
+}
+
+/**
+ * 從目錄名稱解析 repo 全名
+ * @param dirName - 目錄結構 {owner}/{repo}
+ * @returns owner/repo
+ */
+export function parseRepoFromPath(basePath, fullPath) {
+  if (!fullPath.startsWith(basePath)) {
+    throw new Error('Invalid path');
+  }
+
+  const relativePath = fullPath.slice(basePath.length + 1);
+  const parts = relativePath.split('/');
+
+  if (parts.length >= 2) {
+    return `${parts[0]}/${parts[1]}`;
+  }
+
+  throw new Error('Could not parse repo from path');
+}