Developer SDK

C++ examples

Install the SDK · View source on GitHub ↗

embed/state.hpp

c++
// Installation state for one embed installation, kept in one private
// directory named by URNETWORK_EMBED_STATE_DIR (EMBED_CONTRACT.md,
// "Installation state"):
//
//   client.jwt    the scoped client JWT: written by the token fetch, by the
//                 backend tool's provision or by the developer, and rewritten
//                 by the app whenever the sdk refreshes the token
//   instance-id   this installation's uuid, created on first run; it is also
//                 the installation ID the app sends to the token server
//   logs/         the sdk's bounded log files
//
// Every file is replaced atomically with owner-only permissions. On POSIX the
// directory and its files must not be accessible to group or others, and a
// symlinked file is refused; Windows relies on the access control of the
// user's profile directory. The file functions are the C++ provider
// example's.
#pragma once

#include <algorithm>
#include <cctype>
#include <cerrno>
#include <cstdint>
#include <cstdlib>
#include <cstring>
#include <filesystem>
#include <fstream>
#include <iterator>
#include <optional>
#include <random>
#include <stdexcept>
#include <string>
#include <string_view>
#include <system_error>
#include <utility>
#include <vector>

#include <nlohmann/json.hpp>

#ifdef _WIN32
#ifndef NOMINMAX
#define NOMINMAX
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>
#else
#include <fcntl.h>
#include <sys/stat.h>
#include <unistd.h>
#endif

