[Task](crypto | masterkey| SSS) Implement Database "Peek" and Shard Aggregation Logic

[nnicora]

This task implements the core orchestration logic for the "unseal" event. When the OpenKCM service initializes, it must query the database to "peek" at available encrypted shards and select the minimum subset ($M$) required to reconstruct the MasterKey.

The aggregator acts as a traffic controller: it fetches metadata from the database, selects the healthiest or most accessible shards, parallelizes decryption requests to various KMS/HSM providers, and validates the integrity of the resulting plaintext shards before handed them to the GF(256) Math Engine.

Goals

• Implement a "Best-Available" selection strategy to retrieve exactly $M$ shards.
• Orchestrate parallel decryption calls to diverse providers (AWS, GCP, Vault, HSM).
• Implement a "Retry-with-Alternative" logic: if a specific provider is down, fetch a different shard from the database to meet the threshold.
• Aggregate decrypted bytes and verify shard indices ($x$ values) are unique.

Acceptance Criteria

• Database "Peek" Logic: - Implement a query that retrieves shard metadata (ProviderType, KeyID, EncryptedBlob) for a specific MasterKey version.
  • If more than $M$ shards are available, the logic should prioritize providers based on a configurable priority list (e.g., local HSM before cloud KMS).
• Parallel Decryption Orchestration:
  • Use a worker pool or goroutines to trigger decryption calls to the respective clients simultaneously.
  • Implement a global context.Context timeout for the entire aggregation phase.
• Fault Tolerance & Fallback:
  • If a decryption provider returns an error, the aggregator must automatically attempt to fetch an "over-threshold" shard ($M+1$) if available in the database.
• Aggregation & Validation:
  • Confirm that exactly $M$ distinct indices are gathered.
  • Validate that all decrypted shard lengths are consistent (e.g., 32 bytes for AES-256).
• Security & Memory Safety:
  • Decrypted shards must move directly into MasterKeyHolder secure buffers.
  • Zeroization: The aggregation buffer must be explicitly wiped from memory (0x00) immediately after the Math Engine produces the final key.
• Unit Tests:
  • Simulate a successful "3-of-5" unseal.
  • Simulate a "Provider Outage" where the aggregator successfully falls back to a 4th shard to meet the threshold.

Implementation Details

The flow follows a Gather -> Decrypt -> Verify -> Reduce pattern. To minimize the attack surface, the aggregator should never log the plaintext content of any shard, even in "Debug" mode.