@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,201 @@
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <list>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <vector>
+#include <chrono>
+
+#include <boost/asio.hpp>
+
+#include "./registry.h"
+#include <types/types.h>
+#include <types/validation.h>
+#include <types/message.h>
+#include <log_entry.h>
+
+namespace hkp 
+{
+
+class Service;
+class Runtime;
+class Server;
+struct ProcessContext;
+struct Caller;
+
+class App
+{
+public:
+  App();
+  ~App();
+
+  // A runtime id is unique within a space, and there are two kinds. What a
+  // client creates over the api shares one space, the empty one. What a
+  // coordinator builds for a board gets a space per board
+  // (`RuntimeConfiguration::space`), so two boards that both call a runtime
+  // `cpp` each keep their own, and neither is replaced by a client creating a
+  // runtime of that id.
+  //
+  // Everything below that names a runtime means the one in the api's space
+  // unless it is given another.
+  RuntimeConfiguration createRuntime(json config);
+  RuntimeConfiguration createRuntime(RuntimeConfiguration config);
+
+  std::vector<RuntimeConfiguration> getRuntimes(const std::string& space = "") const;
+  std::optional<RuntimeConfiguration> getRuntime(const std::string runtimeId,
+                                                 const std::string& space = "") const;
+
+  bool removeRuntime(const std::string &id, const std::string& space = "");
+  // Removes what is in the api's space; a board's runtimes are its
+  // coordinator's to remove.
+  void removeAllRuntimes();
+
+  json configureService(const std::string &runtimeId, const std::string &instanceId, json config,
+                        const std::string& space = "", const ProcessContext* context = nullptr);
+  json getServiceState(const std::string &runtimeId, const std::string &instanceId) const;
+  json getServices(const std::string &runtimeId, const std::string& space = "") const;
+  json appendService(const std::string& runtimeId, const ServiceConfiguration& service);
+  json removeService(const std::string& runtimeId, const std::string& instanceId);
+  Data processRuntime(const std::string& runtimeId, const Data& data);
+  // The same, as part of a run somebody else began: `context` is what a peer
+  // sent (`runId`, `parentRunId`, `requestId`), and anything it leaves out is
+  // filled in. See ProcessContext::fromJson.
+  Data processRuntime(const std::string& runtimeId, const Data& data, const json& context,
+                      const std::string& space = "");
+  // The same, as a run whose context has already been established — by a
+  // route that knows who is calling, or a link that was told. Whoever builds
+  // the context decides what of it to believe; see ProcessContext.
+  Data processRuntimeAs(const std::string& runtimeId, const Data& data,
+                        const ProcessContext& context, const std::string& space = "");
+  // Runs a runtime's pipeline starting at one service; see Runtime::processAt.
+  // Throws std::runtime_error when the runtime holds no such service.
+  Data processServiceAt(const std::string& runtimeId,
+                        const std::string& instanceId, const Data& data);
+  // The same, as a run whose context has already been established.
+  Data processServiceAtAs(const std::string& runtimeId, const std::string& instanceId,
+                          const Data& data, const ProcessContext& context,
+                          const std::string& space = "");
+  // Whether a runtime holds the service an address names.
+  bool hasService(const std::string& runtimeId, const std::string& instanceId,
+                  const std::string& space = "") const;
+  json getRegistry() const;
+
+  json rearrangeServices(const std::string& runtimeId, const std::vector<std::string>& newOrder);
+
+  // Hand a running runtime values for the references its services hold.
+  //
+  // Answers with the aliases it then holds, and null when there is no such
+  // runtime. Naming them is all that can be asked: there is no route from here
+  // back to a value.
+  json setRuntimeSecrets(const std::string& runtimeId,
+                         const std::map<std::string, SecretEntry>& entries);
+
+  // Hand a running runtime asset descriptors, or null for one deleted. Answers
+  // with the ids it then holds, and null when there is no such runtime.
+  json setRuntimeAssets(const std::string& runtimeId,
+                        const std::map<std::string, nlohmann::json>& entries);
+
+  // Whether an asset resolves on a runtime, and to what — a check, never the
+  // content. Null when there is no such runtime.
+  json checkRuntimeAsset(const std::string& runtimeId, const std::string& assetId);
+
+  // Changes what a running runtime records — `logging`, `logLevel`, `logData`
+  // — without rebuilding it. A field left out is left as it was.
+  //
+  // Answers with the settings the runtime then has, and null when there is no
+  // such runtime.
+  json setRuntimeState(const std::string& runtimeId, const json& state,
+                       const std::string& space = "");
+
+  // Where a runtime's output also goes, beside the clients watching it.
+  //
+  // One sink per runtime, replaced by the next and removed by an empty one. It
+  // is called on the event loop, with what the runtime hands to the next one
+  // (`onData`, under a result purpose), what its services say (`onData`, as a
+  // notification from `sender`) and what it records (`onLog`). `run` is the
+  // run the data was produced in — which a coordinator hands to the next
+  // runtime, and reads whose a notification is to hear from — or null when it
+  // was produced outside one.
+  struct RuntimeOutputSink
+  {
+    std::function<void(const Data&, MessagePurpose, const std::string& sender,
+                       const ProcessContext* run)> onData;
+    std::function<void(const LogEntry&)> onLog;
+  };
+  void setRuntimeOutputSink(const std::string& runtimeId, RuntimeOutputSink sink,
+                            const std::string& space = "");
+  void clearRuntimeOutputSink(const std::string& runtimeId, const std::string& space = "");
+  // Hands a runtime's output to its sink, when it has one. For the runtime.
+  void emitRuntimeData(const std::string& runtimeId, const Data& data,
+                       MessagePurpose purpose, const std::string& sender,
+                       const std::string& space = "", const ProcessContext* run = nullptr);
+  void emitRuntimeLog(const std::string& runtimeId, const LogEntry& entry,
+                      const std::string& space = "");
+
+  std::shared_ptr<Service> createService(const std::string& serviceId);
+  std::shared_ptr<Service> createService(const std::string& serviceId, const std::string& instanceId);
+  const ServiceClass* findServiceClass(const std::string& serviceId) const;
+  
+  Data processRuntimeWithName(const std::string& name, const Data& params) const;
+
+  // Delivers a notification-WebSocket message (raw frame) to the runtime it
+  // belongs to. Called by the Server's WS layer once a connection has bound
+  // itself to a runtimeId via the protocol handshake.
+  // `caller` is whoever opened the socket, as the server verified them; null
+  // where it let the socket in without a token.
+  void dispatchRuntimeWsMessage(const std::string& runtimeId, const std::string& message, bool isBinary,
+                                const Caller* caller = nullptr);
+
+  void postCallback(std::function<void()> callback);
+  // The loop `postCallback` posts to, for something that keeps a connection
+  // of its own on it.
+  boost::asio::io_context& ioContext() { return m_io; }
+
+  // Replacing or clearing a server returns only once the event loop is past
+  // any callback that could still hold the one that left, so its owner may
+  // destroy it right after.
+  void setServer(Server* server);
+  Server* getServer() const { return m_server.load(); }
+  
+  template<typename T>
+  void registerService() { m_registry->registerService<T>(); }
+
+  unsigned int scanForPlugins(const std::string& bundleRoot);
+  bool loadPlugin(const std::string& path);
+  
+private:
+  std::list<std::shared_ptr<Runtime>>::iterator findRuntime(const std::string& runtimeId,
+                                                            const std::string& space = "");
+  std::list<std::shared_ptr<Runtime>>::const_iterator findRuntime(const std::string& runtimeId,
+                                                                  const std::string& space = "") const;
+
+  // Look a runtime up and return a shared_ptr copy under the lock. Callers then
+  // operate on the copy without holding the lock: the copy keeps the Runtime
+  // alive even if another thread removes it concurrently, so operations never
+  // touch a half-destroyed Runtime. Returns nullptr when not found.
+  std::shared_ptr<Runtime> findRuntimeShared(const std::string& runtimeId,
+                                             const std::string& space = "") const;
+
+  std::shared_ptr<Runtime> appendRuntime(const RuntimeConfiguration& config);
+
+  void startEventLoop();
+  void stopEventLoop();
+private:
+  // Guards the structure of m_runtimes (find/insert/erase) only. Held just long
+  // enough to look up or mutate the list — never across a Runtime operation
+  // (process/getConfiguration), which run on a shared_ptr copy instead.
+  mutable std::mutex m_runtimesMutex;
+  std::list<std::shared_ptr<Runtime>> m_runtimes;
+  std::unique_ptr<Registry> m_registry;
+  boost::asio::io_context m_io;
+  boost::asio::executor_work_guard<boost::asio::io_context::executor_type> m_work_guard;
+  std::thread m_eventThread;
+  std::atomic<Server*> m_server{nullptr};
+  mutable std::mutex m_sinksMutex;
+  std::map<std::string, RuntimeOutputSink> m_sinks;
+};
+
+}

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

