(
projectRoot: string,
filePath: string,
options?: { allowSymlinkEscape?: boolean; readOnly?: boolean }
)
| 187 | * path under a root that does not exist is null. |
| 188 | */ |
| 189 | export function validatePathWithinRoot( |
| 190 | projectRoot: string, |
| 191 | filePath: string, |
| 192 | options?: { allowSymlinkEscape?: boolean; readOnly?: boolean } |
| 193 | ): string | null { |
| 194 | // 1. Lexical containment — cheap, catches `../` traversal. Applies even on |
| 195 | // the indexing read path: a crafted `../` escape is still rejected. |
| 196 | const resolved = lexicalPathWithinRoot(projectRoot, filePath); |
| 197 | if (resolved === null) { |
| 198 | return null; |
| 199 | } |
| 200 | const normalizedRoot = path.resolve(projectRoot); |
| 201 | |
| 202 | // 2. Symlink-aware containment — resolve symlinks on both sides and re-check, |
| 203 | // so an in-repo symlink whose real target escapes the root is rejected. |
| 204 | // The indexing read path (allowSymlinkEscape) skips only this rejection so |
| 205 | // it stays consistent with the directory walk, which already followed the |
| 206 | // in-root symlink to enumerate these files (#935). |
| 207 | let realRoot: string; |
| 208 | try { |
| 209 | realRoot = fs.realpathSync(normalizedRoot); |
| 210 | } catch { |
| 211 | return null; |
| 212 | } |
| 213 | |
| 214 | try { |
| 215 | const realResolved = fs.realpathSync(resolved); |
| 216 | if (options?.allowSymlinkEscape) { |
| 217 | return realResolved; |
| 218 | } |
| 219 | return isWithinDir(realResolved, realRoot) ? realResolved : null; |
| 220 | } catch (err) { |
| 221 | // A path under a file (ENOTDIR on POSIX) is a missing leaf too. |
| 222 | if (!isMissingPathError(err)) return null; |
| 223 | } |
| 224 | |
| 225 | // Nothing to read, and with the root in place the indexing read path takes |
| 226 | // whatever ancestor a walk would find, so neither needs one. |
| 227 | if (options?.readOnly || options?.allowSymlinkEscape) return resolved; |
| 228 | |
| 229 | // A missing leaf may still sit below an EXISTING symlink. Resolve the |
| 230 | // nearest existing ancestor before allowing a write path: otherwise |
| 231 | // `project/.codegraph/ui -> /outside` plus a missing `trails/` directory |
| 232 | // passes the lexical check and mkdir follows the symlink out of the root. |
| 233 | let ancestor = path.dirname(resolved); |
| 234 | while (isWithinDir(ancestor, normalizedRoot)) { |
| 235 | try { |
| 236 | const realAncestor = fs.realpathSync(ancestor); |
| 237 | return isWithinDir(realAncestor, realRoot) ? resolved : null; |
| 238 | } catch (err) { |
| 239 | if (!isMissingPathError(err)) return null; |
| 240 | const parent = path.dirname(ancestor); |
| 241 | if (parent === ancestor) return null; |
| 242 | ancestor = parent; |
| 243 | } |
| 244 | } |
| 245 | return null; |
| 246 | } |
no test coverage detected