Skip to main content

Crate connector_secrets

Crate connector_secrets 

Source
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 processwhat protects a value at restprerequisite
MemoryStorenothe process boundarynone
FileStoreyesUnix owner + 0700/0600, or Windows TokenUser owner + protected owner-only DACL; not encryptionan owner-only local state directory
VaultStoreyesVault’s own storage and policya 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:

  • delete exists. flux’s trait has none, so flux auth set --clear bypasses the store entirely and cannot clear a Vault-backed credential.
  • get distinguishes “not stored” from “backend unreachable”. flux’s load returns an Option and 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 are StoreError::NotFound and StoreError::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 SecretStore that survives the process in one platform-protected file.

Structs§

CredentialRef
Where one tenant’s credential for one connector lives.
CredentialScope
Every credential address for one tenant and one connector authority.
InstanceId
One of a tenant’s connections to a connector, named by uuid.
MemoryStore
A SecretStore held in memory.
Secret
A credential value.
SecretBatch
One atomic set of mutations within a CredentialScope.
SecretProposalDigest
A caller-computed SHA-256 proposal digest whose domain this crate never interprets.
SecretTransactionGeneration
One non-zero owner-allocated reclamation generation.
SecretTransactionId
One opaque transaction identifier: generation bytes followed by a unique 192-bit nonce.
TenantInstances
The connections one tenant holds to one connector, and which of them an address names.
TenantLayout
The default layout: tenants/<tenant>/<authority>/<service>/<credential>.

Enums§

PreparedSecretError
Closed, payload-free failures from PreparedSecretStore.
SecretTransactionState
The complete public state vocabulary. Aborted work is deliberately Absent.
StoreError
What a SecretStore can 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 TenantLayout renders.

Traits§

Layout
How a CredentialRef becomes a path in some store.
PreparedSecretStore
A secret store that durably owns one prepared transaction and its bounded recovery outcomes.
SecretStore
A place a tenant’s credentials are kept.

Functions§

validate_instance
Whether instance is a uuid this will place in a path.
validate_tenant
Whether tenant is safe to place in a path.