@@ -0,0 +1,239 @@
+#pragma once
+
+#include <algorithm>
+#include <cstdint>
+#include <functional>
+#include <list>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <regex>
+#include <string>
+#include <vector>
+
+#include <nlohmann/json.hpp>
+
+
+namespace hkp {
+
+// Assets a runtime was given, and the one way to their content.
+//
+// A board declares content once — a page, a script, an image, a model — as an
+// asset *descriptor*: an id, a media type and exactly one source. Service state
+// names one by reference, `hkp-asset://<id>`, as a whole field, and never holds
+// the content itself. getState() therefore echoes the reference, and saving a
+// board writes back what was configured: there is no round trip to undo.
+//
+// The descriptors arrive with the runtime's create payload, or on
+// POST /runtimes/<id>/assets — and again whenever an asset is edited, which is
+// the point: a service resolves its reference at the moment it uses it, so the
+// next use gets the new content without anything being reconfigured. A runtime
+// is given every asset of its board that is not kept to other runtimes, named
+// by its services or not: which one a service uses can be decided as it runs.
+//
+// Where the content comes from depends on the source:
+//
+//   text, base64   already in the descriptor
+//   http(s)://     fetched by this runtime as anyone would fetch it, following
+//                  redirects to other http(s) addresses, cached by sha256 or
+//                  revalidated by ETag
+//   file://        only inside the root this host was given (HKP_ASSET_ROOT);
+//                  refused everywhere else, never read
+//
+// An asset carries no request headers and names no secret. It is resolved
+// without anyone looking, by every runtime holding it, which is no place for a
+// credential; content that needs one is fetched by a service that says where
+// it sends it.
+//
+// The format matches hkp-frontend/src/runtime/board/assets.ts and
+// hkp-node/src/assets.ts: a board written against one runtime has to open
+// against another.
+
+using AssetDescriptor = nlohmann::json;
+
+struct ResolvedAsset
+{
+  std::string id;
+  std::string mediaType;
+  std::string content; // raw bytes
+};
+
+struct AssetResolution
+{
+  // Empty when there is none.
+  std::optional<ResolvedAsset> asset;
+  // Why there is none, or empty when there is.
+  std::string problem;
+};
+
+inline const std::string& assetScheme()
+{
+  static const std::string scheme = "hkp-asset://";
+  return scheme;
+}
+
+inline bool isAssetId(const std::string& id)
+{
+  static const std::regex pattern(R"(^[A-Za-z0-9_.\-]+$)");
+  return std::regex_match(id, pattern);
+}
+
+// The id a whole-value reference names, or nothing for anything else. A
+// reference inside a longer string is not one: nothing is spliced into text.
+inline std::optional<std::string> parseAssetRef(const std::string& value)
+{
+  static const std::regex pattern(R"(^hkp-asset://([A-Za-z0-9_.\-]+)$)");
+  std::smatch match;
+  if (std::regex_match(value, match, pattern))
+  {
+    return match[1].str();
+  }
+  return std::nullopt;
+}
+
+inline std::optional<std::string> parseAssetRef(const nlohmann::json& value)
+{
+  return value.is_string() ? parseAssetRef(value.get<std::string>()) : std::nullopt;
+}
+
+// Every asset id a value mentions, however deeply it is nested — found anywhere
+// in a string, so a reference an expression produces is still one this runtime
+// is told about. Finding is generous; resolving is not.
+inline void findAssetRefs(const nlohmann::json& value, std::vector<std::string>& into)
+{
+  static const std::regex pattern(R"(hkp-asset://([A-Za-z0-9_.\-]+))");
+  if (value.is_string())
+  {
+    const auto text = value.get<std::string>();
+    for (std::sregex_iterator it(text.begin(), text.end(), pattern), end; it != end; ++it)
+    {
+      const auto id = (*it)[1].str();
+      if (std::find(into.begin(), into.end(), id) == into.end())
+      {
+        into.push_back(id);
+      }
+    }
+  }
+  else if (value.is_array() || value.is_object())
+  {
+    for (const auto& child : value)
+    {
+      findAssetRefs(child, into);
+    }
+  }
+}
+
+// Whether a media type is text a pipeline can carry as a string.
+inline bool isTextMediaType(std::string mediaType)
+{
+  mediaType = mediaType.substr(0, mediaType.find(';'));
+  mediaType.erase(0, mediaType.find_first_not_of(" \t"));
+  mediaType.erase(mediaType.find_last_not_of(" \t") + 1);
+  std::transform(mediaType.begin(), mediaType.end(), mediaType.begin(),
+                 [](unsigned char c) { return std::tolower(c); });
+  auto endsWith = [&](const std::string& suffix)
+  {
+    return mediaType.size() >= suffix.size() &&
+           mediaType.compare(mediaType.size() - suffix.size(), suffix.size(), suffix) == 0;
+  };
+  return mediaType.rfind("text/", 0) == 0 || mediaType == "application/json" ||
+         endsWith("+json") || mediaType == "application/javascript" ||
+         mediaType == "application/xml" || endsWith("+xml");
+}
+
+// One descriptor off the wire, or nothing when it is not one. Exactly one
+// source, or it is not an asset: two would leave a runtime choosing between
+// them.
+std::optional<AssetDescriptor> readAssetDescriptor(const nlohmann::json& value,
+                                                   const std::string& fallbackId = "");
+
+// Reads an assets payload off the wire: a map of id to descriptor, where null
+// removes one, or a list of descriptors. Anything it cannot read is dropped
+// rather than failing the request — a malformed entry costs one asset, and the
+// service referencing it says so by name. A removal is an entry holding null.
+std::map<std::string, nlohmann::json> readAssetsPayload(const nlohmann::json& value);
+
+// The bytes base64 text stands for, or nothing when it is not base64.
+//
+// Beast's decoder stops at the first character it does not recognise and hands
+// back what it had, so text that is not base64 — or base64 wrapped over lines —
+// would come out as some of its bytes. What is taken here is what a browser's
+// atob takes — ASCII whitespace ignored, the standard alphabet, padding
+// optional — so that a descriptor resolves to the same content, or the same
+// refusal, on every runtime.
+std::optional<std::string> decodeBase64(const std::string& encoded);
+
+class AssetStore
+{
+public:
+  // How one address is fetched. Supplied for tests; the default speaks HTTP and
+  // HTTPS through Beast. Answers status, body and ETag, or throws. One request:
+  // the store follows a redirect itself, so it does with any fetch.
+  struct FetchResponse
+  {
+    int status = 0;
+    std::string body;
+    std::string etag;
+    // Where a redirect points, as the response gave it; empty otherwise.
+    std::string location;
+  };
+  using Fetch = std::function<FetchResponse(const std::string& url,
+                                            const std::map<std::string, std::string>& headers)>;
+
+  explicit AssetStore(Fetch fetch = nullptr);
+
+  // Replaces everything held.
+  void replace(const std::map<std::string, nlohmann::json>& entries);
+
+  // Adds, replaces or removes (a null entry) individual descriptors, leaving the
+  // rest alone. An asset deleted from the board is gone from every runtime that
+  // was told about it, rather than served on from a stale copy.
+  void merge(const std::map<std::string, nlohmann::json>& entries);
+
+  // The ids held, for saying what a runtime knows about.
+  std::vector<std::string> ids() const;
+
+  // Called with an asset's id whenever its descriptor changes or goes away.
+  // Only a service that loads something once needs it. Returns a handle for
+  // unsubscribe().
+  std::size_t subscribe(const std::string& id, std::function<void(const std::string&)> listener);
+  void unsubscribe(std::size_t handle);
+
+  // An asset's content for one use, or a sentence saying why there is none.
+  // Blocking: a URL source is fetched on the calling thread.
+  AssetResolution resolve(const std::string& reference);
+
+  // Where file:// sources may be read from; empty refuses them all. Defaults to
+  // HKP_ASSET_ROOT.
+  void setFileRoot(const std::string& root);
+
+  std::size_t maxBytes = 64 * 1024 * 1024;
+  std::size_t maxCacheBytes = 128 * 1024 * 1024;
+
+private:
+  struct CacheEntry
+  {
+    std::string version;
+    ResolvedAsset asset;
+    std::string etag;
+  };
+
+  std::string load(const AssetDescriptor& descriptor, const CacheEntry* cached,
+                   std::string& etagOut, std::string& problem);
+  void remember(const std::string& id, CacheEntry entry);
+  void forget(const std::string& id);
+  void changed(const std::string& id);
+
+  mutable std::recursive_mutex m_mutex;
+  std::map<std::string, AssetDescriptor> m_descriptors;
+  std::map<std::string, CacheEntry> m_cache;
+  std::list<std::string> m_cacheOrder; // least recently used first
+  std::size_t m_cachedBytes = 0;
+  std::map<std::size_t, std::pair<std::string, std::function<void(const std::string&)>>> m_listeners;
+  std::size_t m_nextListener = 1;
+  Fetch m_fetch;
+  std::string m_fileRoot;
+};
+
+} // namespace hkp

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

