Skip to main content

connector_secrets/
file.rs

1//! A [`SecretStore`] that survives the process in one platform-protected file.
2//!
3//! [`MemoryStore`](crate::MemoryStore) is honest about what it is — *"the process exiting is the
4//! cleanup"* — and that is the right store for a test and the wrong one for a deployment. A host
5//! with durable accounts whose credentials evaporate on restart makes an operator re-paste every
6//! token every time, which is the habit that gets a token pasted somewhere it should not be. This is
7//! the other end: a single file, owned by one operator, that a restart does not empty.
8//!
9//! # What protects a credential here, stated plainly
10//!
11//! **Nothing cryptographic. The values in this file are recoverable by anyone who can read it.**
12//!
13//! | | |
14//! |---|---|
15//! | Unix owner plus file mode `0600` and directory mode `0700` | set in the create calls, not fixed up afterwards; owner, mode, kind and no-follow handle metadata are checked before every read or write |
16//! | Windows process `TokenUser` SID plus a non-null protected DACL | set in the create calls with one explicit full-control allow entry for that SID; owner, DACL, kind and non-reparse handle metadata are checked before every read or write |
17//! | the write is atomic | a bounded full rewrite into a protected sibling temporary, flush, then the platform replacement primitive — a failed write leaves the previous file whole |
18//! | the file never sits inside a served directory | the path is the caller's, and [`connectors_api`](https://docs.rs/) refuses one under its own workspace root |
19//! | hex encoding | **framing, not protection.** It exists so a value containing a newline cannot forge a second entry, and so a careless `grep` over the filesystem does not match a token. `xxd -r` undoes it. |
20//! | encryption at rest | **absent.** There is no key, no passphrase and no OS keychain integration. |
21//! | protection from Unix root, Windows administrators, or a backup that copies the file | **absent.** |
22//!
23//! That table is the whole security argument, and it is deliberately short. A store that implied more
24//! would be worse than one that implies nothing: the operator's own decision — whether this machine
25//! is one they are willing to leave a vendor token on — is only theirs to make if it is stated.
26//! `VaultStore` remains the answer for a deployment that is not one operator's laptop.
27//!
28//! # Concurrency
29//!
30//! One active 0.20 writer. [`FileStore::open`] takes a non-blocking exclusive kernel lease before it
31//! reads, recovers or cleans state and holds the lease for the store lifetime. Released 0.19.1 did
32//! not take this lease, so every legacy writer must be stopped before the first 0.20 open; concurrent
33//! mixed-version writing is unsupported. A store meant for several writers wants a real backend,
34//! which is what the [`SecretStore`] port is for.
35//!
36//! # The formats
37//!
38//! ```text
39//! # codewandler-connector-secrets file store, v1
40//! tenants/dev-local/com.anthropic.api/api_key 53454e54494e454c
41//! tenants/dev-local/com.zendesk.api/support/api_token 53454e54494e454c
42//! ```
43//!
44//! Clean v1 remains byte-identical until the first prepared-transaction operation. V2 adds one
45//! inclusive retired-generation fence and a canonical bounded transaction ledger ahead of the same
46//! credential-entry grammar. A fixed owner-only sibling stage carries the complete next image while
47//! one transaction is prepared. A fresh 0.19.1 reader refuses v2 by its existing version check.
48//!
49//! One entry per line, `<address> <hex of the value>`, sorted. A blank line and a `#` comment are
50//! skipped. The separator is a space because **no address can contain one** — every segment of a
51//! [`CredentialRef`] is validated, so the split is unambiguous rather than merely conventional.
52//!
53//! Each address is parsed back through the store's [`Layout`] on load and re-rendered, so a line
54//! that is not the canonical spelling of the address it names is a loud error rather than a second
55//! entry for one credential. That is the `parse(render(r)) == r` law in [`Layout`]'s contract,
56//! enforced at the one place where a hand-edited file could break it.
57
58use std::collections::BTreeMap;
59use std::fmt;
60use std::fs::File;
61use std::io::{Read as _, Write as _};
62use std::path::{Path, PathBuf};
63use std::sync::atomic::{AtomicU64, Ordering};
64use std::sync::Mutex;
65
66use async_trait::async_trait;
67use fs2::FileExt as _;
68
69use crate::{
70    batch, CredentialRef, CredentialScope, Layout, Secret, SecretBatch, SecretStore, StoreError,
71    TenantLayout,
72};
73
74#[cfg(unix)]
75#[path = "file/unix.rs"]
76mod platform;
77#[cfg(windows)]
78#[path = "file/windows.rs"]
79mod platform;
80mod prepared;
81
82#[cfg(not(any(unix, windows)))]
83compile_error!("FileStore needs a platform-native owner-only filesystem implementation");
84
85/// The first line of every file this store writes.
86const HEADER: &str = "# codewandler-connector-secrets file store, v1";
87
88/// The prefix a version line begins with, and the version this store speaks.
89///
90/// Split out from [`HEADER`] so the version is **checked** rather than merely written. A header a
91/// reader skips as a comment is decoration: a future `v2` — one that encrypted the values, say, or
92/// changed the separator — would be loaded as `v1`, and the failure would be a wrong answer rather
93/// than a refusal. `v2` bytes read as `v1` is exactly the case a credential store must not guess at.
94const VERSION_PREFIX: &str = "# codewandler-connector-secrets file store, v";
95const VERSION: &str = "1";
96
97/// Maximum encoded bytes accepted from or written to one durable store.
98///
99/// The entire v1 store is intentionally held in memory for atomic whole-file replacement, so a
100/// bound is part of the format's operational contract rather than a transport detail.
101pub const MAX_FILE_BYTES: usize = 1024 * 1024;
102
103/// Maximum number of credential entries accepted in one durable store.
104pub const MAX_ENTRIES: usize = 4096;
105
106/// Maximum UTF-8 bytes accepted for one credential value.
107pub const MAX_VALUE_BYTES: usize = 64 * 1024;
108
109#[cfg(unix)]
110/// The mode a store file is created with, and the widest mode one may be opened at.
111pub const FILE_MODE: u32 = 0o600;
112
113#[cfg(unix)]
114/// The mode the containing directory is created with, and the widest it may be opened at.
115pub const DIR_MODE: u32 = 0o700;
116
117/// Distinguishes one process's in-flight temporary files from another's.
118static NEXT_TEMPORARY: AtomicU64 = AtomicU64::new(0);
119
120/// A [`SecretStore`] kept in one file.
121///
122/// See the [module documentation](self) for what protects the values in it and what does not — the
123/// short answer is the current OS identity plus native owner-only filesystem controls, and nothing
124/// cryptographic.
125///
126pub struct FileStore<L = TenantLayout> {
127    layout: L,
128    path: PathBuf,
129    // The whole store, held in memory and written through on every mutation. `BTreeMap` so the file
130    // is sorted and a diff between two versions of it is readable — and so `paths()` is ordered, the
131    // same property `MemoryStore` offers.
132    entries: Mutex<BTreeMap<String, Secret>>,
133    transactions: Mutex<prepared::FileTransactions>,
134    // The kernel releases this non-blocking exclusive lease if the process exits abruptly.
135    _lease: File,
136    #[cfg(test)]
137    fail_next_write: std::sync::atomic::AtomicBool,
138}
139
140impl<L> Drop for FileStore<L> {
141    fn drop(&mut self) {
142        // Closing the descriptor releases a kernel lock, including after abrupt process exit. The
143        // explicit unlock makes ordinary in-process reopen deterministic before field destruction
144        // completes and is deliberately best effort during Drop.
145        let _ = fs2::FileExt::unlock(&self._lease);
146    }
147}
148
149impl FileStore<TenantLayout> {
150    /// Open — or create — the store at `path`, using the blessed [`TenantLayout`].
151    ///
152    /// On Unix the containing directory is created at `0700` and the file at `0600`. On Windows
153    /// both are created for the process `TokenUser` SID with a protected DACL allowing only that
154    /// SID. Existing state with a foreign owner, wider access, a link/reparse point, the wrong kind
155    /// or uninspectable metadata is **refused**, never tightened or repaired: it may already have
156    /// exposed values, and changing it silently would hide that evidence.
157    ///
158    /// # Errors
159    ///
160    /// [`StoreError::Unreachable`] for an IO or security-inspection failure,
161    /// [`StoreError::Denied`] for native protection this store will not use, and
162    /// [`StoreError::Backend`] for a file it cannot parse. Every one names the filesystem path and
163    /// none carries a value.
164    pub fn open(path: impl Into<PathBuf>) -> Result<Self, StoreError> {
165        Self::open_with_layout(path, TenantLayout)
166    }
167}
168
169impl<L: Layout> FileStore<L> {
170    /// Open — or create — the store at `path`, rendering addresses through `layout`.
171    ///
172    /// # Errors
173    ///
174    /// As [`FileStore::open`].
175    pub fn open_with_layout(path: impl Into<PathBuf>, layout: L) -> Result<Self, StoreError> {
176        let path = path.into();
177
178        if let Some(directory) = path
179            .parent()
180            .filter(|parent| !parent.as_os_str().is_empty())
181        {
182            platform::ensure_directory(directory)?;
183        }
184
185        let lease_path = fixed_sibling(&path, "lease");
186        let lease = platform::open_lease(&lease_path, &path)?;
187        lease
188            .try_lock_exclusive()
189            .map_err(|_| StoreError::Conflict {
190                path: path.display().to_string(),
191                reason: "another FileStore holds the writer/recovery lease".to_owned(),
192            })?;
193
194        let (entries, mut transactions, existed) = match platform::open_existing(&path)? {
195            Some(mut file) => {
196                let contents = read_bounded(&mut file, &path)?;
197                if contents.lines().next() == Some(prepared::HEADER_V2) {
198                    let (entries, transactions) = prepared::parse_v2(&contents, &layout, &path)?;
199                    (entries, transactions, true)
200                } else {
201                    (
202                        parse(&contents, &layout, &path)?,
203                        prepared::FileTransactions::default(),
204                        true,
205                    )
206                }
207            }
208            None => (
209                BTreeMap::new(),
210                prepared::FileTransactions::default(),
211                false,
212            ),
213        };
214
215        recover_stage(&path, &layout, &mut transactions)?;
216
217        let store = Self {
218            layout,
219            path,
220            entries: Mutex::new(entries),
221            transactions: Mutex::new(transactions),
222            _lease: lease,
223            #[cfg(test)]
224            fail_next_write: std::sync::atomic::AtomicBool::new(false),
225        };
226
227        // Written eagerly so that "the store exists, with the right mode" is true after `open`
228        // rather than after the first `put`. An operator who is told where their credentials live
229        // should find something there, and a test asserting the mode should not have to store a
230        // credential first to have something to assert about.
231        if !existed {
232            store.write_through(&store.locked())?;
233        }
234
235        store.reap_temporaries();
236
237        Ok(store)
238    }
239
240    /// Remove any temporary left behind by a write that did not finish.
241    ///
242    /// **A crash between the write and the `rename(2)` leaves a `0600` file holding a complete copy
243    /// of every credential**, under a name nothing else looks at. Without this, `rm <store>` — the
244    /// revocation this store documents — would leave the tokens on disk beside the file the operator
245    /// just deleted, which makes the documented revocation wrong rather than merely incomplete.
246    ///
247    /// Reaped at `open` rather than at write, because the only writer that can leave one behind is a
248    /// process that is no longer running: [`write_through`](Self::write_through) removes its own on
249    /// failure, and there is exactly one in flight at a time. That reasoning depends on the
250    /// single-process rule this module states; a second concurrent host would have its in-flight
251    /// temporary removed under it, and would report the write as failed rather than lose data.
252    ///
253    /// Best effort throughout. A temporary that cannot be read or removed is not a reason to refuse
254    /// to open a store that is otherwise sound — the credentials are the point, and the leftover is
255    /// reported by [`stale_temporaries`](Self::stale_temporaries) for a caller that wants to look.
256    fn reap_temporaries(&self) {
257        for leftover in self.stale_temporaries() {
258            let _ = std::fs::remove_file(leftover);
259        }
260    }
261
262    /// Every unfinished temporary sitting beside this store, in no particular order.
263    ///
264    /// Public so the reaping above is observable rather than merely asserted — a test can plant one,
265    /// see it listed, open the store and see the list empty.
266    pub fn stale_temporaries(&self) -> Vec<PathBuf> {
267        let (Some(directory), Some(name)) = (self.path.parent(), self.path.file_name()) else {
268            return Vec::new();
269        };
270        let (prefix, suffix) = (format!(".{}.", name.to_string_lossy()), ".tmp");
271        let Ok(entries) = std::fs::read_dir(directory) else {
272            return Vec::new();
273        };
274        entries
275            .filter_map(Result::ok)
276            .map(|entry| entry.path())
277            .filter(|path| {
278                path.file_name()
279                    .and_then(|name| name.to_str())
280                    .is_some_and(|name| name.starts_with(&prefix) && name.ends_with(suffix))
281            })
282            .collect()
283    }
284
285    /// The file this store is kept in.
286    pub fn path(&self) -> &Path {
287        &self.path
288    }
289
290    /// The layout this store renders through.
291    pub fn layout(&self) -> &L {
292        &self.layout
293    }
294
295    /// The path `reference` resolves to under this store's layout.
296    ///
297    /// The *address*, not the file — the same question [`MemoryStore::path`](crate::MemoryStore)
298    /// answers.
299    pub fn address(&self, reference: &CredentialRef) -> String {
300        self.layout.render(reference)
301    }
302
303    /// The address a rendered path resolves back to — the inverse of [`address`](Self::address).
304    ///
305    /// # Errors
306    ///
307    /// [`StoreError::Layout`], carrying the layout's own explanation, when the path is not one this
308    /// layout writes.
309    pub fn reference(&self, path: &str) -> Result<CredentialRef, StoreError> {
310        self.layout
311            .parse(path)
312            .map_err(|reason| StoreError::Layout { reason })
313    }
314
315    /// Every address currently holding a value, in order. Values are deliberately not exposed.
316    pub fn paths(&self) -> Vec<String> {
317        self.locked().keys().cloned().collect()
318    }
319
320    /// How many values are held.
321    pub fn len(&self) -> usize {
322        self.locked().len()
323    }
324
325    /// Whether the store holds nothing.
326    pub fn is_empty(&self) -> bool {
327        self.len() == 0
328    }
329
330    #[cfg(test)]
331    fn inject_write_failure(&self) {
332        self.fail_next_write.store(true, Ordering::SeqCst);
333    }
334
335    /// The map, with a poisoned lock recovered rather than propagated — as [`MemoryStore`].
336    ///
337    /// [`MemoryStore`]: crate::MemoryStore
338    fn locked(&self) -> std::sync::MutexGuard<'_, BTreeMap<String, Secret>> {
339        self.entries.lock().unwrap_or_else(|poisoned| {
340            self.entries.clear_poison();
341            poisoned.into_inner()
342        })
343    }
344
345    fn locked_transactions(&self) -> std::sync::MutexGuard<'_, prepared::FileTransactions> {
346        self.transactions.lock().unwrap_or_else(|poisoned| {
347            self.transactions.clear_poison();
348            poisoned.into_inner()
349        })
350    }
351
352    /// Rewrite the whole file, atomically.
353    ///
354    /// **Atomic by the platform replacement primitive**, which is the only way to get it: a file
355    /// opened for truncation is observably empty between the truncate and the write, and a crash in
356    /// that window loses every credential rather than the one being written. The new contents go to
357    /// a fresh owner-only sibling, are flushed, and then replace the old file in one step. A reader
358    /// sees the whole previous version or the whole new one.
359    ///
360    /// The temporary lives in the **same directory** deliberately — replacement is atomic only
361    /// within one filesystem/volume, and a temporary in a global scratch directory could be on
362    /// another one. It is also created with `create_new`, so this never writes through a name
363    /// somebody else placed there.
364    fn write_through(&self, entries: &BTreeMap<String, Secret>) -> Result<(), StoreError> {
365        let encoded_size =
366            validate_candidate_bounds(entries).map_err(|reason| StoreError::Backend {
367                path: self.path.display().to_string(),
368                reason,
369            })?;
370        let mut rendered = String::with_capacity(encoded_size);
371        rendered.push_str(HEADER);
372        rendered.push('\n');
373        for (address, secret) in entries {
374            rendered.push_str(address);
375            rendered.push(' ');
376            rendered.push_str(&hex_encode(secret.expose_secret().as_bytes()));
377            rendered.push('\n');
378        }
379        self.write_rendered_to(&self.path, &rendered, false)
380    }
381
382    fn write_live(
383        &self,
384        entries: &BTreeMap<String, Secret>,
385        transactions: &prepared::FileTransactions,
386    ) -> Result<(), StoreError> {
387        if transactions.version_two {
388            let rendered = prepared::encode_v2(entries, transactions).map_err(|reason| {
389                StoreError::Backend {
390                    path: self.path.display().to_string(),
391                    reason,
392                }
393            })?;
394            self.write_rendered_to(&self.path, &rendered, false)
395        } else {
396            self.write_through(entries)
397        }
398    }
399
400    fn write_rendered_to(
401        &self,
402        destination: &Path,
403        rendered: &str,
404        require_directory_sync: bool,
405    ) -> Result<(), StoreError> {
406        let directory = self
407            .path
408            .parent()
409            .filter(|parent| !parent.as_os_str().is_empty())
410            .unwrap_or_else(|| Path::new("."));
411        let temporary = directory.join(format!(
412            ".{}.{}.{}.tmp",
413            destination
414                .file_name()
415                .and_then(|name| name.to_str())
416                .unwrap_or("credentials"),
417            std::process::id(),
418            NEXT_TEMPORARY.fetch_add(1, Ordering::Relaxed)
419        ));
420
421        platform::ensure_directory(directory)?;
422        // Refuse a destination widened or replaced after this store was opened before candidate
423        // bytes are even rendered, much less written to a temporary. `replace` repeats the check
424        // immediately before the atomic operation to cover the intervening race.
425        platform::validate_destination(destination)?;
426        let result =
427            self.write_temporary(&temporary, destination, rendered, require_directory_sync);
428        if result.is_err() {
429            // Best effort: the write already failed, and a failure to clean up after it is not the
430            // error worth reporting.
431            let _ = std::fs::remove_file(&temporary);
432        }
433        result
434    }
435
436    /// The fallible half of [`write_through`](Self::write_through), split out so the caller has one
437    /// place to clean up from.
438    fn write_temporary(
439        &self,
440        temporary: &Path,
441        destination: &Path,
442        rendered: &str,
443        require_directory_sync: bool,
444    ) -> Result<(), StoreError> {
445        let mut file = platform::create_new(temporary, &self.path)?;
446        crash_failpoint(destination, &self.path, "create");
447        file.write_all(rendered.as_bytes())
448            .map_err(|error| unreachable(&self.path, &error))?;
449        crash_failpoint(destination, &self.path, "write");
450        // Without this the rename can land before the bytes do, and a power cut leaves a file that
451        // is present, correctly named, and empty.
452        platform::flush(&file, &self.path)?;
453        crash_failpoint(destination, &self.path, "flush");
454        drop(file);
455
456        #[cfg(test)]
457        if self.fail_next_write.swap(false, Ordering::SeqCst) {
458            return Err(StoreError::Unreachable {
459                path: self.path.display().to_string(),
460                reason: "injected failure before atomic replacement".to_owned(),
461            });
462        }
463
464        platform::replace(temporary, destination)?;
465        crash_failpoint(destination, &self.path, "replace");
466
467        // The rename itself is a directory operation, so durability of *it* needs the directory
468        // flushed. Prepared transactions require that proof before acknowledging a transition. The
469        // pre-existing point-write contract keeps its best-effort behaviour because an error after
470        // replacement would make its in-memory rollback disagree with the durable file.
471        if let Some(directory) = temporary.parent() {
472            let synced = platform::sync_directory(directory);
473            if require_directory_sync {
474                synced?;
475            }
476        }
477        crash_failpoint(destination, &self.path, "directory-sync");
478
479        Ok(())
480    }
481}
482
483pub(crate) fn validate_candidate_bounds(
484    entries: &BTreeMap<String, Secret>,
485) -> Result<usize, String> {
486    if entries.len() > MAX_ENTRIES {
487        return Err(format!(
488            "the store would contain {} entries, exceeding the {MAX_ENTRIES}-entry limit",
489            entries.len()
490        ));
491    }
492    if entries
493        .values()
494        .any(|secret| secret.expose_secret().len() > MAX_VALUE_BYTES)
495    {
496        return Err(format!(
497            "a credential value exceeds the {MAX_VALUE_BYTES}-byte value limit; the value and its \
498             address are omitted"
499        ));
500    }
501    let encoded_size = entries
502        .iter()
503        .try_fold(HEADER.len() + 1, |size, (address, secret)| {
504            let value_len = secret.expose_secret().len();
505            size.checked_add(address.len())?
506                .checked_add(1)?
507                .checked_add(value_len.checked_mul(2)?)?
508                .checked_add(1)
509        });
510    encoded_size
511        .filter(|size| *size <= MAX_FILE_BYTES)
512        .ok_or_else(|| {
513            format!(
514                "the encoded store would exceed the {MAX_FILE_BYTES}-byte limit; refusing the whole \
515                 mutation rather than allocating or writing a partial file"
516            )
517        })
518}
519
520pub(crate) fn validate_transactional_bounds(
521    entries: &BTreeMap<String, Secret>,
522    terminal_records_after_decision: usize,
523) -> Result<(), String> {
524    let credential_bytes = validate_candidate_bounds(entries)?;
525    // The committed form is the longest record grammar. Reserve one full line per terminal record,
526    // plus the prepared record that successful prepare must be able to turn into a terminal without
527    // discovering capacity after the coordinator's decision.
528    const MAX_TRANSACTION_LINE_BYTES: usize = 160;
529    let ledger_bytes = terminal_records_after_decision
530        .checked_mul(MAX_TRANSACTION_LINE_BYTES)
531        .and_then(|size| size.checked_add(prepared::HEADER_V2.len() + 1 + 36))
532        .ok_or_else(|| "the transaction ledger size overflowed".to_owned())?;
533    credential_bytes
534        .checked_add(ledger_bytes)
535        .filter(|size| *size <= MAX_FILE_BYTES)
536        .map(|_| ())
537        .ok_or_else(|| format!("the encoded store would exceed the {MAX_FILE_BYTES}-byte limit"))
538}
539
540#[async_trait]
541impl<L: Layout + Send + Sync> SecretStore for FileStore<L> {
542    async fn get(&self, reference: &CredentialRef) -> Result<Secret, StoreError> {
543        let path = self.layout.render(reference);
544        self.locked()
545            .get(&path)
546            .cloned()
547            .ok_or(StoreError::NotFound { path })
548    }
549
550    async fn put(&self, reference: &CredentialRef, secret: &Secret) -> Result<(), StoreError> {
551        let address = self.layout.render(reference);
552        let transactions = self.locked_transactions();
553        if transactions.prepared().is_some() {
554            return Err(prepared_conflict(&self.path));
555        }
556        let mut entries = self.locked();
557        let replaced = entries.insert(address.clone(), secret.clone());
558        // Write while still holding the lock, so two concurrent writers cannot interleave a map
559        // mutation with the other's file rewrite and persist a state neither of them held.
560        if let Err(error) = self.write_live(&entries, &transactions) {
561            // The file is the store. A value that reached the map but not the disk would be
562            // resolvable until the next restart and gone after it, which is a worse failure than
563            // refusing — so the map is put back the way it was and the caller is told.
564            match replaced {
565                Some(previous) => entries.insert(address, previous),
566                None => entries.remove(&address),
567            };
568            return Err(error);
569        }
570        Ok(())
571    }
572
573    async fn delete(&self, reference: &CredentialRef) -> Result<(), StoreError> {
574        let address = self.layout.render(reference);
575        let transactions = self.locked_transactions();
576        if transactions.prepared().is_some() {
577            return Err(prepared_conflict(&self.path));
578        }
579        let mut entries = self.locked();
580        // Idempotent, per the trait.
581        let Some(previous) = entries.remove(&address) else {
582            return Ok(());
583        };
584        if let Err(error) = self.write_live(&entries, &transactions) {
585            entries.insert(address, previous);
586            return Err(error);
587        }
588        Ok(())
589    }
590
591    async fn references(&self, scope: &CredentialScope) -> Result<Vec<CredentialRef>, StoreError> {
592        self.locked()
593            .keys()
594            .map(|path| {
595                self.layout
596                    .parse(path)
597                    .map_err(|reason| StoreError::Layout { reason })
598            })
599            .filter_map(|result| match result {
600                Ok(reference) if scope.contains(&reference) => Some(Ok(reference)),
601                Ok(_) => None,
602                Err(error) => Some(Err(error)),
603            })
604            .collect()
605    }
606
607    async fn apply(&self, mutations: &SecretBatch) -> Result<(), StoreError> {
608        let transactions = self.locked_transactions();
609        if transactions.prepared().is_some() {
610            return Err(prepared_conflict(&self.path));
611        }
612        let mut entries = self.locked();
613        let mut candidate = entries.clone();
614        batch::apply_to(&mut candidate, &self.layout, mutations)?;
615        // Persist the complete candidate before changing the in-process view. A write failure leaves
616        // both representations at the old state, matching the point methods' rollback guarantee.
617        self.write_live(&candidate, &transactions)?;
618        *entries = candidate;
619        Ok(())
620    }
621}
622
623/// Path and entry count. **Never a value, and never an address** — a derived `Debug` would print
624/// every key, and C-159 is this repository's precedent for a derived rendering becoming the leak.
625impl<L> fmt::Debug for FileStore<L> {
626    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
627        formatter.write_str("FileStore(<opaque>)")
628    }
629}
630
631/// An IO failure, as a [`StoreError`].
632///
633/// `std::io::Error`'s own message names an errno and, for the calls used here, nothing else. It
634/// never carries file contents, so this cannot carry a value — which is why the reason is passed
635/// through rather than flattened to "an IO error".
636pub(super) fn unreachable(path: &Path, error: &std::io::Error) -> StoreError {
637    StoreError::Unreachable {
638        path: path.display().to_string(),
639        reason: error.to_string(),
640    }
641}
642
643fn prepared_conflict(path: &Path) -> StoreError {
644    StoreError::Conflict {
645        path: path.display().to_string(),
646        reason: "a prepared secret transaction owns the mutation slot".to_owned(),
647    }
648}
649
650fn fixed_sibling(store: &Path, suffix: &str) -> PathBuf {
651    let directory = store
652        .parent()
653        .filter(|parent| !parent.as_os_str().is_empty())
654        .unwrap_or_else(|| Path::new("."));
655    let name = store
656        .file_name()
657        .and_then(|name| name.to_str())
658        .unwrap_or("credentials");
659    directory.join(format!(".{name}.{suffix}"))
660}
661
662fn remove_fixed(path: &Path, store: &Path) -> Result<(), StoreError> {
663    let Some(file) = platform::open_existing(path)? else {
664        return Ok(());
665    };
666    drop(file);
667    std::fs::remove_file(path).map_err(|error| unreachable(store, &error))?;
668    if let Some(directory) = path.parent() {
669        platform::sync_directory(directory)?;
670    }
671    crash_failpoint(path, store, "cleanup");
672    Ok(())
673}
674
675#[cfg(test)]
676fn crash_failpoint(destination: &Path, store: &Path, boundary: &str) {
677    let target = if destination == fixed_sibling(store, "prepared") {
678        "stage"
679    } else {
680        "live"
681    };
682    let expected = format!("{target}:{boundary}");
683    if std::env::var("CONNECTOR_SECRETS_CRASH_AT").ok().as_deref() == Some(expected.as_str()) {
684        std::process::abort();
685    }
686}
687
688#[cfg(not(test))]
689fn crash_failpoint(_destination: &Path, _store: &Path, _boundary: &str) {}
690
691fn recover_stage<L: Layout>(
692    store: &Path,
693    layout: &L,
694    live: &mut prepared::FileTransactions,
695) -> Result<(), StoreError> {
696    let stage_path = fixed_sibling(store, "prepared");
697    let Some(mut stage_file) = platform::open_existing(&stage_path)? else {
698        if live.prepared().is_some() {
699            return Err(StoreError::Backend {
700                path: store.display().to_string(),
701                reason: "the live store is prepared but its complete fixed stage is absent"
702                    .to_owned(),
703            });
704        }
705        return Ok(());
706    };
707    let stage_contents = read_bounded(&mut stage_file, &stage_path)?;
708    let (stage_entries, stage) = prepared::parse_v2(&stage_contents, layout, &stage_path)?;
709    if stage.prepared().is_some() || stage.retired_through != live.retired_through {
710        return Err(StoreError::Backend {
711            path: store.display().to_string(),
712            reason: "the fixed stage does not match the live transaction ledger".to_owned(),
713        });
714    }
715
716    if let Some((id, digest)) = live.prepared() {
717        let mut expected = live.records.clone();
718        expected.insert(id.key(), prepared::FileRecord::Committed(digest));
719        if stage.records != expected {
720            return Err(StoreError::Backend {
721                path: store.display().to_string(),
722                reason: "the fixed stage does not match the live prepared record".to_owned(),
723            });
724        }
725        live.candidate = Some(prepared::Candidate {
726            id,
727            digest,
728            entries: stage_entries,
729        });
730        return Ok(());
731    }
732
733    let mut differing = stage
734        .records
735        .keys()
736        .chain(live.records.keys())
737        .copied()
738        .collect::<std::collections::BTreeSet<_>>();
739    differing.retain(|id| stage.records.get(id) != live.records.get(id));
740    let differing = differing.into_iter().collect::<Vec<_>>();
741    let cleanup_only = match differing.as_slice() {
742        [] => true,
743        [id] => matches!(
744            (stage.records.get(id), live.records.get(id)),
745            (
746                Some(prepared::FileRecord::Committed(_)),
747                None | Some(prepared::FileRecord::Aborted)
748            )
749        ),
750        _ => false,
751    };
752    if !cleanup_only {
753        return Err(StoreError::Backend {
754            path: store.display().to_string(),
755            reason:
756                "the leftover fixed stage has no unambiguous recovery relation to the live store"
757                    .to_owned(),
758        });
759    }
760    remove_fixed(&stage_path, store)
761}
762
763fn read_bounded(file: &mut File, path: &Path) -> Result<String, StoreError> {
764    let length = file
765        .metadata()
766        .map_err(|error| unreachable(path, &error))?
767        .len();
768    if length > MAX_FILE_BYTES as u64 {
769        return Err(StoreError::Backend {
770            path: path.display().to_string(),
771            reason: format!(
772                "the store is {length} bytes, exceeding the {MAX_FILE_BYTES}-byte limit; contents \
773                 were not read"
774            ),
775        });
776    }
777
778    let mut bytes = Vec::with_capacity(length as usize);
779    file.take(MAX_FILE_BYTES as u64 + 1)
780        .read_to_end(&mut bytes)
781        .map_err(|error| unreachable(path, &error))?;
782    if bytes.len() > MAX_FILE_BYTES {
783        return Err(StoreError::Backend {
784            path: path.display().to_string(),
785            reason: format!(
786                "the store grew beyond the {MAX_FILE_BYTES}-byte limit while it was being read; \
787                 contents were refused"
788            ),
789        });
790    }
791    String::from_utf8(bytes).map_err(|_| StoreError::Backend {
792        path: path.display().to_string(),
793        reason: "the store is not UTF-8".to_owned(),
794    })
795}
796
797/// Read a whole store file into a map, refusing anything it cannot account for.
798///
799/// **Nothing is skipped.** A line this cannot read is a credential this store would silently stop
800/// resolving, and "the connector is not connected" is the wrong answer to "the file is damaged" for
801/// exactly the reason [`StoreError::NotFound`] and [`StoreError::Unreachable`] are different types.
802///
803/// No message below quotes a value or any part of one — a hex field that failed to decode is
804/// reported by its line number and its length, never its content.
805fn parse<L: Layout>(
806    contents: &str,
807    layout: &L,
808    file: &Path,
809) -> Result<BTreeMap<String, Secret>, StoreError> {
810    let mut entries = BTreeMap::new();
811    for (index, line) in contents.lines().enumerate() {
812        let number = index + 1;
813        let line = line.trim();
814
815        // **The version is read, not skipped.** It sits behind a `#` so an operator sees a comment,
816        // but a comment nothing checks would let a future format load as this one.
817        if let Some(version) = line.strip_prefix(VERSION_PREFIX) {
818            if version != VERSION {
819                return Err(StoreError::Backend {
820                    path: file.display().to_string(),
821                    reason: format!(
822                        "line {number}: this file says it is version {version:?} and this build \
823                         speaks version {VERSION:?}. Refusing rather than reading it as {VERSION:?} \
824                         — a credential store that guesses at a format it does not know hands back \
825                         a wrong value instead of an error."
826                    ),
827                });
828            }
829            continue;
830        }
831
832        if line.is_empty() || line.starts_with('#') {
833            continue;
834        }
835
836        let bad = |reason: String| StoreError::Backend {
837            path: file.display().to_string(),
838            reason: format!("line {number}: {reason}"),
839        };
840
841        let (address, encoded) = line
842            .split_once(' ')
843            .ok_or_else(|| bad("expected `<address> <hex>`, and there is no space".to_owned()))?;
844
845        if encoded.len() > MAX_VALUE_BYTES * 2 {
846            return Err(bad(format!(
847                "the encoded value is {} characters, exceeding the {}-byte decoded-value limit",
848                encoded.len(),
849                MAX_VALUE_BYTES
850            )));
851        }
852
853        // The address must be one this layout writes, and must be spelled the way this layout
854        // spells it. Both halves matter: the first is what keeps a hand-edited file from inventing
855        // a tenant, and the second is what keeps one credential from having two entries.
856        let reference = layout.parse(address).map_err(&bad)?;
857        let canonical = layout.render(&reference);
858        if canonical != address {
859            return Err(bad(format!(
860                "{address:?} is not how this layout spells the address it names ({canonical:?}), \
861                 so one credential would have two entries"
862            )));
863        }
864
865        let value = hex_decode(encoded).ok_or_else(|| {
866            bad(format!(
867                "the value field is {} characters and is not valid hex",
868                encoded.len()
869            ))
870        })?;
871        let value = String::from_utf8(value)
872            .map_err(|_| bad("the value does not decode to UTF-8".to_owned()))?;
873
874        if entries.insert(canonical, Secret::new(value)).is_some() {
875            return Err(bad(format!(
876                "{address:?} appears more than once, and nothing here can say which is current"
877            )));
878        }
879        if entries.len() > MAX_ENTRIES {
880            return Err(bad(format!(
881                "the store contains more than the {MAX_ENTRIES}-entry limit"
882            )));
883        }
884    }
885    Ok(entries)
886}
887
888/// Lowercase hex. **Framing, not protection** — see the module documentation.
889fn hex_encode(bytes: &[u8]) -> String {
890    use fmt::Write as _;
891    let mut out = String::with_capacity(bytes.len() * 2);
892    for byte in bytes {
893        // Infallible: writing to a `String` cannot fail.
894        let _ = write!(out, "{byte:02x}");
895    }
896    out
897}
898
899/// The inverse of [`hex_encode`], or `None` for anything that is not lowercase-or-uppercase hex of
900/// even length.
901fn hex_decode(encoded: &str) -> Option<Vec<u8>> {
902    if !encoded.len().is_multiple_of(2) {
903        return None;
904    }
905    let bytes = encoded.as_bytes();
906    let mut out = Vec::with_capacity(bytes.len() / 2);
907    for pair in bytes.chunks_exact(2) {
908        let high = (pair[0] as char).to_digit(16)?;
909        let low = (pair[1] as char).to_digit(16)?;
910        out.push((high * 16 + low) as u8);
911    }
912    Some(out)
913}
914
915#[cfg(all(test, unix))]
916mod tests {
917    use super::*;
918    use std::os::unix::fs::{MetadataExt as _, PermissionsExt as _};
919
920    /// Obviously not a credential, and long enough that a redactor would hold it.
921    const SENTINEL: &str = "SENTINEL-NOT-A-REAL-SECRET-file-store";
922
923    /// A directory of this test's own, removed when the guard drops.
924    struct Scratch(PathBuf);
925
926    impl Scratch {
927        fn new(label: &str) -> Self {
928            static NEXT: AtomicU64 = AtomicU64::new(0);
929            let path = std::env::temp_dir().join(format!(
930                "connector-secrets-{label}-{}-{}",
931                std::process::id(),
932                NEXT.fetch_add(1, Ordering::Relaxed)
933            ));
934            let _ = std::fs::remove_dir_all(&path);
935            Self(path)
936        }
937
938        /// The store file inside it — one directory level down, so directory creation is exercised.
939        fn store(&self) -> PathBuf {
940            self.0.join("store").join("credentials")
941        }
942    }
943
944    impl Drop for Scratch {
945        fn drop(&mut self) {
946            let _ = std::fs::remove_dir_all(&self.0);
947        }
948    }
949
950    fn reference() -> CredentialRef {
951        CredentialRef::new("9f3a4b2c", "com.zendesk.api", "support", "api_token").expect("valid")
952    }
953
954    #[tokio::test]
955    async fn an_atomic_move_survives_reopen_as_one_state() {
956        let scratch = Scratch::new("batch-move");
957        let path = scratch.store();
958        let source = reference();
959        let destination = CredentialRef::for_instance(
960            "9f3a4b2c",
961            "com.zendesk.api",
962            "0d3f79ae-b6df-4f77-8f77-438436c3b2ef",
963            "support",
964            "api_token",
965        )
966        .expect("valid instance address");
967        let store = FileStore::open(&path).expect("open");
968        store
969            .put(&source, &Secret::new(SENTINEL))
970            .await
971            .expect("put");
972        let scope = CredentialScope::new("9f3a4b2c", "com.zendesk.api").expect("scope");
973        let mut batch = SecretBatch::new(scope.clone());
974        batch
975            .move_secret(source.clone(), destination.clone())
976            .expect("in scope");
977        store.apply(&batch).await.expect("atomic move");
978        drop(store);
979
980        let reopened = FileStore::open(&path).expect("reopen");
981        assert!(reopened.get(&source).await.unwrap_err().is_not_found());
982        assert_eq!(
983            reopened
984                .get(&destination)
985                .await
986                .expect("destination")
987                .expose_secret(),
988            SENTINEL
989        );
990        assert_eq!(
991            reopened.references(&scope).await.expect("inventory"),
992            vec![destination]
993        );
994    }
995
996    fn mode_of(path: &Path) -> u32 {
997        std::fs::metadata(path)
998            .expect("it exists")
999            .permissions()
1000            .mode()
1001            & 0o777
1002    }
1003
1004    /// **The point of the type.** A value stored through one instance is readable through the next
1005    /// one built over the same file.
1006    #[tokio::test]
1007    async fn a_value_survives_the_store_being_dropped_and_reopened() {
1008        let scratch = Scratch::new("round-trip");
1009        let path = scratch.store();
1010
1011        {
1012            let store = FileStore::open(&path).expect("open");
1013            store
1014                .put(&reference(), &Secret::new(SENTINEL))
1015                .await
1016                .expect("put");
1017        }
1018
1019        let reopened = FileStore::open(&path).expect("reopen");
1020        assert_eq!(
1021            reopened
1022                .get(&reference())
1023                .await
1024                .expect("get")
1025                .expose_secret(),
1026            SENTINEL
1027        );
1028
1029        reopened.delete(&reference()).await.expect("delete");
1030        drop(reopened);
1031        let again = FileStore::open(&path).expect("reopen");
1032        assert!(again.get(&reference()).await.unwrap_err().is_not_found());
1033    }
1034
1035    /// **The full address round-trips, not merely the value.**
1036    ///
1037    /// Two tenants of one vendor and two services of one vendor are the two ways a store keyed
1038    /// loosely collides — the first would undo C-204's per-account tenancy and the second C-219's
1039    /// per-service addressing, and both would do it silently, by handing back *a* credential.
1040    #[tokio::test]
1041    async fn nothing_collides_across_tenants_or_across_services_of_one_vendor() {
1042        let scratch = Scratch::new("addressing");
1043        let path = scratch.store();
1044
1045        let addresses = [
1046            ("tenant-a", "com.zendesk.api", "support", "api_token"),
1047            ("tenant-b", "com.zendesk.api", "support", "api_token"),
1048            ("tenant-a", "com.contentful.api", "delivery", "api_token"),
1049            ("tenant-a", "com.contentful.api", "management", "api_token"),
1050            ("tenant-a", "com.anthropic.api", "default", "api_key"),
1051        ];
1052
1053        {
1054            let store = FileStore::open(&path).expect("open");
1055            for (tenant, authority, service, credential) in addresses {
1056                let reference = CredentialRef::new(tenant, authority, service, credential)
1057                    .expect("a valid address");
1058                store
1059                    .put(
1060                        &reference,
1061                        &Secret::new(format!("{SENTINEL}/{tenant}/{authority}/{service}")),
1062                    )
1063                    .await
1064                    .expect("put");
1065            }
1066            assert_eq!(store.len(), addresses.len(), "two addresses collided");
1067        }
1068
1069        let reopened = FileStore::open(&path).expect("reopen");
1070        assert_eq!(reopened.len(), addresses.len(), "the reload lost an entry");
1071        for (tenant, authority, service, credential) in addresses {
1072            let reference =
1073                CredentialRef::new(tenant, authority, service, credential).expect("valid");
1074            assert_eq!(
1075                reopened.get(&reference).await.expect("get").expose_secret(),
1076                format!("{SENTINEL}/{tenant}/{authority}/{service}"),
1077                "{tenant}/{authority}/{service} came back with another address's value"
1078            );
1079        }
1080    }
1081
1082    /// `0600` and `0700`, on a store that has only just been created.
1083    #[test]
1084    fn a_fresh_store_is_0600_inside_a_0700_directory() {
1085        let scratch = Scratch::new("modes");
1086        let path = scratch.store();
1087        let store = FileStore::open(&path).expect("open");
1088
1089        assert!(path.exists(), "`open` did not create the file");
1090        assert_eq!(
1091            mode_of(store.path()),
1092            FILE_MODE,
1093            "the store file is not 0600"
1094        );
1095        assert_eq!(
1096            mode_of(path.parent().expect("a parent")),
1097            DIR_MODE,
1098            "the containing directory is not 0700"
1099        );
1100    }
1101
1102    /// A file somebody else can read is refused rather than repaired.
1103    #[test]
1104    fn a_world_readable_store_is_refused() {
1105        let scratch = Scratch::new("mode-refusal");
1106        let path = scratch.store();
1107        drop(FileStore::open(&path).expect("open"));
1108        std::fs::write(
1109            &path,
1110            format!(
1111                "{HEADER}\ntenants/9f3a4b2c/com.zendesk.api/support/api_token {}\n",
1112                hex_encode(SENTINEL.as_bytes())
1113            ),
1114        )
1115        .expect("plant a real entry");
1116        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).expect("loosen it");
1117        let before = std::fs::read(&path).expect("prior bytes");
1118
1119        let error = FileStore::open(&path).expect_err("a 0644 store must be refused");
1120        assert!(
1121            matches!(error, StoreError::Denied { .. }),
1122            "expected a refusal, got {error:?}"
1123        );
1124        assert!(
1125            error.to_string().contains("0644"),
1126            "the refusal must say what the mode is: {error}"
1127        );
1128        assert!(!error.to_string().contains(SENTINEL));
1129        assert!(!error.to_string().contains("com.zendesk.api"));
1130        assert_eq!(std::fs::read(&path).expect("bytes remain"), before);
1131        assert_eq!(
1132            mode_of(&path),
1133            0o644,
1134            "the store tightened the mode instead of reporting it"
1135        );
1136    }
1137
1138    /// **A directory somebody else can enter is refused too**, on the same reasoning as the file.
1139    ///
1140    /// Separate from the file case because they are separate calls: deleting the directory leg of
1141    /// [`ensure_directory`] left every file-mode assertion green, so `0700` was a behaviour nothing
1142    /// observed.
1143    #[test]
1144    fn a_world_readable_directory_is_refused() {
1145        let scratch = Scratch::new("dir-mode-refusal");
1146        let path = scratch.store();
1147        drop(FileStore::open(&path).expect("open"));
1148        std::fs::write(
1149            &path,
1150            format!(
1151                "{HEADER}\ntenants/9f3a4b2c/com.zendesk.api/support/api_token {}\n",
1152                hex_encode(SENTINEL.as_bytes())
1153            ),
1154        )
1155        .expect("plant a real entry");
1156        let directory = path.parent().expect("a parent").to_owned();
1157        std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o755))
1158            .expect("loosen it");
1159
1160        let error = FileStore::open(&path).expect_err("a 0755 directory must be refused");
1161
1162        let unsafe_mode = mode_of(&directory);
1163        let bytes = std::fs::read(&path).expect("prior bytes");
1164
1165        assert_eq!(unsafe_mode, 0o755, "refusal repaired the directory");
1166        assert_eq!(std::fs::read(&path).expect("bytes remain"), bytes);
1167        assert!(!error.to_string().contains(SENTINEL));
1168        assert!(!error.to_string().contains("com.zendesk.api"));
1169
1170        // Restored after evidence so a failure still leaves a removable directory.
1171        std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(DIR_MODE))
1172            .expect("restore");
1173
1174        assert!(
1175            matches!(error, StoreError::Denied { .. }),
1176            "expected a refusal, got {error:?}"
1177        );
1178        assert!(
1179            error.to_string().contains("0755"),
1180            "the refusal must say what the mode is: {error}"
1181        );
1182    }
1183
1184    /// A store directly beneath a shared parent is still unsafe, but the operator must never be
1185    /// told to narrow that shared parent for every other user of the machine.
1186    #[test]
1187    fn a_shared_parent_refusal_recommends_an_owner_only_child_not_chmodding_the_parent() {
1188        use std::os::unix::fs::MetadataExt as _;
1189
1190        // `std::env::temp_dir()` is a genuinely shared 01777 directory on Linux, but on macOS it
1191        // normally resolves to a private per-user directory. Construct the unsafe direct parent so
1192        // this test proves the security predicate instead of assuming a platform's temp layout.
1193        let scratch = Scratch::new("shared-parent-refusal");
1194        let parent = scratch.0.join("shared");
1195        std::fs::create_dir_all(&parent).expect("create deliberately shared parent");
1196        std::fs::set_permissions(&parent, std::fs::Permissions::from_mode(0o777))
1197            .expect("make the direct parent non-owner-only");
1198        let path = parent.join("credentials.store");
1199        let before = std::fs::symlink_metadata(&parent).expect("inspect shared parent");
1200        let snapshot = (
1201            before.mode(),
1202            before.uid(),
1203            before.gid(),
1204            before.dev(),
1205            before.ino(),
1206        );
1207
1208        let error = FileStore::open(&path).expect_err("a shared direct parent must be refused");
1209        let message = error.to_string();
1210        assert!(message.contains(&parent.display().to_string()), "{message}");
1211        assert!(message.contains("owner-only child"), "{message}");
1212        assert!(message.contains("per-user state"), "{message}");
1213        assert!(!message.contains("chmod 700"), "{message}");
1214        assert!(!message.contains("com.zendesk.api"), "{message}");
1215        assert!(!message.contains(SENTINEL), "{message}");
1216        assert!(!path.exists(), "a refusal must not create the store");
1217
1218        let after = std::fs::symlink_metadata(&parent).expect("reinspect shared parent");
1219        assert_eq!(
1220            snapshot,
1221            (
1222                after.mode(),
1223                after.uid(),
1224                after.gid(),
1225                after.dev(),
1226                after.ino(),
1227            ),
1228            "refusal changed the shared parent's security metadata"
1229        );
1230    }
1231
1232    #[test]
1233    fn an_oversized_store_is_refused_before_its_contents_are_parsed() {
1234        const EXPECTED_LIMIT: usize = 1024 * 1024;
1235
1236        let scratch = Scratch::new("bounded-read");
1237        let path = scratch.store();
1238        drop(FileStore::open(&path).expect("open"));
1239        std::fs::write(&path, format!("#{}", "x".repeat(EXPECTED_LIMIT)))
1240            .expect("plant an oversized store");
1241
1242        let error = FileStore::open(&path).expect_err("an oversized store must be refused");
1243        let message = error.to_string();
1244        assert!(
1245            message.contains("1048576"),
1246            "the bound must be named: {message}"
1247        );
1248        assert!(message.contains(&path.display().to_string()), "{message}");
1249        assert!(
1250            !message.contains(&"x".repeat(64)),
1251            "contents leaked: {message}"
1252        );
1253    }
1254
1255    /// **A temporary left by a crash is reaped**, because `rm <store>` must actually revoke.
1256    ///
1257    /// A write that dies between the `write_all` and the `rename(2)` leaves a `0600` file holding a
1258    /// complete copy of every credential under a name nothing looks at. An operator who then deletes
1259    /// the store believes they have revoked; the tokens are still on disk beside it.
1260    #[test]
1261    fn a_temporary_left_by_a_crash_is_reaped_on_the_next_open() {
1262        let scratch = Scratch::new("reap");
1263        let path = scratch.store();
1264        drop(FileStore::open(&path).expect("open"));
1265
1266        // What a crash between `write_all` and `rename` leaves: the temporary's real name shape,
1267        // holding a real entry.
1268        let orphan = path.parent().expect("a parent").join(format!(
1269            ".{}.999999.0.tmp",
1270            path.file_name().expect("a name").to_string_lossy()
1271        ));
1272        std::fs::write(
1273            &orphan,
1274            format!(
1275                "{HEADER}\ntenants/a/com.acme.api/token {}\n",
1276                hex_encode(SENTINEL.as_bytes())
1277            ),
1278        )
1279        .expect("plant the orphan");
1280        assert!(orphan.exists());
1281
1282        let store = FileStore::open(&path).expect("reopen");
1283
1284        assert!(
1285            !orphan.exists(),
1286            "a crashed write's temporary survived the next open, so `rm {}` would leave a full \
1287             copy of every credential beside the file the operator deleted",
1288            path.display()
1289        );
1290        assert!(
1291            store.stale_temporaries().is_empty(),
1292            "the store still reports leftovers after reaping them"
1293        );
1294    }
1295
1296    /// A file from a format this build does not speak is refused, not read as this one.
1297    #[test]
1298    fn a_file_from_another_version_is_refused() {
1299        let scratch = Scratch::new("version");
1300        let path = scratch.store();
1301        drop(FileStore::open(&path).expect("open"));
1302        std::fs::write(
1303            &path,
1304            format!(
1305                "{VERSION_PREFIX}3\ntenants/a/com.acme.api/token {}\n",
1306                hex_encode(SENTINEL.as_bytes())
1307            ),
1308        )
1309        .expect("write a v3 file");
1310
1311        let error = FileStore::open(&path).expect_err("a v3 file must not load as v1 or v2");
1312        let message = error.to_string();
1313        assert!(matches!(error, StoreError::Backend { .. }), "{error:?}");
1314        assert!(
1315            message.contains("\"3\""),
1316            "the refusal must name it: {message}"
1317        );
1318        assert!(!message.contains(SENTINEL));
1319
1320        // And the version this build does write is the one it accepts, so the check above cannot be
1321        // satisfied by refusing everything.
1322        std::fs::write(&path, format!("{HEADER}\n")).expect("write a v1 file");
1323        assert!(FileStore::open(&path).is_ok(), "a v1 file must still load");
1324    }
1325
1326    /// **The three legs of the atomic write, audited over this file's own source.**
1327    ///
1328    /// Each of `create_new`, the temporary's `sync_all` and the directory `fsync` can be deleted
1329    /// with the whole suite staying green — they are durability and anti-clobber properties, and a
1330    /// single-threaded test on a working filesystem cannot observe any of them. That is exactly the
1331    /// case this repository already handles by reading its own source
1332    /// (`Secret::every_exit_from_the_wrapper_is_named_expose_secret`), so the same instrument is
1333    /// used here rather than leaving three deletions undefended.
1334    ///
1335    /// It asserts over the write path only, and it fails loudly if it stops matching anything, so it
1336    /// cannot quietly become an assertion about nothing.
1337    #[test]
1338    fn the_write_path_keeps_all_three_legs_of_its_atomicity() {
1339        let unix = include_str!("file/unix.rs");
1340        let windows = include_str!("file/windows.rs");
1341        for (source, fragment, why) in [
1342            (
1343                unix,
1344                "OFlags::CREATE | OFlags::EXCL",
1345                "Unix must create a fresh temporary",
1346            ),
1347            (
1348                unix,
1349                "OFlags::NOFOLLOW",
1350                "Unix must not follow a planted temporary",
1351            ),
1352            (
1353                unix,
1354                "file.sync_all()",
1355                "Unix must flush bytes before rename",
1356            ),
1357            (unix, "std::fs::rename", "Unix replacement must be atomic"),
1358            (
1359                windows,
1360                "CREATE_NEW",
1361                "Windows must create a fresh temporary",
1362            ),
1363            (
1364                windows,
1365                "FlushFileBuffers",
1366                "Windows must flush bytes before replacement",
1367            ),
1368            (
1369                windows,
1370                "ReplaceFileW",
1371                "Windows existing-target replacement must be atomic",
1372            ),
1373            (
1374                windows,
1375                "MoveFileExW",
1376                "Windows first install must be same-directory atomic",
1377            ),
1378        ] {
1379            assert!(
1380                source.contains(fragment),
1381                "the atomic write no longer contains `{fragment}` — {why}. If this was deliberate, \
1382                 the module documentation and this test both have to say so."
1383            );
1384        }
1385    }
1386
1387    /// **A reader never observes a partial store while a writer is rewriting it.**
1388    ///
1389    /// The behavioural half of the audit above, and the assertion
1390    /// `a_write_leaves_no_temporary_and_no_truncated_file` only appeared to make: that test opened
1391    /// the store *after* the writes finished, so a truncate-then-write implementation left it green
1392    /// and the truncation window in its name went unobserved. This one reads while the writes are
1393    /// happening.
1394    ///
1395    /// It can only fail in one direction. Under `rename(2)` every observation is a whole file, so
1396    /// the assertion holds for every interleaving; under truncate-then-write a reader eventually
1397    /// lands in the window and sees a store that is empty, short, or unparseable.
1398    #[test]
1399    fn a_concurrent_reader_never_sees_a_half_written_store() {
1400        let scratch = Scratch::new("torn-read");
1401        let path = scratch.store();
1402        let store = FileStore::open(&path).expect("open");
1403
1404        // Ten entries, so a torn read is a visibly short file rather than an ambiguous one.
1405        let runtime = tokio::runtime::Builder::new_current_thread()
1406            .build()
1407            .expect("a runtime");
1408        for index in 0..10 {
1409            let reference = CredentialRef::new(
1410                format!("tenant-{index}").as_str(),
1411                "com.acme.api",
1412                "default",
1413                "token",
1414            )
1415            .expect("valid");
1416            runtime
1417                .block_on(store.put(&reference, &Secret::new(format!("{SENTINEL}-{index}"))))
1418                .expect("put");
1419        }
1420
1421        let stop = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
1422        let reader = {
1423            let (path, stop) = (path.clone(), std::sync::Arc::clone(&stop));
1424            std::thread::spawn(move || {
1425                let mut observations = 0usize;
1426                while !stop.load(Ordering::Relaxed) {
1427                    // **The bytes, not `FileStore::open`.** Opening a store reaps stale
1428                    // temporaries, and a reader that did that would delete the writer's in-flight
1429                    // one — which is the single-process rule this module states, demonstrated the
1430                    // hard way when this test was first written that way. Reading the file directly
1431                    // is also the truer question: atomicity is a property of what is on disk, not of
1432                    // what a second `FileStore` makes of it.
1433                    let seen = match std::fs::read_to_string(&path) {
1434                        Ok(contents) => contents,
1435                        // `rename(2)` never unlinks the destination, so the path is never absent.
1436                        Err(error) => panic!("a reader could not read the store: {error}"),
1437                    };
1438                    let lines: Vec<&str> = seen
1439                        .lines()
1440                        .filter(|line| !line.trim().is_empty() && !line.starts_with('#'))
1441                        .collect();
1442
1443                    // The writer only ever *replaces* one of the ten values below, so a whole file
1444                    // always has a header and exactly ten entries. Anything else was caught in a
1445                    // truncation window.
1446                    assert!(
1447                        seen.starts_with(HEADER),
1448                        "a reader saw a file that does not begin with the header, so it caught the \
1449                         store mid-write"
1450                    );
1451                    assert_eq!(
1452                        lines.len(),
1453                        10,
1454                        "a reader saw {} entries rather than 10, so it caught the store mid-write",
1455                        lines.len()
1456                    );
1457                    observations += 1;
1458                }
1459                observations
1460            })
1461        };
1462
1463        let target =
1464            CredentialRef::new("tenant-0", "com.acme.api", "default", "token").expect("valid");
1465        for index in 0..300 {
1466            runtime
1467                .block_on(store.put(&target, &Secret::new(format!("{SENTINEL}-rewrite-{index}"))))
1468                .expect("put");
1469        }
1470        stop.store(true, Ordering::Relaxed);
1471
1472        let observations = reader.join().expect("the reader thread did not panic");
1473        assert!(
1474            observations > 0,
1475            "the reader never managed to open the store, so it asserted nothing"
1476        );
1477    }
1478
1479    /// A rewrite leaves no temporary behind, and the file is whole at every point a reader could
1480    /// look at it.
1481    #[tokio::test]
1482    async fn a_write_leaves_no_temporary_and_no_truncated_file() {
1483        let scratch = Scratch::new("atomic");
1484        let path = scratch.store();
1485        let store = FileStore::open(&path).expect("open");
1486
1487        for index in 0..8 {
1488            let reference = CredentialRef::new(
1489                format!("tenant-{index}").as_str(),
1490                "com.acme.api",
1491                "default",
1492                "token",
1493            )
1494            .expect("valid");
1495            store
1496                .put(&reference, &Secret::new(format!("{SENTINEL}-{index}")))
1497                .await
1498                .expect("put");
1499        }
1500
1501        let leftovers: Vec<String> = std::fs::read_dir(path.parent().expect("a parent"))
1502            .expect("read the directory")
1503            .filter_map(Result::ok)
1504            .map(|entry| entry.file_name().to_string_lossy().into_owned())
1505            .filter(|name| name != "credentials" && name != ".credentials.lease")
1506            .collect();
1507        assert!(
1508            leftovers.is_empty(),
1509            "the directory holds files the store did not mean to leave: {leftovers:?}"
1510        );
1511        drop(store);
1512        assert_eq!(FileStore::open(&path).expect("reopen").len(), 8);
1513    }
1514
1515    /// A file this store cannot account for is an error, never a quietly emptier store.
1516    ///
1517    /// Silently skipping a line it could not read would report the tenant as *not connected*, which
1518    /// is precisely the confusion [`StoreError::NotFound`] and [`StoreError::Unreachable`] are two
1519    /// types in order to avoid — and it would invite the operator to paste the token again.
1520    #[test]
1521    fn a_damaged_file_is_refused_rather_than_partly_loaded() {
1522        for (label, contents) in [
1523            ("no separator", "tenants/a/com.acme.api/token\n"),
1524            ("bad hex", "tenants/a/com.acme.api/token zzzz\n"),
1525            ("odd hex", "tenants/a/com.acme.api/token abc\n"),
1526            ("not an address", "wherever/a/token 4141\n"),
1527            (
1528                "the elided service spelled out",
1529                "tenants/a/com.acme.api/default/token 4141\n",
1530            ),
1531            (
1532                "the same address twice",
1533                "tenants/a/com.acme.api/token 4141\ntenants/a/com.acme.api/token 4242\n",
1534            ),
1535        ] {
1536            let scratch = Scratch::new("damaged");
1537            let path = scratch.store();
1538            drop(FileStore::open(&path).expect("open"));
1539            std::fs::write(&path, contents).expect("write the damaged file");
1540
1541            let error = FileStore::open(&path)
1542                .err()
1543                .unwrap_or_else(|| panic!("a store with {label} was loaded rather than refused"));
1544            assert!(
1545                matches!(error, StoreError::Backend { .. }),
1546                "{label}: expected a `Backend` refusal, got {error:?}"
1547            );
1548        }
1549    }
1550
1551    /// Nothing a damaged file produces quotes the bytes it could not read.
1552    #[test]
1553    fn a_parse_failure_names_the_line_and_never_the_value() {
1554        let scratch = Scratch::new("parse-message");
1555        let path = scratch.store();
1556        drop(FileStore::open(&path).expect("open"));
1557        std::fs::write(
1558            &path,
1559            format!(
1560                "{HEADER}\ntenants/a/com.acme.api/token {}!!\n",
1561                hex_encode(SENTINEL.as_bytes())
1562            ),
1563        )
1564        .expect("write");
1565
1566        let error = FileStore::open(&path).expect_err("invalid hex must be refused");
1567        let message = error.to_string();
1568        assert!(matches!(error, StoreError::Backend { .. }), "{error:?}");
1569        assert!(message.contains("line 2"), "no line number: {message}");
1570        assert!(
1571            !message.contains(&hex_encode(SENTINEL.as_bytes())),
1572            "the message quoted the undecodable field: {message}"
1573        );
1574        assert!(!message.contains(SENTINEL), "the message quoted a value");
1575    }
1576
1577    /// The `Debug` rendering, which is the one C-159 warns about.
1578    #[tokio::test]
1579    async fn debug_carries_neither_a_value_nor_an_address() {
1580        let scratch = Scratch::new("debug");
1581        let store = FileStore::open(scratch.store()).expect("open");
1582        store
1583            .put(&reference(), &Secret::new(SENTINEL))
1584            .await
1585            .expect("put");
1586
1587        let rendered = format!("{store:?}");
1588        assert!(!rendered.contains(SENTINEL), "Debug served a value");
1589        assert!(
1590            !rendered.contains("com.zendesk.api"),
1591            "Debug served an address: {rendered}"
1592        );
1593    }
1594
1595    /// Neither does the error a failed write produces. The failure is manufactured by making the
1596    /// directory unwritable, which is the closest thing to a full disk a test can arrange.
1597    #[tokio::test]
1598    async fn a_write_failure_names_no_value() {
1599        let scratch = Scratch::new("write-failure");
1600        let path = scratch.store();
1601        let store = FileStore::open(&path).expect("open");
1602        let directory = path.parent().expect("a parent").to_owned();
1603        std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(0o500))
1604            .expect("make it read-only");
1605
1606        let error = store
1607            .put(&reference(), &Secret::new(SENTINEL))
1608            .await
1609            .expect_err("a read-only directory must refuse a write");
1610
1611        // Restored before the assertions so a failure still cleans up.
1612        std::fs::set_permissions(&directory, std::fs::Permissions::from_mode(DIR_MODE))
1613            .expect("restore");
1614
1615        let message = error.to_string();
1616        assert!(
1617            !message.contains(SENTINEL),
1618            "the write error quoted the value"
1619        );
1620        assert!(
1621            message.contains("credentials"),
1622            "the write error should name the file: {message}"
1623        );
1624        // And the value did not half-land: the map was rolled back with the file.
1625        assert!(store.get(&reference()).await.unwrap_err().is_not_found());
1626    }
1627
1628    #[test]
1629    fn a_store_symlink_is_refused_without_reading_or_changing_either_object() {
1630        use std::os::unix::fs::symlink;
1631
1632        let scratch = Scratch::new("store-symlink");
1633        let real = scratch.store();
1634        drop(FileStore::open(&real).expect("open real store"));
1635        std::fs::write(
1636            &real,
1637            format!(
1638                "{HEADER}\ntenants/9f3a4b2c/com.zendesk.api/support/api_token {}\n",
1639                hex_encode(SENTINEL.as_bytes())
1640            ),
1641        )
1642        .expect("plant target");
1643        let link = real.parent().expect("parent").join("linked-credentials");
1644        symlink(&real, &link).expect("plant symlink");
1645        let before_link = std::fs::symlink_metadata(&link).expect("link metadata");
1646        let before_target = std::fs::read(&real).expect("target bytes");
1647
1648        let error = FileStore::open(&link).expect_err("a symlink must be refused");
1649        let message = error.to_string();
1650        assert!(message.contains(&link.display().to_string()), "{message}");
1651        assert!(!message.contains(SENTINEL), "{message}");
1652        assert_eq!(std::fs::read(&real).expect("target remains"), before_target);
1653        let after_link = std::fs::symlink_metadata(&link).expect("link remains");
1654        assert_eq!(before_link.ino(), after_link.ino());
1655        assert_eq!(before_link.mode(), after_link.mode());
1656    }
1657
1658    #[test]
1659    fn a_directory_symlink_is_refused_without_changing_it() {
1660        use std::os::unix::fs::symlink;
1661
1662        let scratch = Scratch::new("directory-symlink");
1663        let real = scratch.0.join("real-state");
1664        drop(FileStore::open(real.join("credentials")).expect("create real directory"));
1665        let link = scratch.0.join("linked-state");
1666        symlink(&real, &link).expect("plant directory symlink");
1667        let before = std::fs::symlink_metadata(&link).expect("link metadata");
1668
1669        let path = link.join("credentials");
1670        let error = FileStore::open(&path).expect_err("a directory symlink must be refused");
1671        let message = error.to_string();
1672        assert!(message.contains(&link.display().to_string()), "{message}");
1673        assert!(!message.contains(SENTINEL), "{message}");
1674        let after = std::fs::symlink_metadata(&link).expect("link remains");
1675        assert_eq!(before.ino(), after.ino());
1676        assert_eq!(before.mode(), after.mode());
1677    }
1678
1679    #[test]
1680    fn wrong_object_kinds_are_refused_without_repair() {
1681        let scratch = Scratch::new("wrong-kinds");
1682        let store_as_directory = scratch.store();
1683        std::fs::create_dir_all(store_as_directory.parent().expect("parent")).expect("parents");
1684        std::fs::set_permissions(
1685            store_as_directory.parent().expect("parent"),
1686            std::fs::Permissions::from_mode(DIR_MODE),
1687        )
1688        .expect("secure parent");
1689        std::fs::create_dir(&store_as_directory).expect("directory at store path");
1690        let before = std::fs::symlink_metadata(&store_as_directory).expect("metadata");
1691        let error =
1692            FileStore::open(&store_as_directory).expect_err("directory is not a store file");
1693        assert!(matches!(error, StoreError::Denied { .. }), "{error:?}");
1694        let after = std::fs::symlink_metadata(&store_as_directory).expect("metadata remains");
1695        assert_eq!((before.ino(), before.mode()), (after.ino(), after.mode()));
1696
1697        let file_as_directory = scratch.0.join("plain-file");
1698        std::fs::write(&file_as_directory, b"not a directory").expect("plant file");
1699        std::fs::set_permissions(
1700            &file_as_directory,
1701            std::fs::Permissions::from_mode(FILE_MODE),
1702        )
1703        .expect("secure file");
1704        let before = std::fs::symlink_metadata(&file_as_directory).expect("metadata");
1705        let path = file_as_directory.join("credentials");
1706        let error = FileStore::open(&path).expect_err("file is not a state directory");
1707        assert!(matches!(error, StoreError::Denied { .. }), "{error:?}");
1708        let after = std::fs::symlink_metadata(&file_as_directory).expect("metadata remains");
1709        assert_eq!((before.ino(), before.mode()), (after.ino(), after.mode()));
1710    }
1711
1712    #[cfg(target_os = "linux")]
1713    #[test]
1714    fn a_fifo_swap_is_refused_without_blocking_or_reading() {
1715        let scratch = Scratch::new("fifo");
1716        let path = scratch.store();
1717        std::fs::create_dir_all(path.parent().expect("parent")).expect("parent");
1718        std::fs::set_permissions(
1719            path.parent().expect("parent"),
1720            std::fs::Permissions::from_mode(DIR_MODE),
1721        )
1722        .expect("secure parent");
1723        rustix::fs::mkfifoat(
1724            rustix::fs::CWD,
1725            &path,
1726            rustix::fs::Mode::from_raw_mode(FILE_MODE),
1727        )
1728        .expect("plant fifo");
1729        let before = std::fs::symlink_metadata(&path).expect("fifo metadata");
1730
1731        let error = FileStore::open(&path).expect_err("fifo must be refused without opening it");
1732        assert!(matches!(error, StoreError::Denied { .. }), "{error:?}");
1733        let after = std::fs::symlink_metadata(&path).expect("fifo remains");
1734        assert_eq!((before.ino(), before.mode()), (after.ino(), after.mode()));
1735    }
1736
1737    #[test]
1738    fn an_unopenable_store_is_refused_without_reading_or_repair() {
1739        let scratch = Scratch::new("unopenable");
1740        let path = scratch.store();
1741        drop(FileStore::open(&path).expect("open"));
1742        std::fs::write(
1743            &path,
1744            format!(
1745                "{HEADER}\ntenants/9f3a4b2c/com.zendesk.api/support/api_token {}\n",
1746                hex_encode(SENTINEL.as_bytes())
1747            ),
1748        )
1749        .expect("plant a real entry");
1750        let bytes = std::fs::read(&path).expect("prior bytes");
1751        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o000))
1752            .expect("make unopenable");
1753        let before = std::fs::symlink_metadata(&path).expect("metadata");
1754
1755        let error = FileStore::open(&path).expect_err("unopenable metadata handle must refuse");
1756        let message = error.to_string();
1757        assert!(!message.contains(SENTINEL), "{message}");
1758        assert!(!message.contains("com.zendesk.api"), "{message}");
1759        let after = std::fs::symlink_metadata(&path).expect("metadata remains");
1760        assert_eq!((before.uid(), before.mode()), (after.uid(), after.mode()));
1761
1762        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(FILE_MODE))
1763            .expect("restore for cleanup");
1764        assert_eq!(std::fs::read(&path).expect("bytes remain"), bytes);
1765    }
1766
1767    #[tokio::test]
1768    async fn mutations_revalidate_widened_directory_and_file_before_writing_a_temporary() {
1769        for widen_directory in [false, true] {
1770            let scratch = Scratch::new(if widen_directory {
1771                "mutated-directory"
1772            } else {
1773                "mutated-file"
1774            });
1775            let path = scratch.store();
1776            let store = FileStore::open(&path).expect("open");
1777            store
1778                .put(&reference(), &Secret::new(SENTINEL))
1779                .await
1780                .expect("plant prior value");
1781            let before = std::fs::read(&path).expect("prior file");
1782            let widened = if widen_directory {
1783                path.parent().expect("parent")
1784            } else {
1785                path.as_path()
1786            };
1787            let mode = if widen_directory { 0o755 } else { 0o644 };
1788            std::fs::set_permissions(widened, std::fs::Permissions::from_mode(mode))
1789                .expect("widen");
1790
1791            let other = CredentialRef::new("tenant-b", "com.zendesk.api", "support", "api_token")
1792                .expect("other reference");
1793            let error = store
1794                .put(&other, &Secret::new(format!("{SENTINEL}-new")))
1795                .await
1796                .expect_err("widened metadata must refuse mutation");
1797            let message = error.to_string();
1798            assert!(!message.contains(SENTINEL), "{message}");
1799            assert!(!message.contains("com.zendesk.api"), "{message}");
1800            assert_eq!(std::fs::read(&path).expect("prior file remains"), before);
1801            assert!(store.stale_temporaries().is_empty());
1802            assert_eq!(mode_of(widened), mode, "refusal repaired unsafe metadata");
1803
1804            std::fs::set_permissions(
1805                widened,
1806                std::fs::Permissions::from_mode(if widen_directory { DIR_MODE } else { FILE_MODE }),
1807            )
1808            .expect("restore");
1809        }
1810    }
1811
1812    #[test]
1813    #[ignore = "requires euid 0 to plant a foreign-owned file; CI invokes it explicitly with sudo"]
1814    fn a_foreign_owned_store_is_refused_without_repair() {
1815        assert_eq!(
1816            rustix::process::geteuid().as_raw(),
1817            0,
1818            "this ignored fixture requires euid 0"
1819        );
1820        let scratch = Scratch::new("foreign-owned-store");
1821        let path = scratch.store();
1822        drop(FileStore::open(&path).expect("open as root"));
1823        std::fs::write(
1824            &path,
1825            format!(
1826                "{HEADER}\ntenants/9f3a4b2c/com.zendesk.api/support/api_token {}\n",
1827                hex_encode(SENTINEL.as_bytes())
1828            ),
1829        )
1830        .expect("plant a real entry");
1831        let bytes = std::fs::read(&path).expect("prior bytes");
1832        rustix::fs::chown(&path, Some(rustix::process::Uid::from_raw(65534)), None)
1833            .expect("plant foreign owner");
1834        let before = std::fs::symlink_metadata(&path).expect("metadata");
1835
1836        let error = FileStore::open(&path).expect_err("foreign owner must be refused");
1837        let message = error.to_string();
1838        assert!(message.contains(&path.display().to_string()), "{message}");
1839        assert!(!message.contains(SENTINEL), "{message}");
1840        assert!(!message.contains("com.zendesk.api"), "{message}");
1841        assert_eq!(std::fs::read(&path).expect("bytes remain"), bytes);
1842        let after = std::fs::symlink_metadata(&path).expect("metadata remains");
1843        assert_eq!((before.uid(), before.mode()), (after.uid(), after.mode()));
1844    }
1845
1846    #[test]
1847    #[ignore = "requires euid 0 to plant a foreign-owned directory; CI invokes it explicitly with sudo"]
1848    fn a_foreign_owned_directory_is_refused_without_repair() {
1849        assert_eq!(
1850            rustix::process::geteuid().as_raw(),
1851            0,
1852            "this ignored fixture requires euid 0"
1853        );
1854        let scratch = Scratch::new("foreign-owned-directory");
1855        let path = scratch.store();
1856        drop(FileStore::open(&path).expect("open as root"));
1857        std::fs::write(
1858            &path,
1859            format!(
1860                "{HEADER}\ntenants/9f3a4b2c/com.zendesk.api/support/api_token {}\n",
1861                hex_encode(SENTINEL.as_bytes())
1862            ),
1863        )
1864        .expect("plant a real entry");
1865        let bytes = std::fs::read(&path).expect("prior bytes");
1866        let directory = path.parent().expect("parent");
1867        rustix::fs::chown(directory, Some(rustix::process::Uid::from_raw(65534)), None)
1868            .expect("plant foreign owner");
1869        let before = std::fs::symlink_metadata(directory).expect("metadata");
1870
1871        let error = FileStore::open(&path).expect_err("foreign owner must be refused");
1872        let message = error.to_string();
1873        assert!(
1874            message.contains(&directory.display().to_string()),
1875            "{message}"
1876        );
1877        assert!(!message.contains(SENTINEL), "{message}");
1878        assert!(!message.contains("com.zendesk.api"), "{message}");
1879        assert_eq!(std::fs::read(&path).expect("bytes remain"), bytes);
1880        let after = std::fs::symlink_metadata(directory).expect("metadata remains");
1881        assert_eq!((before.uid(), before.mode()), (after.uid(), after.mode()));
1882    }
1883
1884    /// Usable through the trait object, which is how a host binds it.
1885    #[tokio::test]
1886    async fn the_store_is_object_safe() {
1887        let scratch = Scratch::new("object-safe");
1888        let store: std::sync::Arc<dyn SecretStore> =
1889            std::sync::Arc::new(FileStore::open(scratch.store()).expect("open"));
1890        store
1891            .put(&reference(), &Secret::new(SENTINEL))
1892            .await
1893            .expect("put");
1894        assert_eq!(
1895            store.get(&reference()).await.expect("get").expose_secret(),
1896            SENTINEL
1897        );
1898    }
1899
1900    #[test]
1901    fn hex_round_trips_every_byte() {
1902        let bytes: Vec<u8> = (0..=255).collect();
1903        assert_eq!(hex_decode(&hex_encode(&bytes)).as_deref(), Some(&bytes[..]));
1904        assert_eq!(hex_decode("abc"), None, "odd length");
1905        assert_eq!(hex_decode("zz"), None, "not hex");
1906        assert_eq!(hex_decode("AA"), Some(vec![0xaa]), "uppercase is read");
1907    }
1908}
1909
1910#[cfg(test)]
1911mod portable_tests {
1912    use super::*;
1913
1914    const SENTINEL: &str = "SENTINEL-NOT-A-REAL-SECRET-portable-file-store";
1915
1916    struct Scratch(PathBuf);
1917
1918    impl Scratch {
1919        fn new(label: &str) -> Self {
1920            static NEXT: AtomicU64 = AtomicU64::new(0);
1921            let path = std::env::temp_dir().join(format!(
1922                "connector-secrets-portable-{label}-{}-{}",
1923                std::process::id(),
1924                NEXT.fetch_add(1, Ordering::Relaxed)
1925            ));
1926            let _ = std::fs::remove_dir_all(&path);
1927            Self(path)
1928        }
1929
1930        fn store(&self) -> PathBuf {
1931            self.0.join("state").join("credentials")
1932        }
1933    }
1934
1935    impl Drop for Scratch {
1936        fn drop(&mut self) {
1937            let _ = std::fs::remove_dir_all(&self.0);
1938        }
1939    }
1940
1941    fn reference(instance: Option<&str>, leaf: &str) -> CredentialRef {
1942        match instance {
1943            Some(instance) => {
1944                CredentialRef::for_instance("tenant-a", "com.acme.api", instance, "default", leaf)
1945            }
1946            None => CredentialRef::new("tenant-a", "com.acme.api", "default", leaf),
1947        }
1948        .expect("valid reference")
1949    }
1950
1951    #[tokio::test]
1952    async fn a_multi_credential_connection_migration_survives_restart() {
1953        let scratch = Scratch::new("migration-restart");
1954        let path = scratch.store();
1955        let first_instance = "0d3f79ae-b6df-4f77-8f77-438436c3b2ef";
1956        let second_instance = "b183db27-ec61-4d47-9783-4db28c82f4f8";
1957        let legacy_token = reference(None, "token");
1958        let legacy_signing = reference(None, "signing_secret");
1959        let first_token = reference(Some(first_instance), "token");
1960        let first_signing = reference(Some(first_instance), "signing_secret");
1961        let second_token = reference(Some(second_instance), "token");
1962        let second_signing = reference(Some(second_instance), "signing_secret");
1963
1964        let store = FileStore::open(&path).expect("open");
1965        store
1966            .put(
1967                &legacy_token,
1968                &Secret::new(format!("{SENTINEL}-first-token")),
1969            )
1970            .await
1971            .expect("put first token");
1972        store
1973            .put(
1974                &legacy_signing,
1975                &Secret::new(format!("{SENTINEL}-first-signing")),
1976            )
1977            .await
1978            .expect("put first signing secret");
1979
1980        let scope = CredentialScope::new("tenant-a", "com.acme.api").expect("scope");
1981        let mut migration = SecretBatch::new(scope.clone());
1982        migration
1983            .move_secret(legacy_token.clone(), first_token.clone())
1984            .expect("move first token");
1985        migration
1986            .move_secret(legacy_signing.clone(), first_signing.clone())
1987            .expect("move first signing secret");
1988        migration
1989            .put(
1990                second_token.clone(),
1991                Secret::new(format!("{SENTINEL}-second-token")),
1992            )
1993            .expect("put second token");
1994        migration
1995            .put(
1996                second_signing.clone(),
1997                Secret::new(format!("{SENTINEL}-second-signing")),
1998            )
1999            .expect("put second signing secret");
2000        store.apply(&migration).await.expect("atomic migration");
2001        drop(store);
2002
2003        let restarted = FileStore::open(&path).expect("restart");
2004        assert!(restarted
2005            .get(&legacy_token)
2006            .await
2007            .unwrap_err()
2008            .is_not_found());
2009        assert!(restarted
2010            .get(&legacy_signing)
2011            .await
2012            .unwrap_err()
2013            .is_not_found());
2014        assert_eq!(
2015            restarted.references(&scope).await.expect("references"),
2016            vec![
2017                first_signing.clone(),
2018                first_token.clone(),
2019                second_signing.clone(),
2020                second_token.clone(),
2021            ]
2022        );
2023        for (at, expected) in [
2024            (first_token, format!("{SENTINEL}-first-token")),
2025            (first_signing, format!("{SENTINEL}-first-signing")),
2026            (second_token, format!("{SENTINEL}-second-token")),
2027            (second_signing, format!("{SENTINEL}-second-signing")),
2028        ] {
2029            assert_eq!(
2030                restarted
2031                    .get(&at)
2032                    .await
2033                    .expect("migrated value")
2034                    .expose_secret(),
2035                expected
2036            );
2037        }
2038    }
2039
2040    #[tokio::test]
2041    async fn an_injected_write_failure_preserves_the_prior_file_and_batch() {
2042        let scratch = Scratch::new("injected-batch-failure");
2043        let path = scratch.store();
2044        let source = reference(None, "token");
2045        let untouched = reference(None, "signing_secret");
2046        let destination = reference(Some("0d3f79ae-b6df-4f77-8f77-438436c3b2ef"), "token");
2047        let planted = reference(Some("b183db27-ec61-4d47-9783-4db28c82f4f8"), "token");
2048        let store = FileStore::open(&path).expect("open");
2049        store
2050            .put(&source, &Secret::new(format!("{SENTINEL}-source")))
2051            .await
2052            .expect("put source");
2053        store
2054            .put(&untouched, &Secret::new(format!("{SENTINEL}-untouched")))
2055            .await
2056            .expect("put untouched");
2057        let before = std::fs::read(&path).expect("prior file");
2058
2059        let scope = CredentialScope::new("tenant-a", "com.acme.api").expect("scope");
2060        let mut batch = SecretBatch::new(scope);
2061        batch
2062            .move_secret(source.clone(), destination.clone())
2063            .expect("move");
2064        batch
2065            .put(planted.clone(), Secret::new(format!("{SENTINEL}-new")))
2066            .expect("put");
2067        store.inject_write_failure();
2068        let error = store
2069            .apply(&batch)
2070            .await
2071            .expect_err("injected failure must refuse the batch");
2072        let message = error.to_string();
2073        assert!(message.contains(&path.display().to_string()), "{message}");
2074        assert!(!message.contains(SENTINEL), "{message}");
2075        assert!(!message.contains("com.acme.api"), "{message}");
2076        assert_eq!(std::fs::read(&path).expect("prior file remains"), before);
2077        assert_eq!(
2078            store
2079                .get(&source)
2080                .await
2081                .expect("source remains")
2082                .expose_secret(),
2083            format!("{SENTINEL}-source")
2084        );
2085        assert!(store.get(&destination).await.unwrap_err().is_not_found());
2086        assert!(store.get(&planted).await.unwrap_err().is_not_found());
2087        assert!(store.stale_temporaries().is_empty());
2088        drop(store);
2089
2090        let restarted = FileStore::open(&path).expect("restart after failure");
2091        assert_eq!(std::fs::read(&path).expect("whole prior file"), before);
2092        assert_eq!(
2093            restarted
2094                .get(&source)
2095                .await
2096                .expect("source after restart")
2097                .expose_secret(),
2098            format!("{SENTINEL}-source")
2099        );
2100        assert!(restarted
2101            .get(&destination)
2102            .await
2103            .unwrap_err()
2104            .is_not_found());
2105        assert!(restarted.get(&planted).await.unwrap_err().is_not_found());
2106    }
2107
2108    #[tokio::test]
2109    async fn bounded_writes_refuse_before_allocating_or_changing_the_prior_file() {
2110        let scratch = Scratch::new("bounded-write");
2111        let path = scratch.store();
2112        let store = FileStore::open(&path).expect("open");
2113        let before = std::fs::read(&path).expect("prior file");
2114        let error = store
2115            .put(
2116                &reference(None, "token"),
2117                &Secret::new("x".repeat(MAX_VALUE_BYTES + 1)),
2118            )
2119            .await
2120            .expect_err("oversized value must be refused");
2121        let message = error.to_string();
2122        assert!(message.contains(&MAX_VALUE_BYTES.to_string()), "{message}");
2123        assert!(message.contains(&path.display().to_string()), "{message}");
2124        assert!(!message.contains(&"x".repeat(64)), "{message}");
2125        assert!(!message.contains("com.acme.api"), "{message}");
2126        assert_eq!(std::fs::read(&path).expect("prior file remains"), before);
2127        assert!(store.is_empty());
2128        assert!(store.stale_temporaries().is_empty());
2129    }
2130
2131    #[test]
2132    fn bounded_reads_use_metadata_and_a_same_handle_max_plus_one_read() {
2133        let scratch = Scratch::new("bounded-read-portable");
2134        let path = scratch.store();
2135        drop(FileStore::open(&path).expect("open"));
2136        let file = std::fs::OpenOptions::new()
2137            .write(true)
2138            .open(&path)
2139            .expect("open planted store");
2140        file.set_len(MAX_FILE_BYTES as u64 + 1)
2141            .expect("make a sparse oversized store");
2142        drop(file);
2143
2144        let error = FileStore::open(&path).expect_err("oversized store must be refused");
2145        let message = error.to_string();
2146        assert!(message.contains(&MAX_FILE_BYTES.to_string()), "{message}");
2147        assert!(message.contains(&path.display().to_string()), "{message}");
2148
2149        let source = include_str!("file.rs");
2150        let start = source
2151            .find("fn read_bounded")
2152            .expect("bounded reader exists");
2153        let body = &source[start
2154            ..source[start..]
2155                .find("\nfn parse")
2156                .map(|end| start + end)
2157                .expect("bounded reader ends")];
2158        assert!(
2159            body.contains(".metadata()"),
2160            "metadata check left the handle"
2161        );
2162        assert!(
2163            body.contains("file.take(MAX_FILE_BYTES as u64 + 1)"),
2164            "growth-race max+1 read left the same handle"
2165        );
2166    }
2167
2168    #[test]
2169    fn logical_v1_reads_bound_entries_and_individual_values() {
2170        let entries_scratch = Scratch::new("bounded-entry-count");
2171        let entries_path = entries_scratch.store();
2172        drop(FileStore::open(&entries_path).expect("open"));
2173        let mut contents = String::from(HEADER);
2174        contents.push('\n');
2175        for index in 0..=MAX_ENTRIES {
2176            contents.push_str(&format!("tenants/t{index}/com.acme.api/token 41\n"));
2177        }
2178        assert!(
2179            contents.len() < MAX_FILE_BYTES,
2180            "entry fixture must isolate its bound"
2181        );
2182        std::fs::write(&entries_path, contents).expect("plant too many entries");
2183        let error = FileStore::open(&entries_path).expect_err("entry count must be bounded");
2184        let message = error.to_string();
2185        assert!(message.contains(&MAX_ENTRIES.to_string()), "{message}");
2186        assert!(!message.contains("com.acme.api"), "{message}");
2187
2188        let value_scratch = Scratch::new("bounded-value-read");
2189        let value_path = value_scratch.store();
2190        drop(FileStore::open(&value_path).expect("open"));
2191        let contents = format!(
2192            "{HEADER}\ntenants/tenant-a/com.acme.api/token {}\n",
2193            "41".repeat(MAX_VALUE_BYTES + 1)
2194        );
2195        assert!(
2196            contents.len() < MAX_FILE_BYTES,
2197            "value fixture must isolate its bound"
2198        );
2199        std::fs::write(&value_path, contents).expect("plant oversized encoded value");
2200        let error = FileStore::open(&value_path).expect_err("individual value must be bounded");
2201        let message = error.to_string();
2202        assert!(message.contains(&MAX_VALUE_BYTES.to_string()), "{message}");
2203        assert!(!message.contains(&"41".repeat(64)), "{message}");
2204    }
2205}
2206
2207#[cfg(test)]
2208mod transaction_crash_tests {
2209    use super::*;
2210    use crate::{
2211        CredentialScope, PreparedSecretError, PreparedSecretStore, SecretProposalDigest,
2212        SecretTransactionGeneration, SecretTransactionId, SecretTransactionState,
2213    };
2214    use std::process::{Command, Stdio};
2215    use std::sync::atomic::{AtomicU64, Ordering};
2216    use std::time::{Duration, Instant};
2217
2218    const OLD: &str = "SENTINEL-NOT-A-REAL-SECRET-crash-old";
2219    const NEW: &str = "SENTINEL-NOT-A-REAL-SECRET-crash-new";
2220
2221    struct Scratch(PathBuf);
2222
2223    impl Scratch {
2224        fn new(label: &str) -> Self {
2225            static NEXT: AtomicU64 = AtomicU64::new(0);
2226            let path = std::env::temp_dir().join(format!(
2227                "connector-secrets-transaction-{label}-{}-{}",
2228                std::process::id(),
2229                NEXT.fetch_add(1, Ordering::Relaxed)
2230            ));
2231            let _ = std::fs::remove_dir_all(&path);
2232            Self(path)
2233        }
2234
2235        fn store(&self) -> PathBuf {
2236            self.0.join("store").join("credentials")
2237        }
2238    }
2239
2240    impl Drop for Scratch {
2241        fn drop(&mut self) {
2242            let _ = std::fs::remove_dir_all(&self.0);
2243        }
2244    }
2245
2246    fn generation() -> SecretTransactionGeneration {
2247        SecretTransactionGeneration::from_protocol_bytes([0, 0, 0, 0, 0, 0, 0, 1])
2248            .expect("non-zero")
2249    }
2250
2251    fn id() -> SecretTransactionId {
2252        SecretTransactionId::new(generation(), [0x51; 24])
2253    }
2254
2255    fn digest() -> SecretProposalDigest {
2256        SecretProposalDigest::from_protocol_bytes([0x52; 32])
2257    }
2258
2259    fn reference() -> CredentialRef {
2260        CredentialRef::new("tenant-a", "com.acme.api", "default", "token").expect("valid")
2261    }
2262
2263    fn batch() -> SecretBatch {
2264        let reference = reference();
2265        let mut batch = SecretBatch::new(
2266            CredentialScope::new(reference.tenant(), reference.authority()).expect("scope"),
2267        );
2268        batch.put(reference, Secret::new(NEW)).expect("mutation");
2269        batch
2270    }
2271
2272    fn released_v0_19_1_accepts(contents: &str) -> bool {
2273        // This is the released v0.19.1 parser's version gate: any version line other than v1 is a
2274        // hard refusal. Keep the fixture small so it proves the upgrade boundary, not a second
2275        // implementation of the legacy store.
2276        !contents.lines().any(|line| {
2277            line.strip_prefix(VERSION_PREFIX)
2278                .is_some_and(|version| version != VERSION)
2279        })
2280    }
2281
2282    fn run(operation: &str, store: &Path) {
2283        let runtime = tokio::runtime::Builder::new_current_thread()
2284            .build()
2285            .expect("runtime");
2286        runtime.block_on(async {
2287            let store = FileStore::open(store).expect("child open");
2288            match operation {
2289                "prepare" => {
2290                    let _ = store.prepare(id(), digest(), &batch()).await;
2291                }
2292                "commit" => {
2293                    let _ = store.commit(id()).await;
2294                }
2295                "abort" => {
2296                    let _ = store.abort(id()).await;
2297                }
2298                "reclaim" => {
2299                    let _ = store.reclaim(generation()).await;
2300                }
2301                _ => panic!("unknown child operation"),
2302            }
2303        });
2304        panic!("the configured crash boundary was not reached");
2305    }
2306
2307    #[test]
2308    fn prepared_crash_child() {
2309        let Ok(operation) = std::env::var("CONNECTOR_SECRETS_CRASH_CHILD") else {
2310            return;
2311        };
2312        let store = PathBuf::from(std::env::var_os("CONNECTOR_SECRETS_CRASH_STORE").expect("path"));
2313        run(&operation, &store);
2314    }
2315
2316    #[test]
2317    fn lease_child() {
2318        let Ok(mode) = std::env::var("CONNECTOR_SECRETS_LEASE_CHILD") else {
2319            return;
2320        };
2321        let store = PathBuf::from(std::env::var_os("CONNECTOR_SECRETS_LEASE_STORE").expect("path"));
2322        match mode.as_str() {
2323            "hold" => {
2324                let _store = FileStore::open(&store).expect("holder open");
2325                let ready = std::env::var_os("CONNECTOR_SECRETS_LEASE_READY").expect("ready path");
2326                std::fs::write(ready, b"ready").expect("signal ready");
2327                std::thread::sleep(Duration::from_secs(30));
2328            }
2329            "probe" => match FileStore::open(&store) {
2330                Ok(_) => std::process::exit(0),
2331                Err(StoreError::Conflict { .. }) => std::process::exit(42),
2332                Err(_) => std::process::exit(43),
2333            },
2334            _ => panic!("unknown lease child mode"),
2335        }
2336    }
2337
2338    #[test]
2339    fn legacy_writer_child() {
2340        if std::env::var_os("CONNECTOR_SECRETS_LEGACY_CHILD").is_none() {
2341            return;
2342        }
2343        let store = PathBuf::from(
2344            std::env::var_os("CONNECTOR_SECRETS_LEGACY_STORE").expect("legacy store path"),
2345        );
2346        let ready = PathBuf::from(
2347            std::env::var_os("CONNECTOR_SECRETS_LEGACY_READY").expect("legacy ready path"),
2348        );
2349        let release = PathBuf::from(
2350            std::env::var_os("CONNECTOR_SECRETS_LEGACY_RELEASE").expect("legacy release path"),
2351        );
2352        let opened = std::fs::read_to_string(&store).expect("legacy open");
2353        assert!(released_v0_19_1_accepts(&opened), "fixture must open v1");
2354        std::fs::write(&ready, b"ready").expect("signal legacy open");
2355        let deadline = Instant::now() + Duration::from_secs(10);
2356        while !release.exists() && Instant::now() < deadline {
2357            std::thread::sleep(Duration::from_millis(10));
2358        }
2359        assert!(release.exists(), "legacy writer was not released");
2360        // Released 0.19.1 held this parsed v1 image in memory and rewrote it wholesale for every
2361        // point mutation. Reinstalling the bytes it opened models the unsafe stale-writer edge
2362        // without teaching this fixture a second credential-address encoder.
2363        std::fs::write(&store, opened).expect("legacy v1 rewrite");
2364    }
2365
2366    #[test]
2367    fn every_durable_transaction_boundary_recovers_one_complete_state() {
2368        let cases: &[(&str, &[&str])] = &[
2369            (
2370                "prepare",
2371                &[
2372                    "stage:create",
2373                    "stage:write",
2374                    "stage:flush",
2375                    "stage:replace",
2376                    "stage:directory-sync",
2377                    "live:create",
2378                    "live:write",
2379                    "live:flush",
2380                    "live:replace",
2381                    "live:directory-sync",
2382                ],
2383            ),
2384            (
2385                "commit",
2386                &[
2387                    "live:create",
2388                    "live:write",
2389                    "live:flush",
2390                    "live:replace",
2391                    "live:directory-sync",
2392                    "stage:cleanup",
2393                ],
2394            ),
2395            (
2396                "abort",
2397                &[
2398                    "live:create",
2399                    "live:write",
2400                    "live:flush",
2401                    "live:replace",
2402                    "live:directory-sync",
2403                    "stage:cleanup",
2404                ],
2405            ),
2406            (
2407                "reclaim",
2408                &[
2409                    "live:create",
2410                    "live:write",
2411                    "live:flush",
2412                    "live:replace",
2413                    "live:directory-sync",
2414                ],
2415            ),
2416        ];
2417
2418        for (operation, boundaries) in cases {
2419            for boundary in *boundaries {
2420                let scratch = Scratch::new(&format!(
2421                    "crash-{}-{}",
2422                    operation,
2423                    boundary.replace(':', "-")
2424                ));
2425                let path = scratch.store();
2426                let runtime = tokio::runtime::Builder::new_current_thread()
2427                    .build()
2428                    .expect("runtime");
2429                runtime.block_on(async {
2430                    let store = FileStore::open(&path).expect("setup open");
2431                    store
2432                        .put(&reference(), &Secret::new(OLD))
2433                        .await
2434                        .expect("seed");
2435                    if matches!(*operation, "commit" | "abort") {
2436                        store
2437                            .prepare(id(), digest(), &batch())
2438                            .await
2439                            .expect("prepare");
2440                    } else if *operation == "reclaim" {
2441                        store.abort(id()).await.expect("terminal tombstone");
2442                    }
2443                });
2444
2445                let status = Command::new(std::env::current_exe().expect("test executable"))
2446                    .arg("--exact")
2447                    .arg("file::transaction_crash_tests::prepared_crash_child")
2448                    .arg("--nocapture")
2449                    .env("CONNECTOR_SECRETS_CRASH_CHILD", operation)
2450                    .env("CONNECTOR_SECRETS_CRASH_STORE", &path)
2451                    .env("CONNECTOR_SECRETS_CRASH_AT", boundary)
2452                    .stdin(Stdio::null())
2453                    .stdout(Stdio::null())
2454                    .stderr(Stdio::null())
2455                    .status()
2456                    .expect("spawn crash child");
2457                assert!(!status.success(), "{operation} did not crash at {boundary}");
2458
2459                runtime.block_on(async {
2460                    let recovered = FileStore::open(&path).unwrap_or_else(|error| {
2461                        panic!("{operation}/{boundary} did not recover: {error}")
2462                    });
2463                    let transaction = recovered.state(id()).await;
2464                    let value = recovered
2465                        .get(&reference())
2466                        .await
2467                        .expect("one complete credential image")
2468                        .expose_secret()
2469                        .to_owned();
2470                    match *operation {
2471                        "prepare" => match transaction {
2472                            Ok(SecretTransactionState::Absent) => assert_eq!(value, OLD),
2473                            Ok(SecretTransactionState::Prepared) => {
2474                                assert_eq!(value, OLD);
2475                                recovered
2476                                    .commit(id())
2477                                    .await
2478                                    .expect("candidate remains committable");
2479                                assert_eq!(
2480                                    recovered
2481                                        .get(&reference())
2482                                        .await
2483                                        .expect("new")
2484                                        .expose_secret(),
2485                                    NEW
2486                                );
2487                            }
2488                            other => panic!("unexpected prepare recovery at {boundary}: {other:?}"),
2489                        },
2490                        "commit" => match transaction {
2491                            Ok(SecretTransactionState::Prepared) => assert_eq!(value, OLD),
2492                            Ok(SecretTransactionState::Committed) => assert_eq!(value, NEW),
2493                            other => panic!("unexpected commit recovery at {boundary}: {other:?}"),
2494                        },
2495                        "abort" => match transaction {
2496                            Ok(SecretTransactionState::Prepared)
2497                            | Ok(SecretTransactionState::Absent) => assert_eq!(value, OLD),
2498                            other => panic!("unexpected abort recovery at {boundary}: {other:?}"),
2499                        },
2500                        "reclaim" => match transaction {
2501                            Ok(SecretTransactionState::Absent)
2502                            | Err(PreparedSecretError::Retired) => assert_eq!(value, OLD),
2503                            other => panic!("unexpected reclaim recovery at {boundary}: {other:?}"),
2504                        },
2505                        _ => unreachable!(),
2506                    }
2507                });
2508            }
2509        }
2510    }
2511
2512    #[test]
2513    fn two_children_prove_lease_refusal_and_abrupt_release() {
2514        let scratch = Scratch::new("lease-processes");
2515        let path = scratch.store();
2516        drop(FileStore::open(&path).expect("initialize"));
2517        let ready = scratch.0.join("holder.ready");
2518        let executable = std::env::current_exe().expect("test executable");
2519        let mut holder = Command::new(&executable)
2520            .arg("--exact")
2521            .arg("file::transaction_crash_tests::lease_child")
2522            .arg("--nocapture")
2523            .env("CONNECTOR_SECRETS_LEASE_CHILD", "hold")
2524            .env("CONNECTOR_SECRETS_LEASE_STORE", &path)
2525            .env("CONNECTOR_SECRETS_LEASE_READY", &ready)
2526            .stdin(Stdio::null())
2527            .stdout(Stdio::null())
2528            .stderr(Stdio::null())
2529            .spawn()
2530            .expect("spawn holder");
2531        let deadline = Instant::now() + Duration::from_secs(10);
2532        while !ready.exists() && Instant::now() < deadline {
2533            std::thread::sleep(Duration::from_millis(10));
2534        }
2535        assert!(ready.exists(), "holder did not acquire the lease");
2536
2537        let probe = || {
2538            Command::new(&executable)
2539                .arg("--exact")
2540                .arg("file::transaction_crash_tests::lease_child")
2541                .arg("--nocapture")
2542                .env("CONNECTOR_SECRETS_LEASE_CHILD", "probe")
2543                .env("CONNECTOR_SECRETS_LEASE_STORE", &path)
2544                .stdin(Stdio::null())
2545                .stdout(Stdio::null())
2546                .stderr(Stdio::null())
2547                .status()
2548                .expect("spawn probe")
2549        };
2550        assert_eq!(probe().code(), Some(42), "contending child must refuse");
2551        holder.kill().expect("abruptly terminate holder");
2552        holder.wait().expect("reap holder");
2553        assert!(
2554            probe().success(),
2555            "kernel lease must release after process exit"
2556        );
2557    }
2558
2559    #[test]
2560    fn native_upgrade_fixture_proves_legacy_quiescence_and_v2_refusal() {
2561        let scratch = Scratch::new("legacy-upgrade");
2562        let path = scratch.store();
2563        let runtime = tokio::runtime::Builder::new_current_thread()
2564            .build()
2565            .expect("runtime");
2566        runtime.block_on(async {
2567            let store = FileStore::open(&path).expect("initialize v1");
2568            store
2569                .put(&reference(), &Secret::new(OLD))
2570                .await
2571                .expect("seed legacy value");
2572        });
2573
2574        let ready = scratch.0.join("legacy.ready");
2575        let release = scratch.0.join("legacy.release");
2576        let mut legacy = Command::new(std::env::current_exe().expect("test executable"))
2577            .arg("--exact")
2578            .arg("file::transaction_crash_tests::legacy_writer_child")
2579            .arg("--nocapture")
2580            .env("CONNECTOR_SECRETS_LEGACY_CHILD", "1")
2581            .env("CONNECTOR_SECRETS_LEGACY_STORE", &path)
2582            .env("CONNECTOR_SECRETS_LEGACY_READY", &ready)
2583            .env("CONNECTOR_SECRETS_LEGACY_RELEASE", &release)
2584            .stdin(Stdio::null())
2585            .stdout(Stdio::null())
2586            .stderr(Stdio::null())
2587            .spawn()
2588            .expect("spawn already-open legacy writer");
2589        let deadline = Instant::now() + Duration::from_secs(10);
2590        while !ready.exists() && Instant::now() < deadline {
2591            std::thread::sleep(Duration::from_millis(10));
2592        }
2593        assert!(ready.exists(), "legacy writer did not open v1");
2594
2595        runtime.block_on(async {
2596            let current =
2597                FileStore::open(&path).expect("0.20 opener ignores no active legacy lock");
2598            assert_eq!(
2599                current.abort(id()).await,
2600                Ok(SecretTransactionState::Absent)
2601            );
2602            let v2 = std::fs::read_to_string(&path).expect("read migrated v2");
2603            assert!(
2604                !released_v0_19_1_accepts(&v2),
2605                "a fresh released v0.19.1 parser must refuse v2"
2606            );
2607
2608            std::fs::write(&release, b"rewrite").expect("release legacy writer");
2609            assert!(legacy.wait().expect("wait for legacy writer").success());
2610            assert_eq!(
2611                current.state(id()).await,
2612                Ok(SecretTransactionState::Absent),
2613                "an already-open legacy writer can erase the acknowledged tombstone"
2614            );
2615        });
2616        assert!(released_v0_19_1_accepts(
2617            &std::fs::read_to_string(&path).expect("legacy v1 survived")
2618        ));
2619    }
2620}