feat: implement MoloApp plans 01-15 with integration

Full C++23 framework tree: runtime, observability, security,
data, app, realtime, supervisor, clients, CLI, example plus
enterprise tenancy, audit, operability, governance,
supplychain. Postgres via docker compose for tests.
This commit is contained in:
2026-10-23 18:20:04 +02:00
parent 54068f1953
commit 3c4334cec9
1068 changed files with 100899 additions and 2 deletions
+124
View File
@@ -0,0 +1,124 @@
// Appender: the write path for audit records. ORM save()/remove() reach it
// through notify_write (see PATCHES.md entry 2); the AUDIT macro fills
// actor, subject, request and trace ids from the ambient call context.
// Oversize before/after images are truncated to their caps; oversize records
// are rejected loudly, never stored half.
#pragma once
#include <atomic>
#include <chrono>
#include <cstdint>
#include <memory>
#include <stdexcept>
#include <string>
#include "../adapt.h"
#include "../caps.h"
#include "record.h"
#include "store.h"
namespace molo::audit::log {
class Appender {
public:
// INTEGRATION: real null_sink() returns NullSink&, not shared_ptr, and
// real counter() takes (name, int64, labels-string).
explicit Appender(Store& store, ::molo::data::obs::MetricSink& metrics =
::molo::data::obs::null_sink())
: store_(store), metrics_(metrics) {}
struct Write {
std::string actor;
std::string action;
std::string table;
std::string pk;
std::string op;
std::string before_json;
std::string after_json;
std::string tenant;
std::string request_id;
std::string trace_id;
};
// Appends one record, returns its seq. Throws on oversize record.
std::uint64_t Append(Write w) {
if (w.before_json.size() > kMaxBeforeBytes) w.before_json.resize(kMaxBeforeBytes);
if (w.after_json.size() > kMaxAfterBytes) w.after_json.resize(kMaxAfterBytes);
AuditRecord rec;
rec.ts = Now();
rec.tenant = std::move(w.tenant);
rec.actor = std::move(w.actor);
rec.action = std::move(w.action);
rec.table = std::move(w.table);
rec.pk = std::move(w.pk);
rec.op = std::move(w.op);
rec.before_json = std::move(w.before_json);
rec.after_json = std::move(w.after_json);
rec.request_id = std::move(w.request_id);
rec.trace_id = std::move(w.trace_id);
if (rec.Canonical().size() > kMaxRecordBytes)
throw std::runtime_error("audit record exceeds kMaxRecordBytes");
std::uint64_t seq = store_.Append(rec);
appended_.fetch_add(1);
metrics_.counter("audit_records_appended_total", 1, "table=" + rec.table);
MaybeSeal(seq);
return seq;
}
// Process-wide writer installed once at deploy composition. Null until set.
static void Install(Appender* a) { Global() = a; }
static Appender* GlobalInstance() { return Global(); }
std::uint64_t appended() const { return appended_.load(); }
private:
static Appender*& Global() {
static Appender* g = nullptr;
return g;
}
static std::int64_t Now() {
return std::chrono::duration_cast<std::chrono::seconds>(
std::chrono::system_clock::now().time_since_epoch())
.count();
}
void MaybeSeal(std::uint64_t seq) {
if (seq % kSealEveryRecords != 0) return;
Seal s = Chain::MakeSeal(seq / kSealEveryRecords, store_.Tip(), Now(), seal_key_);
store_.SaveSeal(s);
metrics_.counter("audit_seals_total", 1);
}
Store& store_;
::molo::data::obs::MetricSink& metrics_;
std::string seal_key_; // empty until deploy composition provisions the key
std::atomic<std::uint64_t> appended_{0};
};
// ORM hook called from Model save()/remove() after bus->publish. No-op until
// Appender::Install wires the store, so ORM boots without audit configured.
inline void notify_write(const std::string& table, const std::string& pk, const std::string& op,
const std::string& before_json, const std::string& after_json,
const ::molo::data::Context& ctx, const std::string& actor = "") {
Appender* a = Appender::GlobalInstance();
if (!a) return;
Appender::Write w;
w.actor = actor;
w.action = "orm." + op;
w.table = table;
w.pk = pk;
w.op = op;
w.before_json = before_json;
w.after_json = after_json;
w.tenant = ctx.tenant();
w.request_id = ctx.correlation_id();
a->Append(std::move(w));
}
} // namespace molo::audit::log
// AUDIT(store, table, pk, op, before, after, ctx, actor): one-line ORM hook
// filling tenant + request id from the data Context. Availability of the
// global Appender decides whether this writes or no-ops.
#define AUDIT(store, table, pk, op, before, after, ctx, actor) \
::molo::audit::log::notify_write((table), (pk), (op), (before), (after), (ctx), (actor))
+112
View File
@@ -0,0 +1,112 @@
// Hash chain over audit records: hash = SHA256hex(prev_hash || canonical).
// Genesis prev_hash is 64 zeros. Seal checkpoints the tip with an HMAC under
// the audit seal key; Verify replays the chain and names the exact sequence
// number of the first gap or tampered record.
#pragma once
#include <cstdint>
#include <string>
#include <string_view>
#include <vector>
#include "../adapt.h"
#include "../caps.h"
#include "record.h"
namespace molo::audit::log {
inline const std::string& GenesisHash() {
static const std::string k(64, '0');
return k;
}
struct Seal {
std::uint64_t seal_seq = 0;
std::string root; // tip hash at seal time
std::int64_t ts = 0;
std::string mac; // HMAC-SHA256 hex over "seal_seq:root:ts" under seal key
};
struct VerifyResult {
bool ok = true;
std::uint64_t bad_seq = 0; // first gap or tamper, valid when !ok
std::string reason; // "gap", "prev", "hash", "seal"
};
class Chain {
public:
static std::string HashEntry(std::string_view prev_hash, std::string_view canonical) {
std::string in(prev_hash);
in += canonical;
return ::molo::security::crypto::Sha256::hex(
::molo::security::crypto::Sha256::hash(in));
}
// Stamps prev/hash onto rec given the previous tip (genesis for seq 1).
static void Link(AuditRecord& rec, std::string_view prev_tip) {
rec.prev_hash = std::string(prev_tip);
rec.hash = HashEntry(rec.prev_hash, rec.Canonical());
}
static Seal MakeSeal(std::uint64_t seal_seq, std::string_view root, std::int64_t ts,
std::string_view seal_key) {
Seal s;
s.seal_seq = seal_seq;
s.root = std::string(root);
s.ts = ts;
std::string body =
std::to_string(seal_seq) + ":" + s.root + ":" + std::to_string(ts);
// INTEGRATION: real Hmac takes (const string&, const string&) and hex
// takes a non-const ref, so materialize both arguments.
auto mac = ::molo::security::crypto::Hmac::sha256(std::string(seal_key), body);
s.mac = ::molo::security::crypto::Hmac::hex(mac);
return s;
}
static bool CheckSeal(const Seal& s, std::string_view seal_key) {
return MakeSeal(s.seal_seq, s.root, s.ts, seal_key).mac == s.mac;
}
// Replays ordered records: seq continuity, prev linkage, entry hashes.
// When seals is non-empty the covered tips must match a valid seal root.
static VerifyResult Verify(const std::vector<AuditRecord>& recs,
const std::vector<Seal>& seals = {},
std::string_view seal_key = "") {
VerifyResult r;
std::string tip = GenesisHash();
std::uint64_t expect = recs.empty() ? 0 : recs.front().seq;
for (const auto& rec : recs) {
if (rec.seq != expect) {
r.ok = false;
r.bad_seq = expect;
r.reason = "gap";
return r;
}
if (rec.prev_hash != tip) {
r.ok = false;
r.bad_seq = rec.seq;
r.reason = "prev";
return r;
}
if (rec.hash != HashEntry(rec.prev_hash, rec.Canonical())) {
r.ok = false;
r.bad_seq = rec.seq;
r.reason = "hash";
return r;
}
tip = rec.hash;
++expect;
}
for (const auto& s : seals) {
if (!seal_key.empty() && !CheckSeal(s, seal_key)) {
r.ok = false;
r.reason = "seal";
return r;
}
}
(void)kSealEveryRecords;
return r;
}
};
} // namespace molo::audit::log
+107
View File
@@ -0,0 +1,107 @@
// Query: filtered, paged reads over the audit trail. Every query requires
// the audit.read grant (Guard verdict 403 otherwise) and every query, allowed
// or denied, appends its own self-audit record so trail reads stay visible.
#pragma once
#include <cstdint>
#include <optional>
#include <string>
#include <vector>
#include "../adapt.h"
#include "../caps.h"
#include "appender.h"
#include "record.h"
#include "store.h"
namespace molo::audit::log {
struct Filter {
std::string tenant;
std::string table;
std::string actor;
std::string op;
std::uint64_t from_seq = 0;
std::uint64_t to_seq = 0; // 0 means no upper bound
std::size_t limit = 100;
std::string cursor; // seq to resume after, empty starts at from_seq
};
struct QueryPage {
int http_status = 200;
std::string code = "ok";
std::vector<AuditRecord> rows;
std::string next_cursor;
};
class Query {
public:
Query(Store& store, Appender* audit) : store_(store), audit_(audit) {}
// INTEGRATION: real Guard::check takes (Session, roles, required) with
// Session from security/session; any denial maps to 403 per this API.
QueryPage Run(const Filter& f, const ::molo::security::session::Session& session,
const std::vector<::molo::security::auth::Role>& roles = {}) {
using ::molo::security::auth::Guard;
using ::molo::security::auth::Permission;
VerdictOf(Guard::check(session, roles, {Permission{"audit.read"}}));
if (last_status_ == 403) {
SelfAudit(session, f, "query.denied");
QueryPage p;
p.http_status = 403;
p.code = "forbidden";
return p;
}
std::size_t limit = f.limit == 0 ? 100 : f.limit;
if (limit > kQueryPageMax) limit = kQueryPageMax;
std::uint64_t start = f.from_seq == 0 ? 1 : f.from_seq;
if (!f.cursor.empty()) start = std::stoull(f.cursor) + 1;
QueryPage page;
std::uint64_t probe = start;
while (page.rows.size() < limit) {
auto batch = store_.ReadRange(probe, limit - page.rows.size());
if (batch.empty()) break;
for (auto& r : batch) {
probe = r.seq + 1;
if (f.to_seq != 0 && r.seq > f.to_seq) {
probe = 0;
break;
}
if (!f.tenant.empty() && r.tenant != f.tenant) continue;
if (!f.table.empty() && r.table != f.table) continue;
if (!f.actor.empty() && r.actor != f.actor) continue;
if (!f.op.empty() && r.op != f.op) continue;
page.rows.push_back(r);
if (page.rows.size() >= limit) break;
}
if (probe == 0) break;
}
if (!page.rows.empty()) page.next_cursor = std::to_string(page.rows.back().seq);
SelfAudit(session, f, "query.allowed");
return page;
}
private:
void VerdictOf(const ::molo::security::auth::Guard::Verdict& v) {
last_status_ = v.allowed ? 200 : 403;
}
void SelfAudit(const ::molo::security::session::Session& s, const Filter& f,
const std::string& action) {
if (!audit_) return;
Appender::Write w;
w.actor = s.user_id;
w.action = action;
w.table = "audit_records";
w.op = "read";
w.tenant = f.tenant;
w.after_json = "{\"table\":\"" + AuditRecord::Escape(f.table) + "\"}";
audit_->Append(std::move(w));
}
Store& store_;
Appender* audit_;
int last_status_ = 200;
};
} // namespace molo::audit::log
+81
View File
@@ -0,0 +1,81 @@
// AuditRecord: one immutable audit trail entry with fixed JSON keys.
// Key order is frozen (spec 6.1): v,seq,ts,tenant,actor,action,table,pk,op,
// before,after,req,trace,prev,hash. Canonical() renders exactly those keys
// so the hash chain is stable across backends and releases.
#pragma once
#include <cstdint>
#include <string>
namespace molo::audit::log {
struct AuditRecord {
std::uint64_t seq = 0;
std::int64_t ts = 0; // unix seconds
std::string tenant;
std::string actor;
std::string action;
std::string table;
std::string pk;
std::string op; // insert, update, delete, read, export, erase, seal
std::string before_json;
std::string after_json;
std::string request_id;
std::string trace_id;
std::string prev_hash; // 64 hex chars, genesis is 64 zeros
std::string hash; // 64 hex chars over prev_hash + canonical body
static std::string Escape(std::string_view s) {
std::string o;
o.reserve(s.size() + 2);
for (char c : s) {
switch (c) {
case '"':
o += "\\\"";
break;
case '\\':
o += "\\\\";
break;
case '\n':
o += "\\n";
break;
case '\r':
o += "\\r";
break;
case '\t':
o += "\\t";
break;
default:
o += c;
}
}
return o;
}
// Canonical body: every key except hash, fixed order, no whitespace.
std::string Canonical() const {
std::string o = "{\"v\":1";
o += ",\"seq\":" + std::to_string(seq);
o += ",\"ts\":" + std::to_string(ts);
o += ",\"tenant\":\"" + Escape(tenant) + "\"";
o += ",\"actor\":\"" + Escape(actor) + "\"";
o += ",\"action\":\"" + Escape(action) + "\"";
o += ",\"table\":\"" + Escape(table) + "\"";
o += ",\"pk\":\"" + Escape(pk) + "\"";
o += ",\"op\":\"" + Escape(op) + "\"";
o += ",\"before\":" + (before_json.empty() ? "null" : before_json);
o += ",\"after\":" + (after_json.empty() ? "null" : after_json);
o += ",\"req\":\"" + Escape(request_id) + "\"";
o += ",\"trace\":\"" + Escape(trace_id) + "\"";
o += ",\"prev\":\"" + Escape(prev_hash) + "\"}";
return o;
}
std::string ToJson() const {
std::string c = Canonical();
c.pop_back(); // strip closing brace
return c + ",\"hash\":\"" + Escape(hash) + "\"}";
}
};
} // namespace molo::audit::log
+216
View File
@@ -0,0 +1,216 @@
// SqlStore: production Store over both SQL backends (Postgres, SQLite).
// Tables audit_records and audit_seals use one portable DDL; only the
// parameter placeholder style differs per backend. Binding goes through the
// tiny SqlExec seam so this header compiles standalone; ConnectionExec binds
// it to a real molo::data::Connection, tests bind a FakeExec.
#pragma once
#include <cstdint>
#include <cstdlib>
#include <mutex>
#include <string>
#include <vector>
#include "../adapt.h"
#include "../caps.h"
#include "chain.h"
#include "record.h"
#include "store.h"
namespace molo::audit::log {
// Minimal SQL surface the audit store needs. Params are strings; the
// Connection binding promotes integer-looking params to make_int.
class SqlExec {
public:
virtual ~SqlExec() = default;
virtual void Exec(const std::string& sql, const std::vector<std::string>& params) = 0;
virtual std::vector<std::vector<std::string>> Query(const std::string& sql,
const std::vector<std::string>& params,
std::size_t max_rows) = 0;
virtual bool IsPostgres() const = 0;
};
// Binds SqlExec to a real framework Connection. Both backends supported.
class ConnectionExec : public SqlExec {
public:
ConnectionExec(::molo::data::Connection& c, ::molo::data::Context ctx)
: conn_(c), ctx_(std::move(ctx)) {}
void Exec(const std::string& sql, const std::vector<std::string>& params) override {
conn_.exec(ctx_, ::molo::data::BoundStatement(sql, ToValues(params)));
}
std::vector<std::vector<std::string>> Query(const std::string& sql,
const std::vector<std::string>& params,
std::size_t max_rows) override {
auto res = conn_.exec(ctx_, ::molo::data::BoundStatement(sql, ToValues(params)));
std::vector<std::vector<std::string>> out;
// INTEGRATION: real Result exposes size()/raw(i), not a rows member.
for (std::size_t i = 0; i < res.size(); ++i) {
if (out.size() >= max_rows) break;
std::vector<std::string> r;
for (auto& v : res.raw(i)) r.push_back(FromValue(v));
out.push_back(std::move(r));
}
return out;
}
bool IsPostgres() const override { return conn_.is_postgres(); }
private:
static std::vector<::molo::data::Value> ToValues(const std::vector<std::string>& p) {
std::vector<::molo::data::Value> v;
for (auto& s : p) {
char* end = nullptr;
long long n = std::strtoll(s.c_str(), &end, 10);
if (end && *end == '\0' && end != s.c_str())
v.push_back(::molo::data::make_int(n));
else
v.push_back(::molo::data::make_text(s));
}
return v;
}
static std::string FromValue(const ::molo::data::Value& v) {
if (auto* i = std::get_if<std::int64_t>(&v)) return std::to_string(*i);
if (auto* s = std::get_if<std::string>(&v)) return *s;
if (auto* d = std::get_if<double>(&v)) return std::to_string(*d);
if (auto* b = std::get_if<bool>(&v)) return *b ? "1" : "0";
return "";
}
::molo::data::Connection& conn_;
::molo::data::Context ctx_;
};
class SqlStore : public Store {
public:
explicit SqlStore(SqlExec& db) : db_(db) { EnsureSchema(); }
static std::string DdlRecords() {
return "CREATE TABLE IF NOT EXISTS audit_records (seq INTEGER PRIMARY KEY,"
"ts BIGINT NOT NULL,tenant TEXT NOT NULL,actor TEXT NOT NULL,"
"action TEXT NOT NULL,tbl TEXT NOT NULL,pk TEXT NOT NULL,"
"op TEXT NOT NULL,before_json TEXT NOT NULL,after_json TEXT NOT NULL,"
"req TEXT NOT NULL,trace TEXT NOT NULL,prev_hash TEXT NOT NULL,"
"hash TEXT NOT NULL)";
}
static std::string DdlSeals() {
return "CREATE TABLE IF NOT EXISTS audit_seals (seal_seq INTEGER PRIMARY KEY,"
"root TEXT NOT NULL,ts BIGINT NOT NULL,mac TEXT NOT NULL)";
}
std::uint64_t Append(AuditRecord rec) override {
std::lock_guard<std::mutex> g(mu_);
auto tip_rows =
db_.Query("SELECT seq,hash FROM audit_records ORDER BY seq DESC LIMIT 1", {}, 1);
std::uint64_t seq = 1;
std::string tip = GenesisHash();
if (!tip_rows.empty() && tip_rows[0].size() == 2) {
seq = std::stoull(tip_rows[0][0]) + 1;
tip = tip_rows[0][1];
}
rec.seq = seq;
Chain::Link(rec, tip);
const bool pg = db_.IsPostgres();
std::string sql =
"INSERT INTO audit_records (seq,ts,tenant,actor,action,tbl,pk,op,before_json,"
"after_json,req,trace,prev_hash,hash) VALUES (" +
Placeholders(14, pg) + ")";
db_.Exec(sql, {std::to_string(rec.seq), std::to_string(rec.ts), rec.tenant, rec.actor,
rec.action, rec.table, rec.pk, rec.op, rec.before_json, rec.after_json,
rec.request_id, rec.trace_id, rec.prev_hash, rec.hash});
return seq;
}
std::vector<AuditRecord> ReadRange(std::uint64_t from_seq, std::size_t limit) override {
std::lock_guard<std::mutex> g(mu_);
if (limit > kQueryPageMax) limit = kQueryPageMax;
const bool pg = db_.IsPostgres();
std::string sql =
"SELECT seq,ts,tenant,actor,action,tbl,pk,op,before_json,after_json,req,trace,"
"prev_hash,hash FROM audit_records WHERE seq >= " +
Ph(1, pg) + " ORDER BY seq ASC LIMIT " + std::to_string(limit);
std::vector<AuditRecord> out;
for (auto& r : db_.Query(sql, {std::to_string(from_seq)}, limit)) {
if (r.size() != 14) continue;
AuditRecord rec;
rec.seq = std::stoull(r[0]);
rec.ts = std::stoll(r[1]);
rec.tenant = r[2];
rec.actor = r[3];
rec.action = r[4];
rec.table = r[5];
rec.pk = r[6];
rec.op = r[7];
rec.before_json = r[8];
rec.after_json = r[9];
rec.request_id = r[10];
rec.trace_id = r[11];
rec.prev_hash = r[12];
rec.hash = r[13];
out.push_back(std::move(rec));
}
return out;
}
void SaveSeal(const Seal& s) override {
std::lock_guard<std::mutex> g(mu_);
const bool pg = db_.IsPostgres();
db_.Exec("INSERT INTO audit_seals (seal_seq,root,ts,mac) VALUES (" + Placeholders(4, pg) +
")",
{std::to_string(s.seal_seq), s.root, std::to_string(s.ts), s.mac});
}
std::vector<Seal> Seals() override {
std::lock_guard<std::mutex> g(mu_);
std::vector<Seal> out;
for (auto& r : db_.Query("SELECT seal_seq,root,ts,mac FROM audit_seals ORDER BY seal_seq ASC",
{}, 100000)) {
if (r.size() != 4) continue;
Seal s;
s.seal_seq = std::stoull(r[0]);
s.root = r[1];
s.ts = std::stoll(r[2]);
s.mac = r[3];
out.push_back(std::move(s));
}
return out;
}
std::uint64_t LatestSeq() override {
std::lock_guard<std::mutex> g(mu_);
auto rows = db_.Query("SELECT seq FROM audit_records ORDER BY seq DESC LIMIT 1", {}, 1);
return rows.empty() ? 0 : std::stoull(rows[0][0]);
}
std::string Tip() override {
std::lock_guard<std::mutex> g(mu_);
auto rows = db_.Query("SELECT hash FROM audit_records ORDER BY seq DESC LIMIT 1", {}, 1);
return rows.empty() ? GenesisHash() : rows[0][0];
}
private:
void EnsureSchema() {
db_.Exec(DdlRecords(), {});
db_.Exec(DdlSeals(), {});
}
static std::string Ph(int n, bool pg) { return pg ? "$" + std::to_string(n) : "?"; }
static std::string Placeholders(int n, bool pg) {
std::string o;
for (int i = 1; i <= n; ++i) {
if (i > 1) o += ",";
o += Ph(i, pg);
}
return o;
}
SqlExec& db_;
std::mutex mu_;
};
} // namespace molo::audit::log
+80
View File
@@ -0,0 +1,80 @@
// Store: the only persistence seam for the audit trail. Three operations:
// append, read_range, seal. MemoryStore is the standalone/test backend;
// SqlStore (sql_store.h) is the production backend over both SQL drivers.
#pragma once
#include <cstdint>
#include <mutex>
#include <string>
#include <vector>
#include "../caps.h"
#include "chain.h"
#include "record.h"
namespace molo::audit::log {
class Store {
public:
virtual ~Store() = default;
// Appends rec, assigns rec.seq, links the chain, returns the seq.
virtual std::uint64_t Append(AuditRecord rec) = 0;
// Reads at most limit records from from_seq (inclusive), ascending.
virtual std::vector<AuditRecord> ReadRange(std::uint64_t from_seq, std::size_t limit) = 0;
// Persists a chain seal checkpoint.
virtual void SaveSeal(const Seal& s) = 0;
virtual std::vector<Seal> Seals() = 0;
virtual std::uint64_t LatestSeq() = 0;
// Current chain tip, genesis when empty.
virtual std::string Tip() = 0;
};
class MemoryStore : public Store {
public:
std::uint64_t Append(AuditRecord rec) override {
std::lock_guard<std::mutex> g(mu_);
rec.seq = recs_.size() + 1;
Chain::Link(rec, tip_);
tip_ = rec.hash;
recs_.push_back(std::move(rec));
return recs_.size();
}
std::vector<AuditRecord> ReadRange(std::uint64_t from_seq, std::size_t limit) override {
std::lock_guard<std::mutex> g(mu_);
if (limit > kQueryPageMax) limit = kQueryPageMax;
std::vector<AuditRecord> out;
if (from_seq == 0 || from_seq > recs_.size()) return out;
for (std::size_t i = from_seq - 1; i < recs_.size() && out.size() < limit; ++i)
out.push_back(recs_[i]);
return out;
}
void SaveSeal(const Seal& s) override {
std::lock_guard<std::mutex> g(mu_);
seals_.push_back(s);
}
std::vector<Seal> Seals() override {
std::lock_guard<std::mutex> g(mu_);
return seals_;
}
std::uint64_t LatestSeq() override {
std::lock_guard<std::mutex> g(mu_);
return recs_.size();
}
std::string Tip() override {
std::lock_guard<std::mutex> g(mu_);
return tip_;
}
private:
std::mutex mu_;
std::vector<AuditRecord> recs_;
std::vector<Seal> seals_;
std::string tip_ = GenesisHash();
};
} // namespace molo::audit::log