grow_openbao/lib.rs
1// Skeleton created by sdk-kit 0.1.0; owned by this repository (edit freely).
2//! # grow-openbao
3//!
4//! Rust SDK for [OpenBao](https://grow-codes-packages.github.io/openbao/) by Grow Codes:
5//! one async client (tokio) for auth, KV v1/v2, transit, dynamic database credentials with
6//! a lease manager, PKI, policies and mounts, response wrapping and the Grow
7//! [`SecretsProvider`](secrets::SecretsProvider) over KV.
8//!
9//! ```no_run
10//! # async fn demo() -> grow_openbao::Result<()> {
11//! use grow_openbao::secrets::SecretsProvider;
12//! use grow_openbao::{OpenBaoClient, OpenBaoConfig};
13//!
14//! // explicit > GROW_OPENBAO_* > BAO_* / VAULT_* > defaults
15//! let client = OpenBaoClient::new(OpenBaoConfig::from_env()?)?;
16//! println!("healthy: {}", client.health().await?.healthy);
17//!
18//! // KV v2 (auto-detected per mount)
19//! let kv = client.kv().await?;
20//! kv.write("app/db", serde_json::json!({"password": "s3cr3t"}), None).await?;
21//! let secret = kv.read("app/db", None).await?;
22//! assert_eq!(secret.data["password"], "s3cr3t");
23//!
24//! // transit
25//! let ct = client.transit().encrypt("app-key", b"hello", None).await?;
26//! let pt = client.transit().decrypt("app-key", &ct.ciphertext, None).await?;
27//! assert_eq!(pt, b"hello");
28//!
29//! // the Grow SecretsProvider over KV
30//! let secrets = client.secrets();
31//! secrets.set("api-key", "abc123".into(), None).await?;
32//! assert_eq!(secrets.get_string("api-key", None).await?.as_deref(), Some("abc123"));
33//!
34//! client.close().await;
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! Features: `blocking` (a blocking client), `testing` (in-memory fakes, the conformance
40//! runner and the [`testing::init`] / [`testing::unseal`] server lifecycle helpers).
41#![cfg_attr(docsrs, feature(doc_cfg))]
42
43pub mod core;
44
45mod api;
46mod auth;
47mod client;
48mod config;
49mod database;
50mod kv;
51mod lease;
52mod pki;
53mod provider;
54mod renew;
55mod sys;
56mod transit;
57mod wrapping;
58
59#[cfg(feature = "blocking")]
60#[cfg_attr(docsrs, doc(cfg(feature = "blocking")))]
61pub mod blocking;
62
63// The generated test support (`src/testing/mod.rs`, owned by sdk-kit) is compiled as a
64// private module and re-exported together with the service-owned server lifecycle helpers
65// (`init`, `unseal`, `seal`, ...), so `grow_openbao::testing` matches the `testing` module of
66// the other four languages without editing the generated file.
67#[cfg(feature = "testing")]
68#[path = "testing/mod.rs"]
69mod testing_generated;
70
71#[cfg(feature = "testing")]
72mod operator;
73
74/// Test support (feature `testing`): in-memory fakes, the conformance runner (SPEC ยง6) and
75/// the OpenBao server lifecycle helpers ([`testing::init`], [`testing::unseal`],
76/// [`testing::seal`], [`testing::init_status`], [`testing::wait_for_active`]) used by test
77/// fixtures and bootstrap scripts.
78///
79/// ```no_run
80/// # async fn demo() -> grow_openbao::Result<()> {
81/// use grow_openbao::testing::{self, InitOptions};
82/// use grow_openbao::{OpenBaoClient, OpenBaoConfig};
83///
84/// let client = OpenBaoClient::new(OpenBaoConfig::builder().url("http://openbao:8200").build()?)?;
85/// if !testing::init_status(&client).await? {
86/// let init = testing::init(&client, &InitOptions::default()).await?;
87/// testing::unseal(&client, init.keys[0].expose_secret()).await?;
88/// client.set_token(Some(init.root_token.clone()));
89/// }
90/// testing::wait_for_active(&client, std::time::Duration::from_secs(30)).await?;
91/// # Ok(())
92/// # }
93/// ```
94#[cfg(feature = "testing")]
95#[cfg_attr(docsrs, doc(cfg(feature = "testing")))]
96pub mod testing {
97 pub use crate::operator::{
98 init, init_status, seal, unseal, unseal_reset, wait_for_active, InitOptions, InitResult,
99 };
100 pub use crate::testing_generated::*;
101}
102
103pub mod secrets;
104
105pub use crate::core::{Error, ErrorCode, HealthStatus, Result, RetryPolicy, Secret};
106
107pub use crate::config::{DEFAULT_KV_MOUNT, DEFAULT_URL, DEFAULT_VALUE_FIELD};
108
109pub use crate::client::OpenBaoClient;
110
111pub use crate::config::OpenBaoConfig;
112
113pub use crate::config::OpenBaoConfigBuilder;
114
115pub use crate::auth::{
116 AppRoleAuth, Auth, AuthInfo, AuthMethod, JwtAuth, KubernetesAuth, TokenAuth,
117 TokenCreateOptions, TokenInfo, UserpassAuth, DEFAULT_KUBERNETES_JWT_PATH,
118};
119pub use crate::database::{Database, DatabaseConnectionConfig, DatabaseRole, Lease};
120pub use crate::kv::{Kv, KvMetadata, KvMetadataOptions, KvSecret, KvV1, KvV2, KvVersionMetadata};
121pub use crate::lease::{
122 LeaseInfo, LeaseLookup, LeaseManager, ManageOptions, ManagedLease, OnLeaseError, OnLeaseExpire,
123 OnLeaseRenew,
124};
125pub use crate::pki::{
126 Certificate, CertificateInfo, IssueOptions, Pki, Revocation, TidyOptions, TidyStatus,
127};
128pub use crate::provider::{KvSecretsProvider, SecretsProviderOptions};
129pub use crate::renew::{OnExpire, OnRenew, OnRenewError, TokenRenewer, TokenRenewerOptions};
130pub use crate::sys::{
131 AppRoleOptions, HealthResponse, LeaderStatus, MountInfo, MountOptions, Policy, SealStatus,
132 SecretId, SecretIdOptions, Sys,
133};
134pub use crate::transit::{
135 CreateKeyOptions, DataKey, DataKeyOptions, EncryptOptions, HashOptions, HmacOptions,
136 SignOptions, Transit, TransitBatchItem, TransitBatchResult, TransitCiphertext, TransitKey,
137 TransitKeyConfig, TransitKeyVersion, TransitSignature,
138};
139pub use crate::wrapping::{SecretResponse, WrapInfo, WrapLookup, Wrapping};
140
141/// Service-prefixed alias of [`Error`].
142pub type OpenBaoError = Error;