axiam Namespace Reference

Namespaces
namespace	detail
namespace	webhook

Classes
struct	AccessCheck
	A single access-check request (CheckAccessBody). More...
struct	AccessDecision
	Result of an access check (CheckAccessResponse). More...
struct	AuthenticatorOptions
	Tuning for TokenAuthenticator. The defaults are the safe ones. More...
class	AuthError
	Authentication failure: wrong credentials, expired session, MFA failure, or a 401 on the refresh call itself. More...
class	AuthzError
	Authorization failure: authenticated but not permitted. More...
class	AxiamError
	Base class for every error the SDK raises. Never carries raw token material. More...
class	AxiamGuard
	§10 guard functor: a callable that turns a request into an AxiamUser using a caller-supplied authenticator (the §10 verification adapter). More...
struct	AxiamUser
	Authenticated identity injected by the §10 guard into the request context. More...
struct	CaseInsensitiveLess
	Case-insensitive header map key comparison. More...
class	Client
struct	ConfigClampedEvent
	Emitted at client construction, once per caller-supplied setting the SDK clamped (§19.1, §19.2 rule 6). More...
class	CurlTransport
	Owns a POOL of libcurl easy handles (up to TlsConfig::max_concurrent_requests) whose cookie jar, DNS cache and TLS session cache are shared through a CURLSH, so one client instance keeps one session across requests while still performing them concurrently. More...
struct	DeviceAuth
	mTLS device authentication result (POST /api/v1/auth/device). More...
struct	Ed25519Jwk
	One Ed25519 (OKP) public key from the JWK set. More...
struct	HttpRequest
	An outgoing HTTP request produced by the client's request builder. More...
struct	HttpResponse
	An HTTP response, or a transport failure. More...
class	JwksVerifier
struct	LoginResult
	Result of login / verify_mfa. More...
class	NetworkError
	Transport-level failure: connection refused, timeout, TLS error, DNS failure, malformed request (400), rate-limit (408/429) or server error (5xx). More...
struct	ReasonCode
	The three decision reason codes the server currently emits (§11 rule 9). More...
struct	RefreshEvent
	Emitted around a §9 single-flight refresh. More...
struct	RequestEndEvent
	Emitted after a call completes, success or failure. More...
struct	RequestStartEvent
	Emitted before an outbound call leaves the SDK. More...
struct	RetryEvent
	Emitted before each §16 retry wait. More...
class	Sensitive
	Wraps secret material (access tokens, mTLS private keys). More...
struct	TlsConfig
	Immutable TLS / mTLS material handed to the libcurl transport factory. More...
class	TokenAuthenticator
	Safe-by-default local verification of an AXIAM access token. More...
struct	TokenPair
	Result of a token refresh (§9). More...
struct	UserInfo
	Subset of LoginUserInfo returned on a successful authentication. More...
struct	VerifiedToken
	Result of a successful verification: the decoded payload (claims) JSON string. More...

Typedefs
using	NowFn = std::function< std::int64_t()>
	Clock seam: returns the current time as unix seconds. Injected in tests.
using	TelemetryEvent = std::variant< RequestStartEvent, RequestEndEvent, RetryEvent, RefreshEvent, ConfigClampedEvent >
	One §19.1 event.
using	TelemetryHook = std::function< void(const TelemetryEvent &)>
	A caller-supplied telemetry sink (§19).
using	HeaderMap = std::map< std::string, std::string, CaseInsensitiveLess >
using	Transport = std::function< HttpResponse(const HttpRequest &)>
	The transport seam. Injectable; defaults to the libcurl implementation.

Enumerations
enum class	Outcome { kSuccess , kFailure }
	Why a request finished. More...
enum class	RefreshRole { kLeader , kFollower }
	Whether this caller performed a §9 refresh or waited on another thread's. More...

Functions
TokenAuthenticator	make_authenticator (Client &client, std::string expected_tenant_id, AuthenticatorOptions options={})
	Convenience factory: an authenticator bound to a client's JWKS verifier.
const AxiamUser &	require_auth (const std::optional< AxiamUser > &user)
	§11 require_auth — endpoint requires an authenticated identity.
void	require_role (const std::optional< AxiamUser > &user, std::initializer_list< std::string > any_of)
	§11 require_role — local check against the verified token's roles.
void	require_access (Client &client, const std::optional< AxiamUser > &user, const std::string &action, const std::string &resource_id, std::optional< std::string > scope=std::nullopt)
	§11 require_access — authorize the REQUEST's user (subject propagation: subject_id = user.user_id) for action on resource_id.
template<typename Request >
void	require_access (Client &client, const std::optional< AxiamUser > &user, const std::string &action, const std::function< std::string(const Request &)> &resolver, const Request &request, std::optional< std::string > scope=std::nullopt)
	Resolver-based overload (§11.3c): resolve the resource id from an arbitrary request object via a callback, then delegate to the guard above.
void	ensure_curl_global_init ()
	Process-wide libcurl init/cleanup guard (idempotent).
std::optional< std::string >	base64url_decode (const std::string &in)
	Base64url decode (unpadded or padded). Returns nullopt on malformed input.
template<typename T >
std::ostream &	operator<< (std::ostream &os, const Sensitive< T > &s)

