@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-rt/lib/include/egress.h

@@ -0,0 +1,379 @@
+#pragma once
+
+#include <boost/asio/ip/address.hpp>
+#include <boost/asio/ip/tcp.hpp>
+#include <boost/system/error_code.hpp>
+
+#include <cstdint>
+#include <mutex>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace hkp
+{
+
+/**
+ * Where a board may make this server connect to.
+ *
+ * A board names destinations — an HTTP Client's URL, an asset, a model's base
+ * URL, a WebSocket to write to — and the server dials them. On a person's own
+ * machine that is the point; the desktop app's embedded runtime is never told
+ * otherwise. On a server several people's boards run on it is not: its
+ * loopback, its private network and a cloud provider's metadata endpoint
+ * (`169.254.169.254`, which hands out the instance's credentials) are reachable
+ * from here and are not a board's to reach.
+ *
+ * So a standalone server can be told it is hosted (`HKP_EGRESS=public`, read by
+ * standalone_config.h): a destination is reached only when every address its
+ * name resolves to is a public internet address.
+ *
+ * **Judged on what the resolver answers, which is what is connected to.**
+ * Every site that dials a board's destination resolves through `resolve` or
+ * `asyncResolve` here and connects to the endpoints they return, so there is
+ * no second lookup to answer differently; an address literal resolves to
+ * itself and is judged the same way. `tests/egress_sources.test.cpp` fails on
+ * a resolve anywhere else. Connections the operator configured — the
+ * coordinator link, the token issuer's keys — are not a board's destinations
+ * and are not judged here.
+ *
+ * The same rule, range for range, is in hkp-node (`src/egress.ts`) and
+ * hkp-python (`src/hkp/egress.py`).
+ */
+namespace egress
+{
+
+/** An address range: the address as bytes, and how many leading bits count. */
+struct Range
+{
+  std::vector<uint8_t> bytes;
+  int bits = 0;
+};
+
+struct Policy
+{
+  bool hosted = false;
+  /** Addresses and ranges reached anyway, as the operator listed them. */
+  std::vector<Range> allow;
+};
+
+inline bool toBytes(const std::string& text, std::vector<uint8_t>& out)
+{
+  std::string plain = text;
+  if (plain.size() >= 2 && plain.front() == '[' && plain.back() == ']')
+  {
+    plain = plain.substr(1, plain.size() - 2);
+  }
+  if (const auto zone = plain.find('%'); zone != std::string::npos)
+  {
+    plain.erase(zone);
+  }
+  boost::system::error_code ec;
+  const auto address = boost::asio::ip::make_address(plain, ec);
+  if (ec)
+  {
+    return false;
+  }
+  if (address.is_v4())
+  {
+    const auto bytes = address.to_v4().to_bytes();
+    out.assign(bytes.begin(), bytes.end());
+  }
+  else
+  {
+    const auto bytes = address.to_v6().to_bytes();
+    out.assign(bytes.begin(), bytes.end());
+  }
+  return true;
+}
+
+inline bool parseRange(const std::string& text, Range& out)
+{
+  const auto slash = text.find('/');
+  if (!toBytes(text.substr(0, slash), out.bytes))
+  {
+    return false;
+  }
+  const int width = static_cast<int>(out.bytes.size() * 8);
+  if (slash == std::string::npos)
+  {
+    out.bits = width;
+    return true;
+  }
+  try
+  {
+    size_t used = 0;
+    out.bits = std::stoi(text.substr(slash + 1), &used);
+    return used == text.size() - slash - 1 && out.bits >= 0 && out.bits <= width;
+  }
+  catch (const std::exception&)
+  {
+    return false;
+  }
+}
+
+inline Range range(const char* text)
+{
+  Range out;
+  if (!parseRange(text, out))
+  {
+    throw std::logic_error(std::string("Not an address or a range: ") + text);
+  }
+  return out;
+}
+
+inline bool inRange(const std::vector<uint8_t>& bytes, const Range& range)
+{
+  if (bytes.size() != range.bytes.size())
+  {
+    return false;
+  }
+  for (int bit = 0; bit < range.bits; ++bit)
+  {
+    const uint8_t mask = static_cast<uint8_t>(0x80 >> (bit & 7));
+    if ((bytes[bit >> 3] & mask) != (range.bytes[bit >> 3] & mask))
+    {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * What is not the public internet: this host, private networks, link-local
+ * (where the metadata endpoints are), shared address space, and what is not an
+ * address one connects to at all. `::/96` is the deprecated IPv4-compatible
+ * form (`::127.0.0.1`); `64:ff9b:1::/48` is a network's own NAT64 prefix, which
+ * may translate to private IPv4 and puts the IPv4 address where that network
+ * chose, so the whole range is refused rather than judged by what it carries.
+ */
+inline const std::vector<Range>& notPublic()
+{
+  static const std::vector<Range> ranges = {
+    range("0.0.0.0/8"),     range("127.0.0.0/8"),    range("10.0.0.0/8"),
+    range("172.16.0.0/12"), range("192.168.0.0/16"), range("100.64.0.0/10"),
+    range("169.254.0.0/16"), range("192.0.0.0/24"),  range("198.18.0.0/15"),
+    range("224.0.0.0/4"),   range("240.0.0.0/4"),    range("::/96"),
+    range("::1/128"),       range("fe80::/10"),      range("fc00::/7"),
+    range("ff00::/8"),      range("64:ff9b:1::/48"),
+  };
+  return ranges;
+}
+
+/** IPv6 forms that carry an IPv4 address, and where it sits. Such an address
+ *  is the IPv4 address inside it — `::ffff:127.0.0.1` is loopback. */
+inline const std::vector<std::pair<Range, size_t>>& carryIPv4()
+{
+  static const std::vector<std::pair<Range, size_t>> forms = {
+    {range("::ffff:0:0/96"), 12},
+    {range("64:ff9b::/96"), 12},
+    {range("2002::/16"), 2},
+  };
+  return forms;
+}
+
+inline bool isPublicBytes(const std::vector<uint8_t>& bytes)
+{
+  for (const auto& [form, at] : carryIPv4())
+  {
+    if (inRange(bytes, form))
+    {
+      return isPublicBytes(std::vector<uint8_t>(bytes.begin() + at, bytes.begin() + at + 4));
+    }
+  }
+  for (const auto& range : notPublic())
+  {
+    if (inRange(bytes, range))
+    {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Whether `text` is a public internet address. Not an address: false. */
+inline bool isPublicAddress(const std::string& text)
+{
+  std::vector<uint8_t> bytes;
+  return toBytes(text, bytes) && isPublicBytes(bytes);
+}
+
+/**
+ * The policy `HKP_EGRESS` and `HKP_EGRESS_ALLOW` state. An entry of the list
+ * that is not an address or a range is an error rather than skipped — an
+ * operator who meant to allow something should learn now that nothing was —
+ * and so is a name, which could be repointed once allowed.
+ */
+inline Policy readPolicy(const std::string& mode, const std::string& allow, std::string& error)
+{
+  Policy policy;
+  if (mode.empty() || mode == "open")
+  {
+    return policy;
+  }
+  if (mode != "public")
+  {
+    error = "HKP_EGRESS must be \"public\" or unset, not \"" + mode + "\"";
+    return policy;
+  }
+  policy.hosted = true;
+  size_t start = 0;
+  while (start <= allow.size())
+  {
+    const auto comma = allow.find(',', start);
+    std::string entry = allow.substr(start, comma == std::string::npos ? std::string::npos : comma - start);
+    const auto first = entry.find_first_not_of(" \t");
+    const auto last = entry.find_last_not_of(" \t");
+    entry = first == std::string::npos ? "" : entry.substr(first, last - first + 1);
+    if (!entry.empty())
+    {
+      Range parsed;
+      if (!parseRange(entry, parsed))
+      {
+        error = "HKP_EGRESS_ALLOW: \"" + entry +
+                "\" is not an address or a range (names are not accepted: an allowed name could be repointed)";
+        return Policy{};
+      }
+      policy.allow.push_back(parsed);
+    }
+    if (comma == std::string::npos)
+    {
+      break;
+    }
+    start = comma + 1;
+  }
+  return policy;
+}
+
+/** Whether a destination at address `text` may be reached under `policy`. */
+inline bool mayReach(const Policy& policy, const std::string& text)
+{
+  if (!policy.hosted)
+  {
+    return true;
+  }
+  std::vector<uint8_t> bytes;
+  if (!toBytes(text, bytes))
+  {
+    return false;
+  }
+  for (const auto& range : policy.allow)
+  {
+    if (inRange(bytes, range))
+    {
+      return true;
+    }
+  }
+  return isPublicBytes(bytes);
+}
+
+/** A destination this server will not connect to, and why. */
+class Refused : public std::runtime_error
+{
+public:
+  Refused(const std::string& host, const std::string& address)
+    : std::runtime_error(host == address
+                           ? "This server does not reach private addresses (" + address + ")"
+                           : "This server does not reach private addresses (" + host + " is " + address + ")")
+  {
+  }
+};
+
+/** The process's policy. Open until a standalone server is told otherwise. */
+inline Policy& activePolicy()
+{
+  static Policy policy;
+  return policy;
+}
+
+inline std::mutex& policyMutex()
+{
+  static std::mutex mutex;
+  return mutex;
+}
+
+inline void setPolicy(Policy policy)
+{
+  std::lock_guard lock{policyMutex()};
+  activePolicy() = std::move(policy);
+}
+
+inline Policy currentPolicy()
+{
+  std::lock_guard lock{policyMutex()};
+  return activePolicy();
+}
+
+/** Throws `Refused` when any endpoint `results` holds may not be reached. */
+template <class Results>
+void check(const std::string& host, const Results& results)
+{
+  const auto policy = currentPolicy();
+  if (!policy.hosted)
+  {
+    return;
+  }
+  for (const auto& entry : results)
+  {
+    const auto address = entry.endpoint().address().to_string();
+    if (!mayReach(policy, address))
+    {
+      throw Refused(host, address);
+    }
+  }
+}
+
+/** `resolver.resolve(host, port)`, refusing a destination that may not be
+ *  reached. Connect to what it returns. */
+inline boost::asio::ip::tcp::resolver::results_type resolve(boost::asio::ip::tcp::resolver& resolver,
+                                                            const std::string& host,
+                                                            const std::string& port)
+{
+  auto results = resolver.resolve(host, port);
+  check(host, results);
+  return results;
+}
+
+/** What an asynchronous refusal says, where only an error code travels. */
+inline const boost::system::error_category& category()
+{
+  struct Category : boost::system::error_category
+  {
+    const char* name() const noexcept override { return "hkp.egress"; }
+    std::string message(int) const override { return "This server does not reach private addresses"; }
+  };
+  static const Category instance;
+  return instance;
+}
+
+/** `resolver.async_resolve`, answering the handler with an `hkp.egress`
+ *  error and no endpoints for a destination that may not be reached. */
+template <class Handler>
+void asyncResolve(boost::asio::ip::tcp::resolver& resolver,
+                  const std::string& host,
+                  const std::string& port,
+                  Handler&& handler)
+{
+  resolver.async_resolve(
+    host, port,
+    [host, handler = std::forward<Handler>(handler)](const boost::system::error_code& ec,
+                                                     boost::asio::ip::tcp::resolver::results_type results) mutable {
+      if (!ec)
+      {
+        try
+        {
+          check(host, results);
+        }
+        catch (const Refused&)
+        {
+          handler(boost::system::error_code(1, category()), boost::asio::ip::tcp::resolver::results_type{});
+          return;
+        }
+      }
+      handler(ec, std::move(results));
+    });
+}
+
+} // namespace egress
+} // namespace hkp

package/bundle/hkp-rt/lib/include/files.h

@@ -0,0 +1,275 @@
+#pragma once
+
+#include <filesystem>
+#include <fstream>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <system_error>
+#include <utility>
+#include <vector>
+
+namespace hkp
+{
+
+/**
+ * Where a board may make this server read and write files.
+ *
+ * A board names paths — a Filesystem's file, a Monitor's log, a Cache's
+ * folder, a WAV to read — and the server opens them. Opened as given, that is
+ * the whole machine: the vault and settings beside the desktop app
+ * (`~/.hkp/vault.json`, `~/.hkp/settings.json`, which names the origins the
+ * runtime admits), a hosted server's mount secret and coordinator tickets,
+ * `/proc/self/environ`. A board is something somebody else may have written,
+ * so a path it names is reached only when it lies inside a **folder** this
+ * server was given:
+ *
+ * - the first folder is the default: a relative path is taken from it, which
+ *   is what lets a board say `"recordings"` and mean the same thing on every
+ *   machine — a standalone server's `HKP_FILES_DIR`, the desktop app's
+ *   `~/.hkp/cpp/files`;
+ * - the others are what the person or the operator added
+ *   (`HKP_FILES_ALLOW`, the desktop's settings), named by absolute path.
+ *
+ * With no folders nothing is reached — what a host that says nothing gets,
+ * the mobile apps among them.
+ *
+ * **Judged on what the path is, not on how it is spelled.** A path is made
+ * canonical before it is compared — `..` taken out, every symlink that exists
+ * followed — so neither leads outside. A name a service received as data (the
+ * file inside a configured folder, a cache entry's file name) is taken inside
+ * that folder whatever it says, absolute or not: data never chooses the
+ * folder. What a check cannot see is a symlink planted between the check and
+ * the open; nothing a board can drive creates one, and a folder should hold
+ * nothing but what boards may have.
+ *
+ * Services open what `resolve` and `resolveIn` return, through `input`,
+ * `output` and `list`; `tests/files_sources.test.cpp` fails on a file opened
+ * anywhere else. hkp-rt has one tenant, so everyone a hosted server admits
+ * shares its folders. Paths the operator names — a runtime config, plugins,
+ * the coordinator tickets — are not a board's and are not judged here.
+ */
+namespace files
+{
+
+class Path;
+inline std::optional<Path> resolve(const std::string& text, std::string& problem);
+inline std::optional<Path> resolveIn(const Path& folder, const std::string& name, std::string& problem);
+
+/** A path a board named, inside one of the folders. Only `resolve` and
+ *  `resolveIn` make one. */
+class Path
+{
+public:
+  const std::filesystem::path& path() const { return m_path; }
+  std::string string() const { return m_path.string(); }
+
+private:
+  explicit Path(std::filesystem::path path) : m_path(std::move(path)) {}
+  std::filesystem::path m_path;
+
+  friend std::optional<Path> resolve(const std::string& text, std::string& problem);
+  friend std::optional<Path> resolveIn(const Path& folder, const std::string& name, std::string& problem);
+};
+
+/** The folders, as given. Read through `setFolders`, which makes them canonical. */
+inline std::vector<std::filesystem::path>& activeFolders()
+{
+  static std::vector<std::filesystem::path> folders;
+  return folders;
+}
+
+inline std::mutex& foldersMutex()
+{
+  static std::mutex mutex;
+  return mutex;
+}
+
+/** Gives boards these folders, the first being the default. Replaces what was
+ *  given before; an empty list gives them none. */
+inline void setFolders(const std::vector<std::filesystem::path>& folders)
+{
+  std::vector<std::filesystem::path> canonical;
+  for (const auto& folder : folders)
+  {
+    if (folder.empty() || !folder.is_absolute())
+    {
+      continue;
+    }
+    std::error_code ec;
+    auto resolved = std::filesystem::weakly_canonical(folder, ec);
+    if (!ec)
+    {
+      canonical.push_back(std::move(resolved));
+    }
+  }
+  std::lock_guard lock{foldersMutex()};
+  activeFolders() = std::move(canonical);
+}
+
+inline std::vector<std::filesystem::path> folders()
+{
+  std::lock_guard lock{foldersMutex()};
+  return activeFolders();
+}
+
+/** Whether `candidate` is `folder` or lies beneath it. Both canonical. */
+inline bool isInside(const std::filesystem::path& candidate, const std::filesystem::path& folder)
+{
+  const auto rel = candidate.lexically_relative(folder);
+  return !rel.empty() && *rel.begin() != "..";
+}
+
+/**
+ * The file or folder `text` names, when it lies inside one of the folders; a
+ * relative path is taken from the first. Otherwise nothing, and `problem`
+ * says why.
+ */
+inline std::optional<Path> resolve(const std::string& text, std::string& problem)
+{
+  const auto given = folders();
+  if (given.empty())
+  {
+    problem = "This server gives boards no folder to use (" + text + ")";
+    return std::nullopt;
+  }
+  if (text.empty())
+  {
+    problem = "No path given";
+    return std::nullopt;
+  }
+  std::filesystem::path named(text);
+  if (!named.is_absolute())
+  {
+    if (named.has_root_path())
+    {
+      // `C:file` or `\file` on Windows: neither relative nor absolute.
+      problem = text + " is not a path this server takes";
+      return std::nullopt;
+    }
+    named = given.front() / named;
+  }
+  std::error_code ec;
+  auto candidate = std::filesystem::weakly_canonical(named, ec);
+  if (ec)
+  {
+    problem = text + " cannot be resolved: " + ec.message();
+    return std::nullopt;
+  }
+  for (const auto& folder : given)
+  {
+    if (isInside(candidate, folder))
+    {
+      return Path(std::move(candidate));
+    }
+  }
+  problem = text + " is outside the folders this server gives boards";
+  return std::nullopt;
+}
+
+/**
+ * `name` taken inside `folder`, never outside it: a name a service received as
+ * data rather than from its configuration. Absolute or not, it is read as
+ * relative to `folder`.
+ */
+inline std::optional<Path> resolveIn(const Path& folder, const std::string& name, std::string& problem)
+{
+  const auto relative = std::filesystem::path(name).relative_path();
+  std::error_code ec;
+  auto candidate = std::filesystem::weakly_canonical(folder.path() / relative, ec);
+  if (ec)
+  {
+    problem = name + " cannot be resolved: " + ec.message();
+    return std::nullopt;
+  }
+  if (!isInside(candidate, folder.path()))
+  {
+    problem = name + " is outside " + folder.string();
+    return std::nullopt;
+  }
+  return Path(std::move(candidate));
+}
+
+/** `path` opened for reading. */
+inline std::ifstream input(const Path& path, std::ios::openmode mode = std::ios::binary)
+{
+  return std::ifstream(path.path(), std::ios::in | mode);
+}
+
+/** `path` opened for writing; `std::ios::app` appends. The folders it is
+ *  written into are made when missing — they lie inside the same folder. */
+inline std::ofstream output(const Path& path, std::ios::openmode mode = std::ios::binary)
+{
+  std::error_code ec;
+  std::filesystem::create_directories(path.path().parent_path(), ec);
+  return std::ofstream(path.path(), std::ios::out | mode);
+}
+
+/** The names in the folder `path`; empty when it is not one. */
+inline std::vector<std::string> list(const Path& path)
+{
+  std::vector<std::string> names;
+  std::error_code ec;
+  for (std::filesystem::directory_iterator it(path.path(), ec), end; !ec && it != end; it.increment(ec))
+  {
+    names.push_back(it->path().filename().string());
+  }
+  return names;
+}
+
+/** Whether `path` names a file or folder that exists. */
+inline bool exists(const Path& path)
+{
+  std::error_code ec;
+  return std::filesystem::exists(path.path(), ec);
+}
+
+/** Whether `path` names a folder. */
+inline bool isFolder(const Path& path)
+{
+  std::error_code ec;
+  return std::filesystem::is_directory(path.path(), ec);
+}
+
+/**
+ * The folders a list names, separated as `PATH` is (`:`, or `;` on Windows).
+ * An entry that is not absolute is an error rather than skipped — an operator
+ * who meant to give a folder should learn now that none was given.
+ */
+inline std::vector<std::filesystem::path> readFolderList(const std::string& list, const std::string& name,
+                                                         std::string& error)
+{
+#if defined(_WIN32)
+  constexpr char separator = ';';
+#else
+  constexpr char separator = ':';
+#endif
+  std::vector<std::filesystem::path> out;
+  size_t start = 0;
+  while (start <= list.size())
+  {
+    const auto end = list.find(separator, start);
+    std::string entry = list.substr(start, end == std::string::npos ? std::string::npos : end - start);
+    const auto first = entry.find_first_not_of(" \t");
+    const auto last = entry.find_last_not_of(" \t");
+    entry = first == std::string::npos ? "" : entry.substr(first, last - first + 1);
+    if (!entry.empty())
+    {
+      if (!std::filesystem::path(entry).is_absolute())
+      {
+        error = name + ": \"" + entry + "\" is not an absolute path";
+        return {};
+      }
+      out.emplace_back(entry);
+    }
+    if (end == std::string::npos)
+    {
+      break;
+    }
+    start = end + 1;
+  }
+  return out;
+}
+
+} // namespace files
+} // namespace hkp