axiam_sdk/lib.rs
1//! AXIAM SDK for Rust
2//!
3//! This crate provides the official Rust client SDK for AXIAM
4//! (Access eXtended Identity and Authorization Management), a multi-tenant
5//! IAM solution. It conforms to the cross-language SDK behavioral contract
6//! in `../CONTRACT.md` §1–§11, and offers three interchangeable transports
7//! behind Cargo features:
8//!
9//! - `rest` — [`client::AxiamClient`], built on `reqwest`; cookie-based
10//! sessions with CSRF double-submit protection (§3/§4).
11//! - `grpc` — [`grpc::AuthzGrpcClient`], for low-latency authorization
12//! checks from a service mesh.
13//! - `amqp` — [`amqp`], a closure-handler consumer for HMAC-signed,
14//! replay-protected authorization/audit messages (§8), plus
15//! [`amqp::reactor`] — the §22 reactor runtime, where the same HMAC runs in
16//! **both** directions: the server signs the hook event, and the reactor
17//! signs the allow/deny/mutate reply.
18//!
19//! An additional `actix` feature provides [`middleware::AxiamUser`], an
20//! Actix-Web extractor that verifies sessions locally against a cached JWKS
21//! (§10). The `macros` feature adds the §11 *declarative authorization
22//! helpers* — the [`macro@require_access`], [`macro@require_auth`] and
23//! [`macro@require_role`] attribute macros — layered on top of that extractor.
24//! All access/refresh tokens are wrapped in [`Sensitive`] so they are never
25//! accidentally logged or displayed.
26//!
27//! # Example: login then check access (REST transport)
28//!
29//! ```no_run
30//! use axiam_sdk::client::AxiamClient;
31//!
32//! # async fn run() -> Result<(), axiam_sdk::AxiamError> {
33//! let client = AxiamClient::builder()
34//! .base_url("https://axiam.example.com")?
35//! .tenant_slug("acme")
36//! .org_slug("acme")
37//! .build()?;
38//!
39//! client.login("user@example.com", "hunter2").await?;
40//!
41//! let allowed = client
42//! .can("read", "resource-uuid".parse().unwrap(), None)
43//! .await?;
44//! # Ok(())
45//! # }
46//! ```
47
48#![forbid(unsafe_code)]
49#![warn(missing_docs)]
50
51mod error;
52mod sensitive;
53// X-2: shared TLS-scheme guard for transport URLs (REST/gRPC/AMQP). Always
54// compiled (transport modules below are feature-gated but all reuse this).
55mod url_guard;
56
57// CONTRACT.md §19 telemetry hooks. Deliberately ungated: the event types are
58// pure data with no transport dependency, so a caller can name them (and write
59// a sink) under any feature set.
60pub mod telemetry;
61
62// CONTRACT.md §16 bounded read-only retry policy. Internal — the policy is
63// machinery, and §16.6 makes only the disable switch public surface. Gated on
64// `rest` because it waits on the tokio timer.
65#[cfg(feature = "rest")]
66mod retry;
67
68// CONTRACT.md §17 client-side decision memo. Internal — §17.2 makes only the
69// TTL public surface. Off by default; see the module docs for the staleness
70// bound a caller accepts by enabling it.
71/// The per-client cookie store, and the one place a browser build differs.
72#[cfg(feature = "rest")]
73pub mod cookies;
74#[cfg(feature = "rest")]
75mod memo;
76/// CONTRACT.md §23 Secure Remote Password — the protocol half, with no I/O.
77/// Clock types that work on wasm32 as well as native — see the module docs for
78/// why `std::time` cannot be used directly.
79pub mod time;
80
81pub use error::{
82 AuthzKind, AxiamError, IdTokenFailureReason, OAuthProtocolError, SetFailureReason,
83};
84pub use sensitive::Sensitive;
85
86// Single owner of all Phase 16 module declarations (this file is final
87// after plan 16-01; downstream plans 16-02..16-05 only fill in module
88// bodies, never edit this file, to avoid parallel-execution merge
89// conflicts).
90pub mod client;
91pub mod token;
92
93#[cfg(feature = "rest")]
94pub mod rest;
95
96// CONTRACT.md §27 — the management API. Documented by `src/management/mod.rs`'s
97// own `//!` block; a `///` here would be merged with it by rustdoc and resolved
98// in *this* scope, which breaks every intra-doc link the module makes to its own
99// children (and reports the failure with no file or line to point at).
100pub mod management;
101
102// CONTRACT.md §12 OIDC / SSO relying-party helpers — REST-only (built on the
103// same `reqwest`-based transport as `rest`/`client`).
104#[cfg(feature = "rest")]
105pub mod oidc;
106
107#[cfg(feature = "grpc")]
108pub mod grpc;
109
110#[cfg(feature = "amqp")]
111pub mod amqp;
112
113#[cfg(feature = "actix")]
114pub mod middleware;
115
116// CONTRACT.md §13 webhook signature verification (T-145). Pure computation
117// over caller-supplied bytes — no transport of its own — so it is gated on
118// `any(rest, amqp)` rather than on a transport: those are exactly the two
119// feature sets that already vendor its inputs (`hmac`, `sha2`, `hex`,
120// `subtle`), which is why it adds no dependency to either. `rest` is the
121// natural home (webhooks arrive over HTTP and `rest` is on by default, so
122// `verify_webhook` is available out of the box); `amqp` is included because an
123// AMQP-only consumer already has the identical crypto stack and gating a pure
124// HMAC helper away from it would be arbitrary.
125#[cfg(feature = "rest")]
126pub mod uma;
127pub mod webhook;
128
129// CONTRACT.md §32.7: the SSF receiver helper (SET verification and RFC 8936
130// polling). REST-only: it fetches the JWKS and polls over the REST transport.
131#[cfg(feature = "rest")]
132pub mod ssf;
133
134// §11 declarative authorization helpers: re-export the proc-macro attributes
135// from the companion `axiam-sdk-macros` crate so consumers write
136// `use axiam_sdk::require_access;` and never name the macro crate directly.
137// The macros expand to the runtime helpers in [`middleware::authz`].
138#[cfg(feature = "macros")]
139pub use axiam_sdk_macros::{require_access, require_auth, require_role};
140
141// §22.14 declarative reactor handler binding: `#[reactor_handler("...")]`, from
142// the same companion crate. Gated on its own feature rather than on `macros`
143// because `macros` implies `actix` — a reactor is an AMQP daemon with no HTTP
144// surface at all, and making one pull actix-web in to get an attribute macro
145// would be a dependency for nothing.
146#[cfg(feature = "reactor-macros")]
147pub use axiam_sdk_macros::reactor_handler;
148
149/// The range of Rust toolchains this SDK is built and tested against.
150///
151/// The floor enforces itself, and does so well: `rust-version` in `Cargo.toml` is a
152/// hard constraint Cargo checks during resolution, so a consumer on an older
153/// toolchain gets a message naming the crate and the version it needs rather than a
154/// compile error deep in someone else's source.
155///
156/// Nothing enforces the upper end, and nothing can — there is no "maximum Rust" to
157/// declare. Code that compiles on the MSRV keeps compiling on newer toolchains
158/// almost always, but "almost" is where new `deny`-by-default lints, tightened
159/// inference, and edition-adjacent behaviour changes live. Only a build on a current
160/// toolchain settles it.
161///
162/// This SDK has gated on both ends since it was written (D-10), which is why it was
163/// the model the other ten AXIAM SDKs were brought in line with. These constants make
164/// the range readable from code, matching the equivalent surface those SDKs now
165/// expose.
166///
167/// `tests/version_policy.rs` asserts both against `Cargo.toml` and the CI matrix, so
168/// neither can go stale.
169pub mod supported_versions {
170 /// The minimum supported Rust version, mirroring `rust-version` in `Cargo.toml`.
171 ///
172 /// Cargo refuses to build the crate on anything older.
173 pub const MIN_RUST_VERSION: &str = "1.89";
174
175 /// The Rust edition the crate is compiled under.
176 ///
177 /// The edition is a per-crate choice and does not constrain consumers — a 2024
178 /// edition crate is usable from a 2015 edition one — but it does set the MSRV
179 /// floor, since edition 2024 requires Rust 1.85 or newer.
180 pub const EDITION: &str = "2024";
181
182 /// The newest toolchain the CI matrix builds.
183 ///
184 /// `"stable"` rather than a pinned number, deliberately: pinning would freeze
185 /// the upper end at whatever was current the day it was written and quietly stop
186 /// testing anything new. Tracking `stable` means the newest leg keeps moving on
187 /// its own, and a regression introduced by a Rust release surfaces here rather
188 /// than in a consumer's build.
189 pub const NEWEST_TESTED: &str = "stable";
190}