namespace embed {

namespace fs = std::filesystem;

inline constexpr const char* clientJwtFileName = "client.jwt";
inline constexpr const char* instanceIdFileName = "instance-id";

// the largest state file the app reads
inline constexpr std::uintmax_t stateFileByteLimit = 64 * 1024;

// A configuration or credential problem that restarting does not fix (exit
// code 78).
class ConfigError : public std::runtime_error {
public:
    using std::runtime_error::runtime_error;
};

inline constexpr std::string_view standardAlphabet =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
inline constexpr std::string_view urlAlphabet =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

// Decodes standard base64 with padding, or with url the url alphabet without
// padding as jwt segments use it (trailing "=" are ignored there, as the Go
// reference trims them). Empty for any other text.
inline std::optional<std::vector<uint8_t>> base64Decode(std::string_view text, bool url) {
    std::string_view alphabet = url ? urlAlphabet : standardAlphabet;
    std::size_t symbolCount = text.size();
    if (url) {
        while (0 < symbolCount && text[symbolCount - 1] == '=') {
            symbolCount -= 1;
        }
        if (symbolCount % 4 == 1) {
            return std::nullopt;
        }
    } else {
        if (text.size() % 4 != 0) {
            return std::nullopt;
        }
        for (int padding = 0; padding < 2 && 0 < symbolCount && text[symbolCount - 1] == '='; padding += 1) {
            symbolCount -= 1;
        }
        if (symbolCount % 4 == 1) {
            return std::nullopt;
        }
    }
    std::vector<uint8_t> bytes;
    uint32_t group = 0;
    for (std::size_t i = 0; i < symbolCount; i += 1) {
        std::size_t value = alphabet.find(text[i]);
        if (value == std::string_view::npos) {
            return std::nullopt;
        }
        group = group << 6 | static_cast<uint32_t>(value);
        if (i % 4 == 3) {
            bytes.push_back(static_cast<uint8_t>(group >> 16));
            bytes.push_back(static_cast<uint8_t>(group >> 8));
            bytes.push_back(static_cast<uint8_t>(group));
            group = 0;
        }
    }
    // a partial group of 2 or 3 symbols carries 1 or 2 bytes
    if (symbolCount % 4 == 2) {
        bytes.push_back(static_cast<uint8_t>(group >> 4));
    } else if (symbolCount % 4 == 3) {
        bytes.push_back(static_cast<uint8_t>(group >> 10));
        bytes.push_back(static_cast<uint8_t>(group >> 2));
    }
    return bytes;
}

// Reads a uuid in its 8-4-4-4-12 hex form, in either case, into its canonical
// lowercase form.
inline std::optional<std::string> parseUuid(std::string_view text) {
    if (text.size() != 36) {
        return std::nullopt;
    }
    std::string uuid(text);
    for (std::size_t i = 0; i < uuid.size(); i += 1) {
        bool dash = i == 8 || i == 13 || i == 18 || i == 23;
        auto c = static_cast<unsigned char>(uuid[i]);
        if (dash ? c != '-' : !std::isxdigit(c)) {
            return std::nullopt;
        }
        uuid[i] = static_cast<char>(std::tolower(c));
    }
    return uuid;
}

// Random bytes from the system's random device.
inline std::vector<uint8_t> randomBytes(std::size_t count) {
    std::random_device random;
    std::vector<uint8_t> bytes(count);
    for (auto& byte : bytes) {
        byte = static_cast<uint8_t>(random() & 0xff);
    }
    return bytes;
}

// Lowercase hex of bytes.
inline std::string hexString(const std::vector<uint8_t>& bytes) {
    static constexpr char digits[] = "0123456789abcdef";
    std::string text;
    for (uint8_t byte : bytes) {
        text += digits[byte >> 4];
        text += digits[byte & 15];
    }
    return text;
}

// A new random (version 4) uuid.
inline std::string newUuid() {
    std::vector<uint8_t> bytes = randomBytes(16);
    bytes[6] = static_cast<uint8_t>((bytes[6] & 0x0f) | 0x40);
    bytes[8] = static_cast<uint8_t>((bytes[8] & 0x3f) | 0x80);
    std::string hex = hexString(bytes);
    return hex.substr(0, 8) + "-" + hex.substr(8, 4) + "-" + hex.substr(12, 4) + "-" + hex.substr(16, 4) + "-" +
        hex.substr(20);
}

// A path as the utf-8 text the sdk takes.
inline std::string utf8Path(const fs::path& path) {
#if defined(__cpp_char8_t)
    auto text = path.u8string();
    return std::string(text.begin(), text.end());
#else
    return path.u8string();
#endif
}

// The value of an environment variable; empty when it is not set. On Windows
// the wide value is converted to utf-8.
inline std::optional<std::string> environment(const char* name) {
#ifdef _WIN32
    std::wstring wideName(name, name + std::strlen(name));
    const wchar_t* value = _wgetenv(wideName.c_str());
    if (!value) {
        return std::nullopt;
    }
    return utf8Path(fs::path(value));
#else
    const char* value = std::getenv(name);
    if (!value) {
        return std::nullopt;
    }
    return std::string(value);
#endif
}

// Whether a file or directory is open to group or others. Windows relies on
// the access control of the user's profile directory.
inline bool sharedWithOthers(const fs::file_status& status) {
#ifdef _WIN32
    (void)status;
    return false;
#else
    return (status.permissions() & (fs::perms::group_all | fs::perms::others_all)) != fs::perms::none;
#endif
}

// The state directory must be an existing absolute directory, private to its
// owner on POSIX.
inline void checkStateDir(const fs::path& stateDir) {
    if (stateDir.empty()) {
        throw ConfigError("set URNETWORK_EMBED_STATE_DIR to this installation's private state directory");
    }
    if (!stateDir.is_absolute()) {
        throw ConfigError("URNETWORK_EMBED_STATE_DIR must be an absolute path");
    }
    std::error_code error;
    fs::file_status status = fs::status(stateDir, error);
    if (status.type() == fs::file_type::not_found) {
        throw ConfigError("state directory: " + std::make_error_code(std::errc::no_such_file_or_directory).message());
    }
    if (error) {
        throw ConfigError("state directory: " + error.message());
    }
    if (!fs::is_directory(status)) {
        throw ConfigError("URNETWORK_EMBED_STATE_DIR is not a directory");
    }
    if (sharedWithOthers(status)) {
        throw ConfigError("the state directory must be private to its owner (chmod 700)");
    }
}

// Reads a regular, private state file of bounded size; empty when the file
// does not exist. A symlink is refused so that the credential cannot be
// redirected to another file.
inline std::optional<std::string> readPrivateFile(const fs::path& path) {
    std::error_code error;
    fs::file_status status = fs::symlink_status(path, error);
    if (status.type() == fs::file_type::not_found) {
        return std::nullopt;
    }
    if (error) {
        throw std::runtime_error(error.message());
    }
    if (!fs::is_regular_file(status)) {
        throw std::runtime_error("not a regular file");
    }
    if (stateFileByteLimit < fs::file_size(path, error) || error) {
        throw std::runtime_error(error ? error.message() : "file is too large");
    }
    if (sharedWithOthers(status)) {
        throw std::runtime_error("file must be private to its owner (chmod 600)");
    }
    std::ifstream file(path, std::ios::binary);
    if (!file) {
        throw std::runtime_error("cannot open the file");
    }
    std::string data;
    data.resize(stateFileByteLimit + 1);
    file.read(data.data(), static_cast<std::streamsize>(data.size()));
    if (file.bad()) {
        throw std::runtime_error("cannot read the file");
    }
    data.resize(static_cast<std::size_t>(file.gcount()));
    if (stateFileByteLimit < data.size()) {
        throw std::runtime_error("file is too large");
    }
    return data;
}

// Replaces a state file atomically: a private temporary file in the same
// directory is written, synced and renamed over the old file.
inline void writePrivateFile(const fs::path& path, std::string_view data) {
#ifdef _WIN32
    fs::path tempPath = path.parent_path() / (L"." + path.filename().wstring() + L"." +
        fs::path(hexString(randomBytes(8))).wstring());
    HANDLE file = CreateFileW(tempPath.c_str(), GENERIC_WRITE, 0, nullptr, CREATE_NEW, FILE_ATTRIBUTE_NORMAL, nullptr);
    if (file == INVALID_HANDLE_VALUE) {
        throw std::system_error(static_cast<int>(GetLastError()), std::system_category());
    }
    // the first failure's code; ERROR_SUCCESS while every step succeeds
    DWORD code = ERROR_SUCCESS;
    for (std::size_t offset = 0; code == ERROR_SUCCESS && offset < data.size();) {
        DWORD count = 0;
        auto chunk = static_cast<DWORD>(std::min<std::size_t>(data.size() - offset, 1024 * 1024));
        if (!WriteFile(file, data.data() + offset, chunk, &count, nullptr)) {
            code = GetLastError();
        } else if (count == 0) {
            code = ERROR_WRITE_FAULT;
        }
        offset += count;
    }
    if (code == ERROR_SUCCESS && !FlushFileBuffers(file)) {
        code = GetLastError();
    }
    CloseHandle(file);
    if (code == ERROR_SUCCESS &&
        !MoveFileExW(tempPath.c_str(), path.c_str(), MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH)) {
        code = GetLastError();
    }
    if (code != ERROR_SUCCESS) {
        DeleteFileW(tempPath.c_str());
        throw std::system_error(static_cast<int>(code), std::system_category());
    }
#else
    std::string tempPath = (path.parent_path() / ("." + path.filename().string() + ".XXXXXX")).string();
    // mkstemp creates the file with mode 0600
    int fd = mkstemp(tempPath.data());
    if (fd < 0) {
        throw std::system_error(errno, std::generic_category());
    }
    bool written = fchmod(fd, 0600) == 0;
    for (std::size_t offset = 0; written && offset < data.size();) {
        ssize_t count = write(fd, data.data() + offset, data.size() - offset);
        if (count < 0 && errno == EINTR) {
            continue;
        }
        written = 0 < count;
        if (written) {
            offset += static_cast<std::size_t>(count);
        }
    }
    written = written && fsync(fd) == 0;
    int errorNumber = errno;
    if (close(fd) != 0 && written) {
        written = false;
        errorNumber = errno;
    }
    if (written && std::rename(tempPath.c_str(), path.c_str()) != 0) {
        written = false;
        errorNumber = errno;
    }
    if (!written) {
        unlink(tempPath.c_str());
        throw std::system_error(errorNumber, std::generic_category());
    }
#endif
}

// Creates a directory private to its owner; an existing one is kept.
inline void makePrivateDir(const fs::path& path) {
#ifdef _WIN32
    std::error_code error;
    fs::create_directory(path, error);
    if (error) {
        throw std::system_error(error);
    }
#else
    if (mkdir(path.c_str(), 0700) != 0 && errno != EEXIST) {
        throw std::system_error(errno, std::generic_category());
    }
#endif
}

// The client_id claim of a scoped client JWT, in canonical form. This checks
// the token's shape and claim only; the sdk and the server verify the token
// itself.
inline std::string parseClientJwtClientId(std::string_view clientJwt) {
    const char* notJwt = "client.jwt does not hold a JWT; obtain the scoped client JWT from your backend";
    // three non-empty parts separated by dots
    std::size_t firstDot = clientJwt.find('.');
    std::size_t secondDot = firstDot == std::string_view::npos ? firstDot : clientJwt.find('.', firstDot + 1);
    if (secondDot == std::string_view::npos || clientJwt.find('.', secondDot + 1) != std::string_view::npos ||
        firstDot == 0 || secondDot == firstDot + 1 || secondDot + 1 == clientJwt.size()) {
        throw ConfigError(notJwt);
    }
    auto payload = base64Decode(clientJwt.substr(firstDot + 1, secondDot - firstDot - 1), true);
    if (!payload) {
        throw ConfigError(notJwt);
    }
    auto claims = nlohmann::json::parse(payload->begin(), payload->end(), nullptr, false);
    auto claim = claims.is_object() ? claims.find("client_id") : claims.end();
    if (claim == claims.end() || !claim->is_string() || claim->get<std::string>().empty()) {
        throw ConfigError("client.jwt has no client_id claim; write a scoped client JWT, not a network JWT");
    }
    auto clientId = parseUuid(claim->get<std::string>());
    if (!clientId) {
        throw ConfigError("client.jwt has an invalid client_id claim");
    }
    return *clientId;
}

// The text without the whitespace around it.
inline std::string_view trimSpace(std::string_view text) {
    auto space = [](char c) { return std::isspace(static_cast<unsigned char>(c)) != 0; };
    while (!text.empty() && space(text.front())) {
        text.remove_prefix(1);
    }
    while (!text.empty() && space(text.back())) {
        text.remove_suffix(1);
    }
    return text;
}

// Reads instance-id, creating it on first run. An installation keeps one
// instance id for its lifetime.
inline std::string loadOrCreateInstanceId(const fs::path& stateDir) {
    fs::path path = stateDir / instanceIdFileName;
    std::optional<std::string> data;
    try {
        data = readPrivateFile(path);
    } catch (const std::exception& e) {
        throw ConfigError(std::string("read ") + instanceIdFileName + " from the state directory: " + e.what());
    }
    if (data) {
        auto instanceId = parseUuid(trimSpace(*data));
        if (!instanceId) {
            throw ConfigError(std::string(instanceIdFileName) + " does not hold a UUID");
        }
        return *instanceId;
    }
    std::string instanceId = newUuid();
    try {
        writePrivateFile(path, instanceId + "\n");
    } catch (const std::exception& e) {
        throw ConfigError(std::string("write ") + instanceIdFileName + ": " + e.what());
    }
    return instanceId;
}

// Reads client.jwt and its client_id claim: empty when the file is missing.
// A file that cannot be read, or holds no client JWT (a network JWT has no
// client_id claim), throws ConfigError. The token itself is never printed.
inline std::optional<std::pair<std::string, std::string>> loadClientJwt(const fs::path& stateDir) {
    std::optional<std::string> data;
    try {
        data = readPrivateFile(stateDir / clientJwtFileName);
    } catch (const std::exception& e) {
        throw ConfigError(std::string("read ") + clientJwtFileName + " from the state directory: " + e.what());
    }
    if (!data) {
        return std::nullopt;
    }
    std::string clientJwt(trimSpace(*data));
    if (clientJwt.find('\0') != std::string::npos) {
        throw ConfigError("client.jwt does not hold a JWT; obtain the scoped client JWT from your backend");
    }
    std::string clientId = parseClientJwtClientId(clientJwt);
    return std::make_pair(clientJwt, clientId);
}

// Replaces client.jwt atomically with the token and a line break.
inline void saveClientJwt(const fs::path& stateDir, const std::string& clientJwt) {
    writePrivateFile(stateDir / clientJwtFileName, clientJwt + "\n");
}

}  // namespace embed