diff --git a/example/app/ai/OpenaiAdminDemo.cpp b/example/app/ai/OpenaiAdminDemo.cpp index 78103fa..fa66f88 100644 --- a/example/app/ai/OpenaiAdminDemo.cpp +++ b/example/app/ai/OpenaiAdminDemo.cpp @@ -1,13 +1,452 @@ #include "../AiDemos.hpp" +#include + #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 admin API, usage, costs, audit logs, webhooks. Stub: the module agent fills this in. +// 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 %} +

OpenAI administration

+

Organization admin API: users, invites, projects, keys, rate limits, +certificates, groups and roles, usage, costs, audit logs, webhooks. Needs an admin key +(OPENAI_ADMIN_KEY); a regular key is refused.

+

Checking credentials...

+
+ + + + + +
+ +
+

Usage and costs

+ + + +
+ + + +
+

Verify a webhook

+ + + +
+ +

+
+ + +{% 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 +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 strings(const Json& b, const char* key) { + std::vector 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 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(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 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 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(*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) { - (void)router; - (void)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(adm::CallTable::size()))); + o.set("audit_event_types", Json(static_cast(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(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 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(*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(*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 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 diff --git a/example/assets/ai_openai_admin.js b/example/assets/ai_openai_admin.js new file mode 100644 index 0000000..03dcff9 --- /dev/null +++ b/example/assets/ai_openai_admin.js @@ -0,0 +1,71 @@ +// OpenAI administration page: thin client over /ai/openai/admin/* (all limits server side). +(function () { + "use strict"; + var $ = function (id) { return document.getElementById(id); }; + var out = $("oaa-out"), err = $("oaa-error"); + var base = "/ai/openai/admin"; + var calls = []; + + function post(path, body) { + err.textContent = ""; + out.textContent = "..."; + return fetch(base + path, { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body) + }).then(function (res) { + return res.text().then(function (t) { + var j; + try { j = JSON.parse(t); } catch (e) { j = { message: t }; } + if (!res.ok) { err.textContent = j.message || ("HTTP " + res.status); out.textContent = ""; } + else { out.textContent = JSON.stringify(j, null, 2); } + }); + }).catch(function (e) { err.textContent = String(e); out.textContent = ""; }); + } + function json(id) { + try { return JSON.parse($(id).value || "{}"); } + catch (e) { err.textContent = id + " is not valid JSON"; return null; } + } + function current() { + for (var i = 0; i < calls.length; i++) if (calls[i].key === $("oaa-call").value) return calls[i]; + return null; + } + + fetch(base + "/status").then(function (r) { return r.json(); }).then(function (s) { + $("oaa-config").textContent = s.configured + ? "Admin key found." + : (s.admin_key_kind_ok ? "No admin key: calls answer 503 until OPENAI_ADMIN_KEY is set." + : "OPENAI_ADMIN_KEY is not an admin key (sk-admin-...); it is refused."); + }); + fetch(base + "/calls").then(function (r) { return r.json(); }).then(function (d) { + calls = d.calls; + $("oaa-call").innerHTML = calls.map(function (c) { + return ""; + }).join(""); + $("oaa-usage-kind").innerHTML = d.usage_kinds.map(function (k) { return ""; }).join(""); + }); + + $("oaa-run").onclick = function () { + var c = current(); if (!c) return; + var query = json("oaa-query"), body = json("oaa-body"); + if (!query || !body) return; + var payload = { + call: c.key, + ids: $("oaa-ids").value.split(",").map(function (s) { return s.trim(); }).filter(Boolean), + query: query + }; + if (c.method !== "GET" && Object.keys(body).length) payload.body = body; + if (c.destructive) payload.confirm = $("oaa-confirm").checked; + post(c.method === "GET" ? "/read" : (c.destructive ? "/destroy" : "/write"), payload); + }; + function usageBody() { + return { kind: $("oaa-usage-kind").value, start_time: Number($("oaa-start").value) || 0, bucket_width: $("oaa-bucket").value }; + } + $("oaa-usage").onclick = function () { post("/usage", usageBody()); }; + $("oaa-costs").onclick = function () { var b = usageBody(); delete b.kind; b.bucket_width = "1d"; post("/costs", b); }; + $("oaa-audit").onclick = function () { post("/audit", { limit: 20 }); }; + $("oaa-verify").onclick = function () { + var h = json("oaa-wh-headers"); if (!h) return; + post("/webhook/verify", { secret: $("oaa-secret").value, headers: h, body: $("oaa-wh-body").value }); + }; +})(); diff --git a/src/openai/admin/SPEC.md b/src/openai/admin/SPEC.md new file mode 100644 index 0000000..ebf03ba --- /dev/null +++ b/src/openai/admin/SPEC.md @@ -0,0 +1,193 @@ +# OpenAI organization administration - Specification + +Owned directory: `src/openai/admin/`. Namespace `molo::openai::admin`. Depends +on the `src/llm` foundation (`ApiClient`, `Service`, `Config`, `ApiError`) and +`src/security/crypto` (`Hmac`, `Base64`, `SecureRandom`). Plan: +`plans/17-llm-vendor-platforms.md`. + +## 1. Scope + +The OpenAI organization administration API (`/v1/organization/*`), the webhook +endpoint management API (`/v1/webhook_endpoints*`, `/v1/webhook_event_types`) +and webhook delivery verification. 121 calls in one table: + +- Admin API keys, users (and user role assignments), invites, groups (users, + role assignments), custom roles. +- Projects: create, list, get, modify, archive; project users, service + accounts (and their API keys), project API keys, rate limits, project + groups, data retention, model permissions, hosted tool permissions, spend + limit, spend alerts, certificates. +- Organization: certificates (upload, list, get, modify, delete, activate, + deactivate), spend limit, spend alerts, data retention, external storage. +- Usage (completions, embeddings, moderations, images, audio speeches, audio + transcriptions, vector stores, code interpreter sessions, file search calls, + web search calls, decisions), costs, audit logs (all filters, 149 event types). +- Webhooks: event catalog (30 payload shapes, 27 subscribable types), envelope + parser, `WebhookVerifier`, endpoint management (list, get, create, update, + delete, rotate secret, test, event types). +- Data residency: `residency` / `geography` on project create and modify, + `PublicProjectResidency` (15 values), regional hosts (`Regions`). + +Not here: Responses, chat and the rest of the inference API (`src/openai/core`), +files, batch, fine-tuning, vector stores, realtime (`src/openai/platform`). +ChatGPT-side admin products (Compliance API, SCIM) have no entry in the OpenAPI +document and are not implemented. + +## 2. Module map + +| File | Concern | +|---|---| +| `caps.h` | Static ceilings (`AdminCaps`) | +| `calls.h/.cpp` | The ONE call table (`kCalls`, 121 rows) and used schema fields (`kSchemas`); `CallTable::render`, `method`, `auth`, `destructive` | +| `admin_client.h/.cpp` | `AdminApiClient` (admin key only), `ProjectApiClient` (webhook endpoints, project key only), `KeyPolicy`, `Regions` | +| `admin_service.h/.cpp` | `AdminService : llm::Service`: `execute` runs one table row with all guards; `walk` | +| `validate.h/.cpp` | `Validate`: text, id, enum, email, range, count, epoch, https URL, `confirmed` | +| `query.h/.cpp` | `Query` (validated, percent-encoded), `ListOptions` | +| `page.h/.cpp` | `Page`, `PageWalker`, `WalkResult` (truncation reported) | +| `requests.h/.cpp` | Typed bodies: `InviteRequest`, `ProjectCreate`, `ProjectUpdate`, `ProjectUserCreate`, `UserUpdate`, `ServiceAccountCreate/Update/KeyCreate`, `ProjectApiKeyUpdate`, `RateLimitUpdate`, `CertificateUpload`, `SpendAlertSpec`, `SpendLimitSpec`, `RoleSpec/Update`, `ModelPermissions`, `HostedToolPermissions`, `DataRetention`, `ExternalStorageSpec`, `WebhookEndpointSpec` | +| `identity.h/.cpp` | `AdminApiKeys`, `Users`, `Invites`, `Groups`, `Roles` | +| `projects.h/.cpp` | `Projects`, `ProjectUsers`, `ServiceAccounts`, `ProjectApiKeys`, `RateLimits`, `ProjectGroups`, `ProjectPolicies` | +| `governance.h/.cpp` | `Certificates` (org or project scope), `SpendAlerts` (org or project scope), `OrganizationPolicies`, `ExternalStorage` | +| `usage.h/.cpp` | `UsageQuery`, `CostQuery`, `Usage`, `Costs`, `UsageSummary` | +| `audit_log.h/.cpp`, `audit_events.h/.cpp` | `AuditQuery`, `AuditLogs`, `AuditEventCatalog` | +| `webhook_events.h/.cpp` | `WebhookEvents` (catalog), `WebhookEvent`, `WebhookEnvelope` | +| `webhooks.h/.cpp` | `WebhookVerifier`, `WebhookHeaders`, `WebhookCounters`, `WebhookEndpoints` | +| `call_runner.h/.cpp` | `CallRunner`: any table row by key (used by the example's generic routes) | +| `openai_admin.h/.cpp` | `OpenaiAdmin` facade (all services on one client) | +| `crypto_link.cpp` | Link shim, see Gaps | +| `tools/check_spec.py` | Fails when the table, schemas, catalogs or coverage differ from the OpenAPI document | +| `tools/probe_paths.py` | Unauthenticated probe of every GET row | + +## 3. Static caps + +| Knob | Value | +|---|---| +| list page size | 1..100 (api), default 20 | +| page walk | 20 pages, 2000 items, then `truncated` with reason and resume cursor | +| usage buckets | 1d: 31, 1h: 168, 1m: 1440 (api); costs 1..180 (api) | +| filter arrays | 100 values of 256 chars; group_by 8; audit event_types 50 | +| cursor / token | 512 chars | +| names / email / description | 256 / 320 / 1024 chars | +| permissions per role / models per list / scopes / invite projects | 256 / 500 / 32 / 100 | +| key expiry | 1..31536000 s (api maximum) | +| certificate PEM | 64 KiB, no private key material accepted | +| certificate ids per toggle | 10 | +| request body | 256 KiB | +| webhook body | 1 MiB; signature header 4096 chars, 8 signatures | +| webhook tolerance | default 300 s, 0..3600 | +| webhook secret | decoded `whsec_` key at least 24 bytes | +| time values | unix seconds 1..4102444800 | + +Local choices, not API values: walk ceilings, filter and text limits, spend alert +recipients (1..10), rate limit values (0..1e12), the 3600 s tolerance ceiling. + +## 4. Contracts + +- Every URL comes from `kCalls`; ids go through `Service::valid_id`; query + names must be rows of the call (`effective_at[gt]` style object keys allowed + for `effective_at`); body fields must be in the row, required ones present. +- Input is validated before any traffic: `ApiError` 400 `INVALID_ARGUMENT`. + No credential: `NotConfiguredError` 503. +- Credentials. `AdminApiClient` reads `OPENAI_ADMIN_KEY` and refuses any key + not starting `sk-admin-` with 401 `WRONG_KEY_KIND` (message never echoes the + key). So a regular or project key can never reach `/organization/*`. The + OpenAPI document secures `/webhook_endpoints*` and `/webhook_event_types` + with the regular `ApiKeyAuth` ("endpoints of the authenticated project"), so + `WebhookEndpoints` takes a `ProjectApiClient` (`OPENAI_API_KEY`, admin keys + refused). A service built for one kind refuses rows of the other. +- Destructive rows (every DELETE plus `projects.archive`, + `certificates.deactivate`, `projects.certificates.deactivate`, + `data_retention.update`, `projects.data_retention.update`, + `webhook_endpoints.rotate_secret`) throw unless `confirm=true`; the typed + methods take `confirm` without a default. Example routes `/destroy` are + dry runs unless the body has `"confirm":true`. +- Secrets returned once (admin key create, service account and its key create, + webhook endpoint create and rotate) are in the answer only; nothing is logged. +- Lists report truncation (`WalkResult::truncated`), never silently. +- Webhook verification: see `webhooks.h`. Per Standard Webhooks as implemented + by openai-go: signed string `id.timestamp.body`, key from `whsec_` + (canonical base64, >= 24 bytes) or raw bytes, `v1,` entries, any + match accepted, constant-time compare (`SecureRandom::constant_time_equal`), + tolerance both directions. Stricter than openai-go: bare (unprefixed) and + non-`v1` entries are ignored. Rejections are counted per reason + (`WebhookCounters`, shown at `/status`). `unwrap` parses only after verifying. +- Region hosts `.api.openai.com` for us eu au ca jp in sg kr gb ae. + +## 5. Example routes (`/ai/openai/admin`) + +GET `/` (page), `/status`, `/calls`, `/audit-events`, `/webhook-events`. +POST `/read` (any GET row), `/write` (mutating, not destructive), `/destroy` +(destructive, dry run unless confirm), `/usage`, `/costs`, `/audit` (typed +queries, optional `walk`), `/webhook/verify` (local, no credential). Order: +422 on bad input, then 503 `not_configured`; oversize body 413. + +## Sources + +- OpenAI OpenAPI document, `openai/openai-openapi` `openapi.json` at commit + `8243cc8fa6f04430fb1f1a6a2cb926fbeb4f7f26` (2026-10-24, info.version 2.3.0, + the manual_spec branch is older and lacks groups, roles, spend, retention). + Paths, operation ids, security, parameters, bodies, schemas, the `webhooks` + map, `AuditLogEventType`, `PublicProjectResidency`, `ProjectEventTypeEnum`. +- Official openai-go SDK (`main`, `.castiron.stats.yml` carries no spec URL any + more): `api.md` and `webhooks/api.md` (method + path of every row), + `webhooks/webhook_helpers.go` and `webhook_secret.go` (verification + algorithm), `adminorganizationauditlog.go` (bracket array/nested query + format), `adminorganizationusage.go`. Python SDK tests + (`tests/api_resources/test_webhooks.py`) confirm `client.webhooks.*` endpoint + management. +- Standard Webhooks specification (`standard-webhooks/standard-webhooks` + `spec/standard-webhooks.md`): headers, `v1,` signature format, `whsec_`. +- Unauthenticated probes of `*.api.openai.com` (below). + +## Verified against spec + +`python3 -I src/openai/admin/tools/check_spec.py`, run 2026-10-24: `spec ok: +121 calls, 91 schemas, 121 in-scope spec operations covered, 149 audit event +types, 30 sent webhook event types, openai-go lists all 121 rows`. It checks +per row: method, path, operationId, security scheme, path and query +parameters (both directions), request schema name, body fields (both +directions), required fields, 200 response schema; every schema field read; +audit and webhook catalogs; usage `group_by` enums; webhook data fields; +and that no in-scope spec operation is unwrapped. `--head` checks the newest +`main`. + +## Verified live + +2026-10-24, no key, invalid key `sk-admin-invalid`: + +- `python3 -I src/openai/admin/tools/probe_paths.py`: all 58 GET paths of the + table answer 401, `/v1/organization/nonexistent_probe_path` answers 404. +- Error shape: 401 `{"error":{"message":"Incorrect API key provided: ...", + "type":"invalid_request_error","param":null,"code":"invalid_api_key"}}` + (`ApiError::type()` is `invalid_request_error`). +- Hosts `api`, `us`, `eu`, `au`, `ca`, `jp`, `in`, `sg`, `kr`, `gb`, `ae` + `.api.openai.com` resolve and answer 401 on `/v1/organization/users`. +- Opt-in test `openai_admin.live_read_only` (`MOLO_LIVE_NET=1`): invalid-key + probe passes; the read-only list calls (projects, users, limit 1) need + `OPENAI_ADMIN_KEY` and have not run (no key). + +## Unverified + +Everything that needs an admin key: the real shape of every response (typed +accessors read only the list envelope and usage/cost result numbers), whether +the server accepts repeated `name=` for usage arrays (spec form; the SDKs send +`name[]`), `effective_at[gte]` nesting (SDK form), that an admin key always +starts `sk-admin-` (docs examples; the check is a prefix test), the 400 and 404 +bodies of mutating calls, `include=content` for certificates, key expiry +maximum applying to admin keys (spec says so), external storage provider field +sets (from the spec's oneOf), `video.*` webhook payloads (selectable event +types without a payload schema), `live.transport.incoming` data fields (spec +lists a `type` inside `data`), spend amounts being cents (spec text for the +limit; assumed for alerts). The Standard Webhooks vector's signature was +recomputed with python3 hmac, not taken from OpenAI. Webhook delivery retry +behaviour is OpenAI's and untested. + +## Gaps + +- `src/ai.mk` compiles only `Base64.cpp` from `src/security/crypto`; until the + integration adds `Sha256.cpp`, `Hmac.cpp`, `SecureRandom.cpp` to `AI_SRCS`, + `crypto_link.cpp` includes them. Delete `crypto_link.cpp` then (duplicate + symbols otherwise). +- Typed response structs are not generated; responses are `Json`. +- No SCIM, Compliance API or ChatGPT workspace admin (no OpenAPI entries). +- Resume of a truncated walk restarts at the page that hit the ceiling. diff --git a/src/openai/admin/admin_client.cpp b/src/openai/admin/admin_client.cpp new file mode 100644 index 0000000..7c621f0 --- /dev/null +++ b/src/openai/admin/admin_client.cpp @@ -0,0 +1,111 @@ +#include "openai/admin/admin_client.h" + +#include +#include + +#include "clients/transports/http_transport.h" +#include "llm/config.h" +#include "llm/error.h" + +namespace molo::openai::admin { + +namespace { + +const char* const kCodes[] = {"", "us", "eu", "au", "ca", "jp", "in", "sg", "kr", "gb", "ae"}; + +// PublicProjectResidency of the OpenAPI document (checked by tools/check_spec.py). +const std::vector kResidency = { + "GLOBAL", "US_STORAGE_PROCESSING", "EU_STORAGE_PROCESSING", "JP_STORAGE", + "JP_STORAGE_PROCESSING", "KR_STORAGE", "CA_STORAGE", "SG_STORAGE", "IN_STORAGE", + "IN_STORAGE_PROCESSING", "AU_STORAGE", "AU_STORAGE_PROCESSING", "GB_STORAGE", "AE_STORAGE", + "AE_STORAGE_PROCESSING"}; + +llm::ApiClientConfig make_config(const char* key_env, Region region) { + llm::ApiClientConfig c; + c.vendor = "openai"; + c.base_url = Regions::base_url(region); + c.key_env = key_env; + c.auth = llm::AuthStyle::kBearer; + return c; +} + +} // namespace + +const std::vector& Regions::all() { + static const std::vector regions = {Region::kGlobal, Region::kUs, Region::kEu, + Region::kAu, Region::kCa, Region::kJp, + Region::kIn, Region::kSg, Region::kKr, + Region::kGb, Region::kAe}; + return regions; +} + +std::string Regions::code(Region region) { return kCodes[static_cast(region)]; } + +std::string Regions::base_url(Region region) { + const std::string c = code(region); + return c.empty() ? "https://api.openai.com/v1" : "https://" + c + ".api.openai.com/v1"; +} + +std::optional Regions::parse(const std::string& code_text) { + std::string c = code_text; + std::transform(c.begin(), c.end(), c.begin(), [](unsigned char ch) { return std::tolower(ch); }); + if (c.empty() || c == "global") return Region::kGlobal; + for (Region r : all()) + if (code(r) == c) return r; + return std::nullopt; +} + +std::optional Regions::from_residency(const std::string& residency) { + if (std::find(kResidency.begin(), kResidency.end(), residency) == kResidency.end()) + return std::nullopt; + if (residency == "GLOBAL") return Region::kGlobal; + std::string c = residency.substr(0, residency.find('_')); + return parse(c); +} + +const std::vector& Regions::residency_values() { return kResidency; } + +KeyKind KeyPolicy::classify(const std::string& key) { + if (key.empty()) return KeyKind::kNone; + return key.rfind(kAdminPrefix, 0) == 0 ? KeyKind::kAdmin : KeyKind::kProject; +} + +void KeyPolicy::require_admin(const std::string& key) { + if (classify(key) == KeyKind::kProject) + throw llm::ApiError("openai", 401, "WRONG_KEY_KIND", + "OPENAI_ADMIN_KEY must hold an admin key (sk-admin-...); regular and " + "project keys are never sent to the organization API"); +} + +void KeyPolicy::require_project(const std::string& key) { + if (classify(key) == KeyKind::kAdmin) + throw llm::ApiError("openai", 401, "WRONG_KEY_KIND", + "OPENAI_API_KEY holds an admin key; webhook endpoints are managed " + "with the regular project key"); +} + +std::shared_ptr AdminApiClient::with_transport( + std::unique_ptr transport, const std::string& key, Region region) { + KeyPolicy::require_admin(key); + return std::shared_ptr( + new AdminApiClient(std::move(transport), make_config(kEnv, region), key)); +} + +std::shared_ptr AdminApiClient::from_env(Region region) { + return with_transport(std::make_unique(), + llm::Config::get(kEnv), region); +} + +std::shared_ptr ProjectApiClient::with_transport( + std::unique_ptr transport, const std::string& key, Region region) { + KeyPolicy::require_project(key); + return std::shared_ptr( + new ProjectApiClient(std::move(transport), make_config(kEnv, region), key)); +} + +std::shared_ptr ProjectApiClient::from_env(Region region) { + return with_transport(std::make_unique(), + llm::Config::get(kEnv), region); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/admin_client.h b/src/openai/admin/admin_client.h new file mode 100644 index 0000000..60685e9 --- /dev/null +++ b/src/openai/admin/admin_client.h @@ -0,0 +1,80 @@ +#pragma once + +// Credential-typed HTTP clients for the OpenAI administration surface. +// +// AdminApiClient organization administration: bearer OPENAI_ADMIN_KEY only. +// A key that is not an admin key ("sk-admin-...") is refused +// at construction (WRONG_KEY_KIND), so a regular or project +// key can never reach /organization/*. +// ProjectApiClient webhook endpoint management only: bearer OPENAI_API_KEY. +// OpenAI's spec secures /webhook_endpoints with the regular +// project key; an admin key is refused here. +// +// The two classes are distinct types and the services take one or the other, +// so the credential kind is checked by the compiler as well as at runtime. + +#include +#include +#include +#include + +#include "llm/api_client.h" + +namespace molo::openai::admin { + +// Data residency: OpenAI serves each region from .api.openai.com +// (every host below answered 401 on an unauthenticated probe, 2026-10-24). +enum class Region { kGlobal, kUs, kEu, kAu, kCa, kJp, kIn, kSg, kKr, kGb, kAe }; + +class Regions { + public: + static const std::vector& all(); + static std::string code(Region region); // "" for global, "eu", "us", ... + static std::string base_url(Region region); // https://eu.api.openai.com/v1 + static std::optional parse(const std::string& code); // "", "global" -> kGlobal + // Residency enum value of the spec ("EU_STORAGE_PROCESSING") -> the host region it implies. + static std::optional from_residency(const std::string& residency); + static const std::vector& residency_values(); // PublicProjectResidency +}; + +enum class KeyKind { kNone, kAdmin, kProject }; + +class KeyPolicy { + public: + static constexpr const char* kAdminPrefix = "sk-admin-"; + static KeyKind classify(const std::string& key); + // Throws ApiError 401 WRONG_KEY_KIND (never echoes the key). + static void require_admin(const std::string& key); + static void require_project(const std::string& key); +}; + +class AdminApiClient final : public llm::ApiClient { + public: + static constexpr const char* kEnv = "OPENAI_ADMIN_KEY"; + // Key from llm::Config::get("OPENAI_ADMIN_KEY"); empty means not configured. + static std::shared_ptr from_env(Region region = Region::kGlobal); + static std::shared_ptr with_transport( + std::unique_ptr transport, const std::string& key, + Region region = Region::kGlobal); + + private: + AdminApiClient(std::unique_ptr transport, llm::ApiClientConfig config, + std::string key) + : llm::ApiClient(std::move(transport), std::move(config), std::move(key)) {} +}; + +class ProjectApiClient final : public llm::ApiClient { + public: + static constexpr const char* kEnv = "OPENAI_API_KEY"; + static std::shared_ptr from_env(Region region = Region::kGlobal); + static std::shared_ptr with_transport( + std::unique_ptr transport, const std::string& key, + Region region = Region::kGlobal); + + private: + ProjectApiClient(std::unique_ptr transport, llm::ApiClientConfig config, + std::string key) + : llm::ApiClient(std::move(transport), std::move(config), std::move(key)) {} +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/admin_service.cpp b/src/openai/admin/admin_service.cpp new file mode 100644 index 0000000..1c6195a --- /dev/null +++ b/src/openai/admin/admin_service.cpp @@ -0,0 +1,69 @@ +#include "openai/admin/admin_service.h" + +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +AdminService::AdminService(std::shared_ptr client) + : llm::Service(std::move(client)), auth_(AuthKind::kAdmin) {} + +AdminService::AdminService(std::shared_ptr client) + : llm::Service(std::move(client)), auth_(AuthKind::kProject) {} + +AdminService::Json AdminService::execute(Call call, const std::vector& ids, + const Query& query, const Json* body, bool confirm) { + const CallSpec& spec = CallTable::spec(call); + if (CallTable::auth(call) != auth_) + Validate::fail(std::string(spec.key) + " needs a " + spec.auth + + " credential; this service holds the other kind"); + if (CallTable::destructive(call)) Validate::confirmed(spec.key, confirm); + + std::string path = CallTable::render(call, ids); + query.check_against(call); + + Json checked; + const bool takes_body = spec.body_fields[0] != '\0'; + if (takes_body) { + checked = body ? *body : Json::object(); + if (!checked.is_object()) Validate::fail(std::string(spec.key) + " body must be an object"); + for (const auto& [name, value] : checked.as_object()) { + (void)value; + if (!CallTable::allows_body_field(call, name)) + Validate::fail(std::string(spec.key) + " has no body field " + name); + } + for (const std::string& req : CallTable::required_body_fields(call)) { + const Json* v = checked.find(req); + if (!v || v->is_null()) Validate::fail(std::string(spec.key) + " needs " + req); + } + if (checked.dump().size() > AdminCaps::kMaxBodyBytes) Validate::fail("request body over the cap"); + } else if (body) { + Validate::fail(std::string(spec.key) + " takes no body"); + } + + path += query.encoded(); + return client().request(CallTable::method(call), path, takes_body ? &checked : nullptr); +} + +WalkResult AdminService::walk(Call call, const std::vector& ids, const Query& base, + const std::string& cursor_param, const std::string& start_cursor) { + if (!CallTable::allows_query(call, cursor_param)) + Validate::fail(std::string(CallTable::spec(call).key) + " cannot be walked with " + cursor_param); + return PageWalker::walk( + [&](const std::string& cursor) { + Query q = base; + if (!cursor.empty()) q.set(cursor_param, cursor); + return execute(call, ids, q); + }, + start_cursor); +} + +AdminService::Json AdminService::object_of( + std::initializer_list> fields) { + Json o = Json::object(); + for (const auto& [k, v] : fields) + if (!v.is_null()) o.set(k, v); + return o; +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/admin_service.h b/src/openai/admin/admin_service.h new file mode 100644 index 0000000..55a828c --- /dev/null +++ b/src/openai/admin/admin_service.h @@ -0,0 +1,46 @@ +#pragma once + +// Base of every resource service. One `execute` runs one row of the call +// table: it checks the credential kind of the call, refuses destructive calls +// without confirm=true, renders the path from validated ids, checks query +// names and body fields against the row, and sends the request. A service is +// built for one credential kind; running a call of the other kind throws. + +#include +#include +#include + +#include "clients/body/json.h" +#include "llm/api_client.h" +#include "openai/admin/admin_client.h" +#include "openai/admin/calls.h" +#include "openai/admin/page.h" +#include "openai/admin/query.h" + +namespace molo::openai::admin { + +class AdminService : public llm::Service { + public: + using Json = clients::body::Json; + + AuthKind auth_kind() const { return auth_; } + + protected: + AdminService(std::shared_ptr client); + AdminService(std::shared_ptr client); + + // Runs one table row. `ids` fill the {placeholders} in order. `body` must be + // an object whose keys are allowed by the row and cover its required fields. + Json execute(Call call, const std::vector& ids = {}, const Query& query = {}, + const Json* body = nullptr, bool confirm = false); + // A cursor list walked to the page / item ceilings (WalkResult::truncated). + WalkResult walk(Call call, const std::vector& ids, const Query& base, + const std::string& cursor_param, const std::string& start_cursor = ""); + + static Json object_of(std::initializer_list> fields); + + private: + AuthKind auth_; +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/audit_events.cpp b/src/openai/admin/audit_events.cpp new file mode 100644 index 0000000..fb33aa8 --- /dev/null +++ b/src/openai/admin/audit_events.cpp @@ -0,0 +1,87 @@ +#include "openai/admin/audit_events.h" + +#include +#include + +namespace molo::openai::admin { + +// AUDIT-EVENTS-BEGIN (AuditLogEventType enum; checked by tools/check_spec.py) +static const char* const kAuditEvents[] = { + "api_key.created", "api_key.updated", "api_key.deleted", "certificate.created", + "certificate.updated", "certificate.deleted", "certificates.activated", + "certificates.deactivated", "checkpoint.permission.created", "checkpoint.permission.deleted", + "external_key.registered", "external_key.removed", "external_storage.registered", + "external_storage.removed", "group.created", "group.updated", "group.deleted", "invite.sent", + "invite.accepted", "invite.deleted", "ip_allowlist.created", "ip_allowlist.updated", + "ip_allowlist.deleted", "ip_allowlist.config.activated", "ip_allowlist.config.deactivated", + "login.succeeded", "login.failed", "logout.succeeded", "logout.failed", "organization.updated", + "project.created", "project.updated", "project.archived", "project.deleted", + "rate_limit.updated", "rate_limit.deleted", "resource.deleted", "tunnel.created", + "tunnel.updated", "tunnel.deleted", "workload_identity_provider.created", + "workload_identity_provider.updated", "workload_identity_provider.deleted", + "workload_identity_provider_mapping.created", "workload_identity_provider_mapping.updated", + "workload_identity_provider_mapping.deleted", "role.created", "role.updated", "role.deleted", + "role.assignment.created", "role.assignment.deleted", "role.bound_to_resource", + "role.unbound_from_resource", "scim.enabled", "scim.disabled", "service_account.created", + "service_account.updated", "service_account.deleted", "user.added", "user.updated", + "user.deleted", "tenant.metadata.updated", "tenant.microsoft_entra_mapping.upserted", + "tenant.microsoft_entra_mapping.deleted", "tenant.workload_identity.provider.created", + "tenant.workload_identity.provider.updated", "tenant.workload_identity.provider.archived", + "tenant.workload_identity.mapping.created", "tenant.workload_identity.mapping.updated", + "tenant.workload_identity.mapping.archived", "tenant.workload_identity.binding.created", + "tenant.workload_identity.principal.provisioned", + "tenant.workload_identity.access_token.issued", "tenant.admin_api_key.created", + "tenant.admin_api_key.updated", "tenant.admin_api_key.deleted", + "tenant.project_api_key.created", "tenant.trusted_access.business_verification.started", + "tenant.trusted_access.application.submitted", "tenant.chatgpt_access_token.revoked", + "tenant.migration.completed", "tenant.sso.migrated", "tenant.domains.migrated", + "tenant.sso_connection.created", "tenant.sso_connection.updated", + "tenant.sso_connection.deleted", "tenant.sso_connection.setup.started", + "tenant.policy.created", "tenant.policy.updated", "tenant.policy.deleted", + "tenant.policy.attached", "tenant.policy.detached", + "tenant.principal_authentication_policy.resolved", "tenant.scim.setup.started", + "tenant.scim.deletion.requested", "tenant.scim.directory.created", + "tenant.product_access_policy.updated", "tenant.resource_share_grant.created", + "tenant.resource_share_grant.updated", "tenant.resource_share_grant.accepted", + "tenant.resource_share_grant.declined", "tenant.resource_share_grant.revoked", + "tenant.resource_share_grant.deleted", "tenant.service_account.updated", + "tenant.service_account.deleted", "tenant.service_account.token.revoked", + "tenant.billing.overage_limit.updated", "tenant.billing.alerts.updated", + "tenant.billing.info.updated", "tenant.usage_limit.workspace.updated", + "tenant.usage_limit.group.updated", "tenant.usage_limit.user.updated", + "tenant.usage_limit.increase_request.updated", "tenant.usage_limit.increase_request.resolved", + "tenant.group.created", "tenant.group.updated", "tenant.group.deleted", + "tenant.group.member.added", "tenant.group.member.removed", + "tenant.migration_rollout.status.updated", "tenant.migration_rollout.tier.updated", + "tenant.role.metadata.updated", "tenant.custom_role.created", "tenant.custom_role.updated", + "tenant.custom_role.deleted", "tenant.role_assignment.created", + "tenant.role_assignment.deleted", "tenant.resource_role_assignment.created", + "tenant.resource_role_assignment.deleted", "tenant.resource_access.updated", + "tenant.resource_access.deleted", "tenant.ads_account.onboarding.redemption", + "tenant.session_policy.created", "tenant.session_policy.updated", + "tenant.session_policy.deleted", "tenant.session_revocation.started", + "tenant.third_party_app_policy.updated", "tenant.user.added", "tenant.user.updated", + "tenant.user.removed", "tenant.user.looked_up", "tenant.user.invited", + "tenant.membership.revoked", "tenant.api_organization_invite.upserted", + "tenant.api_organization_invite.deleted", "tenant.chatgpt_workspace_invite.upserted", + "tenant.membership.accepted", "tenant.membership.declined", + "tenant.workspace_invite_email_settings.updated", +}; +// AUDIT-EVENTS-END + +const std::vector& AuditEventCatalog::all() { + static const std::vector events(std::begin(kAuditEvents), std::end(kAuditEvents)); + return events; +} + +bool AuditEventCatalog::known(const std::string& type) { + const auto& events = all(); + return std::find(events.begin(), events.end(), type) != events.end(); +} + +std::string AuditEventCatalog::family(const std::string& type) { + const std::size_t dot = type.find('.'); + return dot == std::string::npos ? type : type.substr(0, dot); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/audit_events.h b/src/openai/admin/audit_events.h new file mode 100644 index 0000000..75dc1de --- /dev/null +++ b/src/openai/admin/audit_events.h @@ -0,0 +1,20 @@ +#pragma once + +// The audit log event type catalog: the `AuditLogEventType` enum of OpenAI's +// OpenAPI document, one string per type. `type` filters are validated against +// it before any request is sent. + +#include +#include + +namespace molo::openai::admin { + +class AuditEventCatalog { + public: + static const std::vector& all(); + static bool known(const std::string& type); + // Prefix before the first dot ("api_key", "project", "tenant", ...). + static std::string family(const std::string& type); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/audit_log.cpp b/src/openai/admin/audit_log.cpp new file mode 100644 index 0000000..ea87b48 --- /dev/null +++ b/src/openai/admin/audit_log.cpp @@ -0,0 +1,51 @@ +#include "openai/admin/audit_log.h" + +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +Query AuditQuery::to_query() const { + Query q; + const std::pair*> times[] = { + {"effective_at[gt]", &effective_at_gt}, {"effective_at[gte]", &effective_at_gte}, + {"effective_at[lt]", &effective_at_lt}, {"effective_at[lte]", &effective_at_lte}}; + for (const auto& [name, value] : times) { + if (!*value) continue; + Validate::epoch(name, **value); + q.set_int(name, **value); + } + if (effective_at_gt && effective_at_gte) Validate::fail("give effective_at gt or gte, not both"); + if (effective_at_lt && effective_at_lte) Validate::fail("give effective_at lt or lte, not both"); + q.add_all("project_ids[]", project_ids); + Validate::count("event_types", event_types.size(), AdminCaps::kMaxAuditEventTypes, true); + for (const std::string& t : event_types) + if (!AuditEventCatalog::known(t)) Validate::fail("unknown audit event type " + t); + q.add_all("event_types[]", event_types); + q.add_all("actor_ids[]", actor_ids); + for (const std::string& e : actor_emails) Validate::email(e); + q.add_all("actor_emails[]", actor_emails); + q.add_all("resource_ids[]", resource_ids); + if (tenant_only) q.set_bool("tenant_only", *tenant_only); + if (limit) { + Validate::range("limit", *limit, 1, AdminCaps::kMaxPageLimit); + q.set_int("limit", *limit); + } + if (!after.empty() && !before.empty()) Validate::fail("give after or before, not both"); + if (!after.empty()) q.set("after", after); + if (!before.empty()) q.set("before", before); + return q; +} + +AdminService::Json AuditLogs::list(const AuditQuery& query) { + return execute(Call::kAuditLogsList, {}, query.to_query()); +} + +WalkResult AuditLogs::walk(const AuditQuery& query) { + AuditQuery first = query; + first.after.clear(); + if (!first.before.empty()) Validate::fail("walk follows after; clear before"); + return AdminService::walk(Call::kAuditLogsList, {}, first.to_query(), "after", query.after); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/audit_log.h b/src/openai/admin/audit_log.h new file mode 100644 index 0000000..eda0c0c --- /dev/null +++ b/src/openai/admin/audit_log.h @@ -0,0 +1,37 @@ +#pragma once + +// Audit logs: `GET /organization/audit_logs` with every documented filter and +// the event type catalog (AuditEventCatalog, 149 types in the pinned spec). +// Array filters use the bracket names the spec declares (`event_types[]`), +// `effective_at` is sent as effective_at[gt|gte|lt|lte]. Paging is by id: +// `after` / `before` take an audit log id. + +#include +#include +#include + +#include "openai/admin/admin_service.h" +#include "openai/admin/audit_events.h" + +namespace molo::openai::admin { + +struct AuditQuery { + std::optional effective_at_gt, effective_at_gte, effective_at_lt, effective_at_lte; + std::vector project_ids, event_types, actor_ids, actor_emails, resource_ids; + std::optional tenant_only; + std::optional limit; // 1..100 + std::string after, before; + + Query to_query() const; +}; + +class AuditLogs : public AdminService { + public: + explicit AuditLogs(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const AuditQuery& query = {}); + // Follows `after` up to the page / item ceilings; truncation is reported. + WalkResult walk(const AuditQuery& query); + static const std::vector& event_types() { return AuditEventCatalog::all(); } +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/call_runner.cpp b/src/openai/admin/call_runner.cpp new file mode 100644 index 0000000..37b5516 --- /dev/null +++ b/src/openai/admin/call_runner.cpp @@ -0,0 +1,14 @@ +#include "openai/admin/call_runner.h" + +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +AdminService::Json CallRunner::run(const std::string& key, const std::vector& ids, + const Query& query, const Json* body, bool confirm) { + const CallSpec* spec = CallTable::find(key); + if (!spec) Validate::fail("unknown call " + key); + return execute(spec->call, ids, query, body, confirm); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/call_runner.h b/src/openai/admin/call_runner.h new file mode 100644 index 0000000..a5a760a --- /dev/null +++ b/src/openai/admin/call_runner.h @@ -0,0 +1,25 @@ +#pragma once + +// Runs any row of the call table by its key ("projects.users.list"). Same +// guards as the typed services (credential kind, confirm for destructive +// rows, id and body validation, query names from the table). Used by the +// example's generic routes; typed code should use the resource services. + +#include +#include + +#include "openai/admin/admin_service.h" + +namespace molo::openai::admin { + +class CallRunner : public AdminService { + public: + explicit CallRunner(std::shared_ptr client) : AdminService(std::move(client)) {} + explicit CallRunner(std::shared_ptr client) : AdminService(std::move(client)) {} + + // Throws ApiError::invalid for an unknown key. + Json run(const std::string& key, const std::vector& ids, const Query& query, + const Json* body, bool confirm); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/calls.cpp b/src/openai/admin/calls.cpp new file mode 100644 index 0000000..74a8185 --- /dev/null +++ b/src/openai/admin/calls.cpp @@ -0,0 +1,352 @@ +#include "openai/admin/calls.h" + +#include + +#include "llm/api_client.h" +#include "llm/error.h" + +namespace molo::openai::admin { + +namespace { +constexpr const char* kVendor = "openai"; +} + +// CALLS-BEGIN (parsed by tools/check_spec.py; one row per line) +static const CallSpec kCalls[] = { + {Call::kAdminApiKeysList, "admin_api_keys.list", "GET", "/organization/admin_api_keys", "admin-api-keys-list", "admin", "", "", "after,order,limit", "", "ApiKeyList", ""}, + {Call::kAdminApiKeysCreate, "admin_api_keys.create", "POST", "/organization/admin_api_keys", "admin-api-keys-create", "admin", "name,expires_in_seconds", "name", "", "", "AdminApiKeyCreateResponse", ""}, + {Call::kAdminApiKeysGet, "admin_api_keys.get", "GET", "/organization/admin_api_keys/{key_id}", "admin-api-keys-get", "admin", "", "", "", "", "AdminApiKey", ""}, + {Call::kAdminApiKeysDelete, "admin_api_keys.delete", "DELETE", "/organization/admin_api_keys/{key_id}", "admin-api-keys-delete", "admin", "", "", "", "", "", "destructive"}, + {Call::kAuditLogsList, "audit_logs.list", "GET", "/organization/audit_logs", "list-audit-logs", "admin", "", "", "effective_at,project_ids[],event_types[],actor_ids[],actor_emails[],resource_ids[],tenant_only,limit,after,before", "", "ListAuditLogsResponse", ""}, + {Call::kCertificatesList, "certificates.list", "GET", "/organization/certificates", "listOrganizationCertificates", "admin", "", "", "limit,after,order", "", "ListCertificatesResponse", ""}, + {Call::kCertificatesCreate, "certificates.create", "POST", "/organization/certificates", "uploadCertificate", "admin", "name,certificate", "certificate", "", "UploadCertificateRequest", "Certificate", ""}, + {Call::kCertificatesActivate, "certificates.activate", "POST", "/organization/certificates/activate", "activateOrganizationCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationCertificateActivationResponse", ""}, + {Call::kCertificatesDeactivate, "certificates.deactivate", "POST", "/organization/certificates/deactivate", "deactivateOrganizationCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationCertificateDeactivationResponse", "destructive"}, + {Call::kCertificatesGet, "certificates.get", "GET", "/organization/certificates/{certificate_id}", "getCertificate", "admin", "", "", "include", "", "Certificate", ""}, + {Call::kCertificatesUpdate, "certificates.update", "POST", "/organization/certificates/{certificate_id}", "modifyCertificate", "admin", "name", "", "", "ModifyCertificateRequest", "Certificate", ""}, + {Call::kCertificatesDelete, "certificates.delete", "DELETE", "/organization/certificates/{certificate_id}", "deleteCertificate", "admin", "", "", "", "", "DeleteCertificateResponse", "destructive"}, + {Call::kCosts, "costs", "GET", "/organization/costs", "usage-costs", "admin", "", "", "start_time,end_time,bucket_width,project_ids,api_key_ids,line_items,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kDataRetentionGet, "data_retention.get", "GET", "/organization/data_retention", "retrieve-organization-data-retention", "admin", "", "", "", "", "OrganizationDataRetention", ""}, + {Call::kDataRetentionUpdate, "data_retention.update", "POST", "/organization/data_retention", "update-organization-data-retention", "admin", "retention_type", "retention_type", "", "UpdateOrganizationDataRetentionBody", "OrganizationDataRetention", "destructive"}, + {Call::kGroupsList, "groups.list", "GET", "/organization/groups", "list-groups", "admin", "", "", "limit,after,order", "", "GroupListResource", ""}, + {Call::kGroupsCreate, "groups.create", "POST", "/organization/groups", "create-group", "admin", "name", "name", "", "CreateGroupBody", "GroupResponse", ""}, + {Call::kGroupsGet, "groups.get", "GET", "/organization/groups/{group_id}", "retrieve-group", "admin", "", "", "", "", "GroupResponse", ""}, + {Call::kGroupsUpdate, "groups.update", "POST", "/organization/groups/{group_id}", "update-group", "admin", "name", "name", "", "UpdateGroupBody", "GroupResourceWithSuccess", ""}, + {Call::kGroupsDelete, "groups.delete", "DELETE", "/organization/groups/{group_id}", "delete-group", "admin", "", "", "", "", "GroupDeletedResource", "destructive"}, + {Call::kGroupsRolesList, "groups.roles.list", "GET", "/organization/groups/{group_id}/roles", "list-group-role-assignments", "admin", "", "", "limit,after,order", "", "RoleListResource", ""}, + {Call::kGroupsRolesCreate, "groups.roles.create", "POST", "/organization/groups/{group_id}/roles", "assign-group-role", "admin", "role_id", "role_id", "", "PublicAssignOrganizationGroupRoleBody", "GroupRoleAssignment", ""}, + {Call::kGroupsRolesGet, "groups.roles.get", "GET", "/organization/groups/{group_id}/roles/{role_id}", "retrieve-group-role", "admin", "", "", "", "", "AssignedRoleDetails", ""}, + {Call::kGroupsRolesDelete, "groups.roles.delete", "DELETE", "/organization/groups/{group_id}/roles/{role_id}", "unassign-group-role", "admin", "", "", "", "", "DeletedRoleAssignmentResource", "destructive"}, + {Call::kGroupsUsersList, "groups.users.list", "GET", "/organization/groups/{group_id}/users", "list-group-users", "admin", "", "", "limit,after,order", "", "UserListResource", ""}, + {Call::kGroupsUsersCreate, "groups.users.create", "POST", "/organization/groups/{group_id}/users", "add-group-user", "admin", "user_id", "user_id", "", "CreateGroupUserBody", "GroupUserAssignment", ""}, + {Call::kGroupsUsersGet, "groups.users.get", "GET", "/organization/groups/{group_id}/users/{user_id}", "retrieve-group-user", "admin", "", "", "", "", "GroupMemberUser", ""}, + {Call::kGroupsUsersDelete, "groups.users.delete", "DELETE", "/organization/groups/{group_id}/users/{user_id}", "remove-group-user", "admin", "", "", "", "", "GroupUserDeletedResource", "destructive"}, + {Call::kInvitesList, "invites.list", "GET", "/organization/invites", "list-invites", "admin", "", "", "limit,after", "", "InviteListResponse", ""}, + {Call::kInvitesCreate, "invites.create", "POST", "/organization/invites", "inviteUser", "admin", "email,role,projects", "email,role", "", "InviteRequest", "Invite", ""}, + {Call::kInvitesGet, "invites.get", "GET", "/organization/invites/{invite_id}", "retrieve-invite", "admin", "", "", "", "", "Invite", ""}, + {Call::kInvitesDelete, "invites.delete", "DELETE", "/organization/invites/{invite_id}", "delete-invite", "admin", "", "", "", "", "InviteDeleteResponse", "destructive"}, + {Call::kProjectsList, "projects.list", "GET", "/organization/projects", "list-projects", "admin", "", "", "limit,after,include_archived", "", "ProjectListResponse", ""}, + {Call::kProjectsCreate, "projects.create", "POST", "/organization/projects", "create-project", "admin", "name,geography,residency,external_key_id", "name", "", "ProjectCreateRequest", "Project", ""}, + {Call::kProjectsGet, "projects.get", "GET", "/organization/projects/{project_id}", "retrieve-project", "admin", "", "", "", "", "Project", ""}, + {Call::kProjectsUpdate, "projects.update", "POST", "/organization/projects/{project_id}", "modify-project", "admin", "name,external_key_id,geography", "", "", "ProjectUpdateRequest", "Project", ""}, + {Call::kProjectsApiKeysList, "projects.api_keys.list", "GET", "/organization/projects/{project_id}/api_keys", "list-project-api-keys", "admin", "", "", "limit,after,owner_project_access", "", "ProjectApiKeyListResponse", ""}, + {Call::kProjectsApiKeysGet, "projects.api_keys.get", "GET", "/organization/projects/{project_id}/api_keys/{api_key_id}", "retrieve-project-api-key", "admin", "", "", "", "", "ProjectApiKey", ""}, + {Call::kProjectsApiKeysUpdate, "projects.api_keys.update", "POST", "/organization/projects/{project_id}/api_keys/{api_key_id}", "update-project-api-key", "admin", "expires_in_seconds,scopes", "", "", "UpdateProjectApiKeyBody", "ProjectApiKey", ""}, + {Call::kProjectsApiKeysDelete, "projects.api_keys.delete", "DELETE", "/organization/projects/{project_id}/api_keys/{api_key_id}", "delete-project-api-key", "admin", "", "", "", "", "ProjectApiKeyDeleteResponse", "destructive"}, + {Call::kProjectsArchive, "projects.archive", "POST", "/organization/projects/{project_id}/archive", "archive-project", "admin", "", "", "", "", "Project", "destructive"}, + {Call::kProjectsCertificatesList, "projects.certificates.list", "GET", "/organization/projects/{project_id}/certificates", "listProjectCertificates", "admin", "", "", "limit,after,order", "", "ListProjectCertificatesResponse", ""}, + {Call::kProjectsCertificatesActivate, "projects.certificates.activate", "POST", "/organization/projects/{project_id}/certificates/activate", "activateProjectCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationProjectCertificateActivationResponse", ""}, + {Call::kProjectsCertificatesDeactivate, "projects.certificates.deactivate", "POST", "/organization/projects/{project_id}/certificates/deactivate", "deactivateProjectCertificates", "admin", "certificate_ids", "certificate_ids", "", "ToggleCertificatesRequest", "OrganizationProjectCertificateDeactivationResponse", "destructive"}, + {Call::kProjectsDataRetentionGet, "projects.data_retention.get", "GET", "/organization/projects/{project_id}/data_retention", "retrieve-project-data-retention", "admin", "", "", "", "", "ProjectDataRetention", ""}, + {Call::kProjectsDataRetentionUpdate, "projects.data_retention.update", "POST", "/organization/projects/{project_id}/data_retention", "update-project-data-retention", "admin", "retention_type", "retention_type", "", "UpdateProjectDataRetentionBody", "ProjectDataRetention", "destructive"}, + {Call::kProjectsGroupsList, "projects.groups.list", "GET", "/organization/projects/{project_id}/groups", "list-project-groups", "admin", "", "", "limit,after,order", "", "ProjectGroupListResource", ""}, + {Call::kProjectsGroupsCreate, "projects.groups.create", "POST", "/organization/projects/{project_id}/groups", "add-project-group", "admin", "group_id,role", "group_id,role", "", "InviteProjectGroupBody", "ProjectGroup", ""}, + {Call::kProjectsGroupsGet, "projects.groups.get", "GET", "/organization/projects/{project_id}/groups/{group_id}", "retrieve-project-group", "admin", "", "", "group_type", "", "ProjectGroup", ""}, + {Call::kProjectsGroupsDelete, "projects.groups.delete", "DELETE", "/organization/projects/{project_id}/groups/{group_id}", "remove-project-group", "admin", "", "", "", "", "ProjectGroupDeletedResource", "destructive"}, + {Call::kProjectsHostedToolPermissionsGet, "projects.hosted_tool_permissions.get", "GET", "/organization/projects/{project_id}/hosted_tool_permissions", "retrieve-project-hosted-tool-permissions", "admin", "", "", "", "", "ProjectHostedToolPermissions", ""}, + {Call::kProjectsHostedToolPermissionsUpdate, "projects.hosted_tool_permissions.update", "POST", "/organization/projects/{project_id}/hosted_tool_permissions", "update-project-hosted-tool-permissions", "admin", "file_search,web_search,image_generation,mcp,code_interpreter", "", "", "ProjectHostedToolPermissionsUpdateRequest", "ProjectHostedToolPermissions", ""}, + {Call::kProjectsModelPermissionsGet, "projects.model_permissions.get", "GET", "/organization/projects/{project_id}/model_permissions", "retrieve-project-model-permissions", "admin", "", "", "", "", "ProjectModelPermissions", ""}, + {Call::kProjectsModelPermissionsUpdate, "projects.model_permissions.update", "POST", "/organization/projects/{project_id}/model_permissions", "update-project-model-permissions", "admin", "mode,model_ids", "mode,model_ids", "", "ProjectModelPermissionsUpdateRequest", "ProjectModelPermissions", ""}, + {Call::kProjectsModelPermissionsDelete, "projects.model_permissions.delete", "DELETE", "/organization/projects/{project_id}/model_permissions", "delete-project-model-permissions", "admin", "", "", "", "", "ProjectModelPermissionsDeleteResponse", "destructive"}, + {Call::kProjectsRateLimitsList, "projects.rate_limits.list", "GET", "/organization/projects/{project_id}/rate_limits", "list-project-rate-limits", "admin", "", "", "limit,after,before", "", "ProjectRateLimitListResponse", ""}, + {Call::kProjectsRateLimitsUpdate, "projects.rate_limits.update", "POST", "/organization/projects/{project_id}/rate_limits/{rate_limit_id}", "update-project-rate-limits", "admin", "max_requests_per_1_minute,max_tokens_per_1_minute,max_images_per_1_minute,max_audio_megabytes_per_1_minute,max_requests_per_1_day,batch_1_day_max_input_tokens", "", "", "ProjectRateLimitUpdateRequest", "ProjectRateLimit", ""}, + {Call::kProjectsServiceAccountsList, "projects.service_accounts.list", "GET", "/organization/projects/{project_id}/service_accounts", "list-project-service-accounts", "admin", "", "", "limit,after", "", "ProjectServiceAccountListResponse", ""}, + {Call::kProjectsServiceAccountsCreate, "projects.service_accounts.create", "POST", "/organization/projects/{project_id}/service_accounts", "create-project-service-account", "admin", "name,create_service_account_only,expires_in_seconds", "name", "", "ProjectServiceAccountCreateRequest", "ProjectServiceAccountCreateResponse", ""}, + {Call::kProjectsServiceAccountsGet, "projects.service_accounts.get", "GET", "/organization/projects/{project_id}/service_accounts/{service_account_id}", "retrieve-project-service-account", "admin", "", "", "", "", "ProjectServiceAccount", ""}, + {Call::kProjectsServiceAccountsUpdate, "projects.service_accounts.update", "POST", "/organization/projects/{project_id}/service_accounts/{service_account_id}", "update-project-service-account", "admin", "name,role", "", "", "UpdateProjectServiceAccountBody", "ProjectServiceAccount", ""}, + {Call::kProjectsServiceAccountsDelete, "projects.service_accounts.delete", "DELETE", "/organization/projects/{project_id}/service_accounts/{service_account_id}", "delete-project-service-account", "admin", "", "", "", "", "ProjectServiceAccountDeleteResponse", "destructive"}, + {Call::kProjectsSpendAlertsList, "projects.spend_alerts.list", "GET", "/organization/projects/{project_id}/spend_alerts", "list-project-spend-alerts", "admin", "", "", "limit,order,after,before", "", "ProjectSpendAlertListResource", ""}, + {Call::kProjectsSpendAlertsCreate, "projects.spend_alerts.create", "POST", "/organization/projects/{project_id}/spend_alerts", "create-project-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "ProjectSpendAlert", ""}, + {Call::kProjectsSpendAlertsGet, "projects.spend_alerts.get", "GET", "/organization/projects/{project_id}/spend_alerts/{alert_id}", "retrieve-project-spend-alert", "admin", "", "", "", "", "ProjectSpendAlert", ""}, + {Call::kProjectsSpendAlertsUpdate, "projects.spend_alerts.update", "POST", "/organization/projects/{project_id}/spend_alerts/{alert_id}", "update-project-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "ProjectSpendAlert", ""}, + {Call::kProjectsSpendAlertsDelete, "projects.spend_alerts.delete", "DELETE", "/organization/projects/{project_id}/spend_alerts/{alert_id}", "delete-project-spend-alert", "admin", "", "", "", "", "ProjectSpendAlertDeletedResource", "destructive"}, + {Call::kProjectsUsersList, "projects.users.list", "GET", "/organization/projects/{project_id}/users", "list-project-users", "admin", "", "", "limit,after", "", "ProjectUserListResponse", ""}, + {Call::kProjectsUsersCreate, "projects.users.create", "POST", "/organization/projects/{project_id}/users", "create-project-user", "admin", "user_id,email,role", "role", "", "ProjectUserCreateRequest", "ProjectUser", ""}, + {Call::kProjectsUsersGet, "projects.users.get", "GET", "/organization/projects/{project_id}/users/{user_id}", "retrieve-project-user", "admin", "", "", "", "", "ProjectUser", ""}, + {Call::kProjectsUsersUpdate, "projects.users.update", "POST", "/organization/projects/{project_id}/users/{user_id}", "modify-project-user", "admin", "role", "", "", "ProjectUserUpdateRequest", "ProjectUser", ""}, + {Call::kProjectsUsersDelete, "projects.users.delete", "DELETE", "/organization/projects/{project_id}/users/{user_id}", "delete-project-user", "admin", "", "", "", "", "ProjectUserDeleteResponse", "destructive"}, + {Call::kRolesList, "roles.list", "GET", "/organization/roles", "list-roles", "admin", "", "", "limit,after,order", "", "PublicRoleListResource", ""}, + {Call::kRolesCreate, "roles.create", "POST", "/organization/roles", "create-role", "admin", "role_name,permissions,description", "role_name,permissions", "", "PublicCreateOrganizationRoleBody", "Role", ""}, + {Call::kRolesGet, "roles.get", "GET", "/organization/roles/{role_id}", "retrieve-role", "admin", "", "", "", "", "Role", ""}, + {Call::kRolesUpdate, "roles.update", "POST", "/organization/roles/{role_id}", "update-role", "admin", "permissions,description,role_name", "", "", "PublicUpdateOrganizationRoleBody", "Role", ""}, + {Call::kRolesDelete, "roles.delete", "DELETE", "/organization/roles/{role_id}", "delete-role", "admin", "", "", "", "", "RoleDeletedResource", "destructive"}, + {Call::kSpendAlertsList, "spend_alerts.list", "GET", "/organization/spend_alerts", "list-organization-spend-alerts", "admin", "", "", "limit,order,after,before", "", "OrganizationSpendAlertListResource", ""}, + {Call::kSpendAlertsCreate, "spend_alerts.create", "POST", "/organization/spend_alerts", "create-organization-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "OrganizationSpendAlert", ""}, + {Call::kSpendAlertsGet, "spend_alerts.get", "GET", "/organization/spend_alerts/{alert_id}", "retrieve-organization-spend-alert", "admin", "", "", "", "", "OrganizationSpendAlert", ""}, + {Call::kSpendAlertsUpdate, "spend_alerts.update", "POST", "/organization/spend_alerts/{alert_id}", "update-organization-spend-alert", "admin", "threshold_amount,currency,interval,notification_channel", "threshold_amount,currency,interval,notification_channel", "", "CreateSpendAlertBody", "OrganizationSpendAlert", ""}, + {Call::kSpendAlertsDelete, "spend_alerts.delete", "DELETE", "/organization/spend_alerts/{alert_id}", "delete-organization-spend-alert", "admin", "", "", "", "", "OrganizationSpendAlertDeletedResource", "destructive"}, + {Call::kUsageAudioSpeeches, "usage.audio_speeches", "GET", "/organization/usage/audio_speeches", "usage-audio-speeches", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageAudioTranscriptions, "usage.audio_transcriptions", "GET", "/organization/usage/audio_transcriptions", "usage-audio-transcriptions", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageCodeInterpreterSessions, "usage.code_interpreter_sessions", "GET", "/organization/usage/code_interpreter_sessions", "usage-code-interpreter-sessions", "admin", "", "", "start_time,end_time,bucket_width,project_ids,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageCompletions, "usage.completions", "GET", "/organization/usage/completions", "usage-completions", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,batch,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageEmbeddings, "usage.embeddings", "GET", "/organization/usage/embeddings", "usage-embeddings", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageFileSearchCalls, "usage.file_search_calls", "GET", "/organization/usage/file_search_calls", "usage-file-search-calls", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,vector_store_ids,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageImages, "usage.images", "GET", "/organization/usage/images", "usage-images", "admin", "", "", "start_time,end_time,bucket_width,sources,sizes,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageModerations, "usage.moderations", "GET", "/organization/usage/moderations", "usage-moderations", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageVectorStores, "usage.vector_stores", "GET", "/organization/usage/vector_stores", "usage-vector-stores", "admin", "", "", "start_time,end_time,bucket_width,project_ids,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsageWebSearchCalls, "usage.web_search_calls", "GET", "/organization/usage/web_search_calls", "usage-web-search-calls", "admin", "", "", "start_time,end_time,bucket_width,project_ids,user_ids,api_key_ids,models,context_levels,group_by,limit,page", "", "UsageResponse", ""}, + {Call::kUsersList, "users.list", "GET", "/organization/users", "list-users", "admin", "", "", "limit,after,emails", "", "UserListResponse", ""}, + {Call::kUsersGet, "users.get", "GET", "/organization/users/{user_id}", "retrieve-user", "admin", "", "", "", "", "User", ""}, + {Call::kUsersUpdate, "users.update", "POST", "/organization/users/{user_id}", "modify-user", "admin", "role,role_id,technical_level,developer_persona", "", "", "UserRoleUpdateRequest", "User", ""}, + {Call::kUsersDelete, "users.delete", "DELETE", "/organization/users/{user_id}", "delete-user", "admin", "", "", "", "", "UserDeleteResponse", "destructive"}, + {Call::kUsersRolesList, "users.roles.list", "GET", "/organization/users/{user_id}/roles", "list-user-role-assignments", "admin", "", "", "limit,after,order", "", "RoleListResource", ""}, + {Call::kUsersRolesCreate, "users.roles.create", "POST", "/organization/users/{user_id}/roles", "assign-user-role", "admin", "role_id", "role_id", "", "PublicAssignOrganizationGroupRoleBody", "UserRoleAssignment", ""}, + {Call::kUsersRolesGet, "users.roles.get", "GET", "/organization/users/{user_id}/roles/{role_id}", "retrieve-user-role", "admin", "", "", "", "", "AssignedRoleDetails", ""}, + {Call::kUsersRolesDelete, "users.roles.delete", "DELETE", "/organization/users/{user_id}/roles/{role_id}", "unassign-user-role", "admin", "", "", "", "", "DeletedRoleAssignmentResource", "destructive"}, + {Call::kUsageDecisions, "usage.decisions", "GET", "/organization/usage/decisions", "OrganizationDecisionsusage", "admin", "", "", "start_time,end_time,bucket_width,limit,page,project_ids,group_by,user_ids,api_key_ids,models,batch", "", "PublicDecisionsUsageResponseResource", ""}, + {Call::kExternalStorageList, "external_storage.list", "GET", "/organization/external_storage", "Listexternalstorageconfigurations", "admin", "", "", "project_id,after,order,limit", "", "ExternalStorageListResource", ""}, + {Call::kExternalStorageCreate, "external_storage.create", "POST", "/organization/external_storage", "Createanexternalstorageconfiguration", "admin", "project_id,provider", "project_id,provider", "", "CreateExternalStorageBody", "ExternalStorageResponse", ""}, + {Call::kExternalStorageGet, "external_storage.get", "GET", "/organization/external_storage/{external_storage_id}", "Getanexternalstorageconfiguration", "admin", "", "", "", "", "ExternalStorageResponse", ""}, + {Call::kExternalStorageDelete, "external_storage.delete", "DELETE", "/organization/external_storage/{external_storage_id}", "Deleteanexternalstorageconfiguration", "admin", "", "", "", "", "ExternalStorageDeletedResource", "destructive"}, + {Call::kExternalStorageValidate, "external_storage.validate", "POST", "/organization/external_storage/{external_storage_id}/validate", "Validateanexternalstorageconfiguration", "admin", "", "", "", "", "ExternalStorageResponse", ""}, + {Call::kSpendLimitGet, "spend_limit.get", "GET", "/organization/spend_limit", "Getorganizationspendlimit", "admin", "", "", "", "", "OrganizationSpendLimitResource", ""}, + {Call::kSpendLimitUpdate, "spend_limit.update", "POST", "/organization/spend_limit", "Updateorganizationspendlimit", "admin", "threshold_amount,currency,interval", "threshold_amount,currency,interval", "", "UpdateOrganizationSpendLimitBody", "OrganizationSpendLimitResource", ""}, + {Call::kSpendLimitDelete, "spend_limit.delete", "DELETE", "/organization/spend_limit", "Deleteorganizationspendlimit", "admin", "", "", "", "", "OrganizationSpendLimitDeletedResource", "destructive"}, + {Call::kProjectsSpendLimitGet, "projects.spend_limit.get", "GET", "/organization/projects/{project_id}/spend_limit", "Getprojectspendlimit", "admin", "", "", "", "", "ProjectSpendLimitResource", ""}, + {Call::kProjectsSpendLimitUpdate, "projects.spend_limit.update", "POST", "/organization/projects/{project_id}/spend_limit", "Updateprojectspendlimit", "admin", "threshold_amount,currency,interval", "threshold_amount,currency,interval", "", "UpdateProjectSpendLimitBody", "ProjectSpendLimitResource", ""}, + {Call::kProjectsSpendLimitDelete, "projects.spend_limit.delete", "DELETE", "/organization/projects/{project_id}/spend_limit", "Deleteprojectspendlimit", "admin", "", "", "", "", "ProjectSpendLimitDeletedResource", "destructive"}, + {Call::kProjectsServiceAccountsApiKeysCreate, "projects.service_accounts.api_keys.create", "POST", "/organization/projects/{project_id}/service_accounts/{service_account_id}/api_keys", "CreateanAPIkeyforaserviceaccount", "admin", "name,scopes,expires_in_seconds", "", "", "CreateProjectServiceAccountApiKeyBody", "ServiceAccountApiKeyBody", ""}, + {Call::kWebhookEndpointsList, "webhook_endpoints.list", "GET", "/webhook_endpoints", "ListWebhookEndpoints", "project", "", "", "limit,after", "", "WebhookEndpointListResource", ""}, + {Call::kWebhookEndpointsCreate, "webhook_endpoints.create", "POST", "/webhook_endpoints", "CreateWebhookEndpoint", "project", "name,url,event_types", "name,url,event_types", "", "PublicCreateEndpointBody", "WebhookEndpointWithSecretResource", ""}, + {Call::kWebhookEndpointsGet, "webhook_endpoints.get", "GET", "/webhook_endpoints/{webhook_endpoint_id}", "RetrieveWebhookEndpoint", "project", "", "", "", "", "WebhookEndpointBody", ""}, + {Call::kWebhookEndpointsUpdate, "webhook_endpoints.update", "POST", "/webhook_endpoints/{webhook_endpoint_id}", "UpdateWebhookEndpoint", "project", "name,url,event_types", "", "", "PublicUpdateEndpointBody", "WebhookEndpointBody", ""}, + {Call::kWebhookEndpointsDelete, "webhook_endpoints.delete", "DELETE", "/webhook_endpoints/{webhook_endpoint_id}", "DeleteWebhookEndpoint", "project", "", "", "", "", "DeletedWebhookEndpointResource", "destructive"}, + {Call::kWebhookEndpointsRotateSecret, "webhook_endpoints.rotate_secret", "POST", "/webhook_endpoints/{webhook_endpoint_id}/rotate_secret", "RotateWebhookEndpointSigningSecret", "project", "keep_old_secret_active_for_24_hours", "", "", "PublicRotateSecretBody", "WebhookEndpointWithSecretResource", "destructive"}, + {Call::kWebhookEndpointsTest, "webhook_endpoints.test", "POST", "/webhook_endpoints/{webhook_endpoint_id}/test", "TestWebhookEndpoint", "project", "event_type", "event_type", "", "PublicTestEndpointBody", "WebhookEndpointTestResultResource", ""}, + {Call::kWebhookEventTypesList, "webhook_event_types.list", "GET", "/webhook_event_types", "ListWebhookEventTypes", "project", "", "", "", "", "WebhookEventTypeListResource", ""}, +}; +// CALLS-END + +// SCHEMAS-BEGIN (response fields we read; checked by tools/check_spec.py) +static const SchemaFields kSchemas[] = { + {"ApiKeyList", "object,data,has_more,first_id,last_id"}, + {"AdminApiKeyCreateResponse", "object,id,name,redacted_value,created_at,expires_at,last_used_at,owner,value"}, + {"AdminApiKey", "object,id,name,redacted_value,created_at,expires_at,last_used_at,owner"}, + {"ListAuditLogsResponse", "object,data,first_id,last_id,has_more"}, + {"ListCertificatesResponse", "data,first_id,last_id,has_more,object"}, + {"Certificate", "object,id,name,created_at,certificate_details,active"}, + {"OrganizationCertificateActivationResponse", "object,data"}, + {"OrganizationCertificateDeactivationResponse", "object,data"}, + {"DeleteCertificateResponse", "object,id"}, + {"UsageResponse", "object,data,has_more,next_page"}, + {"OrganizationDataRetention", "object,type"}, + {"GroupListResource", "object,data,has_more,next"}, + {"GroupResponse", "id,name,created_at,is_scim_managed,group_type"}, + {"GroupResourceWithSuccess", "id,name,created_at,is_scim_managed"}, + {"GroupDeletedResource", "object,id,deleted"}, + {"RoleListResource", "object,data,has_more,next"}, + {"GroupRoleAssignment", "object,group,role"}, + {"AssignedRoleDetails", "id,name,permissions,resource_type,predefined_role,description,created_at,updated_at,created_by,created_by_user_obj,metadata,assignment_sources"}, + {"DeletedRoleAssignmentResource", "object,deleted"}, + {"UserListResource", "object,data,has_more,next"}, + {"GroupUserAssignment", "object,user_id,group_id"}, + {"GroupMemberUser", "id,name,email,picture,is_service_account,user_type"}, + {"GroupUserDeletedResource", "object,deleted"}, + {"InviteListResponse", "object,data,first_id,last_id,has_more"}, + {"Invite", "object,id,email,role,status,created_at,expires_at,accepted_at,projects"}, + {"InviteDeleteResponse", "object,id,deleted"}, + {"ProjectListResponse", "object,data,first_id,last_id,has_more"}, + {"Project", "id,object,name,created_at,archived_at,status,external_key_id,residency"}, + {"ProjectApiKeyListResponse", "object,data,first_id,last_id,has_more"}, + {"ProjectApiKey", "object,redacted_value,name,created_at,expires_at,last_used_at,id,owner_project_access,owner"}, + {"ProjectApiKeyDeleteResponse", "object,id,deleted"}, + {"ListProjectCertificatesResponse", "data,first_id,last_id,has_more,object"}, + {"OrganizationProjectCertificateActivationResponse", "object,data"}, + {"OrganizationProjectCertificateDeactivationResponse", "object,data"}, + {"ProjectDataRetention", "object,type"}, + {"ProjectGroupListResource", "object,data,has_more,next"}, + {"ProjectGroup", "object,project_id,group_id,group_name,group_type,created_at"}, + {"ProjectGroupDeletedResource", "object,deleted"}, + {"ProjectHostedToolPermissions", "file_search,web_search,image_generation,mcp,code_interpreter"}, + {"ProjectModelPermissions", "object,mode,model_ids"}, + {"ProjectModelPermissionsDeleteResponse", "object,deleted"}, + {"ProjectRateLimitListResponse", "object,data,first_id,last_id,has_more"}, + {"ProjectRateLimit", "object,id,model,max_requests_per_1_minute,max_tokens_per_1_minute,max_images_per_1_minute,max_audio_megabytes_per_1_minute,max_requests_per_1_day,batch_1_day_max_input_tokens"}, + {"ProjectServiceAccountListResponse", "object,data,first_id,last_id,has_more"}, + {"ProjectServiceAccountCreateResponse", "object,id,name,role,created_at,api_key"}, + {"ProjectServiceAccount", "object,id,name,role,created_at"}, + {"ProjectServiceAccountDeleteResponse", "object,id,deleted"}, + {"ProjectSpendAlertListResource", "object,data,first_id,last_id,has_more"}, + {"ProjectSpendAlert", "id,object,threshold_amount,currency,interval,notification_channel"}, + {"ProjectSpendAlertDeletedResource", "id,object,deleted"}, + {"ProjectUserListResponse", "object,data,first_id,last_id,has_more"}, + {"ProjectUser", "object,id,name,email,role,added_at"}, + {"ProjectUserDeleteResponse", "object,id,deleted"}, + {"PublicRoleListResource", "object,data,has_more,next"}, + {"Role", "object,id,name,description,permissions,resource_type,predefined_role"}, + {"RoleDeletedResource", "object,id,deleted"}, + {"OrganizationSpendAlertListResource", "object,data,first_id,last_id,has_more"}, + {"OrganizationSpendAlert", "id,object,threshold_amount,currency,interval,notification_channel"}, + {"OrganizationSpendAlertDeletedResource", "id,object,deleted"}, + {"UserListResponse", "object,data,first_id,last_id,has_more"}, + {"User", "object,id,name,email,role,added_at,is_default,created,user,is_service_account,is_scale_tier_authorized_purchaser,is_scim_managed,api_key_last_used_at,technical_level,developer_persona,projects"}, + {"UserDeleteResponse", "object,id,deleted"}, + {"UserRoleAssignment", "object,user,role"}, + {"PublicDecisionsUsageResponseResource", "object,has_more,next_page,data"}, + {"ExternalStorageListResource", "object,data,first_id,last_id,has_more"}, + {"ExternalStorageResponse", "object,id,project_id,provider,geography,status,created_at"}, + {"ExternalStorageDeletedResource", "object,id,deleted"}, + {"OrganizationSpendLimitResource", "object,threshold_amount,currency,interval,enforcement"}, + {"OrganizationSpendLimitDeletedResource", "object,deleted"}, + {"ProjectSpendLimitResource", "object,threshold_amount,currency,interval,enforcement"}, + {"ProjectSpendLimitDeletedResource", "object,deleted"}, + {"ServiceAccountApiKeyBody", "object,value,name,created_at,expires_at,id"}, + {"WebhookEndpointListResource", "object,data,first_id,last_id,has_more"}, + {"WebhookEndpointWithSecretResource", "id,object,created_at,updated_at,name,url,event_types,signing_secret_hint,signing_secret"}, + {"WebhookEndpointBody", "id,object,created_at,updated_at,name,url,event_types,signing_secret_hint"}, + {"DeletedWebhookEndpointResource", "id,object,deleted"}, + {"WebhookEndpointTestResultResource", "object,webhook_endpoint_id,event_type,status_code,success"}, + {"WebhookEventTypeListResource", "object,data"}, + {"AuditLog", "id,type,effective_at,project,actor,api_key.created,api_key.updated,api_key.deleted,checkpoint.permission.created,checkpoint.permission.deleted,external_key.registered,external_key.removed,external_storage.registered,external_storage.removed,group.created,group.updated,group.deleted,scim.enabled,scim.disabled,invite.sent,invite.accepted,invite.deleted,ip_allowlist.created,ip_allowlist.updated,ip_allowlist.deleted,ip_allowlist.config.activated,ip_allowlist.config.deactivated,login.succeeded,login.failed,logout.succeeded,logout.failed,organization.updated,project.created,project.updated,project.archived,project.deleted,rate_limit.updated,rate_limit.deleted,role.created,role.updated,role.deleted,role.assignment.created,role.assignment.deleted,role.bound_to_resource,role.unbound_from_resource,service_account.created,service_account.updated,service_account.deleted,workload_identity_provider.created,workload_identity_provider.updated,workload_identity_provider.deleted,workload_identity_provider_mapping.created,workload_identity_provider_mapping.updated,workload_identity_provider_mapping.deleted,user.added,user.updated,user.deleted,certificate.created,certificate.updated,certificate.deleted,certificates.activated,certificates.deactivated"}, + {"UsageTimeBucket", "object,start_time,end_time,results"}, + {"CostsResult", "api_source,object,amount,line_item,project_id,user_id,api_key_id,quantity,quantity_unit"}, + {"UsageCompletionsResult", "api_source,object,input_tokens,input_cached_tokens,input_cache_write_tokens,input_cache_write_30m_tokens,input_cache_write_12h_tokens,input_uncached_tokens,output_tokens,input_text_tokens,output_text_tokens,input_cached_text_tokens,input_audio_tokens,input_cached_audio_tokens,output_audio_tokens,input_image_tokens,input_cached_image_tokens,output_image_tokens,num_model_requests,project_id,user_id,api_key_id,model,batch,service_tier"}, + {"UsageEmbeddingsResult", "object,input_tokens,num_model_requests,project_id,user_id,api_key_id,model"}, + {"UsageModerationsResult", "object,input_tokens,num_model_requests,project_id,user_id,api_key_id,model"}, + {"UsageImagesResult", "object,images,num_model_requests,source,size,project_id,user_id,api_key_id,model"}, + {"UsageAudioSpeechesResult", "object,characters,num_model_requests,project_id,user_id,api_key_id,model"}, + {"UsageAudioTranscriptionsResult", "object,seconds,num_model_requests,project_id,user_id,api_key_id,model"}, + {"UsageVectorStoresResult", "object,usage_bytes,project_id"}, + {"UsageCodeInterpreterSessionsResult", "object,num_sessions,project_id"}, + {"UsageFileSearchCallsResult", "object,num_requests,project_id,user_id,api_key_id,vector_store_id"}, + {"UsageWebSearchCallsResult", "api_source,object,num_model_requests,num_requests,project_id,user_id,api_key_id,model,context_level"}, +}; +// SCHEMAS-END + +std::size_t CallTable::size() { return sizeof(kCalls) / sizeof(kCalls[0]); } + +const CallSpec& CallTable::at(std::size_t index) { + if (index >= size()) throw llm::ApiError::invalid(kVendor, "call index out of range"); + return kCalls[index]; +} + +const CallSpec& CallTable::spec(Call call) { + const auto index = static_cast(call); + if (index >= size() || kCalls[index].call != call) + throw llm::ApiError::invalid(kVendor, "call table out of order"); + return kCalls[index]; +} + +const CallSpec* CallTable::find(const std::string& key) { + for (const CallSpec& row : kCalls) + if (key == row.key) return &row; + return nullptr; +} + +clients::Method CallTable::method(Call call) { + const char* m = spec(call).http_method; + if (std::strcmp(m, "GET") == 0) return clients::Method::kGet; + if (std::strcmp(m, "POST") == 0) return clients::Method::kPost; + if (std::strcmp(m, "DELETE") == 0) return clients::Method::kDelete; + throw llm::ApiError::invalid(kVendor, "unsupported method in call table"); +} + +AuthKind CallTable::auth(Call call) { + return std::strcmp(spec(call).auth, "project") == 0 ? AuthKind::kProject : AuthKind::kAdmin; +} + +bool CallTable::destructive(Call call) { + return std::strcmp(spec(call).flags, "destructive") == 0; +} + +std::vector CallTable::split(const char* list) { + std::vector out; + std::string cur; + for (const char* p = list; *p; ++p) { + if (*p == ',') { + if (!cur.empty()) out.push_back(cur); + cur.clear(); + } else { + cur += *p; + } + } + if (!cur.empty()) out.push_back(cur); + return out; +} + +std::vector CallTable::path_params(Call call) { + std::vector out; + const std::string path = spec(call).path; + std::size_t at = 0; + while ((at = path.find('{', at)) != std::string::npos) { + const std::size_t end = path.find('}', at); + if (end == std::string::npos) break; + out.push_back(path.substr(at + 1, end - at - 1)); + at = end + 1; + } + return out; +} + +std::string CallTable::render(Call call, const std::vector& ids) { + const std::vector names = path_params(call); + if (ids.size() != names.size()) + throw llm::ApiError::invalid(kVendor, std::string(spec(call).key) + " takes " + + std::to_string(names.size()) + " id(s)"); + std::string path = spec(call).path; + for (std::size_t i = 0; i < names.size(); ++i) { + if (!llm::Service::valid_id(ids[i])) + throw llm::ApiError::invalid(kVendor, "bad " + names[i]); + const std::string token = "{" + names[i] + "}"; + path.replace(path.find(token), token.size(), ids[i]); + } + return path; +} + +bool CallTable::allows_body_field(Call call, const std::string& field) { + for (const std::string& f : split(spec(call).body_fields)) + if (f == field) return true; + return false; +} + +std::vector CallTable::required_body_fields(Call call) { + return split(spec(call).required_fields); +} + +bool CallTable::allows_query(Call call, const std::string& name) { + for (const std::string& q : split(spec(call).query_params)) + if (q == name) return true; + // Object parameters are sent as name[key] (effective_at[gte]=...). + static const char* const kObjectParams[] = {"effective_at"}; + for (const char* base : kObjectParams) { + const std::string prefix = std::string(base) + "["; + if (name.rfind(prefix, 0) == 0 && name.back() == ']') + for (const std::string& q : split(spec(call).query_params)) + if (q == base) return true; + } + return false; +} + +std::size_t CallTable::schema_count() { return sizeof(kSchemas) / sizeof(kSchemas[0]); } + +const SchemaFields& CallTable::schema_at(std::size_t index) { + if (index >= schema_count()) throw llm::ApiError::invalid(kVendor, "schema index out of range"); + return kSchemas[index]; +} + +const SchemaFields* CallTable::schema(const std::string& name) { + for (const SchemaFields& s : kSchemas) + if (name == s.schema) return &s; + return nullptr; +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/calls.h b/src/openai/admin/calls.h new file mode 100644 index 0000000..188d382 --- /dev/null +++ b/src/openai/admin/calls.h @@ -0,0 +1,101 @@ +#pragma once + +// The ONE table of REST calls this package makes. Every row is checked against +// OpenAI's published OpenAPI document by tools/check_spec.py. Code builds every +// URL from this table, never from a literal. + +#include +#include +#include + +#include "clients/request.h" + +namespace molo::openai::admin { + +enum class Call { + kAdminApiKeysList, kAdminApiKeysCreate, kAdminApiKeysGet, kAdminApiKeysDelete, kAuditLogsList, + kCertificatesList, kCertificatesCreate, kCertificatesActivate, kCertificatesDeactivate, + kCertificatesGet, kCertificatesUpdate, kCertificatesDelete, kCosts, kDataRetentionGet, + kDataRetentionUpdate, kGroupsList, kGroupsCreate, kGroupsGet, kGroupsUpdate, kGroupsDelete, + kGroupsRolesList, kGroupsRolesCreate, kGroupsRolesGet, kGroupsRolesDelete, kGroupsUsersList, + kGroupsUsersCreate, kGroupsUsersGet, kGroupsUsersDelete, kInvitesList, kInvitesCreate, + kInvitesGet, kInvitesDelete, kProjectsList, kProjectsCreate, kProjectsGet, kProjectsUpdate, + kProjectsApiKeysList, kProjectsApiKeysGet, kProjectsApiKeysUpdate, kProjectsApiKeysDelete, + kProjectsArchive, kProjectsCertificatesList, kProjectsCertificatesActivate, + kProjectsCertificatesDeactivate, kProjectsDataRetentionGet, kProjectsDataRetentionUpdate, + kProjectsGroupsList, kProjectsGroupsCreate, kProjectsGroupsGet, kProjectsGroupsDelete, + kProjectsHostedToolPermissionsGet, kProjectsHostedToolPermissionsUpdate, + kProjectsModelPermissionsGet, kProjectsModelPermissionsUpdate, kProjectsModelPermissionsDelete, + kProjectsRateLimitsList, kProjectsRateLimitsUpdate, kProjectsServiceAccountsList, + kProjectsServiceAccountsCreate, kProjectsServiceAccountsGet, kProjectsServiceAccountsUpdate, + kProjectsServiceAccountsDelete, kProjectsSpendAlertsList, kProjectsSpendAlertsCreate, + kProjectsSpendAlertsGet, kProjectsSpendAlertsUpdate, kProjectsSpendAlertsDelete, + kProjectsUsersList, kProjectsUsersCreate, kProjectsUsersGet, kProjectsUsersUpdate, + kProjectsUsersDelete, kRolesList, kRolesCreate, kRolesGet, kRolesUpdate, kRolesDelete, + kSpendAlertsList, kSpendAlertsCreate, kSpendAlertsGet, kSpendAlertsUpdate, kSpendAlertsDelete, + kUsageAudioSpeeches, kUsageAudioTranscriptions, kUsageCodeInterpreterSessions, + kUsageCompletions, kUsageEmbeddings, kUsageFileSearchCalls, kUsageImages, kUsageModerations, + kUsageVectorStores, kUsageWebSearchCalls, kUsersList, kUsersGet, kUsersUpdate, kUsersDelete, + kUsersRolesList, kUsersRolesCreate, kUsersRolesGet, kUsersRolesDelete, kUsageDecisions, + kExternalStorageList, kExternalStorageCreate, kExternalStorageGet, kExternalStorageDelete, + kExternalStorageValidate, kSpendLimitGet, kSpendLimitUpdate, kSpendLimitDelete, + kProjectsSpendLimitGet, kProjectsSpendLimitUpdate, kProjectsSpendLimitDelete, + kProjectsServiceAccountsApiKeysCreate, kWebhookEndpointsList, kWebhookEndpointsCreate, + kWebhookEndpointsGet, kWebhookEndpointsUpdate, kWebhookEndpointsDelete, + kWebhookEndpointsRotateSecret, kWebhookEndpointsTest, kWebhookEventTypesList, +}; + +// Which credential a call needs. The organization surface takes an admin key +// only; the webhook endpoint management calls take a project API key +// (OpenAPI security: default ApiKeyAuth, see SPEC.md). +enum class AuthKind { kAdmin, kProject }; + +struct CallSpec { + Call call; + const char* key; // stable name, "projects.users.list" + const char* http_method; // GET POST DELETE + const char* path; // OpenAPI path under /v1, "{id}" placeholders + const char* op_id; // OpenAPI operationId + const char* auth; // "admin" or "project" + const char* body_fields; // comma list: request body fields we may send + const char* required_fields; // comma list: body fields that must be present + const char* query_params; // comma list: query parameter names (literal, with []) + const char* request_schema; // named request schema, "" when inline + const char* response_schema; // named 200 response schema, "" when inline + const char* flags; // "destructive" or "" +}; + +struct SchemaFields { + const char* schema; // components.schemas name + const char* fields; // comma list: properties we read +}; + +class CallTable { + public: + static std::size_t size(); + static const CallSpec& at(std::size_t index); + static const CallSpec& spec(Call call); + static const CallSpec* find(const std::string& key); + static clients::Method method(Call call); + static AuthKind auth(Call call); + static bool destructive(Call call); + + // Ordered {placeholder} names of the path template ("project_id", "user_id"). + static std::vector path_params(Call call); + // Replaces the placeholders in order. Every id is validated (one URL path + // segment of [A-Za-z0-9._:-], 1..256, not "." or ".."); the count must match. + static std::string render(Call call, const std::vector& ids); + + static bool allows_body_field(Call call, const std::string& field); + static std::vector required_body_fields(Call call); + static bool allows_query(Call call, const std::string& name); + + static std::size_t schema_count(); + static const SchemaFields& schema_at(std::size_t index); + static const SchemaFields* schema(const std::string& name); + + // Comma-list helpers shared with the audit and usage code. + static std::vector split(const char* comma_list); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/caps.h b/src/openai/admin/caps.h new file mode 100644 index 0000000..845e420 --- /dev/null +++ b/src/openai/admin/caps.h @@ -0,0 +1,62 @@ +#pragma once + +// Static ceilings for the OpenAI organization administration surface. Never +// autotuned. Values marked (api) are ranges OpenAI documents; the rest are +// local floors and ceilings chosen here and listed in SPEC.md section 3. + +#include +#include + +namespace molo::openai::admin { + +struct AdminCaps { + // Paging. + static constexpr int kDefaultPageLimit = 20; // (api) default of every list + static constexpr int kMaxPageLimit = 100; // (api) 1..100 on id-cursor lists + static constexpr int kMaxListPages = 20; // page walks stop here, loudly + static constexpr std::size_t kMaxWalkItems = 2000; // items returned by one walk + static constexpr std::size_t kMaxCursorChars = 512; // after / before / page tokens + + // Usage and costs: bucket limits per bucket_width (api: the parameter text). + static constexpr int kMaxBuckets1d = 31; + static constexpr int kMaxBuckets1h = 168; + static constexpr int kMaxBuckets1m = 1440; + static constexpr int kDefaultBuckets1d = 7; + static constexpr int kMaxCostBuckets = 180; // (api) costs: 1..180, default 7 + static constexpr std::size_t kMaxFilterValues = 100; // values in one array filter + static constexpr std::size_t kMaxFilterChars = 256; // chars in one filter value + static constexpr std::size_t kMaxGroupBy = 8; + static constexpr std::int64_t kMaxTimeSeconds = 4102444800; // 2100-01-01 + + // Names and free text. + static constexpr std::size_t kMaxNameChars = 256; + static constexpr std::size_t kMaxEmailChars = 320; + static constexpr std::size_t kMaxDescriptionChars = 1024; + static constexpr std::size_t kMaxRoleChars = 128; + static constexpr std::size_t kMaxPermissions = 256; + static constexpr std::size_t kMaxInviteProjects = 100; + static constexpr std::size_t kMaxModelIds = 500; + static constexpr std::size_t kMaxScopes = 32; + static constexpr std::int64_t kMaxExpiresInSeconds = 315360000; // 10 years + static constexpr std::size_t kMaxCertificateIds = 10; + static constexpr std::size_t kMaxCertificatePemBytes = 64u * 1024u; + + // Audit logs. + static constexpr std::size_t kMaxAuditEventTypes = 50; + + // Webhooks. + static constexpr std::size_t kMaxWebhookBodyBytes = 1024u * 1024u; + static constexpr std::size_t kMaxWebhookHeaderChars = 4096; + static constexpr std::size_t kMaxWebhookSignatures = 8; + static constexpr std::int64_t kDefaultToleranceSeconds = 300; // SDK default: 5 minutes + static constexpr std::int64_t kMaxToleranceSeconds = 3600; + static constexpr std::size_t kMinSecretBytes = 24; // SDK: decoded whsec_ key + static constexpr std::size_t kMaxSecretChars = 512; + static constexpr std::size_t kMaxWebhookUrlChars = 2048; + static constexpr std::size_t kMaxEndpointEventTypes = 64; + + // Request body ceiling for a single admin call (all bodies are small). + static constexpr std::size_t kMaxBodyBytes = 256u * 1024u; +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/crypto_link.cpp b/src/openai/admin/crypto_link.cpp new file mode 100644 index 0000000..34573fe --- /dev/null +++ b/src/openai/admin/crypto_link.cpp @@ -0,0 +1,9 @@ +// Link shim. src/ai.mk (shared, not editable from this package) compiles only +// src/security/crypto/Base64.cpp into libai, but WebhookVerifier uses +// security::crypto::Hmac (and SecureRandom::constant_time_equal), which need +// Sha256.cpp, Hmac.cpp and SecureRandom.cpp. They are compiled here until the +// integration step adds those three files to AI_SRCS in src/ai.mk; then delete +// this file (keeping both would be a duplicate symbol error at link time). +#include "security/crypto/Sha256.cpp" +#include "security/crypto/Hmac.cpp" +#include "security/crypto/SecureRandom.cpp" diff --git a/src/openai/admin/governance.cpp b/src/openai/admin/governance.cpp new file mode 100644 index 0000000..d706982 --- /dev/null +++ b/src/openai/admin/governance.cpp @@ -0,0 +1,160 @@ +#include "openai/admin/governance.h" + +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +using J = AdminService::Json; + +// ---- certificates ---- + +void Certificates::require_org(const char* what) const { + if (!project_id_.empty()) + Validate::fail(std::string(what) + " exists at organization scope only"); +} + +J Certificates::list(const ListOptions& options) { + if (project_id_.empty()) return execute(Call::kCertificatesList, {}, options.to_query()); + return execute(Call::kProjectsCertificatesList, {project_id_}, options.to_query()); +} + +J Certificates::get(const std::string& certificate_id, bool include_content) { + require_org("get certificate"); + Query q; + if (include_content) q.set("include", "content"); + return execute(Call::kCertificatesGet, {certificate_id}, q); +} + +J Certificates::upload(const CertificateUpload& certificate) { + require_org("upload certificate"); + Json body = certificate.to_json(); + return execute(Call::kCertificatesCreate, {}, {}, &body); +} + +J Certificates::rename(const std::string& certificate_id, const std::string& name) { + require_org("rename certificate"); + Validate::text("name", name, AdminCaps::kMaxNameChars); + Json body = object_of({{"name", Json(name)}}); + return execute(Call::kCertificatesUpdate, {certificate_id}, {}, &body); +} + +J Certificates::destroy(const std::string& certificate_id, bool confirm) { + require_org("delete certificate"); + return execute(Call::kCertificatesDelete, {certificate_id}, {}, nullptr, confirm); +} + +J Certificates::toggle(Call org_call, Call project_call, const std::vector& ids, + bool confirm) { + Validate::count("certificate_ids", ids.size(), AdminCaps::kMaxCertificateIds, false); + Json list = Json::array(); + for (const std::string& id : ids) { + Validate::id("certificate id", id); + list.push(Json(id)); + } + Json body = Json::object(); + body.set("certificate_ids", list); + if (project_id_.empty()) return execute(org_call, {}, {}, &body, confirm); + return execute(project_call, {project_id_}, {}, &body, confirm); +} + +J Certificates::activate(const std::vector& certificate_ids) { + return toggle(Call::kCertificatesActivate, Call::kProjectsCertificatesActivate, certificate_ids, + false); +} + +J Certificates::deactivate(const std::vector& certificate_ids, bool confirm) { + return toggle(Call::kCertificatesDeactivate, Call::kProjectsCertificatesDeactivate, + certificate_ids, confirm); +} + +// ---- spend alerts ---- + +std::vector SpendAlerts::ids(const std::string& alert_id) const { + std::vector out; + if (!project_id_.empty()) out.push_back(project_id_); + if (!alert_id.empty()) out.push_back(alert_id); + return out; +} + +J SpendAlerts::list(const ListOptions& options) { + return execute(project_id_.empty() ? Call::kSpendAlertsList : Call::kProjectsSpendAlertsList, + ids(), options.to_query()); +} + +J SpendAlerts::get(const std::string& alert_id) { + Validate::id("alert_id", alert_id); + return execute(project_id_.empty() ? Call::kSpendAlertsGet : Call::kProjectsSpendAlertsGet, + ids(alert_id)); +} + +J SpendAlerts::create(const SpendAlertSpec& spec) { + Json body = spec.to_json(); + return execute(project_id_.empty() ? Call::kSpendAlertsCreate : Call::kProjectsSpendAlertsCreate, + ids(), {}, &body); +} + +J SpendAlerts::update(const std::string& alert_id, const SpendAlertSpec& spec) { + Validate::id("alert_id", alert_id); + Json body = spec.to_json(); + return execute(project_id_.empty() ? Call::kSpendAlertsUpdate : Call::kProjectsSpendAlertsUpdate, + ids(alert_id), {}, &body); +} + +J SpendAlerts::destroy(const std::string& alert_id, bool confirm) { + Validate::id("alert_id", alert_id); + return execute(project_id_.empty() ? Call::kSpendAlertsDelete : Call::kProjectsSpendAlertsDelete, + ids(alert_id), {}, nullptr, confirm); +} + +// ---- organization policy ---- + +J OrganizationPolicies::spend_limit() { return execute(Call::kSpendLimitGet); } + +J OrganizationPolicies::set_spend_limit(const SpendLimitSpec& limit) { + Json body = limit.to_json(); + return execute(Call::kSpendLimitUpdate, {}, {}, &body); +} + +J OrganizationPolicies::clear_spend_limit(bool confirm) { + return execute(Call::kSpendLimitDelete, {}, {}, nullptr, confirm); +} + +J OrganizationPolicies::data_retention() { return execute(Call::kDataRetentionGet); } + +J OrganizationPolicies::set_data_retention(const std::string& retention_type, bool confirm) { + Json body = DataRetention::organization(retention_type); + return execute(Call::kDataRetentionUpdate, {}, {}, &body, confirm); +} + +// ---- external storage ---- + +J ExternalStorage::list(const ListOptions& options, const std::string& project_id) { + if (!options.before.empty()) + Validate::fail("external storage lists take limit, after and order only"); + Query q = options.to_query(); + if (!project_id.empty()) { + Validate::id("project_id", project_id); + q.set("project_id", project_id); + } + return execute(Call::kExternalStorageList, {}, q); +} + +J ExternalStorage::get(const std::string& external_storage_id) { + return execute(Call::kExternalStorageGet, {external_storage_id}); +} + +J ExternalStorage::create(const ExternalStorageSpec& spec) { + Json body = spec.to_json(); + return execute(Call::kExternalStorageCreate, {}, {}, &body); +} + +J ExternalStorage::validate(const std::string& external_storage_id) { + return execute(Call::kExternalStorageValidate, {external_storage_id}); +} + +J ExternalStorage::destroy(const std::string& external_storage_id, bool confirm) { + return execute(Call::kExternalStorageDelete, {external_storage_id}, {}, nullptr, confirm); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/governance.h b/src/openai/admin/governance.h new file mode 100644 index 0000000..42f2c3b --- /dev/null +++ b/src/openai/admin/governance.h @@ -0,0 +1,79 @@ +#pragma once + +// Organization governance: mTLS certificates, spend alerts, spend limit, data +// retention, external storage. Certificates and spend alerts exist at two +// scopes: the organization (default) and one project (pass its id). + +#include +#include + +#include "openai/admin/admin_service.h" +#include "openai/admin/requests.h" + +namespace molo::openai::admin { + +class Certificates : public AdminService { + public: + // project_id empty: organization scope. Upload, get, rename and delete only + // exist at organization scope; calling them on a project scope throws. + explicit Certificates(std::shared_ptr client, std::string project_id = "") + : AdminService(std::move(client)), project_id_(std::move(project_id)) {} + + Json list(const ListOptions& options = {}); + // include_content adds the PEM body to the answer (query include=content). + Json get(const std::string& certificate_id, bool include_content); + Json upload(const CertificateUpload& certificate); + Json rename(const std::string& certificate_id, const std::string& name); + Json destroy(const std::string& certificate_id, bool confirm); + Json activate(const std::vector& certificate_ids); + Json deactivate(const std::vector& certificate_ids, bool confirm); + + private: + Json toggle(Call org_call, Call project_call, const std::vector& ids, bool confirm); + void require_org(const char* what) const; + std::string project_id_; +}; + +class SpendAlerts : public AdminService { + public: + explicit SpendAlerts(std::shared_ptr client, std::string project_id = "") + : AdminService(std::move(client)), project_id_(std::move(project_id)) {} + + Json list(const ListOptions& options = {}); + Json get(const std::string& alert_id); + Json create(const SpendAlertSpec& spec); + Json update(const std::string& alert_id, const SpendAlertSpec& spec); + Json destroy(const std::string& alert_id, bool confirm); + + private: + std::vector ids(const std::string& alert_id = "") const; + std::string project_id_; +}; + +// Organization-wide policy: hard spend limit, data retention. +class OrganizationPolicies : public AdminService { + public: + explicit OrganizationPolicies(std::shared_ptr client) + : AdminService(std::move(client)) {} + + Json spend_limit(); + Json set_spend_limit(const SpendLimitSpec& limit); + Json clear_spend_limit(bool confirm); + + Json data_retention(); + // Changes how OpenAI retains the whole organization's data: needs confirm. + Json set_data_retention(const std::string& retention_type, bool confirm); +}; + +class ExternalStorage : public AdminService { + public: + explicit ExternalStorage(std::shared_ptr client) : AdminService(std::move(client)) {} + // project_id "" lists all projects. + Json list(const ListOptions& options = {}, const std::string& project_id = ""); + Json get(const std::string& external_storage_id); + Json create(const ExternalStorageSpec& spec); + Json validate(const std::string& external_storage_id); + Json destroy(const std::string& external_storage_id, bool confirm); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/identity.cpp b/src/openai/admin/identity.cpp new file mode 100644 index 0000000..f86c024 --- /dev/null +++ b/src/openai/admin/identity.cpp @@ -0,0 +1,188 @@ +#include "openai/admin/identity.h" + +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +// ---- admin api keys ---- + +AdminService::Json AdminApiKeys::list(const ListOptions& options) { + return execute(Call::kAdminApiKeysList, {}, options.to_query()); +} + +AdminService::Json AdminApiKeys::get(const std::string& key_id) { + return execute(Call::kAdminApiKeysGet, {key_id}); +} + +AdminService::Json AdminApiKeys::create(const std::string& name, + std::optional expires_in_seconds) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + Json body = Json::object(); + body.set("name", Json(name)); + if (expires_in_seconds) { + Validate::range("expires_in_seconds", *expires_in_seconds, 1, kMaxKeyExpirySeconds); + body.set("expires_in_seconds", Json(static_cast(*expires_in_seconds))); + } + return execute(Call::kAdminApiKeysCreate, {}, {}, &body); +} + +AdminService::Json AdminApiKeys::destroy(const std::string& key_id, bool confirm) { + return execute(Call::kAdminApiKeysDelete, {key_id}, {}, nullptr, confirm); +} + +// ---- users ---- + +AdminService::Json Users::list(const ListOptions& options, const std::vector& emails) { + Query q = options.to_query(); + for (const std::string& e : emails) Validate::email(e); + q.add_all("emails", emails); + return execute(Call::kUsersList, {}, q); +} + +AdminService::Json Users::get(const std::string& user_id) { + return execute(Call::kUsersGet, {user_id}); +} + +AdminService::Json Users::update(const std::string& user_id, const UserUpdate& update) { + Json body = update.to_json(); + return execute(Call::kUsersUpdate, {user_id}, {}, &body); +} + +AdminService::Json Users::destroy(const std::string& user_id, bool confirm) { + return execute(Call::kUsersDelete, {user_id}, {}, nullptr, confirm); +} + +AdminService::Json Users::list_roles(const std::string& user_id, const ListOptions& options) { + return execute(Call::kUsersRolesList, {user_id}, options.to_query()); +} + +AdminService::Json Users::assign_role(const std::string& user_id, const std::string& role_id) { + Validate::id("role_id", role_id); + Json body = object_of({{"role_id", Json(role_id)}}); + return execute(Call::kUsersRolesCreate, {user_id}, {}, &body); +} + +AdminService::Json Users::get_role(const std::string& user_id, const std::string& role_id) { + return execute(Call::kUsersRolesGet, {user_id, role_id}); +} + +AdminService::Json Users::unassign_role(const std::string& user_id, const std::string& role_id, + bool confirm) { + return execute(Call::kUsersRolesDelete, {user_id, role_id}, {}, nullptr, confirm); +} + +// ---- invites ---- + +AdminService::Json Invites::list(const ListOptions& options) { + Query q; + if (options.limit) { + Validate::range("limit", *options.limit, 1, AdminCaps::kMaxPageLimit); + q.set_int("limit", *options.limit); + } + if (!options.after.empty()) q.set("after", options.after); + return execute(Call::kInvitesList, {}, q); +} + +AdminService::Json Invites::get(const std::string& invite_id) { + return execute(Call::kInvitesGet, {invite_id}); +} + +AdminService::Json Invites::create(const InviteRequest& request) { + Json body = request.to_json(); + return execute(Call::kInvitesCreate, {}, {}, &body); +} + +AdminService::Json Invites::destroy(const std::string& invite_id, bool confirm) { + return execute(Call::kInvitesDelete, {invite_id}, {}, nullptr, confirm); +} + +// ---- groups ---- + +AdminService::Json Groups::list(const ListOptions& options) { + return execute(Call::kGroupsList, {}, options.to_query()); +} + +AdminService::Json Groups::get(const std::string& group_id) { + return execute(Call::kGroupsGet, {group_id}); +} + +AdminService::Json Groups::create(const std::string& name) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + Json body = object_of({{"name", Json(name)}}); + return execute(Call::kGroupsCreate, {}, {}, &body); +} + +AdminService::Json Groups::rename(const std::string& group_id, const std::string& name) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + Json body = object_of({{"name", Json(name)}}); + return execute(Call::kGroupsUpdate, {group_id}, {}, &body); +} + +AdminService::Json Groups::destroy(const std::string& group_id, bool confirm) { + return execute(Call::kGroupsDelete, {group_id}, {}, nullptr, confirm); +} + +AdminService::Json Groups::list_users(const std::string& group_id, const ListOptions& options) { + return execute(Call::kGroupsUsersList, {group_id}, options.to_query()); +} + +AdminService::Json Groups::add_user(const std::string& group_id, const std::string& user_id) { + Validate::id("user_id", user_id); + Json body = object_of({{"user_id", Json(user_id)}}); + return execute(Call::kGroupsUsersCreate, {group_id}, {}, &body); +} + +AdminService::Json Groups::get_user(const std::string& group_id, const std::string& user_id) { + return execute(Call::kGroupsUsersGet, {group_id, user_id}); +} + +AdminService::Json Groups::remove_user(const std::string& group_id, const std::string& user_id, + bool confirm) { + return execute(Call::kGroupsUsersDelete, {group_id, user_id}, {}, nullptr, confirm); +} + +AdminService::Json Groups::list_roles(const std::string& group_id, const ListOptions& options) { + return execute(Call::kGroupsRolesList, {group_id}, options.to_query()); +} + +AdminService::Json Groups::assign_role(const std::string& group_id, const std::string& role_id) { + Validate::id("role_id", role_id); + Json body = object_of({{"role_id", Json(role_id)}}); + return execute(Call::kGroupsRolesCreate, {group_id}, {}, &body); +} + +AdminService::Json Groups::get_role(const std::string& group_id, const std::string& role_id) { + return execute(Call::kGroupsRolesGet, {group_id, role_id}); +} + +AdminService::Json Groups::unassign_role(const std::string& group_id, const std::string& role_id, + bool confirm) { + return execute(Call::kGroupsRolesDelete, {group_id, role_id}, {}, nullptr, confirm); +} + +// ---- roles ---- + +AdminService::Json Roles::list(const ListOptions& options) { + return execute(Call::kRolesList, {}, options.to_query()); +} + +AdminService::Json Roles::get(const std::string& role_id) { + return execute(Call::kRolesGet, {role_id}); +} + +AdminService::Json Roles::create(const RoleSpec& spec) { + Json body = spec.to_json(); + return execute(Call::kRolesCreate, {}, {}, &body); +} + +AdminService::Json Roles::update(const std::string& role_id, const RoleUpdate& update) { + Json body = update.to_json(); + return execute(Call::kRolesUpdate, {role_id}, {}, &body); +} + +AdminService::Json Roles::destroy(const std::string& role_id, bool confirm) { + return execute(Call::kRolesDelete, {role_id}, {}, nullptr, confirm); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/identity.h b/src/openai/admin/identity.h new file mode 100644 index 0000000..df183ce --- /dev/null +++ b/src/openai/admin/identity.h @@ -0,0 +1,82 @@ +#pragma once + +// Organization identity: admin API keys, users, invites, groups, custom roles. +// Every destructive method takes `confirm` with no default. + +#include +#include + +#include "openai/admin/admin_service.h" +#include "openai/admin/requests.h" + +namespace molo::openai::admin { + +// /organization/admin_api_keys. `create` returns the secret value once. +class AdminApiKeys : public AdminService { + public: + explicit AdminApiKeys(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const ListOptions& options = {}); + Json get(const std::string& key_id); + Json create(const std::string& name, std::optional expires_in_seconds = std::nullopt); + Json destroy(const std::string& key_id, bool confirm); +}; + +// /organization/users and the role assignments of a user. +class Users : public AdminService { + public: + explicit Users(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const ListOptions& options = {}, const std::vector& emails = {}); + Json get(const std::string& user_id); + Json update(const std::string& user_id, const UserUpdate& update); + Json destroy(const std::string& user_id, bool confirm); + + Json list_roles(const std::string& user_id, const ListOptions& options = {}); + Json assign_role(const std::string& user_id, const std::string& role_id); + Json get_role(const std::string& user_id, const std::string& role_id); + Json unassign_role(const std::string& user_id, const std::string& role_id, bool confirm); +}; + +// /organization/invites. Invites are created, listed, read and deleted; the +// API has no resend or update. +class Invites : public AdminService { + public: + explicit Invites(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const ListOptions& options = {}); + Json get(const std::string& invite_id); + Json create(const InviteRequest& request); + Json destroy(const std::string& invite_id, bool confirm); +}; + +// /organization/groups with their users and role assignments. +class Groups : public AdminService { + public: + explicit Groups(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const ListOptions& options = {}); + Json get(const std::string& group_id); + Json create(const std::string& name); + Json rename(const std::string& group_id, const std::string& name); + Json destroy(const std::string& group_id, bool confirm); + + Json list_users(const std::string& group_id, const ListOptions& options = {}); + Json add_user(const std::string& group_id, const std::string& user_id); + Json get_user(const std::string& group_id, const std::string& user_id); + Json remove_user(const std::string& group_id, const std::string& user_id, bool confirm); + + Json list_roles(const std::string& group_id, const ListOptions& options = {}); + Json assign_role(const std::string& group_id, const std::string& role_id); + Json get_role(const std::string& group_id, const std::string& role_id); + Json unassign_role(const std::string& group_id, const std::string& role_id, bool confirm); +}; + +// /organization/roles: custom roles and their permissions. +class Roles : public AdminService { + public: + explicit Roles(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const ListOptions& options = {}); + Json get(const std::string& role_id); + Json create(const RoleSpec& spec); + Json update(const std::string& role_id, const RoleUpdate& update); + Json destroy(const std::string& role_id, bool confirm); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/openai_admin.cpp b/src/openai/admin/openai_admin.cpp new file mode 100644 index 0000000..a6c1bb7 --- /dev/null +++ b/src/openai/admin/openai_admin.cpp @@ -0,0 +1,53 @@ +#include "openai/admin/openai_admin.h" + +#include "clients/transports/http_transport.h" + +namespace molo::openai::admin { + +namespace { +// webhook_endpoints must always hold a client; an empty-key one reports +// not configured on every call. +std::shared_ptr or_empty(std::shared_ptr p) { + if (p) return p; + return ProjectApiClient::with_transport(std::make_unique(), ""); +} +} // namespace + +OpenaiAdmin::OpenaiAdmin(std::shared_ptr admin, + std::shared_ptr project) + : admin_keys(admin), + users(admin), + invites(admin), + groups(admin), + roles(admin), + projects(admin), + project_users(admin), + service_accounts(admin), + project_api_keys(admin), + rate_limits(admin), + project_groups(admin), + project_policies(admin), + organization_policies(admin), + external_storage(admin), + usage(admin), + costs(admin), + audit_logs(admin), + webhook_endpoints(or_empty(project)), + admin_(std::move(admin)), + project_(std::move(project)) {} + +OpenaiAdmin OpenaiAdmin::from_env(Region region) { + OpenaiAdmin out(AdminApiClient::from_env(region), ProjectApiClient::from_env(region)); + out.region_ = region; + return out; +} + +Certificates OpenaiAdmin::certificates(const std::string& project_id) const { + return Certificates(admin_, project_id); +} + +SpendAlerts OpenaiAdmin::spend_alerts(const std::string& project_id) const { + return SpendAlerts(admin_, project_id); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/openai_admin.h b/src/openai/admin/openai_admin.h new file mode 100644 index 0000000..5204522 --- /dev/null +++ b/src/openai/admin/openai_admin.h @@ -0,0 +1,66 @@ +#pragma once + +// The facade of the package: every resource service built on one admin +// client, plus the optional project-key client for webhook endpoints. +// `OpenaiAdmin::from_env` reads OPENAI_ADMIN_KEY (and OPENAI_API_KEY for +// webhook endpoint management) through llm::Config. A key of the wrong kind +// is refused with ApiError 401 WRONG_KEY_KIND. + +#include +#include +#include + +#include "openai/admin/admin_client.h" +#include "openai/admin/audit_log.h" +#include "openai/admin/governance.h" +#include "openai/admin/identity.h" +#include "openai/admin/projects.h" +#include "openai/admin/usage.h" +#include "openai/admin/webhooks.h" + +namespace molo::openai::admin { + +class OpenaiAdmin { + public: + OpenaiAdmin(std::shared_ptr admin, + std::shared_ptr project = nullptr); + + // Throws ApiError WRONG_KEY_KIND for a mis-typed key; empty keys are fine + // (every call then answers NotConfiguredError before any traffic). + static OpenaiAdmin from_env(Region region = Region::kGlobal); + + bool configured() const { return admin_->configured(); } + bool webhook_management_configured() const { return project_ && project_->configured(); } + Region region() const { return region_; } + const llm::ApiClient& client() const { return *admin_; } + + AdminApiKeys admin_keys; + Users users; + Invites invites; + Groups groups; + Roles roles; + Projects projects; + ProjectUsers project_users; + ServiceAccounts service_accounts; + ProjectApiKeys project_api_keys; + RateLimits rate_limits; + ProjectGroups project_groups; + ProjectPolicies project_policies; + OrganizationPolicies organization_policies; + ExternalStorage external_storage; + Usage usage; + Costs costs; + AuditLogs audit_logs; + // Null-safe: calls throw NotConfiguredError when no project key is set. + WebhookEndpoints webhook_endpoints; + + Certificates certificates(const std::string& project_id = "") const; + SpendAlerts spend_alerts(const std::string& project_id = "") const; + + private: + std::shared_ptr admin_; + std::shared_ptr project_; + Region region_ = Region::kGlobal; +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/page.cpp b/src/openai/admin/page.cpp new file mode 100644 index 0000000..223d471 --- /dev/null +++ b/src/openai/admin/page.cpp @@ -0,0 +1,80 @@ +#include "openai/admin/page.h" + +#include "llm/error.h" +#include "openai/admin/caps.h" + +namespace molo::openai::admin { + +using clients::body::Json; + +namespace { +std::string text_or_empty(const Json& doc, const char* key) { + const Json* v = doc.find(key); + return v && v->is_string() ? v->as_string() : ""; +} +} // namespace + +Page::Page(Json envelope) : envelope_(std::move(envelope)) { + if (!envelope_.is_object() || !envelope_.find("data") || !envelope_.find("data")->is_array()) + throw llm::ApiError("openai", 502, "BAD_RESPONSE", "list response has no data array"); + const Json* more = envelope_.find("has_more"); + has_more_ = more && more->is_bool() && more->as_bool(); + token_style_ = envelope_.find("next_page") != nullptr; + first_id_ = text_or_empty(envelope_, "first_id"); + last_id_ = text_or_empty(envelope_, "last_id"); + next_page_ = text_or_empty(envelope_, "next_page"); +} + +const Json::Array& Page::items() const { return envelope_.find("data")->as_array(); } + +std::string Page::next_cursor() const { + if (!has_more_) return ""; + return token_style_ ? next_page_ : last_id_; +} + +Json WalkResult::to_json() const { + Json o = Json::object(); + o.set("data", items); + o.set("pages", Json(pages)); + o.set("count", Json(static_cast(items.as_array().size()))); + o.set("truncated", Json(truncated)); + if (truncated) { + o.set("truncated_reason", Json(reason)); + o.set("next_cursor", Json(next_cursor)); + } + return o; +} + +WalkResult PageWalker::walk(const Fetch& fetch, const std::string& start_cursor) { + WalkResult out; + std::string cursor = start_cursor; + for (;;) { + Page page(fetch(cursor)); + ++out.pages; + for (const Json& item : page.items()) { + if (out.items.as_array().size() >= AdminCaps::kMaxWalkItems) { + out.truncated = true; + out.reason = "item ceiling"; + out.next_cursor = cursor; + return out; + } + out.items.push(item); + } + cursor = page.next_cursor(); + if (cursor.empty()) { + if (page.has_more()) { // more data but no way to continue: say so + out.truncated = true; + out.reason = "server sent has_more without a cursor"; + } + return out; + } + if (out.pages >= AdminCaps::kMaxListPages) { + out.truncated = true; + out.reason = "page ceiling"; + out.next_cursor = cursor; + return out; + } + } +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/page.h b/src/openai/admin/page.h new file mode 100644 index 0000000..11649d2 --- /dev/null +++ b/src/openai/admin/page.h @@ -0,0 +1,59 @@ +#pragma once + +// List envelopes and bounded page walks. +// +// Two paging styles exist in the API: +// cursor {object:"list", data, first_id, last_id, has_more}, next page is +// `after=` (users, projects, groups, audit logs, ...) +// token {object:"page", data, has_more, next_page}, next page is +// `page=` (usage and costs) +// A walk never exceeds AdminCaps::kMaxListPages pages or kMaxWalkItems items; +// when it stops with more data available, `truncated` is true and `reason` +// says which ceiling was hit. Truncation is never silent. + +#include +#include + +#include "clients/body/json.h" + +namespace molo::openai::admin { + +class Page { + public: + explicit Page(clients::body::Json envelope); + + const clients::body::Json& envelope() const { return envelope_; } + const clients::body::Json::Array& items() const; + bool has_more() const { return has_more_; } + bool token_style() const { return token_style_; } + const std::string& first_id() const { return first_id_; } + const std::string& last_id() const { return last_id_; } + const std::string& next_page() const { return next_page_; } + // The value to send as `after` (cursor) or `page` (token); "" when done. + std::string next_cursor() const; + + private: + clients::body::Json envelope_; + bool has_more_ = false; + bool token_style_ = false; + std::string first_id_, last_id_, next_page_; +}; + +struct WalkResult { + clients::body::Json items = clients::body::Json::array(); + int pages = 0; + bool truncated = false; + std::string reason; // "" or "page ceiling" / "item ceiling" + std::string next_cursor; // resume point when truncated + + clients::body::Json to_json() const; +}; + +class PageWalker { + public: + // fetch(cursor) returns one envelope; cursor is "" for the first page. + using Fetch = std::function; + static WalkResult walk(const Fetch& fetch, const std::string& start_cursor = ""); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/projects.cpp b/src/openai/admin/projects.cpp new file mode 100644 index 0000000..0ed62bc --- /dev/null +++ b/src/openai/admin/projects.cpp @@ -0,0 +1,209 @@ +#include "openai/admin/projects.h" + +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +using J = AdminService::Json; + +// ---- projects ---- + +J Projects::list(const ListOptions& options, bool include_archived) { + Query q = options.to_query(); + if (include_archived) q.set_bool("include_archived", true); + return execute(Call::kProjectsList, {}, q); +} + +J Projects::get(const std::string& project_id) { return execute(Call::kProjectsGet, {project_id}); } + +J Projects::create(const ProjectCreate& project) { + Json body = project.to_json(); + return execute(Call::kProjectsCreate, {}, {}, &body); +} + +J Projects::update(const std::string& project_id, const ProjectUpdate& update) { + Json body = update.to_json(); + return execute(Call::kProjectsUpdate, {project_id}, {}, &body); +} + +J Projects::archive(const std::string& project_id, bool confirm) { + return execute(Call::kProjectsArchive, {project_id}, {}, nullptr, confirm); +} + +// ---- project users ---- + +J ProjectUsers::list(const std::string& project_id, const ListOptions& options) { + return execute(Call::kProjectsUsersList, {project_id}, options.to_query()); +} + +J ProjectUsers::get(const std::string& project_id, const std::string& user_id) { + return execute(Call::kProjectsUsersGet, {project_id, user_id}); +} + +J ProjectUsers::create(const std::string& project_id, const ProjectUserCreate& user) { + Json body = user.to_json(); + return execute(Call::kProjectsUsersCreate, {project_id}, {}, &body); +} + +J ProjectUsers::set_role(const std::string& project_id, const std::string& user_id, + const std::string& role) { + Validate::one_of("role", role, {"owner", "member"}); + Json body = object_of({{"role", Json(role)}}); + return execute(Call::kProjectsUsersUpdate, {project_id, user_id}, {}, &body); +} + +J ProjectUsers::destroy(const std::string& project_id, const std::string& user_id, bool confirm) { + return execute(Call::kProjectsUsersDelete, {project_id, user_id}, {}, nullptr, confirm); +} + +// ---- service accounts ---- + +J ServiceAccounts::list(const std::string& project_id, const ListOptions& options) { + return execute(Call::kProjectsServiceAccountsList, {project_id}, options.to_query()); +} + +J ServiceAccounts::get(const std::string& project_id, const std::string& service_account_id) { + return execute(Call::kProjectsServiceAccountsGet, {project_id, service_account_id}); +} + +J ServiceAccounts::create(const std::string& project_id, const ServiceAccountCreate& account) { + Json body = account.to_json(); + return execute(Call::kProjectsServiceAccountsCreate, {project_id}, {}, &body); +} + +J ServiceAccounts::update(const std::string& project_id, const std::string& service_account_id, + const ServiceAccountUpdate& update) { + Json body = update.to_json(); + return execute(Call::kProjectsServiceAccountsUpdate, {project_id, service_account_id}, {}, &body); +} + +J ServiceAccounts::destroy(const std::string& project_id, const std::string& service_account_id, + bool confirm) { + return execute(Call::kProjectsServiceAccountsDelete, {project_id, service_account_id}, {}, nullptr, + confirm); +} + +J ServiceAccounts::create_key(const std::string& project_id, const std::string& service_account_id, + const ServiceAccountKeyCreate& key) { + Json body = key.to_json(); + return execute(Call::kProjectsServiceAccountsApiKeysCreate, {project_id, service_account_id}, {}, + &body); +} + +// ---- project api keys ---- + +J ProjectApiKeys::list(const std::string& project_id, const ListOptions& options, + const std::string& owner_project_access) { + Query q = options.to_query(); + if (!owner_project_access.empty()) { + Validate::one_of("owner_project_access", owner_project_access, {"active", "inactive", "any"}); + q.set("owner_project_access", owner_project_access); + } + return execute(Call::kProjectsApiKeysList, {project_id}, q); +} + +J ProjectApiKeys::get(const std::string& project_id, const std::string& api_key_id) { + return execute(Call::kProjectsApiKeysGet, {project_id, api_key_id}); +} + +J ProjectApiKeys::update(const std::string& project_id, const std::string& api_key_id, + const ProjectApiKeyUpdate& update) { + Json body = update.to_json(); + return execute(Call::kProjectsApiKeysUpdate, {project_id, api_key_id}, {}, &body); +} + +J ProjectApiKeys::destroy(const std::string& project_id, const std::string& api_key_id, + bool confirm) { + return execute(Call::kProjectsApiKeysDelete, {project_id, api_key_id}, {}, nullptr, confirm); +} + +// ---- rate limits ---- + +J RateLimits::list(const std::string& project_id, const ListOptions& options) { + return execute(Call::kProjectsRateLimitsList, {project_id}, options.to_query()); +} + +J RateLimits::update(const std::string& project_id, const std::string& rate_limit_id, + const RateLimitUpdate& update) { + Json body = update.to_json(); + return execute(Call::kProjectsRateLimitsUpdate, {project_id, rate_limit_id}, {}, &body); +} + +// ---- project groups ---- + +J ProjectGroups::list(const std::string& project_id, const ListOptions& options) { + return execute(Call::kProjectsGroupsList, {project_id}, options.to_query()); +} + +J ProjectGroups::add(const std::string& project_id, const std::string& group_id, + const std::string& role) { + Validate::id("group_id", group_id); + Validate::text("role", role, 128); + Json body = object_of({{"group_id", Json(group_id)}, {"role", Json(role)}}); + return execute(Call::kProjectsGroupsCreate, {project_id}, {}, &body); +} + +J ProjectGroups::get(const std::string& project_id, const std::string& group_id, + const std::string& group_type) { + Query q; + if (!group_type.empty()) { + Validate::one_of("group_type", group_type, {"group", "tenant_group"}); + q.set("group_type", group_type); + } + return execute(Call::kProjectsGroupsGet, {project_id, group_id}, q); +} + +J ProjectGroups::remove(const std::string& project_id, const std::string& group_id, bool confirm) { + return execute(Call::kProjectsGroupsDelete, {project_id, group_id}, {}, nullptr, confirm); +} + +// ---- project policies ---- + +J ProjectPolicies::data_retention(const std::string& project_id) { + return execute(Call::kProjectsDataRetentionGet, {project_id}); +} + +J ProjectPolicies::set_data_retention(const std::string& project_id, + const std::string& retention_type, bool confirm) { + Json body = DataRetention::project(retention_type); + return execute(Call::kProjectsDataRetentionUpdate, {project_id}, {}, &body, confirm); +} + +J ProjectPolicies::model_permissions(const std::string& project_id) { + return execute(Call::kProjectsModelPermissionsGet, {project_id}); +} + +J ProjectPolicies::set_model_permissions(const std::string& project_id, + const ModelPermissions& permissions) { + Json body = permissions.to_json(); + return execute(Call::kProjectsModelPermissionsUpdate, {project_id}, {}, &body); +} + +J ProjectPolicies::clear_model_permissions(const std::string& project_id, bool confirm) { + return execute(Call::kProjectsModelPermissionsDelete, {project_id}, {}, nullptr, confirm); +} + +J ProjectPolicies::hosted_tool_permissions(const std::string& project_id) { + return execute(Call::kProjectsHostedToolPermissionsGet, {project_id}); +} + +J ProjectPolicies::set_hosted_tool_permissions(const std::string& project_id, + const HostedToolPermissions& permissions) { + Json body = permissions.to_json(); + return execute(Call::kProjectsHostedToolPermissionsUpdate, {project_id}, {}, &body); +} + +J ProjectPolicies::spend_limit(const std::string& project_id) { + return execute(Call::kProjectsSpendLimitGet, {project_id}); +} + +J ProjectPolicies::set_spend_limit(const std::string& project_id, const SpendLimitSpec& limit) { + Json body = limit.to_json(); + return execute(Call::kProjectsSpendLimitUpdate, {project_id}, {}, &body); +} + +J ProjectPolicies::clear_spend_limit(const std::string& project_id, bool confirm) { + return execute(Call::kProjectsSpendLimitDelete, {project_id}, {}, nullptr, confirm); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/projects.h b/src/openai/admin/projects.h new file mode 100644 index 0000000..6a38cf4 --- /dev/null +++ b/src/openai/admin/projects.h @@ -0,0 +1,105 @@ +#pragma once + +// Projects and everything that hangs off one: users, service accounts, API +// keys, rate limits, groups, data retention, model and hosted tool +// permissions, spend limit. Destructive methods take `confirm`, no default. + +#include + +#include "openai/admin/admin_service.h" +#include "openai/admin/requests.h" + +namespace molo::openai::admin { + +class Projects : public AdminService { + public: + explicit Projects(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const ListOptions& options = {}, bool include_archived = false); + Json get(const std::string& project_id); + Json create(const ProjectCreate& project); + Json update(const std::string& project_id, const ProjectUpdate& update); + // Archiving a project cannot be undone through the API. + Json archive(const std::string& project_id, bool confirm); +}; + +class ProjectUsers : public AdminService { + public: + explicit ProjectUsers(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const std::string& project_id, const ListOptions& options = {}); + Json get(const std::string& project_id, const std::string& user_id); + Json create(const std::string& project_id, const ProjectUserCreate& user); + Json set_role(const std::string& project_id, const std::string& user_id, const std::string& role); + Json destroy(const std::string& project_id, const std::string& user_id, bool confirm); +}; + +class ServiceAccounts : public AdminService { + public: + explicit ServiceAccounts(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const std::string& project_id, const ListOptions& options = {}); + Json get(const std::string& project_id, const std::string& service_account_id); + // The response carries the API key value once, unless create_service_account_only. + Json create(const std::string& project_id, const ServiceAccountCreate& account); + Json update(const std::string& project_id, const std::string& service_account_id, + const ServiceAccountUpdate& update); + Json destroy(const std::string& project_id, const std::string& service_account_id, bool confirm); + // Mints a new API key for the service account (value returned once). + Json create_key(const std::string& project_id, const std::string& service_account_id, + const ServiceAccountKeyCreate& key); +}; + +class ProjectApiKeys : public AdminService { + public: + explicit ProjectApiKeys(std::shared_ptr client) : AdminService(std::move(client)) {} + // owner_project_access: active | inactive | any, or "" for the server default. + Json list(const std::string& project_id, const ListOptions& options = {}, + const std::string& owner_project_access = ""); + Json get(const std::string& project_id, const std::string& api_key_id); + Json update(const std::string& project_id, const std::string& api_key_id, + const ProjectApiKeyUpdate& update); + Json destroy(const std::string& project_id, const std::string& api_key_id, bool confirm); +}; + +class RateLimits : public AdminService { + public: + explicit RateLimits(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const std::string& project_id, const ListOptions& options = {}); + Json update(const std::string& project_id, const std::string& rate_limit_id, + const RateLimitUpdate& update); +}; + +class ProjectGroups : public AdminService { + public: + explicit ProjectGroups(std::shared_ptr client) : AdminService(std::move(client)) {} + Json list(const std::string& project_id, const ListOptions& options = {}); + Json add(const std::string& project_id, const std::string& group_id, const std::string& role); + // group_type: group | tenant_group, or "" for the server default. + Json get(const std::string& project_id, const std::string& group_id, + const std::string& group_type = ""); + Json remove(const std::string& project_id, const std::string& group_id, bool confirm); +}; + +// Per-project policy: data retention, model permissions, hosted tool +// permissions, hard spend limit. +class ProjectPolicies : public AdminService { + public: + explicit ProjectPolicies(std::shared_ptr client) : AdminService(std::move(client)) {} + + Json data_retention(const std::string& project_id); + // Changes how OpenAI retains the project's data: needs confirm. + Json set_data_retention(const std::string& project_id, const std::string& retention_type, + bool confirm); + + Json model_permissions(const std::string& project_id); + Json set_model_permissions(const std::string& project_id, const ModelPermissions& permissions); + Json clear_model_permissions(const std::string& project_id, bool confirm); + + Json hosted_tool_permissions(const std::string& project_id); + Json set_hosted_tool_permissions(const std::string& project_id, + const HostedToolPermissions& permissions); + + Json spend_limit(const std::string& project_id); + Json set_spend_limit(const std::string& project_id, const SpendLimitSpec& limit); + Json clear_spend_limit(const std::string& project_id, bool confirm); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/query.cpp b/src/openai/admin/query.cpp new file mode 100644 index 0000000..f936ff9 --- /dev/null +++ b/src/openai/admin/query.cpp @@ -0,0 +1,93 @@ +#include "openai/admin/query.h" + +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +namespace { +void check_name(const std::string& name) { + if (name.empty() || name.size() > 64) Validate::fail("bad query parameter name"); + for (char c : name) + if (!((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || + c == '_' || c == '[' || c == ']')) + Validate::fail("bad query parameter name"); +} +constexpr std::size_t kMaxPairs = 256; +} // namespace + +Query& Query::set(const std::string& name, const std::string& value) { + check_name(name); + Validate::text("query " + name, value, AdminCaps::kMaxCursorChars, true); + if (pairs_.size() >= kMaxPairs) Validate::fail("too many query parameters"); + pairs_.emplace_back(name, value); + return *this; +} + +Query& Query::set_int(const std::string& name, std::int64_t value) { + return set(name, std::to_string(value)); +} + +Query& Query::set_bool(const std::string& name, bool value) { + return set(name, value ? "true" : "false"); +} + +Query& Query::add_all(const std::string& name, const std::vector& values) { + Validate::count(name, values.size(), AdminCaps::kMaxFilterValues, true); + for (const std::string& v : values) { + Validate::text(name, v, AdminCaps::kMaxFilterChars); + set(name, v); + } + return *this; +} + +bool Query::has(const std::string& name) const { + for (const auto& p : pairs_) + if (p.first == name) return true; + return false; +} + +void Query::check_against(Call call) const { + for (const auto& p : pairs_) + if (!CallTable::allows_query(call, p.first)) + Validate::fail(std::string(CallTable::spec(call).key) + " has no query parameter " + p.first); +} + +std::string Query::escape(const std::string& text) { + static const char* kHex = "0123456789ABCDEF"; + std::string out; + for (unsigned char c : text) { + if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c == '-' || + c == '_' || c == '.' || c == '~') { + out += static_cast(c); + } else { + out += '%'; + out += kHex[c >> 4]; + out += kHex[c & 15]; + } + } + return out; +} + +std::string Query::encoded() const { + std::string out; + for (const auto& p : pairs_) out += (out.empty() ? "?" : "&") + escape(p.first) + "=" + escape(p.second); + return out; +} + +Query ListOptions::to_query() const { + Query q; + if (limit) { + Validate::range("limit", *limit, 1, AdminCaps::kMaxPageLimit); + q.set_int("limit", *limit); + } + if (!after.empty()) q.set("after", after); + if (!before.empty()) q.set("before", before); + if (!order.empty()) { + Validate::one_of("order", order, {"asc", "desc"}); + q.set("order", order); + } + return q; +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/query.h b/src/openai/admin/query.h new file mode 100644 index 0000000..38c209f --- /dev/null +++ b/src/openai/admin/query.h @@ -0,0 +1,53 @@ +#pragma once + +// Query strings. `Query` is an ordered, validated, percent-encoded parameter +// list; `ListOptions` is the id-cursor paging every list call shares. +// Array filters repeat the name ("project_ids=a&project_ids=b", the form the +// OpenAPI document declares); names that the spec spells with brackets +// ("project_ids[]" on audit logs) are passed with the brackets. + +#include +#include +#include +#include +#include + +#include "openai/admin/calls.h" + +namespace molo::openai::admin { + +class Query { + public: + Query& set(const std::string& name, const std::string& value); + Query& set_int(const std::string& name, std::int64_t value); + Query& set_bool(const std::string& name, bool value); + // One "name=value" pair per entry; entries are capped. + Query& add_all(const std::string& name, const std::vector& values); + + bool empty() const { return pairs_.empty(); } + std::size_t size() const { return pairs_.size(); } + const std::vector>& pairs() const { return pairs_; } + bool has(const std::string& name) const; + // Throws unless every name is a query parameter of the call (table). + void check_against(Call call) const; + // "?a=1&b=2" or "" (percent-encoded, deterministic order of insertion). + std::string encoded() const; + + static std::string escape(const std::string& text); + + private: + std::vector> pairs_; +}; + +// limit / after / before / order of the id-cursor lists. Which of them a call +// takes is decided by the call table; sending one the call lacks throws. +struct ListOptions { + std::optional limit; // 1..100 + std::string after; + std::string before; + std::string order; // "asc" or "desc" + + Query to_query() const; +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/requests.cpp b/src/openai/admin/requests.cpp new file mode 100644 index 0000000..d24ab13 --- /dev/null +++ b/src/openai/admin/requests.cpp @@ -0,0 +1,383 @@ +#include "openai/admin/requests.h" + +#include + +#include "openai/admin/admin_client.h" +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" +#include "openai/admin/webhook_events.h" + +namespace molo::openai::admin { + +namespace { + +Json string_array(const std::vector& values) { + Json a = Json::array(); + for (const std::string& v : values) a.push(Json(v)); + return a; +} + +void put_int(Json& o, const char* key, const std::optional& value) { + if (value) o.set(key, Json(static_cast(*value))); +} + +void check_expiry(const std::optional& seconds) { + if (seconds) Validate::range("expires_in_seconds", *seconds, 1, kMaxKeyExpirySeconds); +} + +void check_scopes(const std::vector& scopes) { + Validate::count("scopes", scopes.size(), AdminCaps::kMaxScopes, true); + for (const std::string& s : scopes) Validate::text("scope", s, AdminCaps::kMaxRoleChars); +} + +void need_one(const Json& o, const char* what) { + if (o.as_object().empty()) Validate::fail(std::string(what) + " needs at least one field"); +} + +} // namespace + +Json InviteRequest::to_json() const { + Validate::email(email); + Validate::one_of("role", role, {"reader", "owner"}); + Validate::count("projects", projects.size(), AdminCaps::kMaxInviteProjects, true); + Json o = Json::object(); + o.set("email", Json(email)); + o.set("role", Json(role)); + if (!projects.empty()) { + Json list = Json::array(); + for (const ProjectGrant& g : projects) { + Validate::id("project id", g.id); + Validate::one_of("project role", g.role, {"member", "owner"}); + Json p = Json::object(); + p.set("id", Json(g.id)); + p.set("role", Json(g.role)); + list.push(p); + } + o.set("projects", list); + } + return o; +} + +Json ProjectCreate::to_json() const { + Validate::text("name", name, AdminCaps::kMaxNameChars); + Json o = Json::object(); + o.set("name", Json(name)); + if (!residency.empty()) { + const auto& all = Regions::residency_values(); + if (std::find(all.begin(), all.end(), residency) == all.end()) + Validate::fail("residency is not a PublicProjectResidency value"); + o.set("residency", Json(residency)); + } + if (!geography.empty()) { + Validate::text("geography", geography, 32); + o.set("geography", Json(geography)); + } + if (!external_key_id.empty()) { + Validate::id("external_key_id", external_key_id); + o.set("external_key_id", Json(external_key_id)); + } + return o; +} + +Json ProjectUpdate::to_json() const { + Json o = Json::object(); + if (!name.empty()) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + o.set("name", Json(name)); + } + if (!external_key_id.empty()) { + Validate::id("external_key_id", external_key_id); + o.set("external_key_id", Json(external_key_id)); + } + if (!geography.empty()) { + Validate::text("geography", geography, 32); + o.set("geography", Json(geography)); + } + need_one(o, "project update"); + return o; +} + +Json ProjectUserCreate::to_json() const { + if (user_id.empty() == email.empty()) Validate::fail("give exactly one of user_id and email"); + Validate::one_of("role", role, {"owner", "member"}); + Json o = Json::object(); + if (!user_id.empty()) { + Validate::id("user_id", user_id); + o.set("user_id", Json(user_id)); + } else { + Validate::email(email); + o.set("email", Json(email)); + } + o.set("role", Json(role)); + return o; +} + +Json UserUpdate::to_json() const { + Json o = Json::object(); + if (!role.empty()) { + Validate::one_of("role", role, {"owner", "reader"}); + o.set("role", Json(role)); + } + if (!role_id.empty()) { + Validate::id("role_id", role_id); + o.set("role_id", Json(role_id)); + } + if (!technical_level.empty()) { + Validate::text("technical_level", technical_level, AdminCaps::kMaxRoleChars); + o.set("technical_level", Json(technical_level)); + } + if (!developer_persona.empty()) { + Validate::text("developer_persona", developer_persona, AdminCaps::kMaxRoleChars); + o.set("developer_persona", Json(developer_persona)); + } + need_one(o, "user update"); + return o; +} + +Json ServiceAccountCreate::to_json() const { + Validate::text("name", name, AdminCaps::kMaxNameChars); + check_expiry(expires_in_seconds); + Json o = Json::object(); + o.set("name", Json(name)); + if (create_service_account_only) o.set("create_service_account_only", Json(*create_service_account_only)); + put_int(o, "expires_in_seconds", expires_in_seconds); + return o; +} + +Json ServiceAccountUpdate::to_json() const { + Json o = Json::object(); + if (!name.empty()) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + o.set("name", Json(name)); + } + if (!role.empty()) { + Validate::one_of("role", role, {"member", "owner"}); + o.set("role", Json(role)); + } + need_one(o, "service account update"); + return o; +} + +Json ServiceAccountKeyCreate::to_json() const { + Json o = Json::object(); + if (!name.empty()) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + o.set("name", Json(name)); + } + if (!scopes.empty()) { + check_scopes(scopes); + o.set("scopes", string_array(scopes)); + } + check_expiry(expires_in_seconds); + put_int(o, "expires_in_seconds", expires_in_seconds); + return o; +} + +Json ProjectApiKeyUpdate::to_json() const { + Json o = Json::object(); + check_expiry(expires_in_seconds); + put_int(o, "expires_in_seconds", expires_in_seconds); + if (scopes) { + check_scopes(*scopes); + o.set("scopes", string_array(*scopes)); + } + need_one(o, "project api key update"); + return o; +} + +Json RateLimitUpdate::to_json() const { + Json o = Json::object(); + const std::pair*> fields[] = { + {"max_requests_per_1_minute", &max_requests_per_1_minute}, + {"max_tokens_per_1_minute", &max_tokens_per_1_minute}, + {"max_images_per_1_minute", &max_images_per_1_minute}, + {"max_audio_megabytes_per_1_minute", &max_audio_megabytes_per_1_minute}, + {"max_requests_per_1_day", &max_requests_per_1_day}, + {"batch_1_day_max_input_tokens", &batch_1_day_max_input_tokens}}; + for (const auto& [name, value] : fields) { + if (!*value) continue; + Validate::range(name, **value, 0, 1000000000000LL); + o.set(name, Json(static_cast(**value))); + } + need_one(o, "rate limit update"); + return o; +} + +Json CertificateUpload::to_json() const { + Validate::text("certificate", certificate, AdminCaps::kMaxCertificatePemBytes); + if (certificate.find("-----BEGIN CERTIFICATE-----") == std::string::npos) + Validate::fail("certificate must be a PEM CERTIFICATE block"); + if (certificate.find("PRIVATE KEY") != std::string::npos) + Validate::fail("certificate contains a private key; upload the public certificate only"); + Json o = Json::object(); + o.set("certificate", Json(certificate)); + if (!name.empty()) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + o.set("name", Json(name)); + } + return o; +} + +Json SpendAlertSpec::to_json() const { + Validate::range("threshold_amount", threshold_amount, 1, 1000000000000LL); + Validate::count("recipients", recipients.size(), 10, false); + Json channel = Json::object(); + channel.set("type", Json("email")); + Json to = Json::array(); + for (const std::string& r : recipients) { + Validate::email(r); + to.push(Json(r)); + } + channel.set("recipients", to); + if (!subject_prefix.empty()) { + Validate::text("subject_prefix", subject_prefix, AdminCaps::kMaxNameChars); + channel.set("subject_prefix", Json(subject_prefix)); + } + Json o = Json::object(); + o.set("threshold_amount", Json(static_cast(threshold_amount))); + o.set("currency", Json("USD")); + o.set("interval", Json("month")); + o.set("notification_channel", channel); + return o; +} + +Json SpendLimitSpec::to_json() const { + Validate::range("threshold_amount", threshold_amount, 1, 1000000000000LL); + Json o = Json::object(); + o.set("threshold_amount", Json(static_cast(threshold_amount))); + o.set("currency", Json("USD")); + o.set("interval", Json("month")); + return o; +} + +Json RoleSpec::to_json() const { + Validate::text("role_name", role_name, AdminCaps::kMaxNameChars); + Validate::count("permissions", permissions.size(), AdminCaps::kMaxPermissions, false); + for (const std::string& p : permissions) Validate::text("permission", p, AdminCaps::kMaxNameChars); + Json o = Json::object(); + o.set("role_name", Json(role_name)); + o.set("permissions", string_array(permissions)); + if (!description.empty()) { + Validate::text("description", description, AdminCaps::kMaxDescriptionChars); + o.set("description", Json(description)); + } + return o; +} + +Json RoleUpdate::to_json() const { + Json o = Json::object(); + if (!role_name.empty()) { + Validate::text("role_name", role_name, AdminCaps::kMaxNameChars); + o.set("role_name", Json(role_name)); + } + if (permissions) { + Validate::count("permissions", permissions->size(), AdminCaps::kMaxPermissions, false); + for (const std::string& p : *permissions) Validate::text("permission", p, AdminCaps::kMaxNameChars); + o.set("permissions", string_array(*permissions)); + } + if (!description.empty()) { + Validate::text("description", description, AdminCaps::kMaxDescriptionChars); + o.set("description", Json(description)); + } + need_one(o, "role update"); + return o; +} + +Json ModelPermissions::to_json() const { + Validate::one_of("mode", mode, {"allow_list", "deny_list"}); + Validate::count("model_ids", model_ids.size(), AdminCaps::kMaxModelIds, false); + for (const std::string& m : model_ids) Validate::text("model id", m, AdminCaps::kMaxNameChars); + Json o = Json::object(); + o.set("mode", Json(mode)); + o.set("model_ids", string_array(model_ids)); + return o; +} + +const std::vector& HostedToolPermissions::tools() { + static const std::vector t = {"file_search", "web_search", "image_generation", "mcp", + "code_interpreter"}; + return t; +} + +Json HostedToolPermissions::to_json() const { + Json o = Json::object(); + for (const auto& [tool, on] : enabled) { + if (std::find(tools().begin(), tools().end(), tool) == tools().end()) + Validate::fail("unknown hosted tool " + tool); + Json e = Json::object(); + e.set("enabled", Json(on)); + o.set(tool, e); + } + need_one(o, "hosted tool permissions"); + return o; +} + +Json DataRetention::organization(const std::string& retention_type) { + Validate::one_of("retention_type", retention_type, + {"zero_data_retention", "modified_abuse_monitoring", + "enhanced_zero_data_retention", "enhanced_modified_abuse_monitoring"}); + Json o = Json::object(); + o.set("retention_type", Json(retention_type)); + return o; +} + +Json DataRetention::project(const std::string& retention_type) { + Validate::one_of("retention_type", retention_type, + {"organization_default", "none", "zero_data_retention", + "modified_abuse_monitoring", "enhanced_zero_data_retention", + "enhanced_modified_abuse_monitoring"}); + Json o = Json::object(); + o.set("retention_type", Json(retention_type)); + return o; +} + +Json ExternalStorageSpec::to_json() const { + Validate::id("project_id", project_id); + Validate::one_of("provider type", type, {"aws", "azure", "gcp", "oci"}); + static const std::map> required = { + {"aws", {"bucket", "role_arn"}}, + {"azure", {"tenant_id", "subscription_id", "resource_group", "account_name", "container"}}, + {"gcp", + {"bucket", "workload_identity_project_number", "workload_identity_pool_id", + "workload_identity_provider_id"}}, + {"oci", {"tenancy_ocid", "region", "bucket"}}}; + const auto& need = required.at(type); + for (const auto& [k, v] : provider) { + if (std::find(need.begin(), need.end(), k) == need.end()) + Validate::fail("provider " + type + " has no field " + k); + Validate::text(k, v, AdminCaps::kMaxNameChars); + } + Json p = Json::object(); + p.set("type", Json(type)); + for (const std::string& k : need) { + auto it = provider.find(k); + if (it == provider.end()) Validate::fail("provider " + type + " needs " + k); + p.set(k, Json(it->second)); + } + Json o = Json::object(); + o.set("project_id", Json(project_id)); + o.set("provider", p); + return o; +} + +Json WebhookEndpointSpec::to_json(bool for_create) const { + Json o = Json::object(); + if (for_create || !name.empty()) { + Validate::text("name", name, AdminCaps::kMaxNameChars); + o.set("name", Json(name)); + } + if (for_create || !url.empty()) { + Validate::https_url("url", url, AdminCaps::kMaxWebhookUrlChars); + o.set("url", Json(url)); + } + if (for_create || !event_types.empty()) { + Validate::count("event_types", event_types.size(), AdminCaps::kMaxEndpointEventTypes, false); + for (const std::string& t : event_types) + if (!WebhookEvents::is_subscribable(t)) Validate::fail("event type " + t + " cannot be subscribed to"); + o.set("event_types", string_array(event_types)); + } + if (!for_create) need_one(o, "webhook endpoint update"); + return o; +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/requests.h b/src/openai/admin/requests.h new file mode 100644 index 0000000..3de8f1e --- /dev/null +++ b/src/openai/admin/requests.h @@ -0,0 +1,167 @@ +#pragma once + +// Typed request bodies. Every class validates in `to_json()` (ranges and +// enums taken from the OpenAPI document, ceilings from AdminCaps) and throws +// llm::ApiError::invalid before anything is sent. Optional fields that are +// unset are left out of the body, never sent as null. + +#include +#include +#include +#include +#include + +#include "clients/body/json.h" + +namespace molo::openai::admin { + +using Json = clients::body::Json; + +// Longest expiry the API accepts for a key (1 year, spec maximum). +constexpr std::int64_t kMaxKeyExpirySeconds = 31536000; + +struct ProjectGrant { + std::string id; + std::string role; // member | owner +}; + +struct InviteRequest { + std::string email; + std::string role; // reader | owner + std::vector projects; + Json to_json() const; +}; + +struct ProjectCreate { + std::string name; + std::string residency; // PublicProjectResidency value, optional + std::string geography; // deprecated spelling, optional + std::string external_key_id; // optional + Json to_json() const; +}; + +struct ProjectUpdate { + std::string name; + std::string external_key_id; + std::string geography; + Json to_json() const; // at least one field +}; + +struct ProjectUserCreate { + std::string user_id; // exactly one of user_id / email + std::string email; + std::string role; // owner | member + Json to_json() const; +}; + +struct UserUpdate { + std::string role; // owner | reader + std::string role_id; + std::string technical_level; + std::string developer_persona; + Json to_json() const; // at least one field +}; + +struct ServiceAccountCreate { + std::string name; + std::optional create_service_account_only; + std::optional expires_in_seconds; + Json to_json() const; +}; + +struct ServiceAccountUpdate { + std::string name; + std::string role; // member | owner + Json to_json() const; // at least one field +}; + +struct ServiceAccountKeyCreate { + std::string name; + std::vector scopes; + std::optional expires_in_seconds; + Json to_json() const; +}; + +struct ProjectApiKeyUpdate { + std::optional expires_in_seconds; + std::optional> scopes; // empty vector removes the restriction + Json to_json() const; // at least one field +}; + +struct RateLimitUpdate { + std::optional max_requests_per_1_minute; + std::optional max_tokens_per_1_minute; + std::optional max_images_per_1_minute; + std::optional max_audio_megabytes_per_1_minute; + std::optional max_requests_per_1_day; + std::optional batch_1_day_max_input_tokens; + Json to_json() const; // at least one field +}; + +struct CertificateUpload { + std::string name; // optional + std::string certificate; // PEM + Json to_json() const; +}; + +// Spend alert: USD per month, threshold in cents (spec: integer, minimum 1). +struct SpendAlertSpec { + std::int64_t threshold_amount = 0; + std::vector recipients; // email channel, 1..10 + std::string subject_prefix; // optional + Json to_json() const; +}; + +struct SpendLimitSpec { + std::int64_t threshold_amount = 0; // cents, minimum 1 + Json to_json() const; +}; + +struct RoleSpec { + std::string role_name; + std::vector permissions; + std::string description; // optional + Json to_json() const; +}; + +struct RoleUpdate { + std::string role_name; + std::optional> permissions; + std::string description; + Json to_json() const; // at least one field +}; + +struct ModelPermissions { + std::string mode; // allow_list | deny_list + std::vector model_ids; + Json to_json() const; +}; + +// file_search, web_search, image_generation, mcp, code_interpreter -> enabled. +struct HostedToolPermissions { + std::map enabled; + Json to_json() const; // at least one tool + static const std::vector& tools(); +}; + +// Retention types of the spec: organization and project enums differ. +struct DataRetention { + static Json organization(const std::string& retention_type); + static Json project(const std::string& retention_type); +}; + +struct ExternalStorageSpec { + std::string project_id; + std::string type; // aws | azure | gcp | oci + std::map provider; // fields of that provider, see SPEC + Json to_json() const; +}; + +struct WebhookEndpointSpec { + std::string name; + std::string url; + std::vector event_types; + Json to_json(bool for_create) const; // update needs at least one field +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/tools/check_spec.py b/src/openai/admin/tools/check_spec.py new file mode 100644 index 0000000..778c733 --- /dev/null +++ b/src/openai/admin/tools/check_spec.py @@ -0,0 +1,272 @@ +#!/usr/bin/env python3 +"""Check src/openai/admin against OpenAI's published OpenAPI document. + +Fails (exit 1) when a declared call is absent from the spec, its HTTP method, +path, operationId, auth scheme, query parameters, request body fields, +required fields or response schema differ, when a schema field we read is +absent, when the audit event or webhook event catalogs differ, or when a spec +operation in scope (organization administration, webhook endpoints) is neither +in the call table nor in the explicit EXCLUDED list below. Python 3 stdlib +only, no credentials. + + python3 -I src/openai/admin/tools/check_spec.py # pinned revision + python3 -I src/openai/admin/tools/check_spec.py --head # newest main + python3 -I src/openai/admin/tools/check_spec.py --file x.json + +Second source: the official openai-go SDK api.md must list every table row's +HTTP method and path (cross-check, rule 2 of plan 17). +""" +import json +import os +import re +import sys +import urllib.request + +HERE = os.path.dirname(os.path.abspath(__file__)) +SRC = os.path.join(HERE, "..") +PINNED = "8243cc8fa6f04430fb1f1a6a2cb926fbeb4f7f26" +SPEC_URL = "https://raw.githubusercontent.com/openai/openai-openapi/%s/openapi.json" +GO_API = "https://raw.githubusercontent.com/openai/openai-go/main/api.md" +GO_WEBHOOKS_API = "https://raw.githubusercontent.com/openai/openai-go/main/webhooks/api.md" + +# Spec operations in scope that this package deliberately does not wrap: +# method path -> reason. Empty: every in-scope operation is wrapped. +EXCLUDED = {} + +ROW = re.compile(r'^\s*\{(.*)\},?\s*$') +STR = re.compile(r'"((?:[^"\\]|\\.)*)"') + + +def fetch(url): + req = urllib.request.Request(url, headers={"User-Agent": "molo-check-spec"}) + with urllib.request.urlopen(req, timeout=300) as r: + return r.read() + + +def block(text, begin, end): + a = text.index(begin) + b = text.index(end) + rows = [] + for line in text[a:b].splitlines()[1:]: + m = ROW.match(line) + if m and '"' in line: + rows.append(STR.findall(m.group(1))) + return rows + + +def strings_block(text, begin, end): + a = text.index(begin) + b = text.index(end) + return STR.findall(text[a:b].split("\n", 1)[1]) + + +def in_scope(path): + return path.startswith("/organization") or path.startswith("/webhook_endpoints") \ + or path == "/webhook_event_types" + + +def main(): + args = sys.argv[1:] + if "--file" in args: + raw = open(args[args.index("--file") + 1], "rb").read() + label = args[args.index("--file") + 1] + else: + sha = PINNED + if "--head" in args: + meta = json.loads(fetch("https://api.github.com/repos/openai/openai-openapi/commits/main")) + sha = meta["sha"] + raw = fetch(SPEC_URL % sha) + label = sha + spec = json.loads(raw) + schemas = spec["components"]["schemas"] + paths = spec["paths"] + + def deref(x): + while isinstance(x, dict) and "$ref" in x: + x = schemas[x["$ref"].split("/")[-1]] if x["$ref"].startswith("#/components/schemas/") \ + else resolve(x["$ref"]) + return x + + def resolve(ref): + node = spec + for part in ref.lstrip("#/").split("/"): + node = node[part] + return node + + def flat(sch): + sch = deref(sch) + props, req = dict(sch.get("properties", {})), list(sch.get("required", [])) + for a in sch.get("allOf", []): + p, r = flat(a) + props.update(p) + req += r + return props, req + + calls_src = open(os.path.join(SRC, "calls.cpp")).read() + calls = block(calls_src, "// CALLS-BEGIN", "// CALLS-END") + fields = block(calls_src, "// SCHEMAS-BEGIN", "// SCHEMAS-END") + bad = [] + default_security = spec.get("security", []) + + for key, http, path, op_id, auth, body, req, query, rschema, resp, flags in \ + [tuple(r[:11]) for r in calls]: + node = paths.get(path, {}).get(http.lower()) + if not node: + bad.append("%s: %s %s absent from the spec" % (key, http, path)) + continue + if node.get("operationId") != op_id: + bad.append("%s: operationId %s != %s" % (key, op_id, node.get("operationId"))) + sec = node.get("security", default_security) + scheme = list(sec[0].keys())[0] if sec else "" + want = "AdminApiKeyAuth" if auth == "admin" else "ApiKeyAuth" + if scheme != want: + bad.append("%s: auth %s but the spec says %s" % (key, auth, scheme)) + if auth == "project" and "AdminApiKeyAuth" in json.dumps(sec): + bad.append("%s: project call declared with admin security" % key) + spec_query = [] + for prm in node.get("parameters", []): + prm = deref(prm) + if prm["in"] == "query": + spec_query.append(prm["name"]) + mine = [q for q in query.split(",") if q] + for q in mine: + if q not in spec_query: + bad.append("%s: query parameter %s absent" % (key, q)) + for q in spec_query: + if q not in mine: + bad.append("%s: spec query parameter %s not in the table" % (key, q)) + want_path_params = re.findall(r"\{([^}]+)\}", path) + spec_path_params = [deref(p)["name"] for p in node.get("parameters", []) if deref(p)["in"] == "path"] + if sorted(want_path_params) != sorted(spec_path_params): + bad.append("%s: path parameters %s != %s" % (key, want_path_params, spec_path_params)) + rb = node.get("requestBody") + if rb: + sch = rb["content"]["application/json"]["schema"] + ref = sch["$ref"].split("/")[-1] if "$ref" in sch else "" + if ref != rschema: + bad.append("%s: request schema %r != %r" % (key, rschema, ref)) + props, reqd = flat(sch) + for f in [f for f in body.split(",") if f]: + if f not in props: + bad.append("%s: body field %s absent" % (key, f)) + for f in props: + if f not in body.split(","): + bad.append("%s: spec body field %s not in the table" % (key, f)) + if sorted(set(reqd)) != sorted(f for f in req.split(",") if f): + bad.append("%s: required %s != %s" % (key, sorted(set(reqd)), req)) + elif body or req or rschema: + bad.append("%s: table has a body but the spec has none" % key) + ok = node["responses"].get("200") or node["responses"].get("201") + content = deref(ok).get("content", {}).get("application/json") if ok else None + got = content["schema"]["$ref"].split("/")[-1] if content and "$ref" in content["schema"] else "" + if got != resp: + bad.append("%s: response schema %r != %r" % (key, resp, got)) + if (http == "DELETE") != (flags == "destructive") and key not in ( + "projects.archive", "certificates.deactivate", "projects.certificates.deactivate", + "data_retention.update", "projects.data_retention.update", + "webhook_endpoints.rotate_secret"): + bad.append("%s: destructive flag disagrees with the HTTP method" % key) + + for name, flds in fields: + sch = schemas.get(name) + if sch is None: + bad.append("missing schema %s" % name) + continue + props, _ = flat(sch) + for f in flds.split(","): + if f not in props: + bad.append("schema %s.%s absent" % (name, f)) + + declared = {(r[1], r[2]) for r in calls} + in_scope_ops = 0 + for path, item in paths.items(): + if not in_scope(path): + continue + for method in ("get", "post", "put", "patch", "delete"): + if method in item: + in_scope_ops += 1 + k = (method.upper(), path) + if k not in declared and ("%s %s" % k) not in EXCLUDED: + bad.append("unwrapped spec operation %s %s" % k) + for ex in EXCLUDED: + m, p = ex.split(" ", 1) + if (m, p) in declared: + bad.append("excluded operation %s is also in the table" % ex) + + # Audit event type catalog. + audit_src = open(os.path.join(SRC, "audit_events.cpp")).read() + mine = strings_block(audit_src, "// AUDIT-EVENTS-BEGIN", "// AUDIT-EVENTS-END") + theirs = schemas["AuditLogEventType"]["enum"] + if mine != theirs: + bad.append("audit event catalog differs: missing %s extra %s" % ( + [e for e in theirs if e not in mine], [e for e in mine if e not in theirs])) + + # Webhook catalogs. + wh_src = open(os.path.join(SRC, "webhook_events.cpp")).read() + sent = strings_block(wh_src, "// WEBHOOK-EVENTS-BEGIN", "// WEBHOOK-EVENTS-END") + spec_sent = [] + for name, item in spec.get("webhooks", {}).items(): + sch = item["post"]["requestBody"]["content"]["application/json"]["schema"] + props, _ = flat(sch) + enum = deref(props["type"]).get("enum") + spec_sent += enum or [] + if sorted(sent) != sorted(spec_sent): + bad.append("webhook event types differ: missing %s extra %s" % ( + sorted(set(spec_sent) - set(sent)), sorted(set(sent) - set(spec_sent)))) + sub = strings_block(wh_src, "// SUBSCRIBABLE-BEGIN", "// SUBSCRIBABLE-END") + if sub != schemas["ProjectEventTypeEnum"]["enum"]: + bad.append("subscribable webhook event types differ from ProjectEventTypeEnum") + usage_src = open(os.path.join(SRC, "usage.cpp")).read() + ub = usage_src[usage_src.index("// USAGE-ENDPOINTS-BEGIN"):usage_src.index("// USAGE-ENDPOINTS-END")] + for name, gb in re.findall(r'"(\w+)", Call::\w+,\s*"([^"]*)"\}', ub): + node = paths["/organization/usage/" + name]["get"] + enum = [] + for prm in node["parameters"]: + prm = deref(prm) + if prm["name"] == "group_by": + it = deref(prm["schema"]).get("items") + enum = deref(it).get("enum", []) if it else [] + if enum != [g for g in gb.split(",") if g]: + bad.append("usage %s group_by %s != spec %s" % (name, gb, enum)) + spec_res = [n for n in schemas if n.startswith("Usage") and n.endswith("Result")] + ["CostsResult"] + for n in spec_res: + if n not in [f[0] for f in fields]: + bad.append("usage result schema %s is not in the SCHEMAS table" % n) + evb = wh_src[wh_src.index("// EVENT-SPECS"):wh_src.index("// WEBHOOK-EVENTS-BEGIN")] + rows_ev = re.findall(r'\{"([^"]+)", "([^"]+)", "([^"]*)", "([^"]*)"\}', evb) + for t, key, flds, rq in rows_ev: + item = spec["webhooks"].get(key) + if not item: + bad.append("webhook %s absent" % key) + continue + props, _ = flat(item["post"]["requestBody"]["content"]["application/json"]["schema"]) + dp, dr = flat(props["data"]) + if sorted(dp) != sorted(flds.split(",")) or sorted(set(dr)) != sorted(x for x in rq.split(",") if x): + bad.append("webhook %s data fields differ" % t) + + # Second source: openai-go api.md lists every method and path. + sdk = fetch(GO_API).decode() + fetch(GO_WEBHOOKS_API).decode() + listed = set(re.findall(r'title="(get|post|delete) (/[^"]+)"', sdk)) + miss = 0 + for r in calls: + http, path = r[1].lower(), r[2] + sdk_path = path[1:] if (http, path[1:]) in listed else path + if (http, sdk_path) not in listed and (http, path.lstrip("/")) not in listed: + miss += 1 + bad.append("openai-go api.md does not list %s %s" % (http.upper(), path)) + + if bad: + print("SPEC CHECK FAILED (%s)" % label) + for b in bad: + print(" " + b) + return 1 + print("spec ok: %d calls, %d schemas, %d in-scope spec operations covered, " + "%d audit event types, %d sent webhook event types, openai-go lists all %d rows, " + "openapi %s revision %s, info.version %s" + % (len(calls), len(fields), in_scope_ops, len(theirs), len(spec_sent), len(calls) - miss, + "openapi.json", label, spec["info"]["version"])) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/openai/admin/tools/probe_paths.py b/src/openai/admin/tools/probe_paths.py new file mode 100644 index 0000000..64f08fa --- /dev/null +++ b/src/openai/admin/tools/probe_paths.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +"""Unauthenticated probe: every GET row of calls.cpp must answer 401 (path +exists, auth required) and a made-up sibling must answer 404. Sends an +obviously invalid key, never a real credential. Python 3 stdlib only. + + python3 -I src/openai/admin/tools/probe_paths.py +""" +import os +import re +import sys +import urllib.error +import urllib.request + +HERE = os.path.dirname(os.path.abspath(__file__)) +BASE = "https://api.openai.com/v1" + + +def status(path): + req = urllib.request.Request(BASE + path, headers={"Authorization": "Bearer sk-admin-invalid"}) + try: + with urllib.request.urlopen(req, timeout=30) as r: + return r.status + except urllib.error.HTTPError as e: + return e.code + + +def main(): + src = open(os.path.join(HERE, "..", "calls.cpp")).read() + src = src[src.index("// CALLS-BEGIN"):src.index("// CALLS-END")] + rows = [re.findall(r'"([^"]*)"', l) for l in src.splitlines() if l.strip().startswith("{Call::")] + bad, n = [], 0 + for r in rows: + if r[1] != "GET": + continue + n += 1 + path = re.sub(r"\{[^}]+\}", "probe_id", r[2]) + code = status(path) + if code != 401: + bad.append("%s -> %s (want 401)" % (path, code)) + code = status("/organization/nonexistent_probe_path") + if code != 404: + bad.append("made-up path -> %s (want 404)" % code) + if bad: + print("PROBE FAILED") + for b in bad: + print(" " + b) + return 1 + print("probe ok: %d GET paths answered 401, made-up path answered 404" % n) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/openai/admin/usage.cpp b/src/openai/admin/usage.cpp new file mode 100644 index 0000000..aee1e97 --- /dev/null +++ b/src/openai/admin/usage.cpp @@ -0,0 +1,219 @@ +#include "openai/admin/usage.h" + +#include + +#include "llm/error.h" +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +namespace { + +struct Endpoint { + UsageKind kind; + const char* name; + Call call; + const char* group_by; // comma list from the spec; "" = unconstrained +}; + +// USAGE-ENDPOINTS-BEGIN (name, group_by enum; checked by tools/check_spec.py) +const Endpoint kEndpoints[] = { + {UsageKind::kCompletions, "completions", Call::kUsageCompletions, + "project_id,user_id,api_key_id,model,batch,service_tier,api_source"}, + {UsageKind::kEmbeddings, "embeddings", Call::kUsageEmbeddings, + "project_id,user_id,api_key_id,model"}, + {UsageKind::kModerations, "moderations", Call::kUsageModerations, + "project_id,user_id,api_key_id,model"}, + {UsageKind::kImages, "images", Call::kUsageImages, + "project_id,user_id,api_key_id,model,size,source"}, + {UsageKind::kAudioSpeeches, "audio_speeches", Call::kUsageAudioSpeeches, + "project_id,user_id,api_key_id,model"}, + {UsageKind::kAudioTranscriptions, "audio_transcriptions", Call::kUsageAudioTranscriptions, + "project_id,user_id,api_key_id,model"}, + {UsageKind::kVectorStores, "vector_stores", Call::kUsageVectorStores, "project_id"}, + {UsageKind::kCodeInterpreterSessions, "code_interpreter_sessions", + Call::kUsageCodeInterpreterSessions, "project_id"}, + {UsageKind::kFileSearchCalls, "file_search_calls", Call::kUsageFileSearchCalls, + "project_id,user_id,api_key_id,vector_store_id"}, + {UsageKind::kWebSearchCalls, "web_search_calls", Call::kUsageWebSearchCalls, + "project_id,user_id,api_key_id,model,context_level,api_source"}, + {UsageKind::kDecisions, "decisions", Call::kUsageDecisions, ""}, +}; +// USAGE-ENDPOINTS-END + +const Endpoint& endpoint(UsageKind kind) { + for (const Endpoint& e : kEndpoints) + if (e.kind == kind) return e; + Validate::fail("unknown usage endpoint"); +} + +int max_buckets(const std::string& width) { + if (width == "1m") return AdminCaps::kMaxBuckets1m; + if (width == "1h") return AdminCaps::kMaxBuckets1h; + return AdminCaps::kMaxBuckets1d; +} + +void common(Query& q, std::int64_t start, const std::optional& end, + const std::string& page) { + Validate::epoch("start_time", start); + q.set_int("start_time", start); + if (end) { + Validate::epoch("end_time", *end); + if (*end <= start) Validate::fail("end_time must be after start_time"); + q.set_int("end_time", *end); + } + if (!page.empty()) q.set("page", page); +} + +void group_by_check(const std::vector& values, const std::vector& allowed) { + Validate::count("group_by", values.size(), AdminCaps::kMaxGroupBy, true); + for (const std::string& g : values) { + Validate::text("group_by", g, 64); + if (!allowed.empty() && std::find(allowed.begin(), allowed.end(), g) == allowed.end()) + Validate::fail("group_by " + g + " is not allowed here"); + } +} + +void filter(Query& q, Call call, const char* name, const std::vector& values) { + if (values.empty()) return; + if (!CallTable::allows_query(call, name)) + Validate::fail(std::string(name) + " is not a filter of " + CallTable::spec(call).key); + q.add_all(name, values); +} + +} // namespace + +const std::vector& UsageEndpoints::all() { + static const std::vector kinds = [] { + std::vector v; + for (const Endpoint& e : kEndpoints) v.push_back(e.kind); + return v; + }(); + return kinds; +} + +Call UsageEndpoints::call(UsageKind kind) { return endpoint(kind).call; } +std::string UsageEndpoints::name(UsageKind kind) { return endpoint(kind).name; } + +std::optional UsageEndpoints::parse(const std::string& name) { + for (const Endpoint& e : kEndpoints) + if (name == e.name) return e.kind; + return std::nullopt; +} + +std::vector UsageEndpoints::group_by(UsageKind kind) { + return CallTable::split(endpoint(kind).group_by); +} + +Query UsageQuery::to_query(UsageKind kind) const { + const Call call = UsageEndpoints::call(kind); + Query q; + common(q, start_time, end_time, page); + if (!bucket_width.empty()) { + Validate::one_of("bucket_width", bucket_width, {"1m", "1h", "1d"}); + q.set("bucket_width", bucket_width); + } + if (limit) { + Validate::range("limit", *limit, 1, max_buckets(bucket_width)); + q.set_int("limit", *limit); + } + filter(q, call, "project_ids", project_ids); + filter(q, call, "user_ids", user_ids); + filter(q, call, "api_key_ids", api_key_ids); + filter(q, call, "models", models); + if (batch) { + if (!CallTable::allows_query(call, "batch")) Validate::fail("batch is not a filter here"); + q.set_bool("batch", *batch); + } + group_by_check(group_by, UsageEndpoints::group_by(kind)); + filter(q, call, "group_by", group_by); + for (const std::string& s : sources) + Validate::one_of("source", s, {"image.generation", "image.edit", "image.variation"}); + for (const std::string& s : sizes) + Validate::one_of("size", s, {"256x256", "512x512", "1024x1024", "1792x1792", "1024x1792"}); + filter(q, call, "sources", sources); + filter(q, call, "sizes", sizes); + filter(q, call, "vector_store_ids", vector_store_ids); + filter(q, call, "context_levels", context_levels); + return q; +} + +Query CostQuery::to_query() const { + Query q; + common(q, start_time, end_time, page); + if (!bucket_width.empty()) { + Validate::one_of("bucket_width", bucket_width, {"1d"}); + q.set("bucket_width", bucket_width); + } + if (limit) { + Validate::range("limit", *limit, 1, AdminCaps::kMaxCostBuckets); + q.set_int("limit", *limit); + } + filter(q, Call::kCosts, "project_ids", project_ids); + filter(q, Call::kCosts, "api_key_ids", api_key_ids); + filter(q, Call::kCosts, "line_items", line_items); + group_by_check(group_by, {"project_id", "user_id", "line_item", "api_key_id", "api_source"}); + filter(q, Call::kCosts, "group_by", group_by); + return q; +} + +AdminService::Json Usage::query(UsageKind kind, const UsageQuery& query) { + return execute(UsageEndpoints::call(kind), {}, query.to_query(kind)); +} + +WalkResult Usage::walk(UsageKind kind, const UsageQuery& query) { + UsageQuery first = query; + first.page.clear(); + return AdminService::walk(UsageEndpoints::call(kind), {}, first.to_query(kind), "page", query.page); +} + +AdminService::Json Costs::query(const CostQuery& query) { + return execute(Call::kCosts, {}, query.to_query()); +} + +WalkResult Costs::walk(const CostQuery& query) { + CostQuery first = query; + first.page.clear(); + return AdminService::walk(Call::kCosts, {}, first.to_query(), "page", query.page); +} + +const clients::body::Json::Array& UsageSummary::buckets_of(const clients::body::Json& doc) { + static const clients::body::Json::Array none; + if (doc.is_array()) return doc.as_array(); + const clients::body::Json* data = doc.is_object() ? doc.find("data") : nullptr; + return data && data->is_array() ? data->as_array() : none; +} + +std::map UsageSummary::totals(const clients::body::Json& buckets) { + std::map sum; + for (const auto& bucket : buckets_of(buckets)) { + const auto* results = bucket.is_object() ? bucket.find("results") : nullptr; + if (!results || !results->is_array()) continue; + for (const auto& r : results->as_array()) { + if (!r.is_object()) continue; + for (const auto& [name, value] : r.as_object()) + if (value.is_number()) sum[name] += value.as_number(); + } + } + return sum; +} + +std::map UsageSummary::cost_by_currency(const clients::body::Json& buckets) { + std::map sum; + for (const auto& bucket : buckets_of(buckets)) { + const auto* results = bucket.is_object() ? bucket.find("results") : nullptr; + if (!results || !results->is_array()) continue; + for (const auto& r : results->as_array()) { + const auto* amount = r.is_object() ? r.find("amount") : nullptr; + if (!amount || !amount->is_object()) continue; + const auto* value = amount->find("value"); + const auto* currency = amount->find("currency"); + if (value && value->is_number()) + sum[currency && currency->is_string() ? currency->as_string() : "unknown"] += value->as_number(); + } + } + return sum; +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/usage.h b/src/openai/admin/usage.h new file mode 100644 index 0000000..60f2881 --- /dev/null +++ b/src/openai/admin/usage.h @@ -0,0 +1,86 @@ +#pragma once + +// Usage and cost reports. One method per endpoint family, bucketed time +// series (bucket_width 1m / 1h / 1d, costs 1d only), group_by, filters and +// page-token paging ({object:"page", next_page}). A UsageQuery that sets a +// filter the endpoint does not have (for example `sizes` on completions) is +// rejected before any request. + +#include +#include +#include +#include + +#include "openai/admin/admin_service.h" + +namespace molo::openai::admin { + +enum class UsageKind { + kCompletions, kEmbeddings, kModerations, kImages, kAudioSpeeches, kAudioTranscriptions, + kVectorStores, kCodeInterpreterSessions, kFileSearchCalls, kWebSearchCalls, kDecisions +}; + +class UsageEndpoints { + public: + static const std::vector& all(); + static Call call(UsageKind kind); + static std::string name(UsageKind kind); // "completions", "audio_speeches", ... + static std::optional parse(const std::string& name); + // group_by values the spec lists for the endpoint; empty = unconstrained. + static std::vector group_by(UsageKind kind); +}; + +struct UsageQuery { + std::int64_t start_time = 0; // required, unix seconds, inclusive + std::optional end_time; // exclusive + std::string bucket_width; // 1m | 1h | 1d ("" = 1d) + std::optional limit; // buckets; max depends on bucket_width + std::string page; // next_page token of the previous answer + std::vector project_ids, user_ids, api_key_ids, models; + std::optional batch; // completions and decisions + std::vector group_by; + std::vector sources, sizes; // images + std::vector vector_store_ids; // file search + std::vector context_levels; // web search + + Query to_query(UsageKind kind) const; +}; + +struct CostQuery { + std::int64_t start_time = 0; + std::optional end_time; + std::string bucket_width; // "1d" only + std::optional limit; // 1..180 + std::string page; + std::vector project_ids, api_key_ids, line_items, group_by; + + Query to_query() const; +}; + +class Usage : public AdminService { + public: + explicit Usage(std::shared_ptr client) : AdminService(std::move(client)) {} + Json query(UsageKind kind, const UsageQuery& query); + // Follows next_page up to the page / item ceilings; truncation is reported. + WalkResult walk(UsageKind kind, const UsageQuery& query); +}; + +class Costs : public AdminService { + public: + explicit Costs(std::shared_ptr client) : AdminService(std::move(client)) {} + Json query(const CostQuery& query); + WalkResult walk(const CostQuery& query); +}; + +// Totals over the buckets of one answer (or of a WalkResult::items array). +class UsageSummary { + public: + // Sum of every numeric field of every result ("input_tokens", "images", ...). + static std::map totals(const clients::body::Json& buckets); + // Sum of amount.value per currency over cost results. + static std::map cost_by_currency(const clients::body::Json& buckets); + // The bucket array of an answer ({data:[...]}) or the array itself. + static const clients::body::Json::Array& buckets_of(const clients::body::Json& doc); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/validate.cpp b/src/openai/admin/validate.cpp new file mode 100644 index 0000000..ed360f8 --- /dev/null +++ b/src/openai/admin/validate.cpp @@ -0,0 +1,69 @@ +#include "openai/admin/validate.h" + +#include "llm/api_client.h" +#include "llm/error.h" +#include "openai/admin/caps.h" + +namespace molo::openai::admin { + +void Validate::fail(const std::string& message) { + throw llm::ApiError::invalid("openai", message); +} + +void Validate::text(const std::string& what, const std::string& value, std::size_t max, + bool allow_empty) { + if (value.empty() && !allow_empty) fail(what + " is required"); + if (value.size() > max) fail(what + " is over " + std::to_string(max) + " chars"); + for (unsigned char c : value) + if (c < 0x20 || c == 0x7f) fail(what + " has a control character"); +} + +void Validate::id(const std::string& what, const std::string& value) { + if (!llm::Service::valid_id(value)) fail("bad " + what); +} + +void Validate::one_of(const std::string& what, const std::string& value, + std::initializer_list allowed) { + std::string list; + for (const char* a : allowed) { + if (value == a) return; + list += (list.empty() ? "" : ", ") + std::string(a); + } + fail(what + " must be one of: " + list); +} + +void Validate::email(const std::string& value) { + text("email", value, AdminCaps::kMaxEmailChars); + const std::size_t at = value.find('@'); + if (at == std::string::npos || at == 0 || at + 1 >= value.size() || + value.find('@', at + 1) != std::string::npos || value.find(' ') != std::string::npos || + value.find('.', at) == std::string::npos) + fail("email is not an address"); +} + +void Validate::range(const std::string& what, std::int64_t value, std::int64_t lo, + std::int64_t hi) { + if (value < lo || value > hi) + fail(what + " must be " + std::to_string(lo) + ".." + std::to_string(hi)); +} + +void Validate::count(const std::string& what, std::size_t n, std::size_t max, bool allow_empty) { + if (n == 0 && !allow_empty) fail(what + " needs at least one entry"); + if (n > max) fail(what + " has more than " + std::to_string(max) + " entries"); +} + +void Validate::epoch(const std::string& what, std::int64_t value) { + range(what, value, 1, AdminCaps::kMaxTimeSeconds); +} + +void Validate::https_url(const std::string& what, const std::string& value, std::size_t max) { + text(what, value, max); + if (value.rfind("https://", 0) != 0 || value.size() < 12 || value.find(' ') != std::string::npos) + fail(what + " must be an https:// URL"); +} + +void Validate::confirmed(const std::string& action, bool confirm) { + if (!confirm) fail(action + " is destructive: pass confirm=true to run it"); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/validate.h b/src/openai/admin/validate.h new file mode 100644 index 0000000..383c2a8 --- /dev/null +++ b/src/openai/admin/validate.h @@ -0,0 +1,36 @@ +#pragma once + +// Input validation shared by every request class and service. Every failure +// is an llm::ApiError::invalid (HTTP 400 INVALID_ARGUMENT, vendor "openai") +// raised before any network traffic. + +#include +#include +#include +#include + +namespace molo::openai::admin { + +class Validate { + public: + [[noreturn]] static void fail(const std::string& message); + + // 1..max chars (0 allowed when allow_empty), no control characters. + static void text(const std::string& what, const std::string& value, std::size_t max, + bool allow_empty = false); + // One URL path segment accepted by llm::Service::valid_id. + static void id(const std::string& what, const std::string& value); + static void one_of(const std::string& what, const std::string& value, + std::initializer_list allowed); + static void email(const std::string& value); + static void range(const std::string& what, std::int64_t value, std::int64_t lo, + std::int64_t hi); + static void count(const std::string& what, std::size_t n, std::size_t max, bool allow_empty); + // Unix seconds in (0, kMaxTimeSeconds]. + static void epoch(const std::string& what, std::int64_t value); + static void https_url(const std::string& what, const std::string& value, std::size_t max); + // Destructive calls need an explicit true; there is no default anywhere. + static void confirmed(const std::string& action, bool confirm); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/webhook_events.cpp b/src/openai/admin/webhook_events.cpp new file mode 100644 index 0000000..dd4c31c --- /dev/null +++ b/src/openai/admin/webhook_events.cpp @@ -0,0 +1,205 @@ +#include "openai/admin/webhook_events.h" + +#include +#include + +#include "llm/error.h" +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" + +namespace molo::openai::admin { + +using clients::body::Json; + +// EVENT-SPECS (payload description per event; `webhooks` map of the OpenAPI document) +static const WebhookEventSpec kEvents[] = { + {"agent.environment.expired", "agent_environment_expired", "id", "id"}, + {"agent.environment.failed", "agent_environment_failed", "id", "id"}, + {"agent.environment.ready", "agent_environment_ready", "id", "id"}, + {"agent.environment.suspended", "agent_environment_suspended", "id", "id"}, + {"agent.session.action_required", "agent_session_action_required", "id,required_action", "id,required_action"}, + {"agent.session.created", "agent_session_created", "id,environment_id,environment_type,connect", "id,environment_type"}, + {"agent.session.failed", "agent_session_failed", "id,environment_id,environment_type", "id,environment_type"}, + {"agent.session.idle", "agent_session_idle", "id,environment_id,environment_type", "id,environment_type"}, + {"agent.session.in_progress", "agent_session_in_progress", "id,environment_id,environment_type", "id,environment_type"}, + {"batch.cancelled", "batch_cancelled", "id", "id"}, + {"batch.completed", "batch_completed", "id", "id"}, + {"batch.expired", "batch_expired", "id", "id"}, + {"batch.failed", "batch_failed", "id", "id"}, + {"eval.run.canceled", "eval_run_canceled", "id", "id"}, + {"eval.run.failed", "eval_run_failed", "id", "id"}, + {"eval.run.succeeded", "eval_run_succeeded", "id", "id"}, + {"fine_tuning.job.cancelled", "fine_tuning_job_cancelled", "id", "id"}, + {"fine_tuning.job.failed", "fine_tuning_job_failed", "id", "id"}, + {"fine_tuning.job.succeeded", "fine_tuning_job_succeeded", "id", "id"}, + {"live.call.incoming", "live_call_incoming", "session_id,sip_media_security,sip_headers", "session_id,sip_headers"}, + {"live.transport.incoming", "live_transport_incoming", "type,session_id,sip_media_security,sip_headers", "type,session_id,sip_headers"}, + {"realtime.call.incoming", "realtime_call_incoming", "call_id,sip_media_security,sip_headers", "call_id,sip_headers"}, + {"response.cancelled", "response_cancelled", "id", "id"}, + {"response.completed", "response_completed", "id", "id"}, + {"response.failed", "response_failed", "id", "id"}, + {"response.incomplete", "response_incomplete", "id", "id"}, + {"safety.alert.created", "safety_alert_created", "id", "id"}, + {"safety.deactivation_issued", "safety_deactivation_issued", "id", "id"}, + {"safety.org_alert.created", "safety_org_alert_created", "id", "id"}, + {"safety.warning_issued", "safety_warning_issued", "id", "id"}, +}; + +// WEBHOOK-EVENTS-BEGIN (types of kEvents; checked by tools/check_spec.py) +static const char* const kSent[] = { + "agent.environment.expired", + "agent.environment.failed", + "agent.environment.ready", + "agent.environment.suspended", + "agent.session.action_required", + "agent.session.created", + "agent.session.failed", + "agent.session.idle", + "agent.session.in_progress", + "batch.cancelled", + "batch.completed", + "batch.expired", + "batch.failed", + "eval.run.canceled", + "eval.run.failed", + "eval.run.succeeded", + "fine_tuning.job.cancelled", + "fine_tuning.job.failed", + "fine_tuning.job.succeeded", + "live.call.incoming", + "live.transport.incoming", + "realtime.call.incoming", + "response.cancelled", + "response.completed", + "response.failed", + "response.incomplete", + "safety.alert.created", + "safety.deactivation_issued", + "safety.org_alert.created", + "safety.warning_issued", +}; +// WEBHOOK-EVENTS-END + +// SUBSCRIBABLE-BEGIN (ProjectEventTypeEnum; checked by tools/check_spec.py) +static const char* const kSubscribable[] = { + "batch.completed", + "batch.failed", + "batch.expired", + "batch.cancelled", + "response.completed", + "response.failed", + "response.cancelled", + "response.incomplete", + "eval.run.succeeded", + "eval.run.failed", + "eval.run.canceled", + "fine_tuning.job.succeeded", + "fine_tuning.job.failed", + "fine_tuning.job.cancelled", + "realtime.call.incoming", + "video.completed", + "video.failed", + "agent.environment.ready", + "agent.environment.failed", + "agent.environment.suspended", + "agent.environment.expired", + "agent.session.created", + "agent.session.action_required", + "agent.session.in_progress", + "agent.session.idle", + "agent.session.failed", + "safety.alert.created", +}; +// SUBSCRIBABLE-END + +std::size_t WebhookEvents::count() { return sizeof(kEvents) / sizeof(kEvents[0]); } + +const WebhookEventSpec& WebhookEvents::at(std::size_t index) { + if (index >= count()) Validate::fail("webhook event index out of range"); + return kEvents[index]; +} + +const WebhookEventSpec* WebhookEvents::find(const std::string& type) { + for (const WebhookEventSpec& e : kEvents) + if (type == e.type) return &e; + return nullptr; +} + +const std::vector& WebhookEvents::sent() { + static const std::vector v(std::begin(kSent), std::end(kSent)); + return v; +} + +const std::vector& WebhookEvents::subscribable() { + static const std::vector v(std::begin(kSubscribable), std::end(kSubscribable)); + return v; +} + +bool WebhookEvents::is_subscribable(const std::string& type) { + const auto& v = subscribable(); + return std::find(v.begin(), v.end(), type) != v.end(); +} + +std::string WebhookEvent::family() const { return type.substr(0, type.find('.')); } + +std::string WebhookEvent::resource_id() const { + const Json* id_field = data.is_object() ? data.find("id") : nullptr; + return id_field && id_field->is_string() ? id_field->as_string() : ""; +} + +Json WebhookEvent::to_json() const { + Json o = Json::object(); + o.set("id", Json(id)); + o.set("type", Json(type)); + o.set("created_at", Json(static_cast(created_at))); + o.set("family", Json(family())); + o.set("resource_id", Json(resource_id())); + o.set("known", Json(known)); + Json missing = Json::array(); + for (const std::string& m : missing_data_fields) missing.push(Json(m)); + o.set("missing_data_fields", missing); + o.set("data", data); + return o; +} + +WebhookEvent WebhookEnvelope::parse(const std::string& body) { + if (body.size() > AdminCaps::kMaxWebhookBodyBytes) Validate::fail("webhook body over the cap"); + Json doc; + try { + doc = Json::parse(body); + } catch (const std::exception&) { + Validate::fail("webhook body is not JSON"); + } + if (!doc.is_object()) Validate::fail("webhook body is not an object"); + WebhookEvent ev; + const Json* id_f = doc.find("id"); + const Json* type_f = doc.find("type"); + const Json* created = doc.find("created_at"); + const Json* data = doc.find("data"); + const Json* object = doc.find("object"); + if (!id_f || !id_f->is_string() || id_f->as_string().empty()) Validate::fail("event has no id"); + if (!type_f || !type_f->is_string() || type_f->as_string().empty()) Validate::fail("event has no type"); + if (!created || !created->is_number()) Validate::fail("event has no created_at"); + if (!data || !data->is_object()) Validate::fail("event has no data object"); + if (object && (!object->is_string() || object->as_string() != "event")) + Validate::fail("event object is not \"event\""); + ev.id = id_f->as_string(); + ev.type = type_f->as_string(); + ev.created_at = static_cast(created->as_int()); + ev.data = *data; + if (const WebhookEventSpec* spec = WebhookEvents::find(ev.type)) { + ev.known = true; + std::string list = spec->required_data; + std::size_t from = 0; + while (from < list.size()) { + std::size_t comma = list.find(',', from); + std::string field = list.substr(from, comma == std::string::npos ? std::string::npos : comma - from); + if (!field.empty() && !data->find(field)) ev.missing_data_fields.push_back(field); + if (comma == std::string::npos) break; + from = comma + 1; + } + } + return ev; +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/webhook_events.h b/src/openai/admin/webhook_events.h new file mode 100644 index 0000000..671dbc2 --- /dev/null +++ b/src/openai/admin/webhook_events.h @@ -0,0 +1,64 @@ +#pragma once + +// Webhook event catalog and envelope. +// +// OpenAI delivers `{id, object:"event", created_at, type, data}` to the +// endpoint URL. `WebhookEvents::sent()` lists every event type the OpenAPI +// document declares a payload for (its top-level `webhooks` map); +// `subscribable()` lists the types an endpoint may subscribe to +// (`ProjectEventTypeEnum`, used by the webhook endpoint calls). The two sets +// differ: the spec has payloads for events it does not let endpoints select +// and selectable events with no declared payload (video.*). + +#include +#include +#include +#include + +#include "clients/body/json.h" + +namespace molo::openai::admin { + +struct WebhookEventSpec { + const char* type; // "response.completed" + const char* spec_name; // key in the spec's `webhooks` map + const char* data_fields; // comma list: properties of `data` + const char* required_data; // comma list: required properties of `data` +}; + +class WebhookEvents { + public: + static std::size_t count(); + static const WebhookEventSpec& at(std::size_t index); + static const WebhookEventSpec* find(const std::string& type); + static const std::vector& sent(); + static const std::vector& subscribable(); + static bool is_subscribable(const std::string& type); +}; + +// A parsed delivery body. `known` is false for a type this build has no +// payload description for (accepted, flagged; never an error: OpenAI adds +// event types over time). +struct WebhookEvent { + std::string id; + std::string type; + std::int64_t created_at = 0; + clients::body::Json data; + bool known = false; + std::vector missing_data_fields; // required data fields absent + + // "response.completed" -> "response" + std::string family() const; + // `data.id` when present (resource id the event is about), else "". + std::string resource_id() const; + clients::body::Json to_json() const; +}; + +class WebhookEnvelope { + public: + // Throws ApiError::invalid unless the body is an event object with id, + // type, integer created_at and an object `data`. Body capped. + static WebhookEvent parse(const std::string& body); +}; + +} // namespace molo::openai::admin diff --git a/src/openai/admin/webhooks.cpp b/src/openai/admin/webhooks.cpp new file mode 100644 index 0000000..8f13277 --- /dev/null +++ b/src/openai/admin/webhooks.cpp @@ -0,0 +1,243 @@ +#include "openai/admin/webhooks.h" + +#include +#include +#include + +#include "llm/error.h" +#include "openai/admin/caps.h" +#include "openai/admin/validate.h" +#include "security/crypto/Base64.h" +#include "security/crypto/Hmac.h" +#include "security/crypto/SecureRandom.h" + +namespace molo::openai::admin { + +namespace crypto = security::crypto; + +namespace { + +constexpr std::size_t kFailureCount = 11; +std::array, kFailureCount> g_failures{}; +std::atomic g_accepted{0}; + +std::string lower(std::string s) { + std::transform(s.begin(), s.end(), s.begin(), [](unsigned char c) { return std::tolower(c); }); + return s; +} + +[[noreturn]] void bad_secret(const std::string& why) { + Validate::fail("webhook secret unusable: " + why); +} + +std::string decode_secret(const std::string& secret) { + if (secret.empty() || secret.size() > AdminCaps::kMaxSecretChars) bad_secret("empty or too long"); + static const std::string kPrefix = "whsec_"; + if (secret.rfind(kPrefix, 0) != 0) return secret; // raw key bytes, as the SDKs allow + const std::string encoded = secret.substr(kPrefix.size()); + std::string decoded; + if (!crypto::Base64::decode(encoded, decoded)) bad_secret("not valid base64"); + if (crypto::Base64::encode(decoded) != encoded) bad_secret("base64 is not canonical"); + if (decoded.size() < AdminCaps::kMinSecretBytes) bad_secret("decoded key is under 24 bytes"); + return decoded; +} + +} // namespace + +const char* webhook_failure_name(WebhookFailure f) { + switch (f) { + case WebhookFailure::kNone: return "none"; + case WebhookFailure::kBadSecret: return "bad_secret"; + case WebhookFailure::kBodyTooLarge: return "body_too_large"; + case WebhookFailure::kMissingId: return "missing_webhook_id"; + case WebhookFailure::kMissingTimestamp: return "missing_webhook_timestamp"; + case WebhookFailure::kMissingSignature: return "missing_webhook_signature"; + case WebhookFailure::kBadTimestamp: return "bad_timestamp"; + case WebhookFailure::kTooOld: return "timestamp_too_old"; + case WebhookFailure::kTooNew: return "timestamp_too_new"; + case WebhookFailure::kBadSignatureHeader: return "bad_signature_header"; + case WebhookFailure::kMismatch: return "signature_mismatch"; + } + return "unknown"; +} + +WebhookHeaders WebhookHeaders::from(const std::map& headers) { + WebhookHeaders out; + for (const auto& [name, value] : headers) { + const std::string n = lower(name); + if (n == "webhook-id") out.id = value; + else if (n == "webhook-timestamp") out.timestamp = value; + else if (n == "webhook-signature") out.signature = value; + } + return out; +} + +void WebhookCounters::count(WebhookFailure failure) { + g_failures[static_cast(failure)].fetch_add(1, std::memory_order_relaxed); +} +std::uint64_t WebhookCounters::value(WebhookFailure failure) { + return g_failures[static_cast(failure)].load(std::memory_order_relaxed); +} +std::uint64_t WebhookCounters::accepted() { return g_accepted.load(std::memory_order_relaxed); } +void WebhookCounters::count_accepted() { g_accepted.fetch_add(1, std::memory_order_relaxed); } + +std::map WebhookCounters::snapshot() { + std::map out; + out["accepted"] = accepted(); + for (std::size_t i = 1; i < kFailureCount; ++i) + out[webhook_failure_name(static_cast(i))] = value(static_cast(i)); + return out; +} + +WebhookVerifier::WebhookVerifier(const std::string& secret, std::int64_t tolerance_seconds) + : key_(decode_secret(secret)), tolerance_(tolerance_seconds) { + Validate::range("tolerance_seconds", tolerance_seconds, 0, AdminCaps::kMaxToleranceSeconds); +} + +WebhookVerifier::~WebhookVerifier() { crypto::SecureRandom::zeroize(key_); } + +std::int64_t WebhookVerifier::system_now() { + return std::chrono::duration_cast( + std::chrono::system_clock::now().time_since_epoch()) + .count(); +} + +std::string WebhookVerifier::sign(const std::string& webhook_id, const std::string& timestamp, + const std::string& body) const { + const std::string signed_payload = webhook_id + "." + timestamp + "." + body; + const auto mac = crypto::Hmac::sha256(key_, signed_payload); + return "v1," + crypto::Base64::encode(mac.data(), mac.size()); +} + +VerifyResult WebhookVerifier::verify(const std::string& body, const WebhookHeaders& h) const { + return verify(body, h, system_now()); +} + +VerifyResult WebhookVerifier::verify(const std::string& body, const WebhookHeaders& h, + std::int64_t now) const { + auto reject = [](WebhookFailure f, const std::string& why) { + WebhookCounters::count(f); + VerifyResult r; + r.failure = f; + r.reason = why; + return r; + }; + if (body.size() > AdminCaps::kMaxWebhookBodyBytes) + return reject(WebhookFailure::kBodyTooLarge, "body is over the byte cap"); + if (h.id.empty() || h.id.size() > 256) + return reject(WebhookFailure::kMissingId, "missing webhook-id header"); + if (h.timestamp.empty()) + return reject(WebhookFailure::kMissingTimestamp, "missing webhook-timestamp header"); + if (h.signature.empty()) + return reject(WebhookFailure::kMissingSignature, "missing webhook-signature header"); + if (h.signature.size() > AdminCaps::kMaxWebhookHeaderChars) + return reject(WebhookFailure::kBadSignatureHeader, "webhook-signature header is too long"); + + if (h.timestamp.size() > 12 || + !std::all_of(h.timestamp.begin(), h.timestamp.end(), + [](unsigned char c) { return std::isdigit(c) != 0; })) + return reject(WebhookFailure::kBadTimestamp, "webhook-timestamp is not unix seconds"); + const std::int64_t ts = std::stoll(h.timestamp); + if (now - ts > tolerance_) return reject(WebhookFailure::kTooOld, "timestamp is outside the tolerance (old)"); + if (ts - now > tolerance_) return reject(WebhookFailure::kTooNew, "timestamp is outside the tolerance (future)"); + + // Candidate signatures: space separated "v1," entries. + std::vector candidates; + std::size_t pos = 0; + while (pos < h.signature.size()) { + while (pos < h.signature.size() && std::isspace(static_cast(h.signature[pos]))) ++pos; + std::size_t end = pos; + while (end < h.signature.size() && !std::isspace(static_cast(h.signature[end]))) ++end; + if (end > pos) { + const std::string part = h.signature.substr(pos, end - pos); + if (part.rfind("v1,", 0) == 0) candidates.push_back(part.substr(3)); + } + pos = end; + } + if (candidates.empty()) + return reject(WebhookFailure::kBadSignatureHeader, "no v1 signature in webhook-signature"); + if (candidates.size() > AdminCaps::kMaxWebhookSignatures) + return reject(WebhookFailure::kBadSignatureHeader, "too many signatures in webhook-signature"); + + const std::string signed_payload = h.id + "." + h.timestamp + "." + body; + const auto expected = crypto::Hmac::sha256(key_, signed_payload); + bool match = false; + for (const std::string& c : candidates) { + std::string raw; + if (!crypto::Base64::decode(c, raw) || raw.size() != expected.size()) continue; + match |= crypto::SecureRandom::constant_time_equal( + reinterpret_cast(raw.data()), expected.data(), expected.size()); + } + if (!match) return reject(WebhookFailure::kMismatch, "signature does not match"); + + WebhookCounters::count_accepted(); + VerifyResult ok; + ok.ok = true; + return ok; +} + +void WebhookVerifier::require(const std::string& body, const WebhookHeaders& h, + std::int64_t now) const { + const VerifyResult r = verify(body, h, now); + if (!r.ok) throw llm::ApiError("openai", 401, "INVALID_SIGNATURE", r.reason); +} + +WebhookEvent WebhookVerifier::unwrap(const std::string& body, const WebhookHeaders& h, + std::int64_t now) const { + require(body, h, now); + return WebhookEnvelope::parse(body); +} + +// ---- endpoint management ---- + +AdminService::Json WebhookEndpoints::list(std::optional limit, const std::string& after) { + Query q; + if (limit) { + Validate::range("limit", *limit, 1, AdminCaps::kMaxPageLimit); + q.set_int("limit", *limit); + } + if (!after.empty()) q.set("after", after); + return execute(Call::kWebhookEndpointsList, {}, q); +} + +AdminService::Json WebhookEndpoints::get(const std::string& endpoint_id) { + return execute(Call::kWebhookEndpointsGet, {endpoint_id}); +} + +AdminService::Json WebhookEndpoints::create(const WebhookEndpointSpec& spec) { + Json body = spec.to_json(true); + return execute(Call::kWebhookEndpointsCreate, {}, {}, &body); +} + +AdminService::Json WebhookEndpoints::update(const std::string& endpoint_id, + const WebhookEndpointSpec& spec) { + Json body = spec.to_json(false); + return execute(Call::kWebhookEndpointsUpdate, {endpoint_id}, {}, &body); +} + +AdminService::Json WebhookEndpoints::destroy(const std::string& endpoint_id, bool confirm) { + return execute(Call::kWebhookEndpointsDelete, {endpoint_id}, {}, nullptr, confirm); +} + +AdminService::Json WebhookEndpoints::rotate_secret(const std::string& endpoint_id, + bool keep_old_secret_for_24_hours, + bool confirm) { + Json body = Json::object(); + body.set("keep_old_secret_active_for_24_hours", Json(keep_old_secret_for_24_hours)); + return execute(Call::kWebhookEndpointsRotateSecret, {endpoint_id}, {}, &body, confirm); +} + +AdminService::Json WebhookEndpoints::test(const std::string& endpoint_id, + const std::string& event_type) { + if (!WebhookEvents::is_subscribable(event_type)) + Validate::fail("event type " + event_type + " cannot be tested"); + Json body = Json::object(); + body.set("event_type", Json(event_type)); + return execute(Call::kWebhookEndpointsTest, {endpoint_id}, {}, &body); +} + +AdminService::Json WebhookEndpoints::event_types() { + return execute(Call::kWebhookEventTypesList); +} + +} // namespace molo::openai::admin diff --git a/src/openai/admin/webhooks.h b/src/openai/admin/webhooks.h new file mode 100644 index 0000000..6e00702 --- /dev/null +++ b/src/openai/admin/webhooks.h @@ -0,0 +1,119 @@ +#pragma once + +// Webhooks: signature verification (Standard Webhooks, HMAC-SHA256, as +// OpenAI documents and its official SDKs implement) and endpoint management. +// +// Verification algorithm (read from openai-go webhooks/webhook_helpers.go and +// webhook_secret.go, cross-checked with the Standard Webhooks spec): +// headers webhook-id, webhook-timestamp (unix seconds), webhook-signature +// signed ".." +// key secret "whsec_" -> decoded bytes (>= 24 bytes, canonical +// base64); a secret without the prefix is used as raw bytes +// signature base64(HMAC-SHA256(key, signed)); the header holds one or more +// space separated "v1," entries, any match is enough +// tolerance |now - timestamp| <= tolerance (default 300 s) +// Comparison is constant time (SecureRandom::constant_time_equal). Stricter +// than openai-go in one way: an entry without the "v1," prefix is ignored, and +// entries of other versions (v1a, ...) are skipped, as the Standard Webhooks +// spec says. The raw request body must be passed byte for byte. + +#include +#include +#include +#include +#include +#include + +#include "openai/admin/admin_service.h" +#include "openai/admin/requests.h" +#include "openai/admin/webhook_events.h" + +namespace molo::openai::admin { + +enum class WebhookFailure { + kNone, kBadSecret, kBodyTooLarge, kMissingId, kMissingTimestamp, kMissingSignature, + kBadTimestamp, kTooOld, kTooNew, kBadSignatureHeader, kMismatch +}; + +const char* webhook_failure_name(WebhookFailure failure); + +// The three delivery headers; build with `from` (case-insensitive names). +struct WebhookHeaders { + std::string id; // webhook-id + std::string timestamp; // webhook-timestamp + std::string signature; // webhook-signature + static WebhookHeaders from(const std::map& headers); +}; + +struct VerifyResult { + bool ok = false; + WebhookFailure failure = WebhookFailure::kNone; + std::string reason; // human readable, never contains the secret or the body +}; + +// Process-wide counters of rejected deliveries by reason (loud skips). +class WebhookCounters { + public: + static void count(WebhookFailure failure); + static std::uint64_t value(WebhookFailure failure); + static std::uint64_t accepted(); + static void count_accepted(); + static std::map snapshot(); +}; + +class WebhookVerifier { + public: + // Throws ApiError::invalid on an unusable secret (never echoes it). + explicit WebhookVerifier(const std::string& secret, + std::int64_t tolerance_seconds = 300); + ~WebhookVerifier(); + WebhookVerifier(const WebhookVerifier&) = default; + WebhookVerifier& operator=(const WebhookVerifier&) = default; + + std::int64_t tolerance_seconds() const { return tolerance_; } + + // Never throws; counts every rejection. + VerifyResult verify(const std::string& body, const WebhookHeaders& headers, + std::int64_t now_unix) const; + VerifyResult verify(const std::string& body, const WebhookHeaders& headers) const; + // Throws ApiError 401 INVALID_SIGNATURE on a failed verification. + void require(const std::string& body, const WebhookHeaders& headers, + std::int64_t now_unix) const; + // Verify, then parse the envelope. The body is never parsed before it verifies. + WebhookEvent unwrap(const std::string& body, const WebhookHeaders& headers, + std::int64_t now_unix) const; + + // "v1," for a delivery; used by tests and by senders of test events. + std::string sign(const std::string& webhook_id, const std::string& timestamp, + const std::string& body) const; + + static std::int64_t system_now(); + + private: + std::string key_; + std::int64_t tolerance_; +}; + +// /webhook_endpoints. These calls use the regular project API key +// (OPENAI_API_KEY); an admin key is refused by ProjectApiClient. +class WebhookEndpoints : public AdminService { + public: + explicit WebhookEndpoints(std::shared_ptr client) + : AdminService(std::move(client)) {} + + Json list(std::optional limit = std::nullopt, const std::string& after = ""); + Json get(const std::string& endpoint_id); + // The answer carries the signing secret once. + Json create(const WebhookEndpointSpec& spec); + Json update(const std::string& endpoint_id, const WebhookEndpointSpec& spec); + Json destroy(const std::string& endpoint_id, bool confirm); + // Replaces the signing secret (new secret returned once). Needs confirm: the + // old secret stops verifying unless keep_old_secret_for_24_hours. + Json rotate_secret(const std::string& endpoint_id, bool keep_old_secret_for_24_hours, + bool confirm); + // Makes OpenAI deliver a test event of that type to the endpoint URL. + Json test(const std::string& endpoint_id, const std::string& event_type); + Json event_types(); +}; + +} // namespace molo::openai::admin diff --git a/tests/example/ai/openai/admin/read_test.cpp b/tests/example/ai/openai/admin/read_test.cpp new file mode 100644 index 0000000..a82e727 --- /dev/null +++ b/tests/example/ai/openai/admin/read_test.cpp @@ -0,0 +1,27 @@ +// Route: POST /ai/openai/admin/read (422 first, then 503 without a credential) +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("OPENAI_ADMIN_KEY"); + unsetenv("OPENAI_API_KEY"); + Fixture f; + auto post = [&](const std::string& b) { + return f.client->post("/ai/openai/admin/read", b, "application/json"); + }; + auto ok = post("{\"call\":\"users.list\",\"query\":{\"limit\":5}}"); + check(ok.status == 503 && contains(ok.body, "not_configured"), "valid read without key is 503"); + check(post("{\"call\":\"webhook_event_types.list\"}").status == 503, "project-key call without key is 503"); + check(post("{}").status == 422, "missing call is 422"); + check(post("{\"call\":\"nope.list\"}").status == 422, "unknown call is 422"); + check(post("{\"call\":\"users.update\",\"ids\":[\"u\"]}").status == 422, "write via read is 422"); + check(post("{\"call\":\"users.get\"}").status == 422, "missing id is 422"); + check(post("{\"call\":\"users.get\",\"ids\":[\"../x\"]}").status == 422, "bad id is 422"); + check(post("{\"call\":\"users.list\",\"query\":{\"nope\":1}}").status == 422, "foreign query name is 422"); + check(post("{\"call\":\"users.list\",\"region\":\"zz\"}").status == 422, "bad region is 422"); + check(post("[1]").status == 422, "non-object body is 422"); + check(post("{bad").status == 422, "bad json is 422"); + check(f.client->get("/ai/openai/admin/read").status == 405, "get is 405"); + return finish("ai/openai/admin/read"); +} diff --git a/tests/example/ai/openai/admin/status_test.cpp b/tests/example/ai/openai/admin/status_test.cpp new file mode 100644 index 0000000..d75df0a --- /dev/null +++ b/tests/example/ai/openai/admin/status_test.cpp @@ -0,0 +1,26 @@ +// Route: GET /ai/openai/admin, /status, /calls, /audit-events, /webhook-events (no credential needed) +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("OPENAI_ADMIN_KEY"); + unsetenv("OPENAI_API_KEY"); + Fixture f; + auto page = f.client->get("/ai/openai/admin"); + check(page.status == 200 && contains(page.body, "OpenAI administration"), "page 200"); + check(contains(page.body, "/embedded/ai_openai_admin.js"), "page loads its script"); + auto st = f.client->get("/ai/openai/admin/status"); + check(st.status == 200 && contains(st.body, "\"configured\":false"), "status without key"); + check(contains(st.body, "\"calls\":121"), "status counts the table"); + auto calls = f.client->get("/ai/openai/admin/calls"); + check(calls.status == 200 && contains(calls.body, "projects.service_accounts.api_keys.create"), "call table listed"); + check(contains(calls.body, "\"destructive\":true"), "destructive rows flagged"); + auto audit = f.client->get("/ai/openai/admin/audit-events"); + check(audit.status == 200 && contains(audit.body, "project.archived"), "audit catalog"); + auto hooks = f.client->get("/ai/openai/admin/webhook-events"); + check(hooks.status == 200 && contains(hooks.body, "response.completed"), "webhook catalog"); + check(f.client->post("/ai/openai/admin/status", "{}", "application/json").status == 405, "post status is 405"); + check(contains(f.client->get("/").body, "/ai/openai/admin"), "matrix row for the page"); + return finish("ai/openai/admin/status"); +} diff --git a/tests/example/ai/openai/admin/usage_test.cpp b/tests/example/ai/openai/admin/usage_test.cpp new file mode 100644 index 0000000..13a1745 --- /dev/null +++ b/tests/example/ai/openai/admin/usage_test.cpp @@ -0,0 +1,27 @@ +// Route: POST /ai/openai/admin/usage, /costs, /audit +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("OPENAI_ADMIN_KEY"); + unsetenv("OPENAI_API_KEY"); + Fixture f; + auto p = [&](const char* path, const std::string& b) { + return f.client->post(std::string("/ai/openai/admin/") + path, b, "application/json"); + }; + check(p("usage", "{\"kind\":\"completions\",\"start_time\":1730419200}").status == 503, "usage without key is 503"); + check(p("usage", "{\"kind\":\"completions\"}").status == 422, "missing start_time is 422"); + check(p("usage", "{\"kind\":\"nope\",\"start_time\":1}").status == 422, "unknown kind is 422"); + check(p("usage", "{\"kind\":\"completions\",\"start_time\":1,\"limit\":999}").status == 422, "limit over cap is 422"); + check(p("usage", "{\"kind\":\"completions\",\"start_time\":1,\"sizes\":[\"1024x1024\"]}").status == 422, "foreign filter is 422"); + check(p("usage", "{\"kind\":\"images\",\"start_time\":1,\"group_by\":[\"size\"],\"walk\":true}").status == 503, "walk without key is 503"); + check(p("costs", "{\"start_time\":1730419200,\"limit\":7}").status == 503, "costs without key is 503"); + check(p("costs", "{\"start_time\":1730419200,\"limit\":181}").status == 422, "costs limit over 180 is 422"); + check(p("costs", "{\"start_time\":1,\"bucket_width\":\"1h\"}").status == 422, "costs are daily only"); + check(p("audit", "{\"limit\":20,\"event_types\":[\"project.created\"]}").status == 503, "audit without key is 503"); + check(p("audit", "{\"event_types\":[\"project.exploded\"]}").status == 422, "unknown event type is 422"); + check(p("audit", "{\"after\":\"a\",\"before\":\"b\"}").status == 422, "after and before together is 422"); + check(f.client->get("/ai/openai/admin/usage").status == 405, "get is 405"); + return finish("ai/openai/admin/usage"); +} diff --git a/tests/example/ai/openai/admin/webhook_verify_test.cpp b/tests/example/ai/openai/admin/webhook_verify_test.cpp new file mode 100644 index 0000000..fb53cdb --- /dev/null +++ b/tests/example/ai/openai/admin/webhook_verify_test.cpp @@ -0,0 +1,29 @@ +// Route: POST /ai/openai/admin/webhook/verify (local, no credential) +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + Fixture f; + auto v = [&](const std::string& b) { + return f.client->post("/ai/openai/admin/webhook/verify", b, "application/json"); + }; + // Standard Webhooks reference vector; signature recomputed independently with python3 hmac. + const std::string head = "{\"secret\":\"whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw\",\"now\":"; + const std::string tail = + ",\"headers\":{\"Webhook-Id\":\"msg_p5jXN8AQM9LWM0D4loKWxJek\",\"Webhook-Timestamp\":\"1614265330\"," + "\"Webhook-Signature\":\"v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=\"},"; + auto ok = v(head + "1614265330" + tail + "\"body\":\"{\\\"test\\\": 2432232314}\"}"); + check(ok.status == 200 && contains(ok.body, "\"ok\":true"), "reference vector verifies"); + check(contains(ok.body, "event_error"), "non-event body is reported, not fatal"); + auto old = v(head + "1614266000" + tail + "\"body\":\"{\\\"test\\\": 2432232314}\"}"); + check(old.status == 200 && contains(old.body, "timestamp_too_old"), "stale timestamp rejected"); + auto tampered = v(head + "1614265330" + tail + "\"body\":\"{\\\"test\\\": 2432232315}\"}"); + check(tampered.status == 200 && contains(tampered.body, "signature_mismatch"), "tampered body rejected"); + check(v("{\"headers\":{},\"body\":\"x\"}").status == 422, "missing secret is 422"); + check(v("{\"secret\":\"whsec_!!\",\"headers\":{},\"body\":\"x\"}").status == 422, "bad secret is 422"); + check(v("{\"secret\":\"whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw\",\"body\":\"x\"}").status == 422, "missing headers is 422"); + check(contains(f.client->get("/ai/openai/admin/status").body, "\"signature_mismatch\":1"), "counters exposed"); + check(f.client->get("/ai/openai/admin/webhook/verify").status == 405, "get is 405"); + return finish("ai/openai/admin/webhook_verify"); +} diff --git a/tests/example/ai/openai/admin/write_test.cpp b/tests/example/ai/openai/admin/write_test.cpp new file mode 100644 index 0000000..6a0202b --- /dev/null +++ b/tests/example/ai/openai/admin/write_test.cpp @@ -0,0 +1,31 @@ +// Route: POST /ai/openai/admin/write and /destroy (destructive calls are dry runs unless confirm:true) +#include "support/Assert.hpp" + +using namespace molo::example::test; + +int main() { + unsetenv("OPENAI_ADMIN_KEY"); + unsetenv("OPENAI_API_KEY"); + Fixture f; + auto w = [&](const std::string& b) { return f.client->post("/ai/openai/admin/write", b, "application/json"); }; + auto d = [&](const std::string& b) { return f.client->post("/ai/openai/admin/destroy", b, "application/json"); }; + check(w("{\"call\":\"invites.create\",\"body\":{\"email\":\"a@example.com\",\"role\":\"reader\"}}").status == 503, + "valid write without key is 503"); + check(w("{\"call\":\"invites.create\",\"body\":{\"email\":\"a@example.com\"}}").status == 422, "missing required field is 422"); + check(w("{\"call\":\"invites.create\",\"body\":{\"email\":\"a@example.com\",\"role\":\"reader\",\"x\":1}}").status == 422, + "foreign body field is 422"); + check(w("{\"call\":\"users.delete\",\"ids\":[\"u\"]}").status == 422, "destructive via write is 422"); + check(w("{\"call\":\"users.list\"}").status == 422, "read via write is 422"); + auto dry = d("{\"call\":\"users.delete\",\"ids\":[\"user_1\"]}"); + check(dry.status == 200 && contains(dry.body, "\"dry_run\":true"), "default is a dry run"); + check(contains(dry.body, "DELETE /organization/users/user_1"), "dry run names the call"); + auto arch = d("{\"call\":\"projects.archive\",\"ids\":[\"proj_1\"]}"); + check(arch.status == 200 && contains(arch.body, "dry_run"), "archive is a dry run"); + auto real = d("{\"call\":\"users.delete\",\"ids\":[\"user_1\"],\"confirm\":true}"); + check(real.status == 503 && contains(real.body, "not_configured"), "confirmed delete without key is 503"); + check(d("{\"call\":\"users.get\",\"ids\":[\"u\"]}").status == 422, "non-destructive call on destroy is 422"); + check(d("{\"call\":\"users.delete\",\"confirm\":\"yes\"}").status == 422, "non-bool confirm is 422"); + check(d("{\"call\":\"users.delete\"}").status == 422, "dry run still needs the id"); + check(f.client->get("/ai/openai/admin/destroy").status == 405, "get is 405"); + return finish("ai/openai/admin/write"); +} diff --git a/tests/src/openai/admin/test_admin.cpp b/tests/src/openai/admin/test_admin.cpp new file mode 100644 index 0000000..124ab67 --- /dev/null +++ b/tests/src/openai/admin/test_admin.cpp @@ -0,0 +1,480 @@ +// OpenAI organization administration: call table, credential kinds, +// destructive guards, request construction, query validation, paging +// ceilings, webhook verification and event envelopes. Local and +// deterministic; the mock transport only records the requests we send. +#include +#include +#include + +#include "framework.h" +#include "clients/transports/mock_transport.h" +#include "clients/transports/http_transport.h" +#include "openai/admin/caps.h" +#include "openai/admin/openai_admin.h" + +using namespace molo::openai::admin; +using molo::clients::ClientResponse; +using molo::clients::HeaderMap; +using molo::clients::Method; +using molo::clients::body::Json; +using molo::clients::transports::MockTransport; +using molo::llm::ApiError; +using molo::llm::NotConfiguredError; + +namespace { + +ClientResponse ok_json(const std::string& body = "{}") { + HeaderMap h; + h.set("Content-Type", "application/json"); + return ClientResponse(200, h, body); +} + +struct Rig { + MockTransport* mock; + std::shared_ptr client; + explicit Rig(const std::string& key = "sk-admin-TESTKEY") { + auto t = std::make_unique(); + mock = t.get(); + client = AdminApiClient::with_transport(std::move(t), key); + } + void accept(Method m, const std::string& path) { + molo::clients::transports::MockExpectation ex; + ex.method = m; + ex.path = path; + ex.response = ok_json(); + ex.times = 1000; + mock->expect(ex); + } + MockTransport::SeenRequest last() { return mock->seen().back(); } +}; + +bool throws_invalid(const std::function& f) { + try { + f(); + } catch (const ApiError& e) { + return e.http_status() == 400 && e.type() == "INVALID_ARGUMENT"; + } + return false; +} + +} // namespace + +TEST(openai_admin, table_is_ordered_complete_and_renders_every_path) { + ASSERT_EQ(CallTable::size(), 121u); + int project_calls = 0; + for (std::size_t i = 0; i < CallTable::size(); ++i) { + const CallSpec& s = CallTable::at(i); + ASSERT_EQ(static_cast(s.call), i); + std::vector ids(CallTable::path_params(s.call).size(), "id1"); + std::string path = CallTable::render(s.call, ids); + ASSERT_TRUE(path.find('{') == std::string::npos); + if (CallTable::auth(s.call) == AuthKind::kProject) ++project_calls; + if (std::string(s.http_method) == "DELETE") ASSERT_TRUE(CallTable::destructive(s.call)); + } + ASSERT_EQ(project_calls, 8); // /webhook_endpoints* and /webhook_event_types + ASSERT_TRUE(CallTable::schema_count() > 80u); + ASSERT_EQ(AuditEventCatalog::all().size(), 149u); + ASSERT_EQ(WebhookEvents::sent().size(), 30u); + ASSERT_EQ(WebhookEvents::subscribable().size(), 27u); +} + +TEST(openai_admin, render_rejects_bad_ids_and_wrong_arity) { + ASSERT_TRUE(throws_invalid([] { CallTable::render(Call::kUsersGet, {"../x"}); })); + ASSERT_TRUE(throws_invalid([] { CallTable::render(Call::kUsersGet, {"a/b"}); })); + ASSERT_TRUE(throws_invalid([] { CallTable::render(Call::kUsersGet, {}); })); + ASSERT_TRUE(throws_invalid([] { CallTable::render(Call::kUsersGet, {"a", "b"}); })); + ASSERT_EQ(CallTable::render(Call::kProjectsUsersGet, {"proj_1", "user-2"}), + "/organization/projects/proj_1/users/user-2"); +} + +TEST(openai_admin, only_admin_keys_reach_the_organization_api) { + for (const char* key : {"sk-proj-abc", "sk-abc", "sk-svcacct-x"}) { + try { + Rig r(key); + FAIL("regular key accepted"); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), 401); + ASSERT_EQ(e.type(), "WRONG_KEY_KIND"); + ASSERT_EQ(e.message().find(key), std::string::npos); + } + } + Rig good; + ASSERT_TRUE(good.client->configured()); + Rig none(""); + ASSERT_FALSE(none.client->configured()); + Users users(none.client); + ASSERT_THROW(users.list(), NotConfiguredError); + ASSERT_EQ(none.mock->send_count(), 0u); + // The webhook endpoint client is the mirror image: no admin keys. + ASSERT_THROW(ProjectApiClient::with_transport(std::make_unique(), "sk-admin-x"), + ApiError); +} + +TEST(openai_admin, bearer_header_region_and_base_url) { + Rig r; + r.accept(Method::kGet, "/v1/organization/users"); + Users(r.client).list(); + ASSERT_EQ(r.last().headers.get_or("Authorization", ""), "Bearer sk-admin-TESTKEY"); + ASSERT_EQ(Regions::base_url(Region::kEu), "https://eu.api.openai.com/v1"); + ASSERT_EQ(Regions::base_url(Region::kGlobal), "https://api.openai.com/v1"); + ASSERT_TRUE(Regions::parse("JP").has_value()); + ASSERT_FALSE(Regions::parse("zz").has_value()); + ASSERT_TRUE(*Regions::from_residency("EU_STORAGE_PROCESSING") == Region::kEu); + ASSERT_FALSE(Regions::from_residency("MOON").has_value()); +} + +TEST(openai_admin, service_refuses_a_call_of_the_other_credential_kind) { + Rig r; + WebhookEndpoints wrong( + ProjectApiClient::with_transport(std::make_unique(), "sk-proj-1")); + ASSERT_TRUE(throws_invalid([&] { wrong.list(); }) == false); // fine: project call + // An admin service cannot run a project call: probe through Users with a webhook row. + struct Probe : AdminService { + explicit Probe(std::shared_ptr c) : AdminService(std::move(c)) {} + Json run() { return execute(Call::kWebhookEndpointsList); } + } probe(r.client); + ASSERT_TRUE(throws_invalid([&] { probe.run(); })); + ASSERT_EQ(r.mock->send_count(), 0u); +} + +TEST(openai_admin, destructive_calls_need_confirm_and_send_nothing_without_it) { + Rig r; + r.accept(Method::kDelete, "/v1/organization/users/user_1"); + r.accept(Method::kPost, "/v1/organization/projects/proj_1/archive"); + Users users(r.client); + Projects projects(r.client); + ASSERT_TRUE(throws_invalid([&] { users.destroy("user_1", false); })); + ASSERT_TRUE(throws_invalid([&] { projects.archive("proj_1", false); })); + ASSERT_EQ(r.mock->send_count(), 0u); + users.destroy("user_1", true); + ASSERT_EQ(r.last().method, "DELETE"); + projects.archive("proj_1", true); + ASSERT_EQ(r.last().method, "POST"); + ASSERT_TRUE(r.last().target.find("/organization/projects/proj_1/archive") != std::string::npos); + // retention change and certificate deactivation are guarded too + ProjectPolicies pol(r.client); + ASSERT_TRUE(throws_invalid([&] { pol.set_data_retention("proj_1", "none", false); })); + Certificates certs(r.client); + ASSERT_TRUE(throws_invalid([&] { certs.deactivate({"cert_1"}, false); })); + OrganizationPolicies org(r.client); + ASSERT_TRUE(throws_invalid([&] { org.set_data_retention("zero_data_retention", false); })); +} + +TEST(openai_admin, request_bodies_follow_the_table) { + Rig r; + r.accept(Method::kPost, "/v1/organization/invites"); + r.accept(Method::kPost, "/v1/organization/projects"); + r.accept(Method::kPost, "/v1/organization/projects/proj_1/rate_limits/rl-x"); + Invites(r.client).create({"a@example.com", "reader", {{"proj_1", "member"}}}); + ASSERT_EQ(r.last().body, + "{\"email\":\"a@example.com\",\"projects\":[{\"id\":\"proj_1\",\"role\":\"member\"}]," + "\"role\":\"reader\"}"); + ProjectCreate pc; + pc.name = "Prod"; + pc.residency = "EU_STORAGE_PROCESSING"; + Projects(r.client).create(pc); + ASSERT_EQ(r.last().body, "{\"name\":\"Prod\",\"residency\":\"EU_STORAGE_PROCESSING\"}"); + RateLimitUpdate rl; + rl.max_requests_per_1_minute = 100; + RateLimits(r.client).update("proj_1", "rl-x", rl); + ASSERT_EQ(r.last().body, "{\"max_requests_per_1_minute\":100}"); +} + +TEST(openai_admin, request_validation_rejects_before_traffic) { + Rig r; + Invites inv(r.client); + ASSERT_TRUE(throws_invalid([&] { inv.create({"not-an-email", "reader", {}}); })); + ASSERT_TRUE(throws_invalid([&] { inv.create({"a@b.co", "admin", {}}); })); + ProjectCreate bad; + bad.name = "x"; + bad.residency = "MOON"; + ASSERT_TRUE(throws_invalid([&] { Projects(r.client).create(bad); })); + ASSERT_TRUE(throws_invalid([&] { Projects(r.client).update("p", ProjectUpdate{}); })); + ProjectUserCreate both{"u1", "a@b.co", "owner"}; + ASSERT_TRUE(throws_invalid([&] { both.to_json(); })); + ASSERT_TRUE(throws_invalid([&] { AdminApiKeys(r.client).create("k", 31536001); })); + ASSERT_TRUE(throws_invalid([&] { CertificateUpload{"", "-----BEGIN PRIVATE KEY-----"}.to_json(); })); + ASSERT_TRUE(throws_invalid([&] { SpendAlertSpec{0, {"a@b.co"}, ""}.to_json(); })); + ASSERT_TRUE(throws_invalid([&] { (ListOptions{0, "", "", ""}).to_query(); })); + ASSERT_TRUE(throws_invalid([&] { (ListOptions{101, "", "", ""}).to_query(); })); + ASSERT_TRUE(throws_invalid([&] { (ListOptions{std::nullopt, "", "", "up"}).to_query(); })); + // users.list has no `order` parameter in the table + ASSERT_TRUE(throws_invalid([&] { Users(r.client).list(ListOptions{std::nullopt, "", "", "asc"}); })); + ASSERT_EQ(r.mock->send_count(), 0u); +} + +TEST(openai_admin, usage_queries_are_checked_per_endpoint) { + Rig r; + r.accept(Method::kGet, "/v1/organization/usage/completions"); + r.accept(Method::kGet, "/v1/organization/costs"); + Usage usage(r.client); + UsageQuery q; + q.start_time = 1730419200; + q.bucket_width = "1h"; + q.limit = 24; + q.project_ids = {"proj_a", "proj_b"}; + q.group_by = {"model", "project_id"}; + q.batch = false; + usage.query(UsageKind::kCompletions, q); + const std::string target = r.last().target; + ASSERT_TRUE(target.find("start_time=1730419200") != std::string::npos); + ASSERT_TRUE(target.find("project_ids=proj_a&project_ids=proj_b") != std::string::npos); + ASSERT_TRUE(target.find("group_by=model&group_by=project_id") != std::string::npos); + ASSERT_TRUE(target.find("batch=false") != std::string::npos); + + UsageQuery bad = q; + bad.limit = 169; // 1h max is 168 + ASSERT_TRUE(throws_invalid([&] { usage.query(UsageKind::kCompletions, bad); })); + bad = q; + bad.sizes = {"1024x1024"}; // images only + ASSERT_TRUE(throws_invalid([&] { usage.query(UsageKind::kCompletions, bad); })); + bad = q; + bad.group_by = {"size"}; // images only + ASSERT_TRUE(throws_invalid([&] { usage.query(UsageKind::kCompletions, bad); })); + bad = q; + bad.start_time = 0; + ASSERT_TRUE(throws_invalid([&] { usage.query(UsageKind::kCompletions, bad); })); + bad = q; + bad.end_time = 5; + ASSERT_TRUE(throws_invalid([&] { usage.query(UsageKind::kCompletions, bad); })); + + CostQuery c; + c.start_time = 1730419200; + c.limit = 180; + c.line_items = {"gpt, input"}; + Costs(r.client).query(c); + ASSERT_TRUE(r.last().target.find("line_items=gpt%2C%20input") != std::string::npos); + c.limit = 181; + ASSERT_TRUE(throws_invalid([&] { Costs(r.client).query(c); })); + c.limit = 7; + c.bucket_width = "1h"; // costs are daily only + ASSERT_TRUE(throws_invalid([&] { Costs(r.client).query(c); })); + ASSERT_EQ(UsageEndpoints::all().size(), 11u); +} + +TEST(openai_admin, audit_queries_use_spec_names_and_the_catalog) { + Rig r; + r.accept(Method::kGet, "/v1/organization/audit_logs"); + AuditQuery q; + q.event_types = {"project.created", "api_key.deleted"}; + q.project_ids = {"proj_1"}; + q.effective_at_gte = 1730419200; + q.limit = 100; + q.tenant_only = true; + AuditLogs(r.client).list(q); + const std::string t = r.last().target; + ASSERT_TRUE(t.find("event_types%5B%5D=project.created&event_types%5B%5D=api_key.deleted") != std::string::npos); + ASSERT_TRUE(t.find("effective_at%5Bgte%5D=1730419200") != std::string::npos); + ASSERT_TRUE(t.find("tenant_only=true") != std::string::npos); + AuditQuery bad; + bad.event_types = {"project.exploded"}; + ASSERT_TRUE(throws_invalid([&] { AuditLogs(r.client).list(bad); })); + bad = AuditQuery{}; + bad.after = "a"; + bad.before = "b"; + ASSERT_TRUE(throws_invalid([&] { AuditLogs(r.client).list(bad); })); + ASSERT_TRUE(AuditEventCatalog::known("tenant.user.added")); + ASSERT_EQ(AuditEventCatalog::family("rate_limit.updated"), "rate_limit"); +} + +TEST(openai_admin, walks_stop_at_ceilings_and_say_so) { + int calls = 0; + WalkResult r = PageWalker::walk([&](const std::string& cursor) { + ++calls; + Json page = Json::object(); + Json data = Json::array(); + data.push(Json(cursor.empty() ? "first" : cursor)); + page.set("data", data); + page.set("has_more", Json(true)); + page.set("last_id", Json("id" + std::to_string(calls))); + return page; + }); + ASSERT_TRUE(r.truncated); + ASSERT_EQ(r.reason, "page ceiling"); + ASSERT_EQ(r.pages, AdminCaps::kMaxListPages); + ASSERT_TRUE(r.to_json().find("truncated_reason") != nullptr); + + int n = 0; + WalkResult done = PageWalker::walk([&](const std::string&) { + Json page = Json::object(); + page.set("data", Json::array()); + page.set("has_more", Json(++n < 3)); + page.set("next_page", Json("tok" + std::to_string(n))); + return page; + }); + ASSERT_FALSE(done.truncated); + ASSERT_EQ(done.pages, 3); + ASSERT_THROW(PageWalker::walk([](const std::string&) { return Json::object(); }), ApiError); +} + +TEST(openai_admin, usage_summary_adds_up_buckets) { + // Shape from the OpenAPI document: UsageResponse / UsageCompletionsResult / CostsResult. + Json doc = Json::parse( + "{\"object\":\"page\",\"has_more\":false,\"next_page\":null,\"data\":[{\"object\":\"bucket\"," + "\"start_time\":1,\"end_time\":2,\"results\":[{\"object\":\"organization.usage.completions.result\"," + "\"input_tokens\":10,\"output_tokens\":5,\"num_model_requests\":1},{\"object\":\"x\",\"input_tokens\":2," + "\"output_tokens\":1,\"num_model_requests\":1}]}]}"); + auto totals = UsageSummary::totals(doc); + ASSERT_EQ(totals["input_tokens"], 12.0); + ASSERT_EQ(totals["num_model_requests"], 2.0); + Json costs = Json::parse( + "{\"data\":[{\"results\":[{\"amount\":{\"value\":0.5,\"currency\":\"usd\"}}," + "{\"amount\":{\"value\":0.25,\"currency\":\"usd\"}}]}]}"); + ASSERT_EQ(UsageSummary::cost_by_currency(costs)["usd"], 0.75); +} + +namespace { +// Standard Webhooks reference vector (secret, id, timestamp, body) used by the +// libraries' own tests; the expected signature was recomputed independently +// with python3 hmac/hashlib (it is not copied from OpenAI). +const char* kSecret = "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"; +const char* kId = "msg_p5jXN8AQM9LWM0D4loKWxJek"; +const char* kTs = "1614265330"; +const char* kBody = "{\"test\": 2432232314}"; +const char* kSig = "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE="; +} // namespace + +TEST(openai_admin, webhook_signature_known_vector) { + WebhookVerifier v(kSecret); + ASSERT_EQ(v.sign(kId, kTs, kBody), kSig); + WebhookHeaders h{kId, kTs, kSig}; + ASSERT_TRUE(v.verify(kBody, h, 1614265330).ok); + ASSERT_TRUE(v.verify(kBody, h, 1614265330 + 300).ok); // edge of tolerance + ASSERT_TRUE(v.verify(kBody, h, 1614265330 - 300).ok); +} + +TEST(openai_admin, webhook_rejections_are_specific_and_counted) { + WebhookVerifier v(kSecret); + WebhookHeaders h{kId, kTs, kSig}; + const auto before = WebhookCounters::value(WebhookFailure::kMismatch); + ASSERT_TRUE(v.verify("{\"test\": 2432232315}", h, 1614265330).failure == WebhookFailure::kMismatch); + ASSERT_EQ(WebhookCounters::value(WebhookFailure::kMismatch), before + 1); + ASSERT_TRUE(v.verify(kBody, h, 1614265330 + 301).failure == WebhookFailure::kTooOld); + ASSERT_TRUE(v.verify(kBody, h, 1614265330 - 301).failure == WebhookFailure::kTooNew); + WebhookHeaders w = h; + w.id = "msg_other"; + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kMismatch); + w = h; + w.timestamp = ""; + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kMissingTimestamp); + w = h; + w.timestamp = "16x4"; + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kBadTimestamp); + w = h; + w.signature = ""; + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kMissingSignature); + w = h; + w.id = ""; + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kMissingId); + // unprefixed and other-version entries are never accepted + w = h; + w.signature = std::string(kSig).substr(3); + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kBadSignatureHeader); + w.signature = "v1a," + std::string(kSig).substr(3); + ASSERT_TRUE(v.verify(kBody, w, 1614265330).failure == WebhookFailure::kBadSignatureHeader); + // several entries: any match passes + w.signature = "v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= " + std::string(kSig); + ASSERT_TRUE(v.verify(kBody, w, 1614265330).ok); + // wrong secret + WebhookVerifier other("whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSx"); + ASSERT_FALSE(other.verify(kBody, h, 1614265330).ok); + ASSERT_THROW(other.require(kBody, h, 1614265330), ApiError); + // body cap + ASSERT_TRUE(v.verify(std::string(AdminCaps::kMaxWebhookBodyBytes + 1, 'x'), h, 1614265330).failure == + WebhookFailure::kBodyTooLarge); + ASSERT_TRUE(WebhookCounters::snapshot().count("signature_mismatch") == 1); +} + +TEST(openai_admin, webhook_secret_rules) { + ASSERT_TRUE(throws_invalid([] { WebhookVerifier(""); })); + ASSERT_TRUE(throws_invalid([] { WebhookVerifier("whsec_!!!!"); })); + ASSERT_TRUE(throws_invalid([] { WebhookVerifier("whsec_YWJj"); })); // 3 bytes + ASSERT_TRUE(throws_invalid([] { WebhookVerifier(kSecret, 3601); })); + ASSERT_TRUE(throws_invalid([] { WebhookVerifier(kSecret, -1); })); + WebhookVerifier raw("plain-secret-bytes"); // no prefix: used as raw bytes (as the SDKs do) + WebhookHeaders h = WebhookHeaders::from({{"Webhook-Id", "i1"}, {"WEBHOOK-TIMESTAMP", "100"}, + {"webhook-signature", raw.sign("i1", "100", "{}")}}); + ASSERT_TRUE(raw.verify("{}", h, 100).ok); +} + +TEST(openai_admin, webhook_unwrap_parses_after_verifying) { + // Envelope shape from the OpenAPI `webhooks` map (batch.completed). + const std::string body = + "{\"id\":\"evt_1\",\"object\":\"event\",\"created_at\":1750287018,\"type\":\"batch.completed\"," + "\"data\":{\"id\":\"batch_abc\"}}"; + WebhookVerifier v(kSecret); + WebhookHeaders h{"wh_1", "1750287078", v.sign("wh_1", "1750287078", body)}; + WebhookEvent e = v.unwrap(body, h, 1750287080); + ASSERT_EQ(e.type, "batch.completed"); + ASSERT_EQ(e.family(), "batch"); + ASSERT_EQ(e.resource_id(), "batch_abc"); + ASSERT_TRUE(e.known); + ASSERT_TRUE(e.missing_data_fields.empty()); + ASSERT_THROW(v.unwrap(body + " ", h, 1750287080), ApiError); // not parsed unverified + WebhookEvent unknown = WebhookEnvelope::parse( + "{\"id\":\"e\",\"object\":\"event\",\"created_at\":1,\"type\":\"future.thing\",\"data\":{}}"); + ASSERT_FALSE(unknown.known); + WebhookEvent partial = WebhookEnvelope::parse( + "{\"id\":\"e\",\"created_at\":1,\"type\":\"agent.session.created\",\"data\":{\"id\":\"s\"}}"); + ASSERT_EQ(partial.missing_data_fields.size(), 1u); // environment_type + ASSERT_TRUE(throws_invalid([] { WebhookEnvelope::parse("[]"); })); + ASSERT_TRUE(throws_invalid([] { WebhookEnvelope::parse("{\"id\":\"e\"}"); })); +} + +TEST(openai_admin, webhook_endpoint_calls_validate_event_types) { + WebhookEndpointSpec s; + s.name = "n"; + s.url = "http://insecure.example/x"; + s.event_types = {"batch.completed"}; + ASSERT_TRUE(throws_invalid([&] { s.to_json(true); })); + s.url = "https://hooks.example/x"; + s.event_types = {"live.call.incoming"}; // sent, but not selectable + ASSERT_TRUE(throws_invalid([&] { s.to_json(true); })); + s.event_types = {"video.completed"}; + ASSERT_EQ(s.to_json(true).dump(), + "{\"event_types\":[\"video.completed\"],\"name\":\"n\",\"url\":\"https://hooks.example/x\"}"); + ASSERT_TRUE(throws_invalid([] { WebhookEndpointSpec{}.to_json(false); })); +} + +TEST(openai_admin, certificate_scope_rules) { + Rig r; + Certificates proj(r.client, "proj_1"); + ASSERT_TRUE(throws_invalid([&] { proj.rename("c1", "n"); })); + ASSERT_TRUE(throws_invalid([&] { proj.get("c1", false); })); + ASSERT_TRUE(throws_invalid([&] { proj.activate({}); })); + ASSERT_EQ(r.mock->send_count(), 0u); +} + +// Opt-in live checks (plan rule 7): unauthenticated-grade probe with an +// invalid key, and read-only list calls with a real admin key. +// Captured at startup: other suites change the environment while running. +static const bool kLiveNet = std::getenv("MOLO_LIVE_NET") && std::string(std::getenv("MOLO_LIVE_NET")) == "1"; +static const std::string kLiveAdminKey = std::getenv("OPENAI_ADMIN_KEY") ? std::getenv("OPENAI_ADMIN_KEY") : ""; + +TEST(openai_admin, live_read_only) { + if (!kLiveNet) { + std::cout << "SKIP openai_admin.live_read_only: set MOLO_LIVE_NET=1 (and OPENAI_ADMIN_KEY)\n"; + return; + } + auto probe = AdminApiClient::with_transport( + std::make_unique(), "sk-admin-invalid"); + try { + Users(probe).list(); + FAIL("invalid key accepted"); + } catch (const ApiError& e) { + ASSERT_EQ(e.http_status(), 401); + ASSERT_EQ(e.type(), "invalid_request_error"); + } + auto client = AdminApiClient::with_transport( + std::make_unique(), kLiveAdminKey); + if (!client->configured()) { + std::cout << "SKIP openai_admin.live_read_only (key part): OPENAI_ADMIN_KEY not set\n"; + return; + } + ListOptions one; + one.limit = 1; + Json projects = Projects(client).list(one); + ASSERT_TRUE(projects.find("data") != nullptr); + Json users = Users(client).list(one); + ASSERT_TRUE(users.find("data") != nullptr); +}