Expand description
Where a connector’s credential address resolves to a value.
connector_address::credential owns the address:
tenants/<tenant>/<authority>[/@instances/<uuid>][/<service>]/<credential>, pure and validated —
the instance being which of a tenant’s connections, present only when it holds more than one
(C-406), so a single-connection address is exactly what it always was. It deliberately owns
nothing else — docs/vision.md’s non-goal is load-bearing: “A runtime. This repo compiles; flux
executes.” This crate is the other half, and it is a host library.
§It is outside the compile path, and that is asserted
This host library performs runtime IO: FileStore reaches the filesystem and the optional
Vault transport opens a socket. If connector-cli could reach either, then
“generation is explicit, committed, deterministic and offline” would stop being a statement
about the build, and crates/connector-cli/tests/no_network.rs — whose strongest leg is a source
audit of connector-cli/src — would no longer be able to see the violation, because the socket
would live in a different crate.
So the fence is a test over the resolved dependency graph, not a convention:
crates/connector-cli/tests/dependency_fence.rs. It reads Cargo.lock, which records optional
dependencies too, so adding the edge behind a feature flag trips it as well.
§The shape
use connector_secrets::{CredentialRef, MemoryStore, Secret, SecretStore, StoreError};
let store = MemoryStore::new();
let reference = CredentialRef::new("9f3a4b2c", "com.zendesk.api", "support", "api_token")
.expect("a valid address");
store.put(&reference, &Secret::new("SENTINEL-NOT-A-REAL-SECRET")).await?;
let secret = store.get(&reference).await?;
assert_eq!(secret.expose_secret(), "SENTINEL-NOT-A-REAL-SECRET");
store.delete(&reference).await?;
assert!(matches!(store.get(&reference).await, Err(StoreError::NotFound { .. })));§Three stores, and how to choose between them
| survives the process | what protects a value at rest | prerequisite | |
|---|---|---|---|
MemoryStore | no | the process boundary | none |
FileStore | yes | Unix owner + 0700/0600, or Windows TokenUser owner + protected owner-only DACL; not encryption | an owner-only local state directory |
VaultStore | yes | Vault’s own storage and policy | a Vault an operator runs |
FileStore is the middle rung C-207 added and C-509 made portable. Its values are not
encrypted, and its module documentation distinguishes the Unix and Windows guarantees rather
than treating one platform’s mechanism as portable. Unix root, Windows administrators and copied
backups remain outside the guarantee. It is the right store for one local operator and the wrong
one for a shared or multi-writer deployment.
§Three gaps in flux’s trait, closed deliberately
flux_credentials::CredentialStore is the nearest existing thing, and SecretStore differs
from it in exactly three places, each a decision rather than a preference:
deleteexists. flux’s trait has none, soflux auth set --clearbypasses the store entirely and cannot clear a Vault-backed credential.getdistinguishes “not stored” from “backend unreachable”. flux’sloadreturns anOptionand swallows transport errors with.ok()?, so a Vault outage is indistinguishable from an unconfigured integration — a distinction a multi-tenant deployment will want. Here they areStoreError::NotFoundandStoreError::Unreachable.- The tenant is in the reference, not baked into the store instance. One store serves every tenant, and the address says whose credential is being asked for.
C-494 adds two host guarantees beside those point operations. SecretStore::references
inventories addresses inside a validated CredentialScope without exposing values, and
SecretStore::apply commits a checked SecretBatch atomically. Both default to an explicit
StoreError::Unsupported refusal, because decomposing an unsupported migration into point
writes would expose a half-moved connector.
§Recoverable prepared transactions
An owning host coordinating credentials with its own value-free metadata uses the object-safe
PreparedSecretStore port. MemoryStore and FileStore admit one prepared batch, keep its
candidate invisible until commit, fence replay with owner-allocated non-zero generations and
bound terminal outcomes until PreparedSecretStore::reclaim. Unsupported backends refuse with
PreparedSecretError::Unsupported; callers must not emulate preparation with point writes.
FileStore holds a non-blocking exclusive native lease for its lifetime and persists the
transaction ledger with credentials in v2. Released 0.19.1 writers do not participate in that
lease: stop all of them before the first 0.20 open. An already-open legacy process can rewrite
its cached v1 image and erase v2 recovery state; a fresh 0.19.1 opener safely refuses a migrated
v2 file.
Adapting to flux’s trait remains worth doing and is a separate story (C-93); it is complementary, not competing.
§Out of scope
No expiry, no refresh, no rotation, no revocation. The store hands back a value; keeping it current is the host’s problem, and flux already owns substantial machinery for it. Nothing here should grow a second, differently-shaped version of that.
Re-exports§
pub use file::FileStore;
Modules§
- file
- A
SecretStorethat survives the process in one platform-protected file.
Structs§
- Credential
Ref - Where one tenant’s credential for one connector lives.
- Credential
Scope - Every credential address for one tenant and one connector authority.
- Instance
Id - One of a tenant’s connections to a connector, named by uuid.
- Memory
Store - A
SecretStoreheld in memory. - Secret
- A credential value.
- Secret
Batch - One atomic set of mutations within a
CredentialScope. - Secret
Proposal Digest - A caller-computed SHA-256 proposal digest whose domain this crate never interprets.
- Secret
Transaction Generation - One non-zero owner-allocated reclamation generation.
- Secret
Transaction Id - One opaque transaction identifier: generation bytes followed by a unique 192-bit nonce.
- Tenant
Instances - The connections one tenant holds to one connector, and which of them an address names.
- Tenant
Layout - The default layout:
tenants/<tenant>/<authority>/<service>/<credential>.
Enums§
- Prepared
Secret Error - Closed, payload-free failures from
PreparedSecretStore. - Secret
Transaction State - The complete public state vocabulary. Aborted work is deliberately
Absent. - Store
Error - What a
SecretStorecan fail with.
Constants§
- INSTANCES_
SEGMENT - The segment that introduces an instance uuid:
<authority>/@instances/<uuid>/…. - MAX_
TENANT - The longest tenant id this will accept.
- MAX_
TERMINAL_ TRANSACTIONS - Maximum terminal transaction outcomes retained before owner-acknowledged reclamation.
- TENANTS_
ROOT - The first segment of every path
TenantLayoutrenders.
Traits§
- Layout
- How a
CredentialRefbecomes a path in some store. - Prepared
Secret Store - A secret store that durably owns one prepared transaction and its bounded recovery outcomes.
- Secret
Store - A place a tenant’s credentials are kept.
Functions§
- validate_
instance - Whether
instanceis a uuid this will place in a path. - validate_
tenant - Whether
tenantis safe to place in a path.