Skip to main content

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}