[freshtonic]

Summary

This PR builds the design in ADR 0007 (#491): a pooled source shares the authority to mint keys, never a key. One backend call fetches an authority key, which is cached in memory. Each value then gets its own data key, which is derived locally from the authority key, a fresh 16-byte salt and the value's binding. A batch costs one backend call per cache refresh, and every value still has its own key and its own binding. #508 removed the clone-one-key pooled sources, and this replaces them.

There are two commits. Each one passes clippy with -D warnings on its own.

1. refactor(kms)!: remove KeyIsolation. With Pooled gone, the enum had one value. So the enum, KeyProvider::ISOLATION, BatchGenerateDataKey::ISOLATION and every assertion are removed. There are no readers in this workspace, in cipherstash/stack or in cipherstash-suite. ADR 0003 and the dated design survey still name it, because they are historical records.
2. feat(kms): add AuthorityKeySource.

API

• The new feature authority-keys enables caching, vitaminc-random, hmac and sha2, with zeroize on both. It adds no new crate. It is off by default. The default, traits-only and wasm32 builds do not change.
• No feature gate:
  • DerivesFromAuthorityKey, the capability marker trait, with cache_policy() and purge_expired().
  • AuthorityKeyCachePolicy { max_entries, ttl }. It has no Default, because the TTL is a security control.
• Behind the feature:
  • AuthorityKeyVersion.
  • AuthorityKeys::new(current, versions). It refuses a duplicate version, and a current version that the map does not hold.
  • AuthorityKeySource<T>:
    • new and provision. provision mints the wrapped authority key under the correct binding, so callers never build that binding themselves.
    • It implements KeyProvider<N>, DerivesFromAuthorityKey and IndexKeyProvider (the last delegates to the inner provider).
    • CUSTODY = BackendHeld, because a KeyId carries no key material.
    • RECONSTRUCTION = T::RECONSTRUCTION.
  • AuthorityKeyError.
• The store is a plain struct, not a trait. The deployment persists version → wrapped KeyId, the same as the FixedIndexKeySource id. To rotate, the deployment adds a version, makes it current, and builds the source again. Old versions stay for retrieval.
• When many requests miss the cache at the same time, they share one fetch (moka try_get_with).

Wire format (new ADR 0008)

• Authority key: 32 bytes. The inner provider mints and unwraps it under the binding "vitaminc-kms/authority-key/v1" || u32be(version). The binding names the version, so the backend refuses a wrapped key that is stored under the wrong version.
• Data key: HKDF-SHA256 with salt = 16 bytes from SafeRand and IKM = the authority key. HKDF is built here on hmac, not on the hkdf crate. That crate drops the PRK and each expand block without wiping them, and for a 32-byte key the one expand block is the data key. Here each value is written straight into Protected memory, which zeroizes on drop. The RFC 5869 SHA-256 vectors (cases 1 to 3) check the implementation.
  • info = "vitaminc-kms/authority-key/v1/data-key" || u32be(version) || u16be(N) || u64be(len(binding)) || binding.
  • A compile-time check limits N to 1..=8160.
• KeyId: 0x01 || u32be(version) || salt, exactly 21 bytes. A malformed id or an unknown version gives a typed error for the whole batch before any backend call.
• Known-answer vectors are in the ADR and in the tests. They were computed with an independent Python HKDF.

Docs

• CONTEXT.md gets the authority-key term and the three key tiers.
• ADR 0007 is edited in place to answer its open questions.
• The CachingKeyProvider docs now restate the auditing and in-memory stance. Per-value retrieval is no longer per-value authorization. The cached authority key is Protected and is wiped on eviction and expiry.
• The CRAP feature lists in crap.yml and mise.toml get vitaminc-kms/authority-keys.

Closes CIP-5062.

For the reviewer

• Wiping: the PRK and every expand block are Protected, and the HMAC states wipe on drop. Only SHA-256's own working memory is out of reach, the same as for every HMAC in the workspace. AuthorityKeyError::DataKeyLength is removed: the compile-time check on N means derivation cannot fail.
• Retrieval cannot detect a wrong binding. It derives a key that opens nothing, and the consumer's AEAD reports the failure. The Binding docs, CONTEXT.md and ADR 0007 say this.
• "Pluggable cache strategies" is only the trait seam and the policy struct. There is no strategy trait.
• The LocalStack end-to-end tests copy the client builder rather than share it.
• ADR 0008's note on AWS's Hierarchical keyring KDF was checked against AWS's specification: counter-mode KDF with HMAC-SHA256 (NIST SP 800-108).

Test plan

• 23 new tests, including the RFC 5869 SHA-256 vectors. They cover:
  • round trip, and distinct keys in a 50-value batch
  • a wrong binding derives a different key
  • 100 values cost 1 inner retrieve, and 16 concurrent misses cost 1 fetch
  • an empty batch makes zero inner calls (this was CIP-5033's requirement)
  • TTL refetch, purge_expired, rotation, an unknown version and five malformed ids
  • backend refusal, and the wrong number of keys from the inner provider
  • three known-answer tests, and two end-to-end tests against LocalStack
• cargo test -p vitaminc-kms --all-features --locked: 309 tests and 8 doctests pass. With default features: 58 tests and 4 doctests.
• The test target builds with each of vault, azure, gcp and authority-keys on its own.
• clippy with -D warnings on each commit, fmt --check, the workspace check with all features, wasm32-wasip1, and cargo doc with -D warnings. No ADR number is used twice, and every commit is signed.

🤖 Generated with Claude Code

[github-actions]

✅ No CRAP threshold violations

1645 function(s) analyzed · threshold 30

[github-actions]

🧬 Mutation testing (cargo-mutants, --in-diff)

caught	missed	unviable	timeout
37	0	47	0

✅ Every mutant in the changed lines was caught by a test.