Files
moloapp/example/app/ai/OpenaiAdminDemo.cpp
retoorandClaude Sonnet 5.5 9e550889cc feat(clients): openai admin: organization admin API, usage, costs, audit logs, webhooks
121-call table checked against the OpenAI OpenAPI document, admin-key-only
client, destructive guards, WebhookVerifier (Standard Webhooks HMAC-SHA256),
demo routes under /ai/openai/admin, local and opt-in live tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-24 07:43:17 +02:00

453 lines
18 KiB
C++

#include "../AiDemos.hpp"
#include <optional>
#include "../../fw/Router.hpp"
#include "../../fw/Templates.hpp"
#include "openai/admin/admin_client.h"
#include "openai/admin/audit_log.h"
#include "openai/admin/call_runner.h"
#include "openai/admin/calls.h"
#include "openai/admin/caps.h"
#include "openai/admin/usage.h"
#include "openai/admin/webhooks.h"
namespace molo::example::app {
// OpenAI organization administration over src/openai/admin. GET routes need
// no credential. Every route that calls OpenAI is a POST: 422 on bad input
// first, then 503 openai_admin_not_configured without OPENAI_ADMIN_KEY (the
// webhook endpoint calls use OPENAI_API_KEY and are refused an admin key).
// Destructive calls (delete, archive, deactivate, retention change, secret
// rotation) are dry runs unless the body says "confirm":true. The webhook
// verify route is local: it needs no credential.
namespace {
namespace adm = openai::admin;
using Json = clients::body::Json;
constexpr std::size_t kMaxBody = 256 * 1024;
const char kPage[] = R"OAADMIN({% extends "base.html" %}
{% block content %}
<h1>OpenAI administration</h1>
<p class="hint">Organization admin API: users, invites, projects, keys, rate limits,
certificates, groups and roles, usage, costs, audit logs, webhooks. Needs an admin key
(<code>OPENAI_ADMIN_KEY</code>); a regular key is refused.</p>
<p id="oaa-config" class="hint">Checking credentials...</p>
<section class="oaa">
<label>Call
<select id="oaa-call"></select></label>
<label>Path ids (comma separated, in path order) <input id="oaa-ids" type="text" maxlength="600"></label>
<label>Query (JSON object) <textarea id="oaa-query" rows="2">{}</textarea></label>
<label>Body (JSON object, mutating calls) <textarea id="oaa-body" rows="3">{}</textarea></label>
<label class="oaa-check"><input id="oaa-confirm" type="checkbox"> confirm destructive call</label>
<div class="oaa-actions">
<button id="oaa-run" type="button" class="primary">Run</button>
</div>
<h2>Usage and costs</h2>
<label>Endpoint
<select id="oaa-usage-kind"></select></label>
<label>Start (unix seconds) <input id="oaa-start" type="number" min="1"></label>
<label>Bucket width
<select id="oaa-bucket"><option>1d</option><option>1h</option><option>1m</option></select></label>
<div class="oaa-actions">
<button id="oaa-usage" type="button">Usage</button>
<button id="oaa-costs" type="button">Costs</button>
<button id="oaa-audit" type="button">Audit logs</button>
</div>
<h2>Verify a webhook</h2>
<label>Signing secret <input id="oaa-secret" type="password" maxlength="512" autocomplete="off"></label>
<label>Headers (webhook-id, webhook-timestamp, webhook-signature as JSON)
<textarea id="oaa-wh-headers" rows="3">{}</textarea></label>
<label>Raw body <textarea id="oaa-wh-body" rows="3"></textarea></label>
<div class="oaa-actions"><button id="oaa-verify" type="button">Verify</button></div>
<p id="oaa-error" class="error" role="alert"></p>
<pre id="oaa-out" class="oaa-out"></pre>
</section>
<style>
.oaa label{display:block;margin:.5rem 0}
.oaa input[type=text],.oaa input[type=number],.oaa input[type=password],.oaa textarea,.oaa select{width:100%;box-sizing:border-box}
.oaa-actions{display:flex;flex-wrap:wrap;gap:.5rem;margin:.5rem 0}
.oaa-out{overflow:auto;max-height:24rem;white-space:pre-wrap;word-break:break-word}
</style>
<script src="/embedded/ai_openai_admin.js"></script>
{% endblock %}
)OAADMIN";
fw::Response json_out(const Json& j, int status = 200) {
fw::Response res = fw::JsonResponse(j.dump(), status);
res.headers.set("Cache-Control", "no-store");
return res;
}
[[noreturn]] void bad(const std::string& why) { throw fw::HttpError(422, "validation_error", why); }
[[noreturn]] void rethrow(const llm::ApiError& e) {
if (e.http_status() == 503 && e.type() == "NOT_CONFIGURED")
throw fw::HttpError(503, "not_configured",
"OPENAI_ADMIN_KEY is not set (webhook endpoint calls need OPENAI_API_KEY)");
if (e.type() == "WRONG_KEY_KIND") throw fw::HttpError(503, "not_configured", e.message());
if (e.http_status() == 400 && e.type() == "INVALID_ARGUMENT")
throw fw::HttpError(422, "validation_error", e.message());
throw fw::HttpError(502, "openai_error", e.type() + ": " + e.message());
}
template <typename F>
auto guarded(F&& f) -> decltype(f()) {
try {
return f();
} catch (const llm::ApiError& e) {
rethrow(e);
}
}
Json parse_body(const fw::Request& req) {
if (req.body.size() > kMaxBody) throw fw::HttpError(413, "payload_too_large", "body too large");
if (req.body.empty()) return Json::object();
try {
Json j = Json::parse(req.body);
if (!j.is_object()) bad("body must be a JSON object");
return j;
} catch (const clients::body::JsonError&) {
bad("body is not valid JSON");
}
}
std::string text(const Json& b, const char* key, bool required = false) {
const Json* v = b.find(key);
if (!v || v->is_null()) {
if (required) bad(std::string(key) + " is required");
return "";
}
if (!v->is_string()) bad(std::string(key) + " must be a string");
return v->as_string();
}
std::vector<std::string> strings(const Json& b, const char* key) {
std::vector<std::string> out;
const Json* v = b.find(key);
if (!v || v->is_null()) return out;
if (!v->is_array()) bad(std::string(key) + " must be an array of strings");
for (const Json& e : v->as_array()) {
if (!e.is_string()) bad(std::string(key) + " must be an array of strings");
out.push_back(e.as_string());
}
return out;
}
std::optional<std::int64_t> number(const Json& b, const char* key) {
const Json* v = b.find(key);
if (!v || v->is_null()) return std::nullopt;
if (!v->is_number()) bad(std::string(key) + " must be a number");
return static_cast<std::int64_t>(v->as_int());
}
bool flag(const Json& b, const char* key) {
const Json* v = b.find(key);
if (!v || v->is_null()) return false;
if (!v->is_bool()) bad(std::string(key) + " must be true or false");
return v->as_bool();
}
adm::Region region_of(const Json& b) {
const std::string r = text(b, "region");
auto parsed = adm::Regions::parse(r);
if (!parsed) bad("region must be one of: global, us, eu, au, ca, jp, in, sg, kr, gb, ae");
return *parsed;
}
// Query object -> Query: scalars as one pair, arrays as repeated pairs.
adm::Query query_of(const Json& b) {
adm::Query q;
const Json* v = b.find("query");
if (!v || v->is_null()) return q;
if (!v->is_object()) bad("query must be an object");
for (const auto& [name, val] : v->as_object()) {
if (val.is_string()) q.set(name, val.as_string());
else if (val.is_number()) q.set_int(name, val.as_int());
else if (val.is_bool()) q.set_bool(name, val.as_bool());
else if (val.is_array()) {
std::vector<std::string> items;
for (const Json& e : val.as_array()) {
if (!e.is_string()) bad("query arrays hold strings");
items.push_back(e.as_string());
}
q.add_all(name, items);
} else bad("query value for " + name + " has an unsupported type");
}
return q;
}
adm::AuthKind kind_of(const std::string& key) {
const adm::CallSpec* spec = adm::CallTable::find(key);
if (!spec) bad("unknown call " + key);
return adm::CallTable::auth(spec->call);
}
// Runs one table row with the credential kind the row needs.
Json run_call(const Json& b, const std::string& key, bool confirm) {
const std::vector<std::string> ids = strings(b, "ids");
const adm::Query q = query_of(b);
const Json* body = b.find("body");
if (body && !body->is_null() && !body->is_object()) bad("body must be an object");
const Json* send = body && !body->is_null() ? body : nullptr;
const adm::Region region = region_of(b);
return guarded([&] {
if (kind_of(key) == adm::AuthKind::kProject)
return adm::CallRunner(adm::ProjectApiClient::from_env(region)).run(key, ids, q, send, confirm);
return adm::CallRunner(adm::AdminApiClient::from_env(region)).run(key, ids, q, send, confirm);
});
}
adm::UsageQuery usage_query(const Json& b) {
adm::UsageQuery u;
auto start = number(b, "start_time");
if (!start) bad("start_time is required");
u.start_time = *start;
u.end_time = number(b, "end_time");
u.bucket_width = text(b, "bucket_width");
if (auto l = number(b, "limit")) u.limit = static_cast<int>(*l);
u.page = text(b, "page");
u.project_ids = strings(b, "project_ids");
u.user_ids = strings(b, "user_ids");
u.api_key_ids = strings(b, "api_key_ids");
u.models = strings(b, "models");
if (b.find("batch") && !b.find("batch")->is_null()) u.batch = flag(b, "batch");
u.group_by = strings(b, "group_by");
u.sources = strings(b, "sources");
u.sizes = strings(b, "sizes");
u.vector_store_ids = strings(b, "vector_store_ids");
u.context_levels = strings(b, "context_levels");
return u;
}
} // namespace
void register_ai_openaiadmin_demo(fw::Router& router, Services& services) {
fw::Environment* env = services.templates.get();
services.templates->add_template("ai_openai_admin.html", kPage);
services.add_feature("OpenAI administration", "/ai/openai/admin");
router.get("/ai/openai/admin", "ai-openai-admin-page", [env](fw::Request req) {
(void)req;
fw::TemplateCtx ctx;
ctx["title"] = std::string("OpenAI administration");
return fw::Response(200, env->render("ai_openai_admin.html", ctx), "text/html; charset=utf-8");
});
router.get("/ai/openai/admin/status", "ai-openai-admin-status", [](fw::Request req) {
(void)req;
Json o = Json::object();
bool admin_ok = false, key_ok = true;
try {
admin_ok = adm::AdminApiClient::from_env()->configured();
} catch (const llm::ApiError&) {
key_ok = false;
}
bool hooks = false;
try {
hooks = adm::ProjectApiClient::from_env()->configured();
} catch (const llm::ApiError&) {
}
o.set("configured", Json(admin_ok));
o.set("admin_key_kind_ok", Json(key_ok));
o.set("webhook_management_configured", Json(hooks));
o.set("calls", Json(static_cast<int>(adm::CallTable::size())));
o.set("audit_event_types", Json(static_cast<int>(adm::AuditEventCatalog::all().size())));
o.set("max_list_pages", Json(adm::AdminCaps::kMaxListPages));
Json regions = Json::array();
for (adm::Region r : adm::Regions::all()) regions.push(Json(adm::Regions::base_url(r)));
o.set("regions", regions);
Json counters = Json::object();
for (const auto& [k, v] : adm::WebhookCounters::snapshot()) counters.set(k, Json(static_cast<long>(v)));
o.set("webhook_counters", counters);
return json_out(o);
});
router.get("/ai/openai/admin/calls", "ai-openai-admin-calls", [](fw::Request req) {
(void)req;
Json arr = Json::array();
for (std::size_t i = 0; i < adm::CallTable::size(); ++i) {
const adm::CallSpec& s = adm::CallTable::at(i);
Json r = Json::object();
r.set("key", Json(s.key));
r.set("method", Json(s.http_method));
r.set("path", Json(s.path));
r.set("op", Json(s.op_id));
r.set("auth", Json(s.auth));
r.set("destructive", Json(adm::CallTable::destructive(s.call)));
Json ids = Json::array();
for (const std::string& p : adm::CallTable::path_params(s.call)) ids.push(Json(p));
r.set("ids", ids);
arr.push(r);
}
Json o = Json::object();
o.set("calls", arr);
Json usage = Json::array();
for (adm::UsageKind k : adm::UsageEndpoints::all()) usage.push(Json(adm::UsageEndpoints::name(k)));
o.set("usage_kinds", usage);
return json_out(o);
});
router.get("/ai/openai/admin/audit-events", "ai-openai-admin-audit-events", [](fw::Request req) {
(void)req;
Json arr = Json::array();
for (const std::string& e : adm::AuditEventCatalog::all()) arr.push(Json(e));
Json o = Json::object();
o.set("event_types", arr);
return json_out(o);
});
router.get("/ai/openai/admin/webhook-events", "ai-openai-admin-webhook-events", [](fw::Request req) {
(void)req;
Json sent = Json::array(), sub = Json::array();
for (const std::string& e : adm::WebhookEvents::sent()) sent.push(Json(e));
for (const std::string& e : adm::WebhookEvents::subscribable()) sub.push(Json(e));
Json o = Json::object();
o.set("sent", sent);
o.set("subscribable", sub);
return json_out(o);
});
// Read-only: any GET row of the table.
router.post("/ai/openai/admin/read", "ai-openai-admin-read", [](fw::Request req) {
Json b = parse_body(req);
std::string key = text(b, "call", true);
const adm::CallSpec* spec = adm::CallTable::find(key);
if (!spec) bad("unknown call " + key);
if (std::string(spec->http_method) != "GET") bad(key + " is not a read; use /write or /destroy");
return json_out(run_call(b, key, false));
});
// Mutating, not destructive (create, update, activate, set limits).
router.post("/ai/openai/admin/write", "ai-openai-admin-write", [](fw::Request req) {
Json b = parse_body(req);
std::string key = text(b, "call", true);
const adm::CallSpec* spec = adm::CallTable::find(key);
if (!spec) bad("unknown call " + key);
if (std::string(spec->http_method) == "GET") bad(key + " is a read; use /read");
if (adm::CallTable::destructive(spec->call)) bad(key + " is destructive; use /destroy");
return json_out(run_call(b, key, false));
});
// Destructive: dry run unless "confirm":true.
router.post("/ai/openai/admin/destroy", "ai-openai-admin-destroy", [](fw::Request req) {
Json b = parse_body(req);
std::string key = text(b, "call", true);
const adm::CallSpec* spec = adm::CallTable::find(key);
if (!spec) bad("unknown call " + key);
if (!adm::CallTable::destructive(spec->call)) bad(key + " is not destructive");
const bool confirm = flag(b, "confirm");
if (!confirm) {
const std::vector<std::string> ids = strings(b, "ids");
std::string path;
try {
path = adm::CallTable::render(spec->call, ids);
} catch (const llm::ApiError& e) {
rethrow(e);
}
Json o = Json::object();
o.set("dry_run", Json(true));
o.set("would_call", Json(std::string(spec->http_method) + " " + path));
o.set("hint", Json("send confirm:true to run it"));
return json_out(o);
}
return json_out(run_call(b, key, true));
});
router.post("/ai/openai/admin/usage", "ai-openai-admin-usage", [](fw::Request req) {
Json b = parse_body(req);
auto kind = adm::UsageEndpoints::parse(text(b, "kind", true));
if (!kind) bad("unknown usage kind");
adm::UsageQuery q = usage_query(b);
const bool walk = flag(b, "walk");
const adm::Region region = region_of(b);
return guarded([&] {
adm::Usage usage(adm::AdminApiClient::from_env(region));
return json_out(walk ? usage.walk(*kind, q).to_json() : usage.query(*kind, q));
});
});
router.post("/ai/openai/admin/costs", "ai-openai-admin-costs", [](fw::Request req) {
Json b = parse_body(req);
adm::CostQuery q;
auto start = number(b, "start_time");
if (!start) bad("start_time is required");
q.start_time = *start;
q.end_time = number(b, "end_time");
q.bucket_width = text(b, "bucket_width");
if (auto l = number(b, "limit")) q.limit = static_cast<int>(*l);
q.page = text(b, "page");
q.project_ids = strings(b, "project_ids");
q.api_key_ids = strings(b, "api_key_ids");
q.line_items = strings(b, "line_items");
q.group_by = strings(b, "group_by");
const bool walk = flag(b, "walk");
const adm::Region region = region_of(b);
return guarded([&] {
adm::Costs costs(adm::AdminApiClient::from_env(region));
return json_out(walk ? costs.walk(q).to_json() : costs.query(q));
});
});
router.post("/ai/openai/admin/audit", "ai-openai-admin-audit", [](fw::Request req) {
Json b = parse_body(req);
adm::AuditQuery q;
q.effective_at_gt = number(b, "effective_at_gt");
q.effective_at_gte = number(b, "effective_at_gte");
q.effective_at_lt = number(b, "effective_at_lt");
q.effective_at_lte = number(b, "effective_at_lte");
q.project_ids = strings(b, "project_ids");
q.event_types = strings(b, "event_types");
q.actor_ids = strings(b, "actor_ids");
q.actor_emails = strings(b, "actor_emails");
q.resource_ids = strings(b, "resource_ids");
if (b.find("tenant_only") && !b.find("tenant_only")->is_null()) q.tenant_only = flag(b, "tenant_only");
if (auto l = number(b, "limit")) q.limit = static_cast<int>(*l);
q.after = text(b, "after");
q.before = text(b, "before");
const bool walk = flag(b, "walk");
const adm::Region region = region_of(b);
return guarded([&] {
adm::AuditLogs logs(adm::AdminApiClient::from_env(region));
return json_out(walk ? logs.walk(q).to_json() : logs.list(q));
});
});
// Local: verifies a delivery with a secret the caller supplies.
router.post("/ai/openai/admin/webhook/verify", "ai-openai-admin-webhook-verify", [](fw::Request req) {
Json b = parse_body(req);
std::string secret = text(b, "secret", true);
std::string body = text(b, "body", true);
std::map<std::string, std::string> headers;
const Json* h = b.find("headers");
if (!h || !h->is_object()) bad("headers must be an object");
for (const auto& [k, v] : h->as_object()) {
if (!v.is_string()) bad("header values must be strings");
headers[k] = v.as_string();
}
std::int64_t tolerance = number(b, "tolerance_seconds").value_or(adm::AdminCaps::kDefaultToleranceSeconds);
std::int64_t now = number(b, "now").value_or(adm::WebhookVerifier::system_now());
return guarded([&] {
adm::WebhookVerifier verifier(secret, tolerance);
adm::VerifyResult r = verifier.verify(body, adm::WebhookHeaders::from(headers), now);
Json o = Json::object();
o.set("ok", Json(r.ok));
o.set("failure", Json(adm::webhook_failure_name(r.failure)));
o.set("reason", Json(r.reason));
if (r.ok) {
try {
o.set("event", adm::WebhookEnvelope::parse(body).to_json());
} catch (const llm::ApiError& e) {
o.set("event_error", Json(e.message()));
}
}
return json_out(o);
});
});
}
} // namespace molo::example::app