Catcrafts/catcrafts.net
Watch
2
0
Fork
You've already forked catcrafts.net
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

retire the bunq integration
All checks were successful
Deploy / build-deploy (push) Successful in 3m32s
Details

Browse source 
The webhook is deregistered at bunq and the callback endpoint, its parser,
default-deny classifier, dedup ledger and signature check are removed; the
code is in git history if a bank feed ever comes back. /financials keeps
reading the hand-maintained aggregates file, and sales + shop donations
stay live from the order ledger.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jorijn van der Graaf 2026-08-17 11:36:54 +02:00
commit c31797bd9a
13 changed files with 70 additions and 1694 deletions
Download patch file Download diff file Expand all files Collapse all files

527
server/implementations/Catcrafts.Server-Financials.cpp
View file

@ -6,44 +6,23 @@ The source code of this website is made available for viewing purposes only.
No permission is granted to copy, modify, distribute, or create derivative works.
*/
// The public financials aggregates, and the bunq callback that keeps them live.
// The public financials aggregates.
//
// The page at /financials shows running totals only. Sales fold out of the
// order ledger on every request (Orders.cpp); donations and expenses come from
// the aggregates file this unit owns, and bunq's mutation callback is what
// moves those numbers the moment money does.
// The page at /financials shows running totals only. Sales and shop donations
// fold out of the order ledger on every request (Orders.cpp); the bank-side
// donations and the expenses come from the aggregates file this unit reads —
// written by the owner's own tooling, off this box, and re-read per request so
// updating the file is all it takes to update the page.
//
// THE PRIVACY RULE, which is the reason this unit is shaped the way it is: a
// bank mutation arrives here carrying a counterparty name, an IBAN and a
// description. NONE of that is ever written down. A mutation is classified,
// its amount is added to a category total, and its opaque id goes in a
// dedup ledger so a retry cannot double-count it. Everything else is dropped
// on the floor before anything is persisted. There is therefore no file on
// this box that the callback path could leak a donor's identity from, because
// no such file is ever written.
//
// CLASSIFICATION IS DEFAULT-DENY. A mutation that no rule claims is NOT
// published — not as "other", not as a guess. It is counted and logged for the
// operator, and stays out of the totals until a rule exists for it. Getting a
// number wrong on this page is worse than the number being late.
//
// WHY THE KEY IS NOT HERE. A bunq API key can initiate payments; there is no
// read-only scope. So this box never holds one. The notification filter is
// registered once from the owner's own machine (which is where the key lives,
// IP-bound), and from then on bunq PUSHES here. The server can receive money
// news without being able to move money — which is the whole point.
//
// THE CALLBACK IS PROVISIONAL, THE WEEKLY PULL IS AUTHORITATIVE. Callbacks can
// be missed, replayed or arrive out of order, and the classifier can be wrong
// until a rule is added. The owner's home tooling recomputes every total from
// the full bunq mutation history and overwrites the aggregates file wholesale.
// That is the correction mechanism, and it is why this path is allowed to be
// lossy but never wrong: it may withhold, it may not invent.
// This unit once also held the bunq mutation callback that moved those numbers
// live (parser, default-deny classifier, dedup ledger, signature check). That
// integration was retired 2026-08-17 — the webhook is deregistered and the
// endpoint is gone — and the file is in git history if a bank feed ever comes
// back. What survives is the privacy property the page still promises: the
// only bank-derived state on this box is category totals with an as-of date;
// no transaction, counterparty or timestamp ever reaches disk here.
module;
#include <openssl/bio.h>
#include <openssl/evp.h>
#include <openssl/pem.h>
module Catcrafts.Server;
import std;
@ -65,398 +44,8 @@ std::string ReadStateFile(const std::filesystem::path& p) {
return buf.str();
}
// Write via a temp file and rename, so a reader (the /financials handler, or
// the owner's tooling) never observes a half-written document. The aggregates
// file is read on every page request, so a torn write would be a visible
// wrong number rather than a transient.
bool WriteStateFileAtomic(const std::filesystem::path& p, std::string_view data) {
if (p.empty()) return false;
std::filesystem::path tmp = p;
tmp += ".tmp";
{
std::ofstream out(tmp, std::ios::binary | std::ios::trunc);
if (!out) return false;
out << data;
out.flush();
if (!out) return false;
}
std::error_code ec;
std::filesystem::permissions(tmp,
std::filesystem::perms::owner_read
| std::filesystem::perms::owner_write,
ec);
std::filesystem::rename(tmp, p, ec);
if (ec) {
std::filesystem::remove(tmp, ec);
return false;
}
return true;
}
std::string JsonEscapeF(std::string_view s) {
std::string out;
out.reserve(s.size() + 8);
for (const char c : s) {
switch (c) {
case '"': out += "\\\""; break;
case '\\': out += "\\\\"; break;
case '\n': out += "\\n"; break;
case '\r': out += "\\r"; break;
case '\t': out += "\\t"; break;
default:
if (static_cast<unsigned char>(c) < 0x20) {
out += std::format("\\u{:04x}", static_cast<unsigned char>(c));
} else {
out += c;
}
}
}
return out;
}
std::string LowerF(std::string_view s) {
std::string out(s);
for (char& c : out) {
if (c >= 'A' && c <= 'Z') c = static_cast<char>(c - 'A' + 'a');
}
return out;
}
// ── the ingest ledger ─────────────────────────────────────────────────
//
// Opaque bunq mutation ids and two counters. No amounts against ids, no
// names, nothing that reconstructs a transaction — this file exists purely so
// a redelivered callback is recognised as one already counted.
struct SeenLedger {
std::vector<std::string> ids;
std::int64_t pendingCount = 0; // mutations no rule claimed
std::int64_t pendingMinor = 0; // and what they summed to, for the operator
bool Has(std::string_view id) const {
return std::find(ids.begin(), ids.end(), id) != ids.end();
}
};
SeenLedger LoadSeen(std::string_view json) {
SeenLedger out;
auto doc = Json::Parse(json);
if (!doc || !doc->IsObject()) return out;
if (const Json::Value* a = doc->Find("ids"); a && a->IsArray()) {
for (const Json::Value& v : a->array) {
if (v.type == Json::Type::String && !v.string.empty()) out.ids.push_back(v.string);
}
}
out.pendingCount = doc->Int("pending_count");
out.pendingMinor = doc->Int("pending_minor");
return out;
}
std::string SerialiseSeen(const SeenLedger& s) {
std::string out = "{\"ids\":[";
for (std::size_t i = 0; i < s.ids.size(); ++i) {
if (i) out += ',';
out += std::format("\"{}\"", JsonEscapeF(s.ids[i]));
}
out += std::format("],\"pending_count\":{},\"pending_minor\":{}}}",
s.pendingCount, s.pendingMinor);
return out;
}
// The aggregates file, in exactly the shape Shared's LoadFinancials reads and
// the owner's tooling writes. One format, three writers, no translation layer.
std::string SerialiseFinancials(const Financials& f) {
auto categories = [](const std::vector<FinCategory>& cats) {
std::string out = "[";
for (std::size_t i = 0; i < cats.size(); ++i) {
if (i) out += ',';
out += std::format(R"({{"label":"{}","total_minor":{}}})",
JsonEscapeF(cats[i].label), cats[i].totalMinor);
}
out += ']';
return out;
};
return std::format(
R"({{"as_of":"{}",)"
R"("donations":{{"count":{},"total_minor":{}}},)"
R"("expenses":{}}})",
JsonEscapeF(f.asOf), f.donationCount, f.donationsMinor,
categories(f.expenses));
}
// ── crypto ────────────────────────────────────────────────────────────
struct PkeyDeleter {
void operator()(EVP_PKEY* p) const { EVP_PKEY_free(p); }
};
std::optional<std::vector<unsigned char>> Base64Decode(std::string_view in) {
auto sextet = [](char c) -> int {
if (c >= 'A' && c <= 'Z') return c - 'A';
if (c >= 'a' && c <= 'z') return c - 'a' + 26;
if (c >= '0' && c <= '9') return c - '0' + 52;
if (c == '+') return 62;
if (c == '/') return 63;
return -1;
};
std::vector<unsigned char> out;
std::uint32_t acc = 0;
int bits = 0;
for (const char c : in) {
if (c == '\n' || c == '\r' || c == ' ' || c == '\t') continue;
if (c == '=') break;
const int v = sextet(c);
if (v < 0) return std::nullopt; // not base64: refuse rather than guess
acc = (acc << 6) | static_cast<std::uint32_t>(v);
bits += 6;
if (bits >= 8) {
bits -= 8;
out.push_back(static_cast<unsigned char>((acc >> bits) & 0xff));
}
}
return out;
}
// RSA-SHA256 over the raw request body against bunq's server public key.
//
// Optional and off unless a key file is configured, for an honest reason: the
// header bunq signs callbacks with has changed across API generations, and a
// verifier that is wrong about the header name rejects every real callback
// while looking like it is working. Enable it once a real callback has been
// observed carrying a signature — see deploy/README.md. When it IS enabled a
// failure is fatal to the request: no signature, no ingest.
bool SignatureValid(std::string_view body, std::string_view signatureB64,
const std::filesystem::path& pubkeyPath) {
const std::string pem = ReadStateFile(pubkeyPath);
if (pem.empty() || signatureB64.empty()) return false;
const auto sig = Base64Decode(signatureB64);
if (!sig || sig->empty()) return false;
BIO* bio = BIO_new_mem_buf(pem.data(), static_cast<int>(pem.size()));
if (!bio) return false;
EVP_PKEY* raw = PEM_read_bio_PUBKEY(bio, nullptr, nullptr, nullptr);
BIO_free(bio);
if (!raw) return false;
const std::unique_ptr<EVP_PKEY, PkeyDeleter> key(raw);
EVP_MD_CTX* ctx = EVP_MD_CTX_new();
if (!ctx) return false;
bool ok = false;
do {
if (EVP_DigestVerifyInit(ctx, nullptr, EVP_sha256(), nullptr, key.get()) != 1) break;
ok = EVP_DigestVerify(ctx, sig->data(), sig->size(),
reinterpret_cast<const unsigned char*>(body.data()),
body.size()) == 1;
} while (false);
EVP_MD_CTX_free(ctx);
return ok;
}
// Length-independent, content-independent comparison. The secret sits in the
// callback URL, so an attacker can probe it one request at a time; a plain ==
// would leak the matching prefix through timing.
bool SecretEqual(std::string_view a, std::string_view b) {
if (a.empty() || b.empty()) return false;
unsigned char diff = a.size() == b.size() ? 0 : 1;
const std::size_t n = std::max(a.size(), b.size());
for (std::size_t i = 0; i < n; ++i) {
const unsigned char ca = i < a.size() ? static_cast<unsigned char>(a[i]) : 0;
const unsigned char cb = i < b.size() ? static_cast<unsigned char>(b[i]) : 0;
diff |= static_cast<unsigned char>(ca ^ cb);
}
return diff == 0;
}
// Recursively find the object that describes the payment. bunq wraps the
// payload differently across API generations and event types
// (NotificationUrl -> object -> Payment | MutationCreated | …), so this looks
// for the SHAPE rather than a fixed path: an object carrying an "amount"
// object and an "id". Matching on shape is what keeps a wrapper rename from
// silently turning every callback into a no-op.
const Json::Value* FindPaymentObject(const Json::Value& v) {
if (v.IsObject()) {
const Json::Value* amount = v.Find("amount");
if (amount && amount->IsObject() && amount->Find("value") && v.Find("id")) return &v;
for (const auto& [k, child] : v.object) {
if (const Json::Value* hit = FindPaymentObject(child)) return hit;
}
} else if (v.IsArray()) {
for (const Json::Value& child : v.array) {
if (const Json::Value* hit = FindPaymentObject(child)) return hit;
}
}
return nullptr;
}
} // namespace
// ── pure parsing and classification (exported for the self-test) ──────
std::optional<std::int64_t> ParseSignedAmountToMinor(std::string_view s) {
bool negative = false;
if (s.starts_with('-')) { negative = true; s.remove_prefix(1); }
else if (s.starts_with('+')) { s.remove_prefix(1); }
const auto magnitude = ParseAmountToMinor(s);
if (!magnitude) return std::nullopt;
return negative ? -*magnitude : *magnitude;
}
std::optional<BankMutation> ParseBunqMutation(std::string_view json) {
auto doc = Json::Parse(json);
if (!doc) return std::nullopt;
const Json::Value* pay = FindPaymentObject(*doc);
if (!pay) return std::nullopt;
BankMutation m;
// bunq sends the id as a JSON number; it travels as text from here, like
// every other provider id in this codebase.
if (const Json::Value* id = pay->Find("id")) {
if (id->type == Json::Type::Number) {
m.id = std::format("{}", static_cast<std::int64_t>(id->number));
} else if (id->type == Json::Type::String) {
m.id = id->string;
}
}
if (m.id.empty()) return std::nullopt;
const Json::Value* amount = pay->Find("amount");
if (!amount) return std::nullopt;
m.currency = std::string(amount->Str("currency"));
const auto minor = ParseSignedAmountToMinor(amount->Str("value"));
if (!minor) return std::nullopt;
m.amountMinor = *minor;
if (const Json::Value* cp = pay->Find("counterparty_alias"); cp && cp->IsObject()) {
// The IBAN sits either directly on the alias or under its
// "labelMonetaryAccount"/"iban", depending on the payload flavour.
m.counterpartyIban = std::string(cp->Str("iban"));
if (m.counterpartyIban.empty()) {
if (const Json::Value* lma = cp->Find("labelMonetaryAccount");
lma && lma->IsObject()) {
m.counterpartyIban = std::string(lma->Str("iban"));
}
}
}
m.description = std::string(pay->Str("description"));
if (const std::int64_t acct = pay->Int("monetary_account_id"); acct != 0) {
m.account = std::format("{}", acct);
}
// "2026-08-14 09:31:02.123456" -> "2026-08-14". Only the date is kept, and
// only to stamp the page's as-of line; the time is dropped here, at the
// parser, so no later code can publish it by accident.
if (const std::string_view created = pay->Str("created"); created.size() >= 10) {
m.created = std::string(created.substr(0, 10));
}
return m;
}
FinancialRules LoadFinancialRules(std::string_view json) {
FinancialRules out;
auto doc = Json::Parse(json);
if (!doc || !doc->IsObject()) return out;
if (const Json::Value* a = doc->Find("donation_accounts"); a && a->IsArray()) {
for (const Json::Value& v : a->array) {
if (v.type == Json::Type::String) out.donationAccounts.push_back(v.string);
else if (v.type == Json::Type::Number) {
out.donationAccounts.push_back(
std::format("{}", static_cast<std::int64_t>(v.number)));
}
}
}
if (const Json::Value* a = doc->Find("rules"); a && a->IsArray()) {
for (const Json::Value& v : a->array) {
if (!v.IsObject()) continue;
FinancialRule r;
r.iban = LowerF(v.Str("iban"));
r.descriptionContains = LowerF(v.Str("description_contains"));
r.account = std::string(v.Str("account"));
r.group = std::string(v.Str("group"));
r.label = std::string(v.Str("label"));
// A rule with no criterion would claim every mutation, which is
// the exact opposite of default-deny. A rule whose group is not
// one this code understands is a typo, and a typo must not
// silently become a published category.
const bool hasCriterion = !r.iban.empty() || !r.descriptionContains.empty()
|| !r.account.empty();
const bool knownGroup = r.group == "donations" || r.group == "expense"
|| r.group == "ignore";
if (!hasCriterion || !knownGroup) continue;
// An expense needs a label to render under; donations and ignore
// do not have one.
if (r.group == "expense" && r.label.empty()) continue;
out.rules.push_back(std::move(r));
}
}
return out;
}
MutationClass ClassifyMutation(const BankMutation& m, const FinancialRules& rules) {
MutationClass out;
// Only euro. A foreign-currency mutation has no place in a euro total and
// converting one here would invent a rate.
if (m.currency != "EUR") return out;
const std::string iban = LowerF(m.counterpartyIban);
const std::string description = LowerF(m.description);
// Explicit rules first, so an "ignore" can carve an exception out of a
// donation account — the owner moving money between their own accounts
// must not read as a gift.
for (const FinancialRule& r : rules.rules) {
if (!r.iban.empty() && r.iban != iban) continue;
if (!r.account.empty() && r.account != m.account) continue;
if (!r.descriptionContains.empty()
&& description.find(r.descriptionContains) == std::string::npos) {
continue;
}
out.group = r.group;
out.label = r.label;
return out;
}
// The donation-account default: money ARRIVING on an account dedicated to
// donations is a donation. Keyed on the account rather than the sender
// because donors are strangers — an IBAN allowlist cannot know them, and
// this is the one category that must work for someone who has never paid
// this company before.
if (m.amountMinor > 0
&& std::find(rules.donationAccounts.begin(), rules.donationAccounts.end(), m.account)
!= rules.donationAccounts.end()) {
out.group = "donations";
}
return out;
}
void ApplyMutation(Financials& fin, const MutationClass& cls, const BankMutation& m) {
auto bump = [&](std::vector<FinCategory>& cats) {
for (FinCategory& c : cats) {
if (c.label == cls.label) {
// Outgoing money is negative on the wire and an expense is a
// positive total, so the sign flips here. A refund from a
// supplier arrives positive and correctly REDUCES the
// category rather than appearing as income.
c.totalMinor += -m.amountMinor;
return;
}
}
cats.push_back(FinCategory{ cls.label, -m.amountMinor });
};
if (cls.group == "donations") {
fin.donationsMinor += m.amountMinor;
// The count follows money in, not money out: a refunded donation
// reduces the total without pretending the gift never happened.
if (m.amountMinor > 0) ++fin.donationCount;
} else if (cls.group == "expense") {
bump(fin.expenses);
} else {
return; // "ignore" and unclassified touch nothing
}
// The page's freshness line. Never moves backwards: callbacks can arrive
// out of order, and an as-of date that jumped back a week would read as a
// stall that never happened.
if (!m.created.empty() && m.created > fin.asOf) fin.asOf = m.created;
}
// ── configuration and the live aggregates ─────────────────────────────
void ConfigureFinancials(FinancialsConfig config) {
std::lock_guard lock(gFinMutex);
gFinCfg = std::move(config);
@ -467,94 +56,4 @@ Financials CurrentFinancials() {
return LoadFinancials(ReadStateFile(gFinCfg.publicPath));
}
bool BunqCallbackConfigured() {
std::lock_guard lock(gFinMutex);
return !gFinCfg.callbackSecret.empty() && !gFinCfg.publicPath.empty();
}
bool BunqCallbackAuthorised(std::string_view pathSecret, std::string_view body,
std::string_view signatureB64) {
std::filesystem::path pubkey;
{
std::lock_guard lock(gFinMutex);
if (gFinCfg.callbackSecret.empty()) return false;
if (!SecretEqual(pathSecret, gFinCfg.callbackSecret)) return false;
pubkey = gFinCfg.publicKeyPem;
}
if (pubkey.empty()) return true; // signature checking not enabled
return SignatureValid(body, signatureB64, pubkey);
}
BunqIngestResult IngestBunqNotification(std::string_view body) {
std::lock_guard lock(gFinMutex);
if (gFinCfg.publicPath.empty()) return BunqIngestResult::Ignored;
const auto mutation = ParseBunqMutation(body);
if (!mutation) {
// Deliberately NOT an error status: bunq retries a non-2xx, so a
// payload shape this parser does not understand would become an
// endless redelivery loop. It is logged instead, and the weekly pull
// is what recovers the money. The log names no field VALUES — the
// point of the log is which shape arrived, not what it said.
std::println(std::cerr,
"catcrafts-server: bunq callback carried no recognisable "
"mutation ({} bytes); the weekly reconciliation will pick "
"it up", body.size());
return BunqIngestResult::Ignored;
}
SeenLedger seen = LoadSeen(ReadStateFile(gFinCfg.seenPath));
if (seen.Has(mutation->id)) return BunqIngestResult::Duplicate;
const FinancialRules rules = LoadFinancialRules(ReadStateFile(gFinCfg.rulesPath));
const MutationClass cls = ClassifyMutation(*mutation, rules);
// Recorded as seen either way: an unclassified mutation must not be
// re-counted as pending on every redelivery, and once a rule exists for
// it the weekly pull is what brings the money in.
seen.ids.push_back(mutation->id);
BunqIngestResult result = BunqIngestResult::Withheld;
if (cls.group.empty()) {
++seen.pendingCount;
seen.pendingMinor += mutation->amountMinor;
std::println(std::cerr,
"catcrafts-server: bunq mutation {} matched no rule and is "
"WITHHELD from /financials ({} awaiting classification, "
"{} cents net). Add a rule to {}.",
mutation->id, seen.pendingCount, seen.pendingMinor,
gFinCfg.rulesPath.string());
} else if (cls.group == "ignore") {
result = BunqIngestResult::Ignored;
} else {
Financials fin = LoadFinancials(ReadStateFile(gFinCfg.publicPath));
ApplyMutation(fin, cls, *mutation);
// First publication: a file that has never been written has no as-of
// date, and a mutation with no usable created stamp still has to
// produce one or the page would keep saying nothing is published.
if (fin.asOf.empty()) {
fin.asOf = mutation->created.empty() ? std::string("1970-01-01")
: mutation->created;
}
if (!WriteStateFileAtomic(gFinCfg.publicPath, SerialiseFinancials(fin))) {
std::println(std::cerr,
"catcrafts-server: could not write the financials "
"aggregates to {}", gFinCfg.publicPath.string());
return BunqIngestResult::Failed;
}
result = BunqIngestResult::Applied;
}
if (!WriteStateFileAtomic(gFinCfg.seenPath, SerialiseSeen(seen))) {
// The money is already published; losing the dedup entry only risks a
// double count on redelivery, so say so loudly rather than fail the
// request and guarantee that redelivery.
std::println(std::cerr,
"catcrafts-server: could not write the financials ingest "
"ledger to {} — a redelivered callback may double-count",
gFinCfg.seenPath.string());
}
return result;
}
} // namespace Catcrafts::Server

