remote_update_fetch.hpp

Go to the documentation of this file.

#pragma once
 
// Opt-in remote UX update fetch — the network layer over evaluate_remote_ux_update.
//
// Default OFF. When a developer opts in, this fetches a signed UX pack over HTTPS,
// hands the raw bytes to the pure fail-closed gate (remote_update.hpp), and — only
// if the gate accepts — installs it content-addressed (pack_install.hpp), so the
// loader reads immutable, re-verified files. The signature is the trust anchor: a
// hostile or MITM'd host still cannot forge a signed pack.
//
// Two deliberate design properties the owner asked for:
//
//   * Offline is a FIRST-CLASS outcome, never an error. An unreachable host, a
//     timeout, or a non-2xx response yields RemoteFetchStatus::Unavailable — the
//     caller simply keeps its current UI. Nothing here blocks or throws, so a dead
//     network never stalls the plugin. A developer may supply an offline_fallback
//     pack so the plugin still looks like THEIRS with no network.
//
//   * Everything is customizable. The transport is an injected `fetcher` callable,
//     so any delivery "style" works — a CDN, an object store, a private server with
//     custom auth. `make_http_pack_fetcher()` is a convenience default over
//     runtime::http_*; override it freely.
//
// Privacy: an update check sends ONLY what the server needs to choose the right pack
// — plugin id, channel, installed version — over HTTPS. No device id, no user id, no
// telemetry. `build_update_check_url()` is pure so that contract is testable.
 
#include <pulp/format/reload/pack_install.hpp>
#include <pulp/format/reload/remote_update.hpp>
#include <pulp/format/reload/revocation.hpp>
#include <pulp/format/reload/swap_pack.hpp>
#include <pulp/runtime/http.hpp>
#include <pulp/runtime/safe_relative_path.hpp>
#include <pulp/view/reload_capabilities.hpp>
 
#include <cstdint>
#include <filesystem>
#include <functional>
#include <string>
#include <vector>
 