Variables
constexpr std::chrono::seconds	kDefaultClockSkew {30}
	CONTRACT §10.1 rule 7 — the leeway applied to exp and nbf must be a named, documented, bounded constant, never an inline literal and never operator-configurable to an unbounded value.
constexpr std::chrono::seconds	kMaxClockSkew {60}
constexpr const char *	kVersion = "1.0.0"
	SDK semantic version string (matches CMake project version).

Typedef Documentation

NowFn

using axiam::NowFn = typedef std::function<std::int64_t()>

Clock seam: returns the current time as unix seconds. Injected in tests.

TelemetryEvent

using axiam::TelemetryEvent = typedef std::variant<RequestStartEvent, RequestEndEvent, RetryEvent, RefreshEvent, ConfigClampedEvent>

One §19.1 event.

A closed std::variant rather than a class hierarchy: no code outside this header can add an alternative, which is what makes the "no field can carry a secret" guarantee above hold by construction. Dispatch with std::visit or std::holds_alternative.

TelemetryHook

using axiam::TelemetryHook = typedef std::function<void(const TelemetryEvent&)>

A caller-supplied telemetry sink (§19).

Invoked on the calling thread, inside the operation that produced the event, so it must not block (§19.2 rule 4). Buffering is the caller's job so they can pick the policy; every mature metrics library already buffers.

A hook that throws cannot fail the operation that fired it (§19.2 rule 2) — the dispatcher swallows it. That is a backstop, not a licence.

HeaderMap

using axiam::HeaderMap = typedef std::map<std::string, std::string, CaseInsensitiveLess>

Transport

using axiam::Transport = typedef std::function<HttpResponse(const HttpRequest&)>

The transport seam. Injectable; defaults to the libcurl implementation.

Enumeration Type Documentation

Outcome

enum class axiam::Outcome

strong

Why a request finished.

Enumerator
kSuccess	The call returned a usable response.
kFailure	The call failed, at any layer.

RefreshRole

enum class axiam::RefreshRole

strong

Whether this caller performed a §9 refresh or waited on another thread's.

Enumerator
kLeader	This caller performed the refresh.
kFollower	This caller waited on another thread's refresh.

Function Documentation

make_authenticator()

TokenAuthenticator axiam::make_authenticator ( Client &  client, std::string  expected_tenant_id, AuthenticatorOptions  options = {}  )

inline

Convenience factory: an authenticator bound to a client's JWKS verifier.

The client must outlive the returned authenticator.

require_auth()

const AxiamUser & axiam::require_auth ( const std::optional< AxiamUser > &  user )

inline

§11 require_auth — endpoint requires an authenticated identity.

Exceptions

AuthError

(→ HTTP 401) when no verified user is present.

require_role()

void axiam::require_role ( const std::optional< AxiamUser > &  user, std::initializer_list< std::string >  any_of  )

inline

§11 require_role — local check against the verified token's roles.

No server round-trip. Coarser than require_access; not a substitute for it.

Exceptions

AuthError

(401) when unauthenticated, AuthzError (403) when no role matches.

require_access() [1/2]

void axiam::require_access ( Client &  client, const std::optional< AxiamUser > &  user, const std::string &  action, const std::string &  resource_id, std::optional< std::string >  scope = std::nullopt  )

inline

§11 require_access — authorize the REQUEST's user (subject propagation: subject_id = user.user_id) for action on resource_id.

• unauthenticated → AuthError (401)
• denied / server 403 → AuthzError (403)
• transport/network failure → AuthzError (fail-closed 503 authz_unavailable)

Argument order follows §1: action before resource.

require_access() [2/2]

template<typename Request >

void axiam::require_access	(	Client &	client,
		const std::optional< AxiamUser > &	user,
		const std::string &	action,
		const std::function< std::string(const Request &)> &	resolver,
		const Request &	request,
		std::optional< std::string >	scope = std::nullopt
	)

Resolver-based overload (§11.3c): resolve the resource id from an arbitrary request object via a callback, then delegate to the guard above.

ensure_curl_global_init()

void axiam::ensure_curl_global_init

(

)

Process-wide libcurl init/cleanup guard (idempotent).

base64url_decode()

std::optional< std::string > axiam::base64url_decode

(

const std::string &

in

)

Base64url decode (unpadded or padded). Returns nullopt on malformed input.

operator<<()

template<typename T >

std::ostream & axiam::operator<<	(	std::ostream &	os,
		const Sensitive< T > &	s
	)

Variable Documentation

kDefaultClockSkew

constexpr std::chrono::seconds axiam::kDefaultClockSkew {30}

inlineconstexpr

CONTRACT §10.1 rule 7 — the leeway applied to exp and nbf must be a named, documented, bounded constant, never an inline literal and never operator-configurable to an unbounded value.

kMaxClockSkew is the hard ceiling the constructor enforces; it is the value §10.1 recommends (60 s). kDefaultClockSkew is deliberately stricter than the ceiling: every second of leeway is a second in which an already expired access token is still admitted, so the default takes only what a well-synchronised deployment actually needs. Anything above the ceiling is rejected at construction rather than silently honoured.

kMaxClockSkew

constexpr std::chrono::seconds axiam::kMaxClockSkew {60}

inlineconstexpr

kVersion

constexpr const char* axiam::kVersion = "1.0.0"

inlineconstexpr

SDK semantic version string (matches CMake project version).