feat(client): add a file system backend for the certificate chain cache

[jpraynaud]

Content

This PR includes the file system backend of the certificate chain cache of mithril-client, so that the certificates verified by one CLI run are reused by the next ones:

• Added FileCertificateVerifierCache, available with the fs and unstable features, storing one JSON file per committed certificate with its expiration date under committed/<space>/, where the space is the fingerprint of the genesis verification key that validated it.
• Staged the certificates of a chain validation in progress under staged/<certificate chain validation id>/, with the creation date of the batch in a created_at file.
• Committed a validation by writing each certificate with its expiration date to a separate file, then moving it to the committed directory with an atomic rename, so that no cross process lock is needed and a failed move leaves the staged certificate intact.
• Aligned the expiration semantics on the memory backend: the expiration date of a certificate is set at commit, and a staged batch expires after the staging expiration delay from its creation.
• Swept the expired committed certificates and the expired staged batches when a new batch is staged and at commit, as a best effort that never fails a stage or a commit and only touches batch directories and certificate files.
• Invalidated a committed file that cannot be parsed by deleting it and reporting an error, which the verifier already logs before falling back to the aggregator.
• Restricted the certificate hashes and validation ids used as file names to alphanumeric characters, - and _, since the previous hash of a downloaded certificate could otherwise make the client read and delete files outside the cache.
• Added the fs feature of tokio to the fs feature of the crate.

Pre-submit checklist

• Branch
  • Tests are provided (if possible)
  • Crates versions are updated (if relevant)
  • CHANGELOG file is updated (if relevant)
  • Commit sequence broadly makes sense
  • Key commits have useful messages
• PR
  • All check jobs of the CI have succeeded
  • Self-reviewed the diff
  • Useful pull request description
  • Reviewer requested
• Documentation
  • No new TODOs introduced

Comments

• The backend is gated on the fs feature rather than on non-WASM targets.
• The files are not synced to disk: a committed file truncated by a power loss is detected, deleted and fetched again from the aggregator.
• A staged batch without a readable created_at file (interrupted creation) expires from the last modification of its directory.

Issue(s)

Closes #3522

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved cache publication and integration issues can compromise correctness and prevent the advertised CLI reuse behavior.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Prevent partial batch publication from being trusted · New

What changed in this PR

Adds a filesystem-backed certificate verification cache for reuse across client runs.

Changes:

• Implements staged and committed certificate storage with expiration and cleanup.
• Exposes the backend behind fs and unstable features.
• Adds filename validation, Tokio filesystem support, tests, and changelog documentation.

File	Summary
mithril-client/​src/​certificate_client/​verify_cache/​mod.rs	Registers and exports the filesystem cache backend.
mithril-client/​src/​certificate_client/​verify_cache/​file_cache.rs	Implements the filesystem cache; unresolved concerns remain around partial commits and publishing incomplete files.
mithril-client/​src/​certificate_client/​mod.rs	Exports the cache, but the CLI does not yet configure or use it.
mithril-client/​Cargo.toml	Adds filesystem support; the fs feature documentation should also mention certificate caching.
CHANGELOG.md	Documents the new backend.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Test Results

     5 files  ±  0     221 suites  ±0   47m 36s ⏱️ - 16m 38s
 3 807 tests + 51   3 807 ✅ + 51  0 💤 ±0  0 ❌ ±0 
12 288 runs  +202  12 288 ✅ +202  0 💤 ±0  0 ❌ ±0 

Results for commit faf3736. ± Comparison against base commit bc0bb01.

♻️ This comment has been updated with latest results.

[turmelclem]

LGTM 👍

[damrobi]

LGTM 👍