namespace pulp::format::reload {
 
enum class RemoteFetchStatus {
    Disabled,     
    Applied,      
    UpToDate,     
    Rejected,     
    Unavailable,  
};
 
struct RemoteFetchResult {
    RemoteFetchStatus status = RemoteFetchStatus::Disabled;
    RemoteUpdateResult decision;              
    std::filesystem::path installed_root;     
    std::string detail;
    bool applied() const { return status == RemoteFetchStatus::Applied; }
};

struct FetchedPack {
    bool reachable = false;
    std::string manifest_json;         
    std::filesystem::path local_root;  
    std::string detail;
};

inline std::string url_query_escape(std::string_view s) {
    static const char* hex = "0123456789ABCDEF";
    std::string out;
    out.reserve(s.size());
    for (unsigned char c : s) {
        const bool unreserved = (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') ||
                                (c >= '0' && c <= '9') || c == '-' || c == '_' ||
                                c == '.' || c == '~';
        if (unreserved) {
            out.push_back(static_cast<char>(c));
        } else {
            out.push_back('%');
            out.push_back(hex[c >> 4]);
            out.push_back(hex[c & 0xF]);
        }
    }
    return out;
}

inline std::string build_update_check_url(const std::string& base_url,
                                          const std::string& plugin_id,
                                          const std::string& channel,
                                          std::uint64_t installed_version) {
    const char sep = (base_url.find('?') == std::string::npos) ? '?' : '&';
    return base_url + sep + "plugin=" + url_query_escape(plugin_id) +
           "&channel=" + url_query_escape(channel) +
           "&installed=" + std::to_string(installed_version);
}

inline bool is_safe_pack_member_path(const std::string& p) {
    return runtime::is_safe_relative_path(std::filesystem::path(p));
}
 
struct RemoteUpdateConfig {
    bool enabled = false;                          
    std::string base_url;                          
    std::string plugin_id;
    std::string channel = "stable";
    std::vector<std::uint8_t> trusted_public_key;  
    std::uint64_t installed_pack_version = 0;
    view::CapabilitySet host_granted;              
    std::filesystem::path install_base;            
    std::filesystem::path offline_fallback_root;
    std::function<FetchedPack(const std::string& url)> fetcher;
};

inline RemoteFetchResult check_and_fetch_remote_ux_update(const RemoteUpdateConfig& cfg,
                                                          bool srl_fresh,
                                                          const SignedRevocationList* srl) {
    if (!cfg.enabled)
        return {RemoteFetchStatus::Disabled, {}, {}, "remote update disabled (opt-in)"};
 
    auto offline = [&](std::string why) {
        RemoteFetchResult r{RemoteFetchStatus::Unavailable, {}, {}, std::move(why)};
        if (!cfg.offline_fallback_root.empty()) {
            r.installed_root = cfg.offline_fallback_root;
            r.detail += " — using offline fallback pack";
        }
        return r;
    };
 
    // Plaintext update channels are not allowed — the signature is the trust anchor,
    // but HTTPS still protects the request's privacy + prevents trivial tampering.
    if (cfg.base_url.rfind("https://", 0) != 0)
        return offline("remote update requires an https:// endpoint");
    if (!cfg.fetcher) return offline("no fetcher configured");
 
    const std::string url =
        build_update_check_url(cfg.base_url, cfg.plugin_id, cfg.channel, cfg.installed_pack_version);
    const FetchedPack fetched = cfg.fetcher(url);
    if (!fetched.reachable) return offline("offline: " + fetched.detail);
 
    std::string err;
    auto manifest = parse_swap_pack_manifest(fetched.manifest_json, err);
    if (!manifest)
        return {RemoteFetchStatus::Rejected,
                {RemoteUpdateVerdict::RejectSignature, "malformed manifest: " + err},
                {}, "malformed manifest: " + err};
 
    const auto decision =
        evaluate_remote_ux_update(fetched.local_root, *manifest, cfg.trusted_public_key,
                                  cfg.installed_pack_version, cfg.host_granted, srl_fresh, srl);
    if (!decision.ok()) {
        // A server offering an equal/older version is benign "nothing newer" — not a
        // security event. Everything else is a real rejection to surface loudly.
        const bool benign = decision.verdict == RemoteUpdateVerdict::RejectDowngrade;
        return {benign ? RemoteFetchStatus::UpToDate : RemoteFetchStatus::Rejected,
                decision, {}, decision.detail};
    }
 
    // Accepted: install content-addressed — this re-verifies the exact bytes at the
    // destination, so the loader never reads anything the gate did not clear.
    const auto inst = install_verified_pack(fetched.local_root, *manifest,
                                            cfg.trusted_public_key, cfg.install_base);
    if (!inst.ok())
        return {RemoteFetchStatus::Rejected, decision, {}, "install failed: " + inst.detail};
    return {RemoteFetchStatus::Applied, decision, inst.installed_root, "applied"};
}

inline std::function<FetchedPack(const std::string&)> make_http_pack_fetcher(
    std::string files_base_url, std::filesystem::path download_dir, int timeout_seconds = 20) {
    return [files_base_url = std::move(files_base_url),
            download_dir = std::move(download_dir), timeout_seconds](const std::string& url) {
        FetchedPack out;
        const auto manifest_resp = runtime::http_get(url, timeout_seconds);
        if (!manifest_resp.ok()) {
            out.detail = manifest_resp.error.empty()
                             ? ("HTTP " + std::to_string(manifest_resp.status_code))
                             : manifest_resp.error;
            return out;  // reachable stays false → Unavailable
        }
        std::string err;
        auto manifest = parse_swap_pack_manifest(manifest_resp.body, err);
        if (!manifest) {
            // Reachable, but the manifest is unusable — let the orchestrator reject it
            // (a served-but-malformed manifest is a server problem, not offline).
            out.reachable = true;
            out.manifest_json = manifest_resp.body;
            return out;
        }
        std::error_code ec;
        std::filesystem::create_directories(download_dir, ec);
        for (const auto& f : manifest->files) {
            // The manifest is the UNTRUSTED server's word (the signature is checked
            // later, by the gate). A hostile `path` must never let this write outside
            // download_dir, so screen it BEFORE opening a destination.
            // (install_verified_pack re-checks at publish time; this guards the
            // download write itself.)
            if (!is_safe_pack_member_path(f.path)) {
                out.detail = "unsafe manifest path rejected: " + f.path;
                return out;  // fail closed — treat as unavailable, write nothing
            }
            const std::filesystem::path dest = download_dir / f.path;
            if (!runtime::is_within_directory(download_dir, dest)) {
                out.detail = "unsafe manifest path rejected: " + f.path;
                return out;
            }
            std::filesystem::create_directories(dest.parent_path(), ec);
            if (!runtime::http_download(files_base_url + "/" + f.path, dest.string(),
                                        timeout_seconds)) {
                out.detail = "download failed: " + f.path;
                return out;  // partial fetch → treat as offline/unavailable
            }
        }
        out.reachable = true;
        out.manifest_json = manifest_resp.body;
        out.local_root = download_dir;
        return out;
    };
}
 
}  // namespace pulp::format::reload