56
server/implementations/Catcrafts.Server-Http.cpp
View file

@ -76,10 +76,10 @@ PaymentRails gRails;
std::string gRedirectBase = "https://catcrafts.net";
// The bank-derived aggregates for /financials live in Catcrafts.Server-
// Financials.cpp, which owns their file and the bunq callback that updates
// them. They are read through CurrentFinancials() per request rather than
// cached: unlike the content files they CAN change under a running process,
// and live is the page's whole promise.
// Financials.cpp, which owns their file. They are read through
// CurrentFinancials() per request rather than cached: unlike the content
// files they CAN change under a running process, and live is the page's
// whole promise.
// The reconciler's sweep cadence: the shortest interval any configured rail
// asks for. Each order is still paced by ITS OWN rail's interval inside the
@ -98,12 +98,6 @@ std::chrono::seconds SweepInterval() {
return out;
}
// The callback URL's fixed prefix; everything after it is the shared secret.
// Under /api because Caddy proxies that prefix straight through and the
// analytics ingest censors it out of the public report (deploy/README.md) —
// a URL carrying a secret must not end up on a page anyone can read.
inline constexpr std::string_view kBunqCallbackPrefix = "/api/bunq/";
std::string ReadFile(const std::filesystem::path& p) {
std::ifstream in(p, std::ios::binary);
if (!in) return {};
@ -1132,48 +1126,6 @@ int Serve(std::uint16_t port) {
};
auto fallback = [](const HTTPRequest& req) -> HTTPResponse {
// The bunq mutation callback. Handled here rather than through
// ParseRoute because the path carries a SECRET — the shared route
// table is compiled into the wasm bundle that ships to every browser,
// and a secret has no business being in it.
//
// Everything unauthorised answers 404, never 401: the endpoint should
// not confirm its own existence to a prober, exactly as an unknown
// order token does not confirm the shape of a real one.
if (const std::string_view path = PathWithoutQueryHTTP(req.path);
path.starts_with(kBunqCallbackPrefix)) {
HTTPResponse res;
res.headers["content-type"] = "text/plain; charset=utf-8";
res.headers["cache-control"] = "no-store";
res.headers["x-robots-tag"] = "noindex, nofollow";
const std::string_view secret = path.substr(kBunqCallbackPrefix.size());
if (!BunqCallbackConfigured() || req.method != "POST"
|| req.body.size() > Form::kMaxBodyBytes) {
res.status = "404";
res.body = "Not found\n";
return res;
}
std::string_view signature;
if (const auto h = req.headers.find("x-bunq-server-signature");
h != req.headers.end()) {
signature = h->second;
}
if (!BunqCallbackAuthorised(secret, req.body, signature)) {
res.status = "404";
res.body = "Not found\n";
return res;
}
// 200 for everything the endpoint understood, including a
// withheld or duplicate mutation: those are correct outcomes, and
// a non-2xx would make bunq redeliver a callback that was already
// handled exactly as intended. Only a failed WRITE earns a 500,
// because a retry of that genuinely could succeed.
const BunqIngestResult result = IngestBunqNotification(req.body);
res.status = result == BunqIngestResult::Failed ? "500" : "200";
res.body = result == BunqIngestResult::Failed ? "Could not record\n" : "OK\n";
return res;
}
// A POST to a product page is a checkout submission.
if (req.method == "POST") {
const Route route = ParseRoute(PathWithoutQueryHTTP(req.path));

19
server/implementations/main.cpp
View file

@ -243,26 +243,13 @@ int main(int argc, char** argv) {
}
Server::SetOrdersPath(ordersPath);
// The /financials aggregates and the bunq callback that feeds them.
// Same derivation convention as the rail marker and the shipping
// cache: state hangs off the orders path. The secret is the last
// segment of the callback URL and is what enables the endpoint at
// all; unset means /api/bunq/* is a plain 404. No bunq API KEY is
// ever read here — see Catcrafts.Server-Financials.cpp for why.
// The /financials aggregates. Same derivation convention as the rail
// marker and the shipping cache: state hangs off the orders path. The
// file is written by the owner's tooling and only read here.
{
Server::FinancialsConfig finCfg;
finCfg.publicPath = ordersPath;
finCfg.publicPath += ".financials.json";
finCfg.seenPath = ordersPath;
finCfg.seenPath += ".financials-seen.json";
finCfg.rulesPath = ordersPath;
finCfg.rulesPath += ".financial-rules.json";
if (const char* v = std::getenv("BUNQ_CALLBACK_SECRET"); v && *v) {
finCfg.callbackSecret = v;
}
if (const char* v = std::getenv("BUNQ_CALLBACK_PUBKEY"); v && *v) {
finCfg.publicKeyPem = v;
}
Server::ConfigureFinancials(std::move(finCfg));
}
Server::LoadContent(contentDir, bundleIndex);

101
server/interfaces/Catcrafts.Server.cppm
View file

@ -139,36 +139,17 @@ export namespace Catcrafts::Server {
// ── the bank side of /financials ──────────────────────────────────
//
// Donations and expenses come from a bank mutation callback rather than
// from an API key on this box: a bunq key can INITIATE PAYMENTS and has
// no read-only scope, so the key stays on the owner's machine (IP-bound)
// and is used there once to register a notification filter. From then on
// bunq pushes mutations here, and the server can learn that money moved
// without being able to move any.
//
// What crosses this boundary is deliberately small. A mutation is
// classified, its amount lands in a category total, its opaque id goes in
// a dedup ledger, and the name, IBAN and description are dropped before
// anything is written. Classification is default-deny: money no rule
// claims is withheld from the page and logged, never published as a guess.
// The owner's weekly pull recomputes every total from the full bunq
// history and overwrites the aggregates file, which is what makes this
// path safe to be lossy.
// Bank-side donations and expenses come from an aggregates file written
// by the owner's own tooling, off this box — no bank credential and no
// bank callback exists here (the bunq mutation callback was retired
// 2026-08-17; its code is in git history). Aggregates by construction:
// category totals and an as-of date are all the file can carry, which is
// the page's privacy design.
struct FinancialsConfig {
std::filesystem::path publicPath; // <orders>.financials.json — what
// the page reads; also written by
// the owner's reconciliation
std::filesystem::path seenPath; // <orders>.financials-seen.json —
// ingested mutation ids, so a
// redelivery cannot double-count
std::filesystem::path rulesPath; // <orders>.financial-rules.json —
// the classifier, authored by hand
std::string callbackSecret; // BUNQ_CALLBACK_SECRET; the last
// path segment of the callback
// URL. Empty = endpoint disabled
std::filesystem::path publicKeyPem; // BUNQ_CALLBACK_PUBKEY; empty =
// signature checking off
// the page reads; written by the
// owner's reconciliation
};
void ConfigureFinancials(FinancialsConfig config);
@ -177,72 +158,6 @@ export namespace Catcrafts::Server {
// published yet, which the page states rather than showing zeros.
Financials CurrentFinancials();
// One bank mutation, reduced to what a total needs. Everything
// identifying is dropped by the classifier and never persisted.
struct BankMutation {
std::string id; // bunq's opaque id — the dedup key
std::int64_t amountMinor = 0; // SIGNED: negative is money leaving
std::string currency; // only EUR is ever counted
std::string counterpartyIban; // classifier input; never stored
std::string description; // classifier input; never stored
std::string account; // monetary account id
std::string created; // ISO date only — the time is
// dropped at the parser
};
// One classification rule. A rule matches when every criterion it states
// matches; the first matching rule wins. `group` is "donations",
// "expense" or "ignore" — anything else is a typo and the rule is dropped
// at load rather than inventing a category. (Expenses were once split
// into recurring/one-off; see Financials::expenses for why that went.)
struct FinancialRule {
std::string iban; // exact, case-insensitive
std::string descriptionContains; // substring, case-insensitive
std::string account; // monetary account id
std::string group;
std::string label; // the page's category name
};
struct FinancialRules {
// Accounts whose INCOMING money is a donation by default. Keyed on
// the account because donors are strangers: no IBAN list can know
// them in advance.
std::vector<std::string> donationAccounts;
std::vector<FinancialRule> rules;
};
// Empty group = no rule claimed it. That is the default-deny answer, and
// the caller must withhold rather than guess.
struct MutationClass {
std::string group;
std::string label;
};
// Pure and exported for the self-test.
std::optional<std::int64_t> ParseSignedAmountToMinor(std::string_view s);
std::optional<BankMutation> ParseBunqMutation(std::string_view json);
FinancialRules LoadFinancialRules(std::string_view json);
MutationClass ClassifyMutation(const BankMutation& m, const FinancialRules& rules);
void ApplyMutation(Financials& fin, const MutationClass& cls, const BankMutation& m);
// Whether the callback endpoint exists at all. Unconfigured, the path is
// a plain 404 — an endpoint that is off should not announce itself.
bool BunqCallbackConfigured();
// Constant-time secret check, plus the RSA-SHA256 body signature when a
// public key is configured. False means 404, for the same reason an
// unknown order token is: a probe learns nothing from the shape.
bool BunqCallbackAuthorised(std::string_view pathSecret, std::string_view body,
std::string_view signatureB64);
enum class BunqIngestResult { Applied, Duplicate, Withheld, Ignored, Failed };
// Parse, classify, and fold one notification into the aggregates. Never
// reports a transport-level error for an unparseable body: bunq retries
// non-2xx, so an unknown payload shape would redeliver forever. It is
// logged and left to the weekly reconciliation instead.
BunqIngestResult IngestBunqNotification(std::string_view body);
// ── invoices ──────────────────────────────────────────────────────
//
// A paid order's invoice: plain markdown, clearsigned with the shop's