client.hpp

Go to the documentation of this file.

// axiam::Client — the SDK's REST surface. Built via a fluent builder that
// enforces the §5 tenant-context requirement, wires strict TLS (§6) and optional
// mTLS (§6.1), captures/echoes CSRF (§3), persists cookies (§4), injects the
// tenant header on every request (§5), and performs single-flight token
// refresh (§9). Method names are snake_case per §1.
#pragma once
 
#include <chrono>
#include <functional>
#include <future>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
#include "axiam/errors.hpp"
#include "axiam/jwks.hpp"
#include "axiam/telemetry.hpp"
#include "axiam/transport.hpp"
#include "axiam/types.hpp"
 
namespace axiam {
 
class Client {
public:
    class Builder {
    public:
        Builder& base_url(std::string url);
        Builder& tenant_slug(std::string slug);
        Builder& tenant_id(std::string id);
        Builder& org_slug(std::string slug);
        Builder& org_id(std::string id);
 
        Builder& with_custom_ca(std::string ca_pem);
 
        Builder& with_client_cert(std::string cert_pem, std::string key_pem);
 
        Builder& connect_timeout(std::chrono::milliseconds ms);
        Builder& request_timeout(std::chrono::milliseconds ms);
 
        Builder& max_concurrent_requests(unsigned n);
 
        Builder& transport(Transport t);
 
        Builder& retry_enabled(bool enabled);
 
        Builder& decision_memo_ttl(std::chrono::milliseconds ttl);
 
        Builder& telemetry_hook(TelemetryHook hook);
 
        Client build();
 
    private:
        friend class Client;
        std::string base_url_;
        std::optional<std::string> tenant_slug_;
        std::optional<std::string> tenant_id_;
        std::optional<std::string> org_slug_;
        std::optional<std::string> org_id_;
        unsigned max_concurrent_requests_ = 16;
        std::string custom_ca_pem_;
        std::string client_cert_pem_;
        std::string client_key_pem_;
        std::chrono::milliseconds connect_timeout_{10000};
        std::chrono::milliseconds request_timeout_{30000};
        Transport transport_;  // empty => default libcurl
        bool retry_enabled_ = true;  // §16.1: the switch MUST default to on
        // Stored UNCLAMPED, so the §19 config_clamped event can report what the
        // caller actually asked for rather than the value it was turned into.
        std::chrono::milliseconds decision_memo_ttl_{0};
        TelemetryHook telemetry_hook_;
    };
 
    static Builder builder();
 
    // ---- §1 canonical operations (snake_case) ----
    LoginResult login(const std::string& username_or_email, const std::string& password);
    LoginResult verify_mfa(const Sensitive<std::string>& challenge_token,
                           const std::string& totp_code);
    LoginResult verify_mfa(const std::string& challenge_token, const std::string& totp_code);
    TokenPair refresh();
    void logout();
    AccessDecision check_access(const std::string& action, const std::string& resource_id,
                                std::optional<std::string> scope = std::nullopt,
                                std::optional<std::string> subject_id = std::nullopt);
    AccessDecision can(const std::string& action, const std::string& resource_id,
                       std::optional<std::string> scope = std::nullopt,
                       std::optional<std::string> subject_id = std::nullopt);
    std::vector<AccessDecision> batch_check(const std::vector<AccessCheck>& checks);
 
    DeviceAuth authenticate_device();
 
    // ---- Accepted per-language async twins (§1, C++ row: std::future) ----
    std::future<LoginResult> login_async(std::string username_or_email, std::string password);
    std::future<TokenPair> refresh_async();
    std::future<AccessDecision> check_access_async(std::string action, std::string resource_id,
                                                   std::optional<std::string> scope = std::nullopt,
                                                   std::optional<std::string> subject_id = std::nullopt);
    std::future<std::vector<AccessDecision>> batch_check_async(std::vector<AccessCheck> checks);
 
    // ---- Introspection (used by tests / middleware) ----
    int refresh_call_count() const;
 
    void _set_retry_test_seams(std::function<double()> jitter,
                               std::function<void(std::chrono::milliseconds)> sleeper);
    std::optional<std::string> csrf_token() const;
    bool has_session() const;
    JwksVerifier& jwks();
    const std::string& tenant_header() const;
 
    void close();
 
private:
    struct Impl;
    std::shared_ptr<Impl> p_;
    explicit Client(std::shared_ptr<Impl> impl);
};
 
}  // namespace axiam