connector_secrets/lib.rs
1//! Where a connector's credential **address** resolves to a **value**.
2//!
3//! [`connector_address::credential`] owns the address:
4//! `tenants/<tenant>/<authority>[/@instances/<uuid>][/<service>]/<credential>`, pure and validated —
5//! the instance being which of a tenant's connections, present only when it holds more than one
6//! (C-406), so a single-connection address is exactly what it always was. It deliberately owns
7//! nothing else — `docs/vision.md`'s non-goal is load-bearing: *"A runtime. This repo compiles; flux
8//! executes."* This crate is the other half, and it is a **host library**.
9//!
10//! # It is outside the compile path, and that is asserted
11//!
12//! This host library performs runtime IO: [`FileStore`] reaches the filesystem and the optional
13//! Vault transport opens a socket. If `connector-cli` could reach either, then
14//! *"generation is explicit, committed, deterministic and offline"* would stop being a statement
15//! about the build, and `crates/connector-cli/tests/no_network.rs` — whose strongest leg is a source
16//! audit of `connector-cli/src` — would no longer be able to see the violation, because the socket
17//! would live in a different crate.
18//!
19//! So the fence is a test over the resolved dependency graph, not a convention:
20//! `crates/connector-cli/tests/dependency_fence.rs`. It reads `Cargo.lock`, which records optional
21//! dependencies too, so adding the edge behind a feature flag trips it as well.
22//!
23//! # The shape
24//!
25//! ```
26//! use connector_secrets::{CredentialRef, MemoryStore, Secret, SecretStore, StoreError};
27//!
28//! # async fn example() -> Result<(), StoreError> {
29//! let store = MemoryStore::new();
30//! let reference = CredentialRef::new("9f3a4b2c", "com.zendesk.api", "support", "api_token")
31//! .expect("a valid address");
32//!
33//! store.put(&reference, &Secret::new("SENTINEL-NOT-A-REAL-SECRET")).await?;
34//! let secret = store.get(&reference).await?;
35//! assert_eq!(secret.expose_secret(), "SENTINEL-NOT-A-REAL-SECRET");
36//!
37//! store.delete(&reference).await?;
38//! assert!(matches!(store.get(&reference).await, Err(StoreError::NotFound { .. })));
39//! # Ok(())
40//! # }
41//! # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(example()).unwrap();
42//! ```
43//!
44//! # Three stores, and how to choose between them
45//!
46//! | | survives the process | what protects a value at rest | prerequisite |
47//! |---|---|---|---|
48//! | [`MemoryStore`] | no | the process boundary | none |
49//! | [`FileStore`] | yes | Unix owner + `0700`/`0600`, or Windows `TokenUser` owner + protected owner-only DACL; **not encryption** | an owner-only local state directory |
50//! | `VaultStore` | yes | Vault's own storage and policy | a Vault an operator runs |
51//!
52//! [`FileStore`] is the middle rung C-207 added and C-509 made portable. Its values are **not
53//! encrypted**, and its module documentation distinguishes the Unix and Windows guarantees rather
54//! than treating one platform's mechanism as portable. Unix root, Windows administrators and copied
55//! backups remain outside the guarantee. It is the right store for one local operator and the wrong
56//! one for a shared or multi-writer deployment.
57//!
58//! # Three gaps in flux's trait, closed deliberately
59//!
60//! `flux_credentials::CredentialStore` is the nearest existing thing, and [`SecretStore`] differs
61//! from it in exactly three places, each a decision rather than a preference:
62//!
63//! - **[`delete`](SecretStore::delete) exists.** flux's trait has none, so `flux auth set --clear`
64//! bypasses the store entirely and cannot clear a Vault-backed credential.
65//! - **[`get`](SecretStore::get) distinguishes "not stored" from "backend unreachable".** flux's
66//! `load` returns an `Option` and swallows transport errors with `.ok()?`, so a Vault outage is
67//! indistinguishable from an unconfigured integration — a distinction a multi-tenant deployment
68//! will want. Here they are [`StoreError::NotFound`] and [`StoreError::Unreachable`].
69//! - **The tenant is in the reference**, not baked into the store instance. One store serves every
70//! tenant, and the address says whose credential is being asked for.
71//!
72//! C-494 adds two host guarantees beside those point operations. [`SecretStore::references`]
73//! inventories addresses inside a validated [`CredentialScope`] without exposing values, and
74//! [`SecretStore::apply`] commits a checked [`SecretBatch`] atomically. Both default to an explicit
75//! [`StoreError::Unsupported`] refusal, because decomposing an unsupported migration into point
76//! writes would expose a half-moved connector.
77//!
78//! # Recoverable prepared transactions
79//!
80//! An owning host coordinating credentials with its own value-free metadata uses the object-safe
81//! [`PreparedSecretStore`] port. [`MemoryStore`] and [`FileStore`] admit one prepared batch, keep its
82//! candidate invisible until commit, fence replay with owner-allocated non-zero generations and
83//! bound terminal outcomes until [`PreparedSecretStore::reclaim`]. Unsupported backends refuse with
84//! [`PreparedSecretError::Unsupported`]; callers must not emulate preparation with point writes.
85//!
86//! `FileStore` holds a non-blocking exclusive native lease for its lifetime and persists the
87//! transaction ledger with credentials in v2. Released 0.19.1 writers do not participate in that
88//! lease: stop all of them before the first 0.20 open. An already-open legacy process can rewrite
89//! its cached v1 image and erase v2 recovery state; a fresh 0.19.1 opener safely refuses a migrated
90//! v2 file.
91//!
92//! Adapting *to* flux's trait remains worth doing and is a separate story (C-93); it is
93//! complementary, not competing.
94//!
95//! # Out of scope
96//!
97//! No expiry, no refresh, no rotation, no revocation. The store hands back a value; keeping it
98//! current is the host's problem, and flux already owns substantial machinery for it. Nothing here
99//! should grow a second, differently-shaped version of that.
100
101// Native Windows security creation and descriptor inspection require direct Win32 calls. Unsafe is
102// denied everywhere except the small `file::platform` module that owns those calls.
103#![deny(unsafe_code)]
104
105mod batch;
106pub mod file;
107mod memory;
108mod secret;
109mod transaction;
110#[cfg(feature = "vault")]
111pub mod vault;
112
113pub use batch::SecretBatch;
114pub use file::FileStore;
115pub use memory::MemoryStore;
116pub use secret::Secret;
117pub use transaction::{
118 PreparedSecretError, PreparedSecretStore, SecretProposalDigest, SecretTransactionGeneration,
119 SecretTransactionId, SecretTransactionState, MAX_TERMINAL_TRANSACTIONS,
120};
121#[cfg(feature = "vault")]
122pub use vault::VaultStore;
123
124// The addressing, re-exported rather than redefined. There is one credential addressing scheme in
125// this ecosystem and it lives in `connector-address`; a consumer of this crate should never need to
126// name both crates to spell one address.
127//
128// **These nine names are why `connector-address` exists** (C-407). The publish closure is derived
129// from the manifests, so this re-export decides what ships beside this crate: while the addressing
130// lived in `connector-spec`, it was the whole compiler, permanently, so that
131// `use connector_secrets::CredentialRef` resolved outside this workspace.
132pub use connector_address::credential::{
133 validate_instance, validate_tenant, CredentialRef, CredentialScope, InstanceId, Layout,
134 TenantInstances, TenantLayout, INSTANCES_SEGMENT, MAX_TENANT, TENANTS_ROOT,
135};
136
137use async_trait::async_trait;
138
139/// A place a tenant's credentials are kept.
140///
141/// The unit of addressing is a [`CredentialRef`] — an address, never a store-specific key — so an
142/// implementation composes with a [`Layout`] to decide what path that address becomes. That
143/// composition is the point: the client is commodity, the convention is the part worth owning, and
144/// a deployment that already has a secret layout can keep it without a second addressing scheme.
145///
146/// # Object safety
147///
148/// Deliberately object-safe (`Arc<dyn SecretStore>`), because the intended binding is *injection at
149/// construction*, not a global lookup.
150#[async_trait]
151pub trait SecretStore: Send + Sync {
152 /// Read the value at `reference`.
153 ///
154 /// # Errors
155 ///
156 /// [`StoreError::NotFound`] when the backend answered and nothing is stored there;
157 /// [`StoreError::Unreachable`] when it did not answer at all. Telling those apart is the whole
158 /// reason this returns a `Result` rather than an `Option`, so an implementation must never
159 /// collapse a transport failure into "not configured".
160 async fn get(&self, reference: &CredentialRef) -> Result<Secret, StoreError>;
161
162 /// Write `secret` at `reference`, replacing whatever was there.
163 ///
164 /// # Errors
165 ///
166 /// Any of [`StoreError`] except [`NotFound`](StoreError::NotFound), which a write cannot
167 /// produce.
168 async fn put(&self, reference: &CredentialRef, secret: &Secret) -> Result<(), StoreError>;
169
170 /// Remove whatever is stored at `reference`.
171 ///
172 /// **Idempotent**: deleting an address that holds nothing is `Ok(())`, not
173 /// [`NotFound`](StoreError::NotFound). This is not a softening of the rule above — it is what
174 /// the backend can actually support. Vault's `DELETE` on a KV v2 metadata path answers `204`
175 /// whether or not the secret existed, so a store that reported `NotFound` here would have to
176 /// read first, which is both an extra round trip and a race. The caller that matters is
177 /// "clear this tenant's credential", and it wants idempotence.
178 ///
179 /// # Errors
180 ///
181 /// Any of [`StoreError`] except [`NotFound`](StoreError::NotFound), per the above.
182 async fn delete(&self, reference: &CredentialRef) -> Result<(), StoreError>;
183
184 /// List the addresses inside `scope`, never their values.
185 ///
186 /// Stores without a proven listing policy refuse explicitly; a caller must not infer an empty
187 /// inventory from that refusal.
188 async fn references(&self, _scope: &CredentialScope) -> Result<Vec<CredentialRef>, StoreError> {
189 Err(StoreError::Unsupported {
190 operation: "references".to_owned(),
191 reason: "this secret store cannot enumerate a credential scope".to_owned(),
192 })
193 }
194
195 /// Apply every mutation in `batch` atomically, or expose none of them.
196 async fn apply(&self, _batch: &SecretBatch) -> Result<(), StoreError> {
197 Err(StoreError::Unsupported {
198 operation: "atomic batch".to_owned(),
199 reason: "this secret store cannot guarantee atomic mutation".to_owned(),
200 })
201 }
202}
203
204/// What a [`SecretStore`] can fail with.
205///
206/// Every variant that names a location names the rendered `path`, not the [`CredentialRef`], because
207/// the path is what an operator needs in order to go and look — and because a reference renders
208/// differently under each [`Layout`], so quoting the address alone would send them to the wrong
209/// place. [`Layout`](Self::Layout) is the exception, and only because there is no rendered path in
210/// that case: the path was the *input*, and the layout's own message quotes it. None of them carries
211/// a value: a `StoreError` is safe to log.
212#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
213pub enum StoreError {
214 /// The backend answered, and there is nothing stored at that path.
215 ///
216 /// Distinct from [`Unreachable`](Self::Unreachable) on purpose: this one means "this tenant has
217 /// not connected that integration", and the other means "we cannot say".
218 #[error("no secret is stored at {path}")]
219 NotFound {
220 /// The path the store looked at.
221 path: String,
222 },
223
224 /// The backend could not be reached, or did not answer in a usable way.
225 ///
226 /// A retry may succeed. Never present this to a caller as "not configured".
227 #[error("the secret store at {path} is unreachable: {reason}")]
228 Unreachable {
229 /// The path the store was trying to reach.
230 path: String,
231 /// What went wrong on the wire.
232 reason: String,
233 },
234
235 /// The backend answered and refused: the store's own credentials are missing, expired or not
236 /// authorised for that path.
237 #[error("the secret store refused access to {path}: {reason}")]
238 Denied {
239 /// The path access was refused to.
240 path: String,
241 /// What the backend said.
242 reason: String,
243 },
244
245 /// The backend answered with something this client cannot interpret — a response shape it does
246 /// not recognise, or a status it has no meaning for.
247 ///
248 /// Separate from [`Unreachable`](Self::Unreachable) because retrying will not help.
249 #[error("the secret store returned an unusable response for {path}: {reason}")]
250 Backend {
251 /// The path in question.
252 path: String,
253 /// Why the response could not be used.
254 reason: String,
255 },
256
257 /// The configured [`Layout`] could not recover the address from a path.
258 ///
259 /// A custom layout is allowed to refuse a path it cannot spell; that is stated in [`Layout`]'s
260 /// contract as the alternative to guessing. [`Layout::render`] is infallible, so
261 /// [`Layout::parse`] is the only place a layout can refuse, and [`MemoryStore::reference`] and
262 /// `VaultStore::reference` are the two calls that raise this. That pairing is deliberate: a
263 /// variant no store can construct is a promise that does not hold, and this one used to be
264 /// exactly that (C-149).
265 #[error("the layout could not resolve the address: {reason}")]
266 Layout {
267 /// The layout's own explanation.
268 reason: String,
269 },
270
271 /// A checked mutation conflicts with the state already stored at its address.
272 #[error("the secret store cannot apply a mutation at {path}: {reason}")]
273 Conflict {
274 /// The rendered address in conflict.
275 path: String,
276 /// The checked precondition that failed.
277 reason: String,
278 },
279
280 /// The backend cannot provide a requested guarantee.
281 #[error("the secret store does not support {operation}: {reason}")]
282 Unsupported {
283 /// The store operation that was requested.
284 operation: String,
285 /// Why this backend cannot honour it.
286 reason: String,
287 },
288}
289
290impl StoreError {
291 /// Whether this is [`NotFound`](Self::NotFound) — the "this tenant has not connected it" case.
292 ///
293 /// A named predicate because the distinction is the reason the error type exists, and because a
294 /// caller reaching for it should not have to spell out a match over a growing enum.
295 pub fn is_not_found(&self) -> bool {
296 matches!(self, Self::NotFound { .. })
297 }
298}