@@ -0,0 +1,167 @@
+#pragma once
+
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace hkp
+{
+
+// A verified caller identity extracted from a bearer token.
+struct Principal
+{
+  std::string email;
+  std::string sub;
+  std::string iss;
+};
+
+// A trusted OIDC issuer. A token is accepted only if it is signed by a key from
+// this issuer's JWKS and its `aud` claim is one of `audiences`. It is `iss`+`aud`
+// that defines a trusted issuer — `sub` identifies the *user* and is matched
+// separately against the allow-list.
+struct TrustedIssuer
+{
+  std::string iss;                     // exact `iss` claim, e.g. "https://hookitapp.eu.auth0.com/"
+  std::string jwksUri;                 // JWKS endpoint; derived from `iss` when empty
+  std::vector<std::string> audiences;  // acceptable `aud` values (e.g. SPA client ids)
+};
+
+enum class AuthMode
+{
+  None,  // every request is authorized (loopback / dev). The bind is the boundary.
+  Jwt,   // bearer token must verify against a trusted issuer and an allowed email.
+};
+
+struct AuthConfig
+{
+  AuthMode mode = AuthMode::None;
+  std::vector<TrustedIssuer> issuers;
+  std::vector<std::string> allowedEmails;  // matched case-insensitively
+};
+
+enum class AuthStatus
+{
+  Ok,               // authorized; `principal` is set
+  Unauthenticated,  // missing/invalid/untrusted token → HTTP 401
+  Forbidden,        // valid token, but identity is not allowed → HTTP 403
+};
+
+struct AuthResult
+{
+  AuthStatus status = AuthStatus::Unauthenticated;
+  std::optional<Principal> principal;
+};
+
+// Resolves an opaque (non-JWT) bearer token to a principal, or nullopt.
+//
+// Reserved for future server-to-server ephemeral session tokens — the same
+// shape as hkp-node's OpaqueTokenResolver, where a long-lived caller keeps
+// acting on a user's behalf past JWT expiry. The LAN peer model has no such
+// intermediary today, so this is unset; the seam lets us add it later as a
+// localized change rather than a middleware refactor. Checked BEFORE JWT
+// verification, exactly like hkp-node.
+using OpaqueTokenResolver =
+    std::function<std::optional<Principal>(const std::string& token)>;
+
+// True when `host` is reachable only from the local machine. A loopback bind is
+// itself an access-control boundary, so running without auth there is safe
+// (matches hkp-node's isLoopbackHost).
+bool isLoopbackHost(const std::string& host);
+
+// Verifies bearer tokens against a fixed set of trusted issuers (JWKS-backed
+// RS256) and authorizes them against an email allow-list. Thread-safe; the JWKS
+// cache is populated lazily and refreshed on an unknown key id.
+class Authenticator
+{
+public:
+  explicit Authenticator(AuthConfig config, OpaqueTokenResolver resolveOpaque = {});
+  ~Authenticator();
+
+  Authenticator(const Authenticator&) = delete;
+  Authenticator& operator=(const Authenticator&) = delete;
+
+  Authenticator(Authenticator&&) noexcept;
+  Authenticator& operator=(Authenticator&&) noexcept;
+
+  // True when mode == None: every request is authorized without a token.
+  bool isNoAuth() const;
+
+  // True when the config cannot authorize anyone (Jwt mode with no issuers or no
+  // allowed emails). Callers that resolve to this while exposed are running
+  // fail-closed: every authorize() denies. Surfaced so startup can warn loudly.
+  bool isMisconfigured() const;
+
+  // Authorizes a raw Authorization header value (e.g. "Bearer eyJ...").
+  AuthResult authorize(const std::string& authorizationHeader) const;
+
+  // Replaces the allow-listed emails at runtime (thread-safe). Used by hosts
+  // that learn the permitted identity after the server starts — e.g. iOS pushes
+  // the signed-in user's email once login completes. Issuers/mode are fixed at
+  // construction; only the allow-list is mutable.
+  void setAllowedEmails(std::vector<std::string> emails);
+
+  // Pins a PEM signing key for (iss, kid), bypassing the JWKS fetch for that
+  // key. Useful for offline key pinning and for deterministic, network-free
+  // tests. Safe to call before serving.
+  void pinSigningKey(const std::string& iss, const std::string& kid, const std::string& pem);
+
+private:
+  struct Impl;
+  std::unique_ptr<Impl> m_impl;
+};
+
+// A short-lived, scoped capability grant. Possession of the token authorizes
+// exactly one request shape — a specific HTTP method + path (a runtime's
+// process endpoint) — until it expires, and nothing else.
+//
+// The point is least privilege for out-of-band devices: a trusted caller (the
+// host's own owner UI) mints a grant and hands the token to an unauthenticated
+// device through a side channel (a QR code). That device can process one
+// runtime without a user session, but a leaked or sniffed token cannot drive
+// the wider API — it is bound to a single method + path, so it is deliberately
+// NOT routed through the (unscoped) OpaqueTokenResolver, which would resolve to
+// a full principal.
+//
+// The middleware checks this BEFORE JWT verification. Grants are reusable
+// within their TTL (a chunked upload issues many POSTs); confidentiality on the
+// wire and short lifetimes — not single use — bound the exposure.
+class CapabilityStore
+{
+public:
+  CapabilityStore();
+  ~CapabilityStore();
+
+  CapabilityStore(const CapabilityStore&) = delete;
+  CapabilityStore& operator=(const CapabilityStore&) = delete;
+
+  // Mints a token authorizing exactly one request shape — `method path` — for
+  // `ttl` (clamped to a sane maximum). Returns the raw token — the only point
+  // at which it exists in cleartext server-side; only its SHA-256 digest is
+  // retained. Returns an empty string if either argument is empty or secure
+  // randomness is unavailable.
+  std::string mintGrant(const std::string& method, const std::string& path,
+                        std::chrono::seconds ttl);
+
+  // Convenience wrapper for the process-runtime endpoint: mints a grant scoped
+  // to `POST /runtimes/<runtimeId>`. Returns "" if `runtimeId` is empty. Add
+  // sibling wrappers as more scoped capabilities are needed.
+  std::string mintProcessRuntimeGrant(const std::string& runtimeId,
+                                      std::chrono::seconds ttl);
+
+  // True iff `token` is an unexpired grant whose scope matches this exact
+  // method + path. Expired grants are pruned opportunistically.
+  bool authorize(const std::string& token, const std::string& method,
+                 const std::string& path) const;
+
+  // Revokes every outstanding grant (e.g. a "stop sharing" action).
+  void clear();
+
+private:
+  struct Impl;
+  std::unique_ptr<Impl> m_impl;
+};
+
+}  // namespace hkp