Struct SecretStore 

pub struct SecretStore;

Cross-platform secret store backed by the host OS keychain.

Stateless by design — it holds no cached secrets. Every call round-trips to the OS. That makes concurrent usage safe and avoids any in-process leak surface beyond the immediate call’s return value.

Implementations

impl SecretStore

pub fn new() -> Self

pub fn put(&self, r: &SecretRef, value: &str) -> Result<(), SecretError>

Store a UTF-8 secret under (service, key). Replaces any existing value at the same ref.

On macOS, writes via /usr/bin/security add-generic-password -U -A so the resulting item has a permissive ACL — readable by any binary the user runs. This is necessary because the legacy keychain’s default ACL binds an item to the calling binary’s code-signing hash, which changes on every cargo rebuild and silently revokes read access from later versions of the same CLI tool. (/usr/bin/security is Apple-signed with full keychain entitlements — the same path reads, status checks, and deletes use, and the same path users invoke manually.)

Trade-off: the value transits argv during the spawn (visible to ps from the same user for ~milliseconds). Acceptable for the “single-user developer machine” threat model; any process that can see argv on this machine can also read the keychain directly via security. On other platforms, behavior is unchanged (keyring crate’s native backend).

pub fn put_json<T: Serialize>( &self, r: &SecretRef, value: &T, ) -> Result<(), SecretError>

Store a structured value serialized as JSON.

pub fn get(&self, r: &SecretRef) -> Result<String, SecretError>

Read a UTF-8 secret. Returns NotFound if no entry exists.

On macOS, reads through /usr/bin/security first so repeated helper rebuilds do not churn Keychain prompts against each binary’s CDHash. Backend/authorization failures are returned directly instead of falling back to an in-process read path that can trigger a second prompt.

pub fn get_json<T: for<'de> Deserialize<'de>>( &self, r: &SecretRef, ) -> Result<T, SecretError>

Read a structured value previously stored via put_json.

pub fn delete(&self, r: &SecretRef) -> Result<(), SecretError>

Delete an entry. Returns Ok even if the entry didn’t exist — idempotent from the caller’s perspective.

On macOS, deletes through /usr/bin/security first so the Apple-signed helper, not the rebuilt caller binary, owns Keychain authorization.

pub fn status(&self, r: &SecretRef) -> Result<SecretStatus, SecretError>

Existence check without returning the value. Safe to log.

On macOS, checks status through /usr/bin/security first for the same CDHash-stable authorization behavior as get.

pub fn is_available(&self) -> bool

Probe whether the OS secret store is reachable.

Opens an Entry for an internal-only sentinel and attempts to read it. Returns true iff the backend responds with either a value or NoEntry — both mean the store is reachable; PlatformFailure / NoStorageAccess mean it isn’t.

Side effects

• On macOS with a locked keychain, this may trigger a user unlock prompt. Call only when the caller is ready to handle that UX.
• On Linux it opens a DBus connection to Secret Service.
• Performance: one round-trip to the OS store. Not cached.

pub fn availability(&self) -> AvailabilityCheck

Detailed availability probe. Same round-trip as is_available, but distinguishes “no backend at all” from a specific platform failure so the FFI surface can emit a reason matching the pattern used by the other v0.4 capability probes (accountsList, calendarList, etc.).

Trait Implementations

impl Clone for SecretStore

fn clone(&self) -> SecretStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for SecretStore

impl Debug for SecretStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SecretStore

fn default() -> SecretStore

Returns the “default value” for a type.