feat(clients): google service-account OAuth and per-endpoint credential choice

ServiceAccountAuth signs an RS256 JWT with wolfCrypt from the key file in
GOOGLE_APPLICATION_CREDENTIALS and exchanges it for a self-refreshing bearer
token. GoogleClient holds a key and an OAuth credential and uses OAuth
everywhere except express endpoints, which only accept the key. Signing is
tested with generated RSA keys and public-key verification.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 04:29:58 +02:00
co-authored by Claude Sonnet 5.5
parent 6d744a433f
commit 90629bbbfc
11 changed files with 493 additions and 7 deletions
+9 -2
View File
@@ -17,6 +17,7 @@ client, credentials, errors, or caps.
| `caps.h` | Static ceilings, never autotuned |
| `errors.h/.cpp` | `GoogleError` (http status, Google status, message), `NotConfiguredError`, parser for Google's `{"error":{...}}` body |
| `credentials.h/.cpp` | `Credentials`: API key and OAuth bearer providers, env loader |
| `service_account.h/.cpp` | `ServiceAccountKey`, `JwtSigner` (RS256), `ServiceAccountAuth` (self-refreshing bearer) |
| `endpoints.h/.cpp` | `ServiceEndpoint` plus the catalog of known services |
| `client.h/.cpp` | `GoogleClient`: auth, JSON in/out, error mapping, over any `clients::Transport` |
| `service.h/.cpp` | `Service` base class: holds client plus endpoint, one `call()` |
@@ -44,6 +45,10 @@ client, credentials, errors, or caps.
## 3. Contracts
- Two credentials per client: an API key and an OAuth credential (bearer
token or service account via `GOOGLE_APPLICATION_CREDENTIALS`). OAuth is
used for every endpoint except express ones (`ServiceEndpoint::prefer_key`,
the Vertex express voice path), which only accept the key.
- Credentials: `GOOGLE_API_KEY` is read once by `GoogleClient::from_env()`
from the process environment, else `.env.json.local` (git-ignored, put
secrets here), else `.env.json`, in the working directory. All env knobs
@@ -84,8 +89,10 @@ client, credentials, errors, or caps.
- Streaming recognition (gRPC/WebSocket) and the Gemini Live API are not
implemented; turns are request/response over REST.
- Service-account JWT exchange for OAuth tokens: callers pass a ready token
to `Credentials::bearer`. Owner: this part, `credentials.cpp`.
- Service-account OAuth is implemented (`service_account.h`: RS256 JWT via
wolfCrypt, token exchange, refresh 60 s before expiry) and its signing is
tested with real RSA keys. The token exchange against Google itself is
unverified until a key file is configured (`GOOGLE_APPLICATION_CREDENTIALS`).
- Free-tier quota accounting is Google's; `RESOURCE_EXHAUSTED` is surfaced,
not tracked.
- Live behavior against Google needs a real `GOOGLE_API_KEY`; the suite
+18 -3
View File
@@ -17,13 +17,26 @@ clients::ClientConfig make_config(std::shared_ptr<clients::Auth> auth) {
GoogleClient::GoogleClient(std::unique_ptr<clients::Transport> transport,
std::shared_ptr<clients::Auth> auth)
: client_(std::move(transport), make_config(auth)),
configured_(auth != nullptr) {}
: GoogleClient(std::move(transport), std::move(auth), nullptr) {}
GoogleClient::GoogleClient(std::unique_ptr<clients::Transport> transport,
std::shared_ptr<clients::Auth> key,
std::shared_ptr<clients::Auth> oauth)
: client_(std::move(transport), make_config(nullptr)),
key_auth_(std::move(key)),
oauth_auth_(std::move(oauth)),
configured_(key_auth_ != nullptr || oauth_auth_ != nullptr) {}
std::shared_ptr<clients::Auth> GoogleClient::pick_auth(
const ServiceEndpoint& service) const {
if (oauth_auth_ && !service.prefer_key) return oauth_auth_;
return key_auth_ ? key_auth_ : oauth_auth_;
}
std::shared_ptr<GoogleClient> GoogleClient::from_env() {
return std::make_shared<GoogleClient>(
std::make_unique<clients::transports::HttpTransport>(),
Credentials::from_env());
Credentials::api_key_from_env(), Credentials::oauth_from_env());
}
clients::body::Json GoogleClient::request(clients::Method method,
@@ -35,6 +48,7 @@ clients::body::Json GoogleClient::request(clients::Method method,
clients::ClientRequest req(method,
clients::Url::parse(service.base_url + path));
if (body) req.json(*body);
pick_auth(service)->apply(req);
return finish(service, client_.send_blocking(std::move(req)));
} catch (const GoogleError&) {
throw;
@@ -75,6 +89,7 @@ void GoogleClient::stream_json(const ServiceEndpoint& service,
clients::ClientRequest req(
clients::Method::kPost, clients::Url::parse(service.base_url + path));
req.json(body);
pick_auth(service)->apply(req);
client_.send_stream_blocking(
std::move(req),
[&](const std::string& chunk) { return decoder.feed(chunk); });
+10
View File
@@ -21,6 +21,12 @@ class GoogleClient {
// throws NotConfiguredError before touching the network.
GoogleClient(std::unique_ptr<clients::Transport> transport,
std::shared_ptr<clients::Auth> auth);
// Two credentials: `key` (API key) and `oauth` (bearer or service
// account). OAuth is used for every endpoint except express ones
// (ServiceEndpoint::prefer_key); either may be null.
GoogleClient(std::unique_ptr<clients::Transport> transport,
std::shared_ptr<clients::Auth> key,
std::shared_ptr<clients::Auth> oauth);
// Real HTTPS transport plus GOOGLE_API_KEY from the environment.
static std::shared_ptr<GoogleClient> from_env();
@@ -57,7 +63,11 @@ class GoogleClient {
clients::body::Json finish(const ServiceEndpoint& service,
const clients::ClientResponse& response);
std::shared_ptr<clients::Auth> pick_auth(const ServiceEndpoint& service) const;
clients::Client client_;
std::shared_ptr<clients::Auth> key_auth_;
std::shared_ptr<clients::Auth> oauth_auth_;
bool configured_;
};
+14
View File
@@ -1,6 +1,8 @@
#include "google/credentials.h"
#include <cstdlib>
#include "google/service_account.h"
#include <fstream>
#include <sstream>
@@ -46,6 +48,18 @@ std::string Credentials::env(const char* name) {
return from_json_file(".env.json", name);
}
std::shared_ptr<clients::Auth> Credentials::api_key_from_env(const char* name) {
std::string key = env(name);
if (key.empty()) return nullptr;
return api_key(std::move(key));
}
std::shared_ptr<clients::Auth> Credentials::oauth_from_env() {
std::string token = env("GOOGLE_ACCESS_TOKEN");
if (!token.empty()) return bearer(std::move(token));
return ServiceAccountAuth::from_env();
}
std::shared_ptr<clients::Auth> Credentials::from_env(const char* name) {
// An OAuth access token (GOOGLE_ACCESS_TOKEN, e.g. from
// `gcloud auth print-access-token`) wins: Agent Platform APIs need it.
+7 -1
View File
@@ -19,7 +19,13 @@ class Credentials {
// Value of `name` from the process environment, else .env.json.local,
// else .env.json (working directory); empty when unset everywhere.
static std::string env(const char* name = "GOOGLE_API_KEY");
// api_key(env()) or nullptr when unset or empty.
// API key only (GOOGLE_API_KEY), or nullptr.
static std::shared_ptr<clients::Auth> api_key_from_env(
const char* name = "GOOGLE_API_KEY");
// OAuth only: GOOGLE_ACCESS_TOKEN as a bearer, else the service account in
// GOOGLE_APPLICATION_CREDENTIALS (self-refreshing), else nullptr.
static std::shared_ptr<clients::Auth> oauth_from_env();
// Legacy single credential: token, else key, else nullptr.
static std::shared_ptr<clients::Auth> from_env(
const char* name = "GOOGLE_API_KEY");
};
+1 -1
View File
@@ -14,7 +14,7 @@ ServiceEndpoint generative() {
}
ServiceEndpoint vertex_generative() {
return {"vertex", "https://aiplatform.googleapis.com/v1/publishers/google"};
return {"vertex", "https://aiplatform.googleapis.com/v1/publishers/google", true};
}
std::vector<ServiceEndpoint> catalog() {
+2
View File
@@ -11,6 +11,8 @@ namespace molo::google {
struct ServiceEndpoint {
std::string name;
std::string base_url; // No trailing slash.
// Express-mode endpoints accept only an API key: never send OAuth there.
bool prefer_key = false;
};
namespace endpoints {
+197
View File
@@ -0,0 +1,197 @@
#include "google/service_account.h"
#include <wolfssl/options.h>
#include <wolfssl/wolfcrypt/asn.h>
#include <wolfssl/wolfcrypt/error-crypt.h>
#include <wolfssl/wolfcrypt/random.h>
#include <wolfssl/wolfcrypt/rsa.h>
#include <wolfssl/wolfcrypt/signature.h>
#include <ctime>
#include <fstream>
#include <memory>
#include <sstream>
#include "clients/body/json.h"
#include "clients/client.h"
#include "clients/transports/http_transport.h"
#include "google/credentials.h"
#include "google/errors.h"
#include "security/crypto/Base64.h"
namespace molo::google {
using clients::body::Json;
using security::crypto::Base64;
namespace {
constexpr std::size_t kMaxKeyFileBytes = 64 * 1024;
constexpr auto kRefreshMargin = std::chrono::seconds(60);
std::string str(const Json& doc, const char* key) {
const Json* v = doc.is_object() ? doc.find(key) : nullptr;
return v && v->is_string() ? v->as_string() : "";
}
// Tokens may only be requested from a Google host over https: the key file
// is trusted, but a typo or a swapped file must not send a signed assertion
// to an arbitrary server.
bool google_https(const std::string& uri) {
const std::string scheme = "https://";
if (uri.rfind(scheme, 0) != 0) return false;
std::string host = uri.substr(scheme.size(), uri.find('/', scheme.size()) - scheme.size());
const std::string suffix = ".googleapis.com";
return host.size() > suffix.size() &&
host.compare(host.size() - suffix.size(), suffix.size(), suffix) == 0;
}
std::string pem_to_der(const std::string& pem) {
std::string body;
std::istringstream in(pem);
std::string line;
while (std::getline(in, line)) {
if (!line.empty() && line.back() == '\r') line.pop_back();
if (line.rfind("-----", 0) == 0 || line.empty()) continue;
body += line;
}
std::string der;
if (!Base64::decode(body, der) || der.empty())
throw GoogleError::invalid("private_key is not valid PEM");
return der;
}
class RsaKeyGuard {
public:
RsaKeyGuard() { wc_InitRsaKey(&key, nullptr); }
~RsaKeyGuard() { wc_FreeRsaKey(&key); }
RsaKeyGuard(const RsaKeyGuard&) = delete;
RsaKeyGuard& operator=(const RsaKeyGuard&) = delete;
RsaKey key;
};
} // namespace
ServiceAccountKey ServiceAccountKey::parse(const std::string& json_text) {
Json doc;
try {
doc = Json::parse(json_text);
} catch (const std::exception&) {
throw GoogleError::invalid("service account key is not valid JSON");
}
ServiceAccountKey key;
if (str(doc, "type") != "service_account")
throw GoogleError::invalid("key file type is not service_account");
key.client_email = str(doc, "client_email");
key.private_key_pem = str(doc, "private_key");
std::string uri = str(doc, "token_uri");
if (!uri.empty()) key.token_uri = uri;
key.project_id = str(doc, "project_id");
if (key.client_email.empty() || key.private_key_pem.empty())
throw GoogleError::invalid("key file lacks client_email or private_key");
if (!google_https(key.token_uri))
throw GoogleError::invalid("token_uri must be https on googleapis.com");
return key;
}
ServiceAccountKey ServiceAccountKey::load_file(const std::string& path) {
std::ifstream in(path, std::ios::binary);
if (!in) throw GoogleError::invalid("cannot read service account key file");
std::ostringstream text;
text << in.rdbuf();
if (text.str().size() > kMaxKeyFileBytes)
throw GoogleError::invalid("service account key file over the size cap");
return parse(text.str());
}
JwtSigner::JwtSigner(const ServiceAccountKey& key) : key_(key) {}
std::string JwtSigner::sign(const std::string& scope, std::int64_t iat,
std::chrono::seconds lifetime) const {
Json header = Json::object();
header.set("alg", Json("RS256"));
header.set("typ", Json("JWT"));
Json claims = Json::object();
claims.set("iss", Json(key_.client_email));
claims.set("scope", Json(scope));
claims.set("aud", Json(key_.token_uri));
claims.set("iat", Json(static_cast<double>(iat)));
claims.set("exp", Json(static_cast<double>(iat + lifetime.count())));
std::string signing_input = Base64::encode_url(header.dump()) + "." +
Base64::encode_url(claims.dump());
std::string der = pem_to_der(key_.private_key_pem);
RsaKeyGuard rsa;
word32 idx = 0;
int off = wc_GetPkcs8TraditionalOffset(
reinterpret_cast<byte*>(der.data()), &idx, static_cast<word32>(der.size()));
if (off < 0) idx = 0; // Already traditional PKCS#1.
if (wc_RsaPrivateKeyDecode(reinterpret_cast<const byte*>(der.data()), &idx,
&rsa.key, static_cast<word32>(der.size())) != 0)
throw GoogleError::invalid("private_key is not a usable RSA key");
WC_RNG rng;
if (wc_InitRng(&rng) != 0) throw GoogleError(500, "INTERNAL", "rng init failed");
word32 sig_len = static_cast<word32>(
wc_SignatureGetSize(WC_SIGNATURE_TYPE_RSA_W_ENC, &rsa.key, sizeof(rsa.key)));
std::string sig(sig_len, '\0');
int rc = wc_SignatureGenerate(
WC_HASH_TYPE_SHA256, WC_SIGNATURE_TYPE_RSA_W_ENC,
reinterpret_cast<const byte*>(signing_input.data()),
static_cast<word32>(signing_input.size()), reinterpret_cast<byte*>(sig.data()),
&sig_len, &rsa.key, sizeof(rsa.key), &rng);
wc_FreeRng(&rng);
if (rc != 0) throw GoogleError(500, "INTERNAL", "JWT signing failed");
sig.resize(sig_len);
return signing_input + "." + Base64::encode_url(sig);
}
ServiceAccountAuth::ServiceAccountAuth(ServiceAccountKey key, std::string scope)
: key_(std::move(key)), scope_(std::move(scope)), signer_(key_) {}
ServiceAccountAuth::~ServiceAccountAuth() = default;
std::string ServiceAccountAuth::token() const {
std::lock_guard<std::mutex> lock(mutex_);
auto now = std::chrono::steady_clock::now();
if (!token_.empty() && now + kRefreshMargin < expires_) return token_;
std::string assertion =
signer_.sign(scope_, static_cast<std::int64_t>(std::time(nullptr)));
clients::Client http(std::make_unique<clients::transports::HttpTransport>());
clients::ClientRequest req = clients::ClientRequest::post(key_.token_uri);
req.form("grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer"
"&assertion=" + assertion);
clients::ClientResponse resp = http.send_blocking(std::move(req));
Json doc;
try {
doc = resp.json();
} catch (const std::exception&) {
throw GoogleError(502, "BAD_RESPONSE", "token endpoint returned non-JSON", "oauth2");
}
if (!resp.is_success()) {
std::string msg = str(doc, "error_description");
throw GoogleError(resp.status() == 400 ? 401 : resp.status(),
str(doc, "error").empty() ? "UNAUTHENTICATED" : str(doc, "error"),
msg.empty() ? "token exchange failed" : msg, "oauth2");
}
token_ = str(doc, "access_token");
const Json* ttl = doc.find("expires_in");
long seconds = ttl && ttl->is_number() ? ttl->as_int() : 3600;
if (token_.empty())
throw GoogleError(502, "BAD_RESPONSE", "token endpoint returned no access_token", "oauth2");
expires_ = now + std::chrono::seconds(seconds);
return token_;
}
void ServiceAccountAuth::apply(clients::ClientRequest& request) const {
request.bearer(token());
}
std::shared_ptr<ServiceAccountAuth> ServiceAccountAuth::from_env() {
std::string path = Credentials::env("GOOGLE_APPLICATION_CREDENTIALS");
if (path.empty()) return nullptr;
return std::make_shared<ServiceAccountAuth>(ServiceAccountKey::load_file(path));
}
} // namespace molo::google
+73
View File
@@ -0,0 +1,73 @@
#pragma once
// Service-account credentials (OAuth2 JWT bearer flow, RFC 7523). Reads the
// JSON key file Google issues (client_email, private_key, token_uri), signs a
// short-lived RS256 JWT with wolfCrypt, exchanges it for an access token and
// keeps the token fresh. Needed by every Google API that refuses API keys.
//
// Env: GOOGLE_APPLICATION_CREDENTIALS = path to the key file (looked up like
// every other knob: environment, .env.json.local, .env.json).
#include <chrono>
#include <memory>
#include <mutex>
#include <string>
#include "clients/auth.h"
namespace molo::google {
struct ServiceAccountKey {
std::string client_email;
std::string private_key_pem;
std::string token_uri = "https://oauth2.googleapis.com/token";
std::string project_id; // Informational; from the key file when present.
// Throws GoogleError (invalid) when the file is missing, over the cap,
// malformed, lacks fields, or names a non-Google token endpoint.
static ServiceAccountKey load_file(const std::string& path);
static ServiceAccountKey parse(const std::string& json_text);
};
// RS256 JWT builder. Pure computation, no network.
class JwtSigner {
public:
explicit JwtSigner(const ServiceAccountKey& key);
// header.claims.signature, base64url. exp = iat + lifetime.
std::string sign(const std::string& scope, std::int64_t iat,
std::chrono::seconds lifetime = std::chrono::seconds(3600)) const;
private:
ServiceAccountKey key_;
};
// clients::Auth that always carries a valid bearer token; refreshes one
// minute before expiry. Thread safe. A failed exchange throws GoogleError.
class ServiceAccountAuth : public clients::Auth {
public:
static constexpr const char* kDefaultScope =
"https://www.googleapis.com/auth/cloud-platform";
explicit ServiceAccountAuth(ServiceAccountKey key,
std::string scope = kDefaultScope);
~ServiceAccountAuth() override;
void apply(clients::ClientRequest& request) const override;
const char* scheme() const override { return "service-account"; }
const ServiceAccountKey& key() const { return key_; }
// Env helper: loads GOOGLE_APPLICATION_CREDENTIALS; null when unset.
static std::shared_ptr<ServiceAccountAuth> from_env();
private:
std::string token() const;
ServiceAccountKey key_;
std::string scope_;
JwtSigner signer_;
mutable std::mutex mutex_;
mutable std::string token_;
mutable std::chrono::steady_clock::time_point expires_{};
};
} // namespace molo::google