Implement Phase 9: client libraries (Go, Rust, Lisp, Python)
- clients/README.md: canonical API surface and error type reference - clients/testdata/: shared JSON response fixtures - clients/go/: mciasgoclient package; net/http + TLS 1.2+; sync.RWMutex token state; DisallowUnknownFields on all decoders; 25 tests pass - clients/rust/: async mcias-client crate; reqwest+rustls (no OpenSSL); thiserror MciasError enum; Arc<RwLock> token state; 22+1 tests pass; cargo clippy -D warnings clean - clients/lisp/: ASDF mcias-client; dexador HTTP, yason JSON; mcias-error condition hierarchy; Hunchentoot mock-dispatcher; 37 fiveam checks pass on SBCL 2.6.1; yason boolean normalisation in validate-token - clients/python/: mcias_client package (Python 3.11+); httpx sync; py.typed; dataclasses; 32 pytest tests; mypy --strict + ruff clean - test/mock/mockserver.go: in-memory mock server for Go client tests - ARCHITECTURE.md §19: updated per-language notes to match implementation - PROGRESS.md: Phase 9 marked complete - .gitignore: exclude clients/rust/target/, python .venv, .pytest_cache, .fasl files Security: token never logged or exposed in error messages in any library; TLS enforced in all four languages; token stored under lock/mutex/RwLock
This commit is contained in:
514
clients/rust/src/lib.rs
Normal file
514
clients/rust/src/lib.rs
Normal file
@@ -0,0 +1,514 @@
|
||||
//! # mcias-client
|
||||
//!
|
||||
//! Async Rust client for the MCIAS (Metacircular Identity and Access System)
|
||||
//! REST API.
|
||||
//!
|
||||
//! ## Usage
|
||||
//!
|
||||
//! ```rust,no_run
|
||||
//! use mcias_client::{Client, ClientOptions};
|
||||
//!
|
||||
//! #[tokio::main]
|
||||
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
//! let client = Client::new("https://auth.example.com", ClientOptions::default())?;
|
||||
//!
|
||||
//! let (token, expires_at) = client.login("alice", "s3cret", None).await?;
|
||||
//! println!("Logged in, token expires at {expires_at}");
|
||||
//!
|
||||
//! client.logout().await?;
|
||||
//! Ok(())
|
||||
//! }
|
||||
//! ```
|
||||
//!
|
||||
//! ## Thread Safety
|
||||
//!
|
||||
//! [`Client`] is `Clone + Send + Sync`. The internally stored bearer token is
|
||||
//! protected by an `Arc<tokio::sync::RwLock<...>>` so concurrent async tasks
|
||||
//! may share a single client safely.
|
||||
|
||||
use std::sync::Arc;
|
||||
|
||||
use reqwest::{header, Certificate, StatusCode};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use tokio::sync::RwLock;
|
||||
|
||||
// ---- Error types ----
|
||||
|
||||
/// All errors returned by the MCIAS client.
|
||||
#[derive(Debug, thiserror::Error)]
|
||||
pub enum MciasError {
|
||||
/// HTTP 401 — authentication required or credentials invalid.
|
||||
#[error("authentication error: {0}")]
|
||||
Auth(String),
|
||||
|
||||
/// HTTP 403 — caller lacks required role.
|
||||
#[error("permission denied: {0}")]
|
||||
Forbidden(String),
|
||||
|
||||
/// HTTP 404 — requested resource does not exist.
|
||||
#[error("not found: {0}")]
|
||||
NotFound(String),
|
||||
|
||||
/// HTTP 400 — the request payload was invalid.
|
||||
#[error("invalid input: {0}")]
|
||||
InvalidInput(String),
|
||||
|
||||
/// HTTP 409 — resource conflict (e.g. duplicate username).
|
||||
#[error("conflict: {0}")]
|
||||
Conflict(String),
|
||||
|
||||
/// HTTP 5xx — the server returned an internal error.
|
||||
#[error("server error ({status}): {message}")]
|
||||
Server { status: u16, message: String },
|
||||
|
||||
/// Transport-level error (DNS failure, connection refused, timeout, etc.).
|
||||
#[error("transport error: {0}")]
|
||||
Transport(#[from] reqwest::Error),
|
||||
|
||||
/// Response body could not be decoded.
|
||||
#[error("decode error: {0}")]
|
||||
Decode(String),
|
||||
}
|
||||
|
||||
// ---- Data types ----
|
||||
|
||||
/// Account information returned by the server.
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct Account {
|
||||
pub id: String,
|
||||
pub username: String,
|
||||
pub account_type: String,
|
||||
pub status: String,
|
||||
pub created_at: String,
|
||||
pub updated_at: String,
|
||||
pub totp_enabled: bool,
|
||||
}
|
||||
|
||||
/// Result of a token validation request.
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct TokenClaims {
|
||||
pub valid: bool,
|
||||
#[serde(default)]
|
||||
pub sub: String,
|
||||
#[serde(default)]
|
||||
pub roles: Vec<String>,
|
||||
#[serde(default)]
|
||||
pub expires_at: String,
|
||||
}
|
||||
|
||||
/// The server's Ed25519 public key in JWK format.
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct PublicKey {
|
||||
pub kty: String,
|
||||
pub crv: String,
|
||||
pub x: String,
|
||||
}
|
||||
|
||||
/// Postgres credentials returned by the server.
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct PgCreds {
|
||||
pub host: String,
|
||||
pub port: u16,
|
||||
pub database: String,
|
||||
pub username: String,
|
||||
pub password: String,
|
||||
}
|
||||
|
||||
// ---- Internal request/response types ----
|
||||
|
||||
#[derive(Serialize)]
|
||||
struct LoginRequest<'a> {
|
||||
username: &'a str,
|
||||
password: &'a str,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
totp_code: Option<&'a str>,
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct TokenResponse {
|
||||
token: String,
|
||||
expires_at: String,
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
struct ErrorResponse {
|
||||
#[serde(default)]
|
||||
error: String,
|
||||
}
|
||||
|
||||
// ---- Client options ----
|
||||
|
||||
/// Configuration options for the MCIAS client.
|
||||
#[derive(Debug, Default, Clone)]
|
||||
pub struct ClientOptions {
|
||||
/// Optional PEM-encoded CA certificate for TLS verification.
|
||||
/// Use when connecting to a server with a self-signed or private-CA cert.
|
||||
pub ca_cert_pem: Option<Vec<u8>>,
|
||||
|
||||
/// Optional pre-existing bearer token.
|
||||
pub token: Option<String>,
|
||||
}
|
||||
|
||||
// ---- Client ----
|
||||
|
||||
/// Async MCIAS REST API client.
|
||||
///
|
||||
/// `Client` is cheaply cloneable — the internal HTTP client and token storage
|
||||
/// are reference-counted. All clones share the same token.
|
||||
#[derive(Clone)]
|
||||
pub struct Client {
|
||||
base_url: String,
|
||||
http: reqwest::Client,
|
||||
/// Bearer token storage. `Arc<RwLock<...>>` so clones share the token.
|
||||
token: Arc<RwLock<Option<String>>>,
|
||||
}
|
||||
|
||||
impl Client {
|
||||
/// Create a new client.
|
||||
///
|
||||
/// `base_url` must be an HTTPS URL (e.g. `"https://auth.example.com"`).
|
||||
/// TLS 1.2+ is enforced by the underlying `reqwest` / `rustls` stack.
|
||||
pub fn new(base_url: &str, opts: ClientOptions) -> Result<Self, MciasError> {
|
||||
let mut builder = reqwest::ClientBuilder::new()
|
||||
// Security: enforce TLS 1.2+ minimum.
|
||||
.min_tls_version(reqwest::tls::Version::TLS_1_2)
|
||||
.use_rustls_tls();
|
||||
|
||||
if let Some(pem) = opts.ca_cert_pem {
|
||||
let cert = Certificate::from_pem(&pem)
|
||||
.map_err(|e| MciasError::Decode(format!("parse CA cert: {e}")))?;
|
||||
builder = builder.add_root_certificate(cert);
|
||||
}
|
||||
|
||||
let http = builder.build()?;
|
||||
Ok(Self {
|
||||
base_url: base_url.trim_end_matches('/').to_owned(),
|
||||
http,
|
||||
token: Arc::new(RwLock::new(opts.token)),
|
||||
})
|
||||
}
|
||||
|
||||
/// Return the currently stored bearer token, if any.
|
||||
pub async fn token(&self) -> Option<String> {
|
||||
self.token.read().await.clone()
|
||||
}
|
||||
|
||||
/// Replace the stored bearer token.
|
||||
pub async fn set_token(&self, tok: Option<String>) {
|
||||
*self.token.write().await = tok;
|
||||
}
|
||||
|
||||
// ---- Authentication ----
|
||||
|
||||
/// Login with username and password. On success stores the returned token
|
||||
/// and returns `(token, expires_at)`.
|
||||
///
|
||||
/// `totp_code` may be `None` when TOTP is not enrolled.
|
||||
pub async fn login(
|
||||
&self,
|
||||
username: &str,
|
||||
password: &str,
|
||||
totp_code: Option<&str>,
|
||||
) -> Result<(String, String), MciasError> {
|
||||
let body = LoginRequest {
|
||||
username,
|
||||
password,
|
||||
totp_code,
|
||||
};
|
||||
let resp: TokenResponse = self.post("/v1/auth/login", &body).await?;
|
||||
*self.token.write().await = Some(resp.token.clone());
|
||||
Ok((resp.token, resp.expires_at))
|
||||
}
|
||||
|
||||
/// Logout — revoke the current token on the server. Clears the stored token.
|
||||
pub async fn logout(&self) -> Result<(), MciasError> {
|
||||
self.post_empty("/v1/auth/logout").await?;
|
||||
*self.token.write().await = None;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Renew the current token. The old token is revoked server-side; the new
|
||||
/// token is stored and returned as `(token, expires_at)`.
|
||||
pub async fn renew_token(&self) -> Result<(String, String), MciasError> {
|
||||
let resp: TokenResponse = self.post("/v1/auth/renew", &serde_json::json!({})).await?;
|
||||
*self.token.write().await = Some(resp.token.clone());
|
||||
Ok((resp.token, resp.expires_at))
|
||||
}
|
||||
|
||||
/// Validate a token. Returns [`TokenClaims`] with `valid: false` (no error)
|
||||
/// if the token is invalid or revoked.
|
||||
pub async fn validate_token(&self, token: &str) -> Result<TokenClaims, MciasError> {
|
||||
let body = serde_json::json!({ "token": token });
|
||||
self.post("/v1/token/validate", &body).await
|
||||
}
|
||||
|
||||
// ---- Server information ----
|
||||
|
||||
/// Call the health endpoint. Returns `Ok(())` on HTTP 200.
|
||||
pub async fn health(&self) -> Result<(), MciasError> {
|
||||
self.get_empty("/v1/health").await
|
||||
}
|
||||
|
||||
/// Return the server's Ed25519 public key in JWK format.
|
||||
pub async fn get_public_key(&self) -> Result<PublicKey, MciasError> {
|
||||
self.get("/v1/keys/public").await
|
||||
}
|
||||
|
||||
// ---- Account management (admin only) ----
|
||||
|
||||
/// Create a new account. `account_type` must be `"human"` or `"system"`.
|
||||
pub async fn create_account(
|
||||
&self,
|
||||
username: &str,
|
||||
password: Option<&str>,
|
||||
account_type: &str,
|
||||
) -> Result<Account, MciasError> {
|
||||
let mut body = serde_json::json!({
|
||||
"username": username,
|
||||
"account_type": account_type,
|
||||
});
|
||||
if let Some(pw) = password {
|
||||
body["password"] = serde_json::Value::String(pw.to_owned());
|
||||
}
|
||||
self.post_expect_status("/v1/accounts", &body, StatusCode::CREATED)
|
||||
.await
|
||||
}
|
||||
|
||||
/// List all accounts.
|
||||
pub async fn list_accounts(&self) -> Result<Vec<Account>, MciasError> {
|
||||
self.get("/v1/accounts").await
|
||||
}
|
||||
|
||||
/// Get a single account by UUID.
|
||||
pub async fn get_account(&self, id: &str) -> Result<Account, MciasError> {
|
||||
self.get(&format!("/v1/accounts/{id}")).await
|
||||
}
|
||||
|
||||
/// Update an account's status. Allowed values: `"active"`, `"inactive"`.
|
||||
pub async fn update_account(&self, id: &str, status: &str) -> Result<Account, MciasError> {
|
||||
let body = serde_json::json!({ "status": status });
|
||||
self.patch(&format!("/v1/accounts/{id}"), &body).await
|
||||
}
|
||||
|
||||
/// Soft-delete an account and revoke all its tokens.
|
||||
pub async fn delete_account(&self, id: &str) -> Result<(), MciasError> {
|
||||
self.delete(&format!("/v1/accounts/{id}")).await
|
||||
}
|
||||
|
||||
// ---- Role management (admin only) ----
|
||||
|
||||
/// Get all roles assigned to an account.
|
||||
pub async fn get_roles(&self, account_id: &str) -> Result<Vec<String>, MciasError> {
|
||||
self.get(&format!("/v1/accounts/{account_id}/roles")).await
|
||||
}
|
||||
|
||||
/// Replace the complete role set for an account.
|
||||
pub async fn set_roles(&self, account_id: &str, roles: &[&str]) -> Result<(), MciasError> {
|
||||
let url = format!("/v1/accounts/{account_id}/roles");
|
||||
self.put_no_content(&url, roles).await
|
||||
}
|
||||
|
||||
// ---- Token management (admin only) ----
|
||||
|
||||
/// Issue a long-lived token for a system account.
|
||||
pub async fn issue_service_token(
|
||||
&self,
|
||||
account_id: &str,
|
||||
) -> Result<(String, String), MciasError> {
|
||||
let body = serde_json::json!({ "account_id": account_id });
|
||||
let resp: TokenResponse = self.post("/v1/token/issue", &body).await?;
|
||||
Ok((resp.token, resp.expires_at))
|
||||
}
|
||||
|
||||
/// Revoke a token by JTI.
|
||||
pub async fn revoke_token(&self, jti: &str) -> Result<(), MciasError> {
|
||||
self.delete(&format!("/v1/token/{jti}")).await
|
||||
}
|
||||
|
||||
// ---- PG credentials (admin only) ----
|
||||
|
||||
/// Get decrypted Postgres credentials for an account.
|
||||
pub async fn get_pg_creds(&self, account_id: &str) -> Result<PgCreds, MciasError> {
|
||||
self.get(&format!("/v1/accounts/{account_id}/pgcreds"))
|
||||
.await
|
||||
}
|
||||
|
||||
/// Store Postgres credentials for an account.
|
||||
pub async fn set_pg_creds(
|
||||
&self,
|
||||
account_id: &str,
|
||||
host: &str,
|
||||
port: u16,
|
||||
database: &str,
|
||||
username: &str,
|
||||
password: &str,
|
||||
) -> Result<(), MciasError> {
|
||||
let body = serde_json::json!({
|
||||
"host": host,
|
||||
"port": port,
|
||||
"database": database,
|
||||
"username": username,
|
||||
"password": password,
|
||||
});
|
||||
self.put_no_content(&format!("/v1/accounts/{account_id}/pgcreds"), &body)
|
||||
.await
|
||||
}
|
||||
|
||||
// ---- HTTP helpers ----
|
||||
|
||||
/// Build a request with the Authorization header set from the stored token.
|
||||
/// Security: the token is read under a read-lock and is not logged.
|
||||
async fn auth_header(&self) -> Option<header::HeaderValue> {
|
||||
let guard = self.token.read().await;
|
||||
guard.as_deref().and_then(|tok| {
|
||||
header::HeaderValue::from_str(&format!("Bearer {tok}")).ok()
|
||||
})
|
||||
}
|
||||
|
||||
async fn get<T: for<'de> Deserialize<'de>>(&self, path: &str) -> Result<T, MciasError> {
|
||||
let mut req = self.http.get(format!("{}{path}", self.base_url));
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.decode(resp).await
|
||||
}
|
||||
|
||||
async fn get_empty(&self, path: &str) -> Result<(), MciasError> {
|
||||
let mut req = self.http.get(format!("{}{path}", self.base_url));
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.expect_success(resp).await
|
||||
}
|
||||
|
||||
async fn post<B: Serialize, T: for<'de> Deserialize<'de>>(
|
||||
&self,
|
||||
path: &str,
|
||||
body: &B,
|
||||
) -> Result<T, MciasError> {
|
||||
let mut req = self
|
||||
.http
|
||||
.post(format!("{}{path}", self.base_url))
|
||||
.json(body);
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.decode(resp).await
|
||||
}
|
||||
|
||||
async fn post_expect_status<B: Serialize, T: for<'de> Deserialize<'de>>(
|
||||
&self,
|
||||
path: &str,
|
||||
body: &B,
|
||||
expected: StatusCode,
|
||||
) -> Result<T, MciasError> {
|
||||
let mut req = self
|
||||
.http
|
||||
.post(format!("{}{path}", self.base_url))
|
||||
.json(body);
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
if resp.status() == expected {
|
||||
return resp
|
||||
.json::<T>()
|
||||
.await
|
||||
.map_err(|e| MciasError::Decode(e.to_string()));
|
||||
}
|
||||
Err(self.error_from_response(resp).await)
|
||||
}
|
||||
|
||||
async fn post_empty(&self, path: &str) -> Result<(), MciasError> {
|
||||
let mut req = self
|
||||
.http
|
||||
.post(format!("{}{path}", self.base_url))
|
||||
.header(header::CONTENT_LENGTH, "0");
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.expect_success(resp).await
|
||||
}
|
||||
|
||||
async fn patch<B: Serialize, T: for<'de> Deserialize<'de>>(
|
||||
&self,
|
||||
path: &str,
|
||||
body: &B,
|
||||
) -> Result<T, MciasError> {
|
||||
let mut req = self
|
||||
.http
|
||||
.patch(format!("{}{path}", self.base_url))
|
||||
.json(body);
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.decode(resp).await
|
||||
}
|
||||
|
||||
async fn put_no_content<B: Serialize + ?Sized>(&self, path: &str, body: &B) -> Result<(), MciasError> {
|
||||
let mut req = self
|
||||
.http
|
||||
.put(format!("{}{path}", self.base_url))
|
||||
.json(body);
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.expect_success(resp).await
|
||||
}
|
||||
|
||||
async fn delete(&self, path: &str) -> Result<(), MciasError> {
|
||||
let mut req = self.http.delete(format!("{}{path}", self.base_url));
|
||||
if let Some(auth) = self.auth_header().await {
|
||||
req = req.header(header::AUTHORIZATION, auth);
|
||||
}
|
||||
let resp = req.send().await?;
|
||||
self.expect_success(resp).await
|
||||
}
|
||||
|
||||
async fn decode<T: for<'de> Deserialize<'de>>(
|
||||
&self,
|
||||
resp: reqwest::Response,
|
||||
) -> Result<T, MciasError> {
|
||||
if resp.status().is_success() {
|
||||
return resp
|
||||
.json::<T>()
|
||||
.await
|
||||
.map_err(|e| MciasError::Decode(e.to_string()));
|
||||
}
|
||||
Err(self.error_from_response(resp).await)
|
||||
}
|
||||
|
||||
async fn expect_success(&self, resp: reqwest::Response) -> Result<(), MciasError> {
|
||||
if resp.status().is_success() {
|
||||
return Ok(());
|
||||
}
|
||||
Err(self.error_from_response(resp).await)
|
||||
}
|
||||
|
||||
async fn error_from_response(&self, resp: reqwest::Response) -> MciasError {
|
||||
let status = resp.status();
|
||||
let message = resp
|
||||
.json::<ErrorResponse>()
|
||||
.await
|
||||
.map(|e| if e.error.is_empty() { status.to_string() } else { e.error })
|
||||
.unwrap_or_else(|_| status.to_string());
|
||||
|
||||
match status {
|
||||
StatusCode::UNAUTHORIZED => MciasError::Auth(message),
|
||||
StatusCode::FORBIDDEN => MciasError::Forbidden(message),
|
||||
StatusCode::NOT_FOUND => MciasError::NotFound(message),
|
||||
StatusCode::BAD_REQUEST => MciasError::InvalidInput(message),
|
||||
StatusCode::CONFLICT => MciasError::Conflict(message),
|
||||
s => MciasError::Server {
|
||||
status: s.as_u16(),
|
||||
message,
|
||||
},
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user