Function safeResolvePath

src/security/sanitize.js:125–163

* Resolve a user-supplied path safely against `cwd`. * Returns { ok: true, fullPath, displayPath } on success, * or { ok: false, reason } on rejection. * * Rules: * - Resolved absolute path must be inside `cwd` (unless allowOutside=true) * - Path must not match a sensitive pattern * - P

(reqPath, cwd, options = {})

 *   - Path must not contain NUL bytes
 */
function safeResolvePath(reqPath, cwd, options = {}) {
  if (typeof reqPath !== 'string' || reqPath.length === 0) {
    return { ok: false, reason: 'path must be a non-empty string' };
  }
  if (reqPath.indexOf('\u0000') !== -1) {
    return { ok: false, reason: 'path contains NUL byte' };
  }
  // Expand ~ for the user's home directory only when explicitly allowed
  let candidate = reqPath;
  if (candidate === '~' || candidate.startsWith('~/') || candidate.startsWith('~\\')) {
    if (!options.allowHome) {
      return { ok: false, reason: 'home-relative paths are blocked' };
    }
    candidate = path.join(os.homedir(), candidate.slice(2));
  }
  // Strip leading ./ for normalization
  candidate = candidate.replace(/^\.[/\\]/, '');
  const fullPath = path.resolve(cwd, candidate);

  // Sensitive path check
  for (const re of SENSITIVE_PATH_RE) {
    if (re.test(fullPath)) {
      return { ok: false, reason: 'path is sensitive (auth credentials)' };
    }
  }

  // Containment check (default ON — opt out for tools that legitimately
  // need to read outside the project, like reading user's global config)
  if (!options.allowOutside) {
    const normCwd = path.resolve(cwd);
    const rel = path.relative(normCwd, fullPath);
    if (rel.startsWith('..') || path.isAbsolute(rel)) {
      return { ok: false, reason: 'path resolves outside project root' };
    }
  }

  const displayPath = path.relative(cwd, fullPath) || path.basename(fullPath);
  return { ok: true, fullPath, displayPath };
}

// ─── Shell escaping ─────────────────────────────────────────────────────────