PackPathGuard.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <QtCore/QDir>
#include <QtCore/QFileInfo>
#include <QtCore/QString>
#include <QtCore/QStringList>
 
#include <optional>
 
namespace PhosphorFsLoader {
 
enum class AbsolutePathPolicy {
    Reject,
    Trust,
};
 
[[nodiscard]] inline std::optional<QString> resolveWithinDirectory(const QString& declaredPath,
                                                                   const QString& directory, AbsolutePathPolicy policy)
{
    if (declaredPath.isEmpty() || directory.isEmpty()) {
        return std::nullopt;
    }
 
    const QDir dir(directory);
    const bool wasAbsolute = QFileInfo(declaredPath).isAbsolute();
    if (wasAbsolute && policy == AbsolutePathPolicy::Trust) {
        // Cleaned like every other accepted return, so a trusted override cannot
        // reach watch keys and path-keyed caches in two spellings of one file.
        return QDir::cleanPath(declaredPath);
    }
    // `absoluteFilePath`, not `filePath`: a RELATIVE @p directory would otherwise
    // yield a relative result, breaking both the documented return contract and
    // the cache-dedupe rationale.
    const QString resolved = wasAbsolute ? declaredPath : dir.absoluteFilePath(declaredPath);
 
    const QString lexicalRoot = QDir::cleanPath(dir.absolutePath());
    const QString canonicalRoot = QFileInfo(dir.absolutePath()).canonicalFilePath();
 
    // Canonicalise as much of the target as EXISTS, then re-append the rest.
    //
    // A plain `QFileInfo(resolved).canonicalFilePath()` returns empty for a path
    // whose leaf does not exist yet, and falling back to a purely lexical
    // compare there fails OPEN: `pack/link/future.frag`, where `link` is a
    // symlink out of the pack, is lexically inside and canonically outside, and
    // the leaf not existing is exactly the live-reload case (the watcher arms on
    // the path and the file materialises later). So walk up to the deepest
    // existing ancestor, canonicalise THAT, and rebuild — which resolves every
    // symlinked intermediate component even when the leaf is absent.
    //
    // The climb is PURE STRING WORK via `QFileInfo::absolutePath()`. It must not
    // use `QDir::cdUp()`: that is `cd("..")`, which FAILS on a parent that does
    // not exist, so it stops at the first missing component rather than at the
    // deepest existing ancestor. With two or more missing components below a
    // symlink (`pack/link/sub/future.frag`) the old loop bailed out to a lexical
    // path and handed it to a CANONICAL root comparison — the exact domain mixing
    // this function claims never to do, failing open on a real escape.
    //
    // Returns nullopt when NOTHING on the chain exists up to the filesystem root.
    // That case fails CLOSED rather than degrading to lexical, because a lexical
    // target compared against a canonical root is unsound in both directions.
    const auto canonicalise = [](const QString& path) -> std::optional<QString> {
        QString current = QDir::cleanPath(path);
        QStringList tail;
        // Bounded by the component count: each iteration strips exactly one, and
        // `absolutePath()` of the filesystem root is the root itself, which ends it.
        for (;;) {
            const QString canonical = QFileInfo(current).canonicalFilePath();
            if (!canonical.isEmpty()) {
                if (tail.isEmpty()) {
                    return canonical;
                }
                // Cleaned, so a deepest-existing-ancestor of "/" does not produce
                // a doubled separator.
                return QDir::cleanPath(canonical + QLatin1Char('/') + tail.join(QLatin1Char('/')));
            }
            const QFileInfo info(current);
            // PRESENT but unresolvable is NOT the same as absent, and conflating
            // them is an escape of exactly the kind this climb was rewritten to
            // close. `canonicalFilePath()` returns empty for a DANGLING symlink
            // just as it does for a missing component (a self-referential CYCLE
            // is different: Qt canonicalises it to itself, so a contained cycle
            // never reaches this branch and is accepted by the containment
            // check — see acceptsASymlinkCycleBecauseItStaysContained in the
            // tests). Without this the climb would treat a dangling link as
            // "not there yet", prepend its name, and
            // re-append it LEXICALLY onto the canonical root — mixing the two
            // domains this function promises never to mix. A pack shipping
            // `link -> /outside` while `/outside` does not exist yet would then be
            // accepted, and the stored path resolves out of the pack the moment the
            // target materialises. Nothing re-validates at that point either:
            // QFileSystemWatcher cannot watch a non-existent path, so the
            // materialisation fires no rescan.
            if (info.isSymLink()) {
                return std::nullopt;
            }
            const QString parent = info.absolutePath();
            const QString name = info.fileName();
            if (name.isEmpty() || parent.isEmpty() || parent == current) {
                return std::nullopt;
            }
            tail.prepend(name);
            current = parent;
        }
    };
 
    // Never mix domains: compare canonical against canonical, and only fall back
    // to lexical-vs-lexical when the ROOT itself cannot be canonicalised.
    const bool useCanonical = !canonicalRoot.isEmpty();
    QString target;
    if (useCanonical) {
        const auto canonicalTarget = canonicalise(resolved);
        if (!canonicalTarget) {
            return std::nullopt;
        }
        target = *canonicalTarget;
    } else {
        target = QDir::cleanPath(resolved);
    }
    const QString root = useCanonical ? canonicalRoot : lexicalRoot;
 
    // `root + '/'` unless root already ends in one, so a directory of "/" does
    // not become "//" and refuse everything.
    const QString prefix = root.endsWith(QLatin1Char('/')) ? root : root + QLatin1Char('/');
    if (target == root || !target.startsWith(prefix)) {
        return std::nullopt;
    }
    // The CLEANED form, so `./x.frag` and `sub//x.frag` do not reach watch keys,
    // content signatures and path-keyed caches as distinct strings for one file.
    return QDir::cleanPath(resolved);
}
 
} // namespace PhosphorFsLoader